@digital-gravy/etch-public-api 0.3.3 → 0.6.0

package/README.md

@@ -81,14 +81,23 @@ const classStyles = etch.styles.list({ type: "class" });
 const myStyle = etch.styles.list().find((s) => s.selector === ".lead");
 console.log(myStyle?.id); // the id you pass to blocks.addClass etc.
 
-// Global CSS custom properties
+// Global CSS custom properties (default collection)
 etch.styles.setVariable("--brand", "#0af");
 etch.styles.getVariable("--brand"); // "#0af"
+
+// Variable methods accept an optional collection for multi-collection :root setups
+etch.styles.setVariable("--brand", "#0af", "theme-a");
+etch.styles.getVariable("--brand", "theme-a"); // "#0af"
+etch.styles.listVariables("theme-a");
+etch.styles.removeVariable("--brand", "theme-a");
 ```
 
-> **Note:** The `collection` field on style objects is an internal implementation
-> detail. Always omit the `collection` argument — the default collection is the
-> only one supported via the public API.
+> **Note:** The `collection` field on style **objects** (`StyleSummary`) and the
+> `collection` argument on `create` / `update` are internal implementation
+> details — always omit them for regular styles. The four `:root` variable
+> methods (`listVariables`, `getVariable`, `setVariable`, `removeVariable`) are
+> the exception: they accept an optional `collection` parameter, defaulting to
+> `"default"` when omitted.
 
 ### Component edit mode
 

package/dist/index.d.cts

@@ -610,14 +610,26 @@ interface EtchStylesApi {
     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(): Record<string, string>;
-    /** Read one global CSS custom property, or `undefined` when unset. */
-    getVariable(name: string): string | undefined;
-    /** Set a global CSS custom property (e.g. `('--brand', '#0af')`). */
-    setVariable(name: string, value: string): void;
-    /** Remove a global CSS custom property. */
-    removeVariable(name: string): void;
+    /**
+     * All global CSS custom properties as a `name -> value` record.
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    listVariables(collection?: string): Record<string, string>;
+    /**
+     * Read one global CSS custom property, or `undefined` when unset.
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    getVariable(name: string, collection?: string): string | undefined;
+    /**
+     * Set a global CSS custom property (e.g. `('--brand', '#0af')`).
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    setVariable(name: string, value: string, collection?: string): void;
+    /**
+     * Remove a global CSS custom property.
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    removeVariable(name: string, collection?: string): void;
 }
 
 /**
@@ -1129,6 +1141,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.
@@ -1177,6 +1242,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
@@ -1255,4 +1335,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

@@ -610,14 +610,26 @@ interface EtchStylesApi {
     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(): Record<string, string>;
-    /** Read one global CSS custom property, or `undefined` when unset. */
-    getVariable(name: string): string | undefined;
-    /** Set a global CSS custom property (e.g. `('--brand', '#0af')`). */
-    setVariable(name: string, value: string): void;
-    /** Remove a global CSS custom property. */
-    removeVariable(name: string): void;
+    /**
+     * All global CSS custom properties as a `name -> value` record.
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    listVariables(collection?: string): Record<string, string>;
+    /**
+     * Read one global CSS custom property, or `undefined` when unset.
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    getVariable(name: string, collection?: string): string | undefined;
+    /**
+     * Set a global CSS custom property (e.g. `('--brand', '#0af')`).
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    setVariable(name: string, value: string, collection?: string): void;
+    /**
+     * Remove a global CSS custom property.
+     * @param collection - The `:root` style collection. Defaults to `"default"`.
+     */
+    removeVariable(name: string, collection?: string): void;
 }
 
 /**
@@ -1129,6 +1141,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.
@@ -1177,6 +1242,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
@@ -1255,4 +1335,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.3",
+  "version": "0.6.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",