Editor primitives

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'],
  // BEEB77 has a COLOR axis (Frame) — a color product REQUIRES variantId, or
  // a live render times out. Read real ids from the catalog with getProduct().
  variantId: 'Pv1sLC',
};

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>
  );
}

// Next.js — app/api/realtime/grant/route.ts
// Sandbox: the publishable shop.id alone authorizes the grant (no apiKey).
import { mintRealtimeGrant } from '@snowcone-app/sdk';

export async function POST(req: Request) {
  const { shop } = await req.json();
  const grant = await mintRealtimeGrant({ shop }); // { token, expiresAt }
  return Response.json(grant);
}

// Remix / React Router — app/routes/api.realtime.grant.ts (a resource route)
import { mintRealtimeGrant } from '@snowcone-app/sdk';

export async function action({ request }: { request: Request }) {
  const { shop } = await request.json();
  return Response.json(await mintRealtimeGrant({ shop }));
}

// Plain Node/Express — server.ts
import { mintRealtimeGrant } from '@snowcone-app/sdk';

app.post('/api/realtime/grant', async (req, res) => {
  const grant = await mintRealtimeGrant({ shop: req.body.shop });
  res.json(grant);
});

// One line gets the whole PDP-grammar editor — header (history · menu ·
// buy pill), stage with the buyable mockup picture-in-picture, and the
// morphing control zone. Internally it is NOTHING but the parts on this
// page in our arrangement (CI-enforced), so customizing = recomposing.
import { SnowconeEditor, design } from '@snowcone-app/canvas/embed';
import '@snowcone-app/canvas/style.css';

const d = 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: 'headline' });

export function ProductPage() {
  return (
    <SnowconeEditor
      shop="YOUR_SHOP_ID"
      grantUrl="/api/realtime/grant"
      product={{ productId: 'BEEB77', mockupIds: ['FV1qjO'], variantId: 'Pv1sLC', placements: ['Front'] }}
      design={d}
      onAddToCart={({ designState }) => saveDraft(designState)}
    />
  );
}

// The same parts in YOUR grid: canvas left, a commerce rail right,
// contextual controls docked below. No Snowcone layout opinions leak in —
// the grid, the gap, the rail width are all host CSS.
import { Editor, design } from '@snowcone-app/canvas/embed';

const d = 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: 'headline' });

export function StudioSplit() {
  return (
    <Editor.Root
      shop="YOUR_SHOP_ID"
      grantUrl="/api/realtime/grant"
      product={{ productId: 'BEEB77', mockupIds: ['FV1qjO'], variantId: 'Pv1sLC', placements: ['Front'] }}
      design={d}
    >
      <div style={{ display: 'grid', gridTemplateColumns: '1fr 200px', gap: 24 }}>
        <Editor.Canvas />
        <aside style={{ display: 'grid', gap: 12, alignContent: 'start' }}>
          <Editor.Preview />
          <Editor.Buy onAddToCart={({ designState }) => saveDraft(designState)}>
            Add to cart
          </Editor.Buy>
          <Editor.Layers direction="vertical" />
        </aside>
      </div>
      <Editor.Controls placement="docked" />
    </Editor.Root>
  );
}

// Editor.Buy OWNS variant selection + quantity; YOU render the variant UI
// with useProductSelection() — select() re-resolves the variant and the live
// preview follows on the open session (no remount, no session rebuild).
import { useProductSelection } from '@snowcone-app/canvas/embed';

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>
      {price != null && <span>{(price / 100).toFixed(2)}</span>}
    </>
  );
}

import { design } from '@snowcone-app/canvas/embed';

const d = design({ name: 'Front', width: 1480, height: 2328 })
  .text('YOUR NAME', { anchor: 'top', name: 'headline' })
  .text('EST. 2026', { anchor: 'bottom', name: 'subline' });

d.layer('headline'); // ✓ a LayerToken<'text'>

// @ts-expect-error — a typo is a COMPILE error listing the valid names
d.layer('headlnie');

import { DesignBuilder } from '@snowcone-app/canvas/embed';

// A design loaded from a CMS / JSON string: same API, but the layer-name
// typing degrades to plain string — a typo now COMPILES. The runtime net
// still fires: layer() validates EAGERLY and throws E_LAYER_NOT_FOUND at the
// call site, listing the valid names per kind.
const fromCms = DesignBuilder.fromState(cmsState);
const token = fromCms.layer('headline'); // runtime-checked, not compile-checked

// Every part is sugar over the same headless floor. The STABLE useEditor()
// subset: elements (elements, getElementById), selection (selectedId,
// selectedElement, setSelectedId, …), command execution (executeElementUpdate,
// executeAddElement, executeRemoveElement, executeReorderElement,
// executeCommandBatch), undo/redo (undo, redo, canUndo, canRedo).
import { useEditor, useLayers } from '@snowcone-app/canvas/embed';

function MyChrome() {
  const { selectedElement, undo, redo, canUndo, canRedo } = useEditor();
  const { flatLayers, selectLayer } = useLayers();
  return (
    <div>
      <button onClick={undo} disabled={!canUndo}>Undo</button>
      <button onClick={redo} disabled={!canRedo}>Redo</button>
      {flatLayers.map((layer) => (
        <button key={layer.id} onClick={() => selectLayer(layer.id)}>
          {layer.name}
        </button>
      ))}
      {selectedElement && <span>editing: {selectedElement.id}</span>}
    </div>
  );
}

import { assertRenders, test403Design, testIncompleteDesign } from '@snowcone-app/canvas/testing';
import { design } from '@snowcone-app/canvas/embed';

// The two-render contract check: renders your design as seeded, renders it
// again with every named text layer mutated, and asserts the images DIFFER —
// a dead binding "renders fine" and only this catches it. Network-real: use
// it in nightly/acceptance jobs and agent verify loops, not per-PR unit tests.
const d = design({ name: 'Front', width: 1480, height: 2328 })
  .text('YOUR NAME', { anchor: 'top', name: 'headline' });

await assertRenders(d, { productId: 'BEEB77', mockupIds: ['FV1qjO'], placements: ['Front'] }, {
  shop: 'YOUR_SHOP_ID',
});
// Throws structured errors: E_BINDING_INERT (byte-identical renders),
// E_ASSET_FORBIDDEN (allowlist denial, with failedAssets), E_RENDER_FAILED.

// Deterministic failure fixtures — build your error UI against REAL failures:
const denied = test403Design();      // asset-origin allowlist denial, on demand
const incomplete = testIncompleteDesign(); // Buy gates with layer-seed:name