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

package/README.md

@@ -26,13 +26,13 @@ Acquire it with `getEtch()`, guarded by `isEtchAvailable()` for code that might
 run outside the builder:
 
 ```ts
-import { getEtch, isEtchAvailable } from "@digital-gravy/etch-public-api";
+import { getEtch, isEtchAvailable } from '@digital-gravy/etch-public-api';
 
 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");
+	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');
 }
 ```
 
@@ -41,15 +41,16 @@ 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";
+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 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();
@@ -59,12 +60,12 @@ const etch = await whenEtchReady();
 
 ```ts
 // Read
-const textIds = etch.blocks.find({ type: "etch/text" });
+const textIds = etch.blocks.find({ type: 'etch/text' });
 const json = etch.blocks.getJson(textIds[0]);
 
 // Mutate (routes through the same guarded paths as the UI; undo/redo works)
-etch.blocks.setText(textIds[0], "Hello world");
-etch.blocks.addClass(textIds[0], "lead");
+etch.blocks.setText(textIds[0], 'Hello world');
+etch.blocks.addClass(textIds[0], 'lead');
 
 // Persist (blocks/styles wait for save; stylesheets/components/fields persist immediately)
 await etch.saveAsync();
@@ -74,22 +75,22 @@ await etch.saveAsync();
 
 ```ts
 // Create a class or id rule
-const styleId = etch.styles.create(".lead", "font-size: 1.25rem;");
+const styleId = etch.styles.create('.lead', 'font-size: 1.25rem;');
 
 // Find existing styles by selector type
-const classStyles = etch.styles.list({ type: "class" });
-const myStyle = etch.styles.list().find((s) => s.selector === ".lead");
+const classStyles = etch.styles.list({ type: 'class' });
+const myStyle = etch.styles.list().find((s) => s.selector === '.lead');
 console.log(myStyle?.id); // the id you pass to blocks.addClass etc.
 
 // Global CSS custom properties (default collection)
-etch.styles.setVariable("--brand", "#0af");
-etch.styles.getVariable("--brand"); // "#0af"
+etch.styles.setVariable('--brand', '#0af');
+etch.styles.getVariable('--brand'); // "#0af"
 
 // Variable methods accept an optional collection for multi-collection :root setups
-etch.styles.setVariable("--brand", "#0af", "theme-a");
-etch.styles.getVariable("--brand", "theme-a"); // "#0af"
-etch.styles.listVariables("theme-a");
-etch.styles.removeVariable("--brand", "theme-a");
+etch.styles.setVariable('--brand', '#0af', 'theme-a');
+etch.styles.getVariable('--brand', 'theme-a'); // "#0af"
+etch.styles.listVariables('theme-a');
+etch.styles.removeVariable('--brand', 'theme-a');
 ```
 
 > **Note:** The `collection` field on style **objects** (`StyleSummary`) and the
@@ -106,7 +107,7 @@ for direct inspection or mutation, then save and exit when done:
 
 ```ts
 // Find a component block
-const [compId] = etch.blocks.find({ type: "etch/component" });
+const [compId] = etch.blocks.find({ type: 'etch/component' });
 
 // Enter edit mode — the component's block tree becomes accessible
 etch.blocks.enterComponentEditMode(compId);
@@ -137,19 +138,19 @@ key must be a property declared by the component definition, or the call throws
 `INVALID_ARGUMENT`.
 
 ```ts
-const [cardId] = etch.blocks.find({ type: "etch/component" });
+const [cardId] = etch.blocks.find({ type: 'etch/component' });
 
 // Set a prop the component declares
-etch.blocks.setAttribute(cardId, "title", "Hello world");
+etch.blocks.setAttribute(cardId, 'title', 'Hello world');
 
 // Read it back
-etch.blocks.getAttribute(cardId, "title"); // "Hello world"
+etch.blocks.getAttribute(cardId, 'title'); // "Hello world"
 
 // Or patch several props at once
-etch.blocks.update(cardId, { attributes: { title: "Hi", variant: "primary" } });
+etch.blocks.update(cardId, { attributes: { title: 'Hi', variant: 'primary' } });
 
 // An undeclared key is rejected
-etch.blocks.setAttribute(cardId, "notAProp", "x"); // ✗ throws INVALID_ARGUMENT
+etch.blocks.setAttribute(cardId, 'notAProp', 'x'); // ✗ throws INVALID_ARGUMENT
 ```
 
 > Values are stored as-is. For typed props such as classes or repeater/group
@@ -161,14 +162,14 @@ 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"
+	}
 }
 ```
 
@@ -182,8 +183,8 @@ experimental, **prefer feature detection** over version comparison:
 
 ```ts
 const etch = getEtch();
-if (typeof etch.blocks.someNewMethod === "function") {
-  // safe to use
+if (typeof etch.blocks.someNewMethod === 'function') {
+	// safe to use
 }
 ```
 
@@ -194,7 +195,7 @@ targets, and failing fast when the runtime can't satisfy it:
 
 ```ts
 // Reserved API — shape of versioned access once the contract is stable:
-const etch = getEtch({ apiVersion: "^1.0", id: "my-plugin" });
+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).
 ```
@@ -212,19 +213,19 @@ 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);
+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", // ✗ type error
+	type: 'etch/text',
+	version: 1,
+	context: {},
+	children: [],
+	tag: 'div' // ✗ type error
 });
 ```
 
@@ -233,22 +234,24 @@ etch.blocks.create({
 Some block types recognise **special attributes** in addition to standard HTML:
 
 **`etch/dynamic-image`** — rendered as `<img>`:
+
 - `mediaId` — WordPress attachment ID. Etch fetches the media object and uses its URL as `src`, overriding any explicit `src`. Supports dynamic expressions (e.g. `{post.featured_image_id}`).
 - `useSrcSet` — `"true"` to generate a responsive `srcset` from the media (requires `mediaId`).
 - `maximumSize` — WordPress image size slug (e.g. `"large"`, `"full"`) used when resolving the image. Defaults to `"full"`.
 
 ```ts
-etch.blocks.setAttribute(imgBlockId, "mediaId", "{post.featured_image_id}");
-etch.blocks.setAttribute(imgBlockId, "useSrcSet", "true");
+etch.blocks.setAttribute(imgBlockId, 'mediaId', '{post.featured_image_id}');
+etch.blocks.setAttribute(imgBlockId, 'useSrcSet', 'true');
 ```
 
 **`etch/svg`** — inline SVG:
+
 - `src` — URL of an external `.svg` file. Etch fetches and inlines the SVG at render time. Supports dynamic expressions.
 - `stripColors` — `"true"` to strip `fill` and `stroke` colour declarations from the fetched SVG, so CSS can drive its colours instead.
 
 ```ts
-etch.blocks.setAttribute(svgBlockId, "src", "/icons/logo.svg");
-etch.blocks.setAttribute(svgBlockId, "stripColors", "true");
+etch.blocks.setAttribute(svgBlockId, 'src', '/icons/logo.svg');
+etch.blocks.setAttribute(svgBlockId, 'stripColors', 'true');
 ```
 
 ### Types only
@@ -258,9 +261,9 @@ directly:
 
 ```ts
 import type {
-  PublicBlockJson,
-  EtchBlocksApi,
-} from "@digital-gravy/etch-public-api";
+	PublicBlockJson,
+	EtchBlocksApi
+} from '@digital-gravy/etch-public-api';
 ```
 
 You can also work against the global directly — the package augments
@@ -273,14 +276,14 @@ is imported.
 - `EtchApiError` / `isEtchApiError()` / `EtchApiErrorCode` — typed errors.
 - `ETCH_API_VERSION` — the contract version this package targets (`0.x`).
 - The full contract as exported types:
-  - **Blocks** — `Etch`, `EtchBlocksApi`, `EtchBlockJson`, `PublicBlockJson`, `FindBlocksPredicate`, `BlockPatch`, …
-  - **Styles** — `EtchStylesApi`, `StyleSummary`, `StyleListFilter`, `StyleSelectorType`, `StylePatch`
-  - **Stylesheets** — `EtchStylesheetsApi`, `StylesheetSummary`, `StylesheetInput`, `StylesheetPatch`
-  - **Components** — `EtchComponentsApi`, `PublicComponentSummary`, `PublicComponentJson`, `ComponentPatch`, `ComponentProperty`, …
-  - **Loops** — `EtchLoopsApi`, `EtchLoop`, `EtchLoopConfig`, `BlockLoopBinding`, …
-  - **Navigation** — `EtchNavigationApi`, `NavigationPlace`, `PostSummary`, `TemplateSummary`
-  - **Fields** — `EtchFieldsApi`, `CustomField`, `CustomFieldGroup`, …
-  - **UI / History** — `EtchUiApi`, `EtchHistoryApi`, `ColorScheme`
+    - **Blocks** — `Etch`, `EtchBlocksApi`, `EtchBlockJson`, `PublicBlockJson`, `FindBlocksPredicate`, `BlockPatch`, …
+    - **Styles** — `EtchStylesApi`, `StyleSummary`, `StyleListFilter`, `StyleSelectorType`, `StylePatch`
+    - **Stylesheets** — `EtchStylesheetsApi`, `StylesheetSummary`, `StylesheetInput`, `StylesheetPatch`
+    - **Components** — `EtchComponentsApi`, `PublicComponentSummary`, `PublicComponentJson`, `ComponentPatch`, `ComponentProperty`, …
+    - **Loops** — `EtchLoopsApi`, `EtchLoop`, `EtchLoopConfig`, `BlockLoopBinding`, …
+    - **Navigation** — `EtchNavigationApi`, `NavigationPlace`, `PostSummary`, `TemplateSummary`
+    - **Fields** — `EtchFieldsApi`, `CustomField`, `CustomFieldGroup`, …
+    - **UI / History** — `EtchUiApi`, `EtchHistoryApi`, `ColorScheme`
 
 ## Versioning
 

package/dist/index.cjs

@@ -47,7 +47,10 @@ function getEtch(options = {}) {
     return etch.connect(options);
   }
   if (options.apiVersion) {
-    warnIfIncompatible(options.apiVersion, etch.apiVersion ?? ETCH_API_VERSION);
+    warnIfIncompatible(
+      options.apiVersion,
+      etch.apiVersion ?? ETCH_API_VERSION
+    );
   }
   return etch;
 }

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,OAAO,KAAA,YAAiB,YAAA,IAAiB,KAAA,EAAiB,IAAA,KAAS,cAAA;AACpE;;;AC9BO,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;AAErD,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,CAAmB,OAAA,CAAQ,UAAA,EAAY,IAAA,CAAK,UAAA,IAAc,gBAAgB,CAAA;AAAA,EAC3E;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 value instanceof EtchApiError || (value as Error)?.name === 'EtchApiError';\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\t// eslint-disable-next-line no-console\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(options.apiVersion, etch.apiVersion ?? ETCH_API_VERSION);\n\t}\n\treturn etch;\n}\n"]}
+{"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"]}

package/dist/index.d.cts

@@ -12,7 +12,7 @@ interface EtchBlockContext {
      * panel. This is editor UI state, not document data — most scripts can
      * ignore it.
      */
-    structureState?: "open" | "closed";
+    structureState?: 'open' | 'closed';
     /** Whether the block is hidden (not rendered) on the canvas. */
     hidden?: boolean;
 }
@@ -64,7 +64,7 @@ interface EtchBlockCommon {
 }
 /** A text block (`etch/text`). */
 interface EtchTextBlockJson extends EtchBlockCommon {
-    type: "etch/text";
+    type: 'etch/text';
     /** The block's text content. */
     text: string;
 }
@@ -76,7 +76,7 @@ interface EtchTextBlockJson extends EtchBlockCommon {
  * `blocks.create()` / `blocks.replace()` ignore them.
  */
 interface EtchElementBlockJson extends EtchBlockCommon {
-    type: "etch/element";
+    type: 'etch/element';
     /** The HTML tag name, e.g. `div`, `p`, `h1`. */
     tag: string;
     /** HTML attributes. */
@@ -90,7 +90,7 @@ interface EtchElementBlockJson extends EtchBlockCommon {
  * {@link EtchElementBlockJson}).
  */
 interface EtchDynamicElementBlockJson extends EtchBlockCommon {
-    type: "etch/dynamic-element";
+    type: 'etch/dynamic-element';
     /** HTML attributes (the rendered tag is read from `attributes.tag`). */
     attributes: EtchHtmlAttributes;
 }
@@ -111,7 +111,7 @@ interface EtchDynamicElementBlockJson extends EtchBlockCommon {
  *   to `"full"` when omitted.
  */
 interface EtchDynamicImageBlockJson extends EtchBlockCommon {
-    type: "etch/dynamic-image";
+    type: 'etch/dynamic-image';
     /** HTML attributes (e.g. `src`, `alt`). */
     attributes: EtchHtmlAttributes;
 }
@@ -129,13 +129,13 @@ interface EtchDynamicImageBlockJson extends EtchBlockCommon {
  *   when `src` is set.
  */
 interface EtchSvgBlockJson extends EtchBlockCommon {
-    type: "etch/svg";
+    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";
+    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`. */
@@ -149,13 +149,13 @@ interface EtchLoopBlockJson extends EtchBlockCommon {
 }
 /** A conditional block (`etch/condition`); renders its children when the expression holds. */
 interface EtchConditionBlockJson extends EtchBlockCommon {
-    type: "etch/condition";
+    type: 'etch/condition';
     /** The condition expression. */
     conditionString: string;
 }
 /** An instance of a reusable component (`etch/component`). */
 interface EtchComponentBlockJson extends EtchBlockCommon {
-    type: "etch/component";
+    type: 'etch/component';
     /** Id of the component being instantiated. */
     componentId: number;
     /** Values bound to the component's properties. */
@@ -163,23 +163,23 @@ interface EtchComponentBlockJson extends EtchBlockCommon {
 }
 /** Content projected into a component slot (`etch/slot-content`). */
 interface EtchSlotContentBlockJson extends EtchBlockCommon {
-    type: "etch/slot-content";
+    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";
+    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";
+    type: 'etch/post-content';
 }
 /** A raw-HTML block (`etch/raw-html`). */
 interface EtchRawHtmlBlockJson extends EtchBlockCommon {
-    type: "etch/raw-html";
+    type: 'etch/raw-html';
     /** Sanitized HTML content. */
     content: string;
     /** The original, unsanitized HTML as authored. */
@@ -187,7 +187,7 @@ interface EtchRawHtmlBlockJson extends EtchBlockCommon {
 }
 /** A pass-through wrapper around a native Gutenberg block (`etch/passthrough`). */
 interface EtchPassthroughBlockJson extends EtchBlockCommon {
-    type: "etch/passthrough";
+    type: 'etch/passthrough';
     /** The wrapped Gutenberg block. */
     gutenbergBlock: GutenbergBlock;
 }
@@ -201,7 +201,7 @@ interface EtchPassthroughBlockJson extends EtchBlockCommon {
  */
 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"];
+type EtchBlockTypeName = EtchBlockJson['type'];
 /** Read-only identity attached to every serialized (read) block. */
 interface BlockIdentity {
     /** Stable id of this block. */
@@ -217,7 +217,7 @@ interface BlockIdentity {
  * 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";
+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). */
@@ -227,7 +227,7 @@ interface ReadOnlyBlockStyles {
  * 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 WithIdentity<B> = B extends EtchBlockCommon ? Omit<B, 'children'> & BlockIdentity & (B extends {
     type: StyledBlockType;
 } ? ReadOnlyBlockStyles : unknown) : never;
 /**
@@ -390,9 +390,9 @@ interface MetaQueryItem {
     /** The value(s) to compare against. */
     value: string | number | Array<string | number>;
     /** Comparison operator (defaults to `=`). */
-    compare?: "=" | "!=" | ">" | ">=" | "<" | "<=" | "LIKE" | "NOT LIKE" | "IN" | "NOT IN" | "BETWEEN" | "NOT BETWEEN" | "EXISTS" | "NOT EXISTS";
+    compare?: '=' | '!=' | '>' | '>=' | '<' | '<=' | 'LIKE' | 'NOT LIKE' | 'IN' | 'NOT IN' | 'BETWEEN' | 'NOT BETWEEN' | 'EXISTS' | 'NOT EXISTS';
     /** SQL type the value is cast to before comparison. */
-    type?: "NUMERIC" | "BINARY" | "CHAR" | "DATE" | "DATETIME" | "DECIMAL" | "SIGNED" | "TIME" | "UNSIGNED";
+    type?: 'NUMERIC' | 'BINARY' | 'CHAR' | 'DATE' | 'DATETIME' | 'DECIMAL' | 'SIGNED' | 'TIME' | 'UNSIGNED';
     [key: string]: unknown;
 }
 /**
@@ -403,11 +403,11 @@ interface TaxQueryItem {
     /** The taxonomy to query (e.g. `category`, `post_tag`). */
     taxonomy: string;
     /** Which term field `terms` refers to. */
-    field: "term_id" | "slug" | "name";
+    field: 'term_id' | 'slug' | 'name';
     /** The term(s) to match. */
     terms: string | number | Array<string | number>;
     /** How to match the terms (defaults to `IN`). */
-    operator?: "IN" | "NOT IN" | "AND";
+    operator?: 'IN' | 'NOT IN' | 'AND';
     /** Whether to include child terms of a hierarchical taxonomy. */
     include_children?: boolean;
     [key: string]: unknown;
@@ -429,11 +429,11 @@ interface WpQueryArgs {
     /** Alias of `paged` used in some contexts. */
     page?: NumericParam;
     /** Field to order results by. */
-    orderby?: "date" | "title" | "menu_order" | "rand" | "ID" | "author" | "name" | "modified" | "parent" | "comment_count" | (string & {});
+    orderby?: 'date' | 'title' | 'menu_order' | 'rand' | 'ID' | 'author' | 'name' | 'modified' | 'parent' | 'comment_count' | (string & {});
     /** Sort direction. */
-    order?: "ASC" | "DESC" | (string & {});
+    order?: 'ASC' | 'DESC' | (string & {});
     /** Post status to include. */
-    post_status?: "publish" | "pending" | "draft" | "auto-draft" | "future" | "private" | "inherit" | "trash" | (string & {});
+    post_status?: 'publish' | 'pending' | 'draft' | 'auto-draft' | 'future' | 'private' | 'inherit' | 'trash' | (string & {});
     /** Whether to ignore sticky posts. */
     ignore_sticky_posts?: BooleanParam;
     /** Author id (number) or username (string). */
@@ -459,9 +459,9 @@ interface WpTermsArgs {
     /** Taxonomy to fetch terms from. */
     taxonomy?: string;
     /** Field to order terms by. */
-    orderby?: "name" | "slug" | "term_group" | "term_id" | "description" | "count" | (string & {});
+    orderby?: 'name' | 'slug' | 'term_group' | 'term_id' | 'description' | 'count' | (string & {});
     /** Sort direction. */
-    order?: "ASC" | "DESC" | (string & {});
+    order?: 'ASC' | 'DESC' | (string & {});
     [key: string]: unknown;
 }
 /** WordPress user query arguments (extensible). */
@@ -477,9 +477,9 @@ interface WpUsersArgs {
     /** Columns the `search` keyword is matched against. */
     search_columns?: string[] | string;
     /** Field to order users by. */
-    orderby?: "ID" | "display_name" | "name" | "user_login" | "user_email" | "user_registered" | "post_count" | "meta_value" | "meta_value_num" | (string & {});
+    orderby?: 'ID' | 'display_name' | 'name' | 'user_login' | 'user_email' | 'user_registered' | 'post_count' | 'meta_value' | 'meta_value_num' | (string & {});
     /** Sort direction. */
-    order?: "ASC" | "DESC" | (string & {});
+    order?: 'ASC' | 'DESC' | (string & {});
     /** Number of users to return. */
     number?: NumericParam;
     /** Number of users to skip. */
@@ -490,19 +490,19 @@ interface WpUsersArgs {
 }
 /** Type-specific configuration of an {@link EtchLoop}, discriminated by `type`. */
 type EtchLoopConfig = {
-    type: "wp-query";
+    type: 'wp-query';
     args: WpQueryArgs;
 } | {
-    type: "wp-terms";
+    type: 'wp-terms';
     args: WpTermsArgs;
 } | {
-    type: "wp-users";
+    type: 'wp-users';
     args: WpUsersArgs;
 } | {
-    type: "main-query";
+    type: 'main-query';
     args: WpQueryArgs;
 } | {
-    type: "json";
+    type: 'json';
     data: unknown[];
 };
 /** A loop definition (extensible). */
@@ -566,7 +566,7 @@ interface EtchLoopsApi {
  * - `attribute` — `[data-foo]`, `[type="submit"]`, etc.
  * - `custom` — anything else (pseudo-classes, combinators, etc.)
  */
-type StyleSelectorType = "class" | "id" | "tag" | "element" | "attribute" | "custom";
+type StyleSelectorType = 'class' | 'id' | 'tag' | 'element' | 'attribute' | 'custom';
 /** A style entry as returned by `styles.list()`. */
 interface StyleSummary {
     /** Stable id of the style rule. */
@@ -653,7 +653,7 @@ interface EtchStylesApi {
  * Global stylesheet shapes and the `etch.stylesheets` API surface.
  */
 /** Type of a global stylesheet. */
-type StylesheetType = "default" | "@custom-media";
+type StylesheetType = 'default' | '@custom-media';
 /** A global stylesheet entry. */
 interface StylesheetSummary {
     /** Stable id of the stylesheet. */
@@ -754,8 +754,8 @@ type SelectOptionsString = string;
  */
 interface StringComponentProperty {
     type: {
-        primitive: "string";
-        specialized?: "color" | "url" | "image" | "select" | "array" | "wpMediaId";
+        primitive: 'string';
+        specialized?: 'color' | 'url' | 'image' | 'select' | 'array' | 'wpMediaId';
     };
     /** Default value. */
     default?: string;
@@ -777,7 +777,7 @@ interface StringComponentProperty {
  */
 interface NumberComponentProperty {
     type: {
-        primitive: "number";
+        primitive: 'number';
     };
     /** Default value. */
     default?: number;
@@ -787,7 +787,7 @@ interface NumberComponentProperty {
 /** A boolean property. */
 interface BooleanComponentProperty {
     type: {
-        primitive: "boolean";
+        primitive: 'boolean';
     };
     /** Default value (a string is allowed for expression-driven defaults). */
     default?: boolean | string;
@@ -801,7 +801,7 @@ interface BooleanComponentProperty {
  */
 interface ObjectComponentProperty {
     type: {
-        primitive: "object";
+        primitive: 'object';
         specialized?: string;
     };
     /** Default value. */
@@ -816,7 +816,7 @@ interface ObjectComponentProperty {
  */
 interface ArrayComponentProperty {
     type: {
-        primitive: "array";
+        primitive: 'array';
         specialized?: string;
     };
     /** Default value. */
@@ -825,8 +825,8 @@ interface ArrayComponentProperty {
 /** A list of CSS class names — an `array` specialized as `'class'`. */
 interface ClassComponentProperty {
     type: {
-        primitive: "array";
-        specialized: "class";
+        primitive: 'array';
+        specialized: 'class';
     };
     /** Default value. */
     default?: string[];
@@ -834,8 +834,8 @@ interface ClassComponentProperty {
 /** A group of nested properties — an `object` specialized as `'group'` (no default). */
 interface GroupComponentProperty {
     type: {
-        primitive: "object";
-        specialized: "group";
+        primitive: 'object';
+        specialized: 'group';
     };
     /** The nested properties in this group. */
     properties: ComponentProperty[];
@@ -843,8 +843,8 @@ interface GroupComponentProperty {
 /** A repeatable group — an `array` specialized as `'repeater'` (no default). */
 interface RepeaterComponentProperty {
     type: {
-        primitive: "array";
-        specialized: "repeater";
+        primitive: 'array';
+        specialized: 'repeater';
     };
     /** The nested properties repeated per row. */
     properties: ComponentProperty[];
@@ -852,8 +852,8 @@ interface RepeaterComponentProperty {
 /** A conditional group gated by an expression — a `string` specialized as `'condition'`. */
 interface ConditionComponentProperty {
     type: {
-        primitive: "string";
-        specialized: "condition";
+        primitive: 'string';
+        specialized: 'condition';
     };
     /** The nested properties shown when the condition holds. */
     properties: ComponentProperty[];
@@ -959,7 +959,7 @@ interface EtchComponentsApi {
  * - `style-manager` — the global style manager
  * - `loop-manager` — the loop manager
  */
-type NavigationPlace = "builder" | "templates" | "style-manager" | "content-hub" | "loop-manager";
+type NavigationPlace = 'builder' | 'templates' | 'style-manager' | 'content-hub' | 'loop-manager';
 /** Lightweight post entry returned by `navigation.listPostsAsync()`. */
 interface PostSummary {
     /** Post id. */
@@ -1008,7 +1008,7 @@ interface EtchNavigationApi {
  * Custom field group/value shapes and the `etch.fields` API surface.
  */
 /** Custom field type. Open-ended for future field types. */
-type CustomFieldType = "text" | "textarea" | "number" | "boolean" | (string & {});
+type CustomFieldType = 'text' | 'textarea' | 'number' | 'boolean' | (string & {});
 /** A custom field definition (extensible). */
 interface CustomField {
     /** Display label. */
@@ -1026,13 +1026,13 @@ interface CustomField {
 /** Where a custom field group is assigned. */
 type CustomFieldAssignment = {
     post_types: string[];
-    op: "isIn" | "isNotIn";
+    op: 'isIn' | 'isNotIn';
 } | {
     post_ids: number[];
-    op: "isIn" | "isNotIn";
+    op: 'isIn' | 'isNotIn';
 } | {
     taxonomies: string[];
-    op: "isIn" | "isNotIn";
+    op: 'isIn' | 'isNotIn';
 };
 /** A custom field group definition (extensible). */
 interface CustomFieldGroup {
@@ -1128,7 +1128,7 @@ interface EtchFieldsApi {
  * Builder chrome controls (`etch.ui`) and undo/redo (`etch.history`).
  */
 /** Canvas color scheme. */
-type ColorScheme = "light" | "dark";
+type ColorScheme = 'light' | 'dark';
 /** Builder app/chrome controls: color scheme, interface visibility, exit. */
 interface EtchUiApi {
     /** The current canvas color scheme. */

package/dist/index.d.ts

@@ -12,7 +12,7 @@ interface EtchBlockContext {
      * panel. This is editor UI state, not document data — most scripts can
      * ignore it.
      */
-    structureState?: "open" | "closed";
+    structureState?: 'open' | 'closed';
     /** Whether the block is hidden (not rendered) on the canvas. */
     hidden?: boolean;
 }
@@ -64,7 +64,7 @@ interface EtchBlockCommon {
 }
 /** A text block (`etch/text`). */
 interface EtchTextBlockJson extends EtchBlockCommon {
-    type: "etch/text";
+    type: 'etch/text';
     /** The block's text content. */
     text: string;
 }
@@ -76,7 +76,7 @@ interface EtchTextBlockJson extends EtchBlockCommon {
  * `blocks.create()` / `blocks.replace()` ignore them.
  */
 interface EtchElementBlockJson extends EtchBlockCommon {
-    type: "etch/element";
+    type: 'etch/element';
     /** The HTML tag name, e.g. `div`, `p`, `h1`. */
     tag: string;
     /** HTML attributes. */
@@ -90,7 +90,7 @@ interface EtchElementBlockJson extends EtchBlockCommon {
  * {@link EtchElementBlockJson}).
  */
 interface EtchDynamicElementBlockJson extends EtchBlockCommon {
-    type: "etch/dynamic-element";
+    type: 'etch/dynamic-element';
     /** HTML attributes (the rendered tag is read from `attributes.tag`). */
     attributes: EtchHtmlAttributes;
 }
@@ -111,7 +111,7 @@ interface EtchDynamicElementBlockJson extends EtchBlockCommon {
  *   to `"full"` when omitted.
  */
 interface EtchDynamicImageBlockJson extends EtchBlockCommon {
-    type: "etch/dynamic-image";
+    type: 'etch/dynamic-image';
     /** HTML attributes (e.g. `src`, `alt`). */
     attributes: EtchHtmlAttributes;
 }
@@ -129,13 +129,13 @@ interface EtchDynamicImageBlockJson extends EtchBlockCommon {
  *   when `src` is set.
  */
 interface EtchSvgBlockJson extends EtchBlockCommon {
-    type: "etch/svg";
+    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";
+    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`. */
@@ -149,13 +149,13 @@ interface EtchLoopBlockJson extends EtchBlockCommon {
 }
 /** A conditional block (`etch/condition`); renders its children when the expression holds. */
 interface EtchConditionBlockJson extends EtchBlockCommon {
-    type: "etch/condition";
+    type: 'etch/condition';
     /** The condition expression. */
     conditionString: string;
 }
 /** An instance of a reusable component (`etch/component`). */
 interface EtchComponentBlockJson extends EtchBlockCommon {
-    type: "etch/component";
+    type: 'etch/component';
     /** Id of the component being instantiated. */
     componentId: number;
     /** Values bound to the component's properties. */
@@ -163,23 +163,23 @@ interface EtchComponentBlockJson extends EtchBlockCommon {
 }
 /** Content projected into a component slot (`etch/slot-content`). */
 interface EtchSlotContentBlockJson extends EtchBlockCommon {
-    type: "etch/slot-content";
+    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";
+    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";
+    type: 'etch/post-content';
 }
 /** A raw-HTML block (`etch/raw-html`). */
 interface EtchRawHtmlBlockJson extends EtchBlockCommon {
-    type: "etch/raw-html";
+    type: 'etch/raw-html';
     /** Sanitized HTML content. */
     content: string;
     /** The original, unsanitized HTML as authored. */
@@ -187,7 +187,7 @@ interface EtchRawHtmlBlockJson extends EtchBlockCommon {
 }
 /** A pass-through wrapper around a native Gutenberg block (`etch/passthrough`). */
 interface EtchPassthroughBlockJson extends EtchBlockCommon {
-    type: "etch/passthrough";
+    type: 'etch/passthrough';
     /** The wrapped Gutenberg block. */
     gutenbergBlock: GutenbergBlock;
 }
@@ -201,7 +201,7 @@ interface EtchPassthroughBlockJson extends EtchBlockCommon {
  */
 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"];
+type EtchBlockTypeName = EtchBlockJson['type'];
 /** Read-only identity attached to every serialized (read) block. */
 interface BlockIdentity {
     /** Stable id of this block. */
@@ -217,7 +217,7 @@ interface BlockIdentity {
  * 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";
+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). */
@@ -227,7 +227,7 @@ interface ReadOnlyBlockStyles {
  * 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 WithIdentity<B> = B extends EtchBlockCommon ? Omit<B, 'children'> & BlockIdentity & (B extends {
     type: StyledBlockType;
 } ? ReadOnlyBlockStyles : unknown) : never;
 /**
@@ -390,9 +390,9 @@ interface MetaQueryItem {
     /** The value(s) to compare against. */
     value: string | number | Array<string | number>;
     /** Comparison operator (defaults to `=`). */
-    compare?: "=" | "!=" | ">" | ">=" | "<" | "<=" | "LIKE" | "NOT LIKE" | "IN" | "NOT IN" | "BETWEEN" | "NOT BETWEEN" | "EXISTS" | "NOT EXISTS";
+    compare?: '=' | '!=' | '>' | '>=' | '<' | '<=' | 'LIKE' | 'NOT LIKE' | 'IN' | 'NOT IN' | 'BETWEEN' | 'NOT BETWEEN' | 'EXISTS' | 'NOT EXISTS';
     /** SQL type the value is cast to before comparison. */
-    type?: "NUMERIC" | "BINARY" | "CHAR" | "DATE" | "DATETIME" | "DECIMAL" | "SIGNED" | "TIME" | "UNSIGNED";
+    type?: 'NUMERIC' | 'BINARY' | 'CHAR' | 'DATE' | 'DATETIME' | 'DECIMAL' | 'SIGNED' | 'TIME' | 'UNSIGNED';
     [key: string]: unknown;
 }
 /**
@@ -403,11 +403,11 @@ interface TaxQueryItem {
     /** The taxonomy to query (e.g. `category`, `post_tag`). */
     taxonomy: string;
     /** Which term field `terms` refers to. */
-    field: "term_id" | "slug" | "name";
+    field: 'term_id' | 'slug' | 'name';
     /** The term(s) to match. */
     terms: string | number | Array<string | number>;
     /** How to match the terms (defaults to `IN`). */
-    operator?: "IN" | "NOT IN" | "AND";
+    operator?: 'IN' | 'NOT IN' | 'AND';
     /** Whether to include child terms of a hierarchical taxonomy. */
     include_children?: boolean;
     [key: string]: unknown;
@@ -429,11 +429,11 @@ interface WpQueryArgs {
     /** Alias of `paged` used in some contexts. */
     page?: NumericParam;
     /** Field to order results by. */
-    orderby?: "date" | "title" | "menu_order" | "rand" | "ID" | "author" | "name" | "modified" | "parent" | "comment_count" | (string & {});
+    orderby?: 'date' | 'title' | 'menu_order' | 'rand' | 'ID' | 'author' | 'name' | 'modified' | 'parent' | 'comment_count' | (string & {});
     /** Sort direction. */
-    order?: "ASC" | "DESC" | (string & {});
+    order?: 'ASC' | 'DESC' | (string & {});
     /** Post status to include. */
-    post_status?: "publish" | "pending" | "draft" | "auto-draft" | "future" | "private" | "inherit" | "trash" | (string & {});
+    post_status?: 'publish' | 'pending' | 'draft' | 'auto-draft' | 'future' | 'private' | 'inherit' | 'trash' | (string & {});
     /** Whether to ignore sticky posts. */
     ignore_sticky_posts?: BooleanParam;
     /** Author id (number) or username (string). */
@@ -459,9 +459,9 @@ interface WpTermsArgs {
     /** Taxonomy to fetch terms from. */
     taxonomy?: string;
     /** Field to order terms by. */
-    orderby?: "name" | "slug" | "term_group" | "term_id" | "description" | "count" | (string & {});
+    orderby?: 'name' | 'slug' | 'term_group' | 'term_id' | 'description' | 'count' | (string & {});
     /** Sort direction. */
-    order?: "ASC" | "DESC" | (string & {});
+    order?: 'ASC' | 'DESC' | (string & {});
     [key: string]: unknown;
 }
 /** WordPress user query arguments (extensible). */
@@ -477,9 +477,9 @@ interface WpUsersArgs {
     /** Columns the `search` keyword is matched against. */
     search_columns?: string[] | string;
     /** Field to order users by. */
-    orderby?: "ID" | "display_name" | "name" | "user_login" | "user_email" | "user_registered" | "post_count" | "meta_value" | "meta_value_num" | (string & {});
+    orderby?: 'ID' | 'display_name' | 'name' | 'user_login' | 'user_email' | 'user_registered' | 'post_count' | 'meta_value' | 'meta_value_num' | (string & {});
     /** Sort direction. */
-    order?: "ASC" | "DESC" | (string & {});
+    order?: 'ASC' | 'DESC' | (string & {});
     /** Number of users to return. */
     number?: NumericParam;
     /** Number of users to skip. */
@@ -490,19 +490,19 @@ interface WpUsersArgs {
 }
 /** Type-specific configuration of an {@link EtchLoop}, discriminated by `type`. */
 type EtchLoopConfig = {
-    type: "wp-query";
+    type: 'wp-query';
     args: WpQueryArgs;
 } | {
-    type: "wp-terms";
+    type: 'wp-terms';
     args: WpTermsArgs;
 } | {
-    type: "wp-users";
+    type: 'wp-users';
     args: WpUsersArgs;
 } | {
-    type: "main-query";
+    type: 'main-query';
     args: WpQueryArgs;
 } | {
-    type: "json";
+    type: 'json';
     data: unknown[];
 };
 /** A loop definition (extensible). */
@@ -566,7 +566,7 @@ interface EtchLoopsApi {
  * - `attribute` — `[data-foo]`, `[type="submit"]`, etc.
  * - `custom` — anything else (pseudo-classes, combinators, etc.)
  */
-type StyleSelectorType = "class" | "id" | "tag" | "element" | "attribute" | "custom";
+type StyleSelectorType = 'class' | 'id' | 'tag' | 'element' | 'attribute' | 'custom';
 /** A style entry as returned by `styles.list()`. */
 interface StyleSummary {
     /** Stable id of the style rule. */
@@ -653,7 +653,7 @@ interface EtchStylesApi {
  * Global stylesheet shapes and the `etch.stylesheets` API surface.
  */
 /** Type of a global stylesheet. */
-type StylesheetType = "default" | "@custom-media";
+type StylesheetType = 'default' | '@custom-media';
 /** A global stylesheet entry. */
 interface StylesheetSummary {
     /** Stable id of the stylesheet. */
@@ -754,8 +754,8 @@ type SelectOptionsString = string;
  */
 interface StringComponentProperty {
     type: {
-        primitive: "string";
-        specialized?: "color" | "url" | "image" | "select" | "array" | "wpMediaId";
+        primitive: 'string';
+        specialized?: 'color' | 'url' | 'image' | 'select' | 'array' | 'wpMediaId';
     };
     /** Default value. */
     default?: string;
@@ -777,7 +777,7 @@ interface StringComponentProperty {
  */
 interface NumberComponentProperty {
     type: {
-        primitive: "number";
+        primitive: 'number';
     };
     /** Default value. */
     default?: number;
@@ -787,7 +787,7 @@ interface NumberComponentProperty {
 /** A boolean property. */
 interface BooleanComponentProperty {
     type: {
-        primitive: "boolean";
+        primitive: 'boolean';
     };
     /** Default value (a string is allowed for expression-driven defaults). */
     default?: boolean | string;
@@ -801,7 +801,7 @@ interface BooleanComponentProperty {
  */
 interface ObjectComponentProperty {
     type: {
-        primitive: "object";
+        primitive: 'object';
         specialized?: string;
     };
     /** Default value. */
@@ -816,7 +816,7 @@ interface ObjectComponentProperty {
  */
 interface ArrayComponentProperty {
     type: {
-        primitive: "array";
+        primitive: 'array';
         specialized?: string;
     };
     /** Default value. */
@@ -825,8 +825,8 @@ interface ArrayComponentProperty {
 /** A list of CSS class names — an `array` specialized as `'class'`. */
 interface ClassComponentProperty {
     type: {
-        primitive: "array";
-        specialized: "class";
+        primitive: 'array';
+        specialized: 'class';
     };
     /** Default value. */
     default?: string[];
@@ -834,8 +834,8 @@ interface ClassComponentProperty {
 /** A group of nested properties — an `object` specialized as `'group'` (no default). */
 interface GroupComponentProperty {
     type: {
-        primitive: "object";
-        specialized: "group";
+        primitive: 'object';
+        specialized: 'group';
     };
     /** The nested properties in this group. */
     properties: ComponentProperty[];
@@ -843,8 +843,8 @@ interface GroupComponentProperty {
 /** A repeatable group — an `array` specialized as `'repeater'` (no default). */
 interface RepeaterComponentProperty {
     type: {
-        primitive: "array";
-        specialized: "repeater";
+        primitive: 'array';
+        specialized: 'repeater';
     };
     /** The nested properties repeated per row. */
     properties: ComponentProperty[];
@@ -852,8 +852,8 @@ interface RepeaterComponentProperty {
 /** A conditional group gated by an expression — a `string` specialized as `'condition'`. */
 interface ConditionComponentProperty {
     type: {
-        primitive: "string";
-        specialized: "condition";
+        primitive: 'string';
+        specialized: 'condition';
     };
     /** The nested properties shown when the condition holds. */
     properties: ComponentProperty[];
@@ -959,7 +959,7 @@ interface EtchComponentsApi {
  * - `style-manager` — the global style manager
  * - `loop-manager` — the loop manager
  */
-type NavigationPlace = "builder" | "templates" | "style-manager" | "content-hub" | "loop-manager";
+type NavigationPlace = 'builder' | 'templates' | 'style-manager' | 'content-hub' | 'loop-manager';
 /** Lightweight post entry returned by `navigation.listPostsAsync()`. */
 interface PostSummary {
     /** Post id. */
@@ -1008,7 +1008,7 @@ interface EtchNavigationApi {
  * Custom field group/value shapes and the `etch.fields` API surface.
  */
 /** Custom field type. Open-ended for future field types. */
-type CustomFieldType = "text" | "textarea" | "number" | "boolean" | (string & {});
+type CustomFieldType = 'text' | 'textarea' | 'number' | 'boolean' | (string & {});
 /** A custom field definition (extensible). */
 interface CustomField {
     /** Display label. */
@@ -1026,13 +1026,13 @@ interface CustomField {
 /** Where a custom field group is assigned. */
 type CustomFieldAssignment = {
     post_types: string[];
-    op: "isIn" | "isNotIn";
+    op: 'isIn' | 'isNotIn';
 } | {
     post_ids: number[];
-    op: "isIn" | "isNotIn";
+    op: 'isIn' | 'isNotIn';
 } | {
     taxonomies: string[];
-    op: "isIn" | "isNotIn";
+    op: 'isIn' | 'isNotIn';
 };
 /** A custom field group definition (extensible). */
 interface CustomFieldGroup {
@@ -1128,7 +1128,7 @@ interface EtchFieldsApi {
  * Builder chrome controls (`etch.ui`) and undo/redo (`etch.history`).
  */
 /** Canvas color scheme. */
-type ColorScheme = "light" | "dark";
+type ColorScheme = 'light' | 'dark';
 /** Builder app/chrome controls: color scheme, interface visibility, exit. */
 interface EtchUiApi {
     /** The current canvas color scheme. */

package/dist/index.js

@@ -45,7 +45,10 @@ function getEtch(options = {}) {
     return etch.connect(options);
   }
   if (options.apiVersion) {
-    warnIfIncompatible(options.apiVersion, etch.apiVersion ?? ETCH_API_VERSION);
+    warnIfIncompatible(
+      options.apiVersion,
+      etch.apiVersion ?? ETCH_API_VERSION
+    );
   }
   return etch;
 }

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,OAAO,KAAA,YAAiB,YAAA,IAAiB,KAAA,EAAiB,IAAA,KAAS,cAAA;AACpE;;;AC9BO,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;AAErD,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,CAAmB,OAAA,CAAQ,UAAA,EAAY,IAAA,CAAK,UAAA,IAAc,gBAAgB,CAAA;AAAA,EAC3E;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 value instanceof EtchApiError || (value as Error)?.name === 'EtchApiError';\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\t// eslint-disable-next-line no-console\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(options.apiVersion, etch.apiVersion ?? ETCH_API_VERSION);\n\t}\n\treturn etch;\n}\n"]}
+{"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"]}

package/package.json

@@ -1,46 +1,60 @@
 {
-  "name": "@digital-gravy/etch-public-api",
-  "version": "0.7.0",
-  "description": "MIT-licensed typed client and contract for the Etch builder scripting API (window.etch). Etch itself is a separate proprietary product governed by its own commercial terms.",
-  "license": "MIT",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "sideEffects": false,
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "bun run build"
-  },
-  "keywords": [
-    "etch",
-    "etchwp",
-    "wordpress",
-    "builder",
-    "scripting",
-    "api"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
-    "vitest": "^3.0.5"
-  }
+	"name": "@digital-gravy/etch-public-api",
+	"version": "0.7.1",
+	"description": "MIT-licensed typed client and contract for the Etch builder scripting API (window.etch). Etch itself is a separate proprietary product governed by its own commercial terms.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Digital-Gravy/etch-public-api.git"
+	},
+	"type": "module",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"build": "tsup",
+		"dev": "tsup --watch",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"typecheck": "tsc --noEmit",
+		"lint": "bun run eslint && bun run format:check",
+		"eslint": "eslint .",
+		"format": "prettier --write .",
+		"format:check": "prettier --check .",
+		"prepublishOnly": "bun run build"
+	},
+	"keywords": [
+		"etch",
+		"etchwp",
+		"wordpress",
+		"builder",
+		"scripting",
+		"api"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.39.2",
+		"eslint": "^9.39.2",
+		"eslint-config-prettier": "^10.1.8",
+		"globals": "^17.1.0",
+		"prettier": "^3.8.1",
+		"tsup": "^8.3.5",
+		"typescript": "^5.7.2",
+		"typescript-eslint": "^8.53.1",
+		"vitest": "^3.0.5"
+	}
 }