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

package/README.md

@@ -55,22 +55,68 @@ async function whenEtchReady(timeoutMs = 10_000) {
 const etch = await whenEtchReady();
 ```
 
-### Reading and mutating
+### Reading and mutating blocks
 
 ```ts
 // Read
-const textIds = etch.blocks.find({ type: "text" });
+const textIds = etch.blocks.find({ type: "etch/text" });
 const json = etch.blocks.getJson(textIds[0]);
 
 // Mutate (routes through the same guarded paths as the UI; undo/redo works)
 etch.blocks.setText(textIds[0], "Hello world");
 etch.blocks.addClass(textIds[0], "lead");
 
+// Persist (blocks/styles wait for save; stylesheets/components/fields persist immediately)
+await etch.saveAsync();
+```
+
+### Styles
+
+```ts
+// Create a class or id rule
 const styleId = etch.styles.create(".lead", "font-size: 1.25rem;");
+
+// Find existing styles by selector type
+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
 etch.styles.setVariable("--brand", "#0af");
+etch.styles.getVariable("--brand"); // "#0af"
+```
 
-// Persist (blocks/styles wait for save; stylesheets/components/fields persist immediately)
+> **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.
+
+### Component edit mode
+
+Use `blocks.enterComponentEditMode` to open a component's internal block tree
+for direct inspection or mutation, then save and exit when done:
+
+```ts
+// Find a component block
+const [compId] = etch.blocks.find({ type: "etch/component" });
+
+// Enter edit mode — the component's block tree becomes accessible
+etch.blocks.enterComponentEditMode(compId);
+
+// Inspect or mutate the component's children
+const tree = etch.blocks.getTree();
+
+// Persist the component definition to the backend
+await etch.blocks.saveComponentEditModeAsync();
+
+// Save the page, then exit edit mode
 await etch.saveAsync();
+etch.blocks.exitComponentEditMode();
+```
+
+To discard in-memory changes and restore the original block:
+
+```ts
+etch.blocks.exitComponentEditMode({ revert: true });
 ```
 
 ### Error handling
@@ -142,10 +188,33 @@ etch.blocks.create({
   version: 1,
   context: {},
   children: [],
-  tag: "div",
+  tag: "div", // ✗ type error
 });
 ```
 
+### Special element attributes
+
+Some block types recognise **special attributes** in addition to standard HTML:
+
+**`etch/dynamic-image`** — rendered as `<img>`:
+- `mediaId` — WordPress attachment ID. Etch fetches the media object and uses its URL as `src`, overriding any explicit `src`. Supports dynamic expressions (e.g. `{post.featured_image_id}`).
+- `useSrcSet` — `"true"` to generate a responsive `srcset` from the media (requires `mediaId`).
+- `maximumSize` — WordPress image size slug (e.g. `"large"`, `"full"`) used when resolving the image. Defaults to `"full"`.
+
+```ts
+etch.blocks.setAttribute(imgBlockId, "mediaId", "{post.featured_image_id}");
+etch.blocks.setAttribute(imgBlockId, "useSrcSet", "true");
+```
+
+**`etch/svg`** — inline SVG:
+- `src` — URL of an external `.svg` file. Etch fetches and inlines the SVG at render time. Supports dynamic expressions.
+- `stripColors` — `"true"` to strip `fill` and `stroke` colour declarations from the fetched SVG, so CSS can drive its colours instead.
+
+```ts
+etch.blocks.setAttribute(svgBlockId, "src", "/icons/logo.svg");
+etch.blocks.setAttribute(svgBlockId, "stripColors", "true");
+```
+
 ### Types only
 
 Every contract type is exported and dependency-free, so you can use them
@@ -167,7 +236,15 @@ is imported.
 - `getEtch(options?)` / `isEtchAvailable()` — acquire the API from the page.
 - `EtchApiError` / `isEtchApiError()` / `EtchApiErrorCode` — typed errors.
 - `ETCH_API_VERSION` — the contract version this package targets (`0.x`).
-- The full contract as exported types (`Etch`, `EtchBlocksApi`, `PublicBlockJson`, …).
+- The full contract as exported types:
+  - **Blocks** — `Etch`, `EtchBlocksApi`, `EtchBlockJson`, `PublicBlockJson`, `FindBlocksPredicate`, `BlockPatch`, …
+  - **Styles** — `EtchStylesApi`, `StyleSummary`, `StyleListFilter`, `StyleSelectorType`, `StylePatch`
+  - **Stylesheets** — `EtchStylesheetsApi`, `StylesheetSummary`, `StylesheetInput`, `StylesheetPatch`
+  - **Components** — `EtchComponentsApi`, `PublicComponentSummary`, `PublicComponentJson`, `ComponentPatch`, `ComponentProperty`, …
+  - **Loops** — `EtchLoopsApi`, `EtchLoop`, `EtchLoopConfig`, `BlockLoopBinding`, …
+  - **Navigation** — `EtchNavigationApi`, `NavigationPlace`, `PostSummary`, `TemplateSummary`
+  - **Fields** — `EtchFieldsApi`, `CustomField`, `CustomFieldGroup`, …
+  - **UI / History** — `EtchUiApi`, `EtchHistoryApi`, `ColorScheme`
 
 ## Versioning
 

package/dist/index.d.cts

@@ -1,18 +1,5 @@
 /**
- * The public, dependency-free contract for the Etch builder scripting API.
- *
- * Every type here is self-contained (no imports from the Etch source), so this
- * file can ship as the published `.d.ts` and be the single artifact that is
- * versioned deliberately. It mirrors the runtime exposed on `window.etch`.
- *
- * Method signatures take/return plain serializable values (block ids and JSON),
- * never internal reactive class instances. Loose internal shapes (block JSON,
- * loop query args, custom-field definitions) are modelled as **extensible**
- * objects with an index signature, matching the runtime's permissive parsing.
- *
- * Several string fields use the `'literal' | (string & {})` idiom: the known
- * values appear in autocomplete while any other string is still accepted (for
- * loop parameter expressions, plugin-added values, etc.).
+ * 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}`;
@@ -112,6 +99,16 @@ interface EtchDynamicElementBlockJson extends EtchBlockCommon {
  *
  * The global `styles` applied to the block are **read-only** (see
  * {@link EtchElementBlockJson}).
+ *
+ * **Special attributes** (in addition to standard `<img>` attributes):
+ * - `mediaId` — WordPress attachment post ID. When set, Etch fetches the media
+ *   object and uses its URL as `src`, overriding any explicit `src` attribute.
+ *   Supports dynamic expressions (`{post.featured_image_id}`).
+ * - `useSrcSet` — `"true"` to generate a responsive `srcset` from the media
+ *   (only effective when `mediaId` is set).
+ * - `maximumSize` — maximum WordPress image size slug (e.g. `"large"`,
+ *   `"full"`) used when building `srcset` / resolving the image URL. Defaults
+ *   to `"full"` when omitted.
  */
 interface EtchDynamicImageBlockJson extends EtchBlockCommon {
     type: "etch/dynamic-image";
@@ -123,6 +120,13 @@ interface EtchDynamicImageBlockJson extends EtchBlockCommon {
  *
  * The global `styles` applied to the block are **read-only** (see
  * {@link EtchElementBlockJson}).
+ *
+ * **Special attributes** (in addition to standard SVG attributes):
+ * - `src` — URL of an external `.svg` file. When set, Etch fetches the file and
+ *   inlines its contents at render time. Supports dynamic expressions.
+ * - `stripColors` — `"true"` to strip `fill` and `stroke` colour declarations
+ *   from the fetched SVG so CSS can drive its colours instead. Only effective
+ *   when `src` is set.
  */
 interface EtchSvgBlockJson extends EtchBlockCommon {
     type: "etch/svg";
@@ -307,7 +311,39 @@ interface EtchBlocksApi {
     removeClass(blockId: string, className: string): void;
     /** Whether the block currently has the given CSS class. */
     hasClass(blockId: string, className: string): boolean;
+    /**
+     * Enter component edit (focus) mode on an `etch/component` block. The block
+     * is replaced by a focus wrapper whose children are the component's block
+     * tree, allowing direct inspection and mutation. Throws `WRONG_BLOCK_TYPE`
+     * for non-component blocks and `OPERATION_FAILED` if already in component
+     * edit mode or the component definition is not loaded.
+     */
+    enterComponentEditMode(blockId: string): void;
+    /**
+     * Exit component edit (focus) mode. Does nothing when not in component edit
+     * mode. When `revert` is `true` the original component block is restored and
+     * any in-memory edits to the component definition are discarded; when
+     * omitted (or `false`) the focus wrapper is replaced by the component block
+     * as-is.
+     */
+    exitComponentEditMode(options?: {
+        revert?: boolean;
+    }): void;
+    /** Whether the builder is currently in component edit (focus) mode. */
+    isInComponentEditMode(): boolean;
+    /**
+     * Persist the component currently being edited and save the page. The
+     * builder stays in component edit mode after the call; follow with
+     * `exitComponentEditMode()` when done. Throws `OPERATION_FAILED` when not
+     * in component edit mode.
+     */
+    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.
@@ -500,32 +536,93 @@ interface EtchLoopsApi {
     /** 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.
+ */
+/**
+ * The selector type inferred from a style's selector string.
+ * - `class` — `.my-class`
+ * - `id` — `#my-id`
+ * - `tag` — `div`, `h1`, etc.
+ * - `element` — etch element selector (`:where([data-etch-element="..."])`)
+ * - `attribute` — `[data-foo]`, `[type="submit"]`, etc.
+ * - `custom` — anything else (pseudo-classes, combinators, etc.)
+ */
+type StyleSelectorType = "class" | "id" | "tag" | "element" | "attribute" | "custom";
+/** A style entry as returned by `styles.list()`. */
+interface StyleSummary {
+    /** Stable id of the style rule. */
+    id: string;
+    /** The CSS selector the rule targets. */
+    selector: string;
+    /**
+     * The selector type inferred from the selector string, or `undefined` when
+     * the selector is invalid.
+     */
+    type: StyleSelectorType | undefined;
+    /**
+     * The collection this style belongs to.
+     *
+     * @reserved Collections are an internal implementation detail. Always
+     * `"default"` for styles created via the public API. Do not rely on this
+     * value — it may change without notice.
+     */
+    collection: string;
+    /** The CSS declarations (rule body). */
+    css: string;
+}
+/** Filter accepted by `styles.list()`. All provided fields are AND-matched. */
+interface StyleListFilter {
+    /** Restrict to styles whose inferred selector type matches. */
+    type?: StyleSelectorType;
+    /**
+     * Restrict to styles in this collection.
+     *
+     * @reserved Collections are an internal implementation detail. Omit this
+     * filter — filtering by collection is not supported for external use.
+     */
+    collection?: string;
+}
 /** Patch accepted by `styles.update()`. Omitted fields keep their current value. */
 interface StylePatch {
     /** The CSS selector the rule targets. */
     selector?: string;
     /** The CSS declarations (rule body). */
     css?: string;
-    /** The collection/folder the style belongs to. */
+    /**
+     * @reserved Collections are an internal implementation detail. Do not set
+     * this field — passing a value here has no guaranteed effect.
+     */
     collection?: string;
 }
 /** Global style (CSS) definitions, including `:root` global CSS variables. */
 interface EtchStylesApi {
+    /**
+     * All styles as a flat array, optionally filtered by selector `type`.
+     * Useful for resolving selector names to their ids before passing those ids
+     * to other methods.
+     */
+    list(filter?: StyleListFilter): StyleSummary[];
     /** Create a style rule for `selector`; returns its id. */
-    create(selector: string, css?: string, collection?: string): string;
-    /** Patch a style rule's selector, css, or collection. */
+    create(selector: string, css?: string): string;
+    /** Patch a style rule's selector or css. */
     update(styleId: string, patch: StylePatch): void;
     /** Delete a style rule by id. */
     delete(styleId: string): void;
     /** All global CSS custom properties as a `name -> value` record. */
-    listVariables(collection?: string): Record<string, string>;
+    listVariables(): Record<string, string>;
     /** Read one global CSS custom property, or `undefined` when unset. */
-    getVariable(name: string, collection?: string): string | undefined;
+    getVariable(name: string): string | undefined;
     /** Set a global CSS custom property (e.g. `('--brand', '#0af')`). */
-    setVariable(name: string, value: string, collection?: string): void;
+    setVariable(name: string, value: string): void;
     /** Remove a global CSS custom property. */
-    removeVariable(name: string, collection?: string): void;
+    removeVariable(name: string): void;
 }
+
+/**
+ * Global stylesheet shapes and the `etch.stylesheets` API surface.
+ */
 /** Type of a global stylesheet. */
 type StylesheetType = "default" | "@custom-media";
 /** A global stylesheet entry. */
@@ -581,6 +678,12 @@ interface EtchStylesheetsApi {
     /** Add (or look up) a `@custom-media` definition, e.g. `('--sm', '(max-width: 600px)')`. */
     addCustomMediaAsync(name: string, query: string): Promise<void>;
 }
+
+/**
+ * Reusable-component property model, component JSON shapes, and the
+ * `etch.components` API surface.
+ */
+
 /** Fields shared by every component property. */
 interface ComponentPropertyBase {
     /** Display name of the property. */
@@ -764,7 +867,11 @@ interface PublicComponentSummary {
     id: number;
     /** Display name. */
     name: string;
-    /** Stable key used to reference the component in markup. */
+    /**
+     * Stable key used to reference the component in markup (e.g. `<Card />`).
+     * Always **PascalCase**: starts with an uppercase letter, letters and digits
+     * only (no dashes, underscores, or spaces).
+     */
     key: string;
     /** Optional human-readable description. */
     description?: string;
@@ -780,7 +887,11 @@ interface PublicComponentJson extends PublicComponentSummary {
 interface ComponentPatch {
     /** New display name. */
     name?: string;
-    /** New reference key. */
+    /**
+     * New reference key. It is **converted to PascalCase** before it is stored
+     * (e.g. `my card` → `MyCard`), so the key actually saved may differ from the
+     * string passed here.
+     */
     key?: string;
     /** New description. */
     description?: string;
@@ -807,6 +918,10 @@ interface EtchComponentsApi {
     /** Delete a component by id. */
     deleteAsync(componentId: number): Promise<void>;
 }
+
+/**
+ * Builder navigation shapes and the `etch.navigation` API surface.
+ */
 /**
  * A navigable area of the builder UI:
  * - `builder` — the canvas/editor
@@ -859,6 +974,10 @@ interface EtchNavigationApi {
     /** List available templates. */
     listTemplatesAsync(): Promise<TemplateSummary[]>;
 }
+
+/**
+ * Custom field group/value shapes and the `etch.fields` API surface.
+ */
 /** Custom field type. Open-ended for future field types. */
 type CustomFieldType = "text" | "textarea" | "number" | "boolean" | (string & {});
 /** A custom field definition (extensible). */
@@ -975,6 +1094,10 @@ interface EtchFieldsApi {
     /** Clear one field value on a post. */
     deleteValueAsync(postId: number, fieldKey: string): Promise<void>;
 }
+
+/**
+ * Builder chrome controls (`etch.ui`) and undo/redo (`etch.history`).
+ */
 /** Canvas color scheme. */
 type ColorScheme = "light" | "dark";
 /** Builder app/chrome controls: color scheme, interface visibility, exit. */
@@ -1005,6 +1128,12 @@ interface EtchHistoryApi {
     /** Whether there is a mutation to redo. */
     canRedo(): boolean;
 }
+
+/**
+ * The root {@link Etch} interface exposed on `window.etch`, tying every API
+ * namespace together, plus connection/versioning options.
+ */
+
 /** Options for negotiating an API instance (see the runtime `connect`). */
 interface ConnectOptions {
     /**
@@ -1126,4 +1255,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 StylePatch, 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 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 };

package/dist/index.d.ts

@@ -1,18 +1,5 @@
 /**
- * The public, dependency-free contract for the Etch builder scripting API.
- *
- * Every type here is self-contained (no imports from the Etch source), so this
- * file can ship as the published `.d.ts` and be the single artifact that is
- * versioned deliberately. It mirrors the runtime exposed on `window.etch`.
- *
- * Method signatures take/return plain serializable values (block ids and JSON),
- * never internal reactive class instances. Loose internal shapes (block JSON,
- * loop query args, custom-field definitions) are modelled as **extensible**
- * objects with an index signature, matching the runtime's permissive parsing.
- *
- * Several string fields use the `'literal' | (string & {})` idiom: the known
- * values appear in autocomplete while any other string is still accepted (for
- * loop parameter expressions, plugin-added values, etc.).
+ * 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}`;
@@ -112,6 +99,16 @@ interface EtchDynamicElementBlockJson extends EtchBlockCommon {
  *
  * The global `styles` applied to the block are **read-only** (see
  * {@link EtchElementBlockJson}).
+ *
+ * **Special attributes** (in addition to standard `<img>` attributes):
+ * - `mediaId` — WordPress attachment post ID. When set, Etch fetches the media
+ *   object and uses its URL as `src`, overriding any explicit `src` attribute.
+ *   Supports dynamic expressions (`{post.featured_image_id}`).
+ * - `useSrcSet` — `"true"` to generate a responsive `srcset` from the media
+ *   (only effective when `mediaId` is set).
+ * - `maximumSize` — maximum WordPress image size slug (e.g. `"large"`,
+ *   `"full"`) used when building `srcset` / resolving the image URL. Defaults
+ *   to `"full"` when omitted.
  */
 interface EtchDynamicImageBlockJson extends EtchBlockCommon {
     type: "etch/dynamic-image";
@@ -123,6 +120,13 @@ interface EtchDynamicImageBlockJson extends EtchBlockCommon {
  *
  * The global `styles` applied to the block are **read-only** (see
  * {@link EtchElementBlockJson}).
+ *
+ * **Special attributes** (in addition to standard SVG attributes):
+ * - `src` — URL of an external `.svg` file. When set, Etch fetches the file and
+ *   inlines its contents at render time. Supports dynamic expressions.
+ * - `stripColors` — `"true"` to strip `fill` and `stroke` colour declarations
+ *   from the fetched SVG so CSS can drive its colours instead. Only effective
+ *   when `src` is set.
  */
 interface EtchSvgBlockJson extends EtchBlockCommon {
     type: "etch/svg";
@@ -307,7 +311,39 @@ interface EtchBlocksApi {
     removeClass(blockId: string, className: string): void;
     /** Whether the block currently has the given CSS class. */
     hasClass(blockId: string, className: string): boolean;
+    /**
+     * Enter component edit (focus) mode on an `etch/component` block. The block
+     * is replaced by a focus wrapper whose children are the component's block
+     * tree, allowing direct inspection and mutation. Throws `WRONG_BLOCK_TYPE`
+     * for non-component blocks and `OPERATION_FAILED` if already in component
+     * edit mode or the component definition is not loaded.
+     */
+    enterComponentEditMode(blockId: string): void;
+    /**
+     * Exit component edit (focus) mode. Does nothing when not in component edit
+     * mode. When `revert` is `true` the original component block is restored and
+     * any in-memory edits to the component definition are discarded; when
+     * omitted (or `false`) the focus wrapper is replaced by the component block
+     * as-is.
+     */
+    exitComponentEditMode(options?: {
+        revert?: boolean;
+    }): void;
+    /** Whether the builder is currently in component edit (focus) mode. */
+    isInComponentEditMode(): boolean;
+    /**
+     * Persist the component currently being edited and save the page. The
+     * builder stays in component edit mode after the call; follow with
+     * `exitComponentEditMode()` when done. Throws `OPERATION_FAILED` when not
+     * in component edit mode.
+     */
+    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.
@@ -500,32 +536,93 @@ interface EtchLoopsApi {
     /** 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.
+ */
+/**
+ * The selector type inferred from a style's selector string.
+ * - `class` — `.my-class`
+ * - `id` — `#my-id`
+ * - `tag` — `div`, `h1`, etc.
+ * - `element` — etch element selector (`:where([data-etch-element="..."])`)
+ * - `attribute` — `[data-foo]`, `[type="submit"]`, etc.
+ * - `custom` — anything else (pseudo-classes, combinators, etc.)
+ */
+type StyleSelectorType = "class" | "id" | "tag" | "element" | "attribute" | "custom";
+/** A style entry as returned by `styles.list()`. */
+interface StyleSummary {
+    /** Stable id of the style rule. */
+    id: string;
+    /** The CSS selector the rule targets. */
+    selector: string;
+    /**
+     * The selector type inferred from the selector string, or `undefined` when
+     * the selector is invalid.
+     */
+    type: StyleSelectorType | undefined;
+    /**
+     * The collection this style belongs to.
+     *
+     * @reserved Collections are an internal implementation detail. Always
+     * `"default"` for styles created via the public API. Do not rely on this
+     * value — it may change without notice.
+     */
+    collection: string;
+    /** The CSS declarations (rule body). */
+    css: string;
+}
+/** Filter accepted by `styles.list()`. All provided fields are AND-matched. */
+interface StyleListFilter {
+    /** Restrict to styles whose inferred selector type matches. */
+    type?: StyleSelectorType;
+    /**
+     * Restrict to styles in this collection.
+     *
+     * @reserved Collections are an internal implementation detail. Omit this
+     * filter — filtering by collection is not supported for external use.
+     */
+    collection?: string;
+}
 /** Patch accepted by `styles.update()`. Omitted fields keep their current value. */
 interface StylePatch {
     /** The CSS selector the rule targets. */
     selector?: string;
     /** The CSS declarations (rule body). */
     css?: string;
-    /** The collection/folder the style belongs to. */
+    /**
+     * @reserved Collections are an internal implementation detail. Do not set
+     * this field — passing a value here has no guaranteed effect.
+     */
     collection?: string;
 }
 /** Global style (CSS) definitions, including `:root` global CSS variables. */
 interface EtchStylesApi {
+    /**
+     * All styles as a flat array, optionally filtered by selector `type`.
+     * Useful for resolving selector names to their ids before passing those ids
+     * to other methods.
+     */
+    list(filter?: StyleListFilter): StyleSummary[];
     /** Create a style rule for `selector`; returns its id. */
-    create(selector: string, css?: string, collection?: string): string;
-    /** Patch a style rule's selector, css, or collection. */
+    create(selector: string, css?: string): string;
+    /** Patch a style rule's selector or css. */
     update(styleId: string, patch: StylePatch): void;
     /** Delete a style rule by id. */
     delete(styleId: string): void;
     /** All global CSS custom properties as a `name -> value` record. */
-    listVariables(collection?: string): Record<string, string>;
+    listVariables(): Record<string, string>;
     /** Read one global CSS custom property, or `undefined` when unset. */
-    getVariable(name: string, collection?: string): string | undefined;
+    getVariable(name: string): string | undefined;
     /** Set a global CSS custom property (e.g. `('--brand', '#0af')`). */
-    setVariable(name: string, value: string, collection?: string): void;
+    setVariable(name: string, value: string): void;
     /** Remove a global CSS custom property. */
-    removeVariable(name: string, collection?: string): void;
+    removeVariable(name: string): void;
 }
+
+/**
+ * Global stylesheet shapes and the `etch.stylesheets` API surface.
+ */
 /** Type of a global stylesheet. */
 type StylesheetType = "default" | "@custom-media";
 /** A global stylesheet entry. */
@@ -581,6 +678,12 @@ interface EtchStylesheetsApi {
     /** Add (or look up) a `@custom-media` definition, e.g. `('--sm', '(max-width: 600px)')`. */
     addCustomMediaAsync(name: string, query: string): Promise<void>;
 }
+
+/**
+ * Reusable-component property model, component JSON shapes, and the
+ * `etch.components` API surface.
+ */
+
 /** Fields shared by every component property. */
 interface ComponentPropertyBase {
     /** Display name of the property. */
@@ -764,7 +867,11 @@ interface PublicComponentSummary {
     id: number;
     /** Display name. */
     name: string;
-    /** Stable key used to reference the component in markup. */
+    /**
+     * Stable key used to reference the component in markup (e.g. `<Card />`).
+     * Always **PascalCase**: starts with an uppercase letter, letters and digits
+     * only (no dashes, underscores, or spaces).
+     */
     key: string;
     /** Optional human-readable description. */
     description?: string;
@@ -780,7 +887,11 @@ interface PublicComponentJson extends PublicComponentSummary {
 interface ComponentPatch {
     /** New display name. */
     name?: string;
-    /** New reference key. */
+    /**
+     * New reference key. It is **converted to PascalCase** before it is stored
+     * (e.g. `my card` → `MyCard`), so the key actually saved may differ from the
+     * string passed here.
+     */
     key?: string;
     /** New description. */
     description?: string;
@@ -807,6 +918,10 @@ interface EtchComponentsApi {
     /** Delete a component by id. */
     deleteAsync(componentId: number): Promise<void>;
 }
+
+/**
+ * Builder navigation shapes and the `etch.navigation` API surface.
+ */
 /**
  * A navigable area of the builder UI:
  * - `builder` — the canvas/editor
@@ -859,6 +974,10 @@ interface EtchNavigationApi {
     /** List available templates. */
     listTemplatesAsync(): Promise<TemplateSummary[]>;
 }
+
+/**
+ * Custom field group/value shapes and the `etch.fields` API surface.
+ */
 /** Custom field type. Open-ended for future field types. */
 type CustomFieldType = "text" | "textarea" | "number" | "boolean" | (string & {});
 /** A custom field definition (extensible). */
@@ -975,6 +1094,10 @@ interface EtchFieldsApi {
     /** Clear one field value on a post. */
     deleteValueAsync(postId: number, fieldKey: string): Promise<void>;
 }
+
+/**
+ * Builder chrome controls (`etch.ui`) and undo/redo (`etch.history`).
+ */
 /** Canvas color scheme. */
 type ColorScheme = "light" | "dark";
 /** Builder app/chrome controls: color scheme, interface visibility, exit. */
@@ -1005,6 +1128,12 @@ interface EtchHistoryApi {
     /** Whether there is a mutation to redo. */
     canRedo(): boolean;
 }
+
+/**
+ * The root {@link Etch} interface exposed on `window.etch`, tying every API
+ * namespace together, plus connection/versioning options.
+ */
+
 /** Options for negotiating an API instance (see the runtime `connect`). */
 interface ConnectOptions {
     /**
@@ -1126,4 +1255,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 StylePatch, 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 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 };

package/package.json

@@ -1,43 +1,46 @@
 {
-	"name": "@digital-gravy/etch-public-api",
-	"version": "0.3.1",
-	"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",
-	"main": "./dist/index.cjs",
-	"module": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js",
-			"require": "./dist/index.cjs"
-		}
-	},
-	"files": ["dist", "README.md"],
-	"sideEffects": false,
-	"scripts": {
-		"build": "tsup",
-		"dev": "tsup --watch",
-		"test": "vitest run",
-		"test:watch": "vitest",
-		"typecheck": "tsc --noEmit",
-		"prepublishOnly": "bun run build"
-	},
-	"keywords": [
-		"etch",
-		"etchwp",
-		"wordpress",
-		"builder",
-		"scripting",
-		"api"
-	],
-	"publishConfig": {
-		"access": "public"
-	},
-	"devDependencies": {
-		"tsup": "^8.3.5",
-		"typescript": "^5.7.2",
-		"vitest": "^3.0.5"
-	}
+  "name": "@digital-gravy/etch-public-api",
+  "version": "0.3.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",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "etch",
+    "etchwp",
+    "wordpress",
+    "builder",
+    "scripting",
+    "api"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.5"
+  }
 }