@snowcone-app/sdk 0.1.15 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.2.1
+
+### Patch Changes
+
+- [#233](https://github.com/snowcone-app/snowcone-monorepo/pull/233) [`8b08283`](https://github.com/snowcone-app/snowcone-monorepo/commit/8b0828340ea0d2852655bffe8436f0cb71bde3aa) Thanks [@kevinsproles](https://github.com/kevinsproles)! - fix(realtime): `mintRealtimeGrant` now honors the keyless publishable path
+
+  Omitting `apiKey` (or passing `undefined`/`null`/`''`) no longer sends a
+  broken `Authorization: Bearer undefined` header that 401s. The header is now
+  sent only when a key is actually provided, so `mintRealtimeGrant({ shop })`
+  uses the publishable shop-id path exactly as documented. `apiKey` is now typed
+  as optional.
+
+## 0.2.0
+
+### Minor Changes
+
+- [#220](https://github.com/snowcone-app/snowcone-monorepo/pull/220) [`aa318b5`](https://github.com/snowcone-app/snowcone-monorepo/commit/aa318b51a15e977ecb993c81ae30b6afcf6864b8) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Add realtime saved-design-state API: `createDesignState` (top-level export for building a design state payload) and `RenderSession.renderSavedState(placement, stateId)` (render a previously-saved design state in a realtime session). These were already in `main` and documented on developers.snowcone.app but were missing from the published `@snowcone-app/sdk@0.1.15`, so docs examples failed to compile against the npm package.
+
 All notable changes to the Merch SDK will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
@@ -8,6 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.1.9] - 2025-10-16
 
 ### Added
+
 - **DOM-Based URL Resolution** - Intelligent URL resolution for transformed assets
   - Added `resolveUrlFromDOM()` to find actual rendered URLs in the DOM
   - Automatically resolves Vercel Blob Storage URLs from v0.dev
@@ -15,18 +34,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Perfect for environments where image URLs are transformed at runtime
 
 ### Changed
+
 - **Enhanced URL Normalization** - Multi-tier resolution strategy
   1. First attempts to find actual URL in DOM (for v0/Blob Storage)
   2. Falls back to `window.location.origin` conversion
   3. Warns about localhost URLs for better developer experience
 
 ### Fixed
+
 - Relative URLs now work correctly in v0.dev and Vercel Blob Storage environments
 - Mockup generation can access transformed image URLs with hash suffixes
 
 ## [0.1.8] - 2025-10-16
 
 ### Added
+
 - **Automatic URL Normalization** - Relative artwork URLs are now automatically converted to absolute URLs
   - Added `normalizeImageUrl()` utility function in `utils/url.ts`
   - Supports `/images/art.jpg`, `./art.jpg`, `../art.jpg` patterns
@@ -34,6 +56,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - SSR-safe with helpful warnings
 
 ### Changed
+
 - **Design Generation** - All artwork URLs are normalized in `createDesignForPlacements()`
   - Handles placement designs, provided images, and default URLs
   - Single source of truth for URL normalization
@@ -42,12 +65,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Clear error messages for invalid formats
 
 ### Fixed
+
 - Artwork URLs no longer require absolute paths - relative paths work seamlessly
 - Better developer experience matching Next.js image patterns
 
 ## [0.1.7] - 2025-10-16
 
 ### Changed
+
 - Version bump to maintain parity with @snowcone-app/ui 0.1.11
 - No functional changes in this release
 

package/README.md

@@ -167,25 +167,60 @@ const url = getMockupUrl('hoodie-black', {
 
 See [Public or signed](https://developers.snowcone.app/get-started) for the full picture.
 
-### React Hooks (Optional)
+### Realtime: render a saved canvas, no pixel upload
 
-For React applications, use the React-specific exports:
+`getMockupUrl` composites **one** artwork onto a product. For a full multi-layer
+design — the kind the Snowcone canvas editor produces — use a **`RenderSession`**:
+the browser sends a ~1 KB description of the canvas (or just a saved design's id)
+over a WebSocket, and the server rasterizes it and **fetches the referenced assets
+itself**. No per-placement PNG is ever uploaded, so it's fast on thin/mobile
+clients. This is exactly how the Snowcone PDP renders mockups (see ADR-0079).
+
+Authorize the session with a short-lived **grant**. Mint it server-side with a
+secret API key (`sk_…`, scope `mockups:realtime`) so the key never reaches the
+browser. Create the key — and find your publishable `shop.id` — on the
+[API keys page](https://snowcone.app/api-keys):
 
 ```typescript
-import { useRealtimeMockup } from '@snowcone-app/sdk/react';
-
-function MyComponent() {
-  const { mockupUrl, isGenerating } = useRealtimeMockup({
-    productId: 'BEEB77',
-    artworkUrl: artwork.src,
-    placement: 'Front',
-    alignment: 'center'
+// YOUR backend route, e.g. POST /api/realtime/grant
+import { mintRealtimeGrant } from '@snowcone-app/sdk';
+
+export async function POST(req: Request) {
+  const { shop } = await req.json();
+  const grant = await mintRealtimeGrant({
+    apiKey: process.env.SNOWCONE_API_KEY!, // secret — server only
+    shop,                                  // = shop.id (publishable)
   });
-
-  return <img src={mockupUrl} alt="Product mockup" />;
+  return Response.json(grant); // { token, expiresAt }
 }
 ```
 
+In the browser, point a `RenderSession` at that proxy and render. Render a **saved**
+design by id (no canvas JSON needed) or a live `serializeStateForServer(...)` state:
+
+```typescript
+import { RenderSession } from '@snowcone-app/sdk';
+
+const session = new RenderSession({
+  shop: 'YOUR_SHOP_ID',            // publishable, like Stripe pk_
+  grantUrl: '/api/realtime/grant', // your proxy above
+  product: { productId: 'BEEB77', mockupIds: ['Front'] },
+});
+
+session.onMockups((results) => { img.src = results[0].imageUrl; });
+
+// (a) render a SAVED canvas by id — ideal for fulfillment / agents
+await session.renderSavedState('Front', 'design-state-id');
+
+// (b) or render a live canvas state from @snowcone-app/canvas
+// import { serializeStateForServer } from '@snowcone-app/canvas';
+// await session.renderState('Front', serializeStateForServer(canvasState));
+```
+
+React apps can use the lower-level `useRealtimeMockup({ getToken })` hook from
+`@snowcone-app/sdk/react` instead. Full walkthrough:
+[Realtime server-side render](https://developers.snowcone.app/realtime).
+
 ## TypeScript Support
 
 Full TypeScript definitions are included. Import types:

package/dist/{chunk-RPA3B6I3.js → chunk-D5ZRGKA5.js}

@@ -472,6 +472,32 @@ var RealtimeMockupService = class {
     }
     return true;
   }
+  /**
+   * Render a SAVED canvas by reference (ADR-0079 Phase 4). Sends a `stateId`
+   * instead of inline state; the server resolves it, fetches the referenced
+   * assets, and renders — nothing is uploaded and the client need not hold the
+   * canvas JSON. One-shot (no throttle). Results arrive like any other render.
+   */
+  sendCanvasStateRef(placement, stateId) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.isConfigured) {
+      const reason = !this.ws ? "no WebSocket" : this.ws.readyState !== WebSocket.OPEN ? `ws.readyState=${this.ws.readyState}` : "not configured";
+      console.log(`[WS] sendCanvasStateRef BLOCKED for "${placement}": ${reason}`);
+      return false;
+    }
+    this.lastSentVersion = ++this.requestVersion;
+    this.latestSentVersionByPlacement[placement] = this.lastSentVersion;
+    const message = JSON.stringify({
+      type: "canvas_state",
+      placement,
+      version: this.lastSentVersion,
+      stateId
+    });
+    this.ws.send(message);
+    this.lastBlobSentAt = Date.now();
+    this.addLog(`Sent canvas stateId "${stateId}" for "${placement}" (v${this.lastSentVersion})`, "sent");
+    this.callbacks.onBlobSent?.(placement);
+    return true;
+  }
   sendCanvasStateImmediately(placement, state) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
       console.log(`[WS] sendCanvasStateImmediately ABORTED: ws not open`);

package/dist/index.cjs

@@ -76,6 +76,7 @@ __export(index_exports, {
   createComponent: () => createComponent,
   createContextProvider: () => createContextProvider,
   createDesignForPlacements: () => createDesignForPlacements,
+  createDesignState: () => createDesignState,
   createDevFetcher: () => createDevFetcher,
   createErrorHandler: () => createErrorHandler,
   createEventManager: () => createEventManager,
@@ -5276,6 +5277,32 @@ var RealtimeMockupService = class {
     }
     return true;
   }
+  /**
+   * Render a SAVED canvas by reference (ADR-0079 Phase 4). Sends a `stateId`
+   * instead of inline state; the server resolves it, fetches the referenced
+   * assets, and renders — nothing is uploaded and the client need not hold the
+   * canvas JSON. One-shot (no throttle). Results arrive like any other render.
+   */
+  sendCanvasStateRef(placement, stateId) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.isConfigured) {
+      const reason = !this.ws ? "no WebSocket" : this.ws.readyState !== WebSocket.OPEN ? `ws.readyState=${this.ws.readyState}` : "not configured";
+      console.log(`[WS] sendCanvasStateRef BLOCKED for "${placement}": ${reason}`);
+      return false;
+    }
+    this.lastSentVersion = ++this.requestVersion;
+    this.latestSentVersionByPlacement[placement] = this.lastSentVersion;
+    const message = JSON.stringify({
+      type: "canvas_state",
+      placement,
+      version: this.lastSentVersion,
+      stateId
+    });
+    this.ws.send(message);
+    this.lastBlobSentAt = Date.now();
+    this.addLog(`Sent canvas stateId "${stateId}" for "${placement}" (v${this.lastSentVersion})`, "sent");
+    this.callbacks.onBlobSent?.(placement);
+    return true;
+  }
   sendCanvasStateImmediately(placement, state) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
       console.log(`[WS] sendCanvasStateImmediately ABORTED: ws not open`);
@@ -5459,12 +5486,11 @@ ${versionToSend}
 var DEFAULT_GRANT_BASE = "https://api.snowcone.app";
 async function mintRealtimeGrant(opts) {
   const f = opts.fetch ?? globalThis.fetch;
+  const headers = { "Content-Type": "application/json" };
+  if (opts.apiKey) headers.Authorization = `Bearer ${opts.apiKey}`;
   const res = await f(`${opts.base ?? DEFAULT_GRANT_BASE}/realtime/grant`, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${opts.apiKey}`
-    },
+    headers,
     body: JSON.stringify({ shop: opts.shop })
   });
   if (!res.ok) {
@@ -5566,11 +5592,32 @@ var RenderSession = class {
    * the assets referenced inside — no pixels are uploaded. Results arrive via
    * {@link RenderSession.onMockups}. Safe to call repeatedly (e.g. on every
    * canvas edit); pass `throttleMs` to debounce during live dragging.
+   *
+   * `placement` is the print-area NAME (e.g. `'Front'`, the product's
+   * `placements[].label`) — a different id from the product's `mockupIds`, and it
+   * must match an artboard in `state`. The server renders only once it has a state
+   * for EVERY required placement, so on a multi-placement product call this once
+   * per placement; a missing one surfaces as an `incomplete_canvas_placements`
+   * error on {@link RenderSession.onError}.
+   *
+   * `state` is the flattened `serializeStateForServer()` shape — NOT the
+   * un-flattened shape `createDesignState` takes.
    */
   async renderState(placement, state, throttleMs = 0) {
     await this.connect();
     this.svc.sendCanvasState(placement, state, this.product?.mockupIds.length ?? 1, throttleMs);
   }
+  /**
+   * Render a SAVED canvas by reference (ADR-0079 Phase 4). The server resolves
+   * the `stateId`, fetches the referenced assets, and renders — no pixels are
+   * uploaded and you don't need to hold the canvas JSON. Ideal for re-rendering
+   * a stored design (fulfillment, agents, server-to-server). Results arrive via
+   * {@link RenderSession.onMockups}.
+   */
+  async renderSavedState(placement, stateId) {
+    await this.connect();
+    this.svc.sendCanvasStateRef(placement, stateId);
+  }
   /** Update only the mockup ids to render (reuses the current state). */
   updateMockupIds(mockupIds) {
     if (this.product) this.product = { ...this.product, mockupIds };
@@ -5603,6 +5650,29 @@ var RenderSession = class {
   }
 };
 
+// src/realtime/design-state.ts
+var TRANSPARENT_1X1_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+async function createDesignState(input) {
+  const f = input.fetch ?? globalThis.fetch;
+  const res = await f(`${input.base ?? DEFAULT_GRANT_BASE}/snowcone/design-states`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      productId: input.productId,
+      stateJson: JSON.stringify(input.state),
+      previewBase64: input.previewBase64 ?? TRANSPARENT_1X1_PNG
+    })
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`createDesignState failed: ${res.status}${detail ? ` ${detail}` : ""}`);
+  }
+  const body = await res.json();
+  const ds = body?.designState;
+  if (!ds?.id) throw new Error("createDesignState: response missing designState.id");
+  return { stateId: ds.id, stateUrl: ds.stateUrl ?? "", previewUrl: ds.previewUrl ?? "" };
+}
+
 // src/index.ts
 function getFetcher(config) {
   return config?.fetcher || globalThis.fetch.bind(globalThis);
@@ -5728,6 +5798,7 @@ function createClient(config) {
   createComponent,
   createContextProvider,
   createDesignForPlacements,
+  createDesignState,
   createDevFetcher,
   createErrorHandler,
   createEventManager,

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 export { createDevFetcher } from './dev-fetcher.cjs';
 import { PublicDesign, PublicFill, PublicOptions } from '@snowcone-app/mockup-url';
-import { O as OptionAttribute, a as OptionSelection, C as Combination, F as FrameworkAdapter, b as ComponentProps, c as ComponentDescriptor, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, g as FrameworkUtilities, P as PlacementSettings, M as MockupResult, R as RealtimeMockupService } from './websocket-BQH1HYJp.cjs';
-export { A as AdapterRegistry, h as ProductComponentContext, i as RealtimeMockupCallbacks, j as RealtimeMockupState, k as RenderResult, W as WebSocketConfig, l as WebSocketMessage, m as adapterRegistry, n as computeDisabledChoices, o as createComponent, p as defineComponent, q as deriveDefaultSelection, r as findBestCombination, s as getPricePreview, t as isOptionAvailable, u as resolveBestCombination } from './websocket-BQH1HYJp.cjs';
+import { O as OptionAttribute, a as OptionSelection, C as Combination, F as FrameworkAdapter, b as ComponentProps, c as ComponentDescriptor, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, g as FrameworkUtilities, P as PlacementSettings, M as MockupResult, R as RealtimeMockupService } from './websocket-Poy8LZNA.cjs';
+export { A as AdapterRegistry, h as ProductComponentContext, i as RealtimeMockupCallbacks, j as RealtimeMockupState, k as RenderResult, W as WebSocketConfig, l as WebSocketMessage, m as adapterRegistry, n as computeDisabledChoices, o as createComponent, p as defineComponent, q as deriveDefaultSelection, r as findBestCombination, s as getPricePreview, t as isOptionAvailable, u as resolveBestCombination } from './websocket-Poy8LZNA.cjs';
 
 interface CatalogProduct$2 {
     id: string;
@@ -16,7 +16,6 @@ interface CatalogProduct$2 {
     highestPrice?: number;
     mockups?: {
         id: string;
-        ar: number;
         gvids: string[];
     }[];
     options?: {
@@ -2519,14 +2518,26 @@ declare const DEFAULT_GRANT_BASE = "https://api.snowcone.app";
  * own the target `shop`. Returns a 60s grant your browser code opens the WS
  * with (hand it down via your own endpoint + {@link fetchRealtimeGrant}).
  *
+ * Omit `apiKey` (or pass `undefined`/`null`/`''`) to use the **keyless
+ * publishable path**: no `Authorization` header is sent and the grant is
+ * authorized by the publishable `shop` id alone. Passing a key uses the
+ * secret (sk_) path.
+ *
  * @example
  * // your backend route: POST /api/realtime/grant
  * const grant = await mintRealtimeGrant({ apiKey: process.env.SNOWCONE_API_KEY!, shop });
  * return Response.json(grant);
+ *
+ * @example
+ * // keyless publishable path — quick trials, no API key:
+ * const grant = await mintRealtimeGrant({ shop });
  */
 declare function mintRealtimeGrant(opts: {
-    /** Secret API key (sk_) with the `mockups:realtime` or `mockups` scope. */
-    apiKey: string;
+    /**
+     * Secret API key (sk_) with the `mockups:realtime` or `mockups` scope.
+     * Omit (or pass `undefined`/`null`/`''`) for the keyless publishable path.
+     */
+    apiKey?: string | null;
     /** Target shop id (= shop.id). Must belong to the key's organization. */
     shop: string;
     /** Backend base URL. Defaults to {@link DEFAULT_GRANT_BASE}. */
@@ -2581,8 +2592,18 @@ interface RenderState {
 /** Product the session renders against (Snowcone catalog ids). */
 interface RenderProduct {
     productId: string;
+    /**
+     * The mockup scenes to render — opaque catalog codes (the product's
+     * `mockups[].id`, e.g. `'FV1qjO'`). These are a DIFFERENT namespace from the
+     * `placement` you pass to {@link RenderSession.renderState} (a print-area name
+     * like `'Front'`). Don't pass a placement name here.
+     */
     mockupIds: string[];
-    /** Optional variant (gvid). Omit if the product has no variant axis. */
+    /**
+     * Optional variant (gvid). Omit if the product has no variant axis. Required
+     * for products with a color option — it auto-fills the color placement; without
+     * it the render waits for a color blob that never comes.
+     */
     variantId?: string;
     /** Render width in px (default 1000). */
     width?: number;
@@ -2631,8 +2652,26 @@ declare class RenderSession {
      * the assets referenced inside — no pixels are uploaded. Results arrive via
      * {@link RenderSession.onMockups}. Safe to call repeatedly (e.g. on every
      * canvas edit); pass `throttleMs` to debounce during live dragging.
+     *
+     * `placement` is the print-area NAME (e.g. `'Front'`, the product's
+     * `placements[].label`) — a different id from the product's `mockupIds`, and it
+     * must match an artboard in `state`. The server renders only once it has a state
+     * for EVERY required placement, so on a multi-placement product call this once
+     * per placement; a missing one surfaces as an `incomplete_canvas_placements`
+     * error on {@link RenderSession.onError}.
+     *
+     * `state` is the flattened `serializeStateForServer()` shape — NOT the
+     * un-flattened shape `createDesignState` takes.
      */
     renderState(placement: string, state: RenderState, throttleMs?: number): Promise<void>;
+    /**
+     * Render a SAVED canvas by reference (ADR-0079 Phase 4). The server resolves
+     * the `stateId`, fetches the referenced assets, and renders — no pixels are
+     * uploaded and you don't need to hold the canvas JSON. Ideal for re-rendering
+     * a stored design (fulfillment, agents, server-to-server). Results arrive via
+     * {@link RenderSession.onMockups}.
+     */
+    renderSavedState(placement: string, stateId: string): Promise<void>;
     /** Update only the mockup ids to render (reuses the current state). */
     updateMockupIds(mockupIds: string[]): void;
     /** Current rendered results. */
@@ -2644,6 +2683,45 @@ declare class RenderSession {
     private toConfig;
 }
 
+interface CreateDesignStateInput {
+    /** Catalog product code the design targets. */
+    productId: string;
+    /**
+     * The canvas state to persist — the **raw, un-flattened** stored shape:
+     * top-level `elements` with `transformType` + nested `transformData`, plus
+     * bare `artboards` metadata. The server flattens this at render time
+     * (`normalizeCanvasState`).
+     *
+     * ⚠️ This is NOT the `serializeStateForServer()` output you pass to
+     * `RenderSession.renderState` — that shape is already flattened and will
+     * mis-render if stored here. Persist the raw canvas state (e.g. `toJSON()`
+     * from the editor), not the server-render payload.
+     */
+    state: RenderState | Record<string, unknown>;
+    /**
+     * Preview thumbnail as a base64 PNG/JPEG (no data: prefix). Optional —
+     * defaults to a 1×1 transparent PNG, which is fine for render-only use.
+     */
+    previewBase64?: string;
+    /** Backend base URL. Defaults to {@link DEFAULT_GRANT_BASE}. */
+    base?: string;
+    /** Override fetch (tests / non-global-fetch runtimes). */
+    fetch?: typeof fetch;
+}
+interface CreatedDesignState {
+    /** The id to pass to `renderSavedState(placement, stateId)`. */
+    stateId: string;
+    /** Content-addressed URL of the persisted state JSON. */
+    stateUrl: string;
+    /** Content-addressed URL of the preview image. */
+    previewUrl: string;
+}
+/**
+ * Persist a canvas state and return its `stateId` (+ URLs). Pair with
+ * `RenderSession.renderSavedState(placement, stateId)`.
+ */
+declare function createDesignState(input: CreateDesignStateInput): Promise<CreatedDesignState>;
+
 interface ProductPlacement {
     label: string;
     x: number;
@@ -2698,4 +2776,4 @@ declare function getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Prom
  */
 declare function createClient(config: SdkConfig): SnowconeClient;
 
-export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct$2 as CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, autoRegister, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, withContext, withErrorHandling, withSyncErrorHandling };
+export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct$2 as CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, autoRegister, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, withContext, withErrorHandling, withSyncErrorHandling };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { createDevFetcher } from './dev-fetcher.js';
 import { PublicDesign, PublicFill, PublicOptions } from '@snowcone-app/mockup-url';
-import { O as OptionAttribute, a as OptionSelection, C as Combination, F as FrameworkAdapter, b as ComponentProps, c as ComponentDescriptor, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, g as FrameworkUtilities, P as PlacementSettings, M as MockupResult, R as RealtimeMockupService } from './websocket-BQH1HYJp.js';
-export { A as AdapterRegistry, h as ProductComponentContext, i as RealtimeMockupCallbacks, j as RealtimeMockupState, k as RenderResult, W as WebSocketConfig, l as WebSocketMessage, m as adapterRegistry, n as computeDisabledChoices, o as createComponent, p as defineComponent, q as deriveDefaultSelection, r as findBestCombination, s as getPricePreview, t as isOptionAvailable, u as resolveBestCombination } from './websocket-BQH1HYJp.js';
+import { O as OptionAttribute, a as OptionSelection, C as Combination, F as FrameworkAdapter, b as ComponentProps, c as ComponentDescriptor, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, g as FrameworkUtilities, P as PlacementSettings, M as MockupResult, R as RealtimeMockupService } from './websocket-Poy8LZNA.js';
+export { A as AdapterRegistry, h as ProductComponentContext, i as RealtimeMockupCallbacks, j as RealtimeMockupState, k as RenderResult, W as WebSocketConfig, l as WebSocketMessage, m as adapterRegistry, n as computeDisabledChoices, o as createComponent, p as defineComponent, q as deriveDefaultSelection, r as findBestCombination, s as getPricePreview, t as isOptionAvailable, u as resolveBestCombination } from './websocket-Poy8LZNA.js';
 
 interface CatalogProduct$2 {
     id: string;
@@ -16,7 +16,6 @@ interface CatalogProduct$2 {
     highestPrice?: number;
     mockups?: {
         id: string;
-        ar: number;
         gvids: string[];
     }[];
     options?: {
@@ -2519,14 +2518,26 @@ declare const DEFAULT_GRANT_BASE = "https://api.snowcone.app";
  * own the target `shop`. Returns a 60s grant your browser code opens the WS
  * with (hand it down via your own endpoint + {@link fetchRealtimeGrant}).
  *
+ * Omit `apiKey` (or pass `undefined`/`null`/`''`) to use the **keyless
+ * publishable path**: no `Authorization` header is sent and the grant is
+ * authorized by the publishable `shop` id alone. Passing a key uses the
+ * secret (sk_) path.
+ *
  * @example
  * // your backend route: POST /api/realtime/grant
  * const grant = await mintRealtimeGrant({ apiKey: process.env.SNOWCONE_API_KEY!, shop });
  * return Response.json(grant);
+ *
+ * @example
+ * // keyless publishable path — quick trials, no API key:
+ * const grant = await mintRealtimeGrant({ shop });
  */
 declare function mintRealtimeGrant(opts: {
-    /** Secret API key (sk_) with the `mockups:realtime` or `mockups` scope. */
-    apiKey: string;
+    /**
+     * Secret API key (sk_) with the `mockups:realtime` or `mockups` scope.
+     * Omit (or pass `undefined`/`null`/`''`) for the keyless publishable path.
+     */
+    apiKey?: string | null;
     /** Target shop id (= shop.id). Must belong to the key's organization. */
     shop: string;
     /** Backend base URL. Defaults to {@link DEFAULT_GRANT_BASE}. */
@@ -2581,8 +2592,18 @@ interface RenderState {
 /** Product the session renders against (Snowcone catalog ids). */
 interface RenderProduct {
     productId: string;
+    /**
+     * The mockup scenes to render — opaque catalog codes (the product's
+     * `mockups[].id`, e.g. `'FV1qjO'`). These are a DIFFERENT namespace from the
+     * `placement` you pass to {@link RenderSession.renderState} (a print-area name
+     * like `'Front'`). Don't pass a placement name here.
+     */
     mockupIds: string[];
-    /** Optional variant (gvid). Omit if the product has no variant axis. */
+    /**
+     * Optional variant (gvid). Omit if the product has no variant axis. Required
+     * for products with a color option — it auto-fills the color placement; without
+     * it the render waits for a color blob that never comes.
+     */
     variantId?: string;
     /** Render width in px (default 1000). */
     width?: number;
@@ -2631,8 +2652,26 @@ declare class RenderSession {
      * the assets referenced inside — no pixels are uploaded. Results arrive via
      * {@link RenderSession.onMockups}. Safe to call repeatedly (e.g. on every
      * canvas edit); pass `throttleMs` to debounce during live dragging.
+     *
+     * `placement` is the print-area NAME (e.g. `'Front'`, the product's
+     * `placements[].label`) — a different id from the product's `mockupIds`, and it
+     * must match an artboard in `state`. The server renders only once it has a state
+     * for EVERY required placement, so on a multi-placement product call this once
+     * per placement; a missing one surfaces as an `incomplete_canvas_placements`
+     * error on {@link RenderSession.onError}.
+     *
+     * `state` is the flattened `serializeStateForServer()` shape — NOT the
+     * un-flattened shape `createDesignState` takes.
      */
     renderState(placement: string, state: RenderState, throttleMs?: number): Promise<void>;
+    /**
+     * Render a SAVED canvas by reference (ADR-0079 Phase 4). The server resolves
+     * the `stateId`, fetches the referenced assets, and renders — no pixels are
+     * uploaded and you don't need to hold the canvas JSON. Ideal for re-rendering
+     * a stored design (fulfillment, agents, server-to-server). Results arrive via
+     * {@link RenderSession.onMockups}.
+     */
+    renderSavedState(placement: string, stateId: string): Promise<void>;
     /** Update only the mockup ids to render (reuses the current state). */
     updateMockupIds(mockupIds: string[]): void;
     /** Current rendered results. */
@@ -2644,6 +2683,45 @@ declare class RenderSession {
     private toConfig;
 }
 
+interface CreateDesignStateInput {
+    /** Catalog product code the design targets. */
+    productId: string;
+    /**
+     * The canvas state to persist — the **raw, un-flattened** stored shape:
+     * top-level `elements` with `transformType` + nested `transformData`, plus
+     * bare `artboards` metadata. The server flattens this at render time
+     * (`normalizeCanvasState`).
+     *
+     * ⚠️ This is NOT the `serializeStateForServer()` output you pass to
+     * `RenderSession.renderState` — that shape is already flattened and will
+     * mis-render if stored here. Persist the raw canvas state (e.g. `toJSON()`
+     * from the editor), not the server-render payload.
+     */
+    state: RenderState | Record<string, unknown>;
+    /**
+     * Preview thumbnail as a base64 PNG/JPEG (no data: prefix). Optional —
+     * defaults to a 1×1 transparent PNG, which is fine for render-only use.
+     */
+    previewBase64?: string;
+    /** Backend base URL. Defaults to {@link DEFAULT_GRANT_BASE}. */
+    base?: string;
+    /** Override fetch (tests / non-global-fetch runtimes). */
+    fetch?: typeof fetch;
+}
+interface CreatedDesignState {
+    /** The id to pass to `renderSavedState(placement, stateId)`. */
+    stateId: string;
+    /** Content-addressed URL of the persisted state JSON. */
+    stateUrl: string;
+    /** Content-addressed URL of the preview image. */
+    previewUrl: string;
+}
+/**
+ * Persist a canvas state and return its `stateId` (+ URLs). Pair with
+ * `RenderSession.renderSavedState(placement, stateId)`.
+ */
+declare function createDesignState(input: CreateDesignStateInput): Promise<CreatedDesignState>;
+
 interface ProductPlacement {
     label: string;
     x: number;
@@ -2698,4 +2776,4 @@ declare function getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Prom
  */
 declare function createClient(config: SdkConfig): SnowconeClient;
 
-export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct$2 as CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, autoRegister, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, withContext, withErrorHandling, withSyncErrorHandling };
+export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct$2 as CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, autoRegister, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, withContext, withErrorHandling, withSyncErrorHandling };

package/dist/index.js

@@ -4,7 +4,7 @@ import {
 import {
   REALTIME_WS_URL,
   RealtimeMockupService
-} from "./chunk-RPA3B6I3.js";
+} from "./chunk-D5ZRGKA5.js";
 
 // src/validation.ts
 import { z } from "zod";
@@ -4653,12 +4653,11 @@ function createSvelteComponent(descriptor, svelte) {
 var DEFAULT_GRANT_BASE = "https://api.snowcone.app";
 async function mintRealtimeGrant(opts) {
   const f = opts.fetch ?? globalThis.fetch;
+  const headers = { "Content-Type": "application/json" };
+  if (opts.apiKey) headers.Authorization = `Bearer ${opts.apiKey}`;
   const res = await f(`${opts.base ?? DEFAULT_GRANT_BASE}/realtime/grant`, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${opts.apiKey}`
-    },
+    headers,
     body: JSON.stringify({ shop: opts.shop })
   });
   if (!res.ok) {
@@ -4760,11 +4759,32 @@ var RenderSession = class {
    * the assets referenced inside — no pixels are uploaded. Results arrive via
    * {@link RenderSession.onMockups}. Safe to call repeatedly (e.g. on every
    * canvas edit); pass `throttleMs` to debounce during live dragging.
+   *
+   * `placement` is the print-area NAME (e.g. `'Front'`, the product's
+   * `placements[].label`) — a different id from the product's `mockupIds`, and it
+   * must match an artboard in `state`. The server renders only once it has a state
+   * for EVERY required placement, so on a multi-placement product call this once
+   * per placement; a missing one surfaces as an `incomplete_canvas_placements`
+   * error on {@link RenderSession.onError}.
+   *
+   * `state` is the flattened `serializeStateForServer()` shape — NOT the
+   * un-flattened shape `createDesignState` takes.
    */
   async renderState(placement, state, throttleMs = 0) {
     await this.connect();
     this.svc.sendCanvasState(placement, state, this.product?.mockupIds.length ?? 1, throttleMs);
   }
+  /**
+   * Render a SAVED canvas by reference (ADR-0079 Phase 4). The server resolves
+   * the `stateId`, fetches the referenced assets, and renders — no pixels are
+   * uploaded and you don't need to hold the canvas JSON. Ideal for re-rendering
+   * a stored design (fulfillment, agents, server-to-server). Results arrive via
+   * {@link RenderSession.onMockups}.
+   */
+  async renderSavedState(placement, stateId) {
+    await this.connect();
+    this.svc.sendCanvasStateRef(placement, stateId);
+  }
   /** Update only the mockup ids to render (reuses the current state). */
   updateMockupIds(mockupIds) {
     if (this.product) this.product = { ...this.product, mockupIds };
@@ -4797,6 +4817,29 @@ var RenderSession = class {
   }
 };
 
+// src/realtime/design-state.ts
+var TRANSPARENT_1X1_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+async function createDesignState(input) {
+  const f = input.fetch ?? globalThis.fetch;
+  const res = await f(`${input.base ?? DEFAULT_GRANT_BASE}/snowcone/design-states`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      productId: input.productId,
+      stateJson: JSON.stringify(input.state),
+      previewBase64: input.previewBase64 ?? TRANSPARENT_1X1_PNG
+    })
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`createDesignState failed: ${res.status}${detail ? ` ${detail}` : ""}`);
+  }
+  const body = await res.json();
+  const ds = body?.designState;
+  if (!ds?.id) throw new Error("createDesignState: response missing designState.id");
+  return { stateId: ds.id, stateUrl: ds.stateUrl ?? "", previewUrl: ds.previewUrl ?? "" };
+}
+
 // src/index.ts
 function getFetcher(config) {
   return config?.fetcher || globalThis.fetch.bind(globalThis);
@@ -4921,6 +4964,7 @@ export {
   createComponent,
   createContextProvider,
   createDesignForPlacements,
+  createDesignState,
   createDevFetcher,
   createErrorHandler,
   createEventManager,

package/dist/react.cjs

@@ -504,6 +504,32 @@ var RealtimeMockupService = class {
     }
     return true;
   }
+  /**
+   * Render a SAVED canvas by reference (ADR-0079 Phase 4). Sends a `stateId`
+   * instead of inline state; the server resolves it, fetches the referenced
+   * assets, and renders — nothing is uploaded and the client need not hold the
+   * canvas JSON. One-shot (no throttle). Results arrive like any other render.
+   */
+  sendCanvasStateRef(placement, stateId) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.isConfigured) {
+      const reason = !this.ws ? "no WebSocket" : this.ws.readyState !== WebSocket.OPEN ? `ws.readyState=${this.ws.readyState}` : "not configured";
+      console.log(`[WS] sendCanvasStateRef BLOCKED for "${placement}": ${reason}`);
+      return false;
+    }
+    this.lastSentVersion = ++this.requestVersion;
+    this.latestSentVersionByPlacement[placement] = this.lastSentVersion;
+    const message = JSON.stringify({
+      type: "canvas_state",
+      placement,
+      version: this.lastSentVersion,
+      stateId
+    });
+    this.ws.send(message);
+    this.lastBlobSentAt = Date.now();
+    this.addLog(`Sent canvas stateId "${stateId}" for "${placement}" (v${this.lastSentVersion})`, "sent");
+    this.callbacks.onBlobSent?.(placement);
+    return true;
+  }
   sendCanvasStateImmediately(placement, state) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
       console.log(`[WS] sendCanvasStateImmediately ABORTED: ws not open`);

package/dist/react.d.cts

@@ -1,4 +1,4 @@
-import { M as MockupResult, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-BQH1HYJp.cjs';
+import { M as MockupResult, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-Poy8LZNA.cjs';
 
 interface UseRealtimeMockupOptions {
     wsUrl?: string;

package/dist/react.d.ts

@@ -1,4 +1,4 @@
-import { M as MockupResult, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-BQH1HYJp.js';
+import { M as MockupResult, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-Poy8LZNA.js';
 
 interface UseRealtimeMockupOptions {
     wsUrl?: string;

package/dist/react.js

@@ -1,6 +1,6 @@
 import {
   RealtimeMockupService
-} from "./chunk-RPA3B6I3.js";
+} from "./chunk-D5ZRGKA5.js";
 
 // src/realtime/react.ts
 import { useCallback, useEffect, useRef, useState } from "react";

package/dist/{websocket-BQH1HYJp.d.cts → websocket-Poy8LZNA.d.cts}

@@ -356,6 +356,13 @@ declare class RealtimeMockupService {
      * Alternative to sendCanvasBlob — the server renders the PNG instead of the client.
      */
     sendCanvasState(placement: string, state: object, mockupCount?: number, baseThrottleMs?: number): boolean;
+    /**
+     * Render a SAVED canvas by reference (ADR-0079 Phase 4). Sends a `stateId`
+     * instead of inline state; the server resolves it, fetches the referenced
+     * assets, and renders — nothing is uploaded and the client need not hold the
+     * canvas JSON. One-shot (no throttle). Results arrive like any other render.
+     */
+    sendCanvasStateRef(placement: string, stateId: string): boolean;
     private sendCanvasStateImmediately;
     private sendBlobImmediately;
     /**

package/dist/{websocket-BQH1HYJp.d.ts → websocket-Poy8LZNA.d.ts}

@@ -356,6 +356,13 @@ declare class RealtimeMockupService {
      * Alternative to sendCanvasBlob — the server renders the PNG instead of the client.
      */
     sendCanvasState(placement: string, state: object, mockupCount?: number, baseThrottleMs?: number): boolean;
+    /**
+     * Render a SAVED canvas by reference (ADR-0079 Phase 4). Sends a `stateId`
+     * instead of inline state; the server resolves it, fetches the referenced
+     * assets, and renders — nothing is uploaded and the client need not hold the
+     * canvas JSON. One-shot (no throttle). Results arrive like any other render.
+     */
+    sendCanvasStateRef(placement: string, stateId: string): boolean;
     private sendCanvasStateImmediately;
     private sendBlobImmediately;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/sdk",
-  "version": "0.1.15",
+  "version": "0.2.1",
   "description": "Snowcone SDK for product mockups and print-on-demand",
   "keywords": [
     "merch",