@snowcone-app/sdk 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.3.4
+
+### Patch Changes
+
+- [#288](https://github.com/snowcone-app/snowcone-monorepo/pull/288) [`7ccfe17`](https://github.com/snowcone-app/snowcone-monorepo/commit/7ccfe1724b166719e2aac4e0f5e9a2a5c2c440a4) Thanks [@kevinsproles](https://github.com/kevinsproles)! - `getProduct()` now throws an actionable error for an unknown product id/slug (naming the id, the index, and pointing to `listProducts()`) instead of a bare "Not found", so a typo'd catalog id no longer surfaces as the raw Meilisearch `document_not_found` shape.
+
+- [#281](https://github.com/snowcone-app/snowcone-monorepo/pull/281) [`9e3d941`](https://github.com/snowcone-app/snowcone-monorepo/commit/9e3d941419b3df004feb47369692d30a4a8a2938) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Coalesce duplicate realtime `connect()` calls while a grant is pending or the WebSocket is still connecting, preventing competing initial sockets and benign 1006 close noise during first render.
+
+- [#293](https://github.com/snowcone-app/snowcone-monorepo/pull/293) [`64bcaf0`](https://github.com/snowcone-app/snowcone-monorepo/commit/64bcaf0b61dcd611a81d9a9cb013ab89dc8003f7) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Stop idle canvases from continuously streaming server renders (which silently burned the realtime render budget). `serializeStateForServer` now quantizes element/artboard geometry to 0.01px so the render loop's sub-pixel float drift no longer produces a new wire state every frame, and `RealtimeMockupService` drops duplicate consecutive canvas states per placement. A naive `onChange → renderState` wiring no longer bills the integrator's realtime quota while the user is doing nothing.
+
+- [#300](https://github.com/snowcone-app/snowcone-monorepo/pull/300) [`f80f00a`](https://github.com/snowcone-app/snowcone-monorepo/commit/f80f00a0e38631aac936bfe60de14e7d47be3e6a) Thanks [@kevinsproles](https://github.com/kevinsproles)! - `mockupUrl()` now resolves the shop id and mockup base URL by reading `process.env.NEXT_PUBLIC_*` directly instead of through an aliased `const env = process.env`. The alias defeated Next/webpack's static inlining, so in browser bundles the values came back `undefined` and the live-preview URL fell through to the `SHOP_NOT_CONFIGURED` placeholder. Consumers relying on `NEXT_PUBLIC_SNOWCONE_SHOP_ID` / `NEXT_PUBLIC_MERCH_MOCKUP_URL` env fallbacks (rather than the explicit `shop` prop / `window.snowcone`) now get the configured values.
+
+## 0.3.3
+
+### Patch Changes
+
+- [#268](https://github.com/snowcone-app/snowcone-monorepo/pull/268) [`dd90eba`](https://github.com/snowcone-app/snowcone-monorepo/commit/dd90eba8bbfbbaef82379cb997af84e21f7cad8f) Thanks [@kevinsproles](https://github.com/kevinsproles)! - fix(realtime): fail fast when a color/variant product is missing `variantId`
+
+  `RenderSession` now rejects a product that has a real variant axis (its
+  `options.combinations` expose 2+ distinct `variantId`s) but no valid `variantId`,
+  surfacing an immediate, actionable error at config/`connect()` time instead of
+  hanging silently for ~30s until the watchdog. Pass the catalog product's
+  `options` on `RenderProduct` to opt in. Single-variant / no-option products are
+  unaffected and still render with no `variantId`. The watchdog remains as the
+  backstop. New exports: `assertVariantSelected`, `RenderProductOptions`,
+  `RenderProductCombination`.
+
 ## 0.3.2
 
 ### Patch Changes

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

@@ -19,6 +19,10 @@ var RealtimeMockupService = class {
   lastBlobSentAt = 0;
   canvasBlobs = /* @__PURE__ */ new Map();
   canvasStates = /* @__PURE__ */ new Map();
+  // Serialized JSON of the last canvas state ACTUALLY SENT per placement. Used to
+  // drop duplicate consecutive states so an idle canvas (whose onChange keeps
+  // firing identical states) doesn't stream renders and burn the realtime budget.
+  lastSentStateJson = {};
   colors = /* @__PURE__ */ new Map();
   lastSendTime = {};
   throttleTimeouts = {};
@@ -39,6 +43,8 @@ var RealtimeMockupService = class {
   // the WS with `?token=`, and renews ~15s before expiry via a `renew` message.
   tokenProvider;
   renewTimer = null;
+  isConnecting = false;
+  connectAttempt = 0;
   setCallbacks(callbacks) {
     this.callbacks = callbacks;
   }
@@ -65,16 +71,21 @@ var RealtimeMockupService = class {
     this.callbacks.onLog?.(message, type);
   }
   connect() {
-    if (this.ws?.readyState === WebSocket.OPEN) {
+    if (this.ws?.readyState === WebSocket.OPEN || this.ws?.readyState === WebSocket.CONNECTING || this.isConnecting) {
       return;
     }
+    const attempt = ++this.connectAttempt;
+    this.isConnecting = true;
     if (this.tokenProvider) {
       this.tokenProvider().then((grant) => {
+        if (attempt !== this.connectAttempt || !this.isConnecting) return;
         this.openSocket(grant.token);
         this.scheduleRenew(grant.expiresAt);
       }).catch((err) => {
+        if (attempt !== this.connectAttempt) return;
         this.addLog(`Failed to obtain realtime grant: ${err}`);
         this.status = "Disconnected";
+        this.isConnecting = false;
       });
       return;
     }
@@ -88,6 +99,7 @@ var RealtimeMockupService = class {
       console.log(`[WS] connection OPENED to ${this.wsUrl}`);
       this.addLog("WebSocket connection opened");
       this.status = "Connected";
+      this.isConnecting = false;
     };
     this.ws.onmessage = (event) => {
       try {
@@ -106,11 +118,13 @@ var RealtimeMockupService = class {
       this.isConfigured = false;
       this.configSent = false;
       this.clearRenew();
+      this.isConnecting = false;
       this.callbacks.onDisconnected?.();
     };
     this.ws.onerror = (error) => {
       this.addLog(`WebSocket error: ${error}`);
       this.status = "Disconnected";
+      this.isConnecting = false;
     };
   }
   scheduleRenew(expiresAt) {
@@ -260,6 +274,8 @@ var RealtimeMockupService = class {
     }
   }
   disconnect() {
+    this.connectAttempt++;
+    this.isConnecting = false;
     this.clearRenew();
     if (this.ws) {
       this.ws.close();
@@ -298,6 +314,7 @@ var RealtimeMockupService = class {
         this.canvasStates.clear();
         this.colors.clear();
         this.lastSendTime = {};
+        this.lastSentStateJson = {};
         Object.values(this.throttleTimeouts).forEach((timeout) => clearTimeout(timeout));
         this.throttleTimeouts = {};
         this.requestVersion = 0;
@@ -503,6 +520,11 @@ var RealtimeMockupService = class {
       console.log(`[WS] sendCanvasStateImmediately ABORTED: ws not open`);
       return;
     }
+    const stateJson = JSON.stringify(state);
+    if (this.lastSentStateJson[placement] === stateJson) {
+      this.addLog(`Skipped duplicate canvas state for "${placement}" (unchanged)`, "sent");
+      return;
+    }
     this.lastSentVersion = ++this.requestVersion;
     this.latestSentVersionByPlacement[placement] = this.lastSentVersion;
     const message = JSON.stringify({
@@ -512,6 +534,7 @@ var RealtimeMockupService = class {
       state
     });
     this.ws.send(message);
+    this.lastSentStateJson[placement] = stateJson;
     this.lastBlobSentAt = Date.now();
     this.addLog(`Sent canvas state for "${placement}" (${(message.length / 1024).toFixed(1)}KB, v${this.lastSentVersion})`, "sent");
     this.callbacks.onBlobSent?.(placement);

package/dist/index.cjs

@@ -65,6 +65,7 @@ __export(index_exports, {
   UniversalContextProvider: () => UniversalContextProvider,
   VueAdapter: () => VueAdapter,
   adapterRegistry: () => adapterRegistry,
+  assertVariantSelected: () => assertVariantSelected,
   autoRegister: () => autoRegister,
   buildMockupUrl: () => buildMockupUrl2,
   componentRegistry: () => componentRegistry,
@@ -1796,14 +1797,12 @@ function buildMockupUrl2(options, cfg) {
   );
 }
 function resolveMockupBaseUrl() {
-  const env = typeof process !== "undefined" ? process.env : void 0;
   const winConfig = typeof window !== "undefined" && window.snowcone || {};
-  return winConfig.mockupUrl || env?.SNOWCONE_IMAGE_URL || env?.NEXT_PUBLIC_MERCH_MOCKUP_URL || "https://cdn.snowcone.app";
+  return winConfig.mockupUrl || typeof process !== "undefined" && process.env?.SNOWCONE_IMAGE_URL || typeof process !== "undefined" && process.env?.NEXT_PUBLIC_MERCH_MOCKUP_URL || "https://cdn.snowcone.app";
 }
 function resolveShop() {
-  const env = typeof process !== "undefined" ? process.env : void 0;
   const winConfig = typeof window !== "undefined" && window.snowcone || {};
-  return winConfig.shop || env?.SNOWCONE_SHOP_ID || env?.NEXT_PUBLIC_SNOWCONE_SHOP_ID || "SHOP_NOT_CONFIGURED";
+  return winConfig.shop || typeof process !== "undefined" && process.env?.SNOWCONE_SHOP_ID || typeof process !== "undefined" && process.env?.NEXT_PUBLIC_SNOWCONE_SHOP_ID || "SHOP_NOT_CONFIGURED";
 }
 function mockupUrl(options) {
   const mockupBaseUrl = resolveMockupBaseUrl();
@@ -4836,6 +4835,10 @@ var RealtimeMockupService = class {
   lastBlobSentAt = 0;
   canvasBlobs = /* @__PURE__ */ new Map();
   canvasStates = /* @__PURE__ */ new Map();
+  // Serialized JSON of the last canvas state ACTUALLY SENT per placement. Used to
+  // drop duplicate consecutive states so an idle canvas (whose onChange keeps
+  // firing identical states) doesn't stream renders and burn the realtime budget.
+  lastSentStateJson = {};
   colors = /* @__PURE__ */ new Map();
   lastSendTime = {};
   throttleTimeouts = {};
@@ -4856,6 +4859,8 @@ var RealtimeMockupService = class {
   // the WS with `?token=`, and renews ~15s before expiry via a `renew` message.
   tokenProvider;
   renewTimer = null;
+  isConnecting = false;
+  connectAttempt = 0;
   setCallbacks(callbacks) {
     this.callbacks = callbacks;
   }
@@ -4882,16 +4887,21 @@ var RealtimeMockupService = class {
     this.callbacks.onLog?.(message, type);
   }
   connect() {
-    if (this.ws?.readyState === WebSocket.OPEN) {
+    if (this.ws?.readyState === WebSocket.OPEN || this.ws?.readyState === WebSocket.CONNECTING || this.isConnecting) {
       return;
     }
+    const attempt = ++this.connectAttempt;
+    this.isConnecting = true;
     if (this.tokenProvider) {
       this.tokenProvider().then((grant) => {
+        if (attempt !== this.connectAttempt || !this.isConnecting) return;
         this.openSocket(grant.token);
         this.scheduleRenew(grant.expiresAt);
       }).catch((err) => {
+        if (attempt !== this.connectAttempt) return;
         this.addLog(`Failed to obtain realtime grant: ${err}`);
         this.status = "Disconnected";
+        this.isConnecting = false;
       });
       return;
     }
@@ -4905,6 +4915,7 @@ var RealtimeMockupService = class {
       console.log(`[WS] connection OPENED to ${this.wsUrl}`);
       this.addLog("WebSocket connection opened");
       this.status = "Connected";
+      this.isConnecting = false;
     };
     this.ws.onmessage = (event) => {
       try {
@@ -4923,11 +4934,13 @@ var RealtimeMockupService = class {
       this.isConfigured = false;
       this.configSent = false;
       this.clearRenew();
+      this.isConnecting = false;
       this.callbacks.onDisconnected?.();
     };
     this.ws.onerror = (error) => {
       this.addLog(`WebSocket error: ${error}`);
       this.status = "Disconnected";
+      this.isConnecting = false;
     };
   }
   scheduleRenew(expiresAt) {
@@ -5077,6 +5090,8 @@ var RealtimeMockupService = class {
     }
   }
   disconnect() {
+    this.connectAttempt++;
+    this.isConnecting = false;
     this.clearRenew();
     if (this.ws) {
       this.ws.close();
@@ -5115,6 +5130,7 @@ var RealtimeMockupService = class {
         this.canvasStates.clear();
         this.colors.clear();
         this.lastSendTime = {};
+        this.lastSentStateJson = {};
         Object.values(this.throttleTimeouts).forEach((timeout) => clearTimeout(timeout));
         this.throttleTimeouts = {};
         this.requestVersion = 0;
@@ -5320,6 +5336,11 @@ var RealtimeMockupService = class {
       console.log(`[WS] sendCanvasStateImmediately ABORTED: ws not open`);
       return;
     }
+    const stateJson = JSON.stringify(state);
+    if (this.lastSentStateJson[placement] === stateJson) {
+      this.addLog(`Skipped duplicate canvas state for "${placement}" (unchanged)`, "sent");
+      return;
+    }
     this.lastSentVersion = ++this.requestVersion;
     this.latestSentVersionByPlacement[placement] = this.lastSentVersion;
     const message = JSON.stringify({
@@ -5329,6 +5350,7 @@ var RealtimeMockupService = class {
       state
     });
     this.ws.send(message);
+    this.lastSentStateJson[placement] = stateJson;
     this.lastBlobSentAt = Date.now();
     this.addLog(`Sent canvas state for "${placement}" (${(message.length / 1024).toFixed(1)}KB, v${this.lastSentVersion})`, "sent");
     this.callbacks.onBlobSent?.(placement);
@@ -5523,6 +5545,44 @@ async function fetchRealtimeGrant(grantUrl, shop, fetchImpl) {
 }
 
 // src/realtime/session.ts
+function variantIdsOf(product) {
+  const combos = product.options?.combinations;
+  if (!combos?.length) return [];
+  const ids = /* @__PURE__ */ new Set();
+  for (const c of combos) {
+    if (typeof c.variantId === "string" && c.variantId !== "") ids.add(c.variantId);
+  }
+  return [...ids];
+}
+function assertVariantSelected(product) {
+  const variantIds = variantIdsOf(product);
+  if (variantIds.length < 2) return;
+  const fix = `pass product.variantId from options.combinations[].variantId (valid ids: ${variantIds.join(", ")})`;
+  if (!product.variantId) {
+    throw new Error(
+      `RenderSession: product ${product.productId} requires a variantId \u2014 ${fix}`
+    );
+  }
+  if (!variantIds.includes(product.variantId)) {
+    throw new Error(
+      `RenderSession: product ${product.productId} has an invalid variantId "${product.variantId}" \u2014 ${fix}`
+    );
+  }
+}
+function warnUnknownPlacement(product, placement) {
+  const placements = product.placements;
+  if (!placements?.length) return null;
+  if (placements.includes(placement)) return null;
+  return `RenderSession: placement "${placement}" doesn't match product ${product.productId}'s placements: [${placements.join(", ")}]. Your artboard name + renderState placement arg must equal the catalog placements[].label.`;
+}
+function warnPlacementArtboardMismatch(placement, state) {
+  const artboards = state.artboards;
+  if (!Array.isArray(artboards) || artboards.length === 0) return null;
+  const names = artboards.map((a) => a.name).filter((n) => typeof n === "string");
+  if (names.length === 0) return null;
+  if (names.includes(placement)) return null;
+  return `RenderSession: renderState placement "${placement}" has no matching artboard in the state (artboards: [${names.join(", ")}]). The artboard name must equal the placement arg.`;
+}
 var DEFAULT_RENDER_TIMEOUT_MS = 3e4;
 var RenderSession = class {
   svc;
@@ -5538,6 +5598,7 @@ var RenderSession = class {
     if (!opts.getToken && !opts.grantUrl) {
       throw new Error("RenderSession: provide `grantUrl` or `getToken` to authorize the session");
     }
+    if (opts.product) assertVariantSelected(opts.product);
     this.opts = opts;
     this.product = opts.product ?? null;
     this.renderTimeoutMs = opts.renderTimeoutMs ?? DEFAULT_RENDER_TIMEOUT_MS;
@@ -5557,6 +5618,7 @@ var RenderSession = class {
   }
   /** Set or update the product. Sends config immediately if already connected. */
   setProduct(product) {
+    assertVariantSelected(product);
     this.product = product;
     this.svc.sendConfig(this.toConfig(product));
   }
@@ -5572,6 +5634,13 @@ var RenderSession = class {
       );
     }
     const product = this.product;
+    try {
+      assertVariantSelected(product);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.errorCb?.(message);
+      return Promise.reject(err instanceof Error ? err : new Error(message));
+    }
     this.ready = new Promise((resolve, reject) => {
       let settled = false;
       this.svc.setCallbacks({
@@ -5623,6 +5692,7 @@ var RenderSession = class {
    */
   async renderState(placement, state, throttleMs = 0) {
     await this.connect();
+    this.warnPlacement(placement, state);
     this.svc.sendCanvasState(placement, state, this.product?.mockupIds.length ?? 1, throttleMs);
     this.armWatchdog();
   }
@@ -5635,6 +5705,7 @@ var RenderSession = class {
    */
   async renderSavedState(placement, stateId) {
     await this.connect();
+    this.warnPlacement(placement);
     this.svc.sendCanvasStateRef(placement, stateId);
     this.armWatchdog();
   }
@@ -5653,6 +5724,28 @@ var RenderSession = class {
     this.svc.disconnect();
     this.ready = null;
   }
+  /**
+   * Emit loud, non-fatal warnings for the two ways a placement name silently
+   * produces a blank mockup: (1) the name isn't one of the product's known
+   * `placements` labels, and (2) no artboard in `state` is named after it. Each
+   * warning goes to BOTH `console.warn` and the `onError` callback (if wired) so
+   * a dev sees it whichever channel they watch. Never throws.
+   */
+  warnPlacement(placement, state) {
+    const warnings = [];
+    if (this.product) {
+      const w = warnUnknownPlacement(this.product, placement);
+      if (w) warnings.push(w);
+    }
+    if (state) {
+      const w = warnPlacementArtboardMismatch(placement, state);
+      if (w) warnings.push(w);
+    }
+    for (const w of warnings) {
+      console.warn(w);
+      this.errorCb?.(w);
+    }
+  }
   /**
    * (Re)arm the render watchdog. Clears any prior timer and, unless disabled
    * (`renderTimeoutMs <= 0`), starts a fresh one. If it fires before a mockup
@@ -5768,7 +5861,12 @@ async function getProduct(idOrSlug, config) {
   const url = `${meilisearchHost}/indexes/${meilisearchIndex}/documents/${idOrSlug}`;
   const res = await f(url, { method: "GET", headers });
   if (res.status === 404)
-    throw Object.assign(new Error("Not found"), { code: "NOT_FOUND" });
+    throw Object.assign(
+      new Error(
+        `getProduct: no catalog product "${idOrSlug}" in index "${meilisearchIndex}". Pass a valid product id/slug (browse with listProducts()).`
+      ),
+      { code: "NOT_FOUND", productId: idOrSlug }
+    );
   if (!res.ok) throw new Error(`getProduct failed: ${res.status}`);
   const raw = await res.json();
   return validateProductLoose(raw);
@@ -5831,6 +5929,7 @@ function createClient(config) {
   UniversalContextProvider,
   VueAdapter,
   adapterRegistry,
+  assertVariantSelected,
   autoRegister,
   buildMockupUrl,
   componentRegistry,

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-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';
+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-DTRStLRH.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-DTRStLRH.cjs';
 
 interface CatalogProduct$2 {
     id: string;
@@ -2584,8 +2584,7 @@ declare function fetchRealtimeGrant(grantUrl: string, shop: string, fetchImpl?:
  *   product: { productId: 'BEEB77', mockupIds: ['front'] },
  * });
  * session.onMockups((results) => { img.src = results[0].imageUrl; });
- * await session.connect();
- * session.renderState('Front', serializeStateForServer(canvasState));
+ * await session.renderState('Front', serializeStateForServer(canvasState));
  *
  * For the low-level escape hatch, use {@link RealtimeMockupService} directly.
  */
@@ -2604,6 +2603,29 @@ interface RenderState {
     elements?: Array<Record<string, unknown>>;
     [key: string]: unknown;
 }
+/**
+ * A single variant combination from the catalog product's `options.combinations`.
+ * Each combination pins one value per variant-affecting attribute plus the
+ * `variantId` (gvid) that selection resolves to. Pass `options` on
+ * {@link RenderProduct} so the session can FAIL FAST when a required `variantId`
+ * is missing instead of silently hanging until the watchdog.
+ */
+interface RenderProductCombination {
+    /** The variant (gvid) this combination resolves to. */
+    variantId?: string;
+    /** Attribute selections (e.g. `{ Frame: 'Walnut', Size: '5x7' }`). */
+    [attribute: string]: string | number | undefined;
+}
+/**
+ * The catalog product's `options` block (structurally typed). Only
+ * `combinations` is consumed by the session — to detect whether the product has
+ * a real variant axis (multiple distinct `variantId`s) so a missing/invalid
+ * {@link RenderProduct.variantId} can be rejected up front.
+ */
+interface RenderProductOptions {
+    combinations?: RenderProductCombination[];
+    [key: string]: unknown;
+}
 /** Product the session renders against (Snowcone catalog ids). */
 interface RenderProduct {
     productId: string;
@@ -2618,13 +2640,44 @@ interface RenderProduct {
      * 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.
+     *
+     * If you also pass {@link RenderProduct.options}, the session validates this
+     * up front: a product whose `options.combinations` exposes more than one
+     * variant REQUIRES a `variantId` (and it must be one of the combinations'),
+     * else the session throws immediately rather than hanging until the watchdog.
      */
     variantId?: string;
+    /**
+     * The catalog product's `options` block (its `options.combinations[].variantId`
+     * are the valid variant ids). Optional, but passing it lets the session detect
+     * a missing/invalid required `variantId` and FAIL FAST — turning the classic
+     * 30s silent hang into an immediate, actionable error. You can pass the whole
+     * catalog product's `options` object verbatim.
+     */
+    options?: RenderProductOptions;
+    /**
+     * The product's valid placement labels (the catalog product's
+     * `placements[].label`, e.g. `['Front']`). Optional, but passing it lets the
+     * session WARN LOUDLY when a `renderState(placement, ...)` call uses a name
+     * that isn't a real placement — turning the classic silent blank-mockup
+     * (server waits on `incomplete_canvas_placements`) into an actionable
+     * dev-time message. You can pass the catalog product's
+     * `placements.map(p => p.label)` verbatim.
+     */
+    placements?: string[];
     /** Render width in px (default 1000). */
     width?: number;
     /** Per-placement settings (tiling, scale mode). */
     placementSettings?: Record<string, PlacementSettings>;
 }
+/**
+ * Throws immediately if the product has a variant axis (its
+ * `options.combinations` expose 2+ distinct `variantId`s) but no valid
+ * `variantId` was supplied. This is the fail-fast guard for the otherwise-silent
+ * 30s render hang on color/variant products. Products with no `options` (or a
+ * single variant) are left untouched — they render fine with no `variantId`.
+ */
+declare function assertVariantSelected(product: RenderProduct): void;
 interface RenderSessionOptions {
     /** Publishable shop id (= shop.id, like Stripe pk_). */
     shop: string;
@@ -2712,6 +2765,14 @@ declare class RenderSession {
     getMockups(): MockupResult[];
     /** Close the WebSocket and stop auto-renew. */
     close(): void;
+    /**
+     * Emit loud, non-fatal warnings for the two ways a placement name silently
+     * produces a blank mockup: (1) the name isn't one of the product's known
+     * `placements` labels, and (2) no artboard in `state` is named after it. Each
+     * warning goes to BOTH `console.warn` and the `onError` callback (if wired) so
+     * a dev sees it whichever channel they watch. Never throws.
+     */
+    private warnPlacement;
     /**
      * (Re)arm the render watchdog. Clears any prior timer and, unless disabled
      * (`renderTimeoutMs <= 0`), starts a fresh one. If it fires before a mockup
@@ -2819,4 +2880,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, 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 };
+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, type RenderProductCombination, type RenderProductOptions, 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, assertVariantSelected, 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-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';
+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-DTRStLRH.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-DTRStLRH.js';
 
 interface CatalogProduct$2 {
     id: string;
@@ -2584,8 +2584,7 @@ declare function fetchRealtimeGrant(grantUrl: string, shop: string, fetchImpl?:
  *   product: { productId: 'BEEB77', mockupIds: ['front'] },
  * });
  * session.onMockups((results) => { img.src = results[0].imageUrl; });
- * await session.connect();
- * session.renderState('Front', serializeStateForServer(canvasState));
+ * await session.renderState('Front', serializeStateForServer(canvasState));
  *
  * For the low-level escape hatch, use {@link RealtimeMockupService} directly.
  */
@@ -2604,6 +2603,29 @@ interface RenderState {
     elements?: Array<Record<string, unknown>>;
     [key: string]: unknown;
 }
+/**
+ * A single variant combination from the catalog product's `options.combinations`.
+ * Each combination pins one value per variant-affecting attribute plus the
+ * `variantId` (gvid) that selection resolves to. Pass `options` on
+ * {@link RenderProduct} so the session can FAIL FAST when a required `variantId`
+ * is missing instead of silently hanging until the watchdog.
+ */
+interface RenderProductCombination {
+    /** The variant (gvid) this combination resolves to. */
+    variantId?: string;
+    /** Attribute selections (e.g. `{ Frame: 'Walnut', Size: '5x7' }`). */
+    [attribute: string]: string | number | undefined;
+}
+/**
+ * The catalog product's `options` block (structurally typed). Only
+ * `combinations` is consumed by the session — to detect whether the product has
+ * a real variant axis (multiple distinct `variantId`s) so a missing/invalid
+ * {@link RenderProduct.variantId} can be rejected up front.
+ */
+interface RenderProductOptions {
+    combinations?: RenderProductCombination[];
+    [key: string]: unknown;
+}
 /** Product the session renders against (Snowcone catalog ids). */
 interface RenderProduct {
     productId: string;
@@ -2618,13 +2640,44 @@ interface RenderProduct {
      * 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.
+     *
+     * If you also pass {@link RenderProduct.options}, the session validates this
+     * up front: a product whose `options.combinations` exposes more than one
+     * variant REQUIRES a `variantId` (and it must be one of the combinations'),
+     * else the session throws immediately rather than hanging until the watchdog.
      */
     variantId?: string;
+    /**
+     * The catalog product's `options` block (its `options.combinations[].variantId`
+     * are the valid variant ids). Optional, but passing it lets the session detect
+     * a missing/invalid required `variantId` and FAIL FAST — turning the classic
+     * 30s silent hang into an immediate, actionable error. You can pass the whole
+     * catalog product's `options` object verbatim.
+     */
+    options?: RenderProductOptions;
+    /**
+     * The product's valid placement labels (the catalog product's
+     * `placements[].label`, e.g. `['Front']`). Optional, but passing it lets the
+     * session WARN LOUDLY when a `renderState(placement, ...)` call uses a name
+     * that isn't a real placement — turning the classic silent blank-mockup
+     * (server waits on `incomplete_canvas_placements`) into an actionable
+     * dev-time message. You can pass the catalog product's
+     * `placements.map(p => p.label)` verbatim.
+     */
+    placements?: string[];
     /** Render width in px (default 1000). */
     width?: number;
     /** Per-placement settings (tiling, scale mode). */
     placementSettings?: Record<string, PlacementSettings>;
 }
+/**
+ * Throws immediately if the product has a variant axis (its
+ * `options.combinations` expose 2+ distinct `variantId`s) but no valid
+ * `variantId` was supplied. This is the fail-fast guard for the otherwise-silent
+ * 30s render hang on color/variant products. Products with no `options` (or a
+ * single variant) are left untouched — they render fine with no `variantId`.
+ */
+declare function assertVariantSelected(product: RenderProduct): void;
 interface RenderSessionOptions {
     /** Publishable shop id (= shop.id, like Stripe pk_). */
     shop: string;
@@ -2712,6 +2765,14 @@ declare class RenderSession {
     getMockups(): MockupResult[];
     /** Close the WebSocket and stop auto-renew. */
     close(): void;
+    /**
+     * Emit loud, non-fatal warnings for the two ways a placement name silently
+     * produces a blank mockup: (1) the name isn't one of the product's known
+     * `placements` labels, and (2) no artboard in `state` is named after it. Each
+     * warning goes to BOTH `console.warn` and the `onError` callback (if wired) so
+     * a dev sees it whichever channel they watch. Never throws.
+     */
+    private warnPlacement;
     /**
      * (Re)arm the render watchdog. Clears any prior timer and, unless disabled
      * (`renderTimeoutMs <= 0`), starts a fresh one. If it fires before a mockup
@@ -2819,4 +2880,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, 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 };
+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, type RenderProductCombination, type RenderProductOptions, 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, assertVariantSelected, 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-D5ZRGKA5.js";
+} from "./chunk-IMJKV4YO.js";
 
 // src/validation.ts
 import { z } from "zod";
@@ -1642,14 +1642,12 @@ function buildMockupUrl2(options, cfg) {
   );
 }
 function resolveMockupBaseUrl() {
-  const env = typeof process !== "undefined" ? process.env : void 0;
   const winConfig = typeof window !== "undefined" && window.snowcone || {};
-  return winConfig.mockupUrl || env?.SNOWCONE_IMAGE_URL || env?.NEXT_PUBLIC_MERCH_MOCKUP_URL || "https://cdn.snowcone.app";
+  return winConfig.mockupUrl || typeof process !== "undefined" && process.env?.SNOWCONE_IMAGE_URL || typeof process !== "undefined" && process.env?.NEXT_PUBLIC_MERCH_MOCKUP_URL || "https://cdn.snowcone.app";
 }
 function resolveShop() {
-  const env = typeof process !== "undefined" ? process.env : void 0;
   const winConfig = typeof window !== "undefined" && window.snowcone || {};
-  return winConfig.shop || env?.SNOWCONE_SHOP_ID || env?.NEXT_PUBLIC_SNOWCONE_SHOP_ID || "SHOP_NOT_CONFIGURED";
+  return winConfig.shop || typeof process !== "undefined" && process.env?.SNOWCONE_SHOP_ID || typeof process !== "undefined" && process.env?.NEXT_PUBLIC_SNOWCONE_SHOP_ID || "SHOP_NOT_CONFIGURED";
 }
 function mockupUrl(options) {
   const mockupBaseUrl = resolveMockupBaseUrl();
@@ -4690,6 +4688,44 @@ async function fetchRealtimeGrant(grantUrl, shop, fetchImpl) {
 }
 
 // src/realtime/session.ts
+function variantIdsOf(product) {
+  const combos = product.options?.combinations;
+  if (!combos?.length) return [];
+  const ids = /* @__PURE__ */ new Set();
+  for (const c of combos) {
+    if (typeof c.variantId === "string" && c.variantId !== "") ids.add(c.variantId);
+  }
+  return [...ids];
+}
+function assertVariantSelected(product) {
+  const variantIds = variantIdsOf(product);
+  if (variantIds.length < 2) return;
+  const fix = `pass product.variantId from options.combinations[].variantId (valid ids: ${variantIds.join(", ")})`;
+  if (!product.variantId) {
+    throw new Error(
+      `RenderSession: product ${product.productId} requires a variantId \u2014 ${fix}`
+    );
+  }
+  if (!variantIds.includes(product.variantId)) {
+    throw new Error(
+      `RenderSession: product ${product.productId} has an invalid variantId "${product.variantId}" \u2014 ${fix}`
+    );
+  }
+}
+function warnUnknownPlacement(product, placement) {
+  const placements = product.placements;
+  if (!placements?.length) return null;
+  if (placements.includes(placement)) return null;
+  return `RenderSession: placement "${placement}" doesn't match product ${product.productId}'s placements: [${placements.join(", ")}]. Your artboard name + renderState placement arg must equal the catalog placements[].label.`;
+}
+function warnPlacementArtboardMismatch(placement, state) {
+  const artboards = state.artboards;
+  if (!Array.isArray(artboards) || artboards.length === 0) return null;
+  const names = artboards.map((a) => a.name).filter((n) => typeof n === "string");
+  if (names.length === 0) return null;
+  if (names.includes(placement)) return null;
+  return `RenderSession: renderState placement "${placement}" has no matching artboard in the state (artboards: [${names.join(", ")}]). The artboard name must equal the placement arg.`;
+}
 var DEFAULT_RENDER_TIMEOUT_MS = 3e4;
 var RenderSession = class {
   svc;
@@ -4705,6 +4741,7 @@ var RenderSession = class {
     if (!opts.getToken && !opts.grantUrl) {
       throw new Error("RenderSession: provide `grantUrl` or `getToken` to authorize the session");
     }
+    if (opts.product) assertVariantSelected(opts.product);
     this.opts = opts;
     this.product = opts.product ?? null;
     this.renderTimeoutMs = opts.renderTimeoutMs ?? DEFAULT_RENDER_TIMEOUT_MS;
@@ -4724,6 +4761,7 @@ var RenderSession = class {
   }
   /** Set or update the product. Sends config immediately if already connected. */
   setProduct(product) {
+    assertVariantSelected(product);
     this.product = product;
     this.svc.sendConfig(this.toConfig(product));
   }
@@ -4739,6 +4777,13 @@ var RenderSession = class {
       );
     }
     const product = this.product;
+    try {
+      assertVariantSelected(product);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.errorCb?.(message);
+      return Promise.reject(err instanceof Error ? err : new Error(message));
+    }
     this.ready = new Promise((resolve, reject) => {
       let settled = false;
       this.svc.setCallbacks({
@@ -4790,6 +4835,7 @@ var RenderSession = class {
    */
   async renderState(placement, state, throttleMs = 0) {
     await this.connect();
+    this.warnPlacement(placement, state);
     this.svc.sendCanvasState(placement, state, this.product?.mockupIds.length ?? 1, throttleMs);
     this.armWatchdog();
   }
@@ -4802,6 +4848,7 @@ var RenderSession = class {
    */
   async renderSavedState(placement, stateId) {
     await this.connect();
+    this.warnPlacement(placement);
     this.svc.sendCanvasStateRef(placement, stateId);
     this.armWatchdog();
   }
@@ -4820,6 +4867,28 @@ var RenderSession = class {
     this.svc.disconnect();
     this.ready = null;
   }
+  /**
+   * Emit loud, non-fatal warnings for the two ways a placement name silently
+   * produces a blank mockup: (1) the name isn't one of the product's known
+   * `placements` labels, and (2) no artboard in `state` is named after it. Each
+   * warning goes to BOTH `console.warn` and the `onError` callback (if wired) so
+   * a dev sees it whichever channel they watch. Never throws.
+   */
+  warnPlacement(placement, state) {
+    const warnings = [];
+    if (this.product) {
+      const w = warnUnknownPlacement(this.product, placement);
+      if (w) warnings.push(w);
+    }
+    if (state) {
+      const w = warnPlacementArtboardMismatch(placement, state);
+      if (w) warnings.push(w);
+    }
+    for (const w of warnings) {
+      console.warn(w);
+      this.errorCb?.(w);
+    }
+  }
   /**
    * (Re)arm the render watchdog. Clears any prior timer and, unless disabled
    * (`renderTimeoutMs <= 0`), starts a fresh one. If it fires before a mockup
@@ -4935,7 +5004,12 @@ async function getProduct(idOrSlug, config) {
   const url = `${meilisearchHost}/indexes/${meilisearchIndex}/documents/${idOrSlug}`;
   const res = await f(url, { method: "GET", headers });
   if (res.status === 404)
-    throw Object.assign(new Error("Not found"), { code: "NOT_FOUND" });
+    throw Object.assign(
+      new Error(
+        `getProduct: no catalog product "${idOrSlug}" in index "${meilisearchIndex}". Pass a valid product id/slug (browse with listProducts()).`
+      ),
+      { code: "NOT_FOUND", productId: idOrSlug }
+    );
   if (!res.ok) throw new Error(`getProduct failed: ${res.status}`);
   const raw = await res.json();
   return validateProductLoose(raw);
@@ -4997,6 +5071,7 @@ export {
   UniversalContextProvider,
   VueAdapter,
   adapterRegistry,
+  assertVariantSelected,
   autoRegister,
   buildMockupUrl2 as buildMockupUrl,
   componentRegistry,

package/dist/react.cjs

@@ -51,6 +51,10 @@ var RealtimeMockupService = class {
   lastBlobSentAt = 0;
   canvasBlobs = /* @__PURE__ */ new Map();
   canvasStates = /* @__PURE__ */ new Map();
+  // Serialized JSON of the last canvas state ACTUALLY SENT per placement. Used to
+  // drop duplicate consecutive states so an idle canvas (whose onChange keeps
+  // firing identical states) doesn't stream renders and burn the realtime budget.
+  lastSentStateJson = {};
   colors = /* @__PURE__ */ new Map();
   lastSendTime = {};
   throttleTimeouts = {};
@@ -71,6 +75,8 @@ var RealtimeMockupService = class {
   // the WS with `?token=`, and renews ~15s before expiry via a `renew` message.
   tokenProvider;
   renewTimer = null;
+  isConnecting = false;
+  connectAttempt = 0;
   setCallbacks(callbacks) {
     this.callbacks = callbacks;
   }
@@ -97,16 +103,21 @@ var RealtimeMockupService = class {
     this.callbacks.onLog?.(message, type);
   }
   connect() {
-    if (this.ws?.readyState === WebSocket.OPEN) {
+    if (this.ws?.readyState === WebSocket.OPEN || this.ws?.readyState === WebSocket.CONNECTING || this.isConnecting) {
       return;
     }
+    const attempt = ++this.connectAttempt;
+    this.isConnecting = true;
     if (this.tokenProvider) {
       this.tokenProvider().then((grant) => {
+        if (attempt !== this.connectAttempt || !this.isConnecting) return;
         this.openSocket(grant.token);
         this.scheduleRenew(grant.expiresAt);
       }).catch((err) => {
+        if (attempt !== this.connectAttempt) return;
         this.addLog(`Failed to obtain realtime grant: ${err}`);
         this.status = "Disconnected";
+        this.isConnecting = false;
       });
       return;
     }
@@ -120,6 +131,7 @@ var RealtimeMockupService = class {
       console.log(`[WS] connection OPENED to ${this.wsUrl}`);
       this.addLog("WebSocket connection opened");
       this.status = "Connected";
+      this.isConnecting = false;
     };
     this.ws.onmessage = (event) => {
       try {
@@ -138,11 +150,13 @@ var RealtimeMockupService = class {
       this.isConfigured = false;
       this.configSent = false;
       this.clearRenew();
+      this.isConnecting = false;
       this.callbacks.onDisconnected?.();
     };
     this.ws.onerror = (error) => {
       this.addLog(`WebSocket error: ${error}`);
       this.status = "Disconnected";
+      this.isConnecting = false;
     };
   }
   scheduleRenew(expiresAt) {
@@ -292,6 +306,8 @@ var RealtimeMockupService = class {
     }
   }
   disconnect() {
+    this.connectAttempt++;
+    this.isConnecting = false;
     this.clearRenew();
     if (this.ws) {
       this.ws.close();
@@ -330,6 +346,7 @@ var RealtimeMockupService = class {
         this.canvasStates.clear();
         this.colors.clear();
         this.lastSendTime = {};
+        this.lastSentStateJson = {};
         Object.values(this.throttleTimeouts).forEach((timeout) => clearTimeout(timeout));
         this.throttleTimeouts = {};
         this.requestVersion = 0;
@@ -535,6 +552,11 @@ var RealtimeMockupService = class {
       console.log(`[WS] sendCanvasStateImmediately ABORTED: ws not open`);
       return;
     }
+    const stateJson = JSON.stringify(state);
+    if (this.lastSentStateJson[placement] === stateJson) {
+      this.addLog(`Skipped duplicate canvas state for "${placement}" (unchanged)`, "sent");
+      return;
+    }
     this.lastSentVersion = ++this.requestVersion;
     this.latestSentVersionByPlacement[placement] = this.lastSentVersion;
     const message = JSON.stringify({
@@ -544,6 +566,7 @@ var RealtimeMockupService = class {
       state
     });
     this.ws.send(message);
+    this.lastSentStateJson[placement] = stateJson;
     this.lastBlobSentAt = Date.now();
     this.addLog(`Sent canvas state for "${placement}" (${(message.length / 1024).toFixed(1)}KB, v${this.lastSentVersion})`, "sent");
     this.callbacks.onBlobSent?.(placement);

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-Poy8LZNA.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-DTRStLRH.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-Poy8LZNA.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-DTRStLRH.js';
 
 interface UseRealtimeMockupOptions {
     wsUrl?: string;

package/dist/react.js

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

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

@@ -17,9 +17,10 @@ declare function resolveBestCombination(selection: OptionSelection, attributes:
  */
 declare function computeDisabledChoices(selection: OptionSelection, attributes: Record<string, OptionAttribute>, combinations: Combination[]): Record<string, string[]>;
 /**
- * Derives a reasonable default selection based on the best combination.
+ * Derives a complete default selection based on the best combination.
  * - For attributes that affect combinations, choose the value from the best combo.
- * - For non-affecting attributes, leave unset (caller may choose first choice if desired).
+ * - For every remaining attribute, fall back to a default (color pickers get
+ *   black; otherwise the first choice) so the returned selection is complete.
  */
 declare function deriveDefaultSelection(attributes: Record<string, OptionAttribute>, combinations: Combination[]): OptionSelection;
 /**
@@ -306,6 +307,7 @@ declare class RealtimeMockupService {
     private lastBlobSentAt;
     private canvasBlobs;
     private canvasStates;
+    private lastSentStateJson;
     private colors;
     private lastSendTime;
     private throttleTimeouts;
@@ -316,6 +318,8 @@ declare class RealtimeMockupService {
     private sendVersionInBlob;
     private tokenProvider?;
     private renewTimer;
+    private isConnecting;
+    private connectAttempt;
     constructor(wsUrl?: string);
     setCallbacks(callbacks: RealtimeMockupCallbacks): void;
     /** Provide a grant fetcher to authorize the session (per-shop, renewable). */

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

@@ -17,9 +17,10 @@ declare function resolveBestCombination(selection: OptionSelection, attributes:
  */
 declare function computeDisabledChoices(selection: OptionSelection, attributes: Record<string, OptionAttribute>, combinations: Combination[]): Record<string, string[]>;
 /**
- * Derives a reasonable default selection based on the best combination.
+ * Derives a complete default selection based on the best combination.
  * - For attributes that affect combinations, choose the value from the best combo.
- * - For non-affecting attributes, leave unset (caller may choose first choice if desired).
+ * - For every remaining attribute, fall back to a default (color pickers get
+ *   black; otherwise the first choice) so the returned selection is complete.
  */
 declare function deriveDefaultSelection(attributes: Record<string, OptionAttribute>, combinations: Combination[]): OptionSelection;
 /**
@@ -306,6 +307,7 @@ declare class RealtimeMockupService {
     private lastBlobSentAt;
     private canvasBlobs;
     private canvasStates;
+    private lastSentStateJson;
     private colors;
     private lastSendTime;
     private throttleTimeouts;
@@ -316,6 +318,8 @@ declare class RealtimeMockupService {
     private sendVersionInBlob;
     private tokenProvider?;
     private renewTimer;
+    private isConnecting;
+    private connectAttempt;
     constructor(wsUrl?: string);
     setCallbacks(callbacks: RealtimeMockupCallbacks): void;
     /** Provide a grant fetcher to authorize the session (per-shop, renewable). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/sdk",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Snowcone SDK for product mockups and print-on-demand",
   "keywords": [
     "merch",
@@ -81,6 +81,7 @@
   "scripts": {
     "build": "tsup src/index.ts src/react.ts src/dev-fetcher.ts --format esm,cjs --dts --external zod --external react",
     "clean": "rm -rf dist",
-    "typecheck": "tsc --project ./tsconfig.json --noEmit"
+    "typecheck": "tsc --project ./tsconfig.json --noEmit",
+    "test": "vitest run"
   }
 }