Canvas SDK API.

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

/** Packs independently configurable start/end markers for a line quad. */
export declare function encodeLineMarkers(start: LineMarker, end: LineMarker): number;

/** 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';
    /** Geometry authored by the create gesture. Defaults to an axis-aligned box. */
    readonly geometry?: 'box' | 'line';
    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;
    readonly recordsVersion: 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 PluginBackgroundHandle<State extends PluginJson = PluginJson> {
    readonly id: string;
    readonly label: string;
    readonly [BACKGROUND_STATE]: State;
}

export type PluginBackgroundStatus<State extends PluginJson = PluginJson> = {
    readonly status: 'vacant';
} | {
    readonly status: 'owned';
    readonly state: State;
} | {
    readonly status: 'occupied';
    readonly pluginId: string;
    readonly contributionId: string;
    readonly label: string;
};

export interface PluginBackgroundSurfaceContribution<Kind = unknown, State extends PluginJson = PluginJson> {
    readonly id: string;
    readonly label: string;
    readonly stateSchema: Readonly<Record<string, PluginJson>>;
    readonly sourceKind: string;
    sourceNodeId(state: State): string;
    pack(source: PackedNode<Kind>, state: State, services: PackServices, out: PrimitiveWriter): void;
}

export interface PluginBindingChildEdit {
    readonly x: number;
    readonly y: number;
    readonly width: number;
    readonly height: number;
    readonly rotation: number;
}

export interface PluginBindingDefinition {
    readonly roles: readonly string[];
    readonly onParentRemoved: 'cascade' | 'unbind';
    resolve(child: PluginBindingNodeView, parents: ReadonlyMap<string, PluginBindingNodeView>, payloads: ReadonlyMap<string, PluginJson>): PluginBindingResolveResult | null;
    invert?(edit: PluginBindingChildEdit, parents: ReadonlyMap<string, PluginBindingNodeView>, payloads: ReadonlyMap<string, PluginJson>): Readonly<Record<string, PluginJson>> | null;
}

export interface PluginBindingNodeView {
    readonly x: number;
    readonly y: number;
    readonly width: number;
    readonly height: number;
    readonly rotation: number;
    readonly presentation: 'node' | 'background-source';
    field(key: string): PluginScalar | null;
}

export interface PluginBindingResolveResult {
    readonly x?: number;
    readonly y?: number;
    readonly width?: number;
    readonly height?: number;
    readonly rotation?: number;
    readonly fields?: Readonly<Record<string, PluginScalar>>;
}

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[];
    };
    readonly contextMenu?: {
        readonly target: 'selection';
    } | {
        readonly target: 'background';
        readonly background: PluginBackgroundHandle;
    };
    readonly background?: {
        readonly handle: PluginBackgroundHandle;
        readonly status: 'vacant' | 'owned';
    };
    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;
    binding(type: string, definition: PluginBindingDefinition): void;
    backgroundSurface<Kind = unknown, State extends PluginJson = PluginJson>(contribution: PluginBackgroundSurfaceContribution<Kind, State>): PluginBackgroundHandle<State>;
    migration(contribution: PluginMigrationContribution): void;
    /** Registers trusted same-context rendering under `gpu-renderer`. */
    renderer(contribution: PluginRendererContribution): void;
}

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

export interface PluginDocument {
    readonly revision: number;
    inspect(nodeIds: readonly string[]): readonly PluginNodeSnapshot[];
    /** Reads a bounded projection of one declared kind. */
    inspectKind(kindId: string, limit?: number): readonly PluginNodeSnapshot[];
    /** Reads one opaque document-scoped collaborative collection. */
    recordCollection(collectionId: string, ownerKind: string): PluginRecordCollection | null;
    background<State extends PluginJson>(handle: PluginBackgroundHandle<State>): PluginBackgroundStatus<State>;
    transaction(label: string): PluginDocumentTransaction;
}

export interface PluginDocumentTransaction {
    /** Stages a node and returns a transaction-local id usable by bind. */
    create(node: PluginNodeCreate): string;
    update(node: PluginNodeUpdate): void;
    delete(nodeId: string): void;
    bind(options: {
        readonly child: string;
        readonly role: string;
        readonly type: string;
        readonly parent: string;
        readonly payload: PluginJson;
    }): this;
    unbind(options: {
        readonly child: string;
        readonly role: string;
    }): this;
    setRecord(options: {
        readonly node: string;
        readonly recordId: string;
        readonly value: PluginJson | null;
    }): this;
    setCollectionRecord(options: {
        readonly collectionId: string;
        readonly ownerKind: string;
        readonly recordId: string;
        readonly value: PluginJson | null;
    }): this;
    claimBackground<State extends PluginJson>(handle: PluginBackgroundHandle<State>, state: NoInfer<State>): this;
    releaseBackground(handle: PluginBackgroundHandle): this;
    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[];
    };
    readonly background?: PluginBackgroundHandle;
    /**
     * 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 PluginMigrationContribution {
    readonly id: string;
    run(context: PluginActionContext): Promise<'unchanged' | 'migrated'>;
}

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 locked: boolean;
    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 bindings: readonly {
        readonly role: string;
        readonly type: string;
        readonly parent: string;
        readonly payload: PluginJson;
    }[];
    readonly records: {
        readonly version: number;
        readonly count: number;
    };
    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 locked?: boolean;
    readonly sendToBack?: boolean;
    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 PluginRecordCollection {
    /** Stable document node id used when a user action needs history. */
    readonly ownerId: string;
    readonly records: ReadonlyMap<string, string>;
    readonly version: number;
}

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 interface PluginRendererContribution {
    readonly id: string;
    create(host: PluginRendererHost): PluginRendererInstance;
}

/** A case-insensitive response-header snapshot returned by renderer I/O. */
export type PluginRendererHeaders = Readonly<Record<string, string>>;

/** Services retained for one renderer contribution's complete lifetime. */
export interface PluginRendererHost {
    /** The Editful-owned context. The host restores its state after each call. */
    readonly gl: WebGL2RenderingContext;
    /** Active collaborative board identity; absent for a local-only document. */
    readonly boardId?: string;
    readonly network: PluginRendererNetwork;
    readonly workers: PluginRendererWorkers;
    /** Schedules another host canvas frame without starting a private loop. */
    requestFrame(): void;
    /** Resolves a validated plugin artifact asset to a retained URL. */
    assetUrl(asset: string): string;
    /** Current document records owned by a visible surface node. */
    records(surfaceId: string): ReadonlyMap<string, string> | null;
    /** Writes an automatic renderer-owned cache record without adding user history. */
    setRecord(surfaceId: string, recordId: string, value: PluginJson | null): boolean;
    /** Resolves an opaque document-scoped collection to its collaborative owner. */
    recordCollection(collectionId: string, ownerKind: string): PluginRecordCollection | null;
    /** Writes an automatic record in a document-scoped collaborative collection. */
    setCollectionRecord(collectionId: string, ownerKind: string, recordId: string, value: PluginJson | null): boolean;
}

/** One renderer runtime shared by every surface emitted for its contribution. */
export interface PluginRendererInstance {
    /** Return true when another frame is required after this one. */
    render(frame: PluginSurfaceFrame, target: PluginSurfaceRenderTarget): void | boolean;
    query?(query: PluginSurfaceQuery): PluginSurfaceQueryResult | null;
    featureDrag?(surfaceId: string, phase: PluginSurfaceFeatureDragPhase, point: PluginSurfacePoint): PluginSurfaceFeatureDragResult;
    /** Handles a create-tool placement without exposing domain data to core. */
    place?(surfaceId: string, nodeId: string, kindId: string, point: PluginSurfacePoint): PluginSurfacePlacementResult | false;
    /** Clears renderer-owned selection visuals for one surface. */
    clearFeatureSelection?(surfaceId: string): void;
    /** Returns domain-owned labels/links positioned by generic host chrome. */
    chrome?(surfaceId: string): PluginSurfaceChrome | null;
    surfaceDisposed?(surfaceId: string): void;
    contextLost?(): void;
    contextRestored?(): void;
    dispose(): void;
}

/** Renderer-lifetime, policy-checked network access for tiles and style data. */
export interface PluginRendererNetwork {
    request(request: PluginRendererRequest): Promise<PluginRendererResponse>;
}

export interface PluginRendererRequest {
    readonly url: string;
    readonly method?: 'GET' | 'POST';
    readonly headers?: PluginRendererHeaders;
    readonly body?: ArrayBuffer;
    readonly signal?: AbortSignal;
    /** Host-injected active-board credential for a declared first-party origin. */
    readonly auth?: 'board';
    /** Lower values are more urgent. */
    readonly priority?: number;
}

export interface PluginRendererResponse {
    readonly url: string;
    readonly status: number;
    readonly headers: PluginRendererHeaders;
    readonly body: ArrayBuffer;
}

/** A validated plugin-relative worker owned and terminated by the host. */
export interface PluginRendererWorker {
    postMessage(message: unknown, transfer?: readonly Transferable[]): void;
    onMessage(listener: (message: unknown) => void): () => void;
    onError(listener: (error: ErrorEvent) => void): () => void;
    terminate(): void;
}

export interface PluginRendererWorkers {
    create(asset: string, options?: {
        readonly name?: string;
    }): PluginRendererWorker;
}

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 PluginSurfaceChrome {
    readonly badges?: readonly PluginSurfaceChromeBadge[];
}

export interface PluginSurfaceChromeBadge {
    readonly id: string;
    readonly label: string;
    readonly details?: string;
    readonly href?: string;
    readonly corner: 'bottom-right';
}

export interface PluginSurfaceEditorRequest {
    /** Manual editor contribution owned by the surface renderer's plugin. */
    readonly editorId: string;
    /** Opaque transient state copied and passed back to that editor. */
    readonly state?: PluginJson;
}

export type PluginSurfaceFeatureDragPhase = 'start' | 'move' | 'end' | 'cancel';

export type PluginSurfaceFeatureDragResult = boolean | {
    readonly mutation: PluginSurfaceRecordMutation;
    readonly editor?: PluginSurfaceEditorRequest;
};

export interface PluginSurfaceFeatureInteraction {
    /** Stable plugin-owned identity for the interactive feature. */
    readonly featureId: string;
    readonly draggable?: boolean;
    /** Current record state used to begin an undoable gesture. */
    readonly record?: Omit<PluginSurfaceRecordMutation, 'historyLabel'>;
    readonly editor?: PluginSurfaceEditorRequest;
}

/** Immutable state for one visible retained surface in the current frame. */
export interface PluginSurfaceFrame {
    /** Stable for this document node while the renderer runtime is alive. */
    readonly surfaceId: string;
    /** Stable public document node id that emitted this retained surface. */
    readonly nodeId: string;
    readonly state: Readonly<Record<string, PluginJson>>;
    readonly cssWidth: number;
    readonly cssHeight: number;
    /**
     * CSS-pixel displacement of this retained viewport's center from the center
     * of the complete surface. Large surfaces may be cropped to the host camera
     * so renderers do not allocate pixels for offscreen content.
     */
    readonly viewportCenter: PluginSurfacePoint;
    /**
     * Realized surface pixels per world unit after host GPU limits and budgeting.
     * Equals `canvasZoom` while the retained target can render at full DPR. A
     * renderer should derive projection scale from this value so subsequent
     * compositor scaling cannot change the surface's logical bounds.
     */
    readonly renderScale: number;
    readonly canvasZoom: number;
    readonly time: number;
}

export interface PluginSurfacePlacementResult {
    readonly mutation: PluginSurfaceRecordMutation;
    readonly selection?: PluginSurfaceFeatureInteraction;
}

export interface PluginSurfacePoint {
    readonly x: number;
    readonly y: number;
}

export interface PluginSurfaceQuery {
    readonly surfaceId: string;
    readonly nodeId: string;
    readonly state: Readonly<Record<string, PluginJson>>;
    /** Surface-local CSS pixels from its top-left corner. */
    readonly point: PluginSurfacePoint;
}

export interface PluginSurfaceQueryResult {
    readonly cursor?: 'default' | 'pointer' | 'grab' | 'crosshair';
    readonly features?: readonly PluginJson[];
    /** Optional short pointer-local status rendered in host chrome. */
    readonly statusText?: string;
    /**
     * Optional host interaction for the topmost feature at the query point.
     * The host treats the feature identity and editor state as opaque plugin
     * data; it only coordinates selection, document writes, history and UI.
     */
    readonly interaction?: PluginSurfaceFeatureInteraction;
}

export interface PluginSurfaceRecordMutation {
    readonly recordId: string;
    readonly value: PluginJson;
    /** Collaborative record owner; omitted for a surface-local record. */
    readonly recordOwnerId?: string;
    /** User-facing undo label owned by the plugin's domain vocabulary. */
    readonly historyLabel: string;
}

/** Host-owned framebuffer and dimensions supplied for one surface render. */
export interface PluginSurfaceRenderTarget {
    readonly framebuffer: WebGLFramebuffer;
    readonly width: number;
    readonly height: number;
    readonly devicePixelRatio: number;
}

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;
    /**
     * Places a retained GPU surface in this node's paint order.
     *
     * The renderer contribution is resolved by id. `state` is copied when the
     * dirty scene chunk is gathered and must contain only bounded JSON data;
     * fetched resources and mutable renderer state belong to the renderer
     * instance, never the document or pack callback.
     */
    surface(rendererId: string, state: Readonly<Record<string, PluginJson>>, x: number, y: number, halfW: number, halfH: number, rotation: number): 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";

/** Endpoint decoration understood by {@link Primitive.Line}. */
export declare const LineMarker: {
    readonly None: 0;
    readonly OpenArrow: 1;
    readonly SolidArrow: 2;
    readonly Cap: 3;
};
export type LineMarker = (typeof LineMarker)[keyof typeof LineMarker];

export declare const Primitive: {
    readonly RoundRect: 0;
    readonly Ellipse: 1;
    readonly None: 2;
    /** Procedural straight line. `cornerRadius` carries `encodeLineMarkers(...)`. */
    readonly Line: 3;
    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;