@digital-gravy/etch-public-api 0.7.1 → 0.7.3

package/dist/index.d.cts

@@ -1,6 +1,208 @@
+/**
+ * Loop definitions, WordPress query argument shapes, and the `etch.loops` API
+ * surface.
+ */
+/**
+ * A loop parameter reference, e.g. `$count`. Resolved to a concrete value
+ * before the query runs.
+ */
+type LoopParamRef = `$${string}`;
+/**
+ * A numeric query value, or a loop-parameter expression that resolves to one:
+ * a bare reference (`$count`) or a reference with a numeric fallback
+ * (`$count ?? 10`). Plain numeric strings (e.g. `"10"`) are not accepted —
+ * pass the number itself.
+ */
+type NumericParam = number | LoopParamRef | `$${string} ?? ${number}`;
+/**
+ * A boolean query value, or a loop-parameter expression that resolves to one:
+ * a bare reference (`$sticky`) or a reference with a boolean fallback
+ * (`$sticky ?? false`). WordPress also accepts its integer-boolean convention
+ * (`0`/`1`) for these args.
+ */
+type BooleanParam = boolean | 0 | 1 | LoopParamRef | `$${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?: NumericParam;
+    /** Number of posts to skip. */
+    offset?: NumericParam;
+    /** Page of results to return. */
+    paged?: NumericParam;
+    /** Alias of `paged` used in some contexts. */
+    page?: NumericParam;
+    /** 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?: BooleanParam;
+    /** 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?: NumericParam;
+    /** Number of users to skip. */
+    offset?: NumericParam;
+    /** Page of results to return. */
+    paged?: NumericParam;
+    [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. Every key must be a `$`-prefixed
+     * parameter reference (e.g. `$count`), matching the `$param` expressions
+     * used in the loop's query args.
+     */
+    loopParams?: Record<LoopParamRef, 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;
+}
+
 /**
  * Block JSON shapes (read and write) and the `etch.blocks` API surface.
  */
+
 /** A block type identifier, always namespaced under `etch/` (e.g. `etch/text`). */
 type EtchBlockType = `etch/${string}`;
 /** Editor-facing metadata stored on every block. */
@@ -144,8 +346,11 @@ interface EtchLoopBlockJson extends EtchBlockCommon {
     indexId?: string;
     /** Id of a registered loop definition this block is bound to. */
     loopId?: string;
-    /** Values for the bound loop's parameters. */
-    loopParams?: Record<string, unknown>;
+    /**
+     * Values for the bound loop's parameters. Every key must be a `$`-prefixed
+     * parameter reference (e.g. `$count`).
+     */
+    loopParams?: Record<LoopParamRef, unknown>;
 }
 /** A conditional block (`etch/condition`); renders its children when the expression holds. */
 interface EtchConditionBlockJson extends EtchBlockCommon {
@@ -265,6 +470,50 @@ interface BlockPatch {
     /** Replace the text content. Only valid on text blocks. */
     text?: string;
 }
+/**
+ * A portable, JSON-serializable snapshot of a block subtree produced by
+ * {@link EtchBlocksApi.copy} and consumed by {@link EtchBlocksApi.pasteAsync}.
+ *
+ * Treat it as an **opaque token**: store it, send it over the wire, or hand it
+ * straight back to `pasteAsync()`. The fields below are documented so you can
+ * inspect a payload, but the bundled `styles` / `loops` / `components` /
+ * `customMediaDefinitions` are Etch-internal definitions that `pasteAsync()`
+ * re-creates and re-maps to fresh ids — don't depend on their internal shape or
+ * mutate them.
+ *
+ * Unlike the builder's Cmd-C / Cmd-V shortcuts, `copy()` / `pasteAsync()` never
+ * touch the system clipboard, so they work for fully programmatic flows (no
+ * user gesture or clipboard permission required).
+ */
+interface CopyObject {
+    /** Payload kind. Currently always `"block"`. */
+    type: 'block';
+    /**
+     * Payload schema version, derived from the features the copied block uses.
+     * `paste()` migrates older payloads forward, so pass it back unchanged.
+     */
+    version: number;
+    /** The copied block subtree in Gutenberg block grammar. */
+    gutenbergBlock: GutenbergBlock;
+    /** Global styles referenced by the block, keyed by style id (opaque). */
+    styles?: {
+        [styleId: string]: unknown;
+    };
+    /** Loop definitions referenced by the block, keyed by loop id (opaque). */
+    loops?: {
+        [loopId: string]: unknown;
+    };
+    /** Component definitions referenced by the block, keyed by component id (opaque). */
+    components?: {
+        [componentId: number]: unknown;
+    };
+    /** `@custom-media` definitions referenced by the block's styles (opaque). */
+    customMediaDefinitions?: {
+        [name: string]: unknown;
+    };
+    /** ISO 8601 timestamp of when the copy was produced. */
+    timestamp?: string;
+}
 /** Block selection, reading, structure and property edits. */
 interface EtchBlocksApi {
     /** Select a block in the canvas by id. */
@@ -281,9 +530,13 @@ interface EtchBlocksApi {
     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.
+     * `parentId` defaults to the document root (`null` is treated the same as
+     * omitting it, matching {@link move}), `index` to the end of the parent.
+     *
+     * Throws `WRONG_BLOCK_TYPE` when `parentId` names a block that cannot contain
+     * the new block (e.g. a text or void element).
      */
-    create(json: EtchBlockJson, parentId?: string, index?: number): string;
+    create(json: EtchBlockJson, parentId?: string | null, 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. */
@@ -291,12 +544,44 @@ interface EtchBlocksApi {
     /**
      * Re-parent a block. `newParentId` of `null` moves it to the document root;
      * `index` defaults to the end of the new parent.
+     *
+     * Throws `WRONG_BLOCK_TYPE` when `newParentId` cannot contain the block; the
+     * block is left in its original position.
      */
     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;
+    /**
+     * Serialize a block and its subtree — along with the global styles, loops and
+     * components it references — into a portable {@link CopyObject}. The result is
+     * plain JSON: hold it, persist it, or pass it to {@link pasteAsync}. Unlike the
+     * Cmd-C shortcut this does **not** write to the system clipboard. Throws
+     * `BLOCK_NOT_FOUND` for an unknown id.
+     */
+    copy(blockId: string): CopyObject;
+    /**
+     * Insert a block previously produced by {@link copy}. Any styles, loops and
+     * components it carries are re-created and re-mapped to fresh ids. Resolves to
+     * the id of the newly inserted block. Throws `INVALID_ARGUMENT` for a
+     * malformed payload and `BLOCK_NOT_FOUND` for an unknown `targetId`.
+     *
+     * Placement (mirrors {@link create}):
+     * - **No `targetId`** (omitted or `null`) — appended to the document root, or
+     *   inserted there at `index` when given.
+     * - **`targetId` + `index`** — inserted as a child of the target at `index`.
+     *   Throws `WRONG_BLOCK_TYPE` when the target cannot contain the block: an
+     *   explicit `index` is a deliberate "place it here as a child" request, so
+     *   an impossible target is an error rather than a silent miss.
+     * - **`targetId`, no `index`** — inserted into the target when it accepts
+     *   children, otherwise immediately after it (handy for "paste near this
+     *   block").
+     *
+     * `index` is clamped to the valid range; a negative `index` counts from the
+     * end (`-1` appends).
+     */
+    pasteAsync(payload: CopyObject, targetId?: string | null, index?: number): Promise<string>;
     /** Set the text content of a text block. */
     setText(blockId: string, text: string): void;
     /** Rename a block (sets its label / display name). */
@@ -357,203 +642,6 @@ interface EtchBlocksApi {
     saveComponentEditModeAsync(): Promise<void>;
 }
 
-/**
- * Loop definitions, WordPress query argument shapes, and the `etch.loops` API
- * surface.
- */
-/**
- * A loop parameter reference, e.g. `$count`. Resolved to a concrete value
- * before the query runs.
- */
-type LoopParamRef = `$${string}`;
-/**
- * A numeric query value, or a loop-parameter expression that resolves to one:
- * a bare reference (`$count`) or a reference with a numeric fallback
- * (`$count ?? 10`). Plain numeric strings (e.g. `"10"`) are not accepted —
- * pass the number itself.
- */
-type NumericParam = number | LoopParamRef | `$${string} ?? ${number}`;
-/**
- * A boolean query value, or a loop-parameter expression that resolves to one:
- * a bare reference (`$sticky`) or a reference with a boolean fallback
- * (`$sticky ?? false`). WordPress also accepts its integer-boolean convention
- * (`0`/`1`) for these args.
- */
-type BooleanParam = boolean | 0 | 1 | LoopParamRef | `$${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?: NumericParam;
-    /** Number of posts to skip. */
-    offset?: NumericParam;
-    /** Page of results to return. */
-    paged?: NumericParam;
-    /** Alias of `paged` used in some contexts. */
-    page?: NumericParam;
-    /** 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?: BooleanParam;
-    /** 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?: NumericParam;
-    /** Number of users to skip. */
-    offset?: NumericParam;
-    /** Page of results to return. */
-    paged?: NumericParam;
-    [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;
-}
-
 /**
  * Global style (CSS rule) shapes and the `etch.styles` API surface.
  */
@@ -1352,4 +1440,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
  */
 declare const ETCH_API_VERSION = "0.x";
 
-export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, 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 EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };
+export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };

package/dist/index.d.ts

@@ -1,6 +1,208 @@
+/**
+ * Loop definitions, WordPress query argument shapes, and the `etch.loops` API
+ * surface.
+ */
+/**
+ * A loop parameter reference, e.g. `$count`. Resolved to a concrete value
+ * before the query runs.
+ */
+type LoopParamRef = `$${string}`;
+/**
+ * A numeric query value, or a loop-parameter expression that resolves to one:
+ * a bare reference (`$count`) or a reference with a numeric fallback
+ * (`$count ?? 10`). Plain numeric strings (e.g. `"10"`) are not accepted —
+ * pass the number itself.
+ */
+type NumericParam = number | LoopParamRef | `$${string} ?? ${number}`;
+/**
+ * A boolean query value, or a loop-parameter expression that resolves to one:
+ * a bare reference (`$sticky`) or a reference with a boolean fallback
+ * (`$sticky ?? false`). WordPress also accepts its integer-boolean convention
+ * (`0`/`1`) for these args.
+ */
+type BooleanParam = boolean | 0 | 1 | LoopParamRef | `$${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?: NumericParam;
+    /** Number of posts to skip. */
+    offset?: NumericParam;
+    /** Page of results to return. */
+    paged?: NumericParam;
+    /** Alias of `paged` used in some contexts. */
+    page?: NumericParam;
+    /** 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?: BooleanParam;
+    /** 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?: NumericParam;
+    /** Number of users to skip. */
+    offset?: NumericParam;
+    /** Page of results to return. */
+    paged?: NumericParam;
+    [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. Every key must be a `$`-prefixed
+     * parameter reference (e.g. `$count`), matching the `$param` expressions
+     * used in the loop's query args.
+     */
+    loopParams?: Record<LoopParamRef, 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;
+}
+
 /**
  * Block JSON shapes (read and write) and the `etch.blocks` API surface.
  */
+
 /** A block type identifier, always namespaced under `etch/` (e.g. `etch/text`). */
 type EtchBlockType = `etch/${string}`;
 /** Editor-facing metadata stored on every block. */
@@ -144,8 +346,11 @@ interface EtchLoopBlockJson extends EtchBlockCommon {
     indexId?: string;
     /** Id of a registered loop definition this block is bound to. */
     loopId?: string;
-    /** Values for the bound loop's parameters. */
-    loopParams?: Record<string, unknown>;
+    /**
+     * Values for the bound loop's parameters. Every key must be a `$`-prefixed
+     * parameter reference (e.g. `$count`).
+     */
+    loopParams?: Record<LoopParamRef, unknown>;
 }
 /** A conditional block (`etch/condition`); renders its children when the expression holds. */
 interface EtchConditionBlockJson extends EtchBlockCommon {
@@ -265,6 +470,50 @@ interface BlockPatch {
     /** Replace the text content. Only valid on text blocks. */
     text?: string;
 }
+/**
+ * A portable, JSON-serializable snapshot of a block subtree produced by
+ * {@link EtchBlocksApi.copy} and consumed by {@link EtchBlocksApi.pasteAsync}.
+ *
+ * Treat it as an **opaque token**: store it, send it over the wire, or hand it
+ * straight back to `pasteAsync()`. The fields below are documented so you can
+ * inspect a payload, but the bundled `styles` / `loops` / `components` /
+ * `customMediaDefinitions` are Etch-internal definitions that `pasteAsync()`
+ * re-creates and re-maps to fresh ids — don't depend on their internal shape or
+ * mutate them.
+ *
+ * Unlike the builder's Cmd-C / Cmd-V shortcuts, `copy()` / `pasteAsync()` never
+ * touch the system clipboard, so they work for fully programmatic flows (no
+ * user gesture or clipboard permission required).
+ */
+interface CopyObject {
+    /** Payload kind. Currently always `"block"`. */
+    type: 'block';
+    /**
+     * Payload schema version, derived from the features the copied block uses.
+     * `paste()` migrates older payloads forward, so pass it back unchanged.
+     */
+    version: number;
+    /** The copied block subtree in Gutenberg block grammar. */
+    gutenbergBlock: GutenbergBlock;
+    /** Global styles referenced by the block, keyed by style id (opaque). */
+    styles?: {
+        [styleId: string]: unknown;
+    };
+    /** Loop definitions referenced by the block, keyed by loop id (opaque). */
+    loops?: {
+        [loopId: string]: unknown;
+    };
+    /** Component definitions referenced by the block, keyed by component id (opaque). */
+    components?: {
+        [componentId: number]: unknown;
+    };
+    /** `@custom-media` definitions referenced by the block's styles (opaque). */
+    customMediaDefinitions?: {
+        [name: string]: unknown;
+    };
+    /** ISO 8601 timestamp of when the copy was produced. */
+    timestamp?: string;
+}
 /** Block selection, reading, structure and property edits. */
 interface EtchBlocksApi {
     /** Select a block in the canvas by id. */
@@ -281,9 +530,13 @@ interface EtchBlocksApi {
     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.
+     * `parentId` defaults to the document root (`null` is treated the same as
+     * omitting it, matching {@link move}), `index` to the end of the parent.
+     *
+     * Throws `WRONG_BLOCK_TYPE` when `parentId` names a block that cannot contain
+     * the new block (e.g. a text or void element).
      */
-    create(json: EtchBlockJson, parentId?: string, index?: number): string;
+    create(json: EtchBlockJson, parentId?: string | null, 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. */
@@ -291,12 +544,44 @@ interface EtchBlocksApi {
     /**
      * Re-parent a block. `newParentId` of `null` moves it to the document root;
      * `index` defaults to the end of the new parent.
+     *
+     * Throws `WRONG_BLOCK_TYPE` when `newParentId` cannot contain the block; the
+     * block is left in its original position.
      */
     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;
+    /**
+     * Serialize a block and its subtree — along with the global styles, loops and
+     * components it references — into a portable {@link CopyObject}. The result is
+     * plain JSON: hold it, persist it, or pass it to {@link pasteAsync}. Unlike the
+     * Cmd-C shortcut this does **not** write to the system clipboard. Throws
+     * `BLOCK_NOT_FOUND` for an unknown id.
+     */
+    copy(blockId: string): CopyObject;
+    /**
+     * Insert a block previously produced by {@link copy}. Any styles, loops and
+     * components it carries are re-created and re-mapped to fresh ids. Resolves to
+     * the id of the newly inserted block. Throws `INVALID_ARGUMENT` for a
+     * malformed payload and `BLOCK_NOT_FOUND` for an unknown `targetId`.
+     *
+     * Placement (mirrors {@link create}):
+     * - **No `targetId`** (omitted or `null`) — appended to the document root, or
+     *   inserted there at `index` when given.
+     * - **`targetId` + `index`** — inserted as a child of the target at `index`.
+     *   Throws `WRONG_BLOCK_TYPE` when the target cannot contain the block: an
+     *   explicit `index` is a deliberate "place it here as a child" request, so
+     *   an impossible target is an error rather than a silent miss.
+     * - **`targetId`, no `index`** — inserted into the target when it accepts
+     *   children, otherwise immediately after it (handy for "paste near this
+     *   block").
+     *
+     * `index` is clamped to the valid range; a negative `index` counts from the
+     * end (`-1` appends).
+     */
+    pasteAsync(payload: CopyObject, targetId?: string | null, index?: number): Promise<string>;
     /** Set the text content of a text block. */
     setText(blockId: string, text: string): void;
     /** Rename a block (sets its label / display name). */
@@ -357,203 +642,6 @@ interface EtchBlocksApi {
     saveComponentEditModeAsync(): Promise<void>;
 }
 
-/**
- * Loop definitions, WordPress query argument shapes, and the `etch.loops` API
- * surface.
- */
-/**
- * A loop parameter reference, e.g. `$count`. Resolved to a concrete value
- * before the query runs.
- */
-type LoopParamRef = `$${string}`;
-/**
- * A numeric query value, or a loop-parameter expression that resolves to one:
- * a bare reference (`$count`) or a reference with a numeric fallback
- * (`$count ?? 10`). Plain numeric strings (e.g. `"10"`) are not accepted —
- * pass the number itself.
- */
-type NumericParam = number | LoopParamRef | `$${string} ?? ${number}`;
-/**
- * A boolean query value, or a loop-parameter expression that resolves to one:
- * a bare reference (`$sticky`) or a reference with a boolean fallback
- * (`$sticky ?? false`). WordPress also accepts its integer-boolean convention
- * (`0`/`1`) for these args.
- */
-type BooleanParam = boolean | 0 | 1 | LoopParamRef | `$${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?: NumericParam;
-    /** Number of posts to skip. */
-    offset?: NumericParam;
-    /** Page of results to return. */
-    paged?: NumericParam;
-    /** Alias of `paged` used in some contexts. */
-    page?: NumericParam;
-    /** 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?: BooleanParam;
-    /** 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?: NumericParam;
-    /** Number of users to skip. */
-    offset?: NumericParam;
-    /** Page of results to return. */
-    paged?: NumericParam;
-    [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;
-}
-
 /**
  * Global style (CSS rule) shapes and the `etch.styles` API surface.
  */
@@ -1352,4 +1440,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
  */
 declare const ETCH_API_VERSION = "0.x";
 
-export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, 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 EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };
+export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchRawHtmlBlockJson, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type GutenbergBlock, type LoopParamRef, type MetaQueryItem, type NavigationPlace, type NumberComponentProperty, type NumericParam, type ObjectComponentProperty, type PostCustomFieldGroupEntry, type PostCustomFieldValueEntry, type PostCustomFieldValueResponse, type PostCustomFieldValuesResponse, type PostSummary, type PublicBlockJson, type PublicComponentJson, type PublicComponentSummary, type RepeaterComponentProperty, type ResolvedCustomField, type SelectOptionsString, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@digital-gravy/etch-public-api",
-	"version": "0.7.1",
+	"version": "0.7.3",
 	"description": "MIT-licensed typed client and contract for the Etch builder scripting API (window.etch). Etch itself is a separate proprietary product governed by its own commercial terms.",
 	"license": "MIT",
 	"repository": {