@digital-gravy/etch-public-api 0.9.0 → 0.11.0

package/README.md

@@ -254,6 +254,35 @@ etch.blocks.setAttribute(svgBlockId, 'src', '/icons/logo.svg');
 etch.blocks.setAttribute(svgBlockId, 'stripColors', 'true');
 ```
 
+### Data sources
+
+`etch.dataSources` is the `dataSources` capability's model of dynamic data, and
+supersedes `etch.loops`. A source is defined once for the project under a `key`
+and read anywhere an expression is accepted, through `data('key')`. The
+namespace is **optional** — a runtime without the capability omits it.
+
+```ts
+if (etch.environment?.capabilities.dataSources === true) {
+	const sources = etch.dataSources!;
+
+	await sources.createAsync({
+		key: 'courses',
+		name: 'Courses',
+		type: 'api',
+		metadata: { url: 'https://example.com/courses.json' }
+	});
+
+	// See the real shape before authoring paths against it
+	const value = await sources.resolveAsync('courses');
+
+	// A loop block points its target at the expression — there is no loop id
+	etch.blocks.update(loopBlockId, { target: "data('courses')" });
+}
+```
+
+Reads (`list`, `get`, `findDataSource`) are synchronous; writes persist to the
+backend immediately and do not wait for `saveAsync()`.
+
 ### Skills
 
 `etch.skills` exposes the bundled, read-only authoring guides Etch ships (e.g.
@@ -317,6 +346,7 @@ is imported.
     - **Stylesheets** — `EtchStylesheetsApi`, `StylesheetSummary`, `StylesheetInput`, `StylesheetPatch`
     - **Components** — `EtchComponentsApi`, `PublicComponentSummary`, `PublicComponentJson`, `ComponentPatch`, `ComponentProperty`, …
     - **Loops** — `EtchLoopsApi`, `EtchLoop`, `EtchLoopConfig`, `BlockLoopBinding`, …
+    - **Data sources** — `EtchDataSourcesApi`, `EtchDataSource`, `EtchDataSourceType`, `EtchDataSourcePatch`
     - **Navigation** — `EtchNavigationApi`, `NavigationPlace`, `PostSummary`, `TemplateSummary`
     - **Fields** — `EtchFieldsApi`, `CustomField`, `CustomFieldGroup`, …
     - **Skills** — `EtchSkillsApi`, `SkillSummary`, `SkillDetail`

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts","../src/version.ts","../src/client.ts"],"names":[],"mappings":";;;AAyBO,IAAM,YAAA,GAAN,cAA2B,KAAA,CAAM;AAAA,EAGvC,WAAA,CAAY,MAAwB,OAAA,EAAiB;AACpD,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,cAAA;AACZ,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AAAA,EACb;AACD;AAGO,SAAS,eAAe,KAAA,EAAuC;AACrE,EAAA,OACC,KAAA,YAAiB,YAAA,IAChB,KAAA,EAAiB,IAAA,KAAS,cAAA;AAE7B;;;ACjCO,IAAM,gBAAA,GAAmB;;;ACIhC,SAAS,QAAA,GAA6B;AACrC,EAAA,MAAM,KAAA,GAAQ,UAAA;AACd,EAAA,OAAO,KAAA,CAAM,IAAA;AACd;AAMO,SAAS,eAAA,GAA2B;AAC1C,EAAA,OAAO,UAAS,KAAM,MAAA;AACvB;AAGA,SAAS,QAAQ,OAAA,EAAgC;AAChD,EAAA,MAAM,KAAA,GAAQ,WAAA,CAAY,IAAA,CAAK,OAAO,CAAA;AACtC,EAAA,OAAO,KAAA,GAAQ,MAAA,CAAO,KAAA,CAAM,CAAC,CAAC,CAAA,GAAI,IAAA;AACnC;AAOA,SAAS,kBAAA,CAAmB,WAAmB,OAAA,EAAuB;AACrE,EAAA,MAAM,IAAA,GAAO,QAAQ,SAAS,CAAA;AAC9B,EAAA,MAAM,IAAA,GAAO,QAAQ,OAAO,CAAA;AAC5B,EAAA,IAAI,IAAA,KAAS,IAAA,IAAQ,IAAA,KAAS,IAAA,IAAQ,SAAS,IAAA,EAAM;AACrD,EAAA,OAAA,CAAQ,IAAA;AAAA,IACP,CAAA,qDAAA,EAAwD,SAAS,CAAA,wBAAA,EAC9C,OAAO,CAAA,sBAAA;AAAA,GAC3B;AACD;AAsBO,SAAS,OAAA,CAAQ,OAAA,GAA0B,EAAC,EAAS;AAC3D,EAAA,MAAM,OAAO,QAAA,EAAS;AACtB,EAAA,IAAI,CAAC,IAAA,EAAM;AACV,IAAA,MAAM,IAAI,YAAA;AAAA,MACT,eAAA;AAAA,MACA;AAAA,KAED;AAAA,EACD;AAEA,EAAA,IAAI,OAAO,IAAA,CAAK,OAAA,KAAY,UAAA,EAAY;AACvC,IAAA,OAAO,IAAA,CAAK,QAAQ,OAAO,CAAA;AAAA,EAC5B;AAEA,EAAA,IAAI,QAAQ,UAAA,EAAY;AACvB,IAAA,kBAAA;AAAA,MACC,OAAA,CAAQ,UAAA;AAAA,MACR,KAAK,UAAA,IAAc;AAAA,KACpB;AAAA,EACD;AACA,EAAA,OAAO,IAAA;AACR","file":"index.cjs","sourcesContent":["/**\n * Error codes thrown by the public `window.etch` API.\n *\n * The API throws typed errors (rather than returning sentinels) so that AI\n * assistants and plugin authors can `try`/`catch` and react to a precise cause.\n *\n * The union ends with `(string & {})` so that codes added by newer Etch\n * runtimes still type-check as `EtchApiErrorCode` while keeping autocomplete for\n * the known values.\n */\nexport type EtchApiErrorCode =\n\t| 'BLOCK_NOT_FOUND'\n\t| 'WRONG_BLOCK_TYPE'\n\t| 'READONLY'\n\t| 'INVALID_ARGUMENT'\n\t| 'LOOP_NOT_FOUND'\n\t| 'STYLE_NOT_FOUND'\n\t| 'STYLESHEET_NOT_FOUND'\n\t| 'COMPONENT_NOT_FOUND'\n\t| 'POST_NOT_FOUND'\n\t| 'OPERATION_FAILED'\n\t| 'NOT_AVAILABLE'\n\t| (string & {});\n\n/** Error thrown by the public Etch API (and by this client). */\nexport class EtchApiError extends Error {\n\treadonly code: EtchApiErrorCode;\n\n\tconstructor(code: EtchApiErrorCode, message: string) {\n\t\tsuper(message);\n\t\tthis.name = 'EtchApiError';\n\t\tthis.code = code;\n\t}\n}\n\n/** Narrow an unknown caught value to an {@link EtchApiError}. */\nexport function isEtchApiError(value: unknown): value is EtchApiError {\n\treturn (\n\t\tvalue instanceof EtchApiError ||\n\t\t(value as Error)?.name === 'EtchApiError'\n\t);\n}\n","/**\n * Version of the Etch scripting **contract** this package targets, independent\n * of the Etch product version and of this package's own npm version.\n *\n * `0.x` signals the surface is **experimental** and may change without a major\n * bump until it stabilizes. It matches the value returned by the runtime's\n * {@link Etch.apiVersion} getter on `window.etch`.\n */\nexport const ETCH_API_VERSION = '0.x';\n","import type { ConnectOptions, Etch } from './contract';\nimport { EtchApiError } from './errors';\nimport { ETCH_API_VERSION } from './version';\n\ndeclare global {\n\tinterface Window {\n\t\t/** The Etch scripting API, present once the builder has loaded. */\n\t\tetch?: Etch;\n\t}\n}\n\n/** Read `window.etch` from whatever global object exists, or `undefined`. */\nfunction readEtch(): Etch | undefined {\n\tconst scope = globalThis as { etch?: Etch };\n\treturn scope.etch;\n}\n\n/**\n * Whether the Etch scripting API is present on the page. Use this to guard code\n * that should no-op when not running inside the builder.\n */\nexport function isEtchAvailable(): boolean {\n\treturn readEtch() !== undefined;\n}\n\n/** The major version number of a semver-ish string, or `null` if unparseable. */\nfunction majorOf(version: string): number | null {\n\tconst match = /^\\D*(\\d+)/.exec(version);\n\treturn match ? Number(match[1]) : null;\n}\n\n/**\n * Best-effort compatibility check for `0.x` runtimes that have no native\n * `connect()`. Warns (does not throw) when the requested major differs from the\n * runtime's, so experimental consumers aren't hard-blocked.\n */\nfunction warnIfIncompatible(requested: string, runtime: string): void {\n\tconst want = majorOf(requested);\n\tconst have = majorOf(runtime);\n\tif (want === null || have === null || want === have) return;\n\tconsole.warn(\n\t\t`[@digital-gravy/etch-public-api] Requested Etch API v${requested} but the ` +\n\t\t\t`page provides v${runtime}. Behavior may differ.`\n\t);\n}\n\n/**\n * Acquire the Etch scripting API from the page.\n *\n * The runtime lives on `window.etch` (injected by the builder); this returns it\n * typed. When the page exposes a future stable runtime with a native\n * `connect()`, version negotiation is delegated to it. On today's `0.x`\n * runtime, the global is returned directly after a best-effort version check.\n *\n * @throws {EtchApiError} `NOT_AVAILABLE` when the builder is not present.\n *\n * @example\n * ```ts\n * import { getEtch } from '@etchwp/public-api';\n *\n * const etch = getEtch();\n * const ids = etch.blocks.find({ type: 'text' });\n * etch.blocks.setText(ids[0], 'Hello');\n * await etch.saveAsync();\n * ```\n */\nexport function getEtch(options: ConnectOptions = {}): Etch {\n\tconst etch = readEtch();\n\tif (!etch) {\n\t\tthrow new EtchApiError(\n\t\t\t'NOT_AVAILABLE',\n\t\t\t'window.etch is not available. The Etch builder is not loaded on this page, ' +\n\t\t\t\t'or getEtch() ran before it finished initializing.'\n\t\t);\n\t}\n\n\tif (typeof etch.connect === 'function') {\n\t\treturn etch.connect(options);\n\t}\n\n\tif (options.apiVersion) {\n\t\twarnIfIncompatible(\n\t\t\toptions.apiVersion,\n\t\t\tetch.apiVersion ?? ETCH_API_VERSION\n\t\t);\n\t}\n\treturn etch;\n}\n"]}
+{"version":3,"sources":["../src/errors.ts","../src/version.ts","../src/client.ts"],"names":[],"mappings":";;;AA0BO,IAAM,YAAA,GAAN,cAA2B,KAAA,CAAM;AAAA,EAGvC,WAAA,CAAY,MAAwB,OAAA,EAAiB;AACpD,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,cAAA;AACZ,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AAAA,EACb;AACD;AAGO,SAAS,eAAe,KAAA,EAAuC;AACrE,EAAA,OACC,KAAA,YAAiB,YAAA,IAChB,KAAA,EAAiB,IAAA,KAAS,cAAA;AAE7B;;;AClCO,IAAM,gBAAA,GAAmB;;;ACIhC,SAAS,QAAA,GAA6B;AACrC,EAAA,MAAM,KAAA,GAAQ,UAAA;AACd,EAAA,OAAO,KAAA,CAAM,IAAA;AACd;AAMO,SAAS,eAAA,GAA2B;AAC1C,EAAA,OAAO,UAAS,KAAM,MAAA;AACvB;AAGA,SAAS,QAAQ,OAAA,EAAgC;AAChD,EAAA,MAAM,KAAA,GAAQ,WAAA,CAAY,IAAA,CAAK,OAAO,CAAA;AACtC,EAAA,OAAO,KAAA,GAAQ,MAAA,CAAO,KAAA,CAAM,CAAC,CAAC,CAAA,GAAI,IAAA;AACnC;AAOA,SAAS,kBAAA,CAAmB,WAAmB,OAAA,EAAuB;AACrE,EAAA,MAAM,IAAA,GAAO,QAAQ,SAAS,CAAA;AAC9B,EAAA,MAAM,IAAA,GAAO,QAAQ,OAAO,CAAA;AAC5B,EAAA,IAAI,IAAA,KAAS,IAAA,IAAQ,IAAA,KAAS,IAAA,IAAQ,SAAS,IAAA,EAAM;AACrD,EAAA,OAAA,CAAQ,IAAA;AAAA,IACP,CAAA,qDAAA,EAAwD,SAAS,CAAA,wBAAA,EAC9C,OAAO,CAAA,sBAAA;AAAA,GAC3B;AACD;AAsBO,SAAS,OAAA,CAAQ,OAAA,GAA0B,EAAC,EAAS;AAC3D,EAAA,MAAM,OAAO,QAAA,EAAS;AACtB,EAAA,IAAI,CAAC,IAAA,EAAM;AACV,IAAA,MAAM,IAAI,YAAA;AAAA,MACT,eAAA;AAAA,MACA;AAAA,KAED;AAAA,EACD;AAEA,EAAA,IAAI,OAAO,IAAA,CAAK,OAAA,KAAY,UAAA,EAAY;AACvC,IAAA,OAAO,IAAA,CAAK,QAAQ,OAAO,CAAA;AAAA,EAC5B;AAEA,EAAA,IAAI,QAAQ,UAAA,EAAY;AACvB,IAAA,kBAAA;AAAA,MACC,OAAA,CAAQ,UAAA;AAAA,MACR,KAAK,UAAA,IAAc;AAAA,KACpB;AAAA,EACD;AACA,EAAA,OAAO,IAAA;AACR","file":"index.cjs","sourcesContent":["/**\n * Error codes thrown by the public `window.etch` API.\n *\n * The API throws typed errors (rather than returning sentinels) so that AI\n * assistants and plugin authors can `try`/`catch` and react to a precise cause.\n *\n * The union ends with `(string & {})` so that codes added by newer Etch\n * runtimes still type-check as `EtchApiErrorCode` while keeping autocomplete for\n * the known values.\n */\nexport type EtchApiErrorCode =\n\t| 'BLOCK_NOT_FOUND'\n\t| 'WRONG_BLOCK_TYPE'\n\t| 'READONLY'\n\t| 'INVALID_ARGUMENT'\n\t| 'LOOP_NOT_FOUND'\n\t| 'DATA_SOURCE_NOT_FOUND'\n\t| 'STYLE_NOT_FOUND'\n\t| 'STYLESHEET_NOT_FOUND'\n\t| 'COMPONENT_NOT_FOUND'\n\t| 'POST_NOT_FOUND'\n\t| 'OPERATION_FAILED'\n\t| 'NOT_AVAILABLE'\n\t| (string & {});\n\n/** Error thrown by the public Etch API (and by this client). */\nexport class EtchApiError extends Error {\n\treadonly code: EtchApiErrorCode;\n\n\tconstructor(code: EtchApiErrorCode, message: string) {\n\t\tsuper(message);\n\t\tthis.name = 'EtchApiError';\n\t\tthis.code = code;\n\t}\n}\n\n/** Narrow an unknown caught value to an {@link EtchApiError}. */\nexport function isEtchApiError(value: unknown): value is EtchApiError {\n\treturn (\n\t\tvalue instanceof EtchApiError ||\n\t\t(value as Error)?.name === 'EtchApiError'\n\t);\n}\n","/**\n * Version of the Etch scripting **contract** this package targets, independent\n * of the Etch product version and of this package's own npm version.\n *\n * `0.x` signals the surface is **experimental** and may change without a major\n * bump until it stabilizes. It matches the value returned by the runtime's\n * {@link Etch.apiVersion} getter on `window.etch`.\n */\nexport const ETCH_API_VERSION = '0.x';\n","import type { ConnectOptions, Etch } from './contract';\nimport { EtchApiError } from './errors';\nimport { ETCH_API_VERSION } from './version';\n\ndeclare global {\n\tinterface Window {\n\t\t/** The Etch scripting API, present once the builder has loaded. */\n\t\tetch?: Etch;\n\t}\n}\n\n/** Read `window.etch` from whatever global object exists, or `undefined`. */\nfunction readEtch(): Etch | undefined {\n\tconst scope = globalThis as { etch?: Etch };\n\treturn scope.etch;\n}\n\n/**\n * Whether the Etch scripting API is present on the page. Use this to guard code\n * that should no-op when not running inside the builder.\n */\nexport function isEtchAvailable(): boolean {\n\treturn readEtch() !== undefined;\n}\n\n/** The major version number of a semver-ish string, or `null` if unparseable. */\nfunction majorOf(version: string): number | null {\n\tconst match = /^\\D*(\\d+)/.exec(version);\n\treturn match ? Number(match[1]) : null;\n}\n\n/**\n * Best-effort compatibility check for `0.x` runtimes that have no native\n * `connect()`. Warns (does not throw) when the requested major differs from the\n * runtime's, so experimental consumers aren't hard-blocked.\n */\nfunction warnIfIncompatible(requested: string, runtime: string): void {\n\tconst want = majorOf(requested);\n\tconst have = majorOf(runtime);\n\tif (want === null || have === null || want === have) return;\n\tconsole.warn(\n\t\t`[@digital-gravy/etch-public-api] Requested Etch API v${requested} but the ` +\n\t\t\t`page provides v${runtime}. Behavior may differ.`\n\t);\n}\n\n/**\n * Acquire the Etch scripting API from the page.\n *\n * The runtime lives on `window.etch` (injected by the builder); this returns it\n * typed. When the page exposes a future stable runtime with a native\n * `connect()`, version negotiation is delegated to it. On today's `0.x`\n * runtime, the global is returned directly after a best-effort version check.\n *\n * @throws {EtchApiError} `NOT_AVAILABLE` when the builder is not present.\n *\n * @example\n * ```ts\n * import { getEtch } from '@etchwp/public-api';\n *\n * const etch = getEtch();\n * const ids = etch.blocks.find({ type: 'text' });\n * etch.blocks.setText(ids[0], 'Hello');\n * await etch.saveAsync();\n * ```\n */\nexport function getEtch(options: ConnectOptions = {}): Etch {\n\tconst etch = readEtch();\n\tif (!etch) {\n\t\tthrow new EtchApiError(\n\t\t\t'NOT_AVAILABLE',\n\t\t\t'window.etch is not available. The Etch builder is not loaded on this page, ' +\n\t\t\t\t'or getEtch() ran before it finished initializing.'\n\t\t);\n\t}\n\n\tif (typeof etch.connect === 'function') {\n\t\treturn etch.connect(options);\n\t}\n\n\tif (options.apiVersion) {\n\t\twarnIfIncompatible(\n\t\t\toptions.apiVersion,\n\t\t\tetch.apiVersion ?? ETCH_API_VERSION\n\t\t);\n\t}\n\treturn etch;\n}\n"]}

package/dist/index.d.cts

@@ -340,15 +340,26 @@ 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`. */
+    /**
+     * What the block iterates over.
+     *
+     * On a `dataSources` runtime this is the whole binding and is **required**:
+     * any dynamic expression yielding a list — `data('products').items`, an
+     * enclosing loop's `item.tags`, `range(1, 10)`. On a `loops` runtime it is
+     * optional and means a sub-path within the loop bound by `loopId`.
+     */
     target?: string;
     /** Variable name bound to the current index. */
     indexId?: string;
-    /** Id of a registered loop definition this block is bound to. */
+    /**
+     * Id of a registered loop definition this block is bound to.
+     * **Requires the `loops` capability** — ignored where loops are not backed.
+     */
     loopId?: string;
     /**
      * Values for the bound loop's parameters. Every key must be a `$`-prefixed
      * parameter reference (e.g. `$count`).
+     * **Requires the `loops` capability** — ignored where loops are not backed.
      */
     loopParams?: Record<LoopParamRef, unknown>;
 }
@@ -390,7 +401,13 @@ interface EtchRawHtmlBlockJson extends EtchBlockCommon {
     /** The original, unsanitized HTML as authored. */
     unsafe: string;
 }
-/** A pass-through wrapper around a native Gutenberg block (`etch/passthrough`). */
+/**
+ * A pass-through wrapper around a native Gutenberg block (`etch/passthrough`).
+ *
+ * **Not registered on every build** — this one is WordPress-only. Check
+ * `etch.environment.blockTypes` before authoring it; creating a block type the
+ * runtime does not register is rejected.
+ */
 interface EtchPassthroughBlockJson extends EtchBlockCommon {
     type: 'etch/passthrough';
     /** The wrapped Gutenberg block. */
@@ -402,8 +419,8 @@ interface EtchPassthroughBlockJson extends EtchBlockCommon {
  * time, such as a content-type field. Its children are the resolved JSON, so it
  * accepts no authored children.
  *
- * **Not registered on every build** — this one is Studio-only; creating a block
- * type the runtime does not register is rejected.
+ * **Not registered on every build** — this one is Studio-only. Check
+ * `etch.environment.blockTypes` before authoring it.
  */
 interface EtchRenderBlockJson extends EtchBlockCommon {
     type: 'etch/render';
@@ -484,9 +501,9 @@ interface BlockPatch {
     /** Replace the text content. Only valid on text blocks. */
     text?: string;
     /**
-     * Re-point what the block resolves at: the expression an `etch/loop` block
-     * iterates over, or the one an `etch/render` block renders. Only valid on
-     * block types that carry a `target`.
+     * Re-point what the block resolves at: the iterated expression of an
+     * `etch/loop` block, or the rendered expression of an `etch/render` block.
+     * Only valid on those two types.
      */
     target?: string;
 }
@@ -662,6 +679,169 @@ interface EtchBlocksApi {
     saveComponentEditModeAsync(): Promise<void>;
 }
 
+/**
+ * What this Etch runtime actually is, and which optional surfaces it backs.
+ *
+ * Etch ships as more than one product against **one** contract: `etch-wp` runs
+ * inside WordPress, `etch-studio` is standalone. They expose the same `etch`
+ * namespaces, but a namespace can be declared and not implemented — those
+ * methods throw `EtchApiError` with code `NOT_AVAILABLE`.
+ *
+ * `etch.environment` is how a caller finds that out **without** calling and
+ * catching. It is deliberately a description of the runtime rather than of the
+ * product: prefer `capabilities.loops` over `product === 'etch-wp'`, because
+ * capabilities move between products over time (the data manager, for one, is
+ * on its way to WordPress) while a product check silently rots the day they do.
+ */
+/** Which build of Etch is running. Identity — not a capability check. */
+type EtchProduct = 'etch-wp' | 'etch-studio' | (string & {});
+/**
+ * Optional surfaces a runtime may or may not back.
+ *
+ * `loops` and `dataSources` are the two dynamic-data models, and they decide
+ * how an `etch/loop` block is authored — check which one you are on before
+ * writing one:
+ *
+ * - `loops` — a registry of named loop definitions. A loop block binds to one
+ *   by `loopId` (plus `$`-prefixed `loopParams`), and `target` is an optional
+ *   sub-path within it.
+ * - `dataSources` — named, typed project sources (`json`, `api`, `js`), reached
+ *   through a `data('key')` expression. A loop block carries **only** a
+ *   required `target`, and that target is any *dynamic expression* yielding a
+ *   list — a data source, a path into one (`data('products').items`), nested
+ *   data from an enclosing loop (`item.tags`), or a generated list
+ *   (`range(1, 10)`). There is no `loopId`/`loopParams`. This model supersedes
+ *   `loops` and is expected on both products eventually.
+ *
+ * The rest:
+ *
+ * - `fields` — `etch.fields.*` is backed by a real field store.
+ * - `templates` — template posts exist and `navigation.goTo('templates')` works.
+ * - `wpMedia` — media ids resolve against the **WordPress media library**, so a
+ *   URL can be turned into an id through `/wp/v2/media`. Without it the ids are
+ *   the product's own asset store instead. Either way an `etch/dynamic-image`
+ *   block binds the same: a numeric `mediaId` attribute.
+ */
+type EtchCapability = 'loops' | 'dataSources' | 'fields' | 'templates' | 'wpMedia';
+/**
+ * Capability map. Every key is optional on purpose: a runtime older than a
+ * capability's introduction simply omits it, so **absent means unavailable**.
+ * Test with `=== true` rather than truthiness of a possibly-missing key.
+ */
+type EtchCapabilities = Readonly<Partial<Record<EtchCapability, boolean>>>;
+/** Runtime self-description, exposed as `etch.environment`. */
+interface EtchEnvironment {
+    /**
+     * Which build this is — identity, for display and diagnostics. Every
+     * behavioral decision belongs to {@link capabilities} instead; a product
+     * check goes wrong the moment a capability moves between products.
+     */
+    readonly product: EtchProduct;
+    /** Which optional surfaces this runtime actually backs. */
+    readonly capabilities: EtchCapabilities;
+    /**
+     * Every block `type` this runtime can construct, sorted. Read this instead
+     * of assuming a block exists: `etch/passthrough` is WordPress-only and
+     * `etch/render` is Studio-only, and the list grows with each release.
+     */
+    readonly blockTypes: readonly string[];
+}
+
+/**
+ * Project data sources and the `etch.dataSources` API surface.
+ *
+ * Data sources are the `dataSources` capability's model of dynamic data, and
+ * they supersede {@link EtchLoopsApi | loops}: a named, typed source is defined
+ * once for the project and read anywhere an expression is accepted, through
+ * `data('key')`. A loop block points its `target` at one of those expressions
+ * rather than binding to a loop id.
+ *
+ * Check `etch.environment.capabilities.dataSources === true` before using this
+ * namespace — a runtime without it omits the whole thing.
+ */
+/**
+ * A source type. The three built-ins are listed; the registry behind the
+ * runtime is open, so a host may serve types this contract has never heard of.
+ */
+type EtchDataSourceType = 'json' | 'api' | 'js' | (string & {});
+/**
+ * A project data source, identified by its `key` — the name `data('key')`
+ * calls it by.
+ */
+interface EtchDataSource {
+    /**
+     * Stable identifier used in expressions: `data('products')`. Unique within
+     * the project, and part of every authored expression that reads the source,
+     * so renaming one breaks those expressions.
+     */
+    key: string;
+    /** Display name shown in the data manager. */
+    name: string;
+    /** Which kind of source this is; decides how `metadata` is read. */
+    type: EtchDataSourceType;
+    /**
+     * Type-specific configuration. The built-in types read:
+     *
+     * - `json` — `{ data: unknown }`, the payload served verbatim.
+     * - `api` — `{ url: string; method?: string; headers?: [string, string][] }`,
+     *   fetched and parsed as JSON. A non-OK response fails the source.
+     * - `js` — `{ code: string }`, a function body run in a sandbox. Arguments
+     *   passed by the expression (`data('rows', 5)`) arrive as `args`.
+     */
+    metadata: Record<string, unknown>;
+}
+/** Fields of an {@link EtchDataSource} that `updateAsync` can change. */
+type EtchDataSourcePatch = Partial<EtchDataSource>;
+/**
+ * Project data sources: definitions, and resolving one to its value.
+ *
+ * Reads are synchronous — the project's sources are loaded before `window.etch`
+ * exists. Writes persist to the backend immediately (they do not wait for
+ * {@link Etch.saveAsync}) and drop any value already resolved from the source,
+ * so the canvas re-reads it.
+ */
+interface EtchDataSourcesApi {
+    /** Every data source defined for this project. */
+    list(): EtchDataSource[];
+    /**
+     * One data source by key.
+     * @throws {EtchApiError} `DATA_SOURCE_NOT_FOUND`
+     */
+    get(key: string): EtchDataSource;
+    /**
+     * Fuzzy-search data sources by `name` or `key`, ranked best-first. Returns
+     * an empty array for a blank query or when nothing matches.
+     */
+    findDataSource(query: string): EtchDataSource[];
+    /**
+     * Define a new data source.
+     * @throws {EtchApiError} `INVALID_ARGUMENT` on a malformed source, or when
+     * the key is already taken.
+     */
+    createAsync(source: EtchDataSource): Promise<EtchDataSource>;
+    /**
+     * Change an existing data source. Only the fields present are applied.
+     * @throws {EtchApiError} `DATA_SOURCE_NOT_FOUND`
+     */
+    updateAsync(key: string, patch: EtchDataSourcePatch): Promise<EtchDataSource>;
+    /**
+     * Delete a data source. Expressions still naming it resolve to `undefined`.
+     * @throws {EtchApiError} `DATA_SOURCE_NOT_FOUND`
+     */
+    deleteAsync(key: string): Promise<void>;
+    /**
+     * Resolve a data source to its value, exactly as `data('key', ...args)`
+     * would on the canvas — read this before authoring the property paths that
+     * depend on its shape.
+     *
+     * A source that fails resolves to `undefined` rather than rejecting, which
+     * is what the render sees too.
+     *
+     * @throws {EtchApiError} `DATA_SOURCE_NOT_FOUND`
+     */
+    resolveAsync(key: string, ...args: unknown[]): Promise<unknown>;
+}
+
 /**
  * Global style (CSS rule) shapes and the `etch.styles` API surface.
  */
@@ -1461,6 +1641,16 @@ interface Etch {
     blocks: EtchBlocksApi;
     /** Loop definitions and binding loops to blocks. */
     loops: EtchLoopsApi;
+    /**
+     * Project data sources — the `dataSources` capability's model of dynamic
+     * data, which supersedes {@link loops}.
+     *
+     * Optional: a runtime that does not back the capability omits the namespace
+     * entirely rather than stubbing it, so check
+     * `environment.capabilities.dataSources === true` (or the presence of this
+     * property) before calling it.
+     */
+    dataSources?: EtchDataSourcesApi;
     /** Global style (CSS) definitions and CSS variables. */
     styles: EtchStylesApi;
     /** Global stylesheets and `@custom-media` definitions. */
@@ -1510,6 +1700,16 @@ interface Etch {
     readonly apiVersion: string;
     /** The Etch builder (product) version, for capability checks. */
     readonly version: string;
+    /**
+     * What this runtime is and which optional surfaces it backs. Read this
+     * before using `loops`, `fields`, templates or WordPress media, and before
+     * authoring a block type that may not exist here.
+     *
+     * Optional: runtimes older than the descriptor omit it. Treat a missing
+     * `environment` as `etch-wp` on WordPress with everything available, which
+     * is what every runtime that predates it was.
+     */
+    readonly environment?: EtchEnvironment;
 }
 
 declare global {
@@ -1555,7 +1755,7 @@ declare function getEtch(options?: ConnectOptions): Etch;
  * runtimes still type-check as `EtchApiErrorCode` while keeping autocomplete for
  * the known values.
  */
-type EtchApiErrorCode = 'BLOCK_NOT_FOUND' | 'WRONG_BLOCK_TYPE' | 'READONLY' | 'INVALID_ARGUMENT' | 'LOOP_NOT_FOUND' | 'STYLE_NOT_FOUND' | 'STYLESHEET_NOT_FOUND' | 'COMPONENT_NOT_FOUND' | 'POST_NOT_FOUND' | 'OPERATION_FAILED' | 'NOT_AVAILABLE' | (string & {});
+type EtchApiErrorCode = 'BLOCK_NOT_FOUND' | 'WRONG_BLOCK_TYPE' | 'READONLY' | 'INVALID_ARGUMENT' | 'LOOP_NOT_FOUND' | 'DATA_SOURCE_NOT_FOUND' | 'STYLE_NOT_FOUND' | 'STYLESHEET_NOT_FOUND' | 'COMPONENT_NOT_FOUND' | 'POST_NOT_FOUND' | 'OPERATION_FAILED' | 'NOT_AVAILABLE' | (string & {});
 /** Error thrown by the public Etch API (and by this client). */
 declare class EtchApiError extends Error {
     readonly code: EtchApiErrorCode;
@@ -1574,4 +1774,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
  */
 declare const ETCH_API_VERSION = "0.x";
 
-export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, type EtchAiApi, 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 EtchRenderBlockJson, type EtchSkillsApi, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type ExternalAiState, 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 SkillDetail, type SkillSummary, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };
+export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, type EtchAiApi, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchCapabilities, type EtchCapability, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDataSource, type EtchDataSourcePatch, type EtchDataSourceType, type EtchDataSourcesApi, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchEnvironment, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchProduct, type EtchRawHtmlBlockJson, type EtchRenderBlockJson, type EtchSkillsApi, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type ExternalAiState, 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 SkillDetail, type SkillSummary, 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

@@ -340,15 +340,26 @@ 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`. */
+    /**
+     * What the block iterates over.
+     *
+     * On a `dataSources` runtime this is the whole binding and is **required**:
+     * any dynamic expression yielding a list — `data('products').items`, an
+     * enclosing loop's `item.tags`, `range(1, 10)`. On a `loops` runtime it is
+     * optional and means a sub-path within the loop bound by `loopId`.
+     */
     target?: string;
     /** Variable name bound to the current index. */
     indexId?: string;
-    /** Id of a registered loop definition this block is bound to. */
+    /**
+     * Id of a registered loop definition this block is bound to.
+     * **Requires the `loops` capability** — ignored where loops are not backed.
+     */
     loopId?: string;
     /**
      * Values for the bound loop's parameters. Every key must be a `$`-prefixed
      * parameter reference (e.g. `$count`).
+     * **Requires the `loops` capability** — ignored where loops are not backed.
      */
     loopParams?: Record<LoopParamRef, unknown>;
 }
@@ -390,7 +401,13 @@ interface EtchRawHtmlBlockJson extends EtchBlockCommon {
     /** The original, unsanitized HTML as authored. */
     unsafe: string;
 }
-/** A pass-through wrapper around a native Gutenberg block (`etch/passthrough`). */
+/**
+ * A pass-through wrapper around a native Gutenberg block (`etch/passthrough`).
+ *
+ * **Not registered on every build** — this one is WordPress-only. Check
+ * `etch.environment.blockTypes` before authoring it; creating a block type the
+ * runtime does not register is rejected.
+ */
 interface EtchPassthroughBlockJson extends EtchBlockCommon {
     type: 'etch/passthrough';
     /** The wrapped Gutenberg block. */
@@ -402,8 +419,8 @@ interface EtchPassthroughBlockJson extends EtchBlockCommon {
  * time, such as a content-type field. Its children are the resolved JSON, so it
  * accepts no authored children.
  *
- * **Not registered on every build** — this one is Studio-only; creating a block
- * type the runtime does not register is rejected.
+ * **Not registered on every build** — this one is Studio-only. Check
+ * `etch.environment.blockTypes` before authoring it.
  */
 interface EtchRenderBlockJson extends EtchBlockCommon {
     type: 'etch/render';
@@ -484,9 +501,9 @@ interface BlockPatch {
     /** Replace the text content. Only valid on text blocks. */
     text?: string;
     /**
-     * Re-point what the block resolves at: the expression an `etch/loop` block
-     * iterates over, or the one an `etch/render` block renders. Only valid on
-     * block types that carry a `target`.
+     * Re-point what the block resolves at: the iterated expression of an
+     * `etch/loop` block, or the rendered expression of an `etch/render` block.
+     * Only valid on those two types.
      */
     target?: string;
 }
@@ -662,6 +679,169 @@ interface EtchBlocksApi {
     saveComponentEditModeAsync(): Promise<void>;
 }
 
+/**
+ * What this Etch runtime actually is, and which optional surfaces it backs.
+ *
+ * Etch ships as more than one product against **one** contract: `etch-wp` runs
+ * inside WordPress, `etch-studio` is standalone. They expose the same `etch`
+ * namespaces, but a namespace can be declared and not implemented — those
+ * methods throw `EtchApiError` with code `NOT_AVAILABLE`.
+ *
+ * `etch.environment` is how a caller finds that out **without** calling and
+ * catching. It is deliberately a description of the runtime rather than of the
+ * product: prefer `capabilities.loops` over `product === 'etch-wp'`, because
+ * capabilities move between products over time (the data manager, for one, is
+ * on its way to WordPress) while a product check silently rots the day they do.
+ */
+/** Which build of Etch is running. Identity — not a capability check. */
+type EtchProduct = 'etch-wp' | 'etch-studio' | (string & {});
+/**
+ * Optional surfaces a runtime may or may not back.
+ *
+ * `loops` and `dataSources` are the two dynamic-data models, and they decide
+ * how an `etch/loop` block is authored — check which one you are on before
+ * writing one:
+ *
+ * - `loops` — a registry of named loop definitions. A loop block binds to one
+ *   by `loopId` (plus `$`-prefixed `loopParams`), and `target` is an optional
+ *   sub-path within it.
+ * - `dataSources` — named, typed project sources (`json`, `api`, `js`), reached
+ *   through a `data('key')` expression. A loop block carries **only** a
+ *   required `target`, and that target is any *dynamic expression* yielding a
+ *   list — a data source, a path into one (`data('products').items`), nested
+ *   data from an enclosing loop (`item.tags`), or a generated list
+ *   (`range(1, 10)`). There is no `loopId`/`loopParams`. This model supersedes
+ *   `loops` and is expected on both products eventually.
+ *
+ * The rest:
+ *
+ * - `fields` — `etch.fields.*` is backed by a real field store.
+ * - `templates` — template posts exist and `navigation.goTo('templates')` works.
+ * - `wpMedia` — media ids resolve against the **WordPress media library**, so a
+ *   URL can be turned into an id through `/wp/v2/media`. Without it the ids are
+ *   the product's own asset store instead. Either way an `etch/dynamic-image`
+ *   block binds the same: a numeric `mediaId` attribute.
+ */
+type EtchCapability = 'loops' | 'dataSources' | 'fields' | 'templates' | 'wpMedia';
+/**
+ * Capability map. Every key is optional on purpose: a runtime older than a
+ * capability's introduction simply omits it, so **absent means unavailable**.
+ * Test with `=== true` rather than truthiness of a possibly-missing key.
+ */
+type EtchCapabilities = Readonly<Partial<Record<EtchCapability, boolean>>>;
+/** Runtime self-description, exposed as `etch.environment`. */
+interface EtchEnvironment {
+    /**
+     * Which build this is — identity, for display and diagnostics. Every
+     * behavioral decision belongs to {@link capabilities} instead; a product
+     * check goes wrong the moment a capability moves between products.
+     */
+    readonly product: EtchProduct;
+    /** Which optional surfaces this runtime actually backs. */
+    readonly capabilities: EtchCapabilities;
+    /**
+     * Every block `type` this runtime can construct, sorted. Read this instead
+     * of assuming a block exists: `etch/passthrough` is WordPress-only and
+     * `etch/render` is Studio-only, and the list grows with each release.
+     */
+    readonly blockTypes: readonly string[];
+}
+
+/**
+ * Project data sources and the `etch.dataSources` API surface.
+ *
+ * Data sources are the `dataSources` capability's model of dynamic data, and
+ * they supersede {@link EtchLoopsApi | loops}: a named, typed source is defined
+ * once for the project and read anywhere an expression is accepted, through
+ * `data('key')`. A loop block points its `target` at one of those expressions
+ * rather than binding to a loop id.
+ *
+ * Check `etch.environment.capabilities.dataSources === true` before using this
+ * namespace — a runtime without it omits the whole thing.
+ */
+/**
+ * A source type. The three built-ins are listed; the registry behind the
+ * runtime is open, so a host may serve types this contract has never heard of.
+ */
+type EtchDataSourceType = 'json' | 'api' | 'js' | (string & {});
+/**
+ * A project data source, identified by its `key` — the name `data('key')`
+ * calls it by.
+ */
+interface EtchDataSource {
+    /**
+     * Stable identifier used in expressions: `data('products')`. Unique within
+     * the project, and part of every authored expression that reads the source,
+     * so renaming one breaks those expressions.
+     */
+    key: string;
+    /** Display name shown in the data manager. */
+    name: string;
+    /** Which kind of source this is; decides how `metadata` is read. */
+    type: EtchDataSourceType;
+    /**
+     * Type-specific configuration. The built-in types read:
+     *
+     * - `json` — `{ data: unknown }`, the payload served verbatim.
+     * - `api` — `{ url: string; method?: string; headers?: [string, string][] }`,
+     *   fetched and parsed as JSON. A non-OK response fails the source.
+     * - `js` — `{ code: string }`, a function body run in a sandbox. Arguments
+     *   passed by the expression (`data('rows', 5)`) arrive as `args`.
+     */
+    metadata: Record<string, unknown>;
+}
+/** Fields of an {@link EtchDataSource} that `updateAsync` can change. */
+type EtchDataSourcePatch = Partial<EtchDataSource>;
+/**
+ * Project data sources: definitions, and resolving one to its value.
+ *
+ * Reads are synchronous — the project's sources are loaded before `window.etch`
+ * exists. Writes persist to the backend immediately (they do not wait for
+ * {@link Etch.saveAsync}) and drop any value already resolved from the source,
+ * so the canvas re-reads it.
+ */
+interface EtchDataSourcesApi {
+    /** Every data source defined for this project. */
+    list(): EtchDataSource[];
+    /**
+     * One data source by key.
+     * @throws {EtchApiError} `DATA_SOURCE_NOT_FOUND`
+     */
+    get(key: string): EtchDataSource;
+    /**
+     * Fuzzy-search data sources by `name` or `key`, ranked best-first. Returns
+     * an empty array for a blank query or when nothing matches.
+     */
+    findDataSource(query: string): EtchDataSource[];
+    /**
+     * Define a new data source.
+     * @throws {EtchApiError} `INVALID_ARGUMENT` on a malformed source, or when
+     * the key is already taken.
+     */
+    createAsync(source: EtchDataSource): Promise<EtchDataSource>;
+    /**
+     * Change an existing data source. Only the fields present are applied.
+     * @throws {EtchApiError} `DATA_SOURCE_NOT_FOUND`
+     */
+    updateAsync(key: string, patch: EtchDataSourcePatch): Promise<EtchDataSource>;
+    /**
+     * Delete a data source. Expressions still naming it resolve to `undefined`.
+     * @throws {EtchApiError} `DATA_SOURCE_NOT_FOUND`
+     */
+    deleteAsync(key: string): Promise<void>;
+    /**
+     * Resolve a data source to its value, exactly as `data('key', ...args)`
+     * would on the canvas — read this before authoring the property paths that
+     * depend on its shape.
+     *
+     * A source that fails resolves to `undefined` rather than rejecting, which
+     * is what the render sees too.
+     *
+     * @throws {EtchApiError} `DATA_SOURCE_NOT_FOUND`
+     */
+    resolveAsync(key: string, ...args: unknown[]): Promise<unknown>;
+}
+
 /**
  * Global style (CSS rule) shapes and the `etch.styles` API surface.
  */
@@ -1461,6 +1641,16 @@ interface Etch {
     blocks: EtchBlocksApi;
     /** Loop definitions and binding loops to blocks. */
     loops: EtchLoopsApi;
+    /**
+     * Project data sources — the `dataSources` capability's model of dynamic
+     * data, which supersedes {@link loops}.
+     *
+     * Optional: a runtime that does not back the capability omits the namespace
+     * entirely rather than stubbing it, so check
+     * `environment.capabilities.dataSources === true` (or the presence of this
+     * property) before calling it.
+     */
+    dataSources?: EtchDataSourcesApi;
     /** Global style (CSS) definitions and CSS variables. */
     styles: EtchStylesApi;
     /** Global stylesheets and `@custom-media` definitions. */
@@ -1510,6 +1700,16 @@ interface Etch {
     readonly apiVersion: string;
     /** The Etch builder (product) version, for capability checks. */
     readonly version: string;
+    /**
+     * What this runtime is and which optional surfaces it backs. Read this
+     * before using `loops`, `fields`, templates or WordPress media, and before
+     * authoring a block type that may not exist here.
+     *
+     * Optional: runtimes older than the descriptor omit it. Treat a missing
+     * `environment` as `etch-wp` on WordPress with everything available, which
+     * is what every runtime that predates it was.
+     */
+    readonly environment?: EtchEnvironment;
 }
 
 declare global {
@@ -1555,7 +1755,7 @@ declare function getEtch(options?: ConnectOptions): Etch;
  * runtimes still type-check as `EtchApiErrorCode` while keeping autocomplete for
  * the known values.
  */
-type EtchApiErrorCode = 'BLOCK_NOT_FOUND' | 'WRONG_BLOCK_TYPE' | 'READONLY' | 'INVALID_ARGUMENT' | 'LOOP_NOT_FOUND' | 'STYLE_NOT_FOUND' | 'STYLESHEET_NOT_FOUND' | 'COMPONENT_NOT_FOUND' | 'POST_NOT_FOUND' | 'OPERATION_FAILED' | 'NOT_AVAILABLE' | (string & {});
+type EtchApiErrorCode = 'BLOCK_NOT_FOUND' | 'WRONG_BLOCK_TYPE' | 'READONLY' | 'INVALID_ARGUMENT' | 'LOOP_NOT_FOUND' | 'DATA_SOURCE_NOT_FOUND' | 'STYLE_NOT_FOUND' | 'STYLESHEET_NOT_FOUND' | 'COMPONENT_NOT_FOUND' | 'POST_NOT_FOUND' | 'OPERATION_FAILED' | 'NOT_AVAILABLE' | (string & {});
 /** Error thrown by the public Etch API (and by this client). */
 declare class EtchApiError extends Error {
     readonly code: EtchApiErrorCode;
@@ -1574,4 +1774,4 @@ declare function isEtchApiError(value: unknown): value is EtchApiError;
  */
 declare const ETCH_API_VERSION = "0.x";
 
-export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, type EtchAiApi, 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 EtchRenderBlockJson, type EtchSkillsApi, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type ExternalAiState, 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 SkillDetail, type SkillSummary, type StringComponentProperty, type StyleListFilter, type StylePatch, type StyleSelectorType, type StyleSummary, type StylesheetInput, type StylesheetPatch, type StylesheetSummary, type StylesheetType, type TaxQueryItem, type TemplateSummary, type WpQueryArgs, type WpTermsArgs, type WpUsersArgs, getEtch, isEtchApiError, isEtchAvailable };
+export { type ArrayComponentProperty, type BlockLoopBinding, type BlockPatch, type BooleanComponentProperty, type BooleanParam, type BridgeConnectOptions, type ClassComponentProperty, type ColorScheme, type ComponentPatch, type ComponentProperty, type ComponentPropertyBase, type ConditionComponentProperty, type ConnectOptions, type CopyObject, type CustomField, type CustomFieldAssignment, type CustomFieldGroup, type CustomFieldType, ETCH_API_VERSION, type Etch, type EtchAiApi, EtchApiError, type EtchApiErrorCode, type EtchBlockCommon, type EtchBlockContext, type EtchBlockJson, type EtchBlockOptions, type EtchBlockScript, type EtchBlockType, type EtchBlockTypeName, type EtchBlocksApi, type EtchBridgeConnection, type EtchCapabilities, type EtchCapability, type EtchComponentBlockJson, type EtchComponentsApi, type EtchConditionBlockJson, type EtchDataSource, type EtchDataSourcePatch, type EtchDataSourceType, type EtchDataSourcesApi, type EtchDynamicElementBlockJson, type EtchDynamicImageBlockJson, type EtchElementBlockJson, type EtchEnvironment, type EtchFieldsApi, type EtchHistoryApi, type EtchHtmlAttributes, type EtchLoop, type EtchLoopBlockJson, type EtchLoopConfig, type EtchLoopObj, type EtchLoopsApi, type EtchNavigationApi, type EtchPassthroughBlockJson, type EtchPostContentBlockJson, type EtchProduct, type EtchRawHtmlBlockJson, type EtchRenderBlockJson, type EtchSkillsApi, type EtchSlotContentBlockJson, type EtchSlotPlaceholderBlockJson, type EtchStylesApi, type EtchStylesheetsApi, type EtchSvgBlockJson, type EtchTextBlockJson, type EtchUiApi, type ExternalAiState, 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 SkillDetail, type SkillSummary, 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.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts","../src/version.ts","../src/client.ts"],"names":[],"mappings":";AAyBO,IAAM,YAAA,GAAN,cAA2B,KAAA,CAAM;AAAA,EAGvC,WAAA,CAAY,MAAwB,OAAA,EAAiB;AACpD,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,cAAA;AACZ,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AAAA,EACb;AACD;AAGO,SAAS,eAAe,KAAA,EAAuC;AACrE,EAAA,OACC,KAAA,YAAiB,YAAA,IAChB,KAAA,EAAiB,IAAA,KAAS,cAAA;AAE7B;;;ACjCO,IAAM,gBAAA,GAAmB;;;ACIhC,SAAS,QAAA,GAA6B;AACrC,EAAA,MAAM,KAAA,GAAQ,UAAA;AACd,EAAA,OAAO,KAAA,CAAM,IAAA;AACd;AAMO,SAAS,eAAA,GAA2B;AAC1C,EAAA,OAAO,UAAS,KAAM,MAAA;AACvB;AAGA,SAAS,QAAQ,OAAA,EAAgC;AAChD,EAAA,MAAM,KAAA,GAAQ,WAAA,CAAY,IAAA,CAAK,OAAO,CAAA;AACtC,EAAA,OAAO,KAAA,GAAQ,MAAA,CAAO,KAAA,CAAM,CAAC,CAAC,CAAA,GAAI,IAAA;AACnC;AAOA,SAAS,kBAAA,CAAmB,WAAmB,OAAA,EAAuB;AACrE,EAAA,MAAM,IAAA,GAAO,QAAQ,SAAS,CAAA;AAC9B,EAAA,MAAM,IAAA,GAAO,QAAQ,OAAO,CAAA;AAC5B,EAAA,IAAI,IAAA,KAAS,IAAA,IAAQ,IAAA,KAAS,IAAA,IAAQ,SAAS,IAAA,EAAM;AACrD,EAAA,OAAA,CAAQ,IAAA;AAAA,IACP,CAAA,qDAAA,EAAwD,SAAS,CAAA,wBAAA,EAC9C,OAAO,CAAA,sBAAA;AAAA,GAC3B;AACD;AAsBO,SAAS,OAAA,CAAQ,OAAA,GAA0B,EAAC,EAAS;AAC3D,EAAA,MAAM,OAAO,QAAA,EAAS;AACtB,EAAA,IAAI,CAAC,IAAA,EAAM;AACV,IAAA,MAAM,IAAI,YAAA;AAAA,MACT,eAAA;AAAA,MACA;AAAA,KAED;AAAA,EACD;AAEA,EAAA,IAAI,OAAO,IAAA,CAAK,OAAA,KAAY,UAAA,EAAY;AACvC,IAAA,OAAO,IAAA,CAAK,QAAQ,OAAO,CAAA;AAAA,EAC5B;AAEA,EAAA,IAAI,QAAQ,UAAA,EAAY;AACvB,IAAA,kBAAA;AAAA,MACC,OAAA,CAAQ,UAAA;AAAA,MACR,KAAK,UAAA,IAAc;AAAA,KACpB;AAAA,EACD;AACA,EAAA,OAAO,IAAA;AACR","file":"index.js","sourcesContent":["/**\n * Error codes thrown by the public `window.etch` API.\n *\n * The API throws typed errors (rather than returning sentinels) so that AI\n * assistants and plugin authors can `try`/`catch` and react to a precise cause.\n *\n * The union ends with `(string & {})` so that codes added by newer Etch\n * runtimes still type-check as `EtchApiErrorCode` while keeping autocomplete for\n * the known values.\n */\nexport type EtchApiErrorCode =\n\t| 'BLOCK_NOT_FOUND'\n\t| 'WRONG_BLOCK_TYPE'\n\t| 'READONLY'\n\t| 'INVALID_ARGUMENT'\n\t| 'LOOP_NOT_FOUND'\n\t| 'STYLE_NOT_FOUND'\n\t| 'STYLESHEET_NOT_FOUND'\n\t| 'COMPONENT_NOT_FOUND'\n\t| 'POST_NOT_FOUND'\n\t| 'OPERATION_FAILED'\n\t| 'NOT_AVAILABLE'\n\t| (string & {});\n\n/** Error thrown by the public Etch API (and by this client). */\nexport class EtchApiError extends Error {\n\treadonly code: EtchApiErrorCode;\n\n\tconstructor(code: EtchApiErrorCode, message: string) {\n\t\tsuper(message);\n\t\tthis.name = 'EtchApiError';\n\t\tthis.code = code;\n\t}\n}\n\n/** Narrow an unknown caught value to an {@link EtchApiError}. */\nexport function isEtchApiError(value: unknown): value is EtchApiError {\n\treturn (\n\t\tvalue instanceof EtchApiError ||\n\t\t(value as Error)?.name === 'EtchApiError'\n\t);\n}\n","/**\n * Version of the Etch scripting **contract** this package targets, independent\n * of the Etch product version and of this package's own npm version.\n *\n * `0.x` signals the surface is **experimental** and may change without a major\n * bump until it stabilizes. It matches the value returned by the runtime's\n * {@link Etch.apiVersion} getter on `window.etch`.\n */\nexport const ETCH_API_VERSION = '0.x';\n","import type { ConnectOptions, Etch } from './contract';\nimport { EtchApiError } from './errors';\nimport { ETCH_API_VERSION } from './version';\n\ndeclare global {\n\tinterface Window {\n\t\t/** The Etch scripting API, present once the builder has loaded. */\n\t\tetch?: Etch;\n\t}\n}\n\n/** Read `window.etch` from whatever global object exists, or `undefined`. */\nfunction readEtch(): Etch | undefined {\n\tconst scope = globalThis as { etch?: Etch };\n\treturn scope.etch;\n}\n\n/**\n * Whether the Etch scripting API is present on the page. Use this to guard code\n * that should no-op when not running inside the builder.\n */\nexport function isEtchAvailable(): boolean {\n\treturn readEtch() !== undefined;\n}\n\n/** The major version number of a semver-ish string, or `null` if unparseable. */\nfunction majorOf(version: string): number | null {\n\tconst match = /^\\D*(\\d+)/.exec(version);\n\treturn match ? Number(match[1]) : null;\n}\n\n/**\n * Best-effort compatibility check for `0.x` runtimes that have no native\n * `connect()`. Warns (does not throw) when the requested major differs from the\n * runtime's, so experimental consumers aren't hard-blocked.\n */\nfunction warnIfIncompatible(requested: string, runtime: string): void {\n\tconst want = majorOf(requested);\n\tconst have = majorOf(runtime);\n\tif (want === null || have === null || want === have) return;\n\tconsole.warn(\n\t\t`[@digital-gravy/etch-public-api] Requested Etch API v${requested} but the ` +\n\t\t\t`page provides v${runtime}. Behavior may differ.`\n\t);\n}\n\n/**\n * Acquire the Etch scripting API from the page.\n *\n * The runtime lives on `window.etch` (injected by the builder); this returns it\n * typed. When the page exposes a future stable runtime with a native\n * `connect()`, version negotiation is delegated to it. On today's `0.x`\n * runtime, the global is returned directly after a best-effort version check.\n *\n * @throws {EtchApiError} `NOT_AVAILABLE` when the builder is not present.\n *\n * @example\n * ```ts\n * import { getEtch } from '@etchwp/public-api';\n *\n * const etch = getEtch();\n * const ids = etch.blocks.find({ type: 'text' });\n * etch.blocks.setText(ids[0], 'Hello');\n * await etch.saveAsync();\n * ```\n */\nexport function getEtch(options: ConnectOptions = {}): Etch {\n\tconst etch = readEtch();\n\tif (!etch) {\n\t\tthrow new EtchApiError(\n\t\t\t'NOT_AVAILABLE',\n\t\t\t'window.etch is not available. The Etch builder is not loaded on this page, ' +\n\t\t\t\t'or getEtch() ran before it finished initializing.'\n\t\t);\n\t}\n\n\tif (typeof etch.connect === 'function') {\n\t\treturn etch.connect(options);\n\t}\n\n\tif (options.apiVersion) {\n\t\twarnIfIncompatible(\n\t\t\toptions.apiVersion,\n\t\t\tetch.apiVersion ?? ETCH_API_VERSION\n\t\t);\n\t}\n\treturn etch;\n}\n"]}
+{"version":3,"sources":["../src/errors.ts","../src/version.ts","../src/client.ts"],"names":[],"mappings":";AA0BO,IAAM,YAAA,GAAN,cAA2B,KAAA,CAAM;AAAA,EAGvC,WAAA,CAAY,MAAwB,OAAA,EAAiB;AACpD,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,cAAA;AACZ,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AAAA,EACb;AACD;AAGO,SAAS,eAAe,KAAA,EAAuC;AACrE,EAAA,OACC,KAAA,YAAiB,YAAA,IAChB,KAAA,EAAiB,IAAA,KAAS,cAAA;AAE7B;;;AClCO,IAAM,gBAAA,GAAmB;;;ACIhC,SAAS,QAAA,GAA6B;AACrC,EAAA,MAAM,KAAA,GAAQ,UAAA;AACd,EAAA,OAAO,KAAA,CAAM,IAAA;AACd;AAMO,SAAS,eAAA,GAA2B;AAC1C,EAAA,OAAO,UAAS,KAAM,MAAA;AACvB;AAGA,SAAS,QAAQ,OAAA,EAAgC;AAChD,EAAA,MAAM,KAAA,GAAQ,WAAA,CAAY,IAAA,CAAK,OAAO,CAAA;AACtC,EAAA,OAAO,KAAA,GAAQ,MAAA,CAAO,KAAA,CAAM,CAAC,CAAC,CAAA,GAAI,IAAA;AACnC;AAOA,SAAS,kBAAA,CAAmB,WAAmB,OAAA,EAAuB;AACrE,EAAA,MAAM,IAAA,GAAO,QAAQ,SAAS,CAAA;AAC9B,EAAA,MAAM,IAAA,GAAO,QAAQ,OAAO,CAAA;AAC5B,EAAA,IAAI,IAAA,KAAS,IAAA,IAAQ,IAAA,KAAS,IAAA,IAAQ,SAAS,IAAA,EAAM;AACrD,EAAA,OAAA,CAAQ,IAAA;AAAA,IACP,CAAA,qDAAA,EAAwD,SAAS,CAAA,wBAAA,EAC9C,OAAO,CAAA,sBAAA;AAAA,GAC3B;AACD;AAsBO,SAAS,OAAA,CAAQ,OAAA,GAA0B,EAAC,EAAS;AAC3D,EAAA,MAAM,OAAO,QAAA,EAAS;AACtB,EAAA,IAAI,CAAC,IAAA,EAAM;AACV,IAAA,MAAM,IAAI,YAAA;AAAA,MACT,eAAA;AAAA,MACA;AAAA,KAED;AAAA,EACD;AAEA,EAAA,IAAI,OAAO,IAAA,CAAK,OAAA,KAAY,UAAA,EAAY;AACvC,IAAA,OAAO,IAAA,CAAK,QAAQ,OAAO,CAAA;AAAA,EAC5B;AAEA,EAAA,IAAI,QAAQ,UAAA,EAAY;AACvB,IAAA,kBAAA;AAAA,MACC,OAAA,CAAQ,UAAA;AAAA,MACR,KAAK,UAAA,IAAc;AAAA,KACpB;AAAA,EACD;AACA,EAAA,OAAO,IAAA;AACR","file":"index.js","sourcesContent":["/**\n * Error codes thrown by the public `window.etch` API.\n *\n * The API throws typed errors (rather than returning sentinels) so that AI\n * assistants and plugin authors can `try`/`catch` and react to a precise cause.\n *\n * The union ends with `(string & {})` so that codes added by newer Etch\n * runtimes still type-check as `EtchApiErrorCode` while keeping autocomplete for\n * the known values.\n */\nexport type EtchApiErrorCode =\n\t| 'BLOCK_NOT_FOUND'\n\t| 'WRONG_BLOCK_TYPE'\n\t| 'READONLY'\n\t| 'INVALID_ARGUMENT'\n\t| 'LOOP_NOT_FOUND'\n\t| 'DATA_SOURCE_NOT_FOUND'\n\t| 'STYLE_NOT_FOUND'\n\t| 'STYLESHEET_NOT_FOUND'\n\t| 'COMPONENT_NOT_FOUND'\n\t| 'POST_NOT_FOUND'\n\t| 'OPERATION_FAILED'\n\t| 'NOT_AVAILABLE'\n\t| (string & {});\n\n/** Error thrown by the public Etch API (and by this client). */\nexport class EtchApiError extends Error {\n\treadonly code: EtchApiErrorCode;\n\n\tconstructor(code: EtchApiErrorCode, message: string) {\n\t\tsuper(message);\n\t\tthis.name = 'EtchApiError';\n\t\tthis.code = code;\n\t}\n}\n\n/** Narrow an unknown caught value to an {@link EtchApiError}. */\nexport function isEtchApiError(value: unknown): value is EtchApiError {\n\treturn (\n\t\tvalue instanceof EtchApiError ||\n\t\t(value as Error)?.name === 'EtchApiError'\n\t);\n}\n","/**\n * Version of the Etch scripting **contract** this package targets, independent\n * of the Etch product version and of this package's own npm version.\n *\n * `0.x` signals the surface is **experimental** and may change without a major\n * bump until it stabilizes. It matches the value returned by the runtime's\n * {@link Etch.apiVersion} getter on `window.etch`.\n */\nexport const ETCH_API_VERSION = '0.x';\n","import type { ConnectOptions, Etch } from './contract';\nimport { EtchApiError } from './errors';\nimport { ETCH_API_VERSION } from './version';\n\ndeclare global {\n\tinterface Window {\n\t\t/** The Etch scripting API, present once the builder has loaded. */\n\t\tetch?: Etch;\n\t}\n}\n\n/** Read `window.etch` from whatever global object exists, or `undefined`. */\nfunction readEtch(): Etch | undefined {\n\tconst scope = globalThis as { etch?: Etch };\n\treturn scope.etch;\n}\n\n/**\n * Whether the Etch scripting API is present on the page. Use this to guard code\n * that should no-op when not running inside the builder.\n */\nexport function isEtchAvailable(): boolean {\n\treturn readEtch() !== undefined;\n}\n\n/** The major version number of a semver-ish string, or `null` if unparseable. */\nfunction majorOf(version: string): number | null {\n\tconst match = /^\\D*(\\d+)/.exec(version);\n\treturn match ? Number(match[1]) : null;\n}\n\n/**\n * Best-effort compatibility check for `0.x` runtimes that have no native\n * `connect()`. Warns (does not throw) when the requested major differs from the\n * runtime's, so experimental consumers aren't hard-blocked.\n */\nfunction warnIfIncompatible(requested: string, runtime: string): void {\n\tconst want = majorOf(requested);\n\tconst have = majorOf(runtime);\n\tif (want === null || have === null || want === have) return;\n\tconsole.warn(\n\t\t`[@digital-gravy/etch-public-api] Requested Etch API v${requested} but the ` +\n\t\t\t`page provides v${runtime}. Behavior may differ.`\n\t);\n}\n\n/**\n * Acquire the Etch scripting API from the page.\n *\n * The runtime lives on `window.etch` (injected by the builder); this returns it\n * typed. When the page exposes a future stable runtime with a native\n * `connect()`, version negotiation is delegated to it. On today's `0.x`\n * runtime, the global is returned directly after a best-effort version check.\n *\n * @throws {EtchApiError} `NOT_AVAILABLE` when the builder is not present.\n *\n * @example\n * ```ts\n * import { getEtch } from '@etchwp/public-api';\n *\n * const etch = getEtch();\n * const ids = etch.blocks.find({ type: 'text' });\n * etch.blocks.setText(ids[0], 'Hello');\n * await etch.saveAsync();\n * ```\n */\nexport function getEtch(options: ConnectOptions = {}): Etch {\n\tconst etch = readEtch();\n\tif (!etch) {\n\t\tthrow new EtchApiError(\n\t\t\t'NOT_AVAILABLE',\n\t\t\t'window.etch is not available. The Etch builder is not loaded on this page, ' +\n\t\t\t\t'or getEtch() ran before it finished initializing.'\n\t\t);\n\t}\n\n\tif (typeof etch.connect === 'function') {\n\t\treturn etch.connect(options);\n\t}\n\n\tif (options.apiVersion) {\n\t\twarnIfIncompatible(\n\t\t\toptions.apiVersion,\n\t\t\tetch.apiVersion ?? ETCH_API_VERSION\n\t\t);\n\t}\n\treturn etch;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@digital-gravy/etch-public-api",
-	"version": "0.9.0",
+	"version": "0.11.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",
 	"repository": {