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

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"]}