@snowcone-app/canvas 0.26.0 → 0.28.0

package/ERROR_CONTRACT.md

@@ -42,11 +42,14 @@ the issue key in `error.data.issue`.
 | [`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_INVALID_PATCH`](#e_invalid_patch) | throw | `updateElement(target, patch)`: a patch key doesn't apply to the target element's kind (e.g. `fontSize` on a shape), or a value is out of range (opacity outside 0..1, fontSize/width/height <= 0, non-finite number, wrong primitive type). The message names the element kind and lists the valid keys for it. Dev AND prod. |
+| [`E_NO_ACTIVE_ARTBOARD`](#e_no_active_artboard) | throw | `addElement(spec)`: there is no active artboard to add the element to. Create or select an artboard first (`<Editor.Root>` seeds one automatically; with a raw `EditorProvider` use `executeCreateArtboard`). Replaces the old `handleAddElement` window.alert — agents read throws, not dialogs. |
 | [`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). |
+| [`E_DISTRIBUTE_MIN_THREE`](#e_distribute_min_three) | throw | `computeDistribute()` called with fewer than 3 movable elements — distributing needs something between the two ends. Gate the action on `useAlignDistribute().canDistribute` instead of calling below the threshold (the toolbar hides its distribute buttons for exactly this reason). |
 | [`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. |
@@ -118,6 +121,14 @@ the issue key in `error.data.issue`.
 
   `error.data`: `code`, `layerName`, `validNames`, `docSlug`
 
+- `src/hooks/elementPatch.ts`
+
+  ```text
+  no element with ${isToken ? 'layer name' : 'id or layer name'} "${key}" in this document. Valid layer names: ${JSON.stringify(names)}; valid ids: ${JSON.stringify(all.map((el) => el.id))}.
+  ```
+
+  `error.data`: `code`, `layerName`, `validNames`, `validIds`, `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`).
@@ -406,6 +417,34 @@ the issue key in `error.data.issue`.
 
   `error.data`: `code`, `docSlug`
 
+### `E_INVALID_PATCH`
+
+**Fires when:** `updateElement(target, patch)`: a patch key doesn't apply to the target element's kind (e.g. `fontSize` on a shape), or a value is out of range (opacity outside 0..1, fontSize/width/height <= 0, non-finite number, wrong primitive type). The message names the element kind and lists the valid keys for it. Dev AND prod.
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/hooks/elementPatch.ts`
+
+  ```text
+  ${message}
+  ```
+
+  `error.data`: `code`, `...data`, `docSlug`
+
+### `E_NO_ACTIVE_ARTBOARD`
+
+**Fires when:** `addElement(spec)`: there is no active artboard to add the element to. Create or select an artboard first (`<Editor.Root>` seeds one automatically; with a raw `EditorProvider` use `executeCreateArtboard`). Replaces the old `handleAddElement` window.alert — agents read throws, not dialogs.
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/contexts/EditorContext.tsx`
+
+  ```text
+  addElement({ type: "${elementType}" }) needs an active artboard and none exists. <Editor.Root> seeds one automatically; with a raw EditorProvider create one first (executeCreateArtboard) or select one (artboardManager.setActiveArtboard).
+  ```
+
+  `error.data`: `code`, `type`, `docSlug`
+
 ### `E_ASSET_FORBIDDEN`
 
 **Fires when:** `assertRenders`: the shop's asset-origin allowlist denied a design asset (translated from the server's 403 — F4).
@@ -498,6 +537,18 @@ the issue key in `error.data.issue`.
 
   `error.data`: `code`, `docSlug`
 
+### `E_DISTRIBUTE_MIN_THREE`
+
+**Fires when:** `computeDistribute()` called with fewer than 3 movable elements — distributing needs something between the two ends. Gate the action on `useAlignDistribute().canDistribute` instead of calling below the threshold (the toolbar hides its distribute buttons for exactly this reason).
+
+- `src/utils/alignDistribute.ts`
+
+  ```text
+  distribute ${mode} needs at least ${DISTRIBUTE_MIN_COUNT} movable elements, got ${items.length}. Gate the action on useAlignDistribute().canDistribute (or items.length >= DISTRIBUTE_MIN_COUNT) instead of calling computeDistribute below the threshold.
+  ```
+
+  `error.data`: `code`, `mode`, `count`, `min`
+
 ## Embed wiring issues (the `onIssue` channel)
 
 Mount-time wiring problems and runtime stalls are `EmbedIssue` objects