@digital-gravy/etch-public-api 0.1.1 → 0.3.0

package/README.md

@@ -19,26 +19,55 @@ npm install @digital-gravy/etch-public-api
 
 ## Usage
 
+### Getting the API object
+
+The Etch builder injects the runtime onto `window.etch` during its bootstrap.
+Acquire it with `getEtch()`, guarded by `isEtchAvailable()` for code that might
+run outside the builder:
+
 ```ts
-import { getEtch, isEtchAvailable, EtchApiError } from '@digital-gravy/etch-public-api';
+import { getEtch, isEtchAvailable } from "@digital-gravy/etch-public-api";
 
-if (!isEtchAvailable()) {
-	// Not running inside the Etch builder (or it hasn't finished loading).
-	return;
+function run() {
+  if (!isEtchAvailable()) return; // not running inside the Etch builder
+  const etch = getEtch();
+  const textIds = etch.blocks.find({ type: "text" });
+  etch.blocks.setText(textIds[0], "Hello world");
 }
+```
 
-const etch = getEtch();
+`getEtch()` throws an `EtchApiError` with code `NOT_AVAILABLE` when the builder
+isn't on the page, so you can also `try`/`catch` it. If your script may run
+before the builder has finished loading, wait until it appears:
+
+```ts
+import { getEtch, isEtchAvailable } from "@digital-gravy/etch-public-api";
+
+async function whenEtchReady(timeoutMs = 10_000) {
+  const start = Date.now();
+  while (!isEtchAvailable()) {
+    if (Date.now() - start > timeoutMs) throw new Error("Etch did not load");
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return getEtch();
+}
 
+const etch = await whenEtchReady();
+```
+
+### Reading and mutating
+
+```ts
 // Read
-const textIds = etch.blocks.find({ type: 'text' });
+const textIds = etch.blocks.find({ type: "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');
+etch.blocks.setText(textIds[0], "Hello world");
+etch.blocks.addClass(textIds[0], "lead");
 
-const styleId = etch.styles.create('.lead', 'font-size: 1.25rem;');
-etch.styles.setVariable('--brand', '#0af');
+const styleId = etch.styles.create(".lead", "font-size: 1.25rem;");
+etch.styles.setVariable("--brand", "#0af");
 
 // Persist (blocks/styles wait for save; stylesheets/components/fields persist immediately)
 await etch.saveAsync();
@@ -50,26 +79,71 @@ Methods throw a typed `EtchApiError` with a `code`, rather than returning
 sentinels:
 
 ```ts
-import { isEtchApiError } from '@digital-gravy/etch-public-api';
+import { isEtchApiError } from "@digital-gravy/etch-public-api";
 
 try {
-	etch.blocks.getJson('does-not-exist');
+  etch.blocks.getJson("does-not-exist");
 } catch (err) {
-	if (isEtchApiError(err)) {
-		console.warn(err.code, err.message); // e.g. "BLOCK_NOT_FOUND"
-	}
+  if (isEtchApiError(err)) {
+    console.warn(err.code, err.message); // e.g. "BLOCK_NOT_FOUND"
+  }
 }
 ```
 
 ### Version negotiation
 
-`getEtch()` accepts the contract version your plugin targets. On today's `0.x`
-runtime this is a best-effort check (a console warning on mismatch). On a future
-stable runtime that exposes a native `connect()`, the call is delegated to it
-and you receive a version-pinned instance:
+**Today (`0.x`): there is no real negotiation yet.** The runtime reports
+`etch.apiVersion` as the coarse marker `'0.x'` (not a precise version), and
+`getEtch({ apiVersion })` only does a best-effort major-version check that
+`console.warn`s on mismatch — it never throws or adapts. While the surface is
+experimental, **prefer feature detection** over version comparison:
+
+```ts
+const etch = getEtch();
+if (typeof etch.blocks.someNewMethod === "function") {
+  // safe to use
+}
+```
+
+**In the future (once the contract reaches `1.x`):** `etch.apiVersion` will
+report a real semver, and `getEtch()` will negotiate against the runtime's
+native `connect()` — returning an instance pinned to the version your plugin
+targets, and failing fast when the runtime can't satisfy it:
 
 ```ts
-const etch = getEtch({ apiVersion: '^1.0', id: 'my-plugin' });
+// Reserved API — shape of versioned access once the contract is stable:
+const etch = getEtch({ apiVersion: "^1.0", id: "my-plugin" });
+//    └─ delegates to window.etch.connect({ apiVersion: "^1.0", id }) when present,
+//       yielding a version-pinned instance (throws on an incompatible runtime).
+```
+
+`getEtch()` already accepts `{ apiVersion, id }` today, so plugins can pass them
+now and have them take effect automatically once the stable runtime ships — no
+code change needed.
+
+### Typed block JSON
+
+Block JSON is a **discriminated union** on `type`, so the compiler flags a block
+whose payload doesn't match its declared type, and `getJson()` / `getTree()`
+results narrow by `type`:
+
+```ts
+const block = etch.blocks.getJson(id);
+
+if (block.type === "etch/text") {
+  console.log(block.text); // narrowed to the text-block shape
+} else if (block.type === "etch/element") {
+  console.log(block.tag, block.attributes);
+}
+
+// Authoring is checked too — this is a type error (an `etch/text` has no `tag`):
+etch.blocks.create({
+  type: "etch/text",
+  version: 1,
+  context: {},
+  children: [],
+  tag: "div",
+});
 ```
 
 ### Types only
@@ -78,7 +152,10 @@ Every contract type is exported and dependency-free, so you can use them
 directly:
 
 ```ts
-import type { PublicBlockJson, EtchBlocksApi } from '@digital-gravy/etch-public-api';
+import type {
+  PublicBlockJson,
+  EtchBlocksApi,
+} from "@digital-gravy/etch-public-api";
 ```
 
 You can also work against the global directly — the package augments

package/dist/index.d.cts

@@ -42,14 +42,28 @@ interface EtchBlockScript {
 interface EtchBlockOptions {
     [key: string]: unknown;
 }
+/** HTML attributes of a block. A value of `undefined` clears that attribute. */
+type EtchHtmlAttributes = Record<string, string | undefined>;
 /**
- * A block as plain, structured-clone-safe JSON — the shape accepted by
- * `blocks.create()` / `blocks.replace()`. Concrete block types add their own
- * fields, so the shape is intentionally extensible.
+ * A parsed Gutenberg block (WordPress block grammar), as carried by an
+ * `etch/passthrough` block. `attrs` is an open bag.
  */
-interface EtchBlockJson {
-    /** The block type, e.g. `etch/text` or `etch/div`. */
-    type: EtchBlockType;
+interface GutenbergBlock {
+    /** Block name, e.g. `core/paragraph`. */
+    blockName: string;
+    /** Nested Gutenberg blocks. */
+    innerBlocks: GutenbergBlock[];
+    /** Rendered inner HTML. */
+    innerHTML: string;
+    /** Inner-content fragments (`null` marks an inner-block insertion point). */
+    innerContent: (string | null)[];
+    /** Block attributes. */
+    attrs: {
+        [key: string]: unknown;
+    };
+}
+/** Fields shared by every block, whatever its `type`. */
+interface EtchBlockCommon {
     /** Schema version of this block type. */
     version: number;
     /** Editor-facing metadata (label, hidden, structure state). */
@@ -58,36 +72,167 @@ interface EtchBlockJson {
     script?: EtchBlockScript;
     /** Optional block-type-specific options. */
     options?: EtchBlockOptions;
-    /** Child blocks, each itself an `EtchBlockJson`. */
+    /** Child blocks, each itself an {@link EtchBlockJson}. */
     children: EtchBlockJson[];
-    /** Block-type-specific fields beyond the common ones above. */
-    [key: string]: unknown;
+}
+/** A text block (`etch/text`). */
+interface EtchTextBlockJson extends EtchBlockCommon {
+    type: "etch/text";
+    /** The block's text content. */
+    text: string;
+}
+/**
+ * A static HTML element block (`etch/element`) with a concrete tag.
+ *
+ * The global `styles` applied to the block are **read-only**: they appear on the
+ * read shape ({@link PublicBlockJson}) but are not settable here, so
+ * `blocks.create()` / `blocks.replace()` ignore them.
+ */
+interface EtchElementBlockJson extends EtchBlockCommon {
+    type: "etch/element";
+    /** The HTML tag name, e.g. `div`, `p`, `h1`. */
+    tag: string;
+    /** HTML attributes. */
+    attributes: EtchHtmlAttributes;
+}
+/**
+ * A dynamic element block (`etch/dynamic-element`). Its rendered tag is read
+ * from `attributes.tag` rather than a dedicated field.
+ *
+ * The global `styles` applied to the block are **read-only** (see
+ * {@link EtchElementBlockJson}).
+ */
+interface EtchDynamicElementBlockJson extends EtchBlockCommon {
+    type: "etch/dynamic-element";
+    /** HTML attributes (the rendered tag is read from `attributes.tag`). */
+    attributes: EtchHtmlAttributes;
+}
+/**
+ * A dynamic image block (`etch/dynamic-image`), rendered as an `<img>`.
+ *
+ * The global `styles` applied to the block are **read-only** (see
+ * {@link EtchElementBlockJson}).
+ */
+interface EtchDynamicImageBlockJson extends EtchBlockCommon {
+    type: "etch/dynamic-image";
+    /** HTML attributes (e.g. `src`, `alt`). */
+    attributes: EtchHtmlAttributes;
+}
+/**
+ * An inline SVG block (`etch/svg`).
+ *
+ * The global `styles` applied to the block are **read-only** (see
+ * {@link EtchElementBlockJson}).
+ */
+interface EtchSvgBlockJson extends EtchBlockCommon {
+    type: "etch/svg";
+    /** HTML/SVG attributes. */
+    attributes: EtchHtmlAttributes;
+}
+/** A loop block (`etch/loop`) that repeats its children over a data source. */
+interface EtchLoopBlockJson extends EtchBlockCommon {
+    type: "etch/loop";
+    /** Variable name bound to the current item (e.g. `item`). */
+    itemId: string;
+    /** What the block iterates over (a dynamic path); omitted when bound via `loopId`. */
+    target?: string;
+    /** Variable name bound to the current index. */
+    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>;
+}
+/** A conditional block (`etch/condition`); renders its children when the expression holds. */
+interface EtchConditionBlockJson extends EtchBlockCommon {
+    type: "etch/condition";
+    /** The condition expression. */
+    conditionString: string;
+}
+/** An instance of a reusable component (`etch/component`). */
+interface EtchComponentBlockJson extends EtchBlockCommon {
+    type: "etch/component";
+    /** Id of the component being instantiated. */
+    componentId: number;
+    /** Values bound to the component's properties. */
+    attributes: EtchHtmlAttributes;
+}
+/** Content projected into a component slot (`etch/slot-content`). */
+interface EtchSlotContentBlockJson extends EtchBlockCommon {
+    type: "etch/slot-content";
+    /** Name of the slot this content targets. */
+    slotName: string;
+}
+/** A slot placeholder inside a component definition (`etch/slot-placeholder`). */
+interface EtchSlotPlaceholderBlockJson extends EtchBlockCommon {
+    type: "etch/slot-placeholder";
+    /** Name of the slot. */
+    slotName: string;
+}
+/** The post-content insertion point (`etch/post-content`). No extra fields. */
+interface EtchPostContentBlockJson extends EtchBlockCommon {
+    type: "etch/post-content";
+}
+/** A raw-HTML block (`etch/raw-html`). */
+interface EtchRawHtmlBlockJson extends EtchBlockCommon {
+    type: "etch/raw-html";
+    /** Sanitized HTML content. */
+    content: string;
+    /** The original, unsanitized HTML as authored. */
+    unsafe: string;
+}
+/** A pass-through wrapper around a native Gutenberg block (`etch/passthrough`). */
+interface EtchPassthroughBlockJson extends EtchBlockCommon {
+    type: "etch/passthrough";
+    /** The wrapped Gutenberg block. */
+    gutenbergBlock: GutenbergBlock;
 }
 /**
- * A block serialized for reading: {@link EtchBlockJson} plus its `id` and
- * `parentId` (`null` at the document root). `id`/`parentId` are attached
- * recursively, so every node in `children` is itself a `PublicBlockJson`.
+ * A block as plain, structured-clone-safe JSON — the shape accepted by
+ * `blocks.create()` / `blocks.replace()`.
+ *
+ * This is a **discriminated union** on `type`: the compiler flags a block whose
+ * payload does not match its declared `type` (e.g. an `etch/text` block missing
+ * `text`, or carrying an `etch/element`'s `tag`).
  */
-interface PublicBlockJson {
+type EtchBlockJson = EtchTextBlockJson | EtchElementBlockJson | EtchDynamicElementBlockJson | EtchDynamicImageBlockJson | EtchSvgBlockJson | EtchLoopBlockJson | EtchConditionBlockJson | EtchComponentBlockJson | EtchSlotContentBlockJson | EtchSlotPlaceholderBlockJson | EtchPostContentBlockJson | EtchRawHtmlBlockJson | EtchPassthroughBlockJson;
+/** Every known block `type` string (the discriminants of {@link EtchBlockJson}). */
+type EtchBlockTypeName = EtchBlockJson["type"];
+/** Read-only identity attached to every serialized (read) block. */
+interface BlockIdentity {
     /** Stable id of this block. */
     id: string;
-    /** Id of the parent block, or `null` when the block sits at the document root. */
+    /** Id of the parent block, or `null` at the document root. */
     parentId: string | null;
-    /** The block type, e.g. `etch/text` or `etch/div`. */
-    type: EtchBlockType;
-    /** Schema version of this block type. */
-    version: number;
-    /** Editor-facing metadata (label, hidden, structure state). */
-    context: EtchBlockContext;
-    /** Optional inline script attached to the block. */
-    script?: EtchBlockScript;
-    /** Optional block-type-specific options. */
-    options?: EtchBlockOptions;
-    /** Child blocks, each itself a `PublicBlockJson` with its own id/parentId. */
+    /** Child blocks, each itself a `PublicBlockJson`. */
     children: PublicBlockJson[];
-    /** Block-type-specific fields beyond the common ones above. */
-    [key: string]: unknown;
 }
+/**
+ * Block types that carry global `styles` (ids of the applied global styles).
+ * These are **read-only**: exposed when reading a block, but not part of the
+ * writable {@link EtchBlockJson}, so they cannot be set via
+ * `blocks.create()` / `blocks.replace()`.
+ */
+type StyledBlockType = "etch/element" | "etch/dynamic-element" | "etch/dynamic-image" | "etch/svg";
+/** The read-only `styles` exposed on a {@link StyledBlockType} when reading. */
+interface ReadOnlyBlockStyles {
+    /** Ids of the global styles applied to this block (read-only). */
+    readonly styles: string[];
+}
+/**
+ * Attach read-only identity (`id`/`parentId`) to a block, recursively, plus the
+ * read-only `styles` array for the {@link StyledBlockType}s that carry one.
+ */
+type WithIdentity<B> = B extends EtchBlockCommon ? Omit<B, "children"> & BlockIdentity & (B extends {
+    type: StyledBlockType;
+} ? ReadOnlyBlockStyles : unknown) : never;
+/**
+ * A block serialized for reading: an {@link EtchBlockJson} variant plus its
+ * `id` and `parentId` (`null` at the document root), attached recursively so
+ * every node in `children` is itself a `PublicBlockJson`. Still discriminated
+ * on `type`, so `switch (block.type)` narrows to the matching payload.
+ */
+type PublicBlockJson = WithIdentity<EtchBlockJson>;
 /** Predicate accepted by `blocks.find()`. All provided fields must match (AND). */
 interface FindBlocksPredicate {
     /** Match blocks of this exact type (e.g. `etch/text`). */
@@ -445,7 +590,36 @@ interface ComponentPropertyBase {
     /** Optional human-readable description. */
     description?: string;
 }
-/** A string property, optionally specialized (color picker, image, select, …). */
+/**
+ * Options for a `select` string property: newline-separated entries, each
+ * `Label : Value` (note the spaces around the colon). A line with no ` : ` uses
+ * its text as both label and value, and the **first line is the default**.
+ *
+ * It is a plain `string` (the format is a runtime convention, not enforced by
+ * the type) — parse it by splitting on `\n`, then each line on `" : "`.
+ *
+ * @example
+ * ```text
+ * Red : #ff0000
+ * Green : #00ff00
+ * Blue : #0000ff
+ * ```
+ */
+type SelectOptionsString = string;
+/**
+ * A string property.
+ *
+ * `type.specialized` selects a string sub-type; a plain text property omits it.
+ * Values the builder actually uses:
+ * - `'image'` — image URL
+ * - `'wpMediaId'` — WordPress media id
+ * - `'select'` — a choice from `options`
+ * - `'array'` — a loop/array binding
+ *
+ * `'color'` and `'url'` are defined in the runtime enum but are **not currently
+ * used** by the builder — do not rely on them. (A `'condition'` string is a
+ * gated group, modelled separately as {@link ConditionComponentProperty}.)
+ */
 interface StringComponentProperty {
     type: {
         primitive: "string";
@@ -455,6 +629,12 @@ interface StringComponentProperty {
     default?: string;
     /** Allowed values when `specialized` is `select`. */
     options?: string[];
+    /**
+     * Options for a `select` property, as a newline-separated string. Each line
+     * is `Label : Value` (note the spaces around the colon); a line with no ` : `
+     * uses its text as both label and value. The **first line is the default**.
+     */
+    selectOptionsString?: SelectOptionsString;
 }
 /** A numeric property. */
 interface NumberComponentProperty {
@@ -474,7 +654,13 @@ interface BooleanComponentProperty {
     /** Default value (a string is allowed for expression-driven defaults). */
     default?: boolean | string;
 }
-/** An object property carrying structured data. */
+/**
+ * A generic object property carrying structured data.
+ *
+ * `type.specialized` is left open (`string`) because the runtime does not
+ * constrain it to an enum. The one reserved value is `'group'`, modelled as
+ * {@link GroupComponentProperty}; a plain object omits `specialized`.
+ */
 interface ObjectComponentProperty {
     type: {
         primitive: "object";
@@ -483,7 +669,13 @@ interface ObjectComponentProperty {
     /** Default value. */
     default?: Record<string, unknown> | unknown[];
 }
-/** An array property carrying a list of values. */
+/**
+ * A generic array property carrying a list of values.
+ *
+ * `type.specialized` is left open (`string`). The reserved values are `'class'`
+ * ({@link ClassComponentProperty}) and `'repeater'`
+ * ({@link RepeaterComponentProperty}); a plain array omits `specialized`.
+ */
 interface ArrayComponentProperty {
     type: {
         primitive: "array";
@@ -492,7 +684,7 @@ interface ArrayComponentProperty {
     /** Default value. */
     default?: unknown[];
 }
-/** A property holding a list of CSS class names. */
+/** A list of CSS class names — an `array` specialized as `'class'`. */
 interface ClassComponentProperty {
     type: {
         primitive: "array";
@@ -501,7 +693,7 @@ interface ClassComponentProperty {
     /** Default value. */
     default?: string[];
 }
-/** A group of nested properties (no default of its own). */
+/** A group of nested properties — an `object` specialized as `'group'` (no default). */
 interface GroupComponentProperty {
     type: {
         primitive: "object";
@@ -510,7 +702,7 @@ interface GroupComponentProperty {
     /** The nested properties in this group. */
     properties: ComponentProperty[];
 }
-/** A repeatable group of nested properties (no default of its own). */
+/** A repeatable group — an `array` specialized as `'repeater'` (no default). */
 interface RepeaterComponentProperty {
     type: {
         primitive: "array";
@@ -519,7 +711,7 @@ interface RepeaterComponentProperty {
     /** The nested properties repeated per row. */
     properties: ComponentProperty[];
 }
-/** A conditional group gated by an expression. */
+/** A conditional group gated by an expression — a `string` specialized as `'condition'`. */
 interface ConditionComponentProperty {
     type: {
         primitive: "string";
@@ -530,7 +722,35 @@ interface ConditionComponentProperty {
     /** The condition expression. */
     default?: string;
 }
-/** A single configurable property of a component. */
+/**
+ * A single configurable property of a component.
+ *
+ * The `type` object carries a `primitive` plus an optional `specialized`
+ * refinement. The combinations the builder actually uses:
+ *
+ * - `string` — plain text; or `'image'` | `'wpMediaId'` | `'select'` |
+ *   `'array'`; or `'condition'` (a gated group with nested `properties`)
+ * - `number` — numeric
+ * - `boolean` — boolean
+ * - `object` — generic object; or `'group'` (nested `properties`)
+ * - `array` — generic array; or `'class'` (CSS classes); or `'repeater'`
+ *   (repeating group with nested `properties`)
+ *
+ * (`'color'`/`'url'` are defined in the string enum but unused — see
+ * {@link StringComponentProperty}.)
+ *
+ * `object`/`array` `specialized` is typed as an open `string` because the
+ * runtime does not constrain it to an enum. Because plain `string`/`object`/
+ * `array` variants omit `specialized`, narrow before reading it:
+ *
+ * ```ts
+ * if (prop.type.primitive === "object" && "specialized" in prop.type) {
+ *   if (prop.type.specialized === "group") {
+ *     // …group property
+ *   }
+ * }
+ * ```
+ */
 type ComponentProperty = ComponentPropertyBase & (StringComponentProperty | NumberComponentProperty | BooleanComponentProperty | ObjectComponentProperty | ArrayComponentProperty | ClassComponentProperty | GroupComponentProperty | RepeaterComponentProperty | ConditionComponentProperty);
 /** Component metadata without its block tree (returned by `components.list()`). */
 interface PublicComponentSummary {
@@ -900,4 +1120,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 EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlocksApi, type EtchComponentsApi, type EtchFieldsApi, type EtchHistoryApi, type EtchLoop, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchStylesApi, type EtchStylesheetsApi, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type 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 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 StylePatch, 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

@@ -42,14 +42,28 @@ interface EtchBlockScript {
 interface EtchBlockOptions {
     [key: string]: unknown;
 }
+/** HTML attributes of a block. A value of `undefined` clears that attribute. */
+type EtchHtmlAttributes = Record<string, string | undefined>;
 /**
- * A block as plain, structured-clone-safe JSON — the shape accepted by
- * `blocks.create()` / `blocks.replace()`. Concrete block types add their own
- * fields, so the shape is intentionally extensible.
+ * A parsed Gutenberg block (WordPress block grammar), as carried by an
+ * `etch/passthrough` block. `attrs` is an open bag.
  */
-interface EtchBlockJson {
-    /** The block type, e.g. `etch/text` or `etch/div`. */
-    type: EtchBlockType;
+interface GutenbergBlock {
+    /** Block name, e.g. `core/paragraph`. */
+    blockName: string;
+    /** Nested Gutenberg blocks. */
+    innerBlocks: GutenbergBlock[];
+    /** Rendered inner HTML. */
+    innerHTML: string;
+    /** Inner-content fragments (`null` marks an inner-block insertion point). */
+    innerContent: (string | null)[];
+    /** Block attributes. */
+    attrs: {
+        [key: string]: unknown;
+    };
+}
+/** Fields shared by every block, whatever its `type`. */
+interface EtchBlockCommon {
     /** Schema version of this block type. */
     version: number;
     /** Editor-facing metadata (label, hidden, structure state). */
@@ -58,36 +72,167 @@ interface EtchBlockJson {
     script?: EtchBlockScript;
     /** Optional block-type-specific options. */
     options?: EtchBlockOptions;
-    /** Child blocks, each itself an `EtchBlockJson`. */
+    /** Child blocks, each itself an {@link EtchBlockJson}. */
     children: EtchBlockJson[];
-    /** Block-type-specific fields beyond the common ones above. */
-    [key: string]: unknown;
+}
+/** A text block (`etch/text`). */
+interface EtchTextBlockJson extends EtchBlockCommon {
+    type: "etch/text";
+    /** The block's text content. */
+    text: string;
+}
+/**
+ * A static HTML element block (`etch/element`) with a concrete tag.
+ *
+ * The global `styles` applied to the block are **read-only**: they appear on the
+ * read shape ({@link PublicBlockJson}) but are not settable here, so
+ * `blocks.create()` / `blocks.replace()` ignore them.
+ */
+interface EtchElementBlockJson extends EtchBlockCommon {
+    type: "etch/element";
+    /** The HTML tag name, e.g. `div`, `p`, `h1`. */
+    tag: string;
+    /** HTML attributes. */
+    attributes: EtchHtmlAttributes;
+}
+/**
+ * A dynamic element block (`etch/dynamic-element`). Its rendered tag is read
+ * from `attributes.tag` rather than a dedicated field.
+ *
+ * The global `styles` applied to the block are **read-only** (see
+ * {@link EtchElementBlockJson}).
+ */
+interface EtchDynamicElementBlockJson extends EtchBlockCommon {
+    type: "etch/dynamic-element";
+    /** HTML attributes (the rendered tag is read from `attributes.tag`). */
+    attributes: EtchHtmlAttributes;
+}
+/**
+ * A dynamic image block (`etch/dynamic-image`), rendered as an `<img>`.
+ *
+ * The global `styles` applied to the block are **read-only** (see
+ * {@link EtchElementBlockJson}).
+ */
+interface EtchDynamicImageBlockJson extends EtchBlockCommon {
+    type: "etch/dynamic-image";
+    /** HTML attributes (e.g. `src`, `alt`). */
+    attributes: EtchHtmlAttributes;
+}
+/**
+ * An inline SVG block (`etch/svg`).
+ *
+ * The global `styles` applied to the block are **read-only** (see
+ * {@link EtchElementBlockJson}).
+ */
+interface EtchSvgBlockJson extends EtchBlockCommon {
+    type: "etch/svg";
+    /** HTML/SVG attributes. */
+    attributes: EtchHtmlAttributes;
+}
+/** A loop block (`etch/loop`) that repeats its children over a data source. */
+interface EtchLoopBlockJson extends EtchBlockCommon {
+    type: "etch/loop";
+    /** Variable name bound to the current item (e.g. `item`). */
+    itemId: string;
+    /** What the block iterates over (a dynamic path); omitted when bound via `loopId`. */
+    target?: string;
+    /** Variable name bound to the current index. */
+    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>;
+}
+/** A conditional block (`etch/condition`); renders its children when the expression holds. */
+interface EtchConditionBlockJson extends EtchBlockCommon {
+    type: "etch/condition";
+    /** The condition expression. */
+    conditionString: string;
+}
+/** An instance of a reusable component (`etch/component`). */
+interface EtchComponentBlockJson extends EtchBlockCommon {
+    type: "etch/component";
+    /** Id of the component being instantiated. */
+    componentId: number;
+    /** Values bound to the component's properties. */
+    attributes: EtchHtmlAttributes;
+}
+/** Content projected into a component slot (`etch/slot-content`). */
+interface EtchSlotContentBlockJson extends EtchBlockCommon {
+    type: "etch/slot-content";
+    /** Name of the slot this content targets. */
+    slotName: string;
+}
+/** A slot placeholder inside a component definition (`etch/slot-placeholder`). */
+interface EtchSlotPlaceholderBlockJson extends EtchBlockCommon {
+    type: "etch/slot-placeholder";
+    /** Name of the slot. */
+    slotName: string;
+}
+/** The post-content insertion point (`etch/post-content`). No extra fields. */
+interface EtchPostContentBlockJson extends EtchBlockCommon {
+    type: "etch/post-content";
+}
+/** A raw-HTML block (`etch/raw-html`). */
+interface EtchRawHtmlBlockJson extends EtchBlockCommon {
+    type: "etch/raw-html";
+    /** Sanitized HTML content. */
+    content: string;
+    /** The original, unsanitized HTML as authored. */
+    unsafe: string;
+}
+/** A pass-through wrapper around a native Gutenberg block (`etch/passthrough`). */
+interface EtchPassthroughBlockJson extends EtchBlockCommon {
+    type: "etch/passthrough";
+    /** The wrapped Gutenberg block. */
+    gutenbergBlock: GutenbergBlock;
 }
 /**
- * A block serialized for reading: {@link EtchBlockJson} plus its `id` and
- * `parentId` (`null` at the document root). `id`/`parentId` are attached
- * recursively, so every node in `children` is itself a `PublicBlockJson`.
+ * A block as plain, structured-clone-safe JSON — the shape accepted by
+ * `blocks.create()` / `blocks.replace()`.
+ *
+ * This is a **discriminated union** on `type`: the compiler flags a block whose
+ * payload does not match its declared `type` (e.g. an `etch/text` block missing
+ * `text`, or carrying an `etch/element`'s `tag`).
  */
-interface PublicBlockJson {
+type EtchBlockJson = EtchTextBlockJson | EtchElementBlockJson | EtchDynamicElementBlockJson | EtchDynamicImageBlockJson | EtchSvgBlockJson | EtchLoopBlockJson | EtchConditionBlockJson | EtchComponentBlockJson | EtchSlotContentBlockJson | EtchSlotPlaceholderBlockJson | EtchPostContentBlockJson | EtchRawHtmlBlockJson | EtchPassthroughBlockJson;
+/** Every known block `type` string (the discriminants of {@link EtchBlockJson}). */
+type EtchBlockTypeName = EtchBlockJson["type"];
+/** Read-only identity attached to every serialized (read) block. */
+interface BlockIdentity {
     /** Stable id of this block. */
     id: string;
-    /** Id of the parent block, or `null` when the block sits at the document root. */
+    /** Id of the parent block, or `null` at the document root. */
     parentId: string | null;
-    /** The block type, e.g. `etch/text` or `etch/div`. */
-    type: EtchBlockType;
-    /** Schema version of this block type. */
-    version: number;
-    /** Editor-facing metadata (label, hidden, structure state). */
-    context: EtchBlockContext;
-    /** Optional inline script attached to the block. */
-    script?: EtchBlockScript;
-    /** Optional block-type-specific options. */
-    options?: EtchBlockOptions;
-    /** Child blocks, each itself a `PublicBlockJson` with its own id/parentId. */
+    /** Child blocks, each itself a `PublicBlockJson`. */
     children: PublicBlockJson[];
-    /** Block-type-specific fields beyond the common ones above. */
-    [key: string]: unknown;
 }
+/**
+ * Block types that carry global `styles` (ids of the applied global styles).
+ * These are **read-only**: exposed when reading a block, but not part of the
+ * writable {@link EtchBlockJson}, so they cannot be set via
+ * `blocks.create()` / `blocks.replace()`.
+ */
+type StyledBlockType = "etch/element" | "etch/dynamic-element" | "etch/dynamic-image" | "etch/svg";
+/** The read-only `styles` exposed on a {@link StyledBlockType} when reading. */
+interface ReadOnlyBlockStyles {
+    /** Ids of the global styles applied to this block (read-only). */
+    readonly styles: string[];
+}
+/**
+ * Attach read-only identity (`id`/`parentId`) to a block, recursively, plus the
+ * read-only `styles` array for the {@link StyledBlockType}s that carry one.
+ */
+type WithIdentity<B> = B extends EtchBlockCommon ? Omit<B, "children"> & BlockIdentity & (B extends {
+    type: StyledBlockType;
+} ? ReadOnlyBlockStyles : unknown) : never;
+/**
+ * A block serialized for reading: an {@link EtchBlockJson} variant plus its
+ * `id` and `parentId` (`null` at the document root), attached recursively so
+ * every node in `children` is itself a `PublicBlockJson`. Still discriminated
+ * on `type`, so `switch (block.type)` narrows to the matching payload.
+ */
+type PublicBlockJson = WithIdentity<EtchBlockJson>;
 /** Predicate accepted by `blocks.find()`. All provided fields must match (AND). */
 interface FindBlocksPredicate {
     /** Match blocks of this exact type (e.g. `etch/text`). */
@@ -445,7 +590,36 @@ interface ComponentPropertyBase {
     /** Optional human-readable description. */
     description?: string;
 }
-/** A string property, optionally specialized (color picker, image, select, …). */
+/**
+ * Options for a `select` string property: newline-separated entries, each
+ * `Label : Value` (note the spaces around the colon). A line with no ` : ` uses
+ * its text as both label and value, and the **first line is the default**.
+ *
+ * It is a plain `string` (the format is a runtime convention, not enforced by
+ * the type) — parse it by splitting on `\n`, then each line on `" : "`.
+ *
+ * @example
+ * ```text
+ * Red : #ff0000
+ * Green : #00ff00
+ * Blue : #0000ff
+ * ```
+ */
+type SelectOptionsString = string;
+/**
+ * A string property.
+ *
+ * `type.specialized` selects a string sub-type; a plain text property omits it.
+ * Values the builder actually uses:
+ * - `'image'` — image URL
+ * - `'wpMediaId'` — WordPress media id
+ * - `'select'` — a choice from `options`
+ * - `'array'` — a loop/array binding
+ *
+ * `'color'` and `'url'` are defined in the runtime enum but are **not currently
+ * used** by the builder — do not rely on them. (A `'condition'` string is a
+ * gated group, modelled separately as {@link ConditionComponentProperty}.)
+ */
 interface StringComponentProperty {
     type: {
         primitive: "string";
@@ -455,6 +629,12 @@ interface StringComponentProperty {
     default?: string;
     /** Allowed values when `specialized` is `select`. */
     options?: string[];
+    /**
+     * Options for a `select` property, as a newline-separated string. Each line
+     * is `Label : Value` (note the spaces around the colon); a line with no ` : `
+     * uses its text as both label and value. The **first line is the default**.
+     */
+    selectOptionsString?: SelectOptionsString;
 }
 /** A numeric property. */
 interface NumberComponentProperty {
@@ -474,7 +654,13 @@ interface BooleanComponentProperty {
     /** Default value (a string is allowed for expression-driven defaults). */
     default?: boolean | string;
 }
-/** An object property carrying structured data. */
+/**
+ * A generic object property carrying structured data.
+ *
+ * `type.specialized` is left open (`string`) because the runtime does not
+ * constrain it to an enum. The one reserved value is `'group'`, modelled as
+ * {@link GroupComponentProperty}; a plain object omits `specialized`.
+ */
 interface ObjectComponentProperty {
     type: {
         primitive: "object";
@@ -483,7 +669,13 @@ interface ObjectComponentProperty {
     /** Default value. */
     default?: Record<string, unknown> | unknown[];
 }
-/** An array property carrying a list of values. */
+/**
+ * A generic array property carrying a list of values.
+ *
+ * `type.specialized` is left open (`string`). The reserved values are `'class'`
+ * ({@link ClassComponentProperty}) and `'repeater'`
+ * ({@link RepeaterComponentProperty}); a plain array omits `specialized`.
+ */
 interface ArrayComponentProperty {
     type: {
         primitive: "array";
@@ -492,7 +684,7 @@ interface ArrayComponentProperty {
     /** Default value. */
     default?: unknown[];
 }
-/** A property holding a list of CSS class names. */
+/** A list of CSS class names — an `array` specialized as `'class'`. */
 interface ClassComponentProperty {
     type: {
         primitive: "array";
@@ -501,7 +693,7 @@ interface ClassComponentProperty {
     /** Default value. */
     default?: string[];
 }
-/** A group of nested properties (no default of its own). */
+/** A group of nested properties — an `object` specialized as `'group'` (no default). */
 interface GroupComponentProperty {
     type: {
         primitive: "object";
@@ -510,7 +702,7 @@ interface GroupComponentProperty {
     /** The nested properties in this group. */
     properties: ComponentProperty[];
 }
-/** A repeatable group of nested properties (no default of its own). */
+/** A repeatable group — an `array` specialized as `'repeater'` (no default). */
 interface RepeaterComponentProperty {
     type: {
         primitive: "array";
@@ -519,7 +711,7 @@ interface RepeaterComponentProperty {
     /** The nested properties repeated per row. */
     properties: ComponentProperty[];
 }
-/** A conditional group gated by an expression. */
+/** A conditional group gated by an expression — a `string` specialized as `'condition'`. */
 interface ConditionComponentProperty {
     type: {
         primitive: "string";
@@ -530,7 +722,35 @@ interface ConditionComponentProperty {
     /** The condition expression. */
     default?: string;
 }
-/** A single configurable property of a component. */
+/**
+ * A single configurable property of a component.
+ *
+ * The `type` object carries a `primitive` plus an optional `specialized`
+ * refinement. The combinations the builder actually uses:
+ *
+ * - `string` — plain text; or `'image'` | `'wpMediaId'` | `'select'` |
+ *   `'array'`; or `'condition'` (a gated group with nested `properties`)
+ * - `number` — numeric
+ * - `boolean` — boolean
+ * - `object` — generic object; or `'group'` (nested `properties`)
+ * - `array` — generic array; or `'class'` (CSS classes); or `'repeater'`
+ *   (repeating group with nested `properties`)
+ *
+ * (`'color'`/`'url'` are defined in the string enum but unused — see
+ * {@link StringComponentProperty}.)
+ *
+ * `object`/`array` `specialized` is typed as an open `string` because the
+ * runtime does not constrain it to an enum. Because plain `string`/`object`/
+ * `array` variants omit `specialized`, narrow before reading it:
+ *
+ * ```ts
+ * if (prop.type.primitive === "object" && "specialized" in prop.type) {
+ *   if (prop.type.specialized === "group") {
+ *     // …group property
+ *   }
+ * }
+ * ```
+ */
 type ComponentProperty = ComponentPropertyBase & (StringComponentProperty | NumberComponentProperty | BooleanComponentProperty | ObjectComponentProperty | ArrayComponentProperty | ClassComponentProperty | GroupComponentProperty | RepeaterComponentProperty | ConditionComponentProperty);
 /** Component metadata without its block tree (returned by `components.list()`). */
 interface PublicComponentSummary {
@@ -900,4 +1120,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 EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlocksApi, type EtchComponentsApi, type EtchFieldsApi, type EtchHistoryApi, type EtchLoop, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchStylesApi, type EtchStylesheetsApi, type EtchUiApi, type FindBlocksPredicate, type GroupComponentProperty, type 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 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 StylePatch, 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.1.1",
+	"version": "0.3.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",