@digital-gravy/etch-public-api 0.3.4 → 0.7.0

package/README.md

@@ -128,6 +128,33 @@ To discard in-memory changes and restore the original block:
 etch.blocks.exitComponentEditMode({ revert: true });
 ```
 
+### Component props
+
+A component **instance** exposes its bound props as block attributes — set them
+with `setAttribute` / `update`, read them with `getAttribute`. Unlike an HTML
+block's free-form attributes, a component's props are a **closed schema**: the
+key must be a property declared by the component definition, or the call throws
+`INVALID_ARGUMENT`.
+
+```ts
+const [cardId] = etch.blocks.find({ type: "etch/component" });
+
+// Set a prop the component declares
+etch.blocks.setAttribute(cardId, "title", "Hello world");
+
+// Read it back
+etch.blocks.getAttribute(cardId, "title"); // "Hello world"
+
+// Or patch several props at once
+etch.blocks.update(cardId, { attributes: { title: "Hi", variant: "primary" } });
+
+// An undeclared key is rejected
+etch.blocks.setAttribute(cardId, "notAProp", "x"); // ✗ throws INVALID_ARGUMENT
+```
+
+> Values are stored as-is. For typed props such as classes or repeater/group
+> data, pass the value in the component's internal format.
+
 ### Error handling
 
 Methods throw a typed `EtchApiError` with a `code`, rather than returning

package/dist/index.d.cts

@@ -256,8 +256,10 @@ interface BlockPatch {
     /** 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.
+     * Merge attributes — a key set to `undefined` removes that attribute. Valid
+     * on HTML blocks (free-form HTML attributes) and on component instances,
+     * whose attributes are their bound props — a closed schema, so each key must
+     * be a property declared by the component (an unknown key is rejected).
      */
     attributes?: Record<string, string | undefined>;
     /** Replace the text content. Only valid on text blocks. */
@@ -299,11 +301,26 @@ interface EtchBlocksApi {
     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. */
+    /**
+     * Read an attribute, or `undefined` when it is not set. Works on HTML blocks
+     * (HTML attributes) and component instances (bound prop values). Throws
+     * `WRONG_BLOCK_TYPE` for a block that has no attributes (e.g. a text block).
+     */
     getAttribute(blockId: string, key: string): string | undefined;
-    /** Set an HTML attribute; omit `value` for a valueless (boolean) attribute. */
+    /**
+     * Set an attribute; omit `value` for a valueless (boolean) attribute. Works
+     * on HTML blocks and component instances. On a component, `key` must be a
+     * declared property — props are a closed schema — otherwise
+     * `INVALID_ARGUMENT` is thrown (or `OPERATION_FAILED` if the component
+     * definition has not loaded yet). Throws `WRONG_BLOCK_TYPE` for a block with
+     * no attributes.
+     */
     setAttribute(blockId: string, key: string, value?: string): void;
-    /** Remove an HTML attribute. */
+    /**
+     * Remove an attribute. Works on HTML blocks and component instances. On a
+     * component, `key` must be a declared property (see {@link setAttribute}).
+     * Throws `WRONG_BLOCK_TYPE` for a block with no attributes.
+     */
     removeAttribute(blockId: string, key: string): void;
     /** Add a CSS class to the block. */
     addClass(blockId: string, className: string): void;
@@ -1141,6 +1158,59 @@ interface EtchHistoryApi {
     canRedo(): boolean;
 }
 
+/**
+ * Live bridge connection — lets an external tool (an IDE, a script runner, an AI
+ * agent) drive this Etch instance from outside the page over a WebSocket.
+ *
+ * Calling `window.etch.connectAs(name)` from the builder console opens a
+ * connection to a local bridge server and registers this instance under `name`.
+ * Because the name travels to the server, one server can hold connections to
+ * several Etch tabs at once and address each by name. The server then pushes JS
+ * to evaluate in the page; the page streams console output and the return value
+ * back.
+ *
+ * This is the inverse of Chrome remote debugging: the browser dials out to the
+ * tool, instead of the tool attaching to the browser's debug port. Console-run
+ * code is exempt from the page's CSP, so the connection works even on
+ * locked-down pages.
+ */
+/** Options for {@link Etch.connectAs} / `etch.connectAs`. */
+interface BridgeConnectOptions {
+    /**
+     * Full WebSocket endpoint of the bridge server. Defaults to
+     * `ws://127.0.0.1:7331`. Set this to target a different host/port or a
+     * `wss://` endpoint.
+     */
+    url?: string;
+    /**
+     * Shorthand for a localhost endpoint on a custom port
+     * (`ws://127.0.0.1:<port>`). Ignored when {@link url} is provided.
+     */
+    port?: number;
+    /**
+     * Extra identifying metadata sent to the server alongside the name (e.g. a
+     * project id or environment label), so the tool can group or disambiguate
+     * tabs beyond the name alone.
+     */
+    meta?: Record<string, unknown>;
+    /**
+     * Reconnect automatically (with backoff) when the socket drops. Default
+     * `true`.
+     */
+    reconnect?: boolean;
+}
+/** Handle to a live bridge connection returned by `etch.connectAs`. */
+interface EtchBridgeConnection {
+    /** The name this instance registered under — how the tool addresses it. */
+    readonly name: string;
+    /** The resolved WebSocket endpoint the connection targets. */
+    readonly url: string;
+    /** Whether the socket is currently open. */
+    readonly connected: boolean;
+    /** Close the connection and stop reconnecting. */
+    close(): void;
+}
+
 /**
  * The root {@link Etch} interface exposed on `window.etch`, tying every API
  * namespace together, plus connection/versioning options.
@@ -1189,6 +1259,21 @@ interface Etch {
     history: EtchHistoryApi;
     /** Persist everything (blocks, loops, styles, UI). */
     saveAsync(): Promise<void>;
+    /**
+     * Open a live bridge connection to a local tooling server (an IDE, a script
+     * runner, an AI agent) and register this instance under `name`, so one server
+     * can drive several Etch tabs at once and tell them apart by name. Returns a
+     * handle; call again with a different name/endpoint to open more connections.
+     *
+     * @example
+     * ```js
+     * // In the builder console:
+     * const conn = etch.connectAs('homepage');
+     * // …the tool can now evaluate code in this tab; later:
+     * conn.close();
+     * ```
+     */
+    connectAs(name: string, options?: BridgeConnectOptions): EtchBridgeConnection;
     /**
      * Negotiate a version-pinned API instance. **Reserved** — not implemented by
      * `0.x` runtimes. When present on a future stable runtime, it returns an
@@ -1267,4 +1352,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 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 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 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

@@ -256,8 +256,10 @@ interface BlockPatch {
     /** 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.
+     * Merge attributes — a key set to `undefined` removes that attribute. Valid
+     * on HTML blocks (free-form HTML attributes) and on component instances,
+     * whose attributes are their bound props — a closed schema, so each key must
+     * be a property declared by the component (an unknown key is rejected).
      */
     attributes?: Record<string, string | undefined>;
     /** Replace the text content. Only valid on text blocks. */
@@ -299,11 +301,26 @@ interface EtchBlocksApi {
     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. */
+    /**
+     * Read an attribute, or `undefined` when it is not set. Works on HTML blocks
+     * (HTML attributes) and component instances (bound prop values). Throws
+     * `WRONG_BLOCK_TYPE` for a block that has no attributes (e.g. a text block).
+     */
     getAttribute(blockId: string, key: string): string | undefined;
-    /** Set an HTML attribute; omit `value` for a valueless (boolean) attribute. */
+    /**
+     * Set an attribute; omit `value` for a valueless (boolean) attribute. Works
+     * on HTML blocks and component instances. On a component, `key` must be a
+     * declared property — props are a closed schema — otherwise
+     * `INVALID_ARGUMENT` is thrown (or `OPERATION_FAILED` if the component
+     * definition has not loaded yet). Throws `WRONG_BLOCK_TYPE` for a block with
+     * no attributes.
+     */
     setAttribute(blockId: string, key: string, value?: string): void;
-    /** Remove an HTML attribute. */
+    /**
+     * Remove an attribute. Works on HTML blocks and component instances. On a
+     * component, `key` must be a declared property (see {@link setAttribute}).
+     * Throws `WRONG_BLOCK_TYPE` for a block with no attributes.
+     */
     removeAttribute(blockId: string, key: string): void;
     /** Add a CSS class to the block. */
     addClass(blockId: string, className: string): void;
@@ -1141,6 +1158,59 @@ interface EtchHistoryApi {
     canRedo(): boolean;
 }
 
+/**
+ * Live bridge connection — lets an external tool (an IDE, a script runner, an AI
+ * agent) drive this Etch instance from outside the page over a WebSocket.
+ *
+ * Calling `window.etch.connectAs(name)` from the builder console opens a
+ * connection to a local bridge server and registers this instance under `name`.
+ * Because the name travels to the server, one server can hold connections to
+ * several Etch tabs at once and address each by name. The server then pushes JS
+ * to evaluate in the page; the page streams console output and the return value
+ * back.
+ *
+ * This is the inverse of Chrome remote debugging: the browser dials out to the
+ * tool, instead of the tool attaching to the browser's debug port. Console-run
+ * code is exempt from the page's CSP, so the connection works even on
+ * locked-down pages.
+ */
+/** Options for {@link Etch.connectAs} / `etch.connectAs`. */
+interface BridgeConnectOptions {
+    /**
+     * Full WebSocket endpoint of the bridge server. Defaults to
+     * `ws://127.0.0.1:7331`. Set this to target a different host/port or a
+     * `wss://` endpoint.
+     */
+    url?: string;
+    /**
+     * Shorthand for a localhost endpoint on a custom port
+     * (`ws://127.0.0.1:<port>`). Ignored when {@link url} is provided.
+     */
+    port?: number;
+    /**
+     * Extra identifying metadata sent to the server alongside the name (e.g. a
+     * project id or environment label), so the tool can group or disambiguate
+     * tabs beyond the name alone.
+     */
+    meta?: Record<string, unknown>;
+    /**
+     * Reconnect automatically (with backoff) when the socket drops. Default
+     * `true`.
+     */
+    reconnect?: boolean;
+}
+/** Handle to a live bridge connection returned by `etch.connectAs`. */
+interface EtchBridgeConnection {
+    /** The name this instance registered under — how the tool addresses it. */
+    readonly name: string;
+    /** The resolved WebSocket endpoint the connection targets. */
+    readonly url: string;
+    /** Whether the socket is currently open. */
+    readonly connected: boolean;
+    /** Close the connection and stop reconnecting. */
+    close(): void;
+}
+
 /**
  * The root {@link Etch} interface exposed on `window.etch`, tying every API
  * namespace together, plus connection/versioning options.
@@ -1189,6 +1259,21 @@ interface Etch {
     history: EtchHistoryApi;
     /** Persist everything (blocks, loops, styles, UI). */
     saveAsync(): Promise<void>;
+    /**
+     * Open a live bridge connection to a local tooling server (an IDE, a script
+     * runner, an AI agent) and register this instance under `name`, so one server
+     * can drive several Etch tabs at once and tell them apart by name. Returns a
+     * handle; call again with a different name/endpoint to open more connections.
+     *
+     * @example
+     * ```js
+     * // In the builder console:
+     * const conn = etch.connectAs('homepage');
+     * // …the tool can now evaluate code in this tab; later:
+     * conn.close();
+     * ```
+     */
+    connectAs(name: string, options?: BridgeConnectOptions): EtchBridgeConnection;
     /**
      * Negotiate a version-pinned API instance. **Reserved** — not implemented by
      * `0.x` runtimes. When present on a future stable runtime, it returns an
@@ -1267,4 +1352,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 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 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 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.3.4",
+  "version": "0.7.0",
   "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",
   "type": "module",
@@ -43,4 +43,4 @@
     "typescript": "^5.7.2",
     "vitest": "^3.0.5"
   }
-}
+}