@snowcone-app/canvas 0.36.4 → 0.37.0

package/ERROR_CONTRACT.md

@@ -52,6 +52,12 @@ the issue key in `error.data.issue`.
 | [`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_FONT_LOAD_FAILED`](#e_font_load_failed) | throw | A custom (brand) font failed to load from its hosted URL — the binary fetch failed (CORS, 404, network) or FontFace rejected the bytes. Custom fonts NEVER fall back silently to a system face: the design would render with a different typeface/metrics everywhere it's consumed. `data` carries `family`, `url`, `weight`, `style`. Fix the URL (must serve the font file over a plain cross-origin GET) and re-register. Dev AND prod. |
 | [`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). |
+| [`E_BUNDLE_CONFIG_REQUIRED`](#e_bundle_config_required) | throw | `productToRenderConfig()` was handed a BUNDLE (a catalog product with a `bundle` block — several products in one mockup, ADR-0099). A bundle has no single `variantId` and its placements are role-scoped (`top.front`), so the single-product adapter cannot describe it: use `bundleToRenderConfig()` instead. Never renders the wrong thing. |
+| [`E_NOT_A_BUNDLE`](#e_not_a_bundle) | throw | `bundleToRenderConfig()` was handed a product with no `bundle` block — `picks` / `variants` are bundle parameters the server refuses on a single product. Use `productToRenderConfig()`. |
+| [`E_BUNDLE_ROLE_REQUIRED`](#e_bundle_role_required) | throw | A bundle placement was named WITHOUT its role (`"front"` instead of `"top.front"`): `options.placement` on `bundleToRenderConfig()`, or a design artboard on a bundle session. Two members can both have a "Front", so the bare label is never the identity — `validNames` lists the role-scoped keys. |
+| [`E_BUNDLE_ROLE_NOT_FOUND`](#e_bundle_role_not_found) | throw | `picks` / `variants` named a role the bundle has no slot for. `validNames` lists the bundle's roles. |
+| [`E_BUNDLE_PICK_NOT_FOUND`](#e_bundle_pick_not_found) | throw | `picks[role]` named a product that is not one of that slot's alternatives. `validNames` lists the slot's alternatives. |
+| [`E_BUNDLE_VARIANT_NOT_FOUND`](#e_bundle_variant_not_found) | throw | A slot has no resolvable variant: `variants[role]` is not one of the picked alternative's variant gvids (`validNames`), or the alternative publishes no variant at all. Every role of a bundle session needs a variant — the server keys the render on the per-role set. |
 | [`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. |
@@ -59,6 +65,8 @@ the issue key in `error.data.issue`.
 | [`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. |
+| [`bundle-role-required`](#bundle-role-required) | error → throws `E_EMBED_CONFIG` | BUNDLE session (ADR-0099): a design artboard is a bare label (`"Front"`) instead of a role-scoped key (`"top.front"`), or a bare `variantId` is set — the server refuses both (`E_BUNDLE_ROLE_REQUIRED`): two members can both have a "Front". |
+| [`bundle-variant-required`](#bundle-variant-required) | error → throws `E_EMBED_CONFIG` | BUNDLE session (ADR-0099): a role has no entry in `product.variants` — the server keys the render on the per-role variant set, so every role needs one (`bundleToRenderConfig` fills defaults; hand-written configs must too). |
 | [`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
@@ -289,6 +297,30 @@ the issue key in `error.data.issue`.
 
 **Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
 
+- `src/design/bundle-config.ts`
+
+  ```text
+  bundle ${catalogProduct.id} has no renderable placement "${options.placement}" for picks ${JSON.stringify(picks)}. Keys: [${placementKeys.join(', ')}].
+  ```
+
+  `error.data`: `code`, `productId`, `requested`, `picks`, `validNames`, `docSlug`
+
+- `src/design/bundle-config.ts`
+
+  ```text
+  bundle ${catalogProduct.id} has no renderable image placement for picks ${JSON.stringify(picks)} (a role-scoped, non-color placement with width/height). The catalog payload may be incomplete — fetch it via getProduct(), not a search hit.
+  ```
+
+  `error.data`: `code`, `productId`, `picks`, `docSlug`
+
+- `src/design/bundle-config.ts`
+
+  ```text
+  bundle ${catalogProduct.id} has no mockup scenes — nothing to render a preview into.
+  ```
+
+  `error.data`: `code`, `productId`, `docSlug`
+
 - `src/design/product-config.ts`
 
   ```text
@@ -573,6 +605,81 @@ the issue key in `error.data.issue`.
 
   `error.data`: `code`, `mode`, `count`, `min`
 
+### `E_BUNDLE_CONFIG_REQUIRED`
+
+**Fires when:** `productToRenderConfig()` was handed a BUNDLE (a catalog product with a `bundle` block — several products in one mockup, ADR-0099). A bundle has no single `variantId` and its placements are role-scoped (`top.front`), so the single-product adapter cannot describe it: use `bundleToRenderConfig()` instead. Never renders the wrong thing.
+
+**Docs:** <https://developers.snowcone.app/bundles> (`error.data.docSlug`)
+
+- `src/design/product-config.ts`
+
+  ```text
+  product ${catalogProduct.id} is a bundle (roles: [${catalogProduct.bundle.members.map((m) => m.role).join(', ')}]) — it has per-role variants and role-scoped placement keys, which the single-product config cannot describe. Use bundleToRenderConfig(product, { picks?, variants?, placement?, width? }) instead.
+  ```
+
+  `error.data`: `code`, `productId`, `validNames`, `docSlug`
+
+### `E_NOT_A_BUNDLE`
+
+**Fires when:** `bundleToRenderConfig()` was handed a product with no `bundle` block — `picks` / `variants` are bundle parameters the server refuses on a single product. Use `productToRenderConfig()`.
+
+- `src/design/bundle-config.ts`
+
+  ```text
+  product ${catalogProduct.id} has no bundle block — picks / variants are bundle parameters the server refuses on a single product (E_NOT_A_BUNDLE). Use productToRenderConfig() for it.
+  ```
+
+  `error.data`: `code`, `productId`, `docSlug`
+
+### `E_BUNDLE_ROLE_REQUIRED`
+
+**Fires when:** A bundle placement was named WITHOUT its role (`"front"` instead of `"top.front"`): `options.placement` on `bundleToRenderConfig()`, or a design artboard on a bundle session. Two members can both have a "Front", so the bare label is never the identity — `validNames` lists the role-scoped keys.
+
+- `src/design/bundle-config.ts`
+
+  ```text
+  placement "${options.placement}" names no role — on bundle ${catalogProduct.id} a placement is addressed by its role-scoped key. Keys: [${placementKeys.join(', ')}].
+  ```
+
+  `error.data`: `code`, `productId`, `requested`, `validNames`, `docSlug`
+
+### `E_BUNDLE_ROLE_NOT_FOUND`
+
+**Fires when:** `picks` / `variants` named a role the bundle has no slot for. `validNames` lists the bundle's roles.
+
+- `src/design/bundle-config.ts`
+
+  ```text
+  bundle ${catalogProduct.id} has no role "${role}" (in ${field}). Roles: [${roleNames.join(', ')}].
+  ```
+
+  `error.data`: `code`, `productId`, `field`, `role`, `validNames`, `docSlug`
+
+### `E_BUNDLE_PICK_NOT_FOUND`
+
+**Fires when:** `picks[role]` named a product that is not one of that slot's alternatives. `validNames` lists the slot's alternatives.
+
+- `src/design/bundle-config.ts`
+
+  ```text
+  bundle ${catalogProduct.id} role "${member.role}" has no alternative "${wanted}". Alternatives: [${alternatives.join(', ')}] — pass picks: { ${member.role}: "${alternatives[0]}" }.
+  ```
+
+  `error.data`: `code`, `productId`, `role`, `requested`, `validNames`, `docSlug`
+
+### `E_BUNDLE_VARIANT_NOT_FOUND`
+
+**Fires when:** A slot has no resolvable variant: `variants[role]` is not one of the picked alternative's variant gvids (`validNames`), or the alternative publishes no variant at all. Every role of a bundle session needs a variant — the server keys the render on the per-role set.
+
+- `src/design/bundle-config.ts`
+
+  ```text
+  ${accepted.length === 0 ? `bundle ${catalogProduct.id} role "${member.role}": alternative ${alt.productId} publishes no variant — `}nothing can render this slot (catalog data is incomplete).'
+          : `bundle ${catalogProduct.id} role "${member.role}" (${alt.productId}) has no variant "${requested}". Variants: [${accepted.join(', ')}] — pass variants: { ${member.role}: "${accepted[0]}" }.
+  ```
+
+  `error.data`: `code`, `productId`, `role`, `memberProductId`, `requested`, `validNames`, `docSlug`
+
 ## Embed wiring issues (the `onIssue` channel)
 
 Mount-time wiring problems and runtime stalls are `EmbedIssue` objects
@@ -666,6 +773,36 @@ so `Editor.Root` throws them as `E_EMBED_CONFIG` (the issue key is in
   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.
   ```
 
+### `bundle-role-required`
+
+**Severity:** error (throws as `E_EMBED_CONFIG`)
+
+**Fires when:** BUNDLE session (ADR-0099): a design artboard is a bare label (`"Front"`) instead of a role-scoped key (`"top.front"`), or a bare `variantId` is set — the server refuses both (`E_BUNDLE_ROLE_REQUIRED`): two members can both have a "Front".
+
+- `src/components/embed-realtime/validateEmbed.ts`
+
+  ```text
+  product ${product.productId} is a bundle, but the design's artboard(s) [${roleless.join(', ')}] name no role. On a bundle every placement is addressed by its role-scoped key (<role>.<key>)${keys.length ? ` — keys: [${keys.join(', ')}]` : ''}. Seed the design from bundleToRenderConfig(product).placement.key, not from a bare label.
+  ```
+
+- `src/components/embed-realtime/validateEmbed.ts`
+
+  ```text
+  product ${product.productId} is a bundle, but product.variantId ("${product.variantId}") names no slot — the server refuses it (E_BUNDLE_ROLE_REQUIRED). Name the variant per role instead: product.variants = { <role>: <gvid> } (bundleToRenderConfig fills it), and leave variantId unset.
+  ```
+
+### `bundle-variant-required`
+
+**Severity:** error (throws as `E_EMBED_CONFIG`)
+
+**Fires when:** BUNDLE session (ADR-0099): a role has no entry in `product.variants` — the server keys the render on the per-role variant set, so every role needs one (`bundleToRenderConfig` fills defaults; hand-written configs must too).
+
+- `src/components/embed-realtime/validateEmbed.ts`
+
+  ```text
+  product ${product.productId} is a bundle, but role(s) [${missingVariant.join(', ')}] have no entry in product.variants (${JSON.stringify(product.variants ?? {})}). Every role needs a variant — the server keys the render on the per-role set. Build the product with bundleToRenderConfig(product, { picks, variants }), which fills each slot's default.
+  ```
+
 ### `slow-render`
 
 **Severity:** warn (advisory)

package/dist/{ContextualToolbars-GAkUFq2m.js → ContextualToolbars-CG5Gmv_i.js}

@@ -3,8 +3,8 @@ import * as oe from "react";
 import Fe, { useRef as V, useEffect as Z, useCallback as S, useState as T, useLayoutEffect as Mo, useMemo as He, memo as Eo, useSyncExternalStore as ur } from "react";
 import { createPortal as Io } from "react-dom";
 import { u as ms, a as Ro, g as fr, h as pr } from "./design-builder-CqgTpp9B.js";
-import { o as zo, I as P, N as Se, Y as hr, O as le, Z as St, B as J, P as mr, T as he, i as me, j as ge, _ as j, n as Ht, d as Lo, U as Ze, W as gr, C as br, f as yr, S as xr } from "./useCommands-DC6ZPY1n.js";
-import { R as gs, L as Me, a as vr, I as Cr, T as st } from "./custom-icons-wZuopKx7.js";
+import { o as zo, I as P, N as Se, Y as hr, O as le, Z as St, B as J, P as mr, T as he, i as me, j as ge, _ as j, n as Ht, d as Lo, U as Ze, W as gr, C as br, f as yr, S as xr } from "./useCommands-CQi4Pyd2.js";
+import { R as gs, L as Me, a as vr, I as Cr, T as st } from "./custom-icons-D51KIAfz.js";
 import { M as Ao, ap as Fo, b7 as Oo, H as po, b8 as wr, c as bs, y as kr, b9 as Tr, ba as Nr, bb as Sr, bc as Dr, bd as ho, aA as mo, az as Mr, G as Dt, T as je, g as Er, I as ot, S as $s, P as _o, E as Ir, be as Bo, bf as Rr, L as zr } from "./FontAnalyzer-CEYA_6fY.js";
 import * as Mt from "@radix-ui/react-popover";
 import * as dt from "@radix-ui/react-slider";
@@ -6529,4 +6529,4 @@ export {
   Fl as s,
   Ei as u
 };
-//# sourceMappingURL=ContextualToolbars-GAkUFq2m.js.map
+//# sourceMappingURL=ContextualToolbars-CG5Gmv_i.js.map