@snowcone-app/sdk 0.3.3 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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

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

@@ -1797,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();
@@ -4837,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 = {};
@@ -4857,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;
   }
@@ -4883,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;
     }
@@ -4906,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 {
@@ -4924,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) {
@@ -5078,6 +5090,8 @@ var RealtimeMockupService = class {
     }
   }
   disconnect() {
+    this.connectAttempt++;
+    this.isConnecting = false;
     this.clearRenew();
     if (this.ws) {
       this.ws.close();
@@ -5116,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;
@@ -5321,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({
@@ -5330,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);
@@ -5548,6 +5569,20 @@ function assertVariantSelected(product) {
     );
   }
 }
+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;
@@ -5657,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();
   }
@@ -5669,6 +5705,7 @@ var RenderSession = class {
    */
   async renderSavedState(placement, stateId) {
     await this.connect();
+    this.warnPlacement(placement);
     this.svc.sendCanvasStateRef(placement, stateId);
     this.armWatchdog();
   }
@@ -5687,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
@@ -5802,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);

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.
  */
@@ -2656,6 +2655,16 @@ interface RenderProduct {
      * 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). */
@@ -2756,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

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.
  */
@@ -2656,6 +2655,16 @@ interface RenderProduct {
      * 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). */
@@ -2756,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

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();
@@ -4714,6 +4712,20 @@ function assertVariantSelected(product) {
     );
   }
 }
+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;
@@ -4823,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();
   }
@@ -4835,6 +4848,7 @@ var RenderSession = class {
    */
   async renderSavedState(placement, stateId) {
     await this.connect();
+    this.warnPlacement(placement);
     this.svc.sendCanvasStateRef(placement, stateId);
     this.armWatchdog();
   }
@@ -4853,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
@@ -4968,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);

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.3",
+  "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"
   }
 }