@snowcone-app/canvas 0.19.1 → 0.21.0

package/example/README.md

@@ -0,0 +1,179 @@
+<!-- Assembled by scripts/assemble-example.mjs from the repo's canonical
+     fixture (packages/canvas/fixtures/no-canvas-widget) plus this standalone
+     scaffolding, so the example builds against the PUBLISHED package. -->
+
+# Read me first (you are inside the npm tarball)
+
+This directory is the canonical `Editor.*` integration, shipped inside
+`@snowcone-app/canvas` so an agent in a host repo can onboard without any
+network fetch:
+
+- **`src/Widget.tsx` is the integration to copy** — `Editor.Root` +
+  `Editor.Preview` + `Editor.TextField` + `Editor.Buy`; the design-editor
+  chunk never loads in this composition.
+- `npm install && npm run build` here typechecks + builds it against the
+  published package. `npm run dev` serves it — rendering live needs a real
+  shop key and a grant route (see the docs link below).
+- **`../STYLING_CONTRACT.md`** is the generated restyling contract: every
+  `data-sc-part` value, the DOM each part renders, and every `.sc-root`
+  theming token — restyle without reading package source.
+- `../llms.txt` indexes everything agent-facing in this tarball. The full
+  hosted docs are one fetch: <https://developers.snowcone.app/llms-full.txt>.
+
+One caveat on the protocol below: it was written for contributors inside the
+snowcone monorepo — its `fixtures/<your-name>` paths and `FakeRenderSession`
+test harness are repo-internal, not shipped. In YOUR app the protocol is:
+copy `src/Widget.tsx`, change the three things it marks, and verify with
+`assertRenders` + `expectNoEditorErrors` from `@snowcone-app/canvas/testing`.
+
+---
+
+# Personalization widget — the canonical `Editor.*` example (copy me)
+
+This directory is a **template, not just an exhibit**. The fastest path to your
+own widget — measured at **zero failed iterations** in a cold-start agent run —
+is: copy this folder, change three things, write one test, run one command.
+
+## The protocol
+
+1. **Copy `src/Widget.tsx`** to `fixtures/<your-name>/src/Widget.tsx` (the
+   other files here — `index.html`, `vite.config.ts`, `src/main.tsx` — are
+   this fixture's CI plumbing; you don't need them unless you want a runnable
+   page).
+2. **Change three things in `src/Widget.tsx`:**
+   - the `design(…)` — your artboard size + layers (name every layer you want
+     to bind: `.text('…', { name: 'headline' })`);
+   - the `product` — your catalog ids (`productId`, `mockupIds`; get them from
+     `getProduct()` in `@snowcone-app/sdk` — the ids here are demo values).
+     A product with a COLOR variant axis also needs `variantId`, or the render
+     hangs (pass `options` too so it fails fast instead);
+   - the parts — `<Editor.TextField layer={d.layer('…')}/>` per bindable
+     layer (`optional` ⇒ doesn't gate Buy), `<Editor.Preview/>`,
+     `<Editor.Buy onAddToCart={…}/>`.
+3. **Write your test** at `src/components/editor/__tests__/<your-name>.test.tsx`,
+   copying the pattern in `canonicalExample.test.tsx` (it imports this widget).
+4. **Run `pnpm -C packages/canvas verify`** — typecheck + tests + the
+   bundle-isolation gate. Green = your integration is proven, no browser needed.
+
+`index.html` / `vite.config.ts` / `src/main.tsx` here are load-bearing only for
+THIS canonical fixture (the CI import-graph check builds it). Your copy doesn't
+need them unless you also want a runnable page — the test is the proof.
+
+## The test-harness contract (what the canonical test uses and why)
+
+```ts
+import { FakeRenderSession, mountFlushed } from './testHarness.js';
+import { expectNoEditorErrors } from '../../../testing/editorErrors.js';
+```
+
+- **Two `vi.mock` blocks are required**, copy them verbatim:
+  - `@snowcone-app/sdk` → swaps `RenderSession` for `FakeRenderSession` (no
+    network; you drive mockups by hand);
+  - `@iconify/react` → the embed entry registers icons at module load, and the
+    registry's async timers leak across happy-dom tests without the stub.
+- `FakeRenderSession.reset()` in `beforeEach`; `FakeRenderSession.last` is the
+  session your Root constructed.
+- `session.renderState` is a spy — every render push, with the serialized
+  state as call arg `[1]` (assert your personalization landed there).
+- `session.emitMockups([{ mockupId, imageUrl }])` simulates the server
+  answering. `mockupId` must be one of your `product.mockupIds` when your
+  Preview pins `mockupId=…`; an un-pinned Preview shows the first result.
+- `mountFlushed(<YourWidget/>)` renders and flushes effects + any settled
+  lazy chunks; returns `{ container, unmount }`.
+- `expectNoEditorErrors()` in `afterEach` — REQUIRED. Root's boundary contains
+  composition errors behind an error card in prod; this is what makes a
+  contained error fail your test instead of passing green.
+
+## Selector vocabulary (testing or driving the widget)
+
+| Selector | Means |
+|---|---|
+| `[data-sc-part="preview"]` | the live mockup `<img>` |
+| `[data-sc-part="preview-error"]` | the Preview's render/grant-failure surface (`role="alert"`, message in `data-sc-error`) — shown when a render fails before any mockup exists; a stale mockup beats a blank, so later errors keep the image |
+| `[data-sc-part="textfield"]` | a bound text input; `aria-label` defaults to the **layer name**, so `input[aria-label="headline"]` targets one field |
+| `[data-sc-part="buy"]` | the add-to-cart button |
+| `[data-sc-buy-state]` | `ready` / `incomplete` / `busy` |
+| `[data-sc-buy-missing]` | comma-joined reasons while incomplete, in a STABLE evaluation order you can assert on: `option:<key>`… (variant axes unselected, attribute order) → `variant` (complete selection matching no combination) → `layer:<name>` / `layer-seed:<name>` (per mounted field, mount order; `layer-seed` = still the placeholder) → `empty-design` → `quantity` |
+| `[data-sc-part="error"]` | Root's contained-error card (`[data-sc-part="error-retry"]` when retryable) |
+
+Multiple `<Editor.Preview/>` AND multiple `<Editor.TextField/>` under one Root
+are valid (one field per named layer). One `<Editor.Canvas/>` max.
+
+## Variant selection + quantity (Buy-owned)
+
+`Editor.Buy` owns variant selection and quantity; YOU render the variant UI
+with `useProductSelection()` (same barrel). `select(key, choice)` re-resolves
+the variant and the live preview follows — no remount, no session rebuild.
+`<Editor.Buy defaultQuantity={2}/>` seeds quantity; `setQuantity` changes it
+live. Don't drive variant switching through the Root `product.variantId` prop
+— that re-keys the whole render session (initial `variantId` on a color
+product is still required, it seeds the selection).
+
+A variant product needs an `options` block on the Root `product` — pass your
+catalog product's `options` verbatim; the shape is:
+
+```ts
+const product = {
+  productId: 'BEEB77',
+  mockupIds: ['FV1qjO'],
+  placements: ['Front'],
+  variantId: 'gv-black-s',                       // initial selection (REQUIRED for color axes)
+  options: {
+    attributes: {
+      Color: { choices: [{ label: 'Black', hex: '#000' }, { label: 'White', hex: '#fff' }] },
+      Size: { choices: [{ label: 'S' }, { label: 'M' }] },   // no hex = non-color axis
+    },
+    combinations: [
+      { variantId: 'gv-black-s', Color: 'Black', Size: 'S', price: 1900 },
+      { variantId: 'gv-black-m', Color: 'Black', Size: 'M', price: 2100 },
+    ],
+  },
+};
+```
+
+**The currency rule:** `attributes[key].choices` are always `{ label, hex? }`
+OBJECTS (use `hex` for swatches), but `select()`, `selection`, and
+`disabledChoices` all speak the choice's **`label` string** — pass
+`choice.label`, never the object. The hook's full surface:
+`{ attributes, selection, select, disabledChoices, variantId, price,
+quantity, setQuantity, complete, missing }`.
+
+```tsx
+function VariantPicker() {
+  const { attributes, selection, select, disabledChoices, price, quantity, setQuantity } =
+    useProductSelection();
+  return (
+    <>
+      {Object.entries(attributes).map(([key, attr]) => (
+        <div key={key}>
+          {attr.choices.map(({ label = '', hex }) => (
+            <button
+              key={label}
+              style={hex ? { background: hex } : undefined}
+              disabled={disabledChoices[key]?.includes(label)}
+              aria-pressed={selection[key] === label}
+              onClick={() => select(key, label)}
+            >
+              {label}
+            </button>
+          ))}
+        </div>
+      ))}
+      <button onClick={() => setQuantity(quantity + 1)}>qty {quantity} +</button>
+    </>
+  );
+}
+```
+
+## Failure-mode fixtures (build your error UI against real failures)
+
+From `@snowcone-app/canvas/testing`: `test403Design()` (asset-origin
+allowlist denial — deterministic 403), `testIncompleteDesign()` (Buy gates
+out of the box), `failingGrant()` (grant fetch rejects). For live contract
+checks, `assertRenders(design, product, { shop })` renders twice (seed +
+mutated bindings) and throws structured errors (`E_BINDING_INERT`,
+`E_ASSET_FORBIDDEN`, `E_RENDER_FAILED`) — network-real, so nightly/acceptance
+jobs, not per-PR unit tests.
+
+All `Editor.*` parts are stable (ADR-0085 — the default editor is rebuilt from
+them, CI-gated); the public surface is additive-only.

package/example/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Personalization widget — no-canvas Editor.* composition</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/example/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "snowcone-personalization-widget-example",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "description": "The canonical @snowcone-app/canvas Editor.* example: a no-canvas personalization widget (live preview + bound text field + smart add-to-cart).",
+  "scripts": {
+    "dev": "vite",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc --noEmit && vite build"
+  },
+  "dependencies": {
+    "@snowcone-app/canvas": "^0.21.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "@vitejs/plugin-react": "^4.7.0",
+    "typescript": "^5.9.3",
+    "vite": "^5.4.21"
+  }
+}

package/example/src/Widget.tsx

@@ -0,0 +1,62 @@
+/**
+ * THE canonical personalization example (ADR-0085 / plan D7): a no-canvas
+ * merch widget — live product preview, ONE personalized text layer, smart
+ * add-to-cart — composed from the public `Editor.*` parts. The full canvas
+ * editor never loads; CI asserts this build's static import graph excludes
+ * the rendering engine (`scripts/check-import-graph.mjs`).
+ *
+ * This fixture is also the P0.5 hard-gate exhibit: the same public surface
+ * (`Editor.Root` + parts) serves both this composition and the full
+ * canvas-mounting editor (see the dev app's scrolling editor page).
+ */
+
+import React from 'react';
+import { Editor, design, type EditorBuyPayload } from '@snowcone-app/canvas/embed';
+
+const SHOP_KEY = import.meta.env.VITE_SNOWCONE_SHOP ?? 'demo-shop';
+
+// The design is the single source of truth: it seeds the first render AND
+// mints the typed layer tokens the TextField binds with.
+const nameDrop = design({ name: 'Front', width: 1480, height: 2328 })
+  .background('https://dqMwU8Jct3.storage.snowcone.app/demo/demo-008.jpg', {
+    aspectRatio: 1480 / 2328,
+    name: 'art',
+  })
+  .text('YOUR NAME', { anchor: 'top', name: 'name' });
+
+const product = {
+  productId: 'BEEB77',
+  mockupIds: ['FV1qjO'],
+  placements: ['Front'],
+};
+
+export function PersonalizationWidget({
+  onAddToCart,
+}: {
+  /** Your cart handler. NOTE the payload's `designState` is the EDITOR shape
+   *  (flat `elements` + artboard metadata) — persist it as-is. It is NOT the
+   *  server render shape (`artboards[].elements`) the session pushes;
+   *  `payload.serverRequest` carries that one if you need it. */
+  onAddToCart?: (payload: EditorBuyPayload) => void;
+} = {}): React.ReactElement {
+  return (
+    <Editor.Root shop={SHOP_KEY} product={product} design={nameDrop} grantUrl="/api/realtime/grant">
+      <div style={{ display: 'grid', gap: 12, maxWidth: 320 }}>
+        <Editor.Preview alt="Your personalized tee" fallback={<div aria-busy="true">Rendering…</div>} />
+        <Editor.TextField layer={nameDrop.layer('name')} placeholder="Your name" />
+        <Editor.Buy
+          onAddToCart={
+            onAddToCart ??
+            (({ productId, quantity, designState }) => {
+              // The host's one line: persist the designState (the
+              // re-renderable source of truth) with the cart line.
+              console.log('add-to-cart', { productId, quantity, designState });
+            })
+          }
+        >
+          Add to cart · $24
+        </Editor.Buy>
+      </div>
+    </Editor.Root>
+  );
+}

package/example/src/main.tsx

@@ -0,0 +1,9 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { PersonalizationWidget } from './Widget.js';
+
+createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <PersonalizationWidget />
+  </React.StrictMode>,
+);

package/example/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src"]
+}

package/example/vite.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+// Standalone build of the canonical example against the PUBLISHED
+// @snowcone-app/canvas (the in-repo fixture variant of this file resolves the
+// package to workspace source instead; scripts/assemble-example.mjs swaps in
+// this one when the example ships in the tarball or runs in the
+// published-pins CI gate).
+export default defineConfig({
+  plugins: [react()],
+});

package/llms.txt

@@ -0,0 +1,45 @@
+# @snowcone-app/canvas — agent index (ships inside the npm tarball)
+
+Zero-network onboarding: everything listed here is included in this package.
+Read these before fetching anything.
+
+- example/ — THE canonical integration (a no-canvas personalization widget:
+  Editor.Root + Editor.Preview + Editor.TextField + Editor.Buy; the design
+  editor chunk never loads). Copy example/src/Widget.tsx into your app;
+  example/README.md has the copy protocol, the data-sc-* selector vocabulary,
+  variant selection + quantity via useProductSelection(), and the
+  failure-mode fixtures.
+- STYLING_CONTRACT.md — GENERATED restyling contract: every data-sc-part
+  value, the DOM each part renders, and every .sc-root theming token.
+  Restyle the parts without reading package source.
+- README.md — package overview: the canonical example first, then the
+  standalone design editor (SnowconeCanvas).
+
+Entry points:
+
+- @snowcone-app/canvas/embed — the Editor.* parts and SnowconeEditor (the
+  turnkey default composed from those same parts), the design() builder and
+  typed layer tokens, useProductSelection(), the turnkey
+  RealtimeEmbed/RealtimeCanvas/RealtimeMockup trio, and the chrome-building
+  hooks (useEditor, useLayers, useCommands, ...).
+- @snowcone-app/canvas — SnowconeCanvas, the standalone design editor.
+- @snowcone-app/canvas/testing — assertRenders (two-render binding-liveness
+  check), expectNoEditorErrors (REQUIRED in every integration test), and the
+  deterministic failure fixtures (test403Design, testIncompleteDesign,
+  failingGrant).
+- @snowcone-app/canvas/style.css — the required stylesheet. Fully namespaced
+  (.sc-root scope); it cannot collide with host CSS.
+
+Contracts to rely on:
+
+- All Editor.* throws are structured: EditorError with a stable `code` +
+  `error.data` (valid names, offending values, docSlug). Assert on codes,
+  never message prose.
+- Buy incompleteness is state, not an error: [data-sc-buy-state="incomplete"]
+  with machine-readable reason codes in [data-sc-buy-missing].
+- The public embed surface is additive-only (CI-pinned).
+
+Hosted docs (one fetch, the source of truth):
+https://developers.snowcone.app/llms-full.txt
+The primitives guide (grant-route framework variants, catalog ids, CMS/typed
+layer notes): https://developers.snowcone.app/primitives

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/canvas",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "Self-contained canvas editor component for e-commerce product customization",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -41,7 +41,10 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "llms.txt",
+    "STYLING_CONTRACT.md",
+    "example"
   ],
   "sideEffects": [
     "**/*.css",
@@ -107,7 +110,7 @@
     "react-colorful": "^5.6.1",
     "tailwind-merge": "^3.0.0",
     "tailwind-variants": "^3.1.1",
-    "@snowcone-app/sdk": "0.15.0"
+    "@snowcone-app/sdk": "0.16.0"
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.11.0",
@@ -169,7 +172,7 @@
     "vite-plugin-node-polyfills": "^0.24.0",
     "vitest": "^3.2.4",
     "zod": "^4.1.12",
-    "@snowcone-app/ui": "0.2.5"
+    "@snowcone-app/ui": "0.2.6"
   },
   "scripts": {
     "dev": "vite",
@@ -183,10 +186,12 @@
     "dev:lib": "pnpm run bundle:worker && vite build --config vite.lib.config.ts --watch",
     "preview": "vite preview",
     "typecheck": "tsc --noEmit -p tsconfig.json",
+    "typecheck:verify": "tsc --noEmit -p tsconfig.verify.json",
     "generate": "node scripts/generate.js",
-    "test": "pnpm run test:unit && pnpm run test:component && pnpm run test:ssr && pnpm run check:graph",
+    "gen:styling-contract": "STYLING_CONTRACT_WRITE=1 vitest run src/components/editor/__tests__/stylingContract.test.tsx",
+    "test": "pnpm run typecheck:verify && pnpm run test:unit && pnpm run test:component && pnpm run test:ssr && pnpm run check:graph",
     "check:graph": "node scripts/check-import-graph.mjs",
-    "verify": "pnpm run typecheck && pnpm run test:unit && pnpm run test:component && pnpm run check:graph",
+    "verify": "pnpm run typecheck && pnpm run typecheck:verify && pnpm run test:unit && pnpm run test:component && pnpm run check:graph",
     "test:unit": "vitest run",
     "test:ssr": "vitest run --config vitest.ssr.config.ts",
     "test:unit:watch": "vitest",