@snowcone-app/canvas 0.16.0 → 0.17.1

package/dist/api/embed.d.ts

@@ -34,6 +34,10 @@
  *
  * @packageDocumentation
  */
+export { Editor, DesignStateStore } from '../components/editor/index.js';
+export type { EditorRootProps, EditorRootBaseProps, EditorCanvasProps, EditorPreviewProps, EditorTextFieldProps, EditorBuyProps, EditorBuyPayload, BuyMissingReason, DesignState, } from '../components/editor/index.js';
+export { EditorError, isEditorError } from '../errors/editorError.js';
+export type { EditorErrorCode, EditorErrorData } from '../errors/editorError.js';
 export { RealtimeEmbed } from '../components/embed-realtime/RealtimeEmbed.js';
 export type { RealtimeEmbedProps, GrantSource } from '../components/embed-realtime/RealtimeEmbed.js';
 export { RealtimeCanvas } from '../components/embed-realtime/RealtimeCanvas.js';
@@ -43,10 +47,10 @@ export { RealtimeMockup } from '../components/embed-realtime/RealtimeMockup.js';
 export type { RealtimeMockupProps } from '../components/embed-realtime/RealtimeMockup.js';
 export { useRealtimeMockups } from '../components/embed-realtime/useRealtimeMockups.js';
 export type { UseRealtimeMockupsResult } from '../components/embed-realtime/useRealtimeMockups.js';
-export { validateEmbed } from '../components/embed-realtime/validateEmbed.js';
-export type { ValidateEmbedInput } from '../components/embed-realtime/validateEmbed.js';
-export { design, DesignBuilder } from '../design/design-builder.js';
-export type { Anchor, ShapeKind, DesignArtboard } from '../design/design-builder.js';
+export { validateEmbed, collectEmbedIssues } from '../components/embed-realtime/validateEmbed.js';
+export type { ValidateEmbedInput, EmbedIssue } from '../components/embed-realtime/validateEmbed.js';
+export { design, DesignBuilder, isLayerToken } from '../design/design-builder.js';
+export type { Anchor, ShapeKind, DesignArtboard, AnyDesign, LayerKind, LayerToken, } from '../design/design-builder.js';
 export { useEditor } from '../contexts/EditorContext.js';
 export type { EditorContextValue, EditorProviderProps } from '../contexts/EditorContext.js';
 export { useLayers } from '../hooks/useLayers.js';

package/dist/api/testing.d.ts

@@ -23,3 +23,4 @@
  */
 export { MockEditorProvider, MockEditorProviderWithState, createMockElement, createMockImageElement, createMockArtboard, waitFor, waitForExport, simulateKeyPress, createMockCanvas, assertElementProperties, getElementBounds, } from '../testing/index.js';
 export type { MockEditorProviderProps, MockEditorElement, } from '../testing/index.js';
+export { expectNoEditorErrors, getContainedEditorErrors, resetContainedEditorErrors, } from '../testing/editorErrors.js';

package/dist/components/editor/EditorBuy.d.ts

@@ -0,0 +1,49 @@
+import { default as React, CSSProperties, ReactNode } from 'react';
+import { CartDetail, RenderProduct } from '@snowcone-app/sdk';
+import { ServerRenderRequest } from '../../rendering/serialize-for-server.js';
+import { DesignState } from './designStateStore.js';
+/** A structured incompleteness reason — also serialized (comma-joined) into
+ *  the button's `data-sc-buy-missing` attribute for agents and styling. */
+export type BuyMissingReason = 'variant' | `layer:${string}` | `layer-seed:${string}` | 'empty-design' | 'quantity';
+export interface EditorBuyPayload {
+    productId: string;
+    variantId?: string;
+    quantity: number;
+    /** SDK cart detail (variant resolution + price) when the product carries
+     *  catalog `options`; `null` for option-less products. */
+    cartDetail: CartDetail | null;
+    /** The DESIGN STATE at click time (editor shape) — persist this; it is the
+     *  re-renderable source of truth for the purchased design. */
+    designState: DesignState;
+    /** The same state serialized for the server render path. */
+    serverRequest: ServerRenderRequest;
+}
+export interface EditorBuyProps {
+    /** The final submit — the host's one line. Everything before it (variant,
+     *  quantity, completeness, payload assembly) is this part's job. */
+    onAddToCart: (payload: EditorBuyPayload) => void | Promise<void>;
+    /** Initial quantity (integer ≥ 1; default 1). */
+    quantity?: number;
+    /** Button label. Defaults to "Add to cart". */
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}
+/** Pure completeness evaluation — exported for tests. @internal */
+export declare function evaluateBuyCompleteness(input: {
+    product: RenderProduct;
+    quantity: number;
+    textFields: Array<{
+        name: string;
+        optional: boolean;
+    }>;
+    textOf: (name: string) => string | undefined;
+    seedTextOf: (name: string) => string | undefined;
+    hasRenderableElement: boolean;
+}): BuyMissingReason[];
+/**
+ * The add-to-cart button, completeness-gated and payload-assembling.
+ *
+ * @experimental ADR-0085; subject to change until the P4 gate.
+ */
+export declare function EditorBuy(props: EditorBuyProps): React.ReactElement;

package/dist/components/editor/EditorCanvas.d.ts

@@ -0,0 +1,30 @@
+import { default as React, CSSProperties, ReactNode } from 'react';
+import { EditorCanvasImplProps } from './EditorCanvasImpl.js';
+import { SnowconeCanvasHandle } from '../embed/SnowconeCanvas.js';
+type ImplComponent = (typeof import('./EditorCanvasImpl.js'))['EditorCanvasImpl'];
+/** Load the heavy impl chunk. Exposed for the legacy `<RealtimeCanvas>`
+ *  wrapper so both share ONE lazy boundary (one chunk). @internal */
+export declare function loadCanvasImpl(): Promise<ImplComponent>;
+/** Swap the chunk loader — TEST-ONLY seam for the chunk-load-failure → error
+ *  card → retry contract (a real `import()` can't be made to fail once and
+ *  then succeed under the module cache). Returns a restore function.
+ *  @internal */
+export declare function __setCanvasImplLoaderForTests(loader: () => Promise<ImplComponent>): () => void;
+export interface EditorCanvasProps {
+    /** Your overlay controls — rendered inside the editor context, so the
+     *  binding hooks (`useTextBinding` …) resolve against live elements. */
+    children?: ReactNode;
+    /** Cap the canvas height in px. */
+    maxHeight?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * The editable artboard. Mount at most one under a Root
+ * (`E_DUPLICATE_CANVAS`); mount none for the no-canvas personalization
+ * composition.
+ *
+ * @experimental ADR-0085; subject to change until the P4 gate.
+ */
+export declare const EditorCanvas: React.ForwardRefExoticComponent<EditorCanvasProps & React.RefAttributes<SnowconeCanvasHandle>>;
+export type { EditorCanvasImplProps };

package/dist/components/editor/EditorCanvasImpl.d.ts

@@ -0,0 +1,33 @@
+import { default as React, CSSProperties, ReactNode } from 'react';
+import { CanvasState, SnowconeCanvasHandle } from '../embed/SnowconeCanvas.js';
+import { KitPresetId, KitDefinition } from '../../kits/types.js';
+import { CanvasServices } from '../../contexts/CanvasServicesContext.js';
+export interface EditorCanvasImplProps {
+    /** Your controls (toolbar, inputs). Rendered as an overlay inside the editor
+     *  context so binding hooks work. */
+    children?: ReactNode;
+    /** Editor chrome preset. `Editor.Canvas` pins the chrome-less `'embed-only'`;
+     *  the legacy `<RealtimeCanvas kit>` prop passes richer presets through. */
+    kit?: KitPresetId | KitDefinition;
+    /** Inherit the host app's theme instead of managing its own (default true). */
+    inheritTheme?: boolean;
+    /** Cap the canvas height in px. */
+    maxHeight?: number;
+    /** Privileged-service wiring override (usually inherited from Root). */
+    services?: CanvasServices;
+    /** Observe the live design state (the same {@link CanvasState} the Root's
+     *  state store tracks). Safe to pass inline — read through a ref. */
+    onChange?: (state: CanvasState) => void;
+    /** Whether the wrapping div self-applies `.sc-root`. The legacy
+     *  `<RealtimeCanvas>` always did (it could be the only Snowcone DOM on the
+     *  page); under `Editor.Root` the Root applies it once and parts never
+     *  self-apply (ADR-0085). Re-applying is harmless (same variables), so the
+     *  legacy wrapper keeps `true` for bit-identical back-compat. */
+    selfScope?: boolean;
+    /** `data-sc-part` value for the wrapping div (the parts contract). */
+    partAttr?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+export declare const EditorCanvasImpl: React.ForwardRefExoticComponent<EditorCanvasImplProps & React.RefAttributes<SnowconeCanvasHandle>>;
+export type { CanvasState, SnowconeCanvasHandle };

package/dist/components/editor/EditorPreview.d.ts

@@ -0,0 +1,39 @@
+import { default as React, CSSProperties, ReactNode } from 'react';
+export interface EditorPreviewProps {
+    /** Which mockup scene to show (a `product.mockupIds` entry). Defaults to the
+     *  first mockup that has rendered. */
+    mockupId?: string;
+    /** Shown before the first mockup arrives / while a render is in flight with no
+     *  prior image. Defaults to nothing. */
+    fallback?: ReactNode;
+    /** Alt text for the rendered image. */
+    alt?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * How far the displayed device-pixel width may exceed the delivered mockup's
+ * natural width before {@link resolutionMismatchHint} fires. Renders default to
+ * 1000px wide, so a 1000px image inside a ~1100 device-px slot is fine (browser
+ * downscale slack), but stretched across 2000 device px it looks soft and the
+ * developer deserves to hear why.
+ */
+export declare const RESOLUTION_MISMATCH_RATIO = 1.2;
+/** Rounds a device-pixel width up to the next {@link SUGGESTED_WIDTHS} step
+ *  (capped at the top step). */
+export declare function suggestRenderWidth(devicePx: number): number;
+/**
+ * Builds the dev-console warning shown when a delivered mockup's natural width
+ * is meaningfully below the width it's displayed at in DEVICE pixels (CSS width
+ * × `devicePixelRatio`) — the "my preview looks soft and nothing says why"
+ * trap: renders default to 1000px wide, which blurs on a large or high-density
+ * display. Returns `null` when the resolution is adequate (within
+ * {@link RESOLUTION_MISMATCH_RATIO}) or either measurement is unusable.
+ */
+export declare function resolutionMismatchHint(naturalWidth: number, devicePx: number): string | null;
+/**
+ * The live product mockup. Mount as many as you need under one Root.
+ *
+ * @experimental ADR-0085; subject to change until the P4 gate.
+ */
+export declare function EditorPreview({ mockupId, fallback, alt, className, style, }: EditorPreviewProps): React.ReactElement;

package/dist/components/editor/EditorRoot.d.ts

@@ -0,0 +1,86 @@
+import { default as React, ReactNode } from 'react';
+import { RenderProduct, MockupResult, RealtimeGrant } from '@snowcone-app/sdk';
+import { AnyDesign } from '../../design/design-builder.js';
+import { CanvasServices } from '../../contexts/CanvasServicesContext.js';
+/**
+ * How the session authorizes. Provide exactly one — the discriminated union makes
+ * "I forgot the grant" a compile error rather than a silent runtime hang.
+ *
+ * Member order is load-bearing: when NEITHER prop is supplied (the common
+ * mistake) TS reports the missing property of the LAST union member, so the
+ * `grantUrl` arm is kept last on purpose — the error then reads "Property
+ * 'grantUrl' is missing", pointing at the recommended prop instead of `grant`.
+ * Don't reorder these.
+ */
+export type GrantSource = {
+    /** Full control over fetching the grant: a token or a token factory. */
+    grant: RealtimeGrant | (() => Promise<RealtimeGrant>);
+    grantUrl?: never;
+} | {
+    /** Your endpoint returning `{ token, expiresAt }` for `POST { shop }` —
+     *  a same-origin proxy to `mintRealtimeGrant`. Recommended. */
+    grantUrl: string;
+    grant?: never;
+};
+export type EditorRootBaseProps = {
+    /** Publishable shop id (= shop.id, like a Stripe pk_). Billing target. */
+    shop: string;
+    /** Product to render against (catalog ids). `mockupIds` are scene codes
+     *  (product.mockups[].id), NOT placement names. Pass `placements`, `options`
+     *  + `requiredPlacements` so wiring mistakes (including a multi-placement
+     *  product, which the embed can't render) fail loud at mount instead of
+     *  hanging. */
+    product: RenderProduct;
+    /** Single source of truth — seeds the canvas AND the first render. Build it
+     *  with `design({ name, width, height })…`. Its artboard `name` is the
+     *  placement every render targets. */
+    design: AnyDesign;
+    /** Edit→render throttle in ms (default 200). */
+    throttleMs?: number;
+    /** Called whenever new mockups arrive. */
+    onMockups?: (results: MockupResult[]) => void;
+    /** Called on a render/timeout error. */
+    onRenderError?: (message: string) => void;
+    /** Override the realtime WS endpoint (defaults to the SDK's prod URL). */
+    wsUrl?: string;
+    /**
+     * Privileged-service wiring for the editor chrome (the Image Browser's
+     * stock-image search and AI generation tabs). Same pattern as `grantUrl`:
+     * host these URLs on your server; your vendor keys live there.
+     */
+    services?: CanvasServices;
+    children?: ReactNode;
+    /**
+     * Wiring-validation mode. `Editor.Root` defaults to `'throw'` (F3:
+     * console.error is invisible to headless agents — error-severity wiring
+     * issues throw `EditorError E_EMBED_CONFIG` into Root's boundary). The
+     * legacy `<RealtimeEmbed>` wrapper passes `'warn'` for back-compat
+     * (dev-only console diagnostics, never throws).
+     * @internal
+     */
+    __validation?: 'throw' | 'warn';
+};
+export type EditorRootProps = GrantSource & EditorRootBaseProps;
+/**
+ * How long a render may be in flight before the embed assumes something is wrong
+ * and surfaces a diagnostic. A healthy render returns in ~2s; the session's own
+ * watchdog is ~30s. 8s sits in between — long enough not to false-fire on a
+ * genuinely slow render, short enough to spare a first-timer the full 30s of
+ * silence.
+ */
+export declare const SLOW_RENDER_HINT_MS = 8000;
+/**
+ * The dev-console message shown when a render hasn't produced a mockup in
+ * {@link SLOW_RENDER_HINT_MS}. A general backstop for the whole silent-hang
+ * class — not just the missing-`variantId` trap — so a stuck embed always says
+ * *something* actionable instead of hanging quietly.
+ */
+export declare function slowRenderHint(placement: string): string;
+/**
+ * The root of an `Editor.*` composition. See the module doc for the state
+ * model; see `RealtimeEmbed` for the legacy turnkey wrapper this was
+ * extracted from.
+ *
+ * @experimental ADR-0085; subject to change until the P4 gate.
+ */
+export declare function EditorRoot(props: EditorRootProps): React.ReactElement;

package/dist/components/editor/EditorTextField.d.ts

@@ -0,0 +1,22 @@
+import { default as React, CSSProperties } from 'react';
+import { LayerToken } from '../../design/design-builder.js';
+export interface EditorTextFieldProps {
+    /** The text layer this input edits — mint with `design.layer("name")`.
+     *  Type-checked against the design's TEXT-layer names when the design is
+     *  statically built; runtime-validated always. */
+    layer: LayerToken<'text'>;
+    /** Marked optional ⇒ Buy completeness does not require it (C2/C3). */
+    optional?: boolean;
+    placeholder?: string;
+    /** Accessible label. Defaults to the layer name. */
+    'aria-label'?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A text input bound to a design layer. Works with or without a mounted
+ * `Editor.Canvas`.
+ *
+ * @experimental ADR-0085; subject to change until the P4 gate.
+ */
+export declare function EditorTextField(props: EditorTextFieldProps): React.ReactElement;

package/dist/components/editor/RootInternals.d.ts

@@ -0,0 +1,77 @@
+import { EditorError } from '../../errors/editorError.js';
+import { DesignStateStore } from './designStateStore.js';
+/** Imperative ops a mounted `Editor.Canvas` offers sibling parts. Routes
+ *  TextField writes through the editor command path (undo/redo, repaint) so
+ *  the editor document stays the single write authority while a canvas is
+ *  mounted (ADR-0085 §3). */
+export interface CanvasBridge {
+    /** Set a named text layer's content via editor commands. Returns false when
+     *  no live element carries the name. */
+    setTextByName(name: string, text: string): boolean;
+}
+export interface TextFieldRegistration {
+    name: string;
+    optional: boolean;
+}
+export declare class EditorPartsRegistry {
+    private canvasIds;
+    private requirements;
+    private textFields;
+    private bridge;
+    private listeners;
+    private version;
+    /** Monotonic snapshot for `useSyncExternalStore`. */
+    getVersion: () => number;
+    subscribe: (listener: () => void) => (() => void);
+    registerCanvas(instanceId: string): () => void;
+    hasCanvas(): boolean;
+    /** Declare that a part is meaningless without a mounted Canvas (ADR-0085 §4
+     *  table). Validated by Root once per commit. */
+    requireCanvas(instanceId: string, partName: string): () => void;
+    /** Run by Root during RENDER, re-triggered by every registry change — by
+     *  then the whole commit's registrations are in, so there is no race
+     *  against the lazy chunk (ADR-0085 §4). Throws land in Root's boundary. */
+    validate(): void;
+    registerTextField(instanceId: string, reg: TextFieldRegistration): () => void;
+    /** Mounted TextField registrations — Buy's required-layer list (C2/C3).
+     *  Unmounted (incl. conditionally hidden) fields are absent by construction. */
+    getTextFields(): TextFieldRegistration[];
+    registerCanvasBridge(bridge: CanvasBridge): () => void;
+    getCanvasBridge(): CanvasBridge | null;
+    private bump;
+}
+export interface EditorRootInternals {
+    /** The one live design state under this Root (ADR-0085 §3 / T2). */
+    store: DesignStateStore;
+    registry: EditorPartsRegistry;
+    /**
+     * Handler/async-time invariant channel (ADR-0085, D11 containment): React
+     * error boundaries only catch render/lifecycle throws, so handlers report
+     * here — throws in dev AND test (an agent's test must fail loud), routes to
+     * Root's error state (same visible card) in prod.
+     */
+    reportInvariant(error: EditorError): void;
+    /**
+     * Runtime-failure channel (NOT a composition mistake — e.g. the lazy
+     * renderer chunk failing to load): routes to Root's error card in every
+     * env, with a retry affordance. Never throws.
+     */
+    reportRuntimeError(error: EditorError): void;
+}
+export declare const EditorRootInternalsContext: import('react').Context<EditorRootInternals | null>;
+/**
+ * Read the Root internals. Throws `E_OUTSIDE_ROOT` (dev AND prod) when the
+ * part is mounted outside `<Editor.Root>` — the most common wiring mistake.
+ */
+export declare function useEditorRootInternals(partName: string): EditorRootInternals;
+/**
+ * Declare that the calling part requires a mounted `Editor.Canvas` under the
+ * same Root (ADR-0085 §4 — Controls/Add/History/Menu in P3; the throw is
+ * `E_REQUIRES_CANVAS`, validated race-free by Root once per commit).
+ */
+export declare function useRequiresCanvas(partName: string): void;
+/** Shared impl of the invariant channel. @internal */
+export declare function makeInvariantReporter(routeToErrorState: (error: EditorError) => void): {
+    reportInvariant: (error: EditorError) => void;
+    reportRuntimeError: (error: EditorError) => void;
+};

package/dist/components/editor/designStateStore.d.ts

@@ -0,0 +1,45 @@
+import { AnyElementConfig } from '../../types/index.js';
+/** Editor-shape design state — the same shape `design.toJSON()` produces and
+ *  `<SnowconeCanvas onChange>` emits (and `serializeStateForServer` accepts). */
+export interface DesignState {
+    elements: AnyElementConfig[];
+    artboards: Array<{
+        name: string;
+        width: number;
+        height: number;
+        backgroundColor?: string;
+        exportBackground?: boolean;
+    }>;
+    activeArtboard: string;
+}
+export declare class DesignStateStore {
+    private state;
+    /** Frozen snapshot of the values the design was seeded with — Buy's
+     *  "differs from seed" completeness rule (C3) compares against this. */
+    private readonly seedTextByName;
+    private readonly listeners;
+    constructor(seed: DesignState);
+    getState: () => DesignState;
+    subscribe: (listener: () => void) => (() => void);
+    /** Replace the whole state (the canvas `onChange` path). */
+    setState(next: DesignState): void;
+    /** The seed value of a named text layer (for completeness rule C3). */
+    seedTextOf(name: string): string | undefined;
+    /** Current text of a named text layer, or undefined when absent. */
+    textOf(name: string): string | undefined;
+    /** Kind of the named layer in the CURRENT state ('text' | 'image' | null
+     *  for unbindable), or undefined when no layer has the name. */
+    layerKindOf(name: string): 'text' | 'image' | null | undefined;
+    /** Names of bindable layers in the current state, for error messages. */
+    bindableLayerNames(): string[];
+    /**
+     * Direct write path for `Editor.TextField` when NO canvas is mounted (with
+     * one, writes route through the editor command path and arrive back here
+     * via `setState`). Immutable update; last-write-wins.
+     */
+    updateTextLayer(name: string, text: string): void;
+    /** ≥1 element with visible content (completeness rule C4): non-empty text,
+     *  an image with a URL, or a shape. Hidden elements don't count. */
+    hasRenderableElement(): boolean;
+    private emit;
+}

package/dist/components/editor/index.d.ts

@@ -0,0 +1,23 @@
+import { EditorRoot } from './EditorRoot.js';
+import { EditorPreview } from './EditorPreview.js';
+import { EditorTextField } from './EditorTextField.js';
+import { EditorBuy } from './EditorBuy.js';
+export declare const Editor: {
+    /** The one provider boundary — session, design, live state, error boundary. */
+    readonly Root: typeof EditorRoot;
+    /** The editable artboard (the ONE lazy renderer boundary — D9). */
+    readonly Canvas: import('react').ForwardRefExoticComponent<import('./EditorCanvas.js').EditorCanvasProps & import('react').RefAttributes<import('./EditorCanvasImpl.js').SnowconeCanvasHandle>>;
+    /** Live product mockup. ×N under one Root is valid. */
+    readonly Preview: typeof EditorPreview;
+    /** Form input bound to a design text layer by typed token (T1). */
+    readonly TextField: typeof EditorTextField;
+    /** Smart commerce part: completeness + payload assembly; submit = host callback. */
+    readonly Buy: typeof EditorBuy;
+};
+export type { EditorRootProps, EditorRootBaseProps, GrantSource } from './EditorRoot.js';
+export type { EditorCanvasProps } from './EditorCanvas.js';
+export type { EditorPreviewProps } from './EditorPreview.js';
+export type { EditorTextFieldProps } from './EditorTextField.js';
+export type { EditorBuyProps, EditorBuyPayload, BuyMissingReason } from './EditorBuy.js';
+export type { DesignState } from './designStateStore.js';
+export { DesignStateStore } from './designStateStore.js';

package/dist/components/embed-realtime/RealtimeCanvas.d.ts

@@ -15,7 +15,7 @@ export interface RealtimeCanvasProps {
      *
      * To ship a real editor through the turnkey realtime path, pass a richer
      * preset — `'compact-customizer'` (a trimmed toolbar) or `'pro-studio'` (full
-     * panels). Every edit still flows to the shared {@link RenderSession} as a
+     * panels). Every edit still flows to the shared RenderSession as a
      * server render automatically; you get add-element / font-size / layers for
      * free without ejecting to a raw `SnowconeCanvas` + `RenderSession`.
      *

package/dist/components/embed-realtime/RealtimeEmbed.d.ts

@@ -1,79 +1,6 @@
-import { default as React, ReactNode } from 'react';
-import { RenderProduct, MockupResult, RealtimeGrant } from '@snowcone-app/sdk';
-import { DesignBuilder } from '../../design/design-builder.js';
-import { CanvasServices } from '../../contexts/CanvasServicesContext.js';
-/**
- * How the session authorizes. Provide exactly one — the discriminated union makes
- * "I forgot the grant" a compile error rather than a silent runtime hang.
- *
- * Member order is load-bearing: when NEITHER prop is supplied (the common
- * mistake) TS reports the missing property of the LAST union member, so the
- * `grantUrl` arm is kept last on purpose — the error then reads "Property
- * 'grantUrl' is missing", pointing at the recommended prop instead of `grant`.
- * Don't reorder these.
- */
-export type GrantSource = {
-    /** Full control over fetching the grant: a token or a token factory. */
-    grant: RealtimeGrant | (() => Promise<RealtimeGrant>);
-    grantUrl?: never;
-} | {
-    /** Your endpoint returning `{ token, expiresAt }` for `POST { shop }` —
-     *  a same-origin proxy to `mintRealtimeGrant`. Recommended. */
-    grantUrl: string;
-    grant?: never;
-};
-export type RealtimeEmbedProps = GrantSource & {
-    /** Publishable shop id (= shop.id, like a Stripe pk_). Billing target. */
-    shop: string;
-    /** Product to render against (catalog ids). `mockupIds` are scene codes
-     *  (product.mockups[].id), NOT placement names. Pass `placements`, `options`
-     *  + `requiredPlacements` so wiring mistakes (including a multi-placement
-     *  product, which the embed can't render) fail loud at mount instead of
-     *  hanging. */
-    product: RenderProduct;
-    /** Single source of truth — seeds the canvas AND the first render. Build it
-     *  with `design({ name, width, height })…`. Its artboard `name` is the
-     *  placement every render targets. */
-    design: DesignBuilder;
-    /** Edit→render throttle in ms (default 200). */
-    throttleMs?: number;
-    /** Called whenever new mockups arrive. */
-    onMockups?: (results: MockupResult[]) => void;
-    /** Called on a render/timeout error. */
-    onRenderError?: (message: string) => void;
-    /** Override the realtime WS endpoint (defaults to the SDK's prod URL). */
-    wsUrl?: string;
-    /**
-     * Privileged-service wiring for the editor chrome (the Image Browser's
-     * stock-image search and AI generation tabs). Same pattern as `grantUrl`:
-     * host these URLs on your server; your vendor keys live there. Flows to
-     * every `<RealtimeCanvas>` inside this embed. Tabs without a configured
-     * service do not render.
-     *
-     * @example
-     * ```tsx
-     * <RealtimeEmbed
-     *   services={{ imageSearchUrl: '/api/image-search', generateUrl: '/api/generate-image' }}
-     *   …
-     * />
-     * ```
-     */
-    services?: CanvasServices;
-    children?: ReactNode;
-};
-/**
- * How long a render may be in flight before the embed assumes something is wrong
- * and surfaces a diagnostic. A healthy render returns in ~2s; the session's own
- * watchdog is ~30s. 8s sits in between — long enough not to false-fire on a
- * genuinely slow render, short enough to spare a first-timer the full 30s of
- * silence.
- */
-export declare const SLOW_RENDER_HINT_MS = 8000;
-/**
- * The dev-console message shown when a render hasn't produced a mockup in
- * {@link SLOW_RENDER_HINT_MS}. A general backstop for the whole silent-hang
- * class — not just the missing-`variantId` trap — so a stuck embed always says
- * *something* actionable instead of hanging quietly.
- */
-export declare function slowRenderHint(placement: string): string;
+import { default as React } from 'react';
+import { EditorRootBaseProps, GrantSource } from '../editor/EditorRoot.js';
+export { SLOW_RENDER_HINT_MS, slowRenderHint } from '../editor/EditorRoot.js';
+export type { GrantSource };
+export type RealtimeEmbedProps = GrantSource & Omit<EditorRootBaseProps, '__validation'>;
 export declare function RealtimeEmbed(props: RealtimeEmbedProps): React.ReactElement;

package/dist/components/embed-realtime/RealtimeMockup.d.ts

@@ -1,34 +1,5 @@
-import { default as React, CSSProperties, ReactNode } from 'react';
-export interface RealtimeMockupProps {
-    /** Which mockup scene to show (a `product.mockupIds` entry). Defaults to the
-     *  first mockup that has rendered. */
-    mockupId?: string;
-    /** Shown before the first mockup arrives / while a render is in flight with no
-     *  prior image. Defaults to nothing. */
-    fallback?: ReactNode;
-    /** Alt text for the rendered image. */
-    alt?: string;
-    className?: string;
-    style?: CSSProperties;
-}
-/**
- * How far the displayed device-pixel width may exceed the delivered mockup's
- * natural width before {@link resolutionMismatchHint} fires. Renders default to
- * 1000px wide, so a 1000px image inside a ~1100 device-px slot is fine (browser
- * downscale slack), but stretched across 2000 device px it looks soft and the
- * developer deserves to hear why.
- */
-export declare const RESOLUTION_MISMATCH_RATIO = 1.2;
-/** Rounds a device-pixel width up to the next {@link SUGGESTED_WIDTHS} step
- *  (capped at the top step). */
-export declare function suggestRenderWidth(devicePx: number): number;
-/**
- * Builds the dev-console warning shown when a delivered mockup's natural width
- * is meaningfully below the width it's displayed at in DEVICE pixels (CSS width
- * × `devicePixelRatio`) — the "my preview looks soft and nothing says why"
- * trap: renders default to 1000px wide, which blurs on a large or high-density
- * display. Returns `null` when the resolution is adequate (within
- * {@link RESOLUTION_MISMATCH_RATIO}) or either measurement is unusable.
- */
-export declare function resolutionMismatchHint(naturalWidth: number, devicePx: number): string | null;
-export declare function RealtimeMockup({ mockupId, fallback, alt, className, style, }: RealtimeMockupProps): React.ReactElement;
+import { default as React } from 'react';
+import { EditorPreviewProps } from '../editor/EditorPreview.js';
+export { RESOLUTION_MISMATCH_RATIO, resolutionMismatchHint, suggestRenderWidth, } from '../editor/EditorPreview.js';
+export type RealtimeMockupProps = EditorPreviewProps;
+export declare function RealtimeMockup(props: RealtimeMockupProps): React.ReactElement;

package/dist/components/embed-realtime/context.d.ts

@@ -1,6 +1,7 @@
 import { RenderSession, RenderProduct, RenderState, MockupResult } from '@snowcone-app/sdk';
-import { DesignBuilder } from '../../design/design-builder.js';
+import { AnyDesign } from '../../design/design-builder.js';
 import { PieceGuidesConfig } from '../embed/SnowconeCanvas.js';
+import { DesignStateStore } from '../editor/designStateStore.js';
 export interface EmbedContextValue {
     /** The single session the editor pushes renders to. `null` if the session
      *  failed to construct (a config fail-fast, surfaced via `error`). Escape
@@ -8,7 +9,7 @@ export interface EmbedContextValue {
     session: RenderSession | null;
     /** The design the embed was seeded with — single source of truth for both the
      *  canvas seed and the seed render. */
-    design: DesignBuilder;
+    design: AnyDesign;
     /** The placement name (= the design's artboard name). Both the canvas artboard
      *  and every `renderState` call use this; derived once so it can't drift. */
     placement: string;
@@ -32,6 +33,15 @@ export interface EmbedContextValue {
     pieceGuides: PieceGuidesConfig | null;
     /** Dispatch a server render for the embed's placement. Sets `isRendering`. */
     pushRender: (state: RenderState, throttleMs?: number) => void;
+    /**
+     * The ONE live design state under this Root (ADR-0085 §3 / T2): seeded from
+     * `design`, updated by every canvas change and every `Editor.TextField`
+     * write, last-write-wins. Commerce parts read THIS, never the seed. Stable
+     * identity; subscribe for updates (`useSyncExternalStore`-shaped).
+     *
+     * @experimental ADR-0085; subject to change until the P4 gate.
+     */
+    stateStore: DesignStateStore;
 }
 export declare const EmbedContext: import('react').Context<EmbedContextValue | undefined>;
 /**

package/dist/components/embed-realtime/validateEmbed.d.ts

@@ -1,9 +1,23 @@
 import { RenderProduct } from '@snowcone-app/sdk';
-import { DesignBuilder } from '../../design/design-builder.js';
+import { AnyDesign } from '../../design/design-builder.js';
 export interface ValidateEmbedInput {
     shop: string;
     product: RenderProduct;
-    design: DesignBuilder;
+    design: AnyDesign;
     hasGrant: boolean;
 }
-export declare function validateEmbed({ shop, product, design, hasGrant }: ValidateEmbedInput): void;
+/** One wiring problem found at mount. `error`-severity issues break the embed
+ *  (no render will ever arrive / it targets the wrong thing); `warn`-severity
+ *  issues are advisory. */
+export interface EmbedIssue {
+    severity: 'error' | 'warn';
+    /** Stable issue key, carried into `EditorError.data.issue` in throw mode. */
+    issue: 'missing-shop' | 'missing-grant' | 'empty-mockup-ids' | 'variant-required' | 'multi-placement' | 'placement-mismatch' | 'duplicate-layer-names';
+    message: string;
+}
+/** Find every wiring problem. Pure — no logging, no throwing. */
+export declare function collectEmbedIssues({ shop, product, design, hasGrant }: ValidateEmbedInput): EmbedIssue[];
+/** Legacy advisory API: log everything, never throw. (`placement-mismatch`
+ *  keeps its historical `console.warn` level here; in `Editor.Root`'s throw
+ *  mode it is error-severity per F3.) */
+export declare function validateEmbed(input: ValidateEmbedInput): void;