@snowcone-app/canvas 0.22.0 → 0.26.0

package/ERROR_CONTRACT.md

@@ -0,0 +1,600 @@
+# `Editor.*` error contract
+
+<!-- GENERATED — do not edit. Derived from the EditorError/EmbedIssue source
+     of truth by packages/canvas/scripts/gen-error-contract.mjs.
+     Regenerate: pnpm -C packages/canvas gen:error-contract -->
+
+Every composition/runtime violation in the `Editor.*` parts throws an
+`EditorError`: a stable machine-readable `code` plus a structured
+`error.data` payload (always including `code`, usually `docSlug` and the
+valid alternatives). Throws fire dev AND prod and are contained by
+`Editor.Root`'s error boundary. **Assert on `code` + `data` fields, never
+on message prose** — messages are rendered from the data and may be
+reworded. Every message names the violated contract and the corrective
+code, so the fix is in the message itself. `${…}` in the templates below
+marks runtime facts.
+
+Advisory wiring problems (severity `warn`) never throw: they reach the
+host through `Editor.Root`'s `onIssue` channel as `EmbedIssue` objects —
+see [Embed wiring issues](#embed-wiring-issues-the-onissue-channel).
+Error-severity wiring issues escalate to a thrown `E_EMBED_CONFIG` with
+the issue key in `error.data.issue`.
+
+## Code index
+
+| code | severity | fires when |
+|---|---|---|
+| [`E_OUTSIDE_ROOT`](#e_outside_root) | throw | An `Editor.*` part mounted outside `<Editor.Root>`. |
+| [`E_LAYER_NOT_FOUND`](#e_layer_not_found) | throw | A layer token (or its name) matches no layer in the mounted design. |
+| [`E_LAYER_WRONG_KIND`](#e_layer_wrong_kind) | throw | The layer exists but is not the kind the part binds (e.g. an image layer passed to `Editor.TextField`). |
+| [`E_LAYER_TOKEN_REQUIRED`](#e_layer_token_required) | throw | `Editor.TextField` received a bare string (or other non-token) — layers bind by `design.layer("name")` token only (ADR-0085 §1). |
+| [`E_BOUND_LAYER_MUTATION`](#e_bound_layer_mutation) | throw | Programmatic rename/delete of a layer a mounted TextField is bound to. |
+| [`E_DUPLICATE_CANVAS`](#e_duplicate_canvas) | throw | Two `Editor.Canvas` parts mounted under one Root. |
+| [`E_REQUIRES_CANVAS`](#e_requires_canvas) | throw | A part that needs a mounted `Editor.Canvas` found none under this Root. |
+| [`E_BUY_NO_PRODUCT`](#e_buy_no_product) | throw | `Editor.Buy` mounted without product context. |
+| [`E_CHUNK_LOAD_FAILED`](#e_chunk_load_failed) | throw | The lazy renderer chunk failed to load (network/CDN). Retryable. |
+| [`E_EMBED_CONFIG`](#e_embed_config) | throw | Embed wiring invalid at mount (missing grant/mockupIds, variant or placement mismatch) — the throw-mode upgrade of `validateEmbed` (F3). |
+| [`E_PRODUCT_NOT_RENDERABLE`](#e_product_not_renderable) | throw | `productToRenderConfig`: the catalog product has no renderable image placement / no mockup scenes, or the requested placement doesn't exist. |
+| [`E_DUPLICATE_ARTBOARD`](#e_duplicate_artboard) | throw | `design().artboard()`: an artboard with this label already exists in the design (artboard names are placement labels — unique by contract). |
+| [`E_UNKNOWN_PLACEMENT`](#e_unknown_placement) | throw | `usePlacements().select()`: the label names no artboard in the design (ADR-0088). Lists the valid placement labels. |
+| [`E_UNKNOWN_OPTION`](#e_unknown_option) | throw | `select()` named an option key/choice that doesn't exist on the product (Buy-owned selection, ADR-0085 §2 / P2). |
+| [`E_COLOR_ROLE_COLLISION`](#e_color_role_collision) | throw | `design({ colors })`: two color roles share one (normalized) hex value. `useColorBinding` matches by VALUE, so colliding roles would capture each other's elements — rejected at mint time instead of failing subtly. |
+| [`E_COLOR_ROLE_INVALID`](#e_color_role_invalid) | throw | `design({ colors })`: a role's value is not a `#RGB`/`#RRGGBB` hex (value-matched bindings normalize hex; other syntaxes can't bind). |
+| [`E_COLOR_ROLE_NOT_FOUND`](#e_color_role_not_found) | throw | `design.color(name)`: no color role with this name — lists the design's declared roles. |
+| [`E_PREVIEW_NO_LOADER`](#e_preview_no_loader) | throw | `Editor.Preview loadingOverlay` got `false`/an unknown value. A mockup preview ALWAYS has a render-in-flight treatment (a server render takes real time, and the loader paints OVER the still-visible previous mockup) — keep the default, pass a variant/custom element, or declare `"host-owned"` with your own indicator. Silence-then-pop-in is a composition mistake, not a preference. |
+| [`E_ASSET_FORBIDDEN`](#e_asset_forbidden) | throw | `assertRenders`: the shop's asset-origin allowlist denied a design asset (translated from the server's 403 — F4). |
+| [`E_RENDER_FAILED`](#e_render_failed) | throw | `assertRenders`: the render failed or produced no usable image (F4). |
+| [`E_BINDING_INERT`](#e_binding_inert) | throw | `assertRenders`: the mutated render is byte-identical to the seed render — the binding under test is dead (the two-render contract, F4). |
+| [`E_NO_MUTABLE_BINDING`](#e_no_mutable_binding) | throw | `assertRenders`: the design has no named text layer to mutate and no `mutate` override was given (F4). |
+| [`E_AUDIT_NO_ROOT`](#e_audit_no_root) | throw | `auditEditor()` called with no `<Editor.Root>` mounted — the imperative audit reads the most-recent mounted Root's registry (#10). |
+| [`missing-shop`](#missing-shop) | error → throws `E_EMBED_CONFIG` | No `shop` (the publishable shop id) was passed. |
+| [`missing-grant`](#missing-grant) | error → throws `E_EMBED_CONFIG` | No grant source (`grantUrl`/`grant`) — the session can never authorize, so no mockup ever renders. |
+| [`empty-mockup-ids`](#empty-mockup-ids) | error → throws `E_EMBED_CONFIG` | `product.mockupIds` is empty — nothing to render. |
+| [`variant-required`](#variant-required) | error → throws `E_EMBED_CONFIG` | The product has a variant axis but no `variantId` — the render would hang ~30s waiting on a color blob that never comes. |
+| [`multi-placement`](#multi-placement) | error → throws `E_EMBED_CONFIG` | The product requires several placements but this embed renders ONE — the server times out waiting on the rest (needs the eject path). |
+| [`placement-mismatch`](#placement-mismatch) | error → throws `E_EMBED_CONFIG` | The design's placement isn't one of the product's placements — the server renders a blank mockup. |
+| [`duplicate-layer-names`](#duplicate-layer-names) | warn (advisory) | Two layers share a name — name-bound hooks bind the FIRST match, so a control may edit the wrong layer. |
+| [`slow-render`](#slow-render) | warn (advisory) | Runtime (not mount-time): a render has been in flight past `SLOW_RENDER_HINT_MS` with no mockup and no error — the silent-hang class. The render may still arrive; this is a heads-up. |
+
+## `EditorError` codes
+
+### `E_OUTSIDE_ROOT`
+
+**Fires when:** An `Editor.*` part mounted outside `<Editor.Root>`.
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/components/editor/RootInternals.ts`
+
+  ```text
+  <${partName}> must be rendered inside <Editor.Root>. Wrap it: <Editor.Root shop={…} product={…} design={…} grantUrl={…}><${partName}/></Editor.Root>
+  ```
+
+  `error.data`: `code`, `part`, `docSlug`
+
+### `E_LAYER_NOT_FOUND`
+
+**Fires when:** A layer token (or its name) matches no layer in the mounted design.
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/components/editor/EditorTextField.tsx`
+
+  ```text
+  no layer "${layer.name}" in this Root's design — the token was minted from a different design than the one passed to <Editor.Root design={…}>. Bindable layers here: ${JSON.stringify(stateStore.bindableLayerNames())}.
+  ```
+
+  `error.data`: `code`, `layerName`, `validNames`, `docSlug`
+
+- `src/components/editor/EditorTextField.tsx`
+
+  ```text
+  layer "${layer.name}" no longer exists in the mounted canvas — it was removed or renamed after this <Editor.TextField> bound to it. Bound layers must not be renamed or deleted while a field is mounted (ADR-0085 §3).
+  ```
+
+  `error.data`: `code`, `layerName`, `docSlug`
+
+- `src/components/editor/designStateStore.ts`
+
+  ```text
+  no layer "${name}" in the current design state. Bindable layers: ${JSON.stringify(this.bindableLayerNames())}.
+  ```
+
+  `error.data`: `code`, `layerName`, `validNames`, `docSlug`
+
+- `src/design/design-builder.ts`
+
+  ```text
+  no layer "${name}" in this design. Text layers: ${JSON.stringify(textNames)}; image layers: ${JSON.stringify(imageNames)}. Fix the name, or add the layer first — e.g. design(…).text('…', { name: '${name}' }).
+  ```
+
+  `error.data`: `code`, `layerName`, `validNames`, `textNames`, `imageNames`, `docSlug`
+
+- `src/hooks/bindingGuards.ts`
+
+  ```text
+  no layer "${name}" in this Root's document — the token was minted from a different design than the one passed to <Editor.Root design={…}>, or the layer was deleted. Bindable layers here: ${JSON.stringify(named.map((e) => e.name))}.
+  ```
+
+  `error.data`: `code`, `layerName`, `validNames`, `docSlug`
+
+### `E_LAYER_WRONG_KIND`
+
+**Fires when:** The layer exists but is not the kind the part binds (e.g. an image layer passed to `Editor.TextField`).
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/components/editor/EditorTextField.tsx`
+
+  ```text
+  layer "${layer.name}" is ${kindNow === null ? 'not a bindable kind' : `an ${kindNow} layer`} — <Editor.TextField> binds text layers only.
+  ```
+
+  `error.data`: `code`, `layerName`, `actualKind`, `docSlug`
+
+- `src/design/design-builder.ts`
+
+  ```text
+  layer "${name}" is a ${(el as { transformType?: string }).transformType} element — only text and image layers are bindable. Bindable layers: ${JSON.stringify([...this.layerNamesOfKind('text'), ...this.layerNamesOfKind('image')])}.
+  ```
+
+  `error.data`: `code`, `layerName`, `actualType`, `docSlug`
+
+- `src/hooks/bindingGuards.ts`
+
+  ```text
+  layer "${name}" is a ${layerOrName.kind} token — this hook binds ${expectedKind} layers only (use ${HOOK_BY_KIND[layerOrName.kind]}).
+  ```
+
+  `error.data`: `code`, `layerName`, `actualKind`, `expectedKind`, `docSlug`
+
+- `src/hooks/bindingGuards.ts`
+
+  ```text
+  layer "${name}" is ${actual === 'unbindable' ? 'not a bindable kind' : `an ${actual} layer`} — this hook binds ${expectedKind} layers only.
+  ```
+
+  `error.data`: `code`, `layerName`, `actualKind`, `expectedKind`, `docSlug`
+
+### `E_LAYER_TOKEN_REQUIRED`
+
+**Fires when:** `Editor.TextField` received a bare string (or other non-token) — layers bind by `design.layer("name")` token only (ADR-0085 §1).
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/components/editor/EditorTextField.tsx`
+
+  ```text
+  the `layer` prop must be a token minted by the design — pass layer={design.layer("name")}, not ${typeof layer === 'string' ? `the bare string "${layer}"` : 'a plain value'}. Tokens validate the name against the design's layers at mint time.
+  ```
+
+  `error.data`: `code`, `received`, `docSlug`
+
+### `E_BOUND_LAYER_MUTATION`
+
+**Fires when:** Programmatic rename/delete of a layer a mounted TextField is bound to.
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/hooks/useCommandHistory.ts`
+
+  ```text
+  cannot ${operation} layer "${name}" — a mounted <${bound.part} layer={design.layer("${name}")}> is bound to it. Unmount that field first, or keep the layer and set its text through the field / its binding instead.
+  ```
+
+  `error.data`: `code`, `layer`, `part`, `operation`, `docSlug`
+
+### `E_DUPLICATE_CANVAS`
+
+**Fires when:** Two `Editor.Canvas` parts mounted under one Root.
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/components/editor/RootInternals.ts`
+
+  ```text
+  two <Editor.Canvas> parts are mounted under one <Editor.Root>. A Root owns exactly one editable artboard — remove one Canvas, or mount a second <Editor.Root> for a second editor. (Multiple <Editor.Preview> parts ARE valid.)
+  ```
+
+  `error.data`: `code`, `docSlug`
+
+### `E_REQUIRES_CANVAS`
+
+**Fires when:** A part that needs a mounted `Editor.Canvas` found none under this Root.
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/components/editor/RootInternals.ts`
+
+  ```text
+  ${parts.join(', ')} require${parts.length === 1 ? 's' : ''} an <Editor.Canvas> under the same <Editor.Root> — they operate on the editable artboard (selection, editor commands). Mount <Editor.Canvas/>, or remove the part. Canvas-free parts: Editor.Preview, Editor.Buy, Editor.TextField, Editor.Layers.
+  ```
+
+  `error.data`: `code`, `parts`, `docSlug`
+
+### `E_BUY_NO_PRODUCT`
+
+**Fires when:** `Editor.Buy` mounted without product context.
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/components/editor/EditorBuy.tsx`
+
+  ```text
+  <Editor.Buy> has no product context — pass `product` (with `productId`) on <Editor.Root product={…}>. Buy assembles its cart payload from the Root product and the live design state.
+  ```
+
+  `error.data`: `code`, `docSlug`
+
+### `E_CHUNK_LOAD_FAILED`
+
+**Fires when:** The lazy renderer chunk failed to load (network/CDN). Retryable.
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/components/editor/EditorCanvas.tsx`
+
+  ```text
+  the editor's rendering chunk failed to load (${err instanceof Error ? err.message : String(err)}). This is a network/CDN failure, not a composition mistake — retry, or check the deployment serves the @snowcone-app/canvas lazy chunks.
+  ```
+
+  `error.data`: `code`, `cause`, `docSlug`
+
+- `src/components/editor/EditorControls.tsx`
+
+  ```text
+  the editor's controls chunk failed to load (${err instanceof Error ? err.message : String(err)}). This is a network/CDN failure, not a composition mistake — retry, or check the deployment serves the @snowcone-app/canvas lazy chunks.
+  ```
+
+  `error.data`: `code`, `cause`, `docSlug`
+
+- `src/components/editor/LazyImageBrowser.tsx`
+
+  ```text
+  the editor's image-browser chunk failed to load (${err instanceof Error ? err.message : String(err)}). This is a network/CDN failure, not a composition mistake — retry, or check the deployment serves the @snowcone-app/canvas lazy chunks.
+  ```
+
+  `error.data`: `code`, `cause`, `docSlug`
+
+### `E_EMBED_CONFIG`
+
+**Fires when:** Embed wiring invalid at mount (missing grant/mockupIds, variant or placement mismatch) — the throw-mode upgrade of `validateEmbed` (F3).
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/components/editor/EditorRoot.tsx`
+
+  ```text
+  ${fatal.message}
+  ```
+
+  `error.data`: `code`, `issue`, `docSlug`
+
+### `E_PRODUCT_NOT_RENDERABLE`
+
+**Fires when:** `productToRenderConfig`: the catalog product has no renderable image placement / no mockup scenes, or the requested placement doesn't exist.
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/design/product-config.ts`
+
+  ```text
+  product ${catalogProduct.id} has no renderable placement "${options.placement}". Renderable image placements: [${renderableLabels.join(', ')}].
+  ```
+
+  `error.data`: `code`, `productId`, `requested`, `validNames`, `docSlug`
+
+- `src/design/product-config.ts`
+
+  ```text
+  product ${catalogProduct.id} has no renderable image placement (a non-color placement with width/height). The catalog payload may be incomplete — fetch it via getProduct(), not a search hit.
+  ```
+
+  `error.data`: `code`, `productId`, `docSlug`
+
+- `src/design/product-config.ts`
+
+  ```text
+  product ${catalogProduct.id} has no mockup scenes — nothing to render a preview into.
+  ```
+
+  `error.data`: `code`, `productId`, `docSlug`
+
+### `E_DUPLICATE_ARTBOARD`
+
+**Fires when:** `design().artboard()`: an artboard with this label already exists in the design (artboard names are placement labels — unique by contract).
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/design/design-builder.ts`
+
+  ```text
+  the design already has an artboard "${label}" — artboard names are placement labels and must be unique. Existing: ${JSON.stringify(this.allArtboards.map((a) => a.name))}.
+  ```
+
+  `error.data`: `code`, `artboardName`, `validNames`, `docSlug`
+
+### `E_UNKNOWN_PLACEMENT`
+
+**Fires when:** `usePlacements().select()`: the label names no artboard in the design (ADR-0088). Lists the valid placement labels.
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/components/editor/EditorRoot.tsx`
+
+  ```text
+  no placement "${label}" in this design — its artboards are ${JSON.stringify(placements)}. Add it to the seed with design(…).artboard('${label}', { width, height }) (ADR-0088).
+  ```
+
+  `error.data`: `code`, `placement`, `validNames`, `docSlug`
+
+### `E_UNKNOWN_OPTION`
+
+**Fires when:** `select()` named an option key/choice that doesn't exist on the product (Buy-owned selection, ADR-0085 §2 / P2).
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/components/editor/commerceStore.ts`
+
+  ```text
+  product ${this.product.productId} has no option "${key}". Valid option keys: ${JSON.stringify(Object.keys(this.attrs))}.
+  ```
+
+  `error.data`: `code`, `key`, `validKeys`, `docSlug`
+
+- `src/components/editor/commerceStore.ts`
+
+  ```text
+  "${choice}" is not a choice of option "${key}" on product ${this.product.productId}. Valid choices: ${JSON.stringify(labels)}.
+  ```
+
+  `error.data`: `code`, `key`, `choice`, `validChoices`, `docSlug`
+
+### `E_COLOR_ROLE_COLLISION`
+
+**Fires when:** `design({ colors })`: two color roles share one (normalized) hex value. `useColorBinding` matches by VALUE, so colliding roles would capture each other's elements — rejected at mint time instead of failing subtly.
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/design/design-builder.ts`
+
+  ```text
+  color roles "${collision[0]}" and "${roleName}" both normalize to ${value}. useColorBinding matches elements by VALUE, so colliding roles would repaint each other's elements — give every role a distinct hex.
+  ```
+
+  `error.data`: `code`, `roles`, `value`, `docSlug`
+
+### `E_COLOR_ROLE_INVALID`
+
+**Fires when:** `design({ colors })`: a role's value is not a `#RGB`/`#RRGGBB` hex (value-matched bindings normalize hex; other syntaxes can't bind).
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/design/design-builder.ts`
+
+  ```text
+  color role "${roleName}" is ${JSON.stringify(raw)} — roles must be #RGB/#RRGGBB hex (useColorBinding matches by normalized hex value; other syntaxes can't bind).
+  ```
+
+  `error.data`: `code`, `roleName`, `value`, `docSlug`
+
+### `E_COLOR_ROLE_NOT_FOUND`
+
+**Fires when:** `design.color(name)`: no color role with this name — lists the design's declared roles.
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/design/design-builder.ts`
+
+  ```text
+  no color role "${name}" in this design. Declared roles: ${JSON.stringify([...this.colorRoles.keys()])}. Declare roles up front — design({ …, colors: { ${name}: '#FF2D8A' } }).
+  ```
+
+  `error.data`: `code`, `roleName`, `validNames`, `docSlug`
+
+### `E_PREVIEW_NO_LOADER`
+
+**Fires when:** `Editor.Preview loadingOverlay` got `false`/an unknown value. A mockup preview ALWAYS has a render-in-flight treatment (a server render takes real time, and the loader paints OVER the still-visible previous mockup) — keep the default, pass a variant/custom element, or declare `"host-owned"` with your own indicator. Silence-then-pop-in is a composition mistake, not a preference.
+
+**Docs:** <https://developers.snowcone.app/preview-loading-overlay> (`error.data.docSlug`)
+
+- `src/components/editor/EditorPreview.tsx`
+
+  ```text
+  Editor.Preview: invalid loadingOverlay value ${JSON.stringify(value)}. A mockup preview always has a render-in-flight treatment (the loader paints over the still-visible previous mockup). Omit the prop for the default rainbow overlay, pass "dark" | "light", pass a custom ReactElement, or declare "host-owned" if the host renders its own indicator off data-sc-preview-state / <Editor.LoadingOverlay>.
+  ```
+
+  `error.data`: `code`, `docSlug`
+
+### `E_ASSET_FORBIDDEN`
+
+**Fires when:** `assertRenders`: the shop's asset-origin allowlist denied a design asset (translated from the server's 403 — F4).
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/testing/assertRenders.ts`
+
+  ```text
+  the shop's asset-origin allowlist denied an asset in this design (${label} render). Allow the asset's origin on the shop (or host it on the shop's storage origin).
+  ```
+
+  `error.data`: `code`, `phase`, `url`, `failedAssets`, `docSlug`
+
+### `E_RENDER_FAILED`
+
+**Fires when:** `assertRenders`: the render failed or produced no usable image (F4).
+
+- `src/testing/assertRenders.ts`
+
+  ```text
+  the ${label} render produced no mockup within ${timeoutMs}ms.
+  ```
+
+  `error.data`: `code`, `phase`, `timeoutMs`
+
+- `src/testing/assertRenders.ts`
+
+  ```text
+  the ${label} render failed: ${message}
+  ```
+
+  `error.data`: `code`, `phase`, `error`
+
+- `src/testing/assertRenders.ts`
+
+  ```text
+  the ${label} render failed to dispatch: ${message}
+  ```
+
+  `error.data`: `code`, `phase`, `error`
+
+- `src/testing/assertRenders.ts`
+
+  ```text
+  the ${label} render's image fetch failed: ${err.message}
+  ```
+
+  `error.data`: `code`, `phase`, `url`, `...err.data`
+
+### `E_BINDING_INERT`
+
+**Fires when:** `assertRenders`: the mutated render is byte-identical to the seed render — the binding under test is dead (the two-render contract, F4).
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/testing/assertRenders.ts`
+
+  ```text
+  the mutated render is byte-identical to the seed render — the mutation never reached the server, so the binding under test is DEAD. Usual causes: the mutated layer name doesn't exist in the design (check design.layer() names), or opts.mutate returned the seed unchanged.
+  ```
+
+  `error.data`: `code`, `seedUrl`, `mutatedUrl`, `bytes`, `docSlug`
+
+### `E_NO_MUTABLE_BINDING`
+
+**Fires when:** `assertRenders`: the design has no named text layer to mutate and no `mutate` override was given (F4).
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/testing/assertRenders.ts`
+
+  ```text
+  this design has no NAMED text layer to mutate for the two-render check. Name one (design().text("…", { name: "headline" })) or pass opts.mutate to define the mutation.
+  ```
+
+  `error.data`: `code`, `docSlug`
+
+### `E_AUDIT_NO_ROOT`
+
+**Fires when:** `auditEditor()` called with no `<Editor.Root>` mounted — the imperative audit reads the most-recent mounted Root's registry (#10).
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/components/editor/editorAudit.ts`
+
+  ```text
+  auditEditor() found no mounted <Editor.Root>. Mount a Root first — or, to audit at mount time, pass onAudit on the Root: <Editor.Root onAudit={(report) => …}>.
+  ```
+
+  `error.data`: `code`, `docSlug`
+
+## Embed wiring issues (the `onIssue` channel)
+
+Mount-time wiring problems and runtime stalls are `EmbedIssue` objects
+(`{ severity, issue, message }`) delivered to `Editor.Root`'s `onIssue`
+prop in every env. `warn`-severity issues are advisory — the embed still
+mounts and renders what it can. `error`-severity issues break the embed,
+so `Editor.Root` throws them as `E_EMBED_CONFIG` (the issue key is in
+`error.data.issue`).
+
+### `missing-shop`
+
+**Severity:** error (throws as `E_EMBED_CONFIG`)
+
+**Fires when:** No `shop` (the publishable shop id) was passed.
+
+- `src/components/embed-realtime/validateEmbed.ts`
+
+  ```text
+  `shop` is required (your publishable shop id).
+  ```
+
+### `missing-grant`
+
+**Severity:** error (throws as `E_EMBED_CONFIG`)
+
+**Fires when:** No grant source (`grantUrl`/`grant`) — the session can never authorize, so no mockup ever renders.
+
+- `src/components/embed-realtime/validateEmbed.ts`
+
+  ```text
+  no grant source — pass `grantUrl` (a proxy to mintRealtimeGrant) or `grant`. Without it the session can never authorize and no mockup renders.
+  ```
+
+### `empty-mockup-ids`
+
+**Severity:** error (throws as `E_EMBED_CONFIG`)
+
+**Fires when:** `product.mockupIds` is empty — nothing to render.
+
+- `src/components/embed-realtime/validateEmbed.ts`
+
+  ```text
+  product.mockupIds is empty — pass the catalog scene codes (product.mockups[].id) you want rendered, e.g. ["FV1qjO"].
+  ```
+
+### `variant-required`
+
+**Severity:** error (throws as `E_EMBED_CONFIG`)
+
+**Fires when:** The product has a variant axis but no `variantId` — the render would hang ~30s waiting on a color blob that never comes.
+
+- `src/components/embed-realtime/validateEmbed.ts`
+
+  ```text
+  ${err instanceof Error ? err.message : String(err)}
+  ```
+
+### `multi-placement`
+
+**Severity:** error (throws as `E_EMBED_CONFIG`)
+
+**Fires when:** The product requires several placements but this embed renders ONE — the server times out waiting on the rest (needs the eject path).
+
+- `src/components/embed-realtime/validateEmbed.ts`
+
+  ```text
+  product ${product.productId} requires placements [${required.join(', ')}] but the design only has artboards [${artboardNames.join(', ')}] — missing [${missing.join(', ')}]. The render would time out waiting for the missing canvas_states. Add each missing placement to the seed: design(…).artboard('${missing[0]}', { width, height })… (ADR-0088), or use the eject path — see https://developers.snowcone.app/embed-mode#eject.
+  ```
+
+### `placement-mismatch`
+
+**Severity:** error (throws as `E_EMBED_CONFIG`)
+
+**Fires when:** The design's placement isn't one of the product's placements — the server renders a blank mockup.
+
+- `src/components/embed-realtime/validateEmbed.ts`
+
+  ```text
+  the design's artboard(s) [${foreign.join(', ')}] are not in product.placements [${product.placements!.join(', ')}]. Every artboard name must equal a real product placement label (renderState targets placements by that name), or the server renders a blank mockup. Fix the `name` passed to design({ name }) / design().artboard(name, …).
+  ```
+
+### `duplicate-layer-names`
+
+**Severity:** warn (advisory)
+
+**Fires when:** Two layers share a name — name-bound hooks bind the FIRST match, so a control may edit the wrong layer.
+
+- `src/components/embed-realtime/validateEmbed.ts`
+
+  ```text
+  duplicate layer name(s) [${[...new Set(dupes)].join(', ')}] — useTextBinding(name) / useImageBinding(name) bind to the FIRST match, so a duplicate name makes a control edit the wrong layer. Keep names unique.
+  ```
+
+### `slow-render`
+
+**Severity:** warn (advisory)
+
+**Fires when:** Runtime (not mount-time): a render has been in flight past `SLOW_RENDER_HINT_MS` with no mockup and no error — the silent-hang class. The render may still arrive; this is a heads-up.
+
+- `src/components/editor/EditorRoot.tsx`

package/README.md

@@ -135,7 +135,8 @@ Every part renders minimal DOM tagged `data-sc-part` and themes through
 `.sc-root` CSS custom properties — the full generated reference is
 [`STYLING_CONTRACT.md`](./STYLING_CONTRACT.md). Composition mistakes throw
 structured `EditorError`s (stable `code` + `error.data`) in dev AND prod,
-contained by the Root's error boundary. Test with
+contained by the Root's error boundary — the full generated code catalog is
+[`ERROR_CONTRACT.md`](./ERROR_CONTRACT.md). Test with
 `@snowcone-app/canvas/testing`: `assertRenders` proves a design's bindings
 are alive; `expectNoEditorErrors()` makes contained errors fail your tests.