/**
 * Manifest ambient type declarations.
 * https://manifestx.dev
 *
 * This file gives editors (VS Code, Cursor, JetBrains) and AI coding assistants
 * type information for Manifest's magic globals and data-source state. It is
 * intended to live in the project root and is regenerated by `npx mnfst-types`
 * to add project-specific augmentations to ManifestSources from manifest.json.
 *
 * Hand-edits below the AUGMENTATION marker will be overwritten on regeneration.
 */

// ---------------------------------------------------------------------------
// Data-source state and operators (attached to every $x.<source>)
// ---------------------------------------------------------------------------

/** Appwrite-style query expression returned by helper builders. */
export type ManifestQueryExpr = string;

/** Appwrite-style query helpers used with `$query([...])`. */
export interface ManifestQuery {
    equal(field: string, value: unknown): ManifestQueryExpr;
    notEqual(field: string, value: unknown): ManifestQueryExpr;
    lessThan(field: string, value: number | string): ManifestQueryExpr;
    lessThanEqual(field: string, value: number | string): ManifestQueryExpr;
    greaterThan(field: string, value: number | string): ManifestQueryExpr;
    greaterThanEqual(field: string, value: number | string): ManifestQueryExpr;
    between(field: string, start: number | string, end: number | string): ManifestQueryExpr;
    contains(field: string, value: string | string[]): ManifestQueryExpr;
    startsWith(field: string, value: string): ManifestQueryExpr;
    endsWith(field: string, value: string): ManifestQueryExpr;
    search(field: string, value: string): ManifestQueryExpr;
    isNull(field: string): ManifestQueryExpr;
    isNotNull(field: string): ManifestQueryExpr;
    select(fields: string[]): ManifestQueryExpr;
    orderAsc(field: string): ManifestQueryExpr;
    orderDesc(field: string): ManifestQueryExpr;
    limit(value: number): ManifestQueryExpr;
    offset(value: number): ManifestQueryExpr;
    cursorAfter(id: string): ManifestQueryExpr;
    cursorBefore(id: string): ManifestQueryExpr;
}

/** State flags exposed on every data source (array or object). */
export interface ManifestSourceState {
    /** True while the source is fetching for the first time or after a mutation. */
    readonly $loading: boolean;
    /** Last error from a load or mutation, or null. */
    readonly $error: Error | string | null;
    /** True once initial load has completed (success or failure). */
    readonly $ready: boolean;
}

/** Operators available on array-shaped sources (CSV tabular, JSON arrays, Appwrite tables). */
export interface ManifestArrayOps<T> {
    /** Substring match across the given fields. Returns matching items. */
    $search(term: string, ...fields: (keyof T & string)[]): T[];
    /**
     * Local sources: filter by an array of `Manifest.query.*` expressions and array methods.
     * Appwrite sources: server-side query, returns a Promise.
     */
    $query(expressions: ManifestQueryExpr[]): T[] | Promise<T[]>;
    /** Look up a single row whose `id` matches the current route param, if any. */
    $route(path?: string): T | undefined;
}

/** Mutations available on Appwrite-table sources. */
export interface ManifestAppwriteTableOps<T> {
    $create(values: Partial<T>): Promise<T>;
    $update(id: string, values: Partial<T>): Promise<T>;
    $delete(id: string): Promise<void>;
    $duplicate(id: string, overrides?: Partial<T>): Promise<T>;
}

/** Operations available on Appwrite-bucket (storage) sources. */
export interface ManifestAppwriteBucketOps {
    $url(fileId: string): string;
    $preview(fileId: string, opts?: Record<string, unknown>): string;
    $download(fileId: string): string;
    $openUrl(fileId: string): void;
    $openPreview(fileId: string): void;
    $openDownload(fileId: string): void;
    $upload(file: File | Blob, opts?: Record<string, unknown>): Promise<{ $id: string }>;
    $remove(fileId: string): Promise<void>;
    $filesFor(parentId: string, fieldName?: string): unknown[];
    $unlinkFrom(parentId: string, fileId: string): Promise<void>;
    $removeFrom(parentId: string, fileId: string): Promise<void>;
}

/**
 * The shape returned by `$x.<source>` for an array-of-rows source.
 * Behaves as a regular `T[]` (supports `map`, `filter`, `find`, etc.) plus
 * Manifest operators and state flags.
 */
export type ManifestArraySource<T> =
    & ReadonlyArray<T>
    & ManifestSourceState
    & ManifestArrayOps<T>
    & Partial<ManifestAppwriteTableOps<T>>;

/** The shape returned by `$x.<source>` for an object-shaped source (CSV key-value, JSON object, YAML map). */
export type ManifestObjectSource<T> = T & ManifestSourceState;

/** The shape returned by `$x.<source>` for an Appwrite storage bucket. */
export type ManifestBucketSource = ManifestSourceState & ManifestAppwriteBucketOps;

// ---------------------------------------------------------------------------
// Magic globals registered by Manifest plugins
// ---------------------------------------------------------------------------

/**
 * Project-specific data sources, keyed by the names declared in `manifest.json`'s
 * `data` property. Augmented by `npx mnfst-types` from manifest.json + sample
 * data (declarations appended below the AUGMENTATION marker).
 */
export interface ManifestSources {
    [sourceName: string]: ManifestArraySource<any> | ManifestObjectSource<any> | ManifestBucketSource;
}

/** `$auth` from the Appwrite auth plugin. Loose by design — auth API is broad. */
export interface ManifestAuth {
    readonly current: { $id: string; email?: string; name?: string;[k: string]: unknown } | null;
    readonly isAuthenticated: boolean;
    readonly isLoading: boolean;
    readonly currentTeam: { $id: string; name: string;[k: string]: unknown } | null;
    readonly teams: Array<{ $id: string; name: string;[k: string]: unknown }>;
    login(email: string, password?: string): Promise<unknown>;
    loginWithMagic(email: string): Promise<unknown>;
    loginWithOAuth(provider: string, opts?: Record<string, unknown>): Promise<unknown>;
    loginAsGuest(): Promise<unknown>;
    logout(): Promise<unknown>;
    [extra: string]: unknown;
}

/** `$locale` from the localization plugin. */
export interface ManifestLocale {
    readonly current: string;
    readonly available: string[];
    set(locale: string): void;
}

/** One toast flavor: callable, with `.dismiss` (adds a close button) and `.fixed` (sticky) variants. */
export interface ManifestToastVariant {
    (message: string, opts?: Record<string, unknown>): void;
    dismiss(message: string, opts?: Record<string, unknown>): void;
    fixed(message: string, opts?: Record<string, unknown>): void;
}

/** `$toast` from the toasts plugin. Typed variants: `$toast.brand(...)`, `$toast.positive.dismiss(...)`. */
export interface ManifestToast extends ManifestToastVariant {
    brand: ManifestToastVariant;
    accent: ManifestToastVariant;
    positive: ManifestToastVariant;
    negative: ManifestToastVariant;
}

/** `$color` from the color plugin — the current light/dark/system color mode. */
export interface ManifestColor {
    current: 'light' | 'dark' | 'system' | string;
}

/** `$colorpicker` from the colorpicker plugin. Loose by design. */
export interface ManifestColorpicker {
    (id?: string): Record<string, unknown>;
    [extra: string]: unknown;
}

/** One URL query parameter handle from `$url.<name>` (reactive). */
export interface ManifestUrlParam {
    /** Current value (get/set; empty string when absent). */
    value: string;
    /** First value when the param repeats. */
    readonly first: string;
    /** All values for a repeating param. */
    readonly all: string[];
    set(value: string): void;
    add(value: string): void;
    remove(value?: string): void;
    clear(): void;
}

/** `$url` from the url-parameters plugin: `$url.tab.value`, `$url.tag.add('x')`, ... */
export interface ManifestUrl {
    [param: string]: ManifestUrlParam;
}

/** `$route` magic — the current route path (e.g. '/docs/elements'). */
export type ManifestRoute = string;

/**
 * `$modify('attr')` — exposed in component HTML. Returns the value of an
 * attribute set on the parent component instance (Manifest's prop mechanism).
 */
export type ManifestModify = (attr: string) => string | undefined;

/** `$try(fn)` — run a callback and swallow any thrown error, returning undefined on failure. */
export type ManifestTry = <T>(fn: () => T) => T | undefined;

/** `$pay` from the payments plugin: callable to start checkout, plus portal/state helpers. */
export interface ManifestPay {
    (ref: string, payload?: Record<string, unknown>): Promise<unknown>;
    portal(ref?: string, payload?: Record<string, unknown>): Promise<unknown>;
    refresh(): Promise<unknown>;
    register(name: string, adapter: unknown): void;
    readonly state: Record<string, unknown> | undefined;
    readonly loading: boolean | undefined;
    [extra: string]: unknown;
}

/** A conversation handle returned by `$chat.open(...)`. Loose by design. */
export interface ManifestChatHandle {
    readonly messages: unknown[];
    readonly participants: unknown[];
    readonly typing: unknown[];
    readonly me: unknown;
    [extra: string]: unknown;
}

/** `$chat` from the chat plugin — adapter-based conversation projection. */
export interface ManifestChat {
    open(conversationId: string, opts?: Record<string, unknown>): ManifestChatHandle;
    merge(handles: ManifestChatHandle[], opts?: Record<string, unknown>): ManifestChatHandle;
    adapter(name: string, factory?: unknown): unknown;
    flatten(tree: unknown): unknown[];
    /** Shared revision counter — trackable even before any handle resolves. */
    readonly version: number;
    [extra: string]: unknown;
}

/** One `$status.<name>` entry. */
export interface ManifestStatusEntry {
    readonly state: string;
    [extra: string]: unknown;
}

/** `$status` from the status plugin: `$status.api.state`, iterable, stringifies to the overall state. */
export interface ManifestStatus extends Iterable<ManifestStatusEntry> {
    readonly [name: string]: any;
}

/** `$presence` from the Appwrite presences plugin. */
export interface ManifestPresence {
    start(opts?: Record<string, unknown>): Promise<unknown>;
    stop(): void;
    set(values: Record<string, unknown>): Promise<unknown>;
    clear(): Promise<unknown>;
    of(userId: string): unknown;
    all(): unknown[];
    readonly records: Record<string, unknown>;
    readonly list: unknown[];
    readonly ready: boolean;
    readonly error: unknown;
    readonly me: unknown;
}

/** `$date(id?)` from the datepicker plugin — the picker API for the nearest (or given) instance. */
export type ManifestDate = (id?: string) => Record<string, unknown>;

/** `$chart(id?)` from the charts plugin — the chart API for the nearest (or given) instance. */
export type ManifestChart = (id?: string) => Record<string, unknown>;

/** `$export(opts)` from the export plugin — export the page or a data source (pdf/csv/json/...). */
export type ManifestExport = (opts?: {
    format?: string;
    filename?: string;
    source?: string;
    data?: unknown;
    [extra: string]: unknown;
}) => Promise<unknown>;

/** `$import(opts)` from the import plugin — pick a local file and parse it (json/csv). Resolves the parsed data, or null when the dialog is dismissed. */
export type ManifestImport = (opts?: {
    format?: 'json' | 'csv';
    /** Data source to replace with the parsed content. */
    source?: string;
    /** Override the file input's accept list. */
    accept?: string;
    [extra: string]: unknown;
}) => Promise<unknown>;

/** `$device` from the utilities plugin (enriched by the device plugin when present). */
export interface ManifestDevice {
    readonly os: string;
    readonly touch: boolean;
    readonly online: boolean;
    readonly standalone: boolean;
    readonly native: boolean;
    readonly platform: string;
}

/** `$share` from the device plugin — native sheet, web share, or clipboard fallback. */
export type ManifestShare = (opts?: { title?: string; text?: string; url?: string }) =>
    Promise<{ shared: boolean; method: string; cancelled?: boolean }>;

/** `$push` from the device plugin — push/notification permissions and token. */
export interface ManifestPush {
    /** Ask for permission, on your schedule (never prompted on load). */
    request(): Promise<'granted' | 'denied' | 'prompt' | 'unsupported' | string>;
    /** Register with the platform push service (no-op on the web). */
    register(): Promise<unknown>;
    onToken(handler: (token: string) => void): void;
    onReceive(handler: (notification: unknown) => void): void;
    onTap(handler: (notification: unknown) => void): void;
    readonly permission: string;
    readonly token: string | null;
    [extra: string]: unknown;
}

/** `$secure` from the device plugin — secure key-value storage (native keychain or fallback). */
export interface ManifestSecure {
    get(key: string): Promise<string | null>;
    set(key: string, value: string): Promise<void>;
    remove(key: string): Promise<void>;
    keys(): Promise<string[]>;
    clear(): Promise<void>;
    use(adapter: unknown): void;
}

/** `$links` from the device plugin — deep/universal link handling. */
export interface ManifestLinks {
    /** Take over an inbound link: link.url is the full URL, link.path the route it maps to. */
    on(handler: (link: { url: string; path: string }) => void): void;
    open(url: string): void;
    readonly last: string | null;
}

/** `$app` from the device plugin — foreground/background state. */
export interface ManifestApp {
    readonly active: boolean;
    onChange(handler: (active: boolean) => void): void;
}

/** `$haptics` from the device plugin — haptic feedback with web vibration fallback. */
export interface ManifestHaptics {
    impact(style?: 'LIGHT' | 'MEDIUM' | 'HEAVY' | string): Promise<unknown>;
    notification(type?: 'SUCCESS' | 'WARNING' | 'ERROR' | string): Promise<unknown>;
    selection(): Promise<unknown>;
    vibrate(ms?: number): Promise<unknown> | unknown;
    [extra: string]: unknown;
}

/** `$biometric` from the device plugin. */
export interface ManifestBiometric {
    available(): Promise<boolean>;
    verify(opts?: Record<string, unknown>): Promise<unknown>;
}

/** `$camera` from the device plugin. */
export interface ManifestCamera {
    photo(opts?: Record<string, unknown>): Promise<unknown>;
    pick(opts?: Record<string, unknown>): Promise<unknown>;
}

/** Element editor (`x-edit`) — opt-in plugin. Sortable lists and resizable elements
 *  by default; add `.authoring` where a region is a page being edited. */
export interface ManifestEdit {
    /** True while a `.gated` area is editable. */
    active: boolean;
    canUndo: boolean;
    canRedo: boolean;
    /** Set a handler to route patches somewhere other than the dev server. */
    onPublish: ((patches: unknown[], state: { log: unknown[]; cursor: number }) => unknown) | null;
    toggle(): void;
    on(): void;
    off(): void;
    undo(): void;
    redo(): void;
    /** Lock an element and its subtree out of editing (runtime, not logged). */
    lock(el: Element): void;
    unlock(el: Element): void;
    /** Resolve the edit log into source patches and send them. */
    publish(): Promise<unknown>;
    /** The resolved source patches, without sending them. */
    patches(): unknown[];
    /** The raw delta log — persist it yourself to move edits between devices. */
    export(): { log: unknown[]; cursor: number };
    /** The block a context menu is acting on — set by the last right-click, or
     *  assignable. Block operations default to it when called with no element. */
    target: Element | null;
    /** Whether an operation applies right now: copy, cut, paste, duplicate, remove. */
    can(op: string, el?: Element): boolean;
    copy(el?: Element): boolean;
    cut(el?: Element): boolean;
    paste(el?: Element): boolean;
    duplicate(el?: Element): boolean;
    remove(el?: Element): boolean;
    /** The addressable block containing a node, or null. */
    block(node: Element): Element | null;
}

/** Text editor (`x-text-edit`) — the area this element sits in, or the last focused one. */
export interface ManifestTextEdit {
    /** The stored value, in the mode the directive was given. Assigning replaces the
     *  document and resets undo history. */
    value: string;
    focus(): void;
    /** The href at the caret; assign to set it, assign '' to unlink. */
    link: string;
    /** Page-level styles (font, size, leading, align, color, background) as CSS
     *  custom properties on the area. Presentation, not document content — persist
     *  it yourself. Assign `{}` to clear. */
    page: Record<string, string>;
    /** Select the whole document. */
    selectAll(): void;
    /** The current selection and its geometry, or null. Also emitted as a
     *  `text-edit:selection` event and as --text-edit-selection-* custom properties
     *  on the area, for anchoring a menu to it. */
    selection: {
        collapsed: boolean; text: string;
        x: number; y: number; width: number; height: number;
        top: number; bottom: number; left: number; right: number;
    } | null;
    /** Apply a command. Commands are named for the tag they produce — 'strong',
     *  'blockquote', 'h2', 'ul', 'a', 'img', 'table' — plus the operations with no
     *  tag of their own: 'indent', 'outdent', 'align', 'color', 'background',
     *  'font', 'size', 'checklist', 'clear', 'undo', 'redo', 'block'. */
    run(command: string, arg?: string | number): void;
    /** Whether that command is active at the caret. */
    active(command: string): boolean;
    /** Whether that command is available in this area's mode. */
    can(command: string): boolean;
    /** Read the content as markdown regardless of the storage mode. */
    markdown(): string;
    /** Read the content as sanitized HTML regardless of the storage mode. */
    html(): string;
}

/**
 * Manifest's custom-element/attribute authoring surface (documentation aid —
 * these are HTML attributes, not JS globals). Element styles pair with most.
 */
export type ManifestDirective =
    | 'x-route' | 'x-anchors'
    | 'x-icon' | 'x-svg' | 'x-markdown' | 'x-code' | 'x-code-group'
    | 'x-toast' | 'x-tooltip' | 'x-carousel' | 'x-virtual' | 'x-resize' | 'x-computed' | 'x-defer'
    | 'x-chart' | 'x-date' | 'x-color' | 'x-colorpicker' | 'x-combobox'
    | 'x-export' | 'x-import' | 'x-pay' | 'x-files' | 'x-data-files'
    | 'x-edit' | 'x-text-edit';

// ---------------------------------------------------------------------------
// Global declarations (what Alpine exposes inside `x-data`, `x-show`, etc.)
// ---------------------------------------------------------------------------

declare global {
    /** Project data sources registered in manifest.json. */
    const $x: ManifestSources;
    /** The current route path (compare or .startsWith against it). */
    const $route: ManifestRoute;
    /** Read a parent component attribute (Manifest's prop mechanism). */
    const $modify: ManifestModify;
    /** Run a callback safely, returning undefined on error. */
    const $try: ManifestTry;
    /**
     * Cached derivation for `x-data` / `Alpine.data` scopes: `rows: $computed(function () { return this.items.filter(…) })`.
     * Recomputed once per flush when a tracked dependency changes; reads as a plain property with a stable identity in between.
     */
    const $computed: <T>(fn: (this: any) => T) => T;
    /** Appwrite auth plugin (present when the plugin is loaded). */
    const $auth: ManifestAuth;
    /** Localization plugin. */
    const $locale: ManifestLocale;
    /** Toasts plugin. */
    const $toast: ManifestToast;
    /** Color-mode plugin (`$color.current = 'dark'`). */
    const $color: ManifestColor;
    /** Colorpicker plugin. */
    const $colorpicker: ManifestColorpicker;
    /** URL parameters plugin (`$url.tab.value`). */
    const $url: ManifestUrl;
    /** Payments plugin. */
    const $pay: ManifestPay;
    /** Chat plugin. */
    const $chat: ManifestChat;
    /** Status plugin. */
    const $status: ManifestStatus;
    /** Appwrite presences plugin. */
    const $presence: ManifestPresence;
    /** Datepicker plugin. */
    const $date: ManifestDate;
    /** Charts plugin. */
    const $chart: ManifestChart;
    /** Export plugin. */
    const $export: ManifestExport;
    /** Import plugin. */
    const $import: ManifestImport;
    /** Element editor (edit plugin; opt-in). */
    const $edit: ManifestEdit;
    /** Text editor (text-edit plugin). */
    const $text: ManifestTextEdit;
    /** Device/platform info (utilities; enriched by the device plugin). */
    const $device: ManifestDevice;
    /** Native share (device plugin). */
    const $share: ManifestShare;
    /** Push permissions (device plugin). */
    const $push: ManifestPush;
    /** Secure storage (device plugin). */
    const $secure: ManifestSecure;
    /** Deep links (device plugin). */
    const $links: ManifestLinks;
    /** App foreground state (device plugin). */
    const $app: ManifestApp;
    /** Haptics (device plugin). */
    const $haptics: ManifestHaptics;
    /** Biometric auth (device plugin). */
    const $biometric: ManifestBiometric;
    /** Camera (device plugin). */
    const $camera: ManifestCamera;

    /** Window-level Manifest namespace exposed by the loader. */
    interface Window {
        Manifest?: {
            loadPlugin(name: string, version?: string): Promise<unknown>;
            loadTailwind(version?: string): Promise<unknown>;
            getPluginUrl(name: string, version?: string): string;
            /** Defer a closed container built at runtime (call before Alpine.initTree). */
            defer?(el: Element): unknown;
            /** App-shell service worker diagnostics; kill() unregisters and clears its caches. */
            sw?: { registered: boolean; version: string | null; kill(): Promise<void> };
            /** The two-line same-origin /sw.js stub pinned to a framework version. */
            swStub?(version?: string): string;
        };
        Alpine?: unknown;
        __manifestLoaded?: unknown;
    }

    /**
     * Fired when the utilities runtime sees a class the baked sheet (and
     * `manifest.json`'s `utilities.safelist`/`patterns`) doesn't cover, after
     * publish stamped that sheet as covering every class — see
     * manifest.utilities.static.js. `engineLoaded` is true once the lazily
     * loaded Tailwind engine has taken over, false if that load failed.
     */
    interface WindowEventMap {
        'manifest:utilities-uncovered': CustomEvent<{ classes: string[]; engineLoaded: boolean }>;
    }
}

// ---------------------------------------------------------------------------
// AUGMENTATION:start
// Project-specific declarations are appended below by `npx mnfst-types`.
// Do not hand-edit between the start/end markers — re-running the CLI
// regenerates this section from manifest.json + sample data.
// ---------------------------------------------------------------------------

// (No project augmentations yet — run `npx mnfst-types` to generate.)

// ---------------------------------------------------------------------------
// AUGMENTATION:end
// ---------------------------------------------------------------------------

export { };