@snowcone-app/canvas 0.37.1 → 0.38.0

package/ERROR_CONTRACT.md

@@ -36,7 +36,8 @@ the issue key in `error.data.issue`.
 | [`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_PLACEMENT`](#e_unknown_placement) | throw | `usePlacements().select()` / `.split()`: the label is neither a required product placement nor a design artboard (ADR-0088 / ADR-0101). Lists the valid placement labels. |
+| [`E_LINK_BASE`](#e_link_base) | throw | `usePlacements().link()`: the label is the BASE artboard — the one every linked placement inherits — so it cannot be re-linked (ADR-0101). Link a split placement instead, or call `linkAll()`. |
 | [`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). |
@@ -62,7 +63,7 @@ the issue key in `error.data.issue`.
 | [`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). |
+| [`placements-inherit-base`](#placements-inherit-base) | warn (advisory) | ADR-0101 advisory: the design authors 2+ artboards but leaves some required placements without one — those placements INHERIT the base (the first artboard), re-fit per placement. Not an error: base + overrides is the model. Assert on this to catch a half-finished per-placement seed. |
 | [`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". |
@@ -361,18 +362,48 @@ the issue key in `error.data.issue`.
 
 ### `E_UNKNOWN_PLACEMENT`
 
-**Fires when:** `usePlacements().select()`: the label names no artboard in the design (ADR-0088). Lists the valid placement labels.
+**Fires when:** `usePlacements().select()` / `.split()`: the label is neither a required product placement nor a design artboard (ADR-0088 / ADR-0101). 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).
+  no placement "${label}" — the product's placements are ${JSON.stringify(requiredPlacements)} and the design's artboards are ${JSON.stringify(placements)} (ADR-0088 / ADR-0101).
   ```
 
   `error.data`: `code`, `placement`, `validNames`, `docSlug`
 
+- `src/components/editor/EditorRoot.tsx`
+
+  ```text
+  cannot split "${label}" — the product's placements are ${JSON.stringify(requiredPlacements)} (ADR-0101).
+  ```
+
+  `error.data`: `code`, `placement`, `validNames`, `docSlug`
+
+### `E_LINK_BASE`
+
+**Fires when:** `usePlacements().link()`: the label is the BASE artboard — the one every linked placement inherits — so it cannot be re-linked (ADR-0101). Link a split placement instead, or call `linkAll()`.
+
+**Docs:** <https://developers.snowcone.app/embed-mode> (`error.data.docSlug`)
+
+- `src/components/editor/EditorRoot.tsx`
+
+  ```text
+  "${label}" is the base artboard — every linked placement inherits it, so it cannot be re-linked. Link a split placement instead, or call linkAll(). Artboards: ${JSON.stringify(placements)}.
+  ```
+
+  `error.data`: `code`, `artboardName`, `validNames`, `docSlug`
+
+- `src/components/editor/designStateStore.ts`
+
+  ```text
+  "${label}" is the base artboard — every linked placement inherits it, so it cannot be re-linked. Link a split placement instead, or call linkAll(). Artboards: ${JSON.stringify(this.artboardNames())}.
+  ```
+
+  `error.data`: `code`, `artboardName`, `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).
@@ -737,16 +768,16 @@ so `Editor.Root` throws them as `E_EMBED_CONFIG` (the issue key is in
   ${err instanceof Error ? err.message : String(err)}
   ```
 
-### `multi-placement`
+### `placements-inherit-base`
 
-**Severity:** error (throws as `E_EMBED_CONFIG`)
+**Severity:** warn (advisory)
 
-**Fires when:** The product requires several placements but this embed renders ONE — the server times out waiting on the rest (needs the eject path).
+**Fires when:** ADR-0101 advisory: the design authors 2+ artboards but leaves some required placements without one — those placements INHERIT the base (the first artboard), re-fit per placement. Not an error: base + overrides is the model. Assert on this to catch a half-finished per-placement seed.
 
 - `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.
+  product ${product.productId} requires placements [${required.join(', ')}]; the design authors [${artboardNames.join(', ')}], so [${inheriting.join(', ')}] inherit the base artboard "${artboardNames[0]}" (re-fit per placement, ADR-0101). Intended? Otherwise split them: design(…).artboard('${inheriting[0]}', { width, height })… or usePlacements().split('${inheriting[0]}') at runtime.
   ```
 
 ### `placement-mismatch`

package/STYLING_CONTRACT.md

@@ -29,6 +29,7 @@ stable hooks; `sc:`-prefixed utility classes are internal and NOT contract.
 | `menu` | Editor.Menu |
 | `placements` | Editor.Placements |
 | `placements-item` | Editor.Placements |
+| `placements-link-toggle` | Editor.Placements |
 | `preview` | Editor.Preview |
 | `preview-error` | Editor.Preview |
 | `preview-image` | Editor.Preview |
@@ -200,20 +201,41 @@ stable hooks; `sc:`-prefixed utility classes are internal and NOT contract.
   <input type="file">
 ```
 
-### `placements` — Editor.Placements — two-placement design
+### `placements` — Editor.Placements — split (per-placement artboards): tabs + re-link action
 
 ```html
 <div data-sc-part="placements">
   <button aria-pressed="true" data-sc-active="true" data-sc-part="placements-item" type="button">
   <button aria-pressed="false" data-sc-active="false" data-sc-part="placements-item" type="button">
+  <button data-sc-part="placements-link-toggle" type="button">
 ```
 
-### `placements-item` — Editor.Placements — one tab (active state in data-sc-active)
+### `placements` — Editor.Placements — linked (one design on every area, the default)
+
+```html
+<div data-sc-part="placements">
+  <span data-sc-active="true" data-sc-part="placements-item" title=<title>>
+  <button data-sc-part="placements-link-toggle" type="button">
+```
+
+### `placements-item` — Editor.Placements — one tab (active in data-sc-active, inherited in data-sc-linked)
 
 ```html
 <button aria-pressed="true" data-sc-active="true" data-sc-part="placements-item" type="button">
 ```
 
+### `placements-link-toggle` — Editor.Placements — "Use one design for all" (split state)
+
+```html
+<button data-sc-part="placements-link-toggle" type="button">
+```
+
+### `placements-link-toggle` — Editor.Placements — "Customize separately" (linked state)
+
+```html
+<button data-sc-part="placements-link-toggle" type="button">
+```
+
 ### `preview` — Editor.Preview — awaiting the first mockup
 
 ```html

package/dist/{CanvasRenderer-CTN4j-uO.js → CanvasRenderer-D-E5WWLm.js}

@@ -1,6 +1,6 @@
-import { a5 as ie, a6 as ae, aG as nt, a7 as Ot, aT as re, aR as le, aK as Yt, aQ as he, aJ as gt, aU as ce, aV as Gt, aW as de, aX as fe, c as Jt, aY as ge, aZ as ue, a_ as pe, a$ as ye, ae as Qt, aa as te, ai as pt, ab as ee, ac as Lt, aj as Xt, ah as Pt, ak as Nt, af as be, al as Se, b0 as Kt, b1 as me, b2 as Te, b3 as we, I as ve, b4 as xe, b5 as Me, b6 as tt } from "./FontAnalyzer-CEYA_6fY.js";
-import { T as Wt, b as Re, y as Ce, O as ke, P as Dt, F as At, Q as Pe, R as Ae, S as Ee, U as $t } from "./ExportManager-CDX5_up8.js";
-import { i as _t, a as He } from "./guards-DldCuuJq.js";
+import { k as ie, l as ae, Y as nt, m as Ot, Z as re, _ as le, $ as Yt, a0 as he, a1 as gt, a2 as ce, a3 as Gt, a4 as de, a5 as fe, c as Jt, a6 as ge, a7 as ue, a8 as pe, a9 as ye, aa as Qt, s as te, ab as pt, w as ee, ac as Lt, ad as Xt, ae as Pt, af as Nt, ag as be, ah as Se, ai as Kt, aj as me, ak as Te, al as we, I as ve, am as xe, an as Me, ao as tt } from "./FontAnalyzer-DWHS41ba.js";
+import { T as Wt, b as Re, u as Ce, K as ke, L as Dt, z as At, M as Pe, N as Ae, O as Ee, P as $t } from "./ExportManager-BbBfO22S.js";
+import { a as _t, i as He } from "./guards-DMmhw_Ow.js";
 const ct = {
   // Canvas-specific
   canvas: {
@@ -3456,4 +3456,4 @@ export {
   jt as g,
   Je as r
 };
-//# sourceMappingURL=CanvasRenderer-CTN4j-uO.js.map
+//# sourceMappingURL=CanvasRenderer-D-E5WWLm.js.map