Canvas SDK API.

/** Identity helper preserving the definition's precise inferred type. */
export declare function definePlugin<const Definition extends PluginDefinition>(plugin: Definition): Definition;

/** Converts `#rgb`, `#rrggbb`, or `#rrggbbaa` to an Editful packed color. */
export declare function hexColor(hex: string): number;

/**
 * Validates the complete JSON-Schema subset supported by plugin actions.
 * Registration, desktop execution, and the MCP catalog all use this contract.
 */
export declare function validatePluginActionSchema(schema: Readonly<Record<string, PluginJson>>, path?: string, depth?: number): void;

export declare class PluginActionCancelledError extends Error {
    constructor(message?: string);
}

export declare class PluginActionConflictError extends Error {
    constructor(message?: string);
}

export declare class PluginConfigurationError extends Error {
    constructor(message: string);
}

export declare class PluginHostFeatureError extends Error {
    constructor(message: string);
}

export declare class PluginNetworkError extends Error {
    constructor(message: string);
}

export interface CreateContribution {
    readonly label: string;
    readonly icon?: string;
    readonly shortcut: string;
    readonly cursor: 'crosshair' | 'text';
    readonly gesture: 'drag' | 'place';
    readonly order: number;
    readonly defaultSize: {
        readonly width: number;
        readonly height: number;
    };
    readonly styleSlot: 'shape' | 'palette' | 'text';
    readonly opensTextEditor?: boolean;
}

export interface FieldHandle<Value, Kind = unknown> {
    readonly [FIELD_VALUE]: (value: Value) => Value;
    readonly [FIELD_KIND]: (kind: Kind) => Kind;
}

export interface FieldOptions<Value> {
    readonly default?: Value;
}

export interface KindBuilder<Kind = unknown> {
    readonly field: KindFieldBuilder<Kind>;
    readonly ui: ViewBuilder<Kind>;
    create(contribution: CreateContribution): void;
    hit(shape: 'rect' | 'ellipse'): void;
    text(contribution: TextContribution<Kind>): void;
    view(contribution: ViewContribution<Kind>): void;
    defaults(contribution: StyleDefaults): void;
    agent(contribution: {
        readonly name: string;
        readonly description?: string;
    }): void;
    interaction(contribution: PluginInteractionContribution): void;
    asset(): void;
    pack(fn: PackFunction<Kind>): void;
}

export interface KindFieldBuilder<Kind = unknown> {
    f64(name: string, options?: FieldOptions<number>): FieldHandle<number, Kind>;
    i32(name: string, options?: FieldOptions<number>): FieldHandle<number, Kind>;
    bool(name: string, options?: FieldOptions<boolean>): FieldHandle<boolean, Kind>;
    string(name: string, options?: FieldOptions<string>): FieldHandle<string, Kind>;
    text(name: string): FieldHandle<string, Kind>;
}

/** Read-only node view valid only for the duration of one pack call. */
export interface PackedNode<Kind = unknown> {
    readonly x: number;
    readonly y: number;
    readonly halfW: number;
    readonly halfH: number;
    readonly rotation: number;
    readonly cornerRadius: number;
    readonly strokeWidth: number;
    readonly fill: number;
    readonly stroke: number;
    readonly assetId: string;
    readonly fontFamily: number;
    readonly fontSize: number;
    readonly fontWeight: number;
    readonly fontItalic: boolean;
    readonly textAlign: number;
    readonly textColor: number;
    readonly lineHeight: number;
    readonly letterSpacing: number;
    readonly textPadding: number;
    readonly textVerticalAlign: number;
    readonly textSizing: number;
    get<Value>(field: FieldHandle<Value, Kind>): Value;
}

export type PackFunction<Kind = unknown> = (node: PackedNode<Kind>, services: PackServices, out: PrimitiveWriter) => void;

export interface PackServices {
    readonly text: {
        readonly sharedTextStyle: TextStyle;
        familyOf(font: number): TextStyle['family'];
    };
}

export interface PluginActionContext {
    readonly signal: AbortSignal;
    /** Stable board id for constructing declared board-scoped service requests. */
    readonly boardId?: string;
    readonly document: PluginDocument;
    readonly selection: PluginSelection;
    readonly settings: PluginSettings;
    readonly secrets: PluginSecrets;
    readonly network: PluginNetwork;
    readonly remoteMedia: PluginRemoteMedia;
    readonly ui: PluginActionUi;
    readonly editors: PluginEditors;
    openExternal(url: string): Promise<void>;
}

export interface PluginActionUi {
    prompt(options: {
        readonly label: string;
        readonly description?: string;
        readonly initial?: string | number;
    }): Promise<string | number | null>;
    confirm(options: {
        readonly label: string;
        readonly description?: string;
    }): Promise<boolean>;
    pick<Value extends PluginJson>(options: {
        readonly label: string;
        readonly description?: string;
        readonly items: readonly PluginPickerItem<Value>[];
    }): Promise<Value | null>;
    /**
     * Publishes a bounded notice into the host notification tray. Plugins cannot
     * choose its position, duration, markup, or actions.
     */
    notify(notification: PluginNotification): void;
    progress(message: string): void;
    error(message: string): void;
}

export interface PluginAgentActionContribution<Input extends PluginJson = PluginJson, Output extends PluginJson = PluginJson> {
    readonly id: string;
    readonly name: string;
    readonly description: string;
    readonly inputSchema: Readonly<Record<string, PluginJson>>;
    readonly outputSchema: Readonly<Record<string, PluginJson>>;
    readonly requiresConfirmation: boolean;
    run(input: Input, context: PluginActionContext): Promise<Output>;
}

export interface PluginCommandContribution {
    readonly id: string;
    readonly label: string;
    readonly description?: string;
    readonly shortcut?: string;
    /** Exposes this command as a toolbar button in addition to the command palette. */
    readonly toolbar?: {
        /** Optional toolbar-only label; the command palette keeps the command label. */
        readonly label?: string;
        /** Built-in glyph key or explicit `./path.svg` bundled in the plugin artifact. */
        readonly icon?: string;
        readonly order: number;
        /**
         * Manual editor whose open state makes this button behave as an active
         * canvas tool. The host dismisses that editor after choosing empty canvas
         * or a different object, while clicks on the current selection keep it open.
         */
        readonly activeEditor?: string;
    };
    readonly selection?: {
        readonly minimum?: number;
        readonly maximum?: number;
        readonly kinds?: readonly string[];
    };
    run(context: PluginActionContext): Promise<void>;
}

export interface PluginContext {
    readonly pluginId: string;
    kind<const Id extends string>(id: Id): KindBuilder<Id>;
    command(contribution: PluginCommandContribution): void;
    editor(contribution: PluginEditorContribution): void;
    importer(contribution: PluginImporterContribution): void;
    action(contribution: PluginAgentActionContribution): void;
}

export interface PluginDefinition {
    register(context: PluginContext): void;
}

export interface PluginDocument {
    readonly revision: number;
    inspect(nodeIds: readonly string[]): readonly PluginNodeSnapshot[];
    transaction(label: string): PluginDocumentTransaction;
}

export interface PluginDocumentTransaction {
    create(node: PluginNodeCreate): void;
    update(node: PluginNodeUpdate): void;
    delete(nodeId: string): void;
    commit(): void;
}

export interface PluginEditorContribution {
    readonly id: string;
    readonly label: string;
    readonly surface: PluginEditorSurface;
    readonly order?: number;
    /**
     * Automatic editors follow their selection requirement. Manual editors are
     * hidden until this plugin opens them through `context.editors`.
     */
    readonly activation?: 'automatic' | 'manual';
    /**
     * Omit to allow any selection. When present, every selected node must match
     * the declared kinds. This applies after the activation requirement.
     */
    readonly selection?: {
        readonly minimum?: number;
        readonly maximum?: number;
        readonly kinds?: readonly string[];
    };
    /**
     * Mounts trusted plugin UI directly into Editful's renderer. Plugins may use
     * plain DOM or mount a bundled React root and must release owned resources.
     */
    mount(container: HTMLElement, context: PluginActionContext): void | (() => void) | PluginEditorInstance;
}

export interface PluginEditorInstance {
    update?(context: PluginActionContext): void;
    dispose(): void;
}

/**
 * Controls trusted plugin editor surfaces owned by the current plugin.
 *
 * Manual editor state is transient host UI state: it is bounded JSON, is not
 * written to the canvas document, and disappears with the current runtime.
 */
export interface PluginEditors {
    open(editorId: string, state?: PluginJson): void;
    close(editorId: string): void;
    state(editorId: string): PluginJson | undefined;
}

export type PluginEditorSurface = 'toolbar' | 'left-sidebar' | 'right-sidebar';

export interface PluginImporterContribution {
    readonly id: string;
    readonly label: string;
    readonly priority?: number;
    readonly match: {
        readonly mediaTypes?: readonly string[];
        readonly extensions?: readonly string[];
        readonly urlSchemes?: readonly string[];
        readonly urlHosts?: readonly string[];
    };
    import(input: PluginImporterInput, context: PluginActionContext): Promise<'handled' | 'rejected'>;
}

export interface PluginImporterInput {
    readonly operation: 'paste' | 'drop';
    readonly text?: string;
    readonly uriList?: readonly string[];
    readonly files: readonly {
        readonly name: string;
        readonly mediaType: string;
        readonly byteLength: number;
        readBytes(): Promise<Uint8Array>;
    }[];
    readonly point: {
        readonly x: number;
        readonly y: number;
    };
}

export interface PluginInteractionContribution {
    readonly id: string;
    readonly label: string;
    readonly cursor: 'pointer' | 'default';
    activate(node: PluginNodeSnapshot, context: PluginActionContext): Promise<void>;
}

export type PluginJson = null | PluginScalar | readonly PluginJson[] | {
    readonly [key: string]: PluginJson;
};

export interface PluginNetwork {
    request(request: PluginNetworkRequest): Promise<PluginNetworkResponse>;
}

export interface PluginNetworkRequest {
    readonly url: string;
    readonly method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
    readonly headers?: Readonly<Record<string, string>>;
    readonly body?: string | Uint8Array;
    readonly response?: 'json' | 'text' | 'bytes';
    readonly timeoutMs?: number;
    /** Host-injected board credential, available only for the first-party service. */
    readonly auth?: 'board';
}

export interface PluginNetworkResponse {
    readonly status: number;
    readonly headers: Readonly<Record<string, string>>;
    readonly body: PluginJson | string | Uint8Array;
}

export interface PluginNodeCreate {
    readonly kind: string;
    readonly x: number;
    readonly y: number;
    readonly width: number;
    readonly height: number;
    readonly rotation?: number;
    readonly fill?: number;
    readonly stroke?: number;
    readonly strokeWidth?: number;
    readonly fontFamily?: TextFont;
    readonly fontSize?: number;
    readonly fontWeight?: number;
    readonly fontItalic?: boolean;
    readonly textAlign?: TextAlign;
    readonly textColor?: number;
    readonly lineHeight?: number;
    readonly letterSpacing?: number;
    readonly textPadding?: number;
    readonly textVerticalAlign?: TextVerticalAlign;
    readonly fields?: Readonly<Record<string, PluginScalar>>;
}

export interface PluginNodeSnapshot {
    readonly id: string;
    readonly kind: string;
    readonly x: number;
    readonly y: number;
    readonly width: number;
    readonly height: number;
    readonly rotation: number;
    readonly fill: number;
    readonly stroke: number;
    readonly strokeWidth: number;
    readonly fontFamily: TextFont;
    readonly fontSize: number;
    readonly fontWeight: number;
    readonly fontItalic: boolean;
    readonly textAlign: TextAlign;
    readonly textColor: number;
    readonly lineHeight: number;
    readonly letterSpacing: number;
    readonly textPadding: number;
    readonly textVerticalAlign: TextVerticalAlign;
    field<Value extends PluginScalar>(name: string): Value | undefined;
}

export interface PluginNodeUpdate {
    readonly id: string;
    readonly x?: number;
    readonly y?: number;
    readonly width?: number;
    readonly height?: number;
    readonly rotation?: number;
    readonly fill?: number;
    readonly stroke?: number;
    readonly strokeWidth?: number;
    readonly fontFamily?: TextFont;
    readonly fontSize?: number;
    readonly fontWeight?: number;
    readonly fontItalic?: boolean;
    readonly textAlign?: TextAlign;
    readonly textColor?: number;
    readonly lineHeight?: number;
    readonly letterSpacing?: number;
    readonly textPadding?: number;
    readonly textVerticalAlign?: TextVerticalAlign;
    readonly fields?: Readonly<Record<string, PluginScalar>>;
}

export interface PluginNotification {
    /** Short notification heading rendered as text by the host. */
    readonly title: string;
    /** Optional supporting copy rendered as text by the host. */
    readonly message?: string;
    /**
     * The host owns placement and lifetime. Info, success, and warning notices
     * leave automatically; errors remain until resolved or dismissed.
     */
    readonly tone?: PluginNotificationTone;
}

export type PluginNotificationTone = 'info' | 'success' | 'warning' | 'error';

export interface PluginPickerItem<Value extends PluginJson = PluginJson> {
    readonly value: Value;
    readonly label: string;
    readonly description?: string;
    readonly imageUrl?: string;
    readonly links?: readonly PluginPickerLink[];
}

export interface PluginPickerLink {
    readonly label: string;
    readonly href: string;
}

export interface PluginRemoteImageDimensions {
    readonly width: number;
    readonly height: number;
}

export interface PluginRemoteMedia {
    /**
     * Decodes an exact URL under this plugin's declared remote-media policy and
     * leaves the result warm in the host image cache.
     */
    probe(url: string): Promise<PluginRemoteImageDimensions>;
}

export type PluginScalar = string | number | boolean;

export interface PluginSecrets {
    get(name: string): Promise<string | undefined>;
}

export interface PluginSelection {
    snapshot(): PluginSelectionSummary;
    nodeIds(): readonly string[];
}

export interface PluginSelectionSummary {
    readonly count: number;
    readonly kindIds: readonly string[];
}

export interface PluginSettings {
    get(key: string): PluginScalar | undefined;
}

export interface PrimitiveWriter {
    quad(x: number, y: number, halfW: number, halfH: number, rotation: number, cornerRadius: number, strokeWidth: number, primitive: Primitive, fill: number, stroke: number): void;
    textBlock(block: {
        x: number;
        y: number;
        halfW: number;
        halfH: number;
        text: string;
        style: TextStyle;
        font: number;
        wrapWidth: number;
        padding: number;
        /** Overrides vertical inset while preserving `padding` horizontally. */
        verticalPadding?: number;
        verticalAlign: number;
        readonly background?: {
            readonly fill: number;
            readonly stroke?: number;
            readonly strokeWidth?: number;
            readonly cornerRadius: number;
        };
    }): void;
    imageQuad(assetId: string, x: number, y: number, halfW: number, halfH: number, rotation: number): void;
    imageQuad(source: {
        readonly url: string;
    }, x: number, y: number, halfW: number, halfH: number, rotation: number): void;
    interactionRegion(interactionId: string, x: number, y: number, width: number, height: number, semantics: {
        readonly role: 'button' | 'link';
        readonly label: string;
    }): void;
}

export interface StyleDefaults {
    readonly fill?: number;
    readonly stroke?: number;
    readonly strokeWidth?: number;
    readonly cornerRadius?: number;
    readonly fontSize?: number;
    readonly textColor?: number;
    readonly lineHeight?: number;
    readonly textSizing?: number;
}

export interface TextContribution<Kind = unknown> {
    readonly field: FieldHandle<string, Kind>;
    readonly padding: number | 'node';
    readonly verticalAlign: 'top' | 'center' | 'node';
    readonly font: 'shared' | 'node';
    readonly width: 'user' | 'auto' | 'derived';
    readonly height: 'user' | 'auto' | 'derived';
    readonly minWidth?: number;
    readonly minHeight?: number;
}

export interface TextStyle {
    readonly family: 'sans' | 'serif' | 'mono';
    readonly weight: number;
    readonly italic: boolean;
    readonly size: number;
    readonly lineHeight: number;
    readonly letterSpacing: number;
    readonly align: 'left' | 'center' | 'right';
    readonly color: number;
}

/** Paint, padding, and optional child content for a container. */
export interface ViewBoxOptions<Kind = unknown> {
    /** The single child inside the box. */
    readonly child?: ViewNode<Kind>;
    /** Defaults to zero. Physical sides override their logical axis. */
    readonly padding?: number | ViewInsets;
    /** Packed fill, field-bound fill, or the node's fill. */
    readonly fill?: ViewValue<number, Kind> | 'node';
    /** Packed stroke, field-bound stroke, or the node's stroke. */
    readonly stroke?: ViewValue<number, Kind> | 'node';
    /** Stroke width in canvas units, or the node's stroke width. */
    readonly strokeWidth?: number | 'node';
    /** Corner radius, the node's radius, or a full pill radius. */
    readonly cornerRadius?: number | 'node' | 'full';
}

/** Kind-scoped factory for declarative view primitives. */
export interface ViewBuilder<Kind = unknown> {
    /** Creates measured display text from a literal or field value. */
    text(value: ViewValue<string, Kind>, options: ViewTextOptions<Kind>): ViewNode<Kind>;
    /** Creates a fixed-height remote or document-backed image. */
    image(source: ViewImageSource<Kind>, options: ViewImageOptions): ViewNode<Kind>;
    /** Creates a painted container with zero or one child. */
    box(options: ViewBoxOptions<Kind>): ViewNode<Kind>;
    /** Creates an inline or block layout container. */
    stack(options: ViewStackOptions<Kind>): ViewNode<Kind>;
    /** Creates flexible space within an inline stack. */
    spacer(): ViewNode<Kind>;
}

/** Root view and host-owned sizing policy registered with a node kind. */
export interface ViewContribution<Kind = unknown> {
    /** Root of the declarative view tree. */
    readonly root: ViewNode<Kind>;
    /** User-resizable width and optional minimum width. */
    readonly width: {
        readonly mode: 'user';
        readonly min?: number;
    };
    /** Height derived from the measured root content. */
    readonly height: {
        readonly mode: 'fit-content';
    };
}

/** Fixed image dimensions within a declarative view. */
export interface ViewImageOptions {
    /** Fixed width, or all available block width. */
    readonly width: number | 'fill';
    /** Fixed height in canvas units. */
    readonly height: number;
}

/** Remote or document-backed source for an image primitive. */
export type ViewImageSource<Kind = unknown> = {
    readonly url: ViewValue<string, Kind>;
} | {
    readonly asset: ViewValue<string, Kind>;
};

/** Logical and physical insets for a view box. Physical sides take precedence. */
export interface ViewInsets {
    /** Left and right inset. */
    readonly inline?: number;
    /** Top and bottom inset. */
    readonly block?: number;
    /** Top inset. */
    readonly top?: number;
    /** Right inset. */
    readonly right?: number;
    /** Bottom inset. */
    readonly bottom?: number;
    /** Left inset. */
    readonly left?: number;
}

/** Opaque declarative view node created by a kind's {@link ViewBuilder}. */
export interface ViewNode<Kind = unknown> {
    readonly [VIEW_NODE_KIND]: (kind: Kind) => Kind;
}

/** Ordered children on the inline or block axis. */
export interface ViewStackOptions<Kind = unknown> {
    /** Inline lays out left to right. Block lays out top to bottom. */
    readonly axis: 'inline' | 'block';
    /** Ordered view nodes owned by the same kind. */
    readonly children: readonly ViewNode<Kind>[];
    /** Defaults to zero. */
    readonly gap?: number;
    /** Inline cross-axis alignment. Defaults to center. */
    readonly align?: 'start' | 'center' | 'end';
}

/** Font metrics used by both text measurement and paint. */
export interface ViewTextFont {
    /** Bundled font family. */
    readonly family: TextFont;
    /** Font size in canvas units, or the node's font size. */
    readonly size: number | 'node';
    /** Numeric font weight, or the node's font weight. */
    readonly weight: number | 'node';
    /** Italic state, or the node's italic state. */
    readonly italic?: boolean | 'node';
    /** Unitless line height, or the node's line height. */
    readonly lineHeight: number | 'node';
    /** Letter spacing in canvas units, or the node's letter spacing. */
    readonly letterSpacing?: number | 'node';
    /** Horizontal text alignment. */
    readonly align?: 'left' | 'center' | 'right';
}

/** Options for a display-only text primitive. */
export interface ViewTextOptions<Kind = unknown> {
    /** Font metrics shared by measurement and paint. */
    readonly font: ViewTextFont;
    /** Packed color, field-bound color, or the node's text color. */
    readonly color: ViewValue<number, Kind> | 'node';
    /** Defaults to true. False measures the text at its intrinsic width. */
    readonly wrap?: boolean;
    /** Optional pointer semantics for the text bounds. */
    readonly interaction?: {
        /** Identifier reported to the plugin interaction handler. */
        readonly id: string;
        /** Accessible interaction role. */
        readonly role: 'button' | 'link';
        /** Accessible label for the interaction region. */
        readonly label: string;
    };
}

/** A fixed value or a field handle resolved from the rendered canvas node. */
export type ViewValue<Value, Kind = unknown> = Value | FieldHandle<Value, Kind>;

/** Runtime plugin contract implemented by compatible Editful 0.9.x releases. */
export declare const EDITFUL_PLUGIN_API_VERSION: "0.9.0";

export declare const Primitive: {
    readonly RoundRect: 0;
    readonly Ellipse: 1;
    readonly None: 2;
    readonly TextBlock: 100;
    readonly ImageQuad: 101;
};
export type Primitive = (typeof Primitive)[keyof typeof Primitive];

export declare const TextAlign: {
    readonly Left: 0;
    readonly Center: 1;
    readonly Right: 2;
};
export type TextAlign = (typeof TextAlign)[keyof typeof TextAlign];

export declare const TextFont: {
    readonly Sans: 0;
    readonly Serif: 1;
    readonly Mono: 2;
};
export type TextFont = number;

export declare const TextSizing: {
    readonly Fixed: 0;
    readonly AutoWidth: 1;
    readonly AutoHeight: 2;
    readonly Auto: 3;
};

export declare const TextVerticalAlign: {
    readonly Top: 0;
    readonly Middle: 1;
    readonly Bottom: 2;
};
export type TextVerticalAlign = (typeof TextVerticalAlign)[keyof typeof TextVerticalAlign];

/** Sentinel used by text layout when wrapping is disabled. */
export declare const UNBOUNDED_WRAP: number;