import { FC } from 'react';
import { HCEvalValue } from './HyperCardExpression';
import { HCContainerRef, HCEventName, HCPart, HCStack, HCValue } from './HyperCardModel';
/** Props every registered HyperCard part component receives. */
export interface HyperCardPartProps {
    /** The authored part definition (id, rect, options, …). */
    part: HCPart;
    partId: string;
    stackId: string;
    /** `part.options` — static "settings" applied to the embed. */
    options: Record<string, unknown>;
    /** `part.locked` — e.g. lock a map's pan/zoom controls. */
    locked: boolean;
    /** Current value in this part's field slot. */
    value: string;
    /** Commit a value back into this part's field slot (readable by scripts). */
    setValue: (value: string) => void;
    /** Trigger this part's own script (default `onMouseUp`). */
    fire: (event?: HCEventName) => void;
    /** Read a stack variable. */
    getVariable: (name: string) => HCValue | undefined;
    /** Evaluate a HyperCard expression against the current stack state. */
    resolve: (expr: string) => string;
}
export type HyperCardPartComponent = FC<HyperCardPartProps>;
/**
 * The context a command handler runs with, inside the pure reducer. Pure
 * commands mutate via get/set; async commands call `await(...)` to suspend the
 * stack until a matching effect handler resolves.
 */
export interface HCCommandContext {
    getVar: (name: string) => HCValue | undefined;
    setVar: (name: string, value: HCValue) => void;
    getField: (partId: string) => string | undefined;
    setField: (partId: string, value: string) => void;
    evaluate: (expr: string) => HCEvalValue;
    show: (partId: string, visible: boolean) => void;
    go: (to: string) => void;
    /** Queue a fire-and-forget custom effect for the component to handle async. */
    queueEffect: (name: string, args?: Record<string, unknown>) => void;
    /**
     * Suspend the stack and queue a custom effect; the matching effect handler
     * must call `api.resolve(value)` to bind the result (to `it` and the optional
     * container) and resume execution — the same mechanism as `ask`/`answer`.
     */
    await: (name: string, args?: Record<string, unknown>, into?: HCContainerRef) => void;
}
/** An action object dispatched to a command handler (`do` is the command name). */
export type HCCommandAction = {
    do: string;
} & Record<string, unknown>;
export interface HCCommandSpec {
    run: (ctx: HCCommandContext, action: HCCommandAction) => void;
}
export interface HyperCardEffectApi {
    /** Resume a blocking command with a result (no-op for fire-and-forget). */
    resolve: (value: string) => void;
    setField: (partId: string, value: string) => void;
    setVariable: (name: string, value: HCValue) => void;
    stackId: string;
}
export type HyperCardEffectHandler = (args: Record<string, unknown>, api: HyperCardEffectApi) => void | Promise<void>;
export type HyperCardOptionPickerComponent = FC<{
    value: unknown;
    onChange: (value: unknown) => void;
}>;
/** Register a custom display part rendered by its `type` name. */
export declare function registerHyperCardPart(type: string, component: HyperCardPartComponent): void;
export declare function getHyperCardPart(type: string): HyperCardPartComponent | undefined;
/** Register a custom command (a stack action with `do: name`). */
export declare function registerHyperCardCommand(name: string, spec: HCCommandSpec): void;
export declare function getHyperCardCommand(name: string): HCCommandSpec | undefined;
/** Register a component-side async handler for a custom effect. */
export declare function registerHyperCardEffectHandler(name: string, handler: HyperCardEffectHandler): void;
export declare function getHyperCardEffectHandler(name: string): HyperCardEffectHandler | undefined;
/** Register a component that replaces the bare input for a "picker"-kind option field. */
export declare function registerHyperCardOptionPicker(id: string, component: HyperCardOptionPickerComponent): void;
export declare function getHyperCardOptionPicker(id: string): HyperCardOptionPickerComponent | undefined;
/** Register a stack so it appears in HyperCard's top-level Examples menu. */
export declare function registerHyperCardStack(id: string, name: string, stack: HCStack): void;
export declare function getRegisteredStacks(): {
    id: string;
    name: string;
    stack: HCStack;
}[];
/** One typed field in an inspector/builder form. `choices` edits a string list; `json` edits raw JSON; `picker` renders a registered component in place of the bare input. */
export interface HCOptionField {
    key: string;
    label: string;
    kind: "text" | "number" | "checkbox" | "choices" | "json" | "sound" | "picker";
    default?: unknown;
    /** Required when kind === "picker" — looked up via getHyperCardOptionPicker. */
    pickerId?: string;
}
/** How the stack EDITOR presents a registered custom part. */
export interface HyperCardPartEditorMeta {
    label: string;
    defaultSize?: [number, number];
    defaultOptions?: Record<string, unknown>;
    defaultContent?: string;
    optionsSchema?: HCOptionField[];
}
/** How the script BUILDER presents a registered custom command. */
export interface HyperCardCommandEditorMeta {
    label: string;
    fields: HCOptionField[];
}
export declare function registerHyperCardPartEditorMeta(type: string, meta: HyperCardPartEditorMeta): void;
export declare function getHyperCardPartEditorMeta(type: string): HyperCardPartEditorMeta | undefined;
export declare function getRegisteredEditorPartTypes(): {
    type: string;
    meta: HyperCardPartEditorMeta;
}[];
export declare function registerHyperCardCommandEditorMeta(name: string, meta: HyperCardCommandEditorMeta): void;
export declare function getHyperCardCommandEditorMeta(name: string): HyperCardCommandEditorMeta | undefined;
export declare function getRegisteredEditorCommands(): {
    name: string;
    meta: HyperCardCommandEditorMeta;
}[];
export interface HCSavedStackRef {
    id: string;
    name: string;
    updatedAt?: string;
}
/**
 * On a successful save, providers that persist to an addressable store
 * SHOULD return `ref` so the host can rebind the open stack to
 * `saved:<providerId>:<ref.id>` — otherwise a first-time create is followed
 * by duplicate creates on every resave.
 */
export type HCSaveResult = {
    ok: true;
    ref?: HCSavedStackRef;
} | {
    ok: false;
    error: string;
};
/** A destination the editor can save stacks to (and optionally reopen from). */
export interface HyperCardSaveProvider {
    id: string;
    label: string;
    canSave: () => boolean;
    save: (stack: HCStack, meta: {
        stackId: string;
        fileName?: string;
    }) => Promise<HCSaveResult>;
    list?: () => Promise<HCSavedStackRef[]>;
    load?: (ref: HCSavedStackRef) => Promise<HCStack>;
}
export declare function registerHyperCardSaveProvider(provider: HyperCardSaveProvider): void;
export declare function getHyperCardSaveProviders(): HyperCardSaveProvider[];
//# sourceMappingURL=HyperCardPlugins.d.ts.map