@digital-gravy/etch-public-api 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,884 @@
+/**
+ * The public, dependency-free contract for the Etch builder scripting API.
+ *
+ * Every type here is self-contained (no imports from the Etch source), so this
+ * file can ship as the published `.d.ts` and be the single artifact that is
+ * versioned deliberately. It mirrors the runtime exposed on `window.etch`.
+ *
+ * Method signatures take/return plain serializable values (block ids and JSON),
+ * never internal reactive class instances. Loose internal shapes (block JSON,
+ * loop query args, custom-field definitions) are modelled as **extensible**
+ * objects with an index signature, matching the runtime's permissive parsing.
+ *
+ * Several string fields use the `'literal' | (string & {})` idiom: the known
+ * values appear in autocomplete while any other string is still accepted (for
+ * loop parameter expressions, plugin-added values, etc.).
+ */
+/** A block type identifier, always namespaced under `etch/` (e.g. `etch/text`). */
+type EtchBlockType = `etch/${string}`;
+/** Editor-facing metadata stored on every block. */
+interface EtchBlockContext {
+    /** The block's display label in the structure panel. */
+    name?: string;
+    /**
+     * Whether the block is expanded or collapsed in the builder's structure
+     * panel. This is editor UI state, not document data — most scripts can
+     * ignore it.
+     */
+    structureState?: "open" | "closed";
+    /** Whether the block is hidden (not rendered) on the canvas. */
+    hidden?: boolean;
+}
+/** Inline script attached to a block. */
+interface EtchBlockScript {
+    /** The JavaScript source associated with the block. */
+    code: string;
+}
+/**
+ * Block-type-specific options. The set of keys depends on the block type (e.g.
+ * a video block carries `youtubeUrl`, an image block `srcUrl`), so this is an
+ * open bag rather than a fixed shape.
+ */
+interface EtchBlockOptions {
+    [key: string]: unknown;
+}
+/**
+ * A block as plain, structured-clone-safe JSON — the shape accepted by
+ * `blocks.create()` / `blocks.replace()`. Concrete block types add their own
+ * fields, so the shape is intentionally extensible.
+ */
+interface EtchBlockJson {
+    /** The block type, e.g. `etch/text` or `etch/div`. */
+    type: EtchBlockType;
+    /** Schema version of this block type. */
+    version: number;
+    /** Editor-facing metadata (label, hidden, structure state). */
+    context: EtchBlockContext;
+    /** Optional inline script attached to the block. */
+    script?: EtchBlockScript;
+    /** Optional block-type-specific options. */
+    options?: EtchBlockOptions;
+    /** Child blocks, each itself an `EtchBlockJson`. */
+    children: EtchBlockJson[];
+    /** Block-type-specific fields beyond the common ones above. */
+    [key: string]: unknown;
+}
+/**
+ * A block serialized for reading: {@link EtchBlockJson} plus its `id` and
+ * `parentId` (`null` at the document root). `id`/`parentId` are attached
+ * recursively, so every node in `children` is itself a `PublicBlockJson`.
+ */
+interface PublicBlockJson {
+    /** Stable id of this block. */
+    id: string;
+    /** Id of the parent block, or `null` when the block sits at the document root. */
+    parentId: string | null;
+    /** The block type, e.g. `etch/text` or `etch/div`. */
+    type: EtchBlockType;
+    /** Schema version of this block type. */
+    version: number;
+    /** Editor-facing metadata (label, hidden, structure state). */
+    context: EtchBlockContext;
+    /** Optional inline script attached to the block. */
+    script?: EtchBlockScript;
+    /** Optional block-type-specific options. */
+    options?: EtchBlockOptions;
+    /** Child blocks, each itself a `PublicBlockJson` with its own id/parentId. */
+    children: PublicBlockJson[];
+    /** Block-type-specific fields beyond the common ones above. */
+    [key: string]: unknown;
+}
+/** Predicate accepted by `blocks.find()`. All provided fields must match (AND). */
+interface FindBlocksPredicate {
+    /** Match blocks of this exact type (e.g. `etch/text`). */
+    type?: string;
+    /** Match blocks carrying this CSS class. */
+    class?: string;
+    /** Match blocks that have this HTML attribute set. */
+    attribute?: string;
+}
+/**
+ * Patch accepted by `blocks.update()`. Only the provided fields are changed; the
+ * block keeps its id and children.
+ */
+interface BlockPatch {
+    /** Rename the block (its structure-panel label). */
+    name?: string;
+    /** Hide or show the block on the canvas. */
+    hidden?: boolean;
+    /**
+     * Merge HTML attributes — a key set to `undefined` removes that attribute.
+     * Only valid on HTML blocks.
+     */
+    attributes?: Record<string, string | undefined>;
+    /** Replace the text content. Only valid on text blocks. */
+    text?: string;
+}
+/** Block selection, reading, structure and property edits. */
+interface EtchBlocksApi {
+    /** Select a block in the canvas by id. */
+    select(blockId: string): void;
+    /** Clear the current selection. */
+    deselect(): void;
+    /** Id of the currently selected block, or `null` when nothing is selected. */
+    getSelectedId(): string | null;
+    /** The block (and its subtree) as serializable JSON, with `id`/`parentId` attached. */
+    getJson(blockId: string): PublicBlockJson;
+    /** The whole document as a forest of top-level blocks with nested children. */
+    getTree(): PublicBlockJson[];
+    /** Ids of every block matching the predicate (all provided fields AND-matched). */
+    find(predicate: FindBlocksPredicate): string[];
+    /**
+     * Build a block from JSON and insert it; returns the new block id.
+     * `parentId` defaults to the document root, `index` to the end of the parent.
+     */
+    create(json: EtchBlockJson, parentId?: string, index?: number): string;
+    /** Remove a block and its entire subtree. */
+    delete(blockId: string): void;
+    /** Deep-copy a block next to the original; returns the new block's id. */
+    duplicate(blockId: string): string;
+    /**
+     * Re-parent a block. `newParentId` of `null` moves it to the document root;
+     * `index` defaults to the end of the new parent.
+     */
+    move(blockId: string, newParentId: string | null, index?: number): void;
+    /** Replace a block with a new one built from JSON; returns the new block id. */
+    replace(blockId: string, json: EtchBlockJson): string;
+    /** Patch a block's common editable properties in place (keeps id/children). */
+    update(blockId: string, patch: BlockPatch): void;
+    /** Set the text content of a text block. */
+    setText(blockId: string, text: string): void;
+    /** Rename a block (sets its label / display name). */
+    rename(blockId: string, name: string): void;
+    /** Read an HTML attribute, or `undefined` when it is not set. */
+    getAttribute(blockId: string, key: string): string | undefined;
+    /** Set an HTML attribute; omit `value` for a valueless (boolean) attribute. */
+    setAttribute(blockId: string, key: string, value?: string): void;
+    /** Remove an HTML attribute. */
+    removeAttribute(blockId: string, key: string): void;
+    /** Add a CSS class to the block. */
+    addClass(blockId: string, className: string): void;
+    /** Remove a CSS class from the block. */
+    removeClass(blockId: string, className: string): void;
+    /** Whether the block currently has the given CSS class. */
+    hasClass(blockId: string, className: string): boolean;
+}
+/**
+ * A `WP_Query` meta-query clause. Extensible — additional keys are allowed.
+ * @see https://developer.wordpress.org/reference/classes/wp_query/#custom-field-post-meta-parameters
+ */
+interface MetaQueryItem {
+    /** The custom field (meta) key to compare. */
+    key: string;
+    /** The value(s) to compare against. */
+    value: string | number | Array<string | number>;
+    /** Comparison operator (defaults to `=`). */
+    compare?: "=" | "!=" | ">" | ">=" | "<" | "<=" | "LIKE" | "NOT LIKE" | "IN" | "NOT IN" | "BETWEEN" | "NOT BETWEEN" | "EXISTS" | "NOT EXISTS";
+    /** SQL type the value is cast to before comparison. */
+    type?: "NUMERIC" | "BINARY" | "CHAR" | "DATE" | "DATETIME" | "DECIMAL" | "SIGNED" | "TIME" | "UNSIGNED";
+    [key: string]: unknown;
+}
+/**
+ * A `WP_Query` taxonomy-query clause. Extensible — additional keys are allowed.
+ * @see https://developer.wordpress.org/reference/classes/wp_query/#taxonomy-parameters
+ */
+interface TaxQueryItem {
+    /** The taxonomy to query (e.g. `category`, `post_tag`). */
+    taxonomy: string;
+    /** Which term field `terms` refers to. */
+    field: "term_id" | "slug" | "name";
+    /** The term(s) to match. */
+    terms: string | number | Array<string | number>;
+    /** How to match the terms (defaults to `IN`). */
+    operator?: "IN" | "NOT IN" | "AND";
+    /** Whether to include child terms of a hierarchical taxonomy. */
+    include_children?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * WordPress query arguments. Values may be static or a loop parameter
+ * expression (`"$param"` or `"$param ?? fallback"`). Extensible — any
+ * additional `WP_Query` argument is allowed.
+ */
+interface WpQueryArgs {
+    /** Post type(s) to query. */
+    post_type?: string | string[];
+    /** Number of posts per page (`-1` for all). */
+    posts_per_page?: number | string;
+    /** Number of posts to skip. */
+    offset?: number | string;
+    /** Page of results to return. */
+    paged?: number | string;
+    /** Alias of `paged` used in some contexts. */
+    page?: number | string;
+    /** Field to order results by. */
+    orderby?: "date" | "title" | "menu_order" | "rand" | "ID" | "author" | "name" | "modified" | "parent" | "comment_count" | (string & {});
+    /** Sort direction. */
+    order?: "ASC" | "DESC" | (string & {});
+    /** Post status to include. */
+    post_status?: "publish" | "pending" | "draft" | "auto-draft" | "future" | "private" | "inherit" | "trash" | (string & {});
+    /** Whether to ignore sticky posts. */
+    ignore_sticky_posts?: boolean | 0 | 1 | (string & {});
+    /** Author id (number) or username (string). */
+    author?: number | string;
+    /** Author by `user_nicename`. */
+    author_name?: string;
+    /** Category id (number) or slug (string). */
+    category?: number | string;
+    /** Category by slug. */
+    category_name?: string;
+    /** Tag slug. */
+    tag?: string;
+    /** Taxonomy query clauses. */
+    tax_query?: TaxQueryItem[];
+    /** Meta (custom field) query clauses. */
+    meta_query?: MetaQueryItem[];
+    /** Search keyword. */
+    s?: string;
+    [key: string]: unknown;
+}
+/** WordPress taxonomy-term query arguments (extensible). */
+interface WpTermsArgs {
+    /** Taxonomy to fetch terms from. */
+    taxonomy?: string;
+    /** Field to order terms by. */
+    orderby?: "name" | "slug" | "term_group" | "term_id" | "description" | "count" | (string & {});
+    /** Sort direction. */
+    order?: "ASC" | "DESC" | (string & {});
+    [key: string]: unknown;
+}
+/** WordPress user query arguments (extensible). */
+interface WpUsersArgs {
+    /** Role(s) users must have. */
+    role?: string | string[];
+    /** User ids to include. */
+    include?: number[] | string;
+    /** User ids to exclude. */
+    exclude?: number[] | string;
+    /** Search keyword. */
+    search?: string;
+    /** Columns the `search` keyword is matched against. */
+    search_columns?: string[] | string;
+    /** Field to order users by. */
+    orderby?: "ID" | "display_name" | "name" | "user_login" | "user_email" | "user_registered" | "post_count" | "meta_value" | "meta_value_num" | (string & {});
+    /** Sort direction. */
+    order?: "ASC" | "DESC" | (string & {});
+    /** Number of users to return. */
+    number?: number | string;
+    /** Number of users to skip. */
+    offset?: number | string;
+    /** Page of results to return. */
+    paged?: number | string;
+    [key: string]: unknown;
+}
+/** Type-specific configuration of an {@link EtchLoop}, discriminated by `type`. */
+type EtchLoopConfig = {
+    type: "wp-query";
+    args: WpQueryArgs;
+} | {
+    type: "wp-terms";
+    args: WpTermsArgs;
+} | {
+    type: "wp-users";
+    args: WpUsersArgs;
+} | {
+    type: "main-query";
+    args: WpQueryArgs;
+} | {
+    type: "json";
+    data: unknown[];
+};
+/** A loop definition (extensible). */
+interface EtchLoop {
+    /** Stable, human-authored key used to reference the loop. */
+    key: string;
+    /** Display name shown in the loop manager. */
+    name: string;
+    /** Whether the loop is global (reusable across pages) or local to a document. */
+    global: boolean;
+    /** The loop's data source and arguments. */
+    config: EtchLoopConfig;
+    [key: string]: unknown;
+}
+/** All loops keyed by id. */
+type EtchLoopObj = Record<string, EtchLoop>;
+/** Partial loop binding applied to an `etch/loop` block by `loops.setForBlock()`. */
+interface BlockLoopBinding {
+    /** Id of the loop to bind. */
+    loopId?: string;
+    /** What the block iterates over (e.g. the loop's items). */
+    target?: string;
+    /** Variable name bound to the current item inside the loop. */
+    itemId?: string;
+    /** Variable name bound to the current index inside the loop. */
+    indexId?: string;
+    /** Values for the loop's parameters (used by `$param` expressions). */
+    loopParams?: Record<string, unknown>;
+}
+/** Loop definitions and binding loops to blocks. */
+interface EtchLoopsApi {
+    /** All loops keyed by id. */
+    getAll(): EtchLoopObj;
+    /** Add a new loop; returns its generated id. */
+    add(loop: EtchLoop): string;
+    /** Replace an existing loop's definition. */
+    update(loopId: string, loop: EtchLoop): void;
+    /** Delete a loop by id. */
+    delete(loopId: string): void;
+    /**
+     * Fuzzy-search loops by `name` or `key`, ranked best-first. Each hit is the
+     * loop plus its `id` (the value `setForBlock`/`update`/`delete` expect).
+     * Returns an empty array for a blank query or when nothing matches.
+     */
+    findLoop(query: string): (EtchLoop & {
+        id: string;
+    })[];
+    /** Bind (or update the binding of) a loop on an `etch/loop` block. */
+    setForBlock(blockId: string, loop: BlockLoopBinding): void;
+}
+/** Patch accepted by `styles.update()`. Omitted fields keep their current value. */
+interface StylePatch {
+    /** The CSS selector the rule targets. */
+    selector?: string;
+    /** The CSS declarations (rule body). */
+    css?: string;
+    /** The collection/folder the style belongs to. */
+    collection?: string;
+}
+/** Global style (CSS) definitions, including `:root` global CSS variables. */
+interface EtchStylesApi {
+    /** Create a style rule for `selector`; returns its id. */
+    create(selector: string, css?: string, collection?: string): string;
+    /** Patch a style rule's selector, css, or collection. */
+    update(styleId: string, patch: StylePatch): void;
+    /** Delete a style rule by id. */
+    delete(styleId: string): void;
+    /** All global CSS custom properties as a `name -> value` record. */
+    listVariables(collection?: string): Record<string, string>;
+    /** Read one global CSS custom property, or `undefined` when unset. */
+    getVariable(name: string, collection?: string): string | undefined;
+    /** Set a global CSS custom property (e.g. `('--brand', '#0af')`). */
+    setVariable(name: string, value: string, collection?: string): void;
+    /** Remove a global CSS custom property. */
+    removeVariable(name: string, collection?: string): void;
+}
+/** Type of a global stylesheet. */
+type StylesheetType = "default" | "@custom-media";
+/** A global stylesheet entry. */
+interface StylesheetSummary {
+    /** Stable id of the stylesheet. */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** The full CSS contents. */
+    css: string;
+    /** Whether this is a regular stylesheet or a `@custom-media` definition set. */
+    type: StylesheetType;
+}
+/** Input for `stylesheets.create()`. */
+interface StylesheetInput {
+    /** Display name. */
+    name: string;
+    /** Initial CSS contents. */
+    css: string;
+    /** Stylesheet type (defaults to `default`). */
+    type?: StylesheetType;
+}
+/** Patch for `stylesheets.update()`. Omitted fields keep their current value. */
+interface StylesheetPatch {
+    /** New display name. */
+    name?: string;
+    /** Replacement CSS contents. */
+    css?: string;
+    /** New stylesheet type. */
+    type?: StylesheetType;
+}
+/**
+ * Global stylesheets and `@custom-media` definitions.
+ *
+ * Note: every method persists to the backend immediately (they do not wait for
+ * {@link Etch.saveAsync}).
+ */
+interface EtchStylesheetsApi {
+    /** All global stylesheets as plain summaries. */
+    list(): StylesheetSummary[];
+    /** One stylesheet by id. */
+    get(stylesheetId: string): StylesheetSummary;
+    /** Create a stylesheet; resolves to its new id. */
+    createAsync(input: StylesheetInput): Promise<string>;
+    /** Patch a stylesheet's name, css, or type. */
+    updateAsync(stylesheetId: string, patch: StylesheetPatch): Promise<void>;
+    /** Append CSS to a stylesheet (a newline is inserted before it). */
+    appendAsync(stylesheetId: string, css: string): Promise<void>;
+    /** Delete a stylesheet by id. */
+    deleteAsync(stylesheetId: string): Promise<void>;
+    /** All `@custom-media` definitions as a `name -> query` record. */
+    listCustomMedia(): Record<string, string>;
+    /** Add (or look up) a `@custom-media` definition, e.g. `('--sm', '(max-width: 600px)')`. */
+    addCustomMediaAsync(name: string, query: string): Promise<void>;
+}
+/** Fields shared by every component property. */
+interface ComponentPropertyBase {
+    /** Display name of the property. */
+    name: string;
+    /** Stable key used to reference the property in markup. */
+    key: string;
+    /** Optional human-readable description. */
+    description?: string;
+}
+/** A string property, optionally specialized (color picker, image, select, …). */
+interface StringComponentProperty {
+    type: {
+        primitive: "string";
+        specialized?: "color" | "url" | "image" | "select" | "array" | "wpMediaId";
+    };
+    /** Default value. */
+    default?: string;
+    /** Allowed values when `specialized` is `select`. */
+    options?: string[];
+}
+/** A numeric property. */
+interface NumberComponentProperty {
+    type: {
+        primitive: "number";
+    };
+    /** Default value. */
+    default?: number;
+    /** Allowed values, when constrained to a set. */
+    options?: number[];
+}
+/** A boolean property. */
+interface BooleanComponentProperty {
+    type: {
+        primitive: "boolean";
+    };
+    /** Default value (a string is allowed for expression-driven defaults). */
+    default?: boolean | string;
+}
+/** An object property carrying structured data. */
+interface ObjectComponentProperty {
+    type: {
+        primitive: "object";
+        specialized?: string;
+    };
+    /** Default value. */
+    default?: Record<string, unknown> | unknown[];
+}
+/** An array property carrying a list of values. */
+interface ArrayComponentProperty {
+    type: {
+        primitive: "array";
+        specialized?: string;
+    };
+    /** Default value. */
+    default?: unknown[];
+}
+/** A property holding a list of CSS class names. */
+interface ClassComponentProperty {
+    type: {
+        primitive: "array";
+        specialized: "class";
+    };
+    /** Default value. */
+    default?: string[];
+}
+/** A group of nested properties (no default of its own). */
+interface GroupComponentProperty {
+    type: {
+        primitive: "object";
+        specialized: "group";
+    };
+    /** The nested properties in this group. */
+    properties: ComponentProperty[];
+}
+/** A repeatable group of nested properties (no default of its own). */
+interface RepeaterComponentProperty {
+    type: {
+        primitive: "array";
+        specialized: "repeater";
+    };
+    /** The nested properties repeated per row. */
+    properties: ComponentProperty[];
+}
+/** A conditional group gated by an expression. */
+interface ConditionComponentProperty {
+    type: {
+        primitive: "string";
+        specialized: "condition";
+    };
+    /** The nested properties shown when the condition holds. */
+    properties: ComponentProperty[];
+    /** The condition expression. */
+    default?: string;
+}
+/** A single configurable property of a component. */
+type ComponentProperty = ComponentPropertyBase & (StringComponentProperty | NumberComponentProperty | BooleanComponentProperty | ObjectComponentProperty | ArrayComponentProperty | ClassComponentProperty | GroupComponentProperty | RepeaterComponentProperty | ConditionComponentProperty);
+/** Component metadata without its block tree (returned by `components.list()`). */
+interface PublicComponentSummary {
+    /** Numeric id of the component. */
+    id: number;
+    /** Display name. */
+    name: string;
+    /** Stable key used to reference the component in markup. */
+    key: string;
+    /** Optional human-readable description. */
+    description?: string;
+    /** The component's configurable properties. */
+    properties: ComponentProperty[];
+}
+/** Full component definition including its block tree as serializable JSON. */
+interface PublicComponentJson extends PublicComponentSummary {
+    /** The component's block tree as serializable JSON. */
+    blocks: PublicBlockJson[];
+}
+/** Patch accepted by `components.update()`. Omitted fields keep their current value. */
+interface ComponentPatch {
+    /** New display name. */
+    name?: string;
+    /** New reference key. */
+    key?: string;
+    /** New description. */
+    description?: string;
+    /** Replacement set of configurable properties. */
+    properties?: ComponentProperty[];
+    /** Replacement block tree as JSON. */
+    blocks?: EtchBlockJson[];
+}
+/**
+ * Reusable Etch component definitions.
+ *
+ * Note: `createAsync`/`updateAsync`/`deleteAsync` persist to the backend immediately (they do
+ * not wait for {@link Etch.saveAsync}).
+ */
+interface EtchComponentsApi {
+    /** All components as summaries (without their block trees). */
+    list(): PublicComponentSummary[];
+    /** One component including its block tree, by id. */
+    getJson(componentId: number): PublicComponentJson;
+    /** Create an empty component with the given name; resolves to its new id. */
+    createAsync(name: string): Promise<number>;
+    /** Patch a component's metadata, properties, or block tree. */
+    updateAsync(componentId: number, patch: ComponentPatch): Promise<void>;
+    /** Delete a component by id. */
+    deleteAsync(componentId: number): Promise<void>;
+}
+/**
+ * A navigable area of the builder UI:
+ * - `builder` — the canvas/editor
+ * - `templates` — the template switcher
+ * - `content-hub` — the pages/posts browser
+ * - `style-manager` — the global style manager
+ * - `loop-manager` — the loop manager
+ */
+type NavigationPlace = "builder" | "templates" | "style-manager" | "content-hub" | "loop-manager";
+/** Lightweight post entry returned by `navigation.listPostsAsync()`. */
+interface PostSummary {
+    /** Post id. */
+    id: number;
+    /** Post title. */
+    title: string;
+    /** URL slug. */
+    slug: string;
+    /** Post status (e.g. `publish`, `draft`). */
+    status: string;
+    /** Post type (e.g. `page`, `post`, or a custom type). */
+    postType: string;
+}
+/** Lightweight template entry returned by `navigation.listTemplatesAsync()`. */
+interface TemplateSummary {
+    /** Template id. */
+    id: number;
+    /** Template title. */
+    title: string;
+    /** Template slug. */
+    slug: string;
+}
+/** Switching the active post/template and navigating between builder UI areas. */
+interface EtchNavigationApi {
+    /** Navigate to a builder UI area (e.g. the loop manager). */
+    goTo(place: NavigationPlace): void;
+    /** The currently active builder UI area. */
+    getCurrentPlace(): NavigationPlace;
+    /** All builder UI areas that `goTo` accepts. */
+    getPlaces(): NavigationPlace[];
+    /** Switch the canvas to a post (page/post/CPT) by id, returning to the builder view. */
+    openPostAsync(postId: number): Promise<void>;
+    /** Switch the canvas to a template by id, returning to the builder view. */
+    openTemplateAsync(templateId: number): Promise<void>;
+    /** Id of the post/template currently open in the canvas (`null` if none). */
+    getActivePostId(): number | null;
+    /** Whether the canvas is currently editing a template. */
+    isEditingTemplate(): boolean;
+    /** List available posts, optionally filtered to one post type. */
+    listPostsAsync(postType?: string): Promise<PostSummary[]>;
+    /** List available templates. */
+    listTemplatesAsync(): Promise<TemplateSummary[]>;
+}
+/** Custom field type. Open-ended for future field types. */
+type CustomFieldType = "text" | "textarea" | "number" | "boolean" | (string & {});
+/** A custom field definition (extensible). */
+interface CustomField {
+    /** Display label. */
+    label: string;
+    /** Stable key used to read/write the field's value. */
+    key: string;
+    /** The field's data type. */
+    type: CustomFieldType;
+    /** Optional help text. */
+    description?: string;
+    /** Whether a value is required. */
+    required?: boolean;
+    [key: string]: unknown;
+}
+/** Where a custom field group is assigned. */
+type CustomFieldAssignment = {
+    post_types: string[];
+    op: "isIn" | "isNotIn";
+} | {
+    post_ids: number[];
+    op: "isIn" | "isNotIn";
+} | {
+    taxonomies: string[];
+    op: "isIn" | "isNotIn";
+};
+/** A custom field group definition (extensible). */
+interface CustomFieldGroup {
+    /** Display label of the group. */
+    label: string;
+    /** Optional description. */
+    description?: string;
+    /** The fields in this group. */
+    fields: CustomField[];
+    /** Which posts/taxonomies this group is assigned to. */
+    assigned_to: CustomFieldAssignment;
+    [key: string]: unknown;
+}
+/** A resolved field returned by the single field-value endpoints. */
+interface ResolvedCustomField {
+    /** The field's key. */
+    key: string;
+    /** The field's label. */
+    label: string;
+    /** The field's data type. */
+    type: CustomFieldType;
+    /** The resolved value; varies per field type, `null` when unset. */
+    value: unknown;
+}
+/** Response from `fields.getValueAsync()` — the resolved field plus its group/post. */
+interface PostCustomFieldValueResponse {
+    /** Id of the post the value belongs to. */
+    post_id: number;
+    /** Id of the group the field was resolved from. */
+    group_id: string;
+    /** The resolved field and its value. */
+    field: ResolvedCustomField;
+}
+/** Per-field entry inside a bulk field-values response (keyed by field key). */
+interface PostCustomFieldValueEntry {
+    /** The field's label. */
+    label: string;
+    /** The field's data type. */
+    type: CustomFieldType;
+    /** The resolved value; varies per field type, `null` when unset. */
+    value: unknown;
+}
+/** Per-group entry inside a bulk field-values response. */
+interface PostCustomFieldGroupEntry {
+    /** The group's label. */
+    label: string;
+    /** The group's resolved field values, keyed by field key. */
+    fields: Record<string, PostCustomFieldValueEntry>;
+}
+/** Response from `fields.getValuesAsync()` — every group assigned to the post. */
+interface PostCustomFieldValuesResponse {
+    /** Id of the post. */
+    post_id: number;
+    /** Every assigned group with its resolved field values, keyed by group id. */
+    groups: Record<string, PostCustomFieldGroupEntry>;
+}
+/**
+ * Custom field groups, their fields, and per-post field values.
+ *
+ * Note: every method persists to the backend immediately (they do not wait for
+ * {@link Etch.saveAsync}).
+ */
+interface EtchFieldsApi {
+    /** All custom field groups, keyed by group id. */
+    listGroupsAsync(): Promise<Record<string, CustomFieldGroup>>;
+    /** One custom field group by id. */
+    getGroupAsync(groupId: string): Promise<CustomFieldGroup>;
+    /** Create a custom field group; resolves to its new id. */
+    createGroupAsync(definition: CustomFieldGroup): Promise<string>;
+    /** Replace a custom field group's definition. */
+    updateGroupAsync(groupId: string, definition: CustomFieldGroup): Promise<void>;
+    /** Delete a custom field group by id. */
+    deleteGroupAsync(groupId: string): Promise<void>;
+    /** Add a field to a group. */
+    addFieldAsync(groupId: string, field: CustomField): Promise<void>;
+    /** Replace a field within a group. */
+    updateFieldAsync(groupId: string, fieldKey: string, field: CustomField): Promise<void>;
+    /** Remove a field from a group. */
+    removeFieldAsync(groupId: string, fieldKey: string): Promise<void>;
+    /** All resolved field values for a post, grouped. */
+    getValuesAsync(postId: number): Promise<PostCustomFieldValuesResponse>;
+    /** One resolved field value for a post. */
+    getValueAsync(postId: number, fieldKey: string): Promise<PostCustomFieldValueResponse>;
+    /** Set one field value on a post; resolves to the updated resolved field. */
+    setValueAsync(postId: number, fieldKey: string, value: unknown): Promise<PostCustomFieldValueResponse>;
+    /** Set several field values on a post at once. */
+    setValuesAsync(postId: number, values: Record<string, unknown>): Promise<void>;
+    /** Clear one field value on a post. */
+    deleteValueAsync(postId: number, fieldKey: string): Promise<void>;
+}
+/** Canvas color scheme. */
+type ColorScheme = "light" | "dark";
+/** Builder app/chrome controls: color scheme, interface visibility, exit. */
+interface EtchUiApi {
+    /** The current canvas color scheme. */
+    getColorScheme(): ColorScheme;
+    /** Set the canvas color scheme (persisted locally, per active page). */
+    setColorScheme(scheme: ColorScheme): void;
+    /** Toggle between light and dark canvas color schemes. */
+    toggleColorScheme(): void;
+    /** Whether the builder chrome (panels/toolbars) is currently hidden. */
+    isInterfaceHidden(): boolean;
+    /** Show or hide the builder chrome. */
+    setInterfaceHidden(hidden: boolean): void;
+    /** Toggle the builder chrome visibility. */
+    toggleInterface(): void;
+    /** Leave the builder and return to the WordPress admin dashboard. */
+    exitToWordPress(): void;
+}
+/** Undo/redo of builder mutations. */
+interface EtchHistoryApi {
+    /** Undo the last builder mutation. */
+    undo(): void;
+    /** Redo the last undone mutation. */
+    redo(): void;
+    /** Whether there is a mutation to undo. */
+    canUndo(): boolean;
+    /** Whether there is a mutation to redo. */
+    canRedo(): boolean;
+}
+/** Options for negotiating an API instance (see the runtime `connect`). */
+interface ConnectOptions {
+    /**
+     * The contract version this consumer targets, e.g. `"^1.0"`. Reserved for
+     * the stable (`1.x`) runtime; ignored by `0.x` runtimes that have no
+     * `connect()`.
+     */
+    apiVersion?: string;
+    /** A stable identifier for the calling plugin (for telemetry / guards). */
+    id?: string;
+}
+/**
+ * Public, scriptable builder API exposed on `window.etch`.
+ *
+ * Intended for AI assistants and third-party plugins. Every method takes/returns
+ * plain serializable values (block ids and JSON), never internal reactive class
+ * instances. Mutations route through the same guarded paths the UI uses, so
+ * `readonly` checks, child-acceptance rules and undo/redo history all keep
+ * working.
+ *
+ * Methods throw `EtchApiError` (with a `code`) on failure.
+ */
+interface Etch {
+    /** Block selection, reading, structure and property edits. */
+    blocks: EtchBlocksApi;
+    /** Loop definitions and binding loops to blocks. */
+    loops: EtchLoopsApi;
+    /** Global style (CSS) definitions and CSS variables. */
+    styles: EtchStylesApi;
+    /** Global stylesheets and `@custom-media` definitions. */
+    stylesheets: EtchStylesheetsApi;
+    /** Reusable component definitions. */
+    components: EtchComponentsApi;
+    /** Switching the active post/template and navigating the builder UI. */
+    navigation: EtchNavigationApi;
+    /** Custom field groups, fields, and per-post values. */
+    fields: EtchFieldsApi;
+    /** Builder chrome controls (color scheme, interface visibility, exit). */
+    ui: EtchUiApi;
+    /** Undo/redo of builder mutations. */
+    history: EtchHistoryApi;
+    /** Persist everything (blocks, loops, styles, UI). */
+    saveAsync(): Promise<void>;
+    /**
+     * Negotiate a version-pinned API instance. **Reserved** — not implemented by
+     * `0.x` runtimes. When present on a future stable runtime, it returns an
+     * adapter pinned to the requested {@link ConnectOptions.apiVersion}.
+     */
+    connect?(options?: ConnectOptions): Etch;
+    /**
+     * Version of the scripting contract exposed on `window.etch`, independent of
+     * the product {@link Etch.version}. `0.x` while experimental. Prefer feature
+     * detection over comparing this value.
+     */
+    readonly apiVersion: string;
+    /** The Etch builder (product) version, for capability checks. */
+    readonly version: string;
+}
+
+declare global {
+    interface Window {
+        /** The Etch scripting API, present once the builder has loaded. */
+        etch?: Etch;
+    }
+}
+/**
+ * Whether the Etch scripting API is present on the page. Use this to guard code
+ * that should no-op when not running inside the builder.
+ */
+declare function isEtchAvailable(): boolean;
+/**
+ * Acquire the Etch scripting API from the page.
+ *
+ * The runtime lives on `window.etch` (injected by the builder); this returns it
+ * typed. When the page exposes a future stable runtime with a native
+ * `connect()`, version negotiation is delegated to it. On today's `0.x`
+ * runtime, the global is returned directly after a best-effort version check.
+ *
+ * @throws {EtchApiError} `NOT_AVAILABLE` when the builder is not present.
+ *
+ * @example
+ * ```ts
+ * import { getEtch } from '@etchwp/public-api';
+ *
+ * const etch = getEtch();
+ * const ids = etch.blocks.find({ type: 'text' });
+ * etch.blocks.setText(ids[0], 'Hello');
+ * await etch.saveAsync();
+ * ```
+ */
+declare function getEtch(options?: ConnectOptions): Etch;
+
+/**
+ * Error codes thrown by the public `window.etch` API.
+ *
+ * The API throws typed errors (rather than returning sentinels) so that AI
+ * assistants and plugin authors can `try`/`catch` and react to a precise cause.
+ *
+ * The union ends with `(string & {})` so that codes added by newer Etch
+ * runtimes still type-check as `EtchApiErrorCode` while keeping autocomplete for
+ * the known values.
+ */
+type EtchApiErrorCode = 'BLOCK_NOT_FOUND' | 'WRONG_BLOCK_TYPE' | 'READONLY' | 'INVALID_ARGUMENT' | 'LOOP_NOT_FOUND' | 'STYLE_NOT_FOUND' | 'STYLESHEET_NOT_FOUND' | 'COMPONENT_NOT_FOUND' | 'POST_NOT_FOUND' | 'OPERATION_FAILED' | 'NOT_AVAILABLE' | (string & {});
+/** Error thrown by the public Etch API (and by this client). */
+declare class EtchApiError extends Error {
+    readonly code: EtchApiErrorCode;
+    constructor(code: EtchApiErrorCode, message: string);
+}
+/** Narrow an unknown caught value to an {@link EtchApiError}. */
+declare function isEtchApiError(value: unknown): value is EtchApiError;
+
+/**
+ * Version of the Etch scripting **contract** this package targets, independent
+ * of the Etch product version and of this package's own npm version.
+ *
+ * `0.x` signals the surface is **experimental** and may change without a major
+ * bump until it stabilizes. It matches the value returned by the runtime's
+ * {@link Etch.apiVersion} getter on `window.etch`.
+ */
+declare const ETCH_API_VERSION = "0.x";
+
+export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, EtchApiError, type EtchApiErrorCode, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlocksApi, type EtchComponentsApi, type EtchFieldsApi, type EtchHistoryApi, type EtchLoop, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchStylesApi, type EtchStylesheetsApi, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type StringComponentProperty, type StylePatch, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };