@snowcone-app/sdk 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.3.5
+
+### Patch Changes
+
+- [#304](https://github.com/snowcone-app/snowcone-monorepo/pull/304) [`2700cd9`](https://github.com/snowcone-app/snowcone-monorepo/commit/2700cd93831c50a1a5d496b04d40fd0c1a89b641) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Realtime: the first render no longer races the WebSocket handshake. `sendCanvasState` (and therefore both `RenderSession.renderState` and the `useRealtimeMockup` hook) now **buffers** a canvas state sent before the session is connected+configured and flushes it automatically on `configured` — exactly as canvas blobs already did. Previously the state was silently dropped (`ws.readyState=0 BLOCKED`) and dead-ended in the 30s render watchdog with no mockup. This was the most-reported clean-room DX failure; it is now impossible on every code path through `RealtimeMockupService`.
+
+  The render-timeout message is also now **cause-aware**: instead of always blaming a missing `variantId`, it reports what was actually observed — socket not open, config never acknowledged, a genuine missing variant selection, or "the server accepted config but rendered nothing" (naming the product/mockupIds to check). The old message sent dogfooders chasing the wrong cause.
+
+  Pinned by regression tests: pre-connect buffering + flush at the service level, and a React **StrictMode** mount of `useRealtimeMockup` proving the first render survives the mount→cleanup→mount double-invoke that App-Router projects trigger.
+
+- [#309](https://github.com/snowcone-app/snowcone-monorepo/pull/309) [`df2793c`](https://github.com/snowcone-app/snowcone-monorepo/commit/df2793c915bc8dc43eb0948a5f74912b333a43d2) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Realtime: every `canvas_state` render now carries a per-request **`requestId`** (a 32-hex W3C trace-id) and a **`traceparent`** header so a single edit can be followed end-to-end. The client logs `req=<id>` on send and on `mockup_rendered` (alongside `renderMs`, `blobToRenderMs`, and a client-observed `clientRoundTripMs`), the server tags the queue → dequeue → composite-fetch start/end log lines with the same `req=<id>`, and the server forwards the `traceparent` onto the internal `/mockups` composite render so it becomes a child span in OTel. Grep one id across client + server logs, or paste it as a trace-id in the tracing backend, to localize where realtime render latency is spent. `requestId` is now also surfaced on `MockupResult`.
+
+## 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-YTOTCNEW.js}

@@ -2,6 +2,16 @@
 var REALTIME_WS_URL = "wss://cdn.snowcone.app/realtime";
 
 // src/realtime/websocket.ts
+function randHex(len) {
+  const arr = new Uint8Array(len);
+  globalThis.crypto.getRandomValues(arr);
+  return Array.from(arr, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function newRenderCorrelation() {
+  const traceId = randHex(16);
+  const spanId = randHex(8);
+  return { requestId: traceId, traceparent: `00-${traceId}-${spanId}-01` };
+}
 var RealtimeMockupService = class {
   constructor(wsUrl = REALTIME_WS_URL) {
     this.wsUrl = wsUrl;
@@ -17,8 +27,25 @@ var RealtimeMockupService = class {
   lastError = null;
   callbacks = {};
   lastBlobSentAt = 0;
+  // Per-request send timestamps keyed by requestId, for client-observed
+  // round-trip timing in the mockup_rendered log. Pruned to a small cap so an
+  // in-flight burst can't grow it unbounded.
+  requestSendTimes = /* @__PURE__ */ new Map();
   canvasBlobs = /* @__PURE__ */ new Map();
   canvasStates = /* @__PURE__ */ new Map();
+  // States sent BEFORE the session is connected+configured. The #1 recurring DX
+  // failure ("connect race"): a caller fires renderState/sendCanvasState during
+  // the WS handshake, the state was silently dropped, and the 30s watchdog fired
+  // with no mockup pointing at the wrong cause. Blobs were already buffered and
+  // auto-flushed on `configured`; states were not. We now buffer the latest
+  // state per placement and flush it on `configured`, so the first render
+  // survives the race on EVERY path through this service — the `RenderSession`
+  // facade and the `useRealtimeMockup` hook alike.
+  pendingStates = /* @__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 +66,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 +94,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 +122,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 +141,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) {
@@ -173,6 +210,16 @@ var RealtimeMockupService = class {
             });
           }, 100);
         }
+        if (this.pendingStates.size > 0) {
+          const pending = Array.from(this.pendingStates.entries());
+          this.pendingStates.clear();
+          this.addLog(`\u{1F4E6} Flushing ${pending.length} buffered canvas state(s)`);
+          setTimeout(() => {
+            for (const [placement, { state, mockupCount }] of pending) {
+              this.sendCanvasState(placement, state, mockupCount, 0);
+            }
+          }, 100);
+        }
         break;
       case "blob_received":
         const placementName = data.placement || "unknown";
@@ -186,8 +233,10 @@ var RealtimeMockupService = class {
       case "rendering_started":
         this.addLog("\u{1F3A8} Mockup rendering has started...");
         break;
-      case "mockup_rendered":
-        console.log(`[WS] mockup_rendered received: mockupId=${data.mockupId} hasImageUrl=${!!data.imageUrl} v=${data.requestVersion} placement="${data.placement}" renderMs=${data.renderMs}`);
+      case "mockup_rendered": {
+        const sentAt = data.requestId ? this.requestSendTimes.get(data.requestId) : void 0;
+        const clientRoundTripMs = sentAt !== void 0 ? Date.now() - sentAt : void 0;
+        console.log(`[WS] mockup_rendered received: mockupId=${data.mockupId} hasImageUrl=${!!data.imageUrl} v=${data.requestVersion} req=${data.requestId ?? "?"} placement="${data.placement}" renderMs=${data.renderMs} blobToRenderMs=${data.blobToRenderMs} clientRoundTripMs=${clientRoundTripMs ?? "?"} at ${Date.now()}`);
         if (data.imageUrl && data.mockupId) {
           const responseVersion = data.requestVersion;
           const responsePlacement = data.placement;
@@ -205,6 +254,7 @@ var RealtimeMockupService = class {
             imageUrl: data.imageUrl,
             renderUrl: data.renderUrl || data.imageUrl,
             imageSize: data.imageSize || 0,
+            requestId: data.requestId,
             requestVersion: responseVersion,
             placement: responsePlacement,
             renderMs: data.renderMs,
@@ -227,6 +277,7 @@ var RealtimeMockupService = class {
           this.addLog(`\u26A0\uFE0F mockup_rendered message dropped: missing required fields [${missing.join(", ")}]. Full data keys: [${Object.keys(data).join(", ")}]`);
         }
         break;
+      }
       case "all_mockups_rendered":
         console.log(`[WS] all_mockups_rendered received: ${data.mockups?.length ?? 0} mockups`);
         if (data.mockups) {
@@ -260,7 +311,10 @@ var RealtimeMockupService = class {
     }
   }
   disconnect() {
+    this.connectAttempt++;
+    this.isConnecting = false;
     this.clearRenew();
+    this.pendingStates.clear();
     if (this.ws) {
       this.ws.close();
       this.ws = null;
@@ -298,6 +352,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;
@@ -431,9 +486,11 @@ var RealtimeMockupService = class {
   sendCanvasState(placement, state, mockupCount = 1, baseThrottleMs = 1e3) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.isConfigured) {
       const reason = !this.ws ? "no WebSocket" : this.ws.readyState !== WebSocket.OPEN ? `ws.readyState=${this.ws.readyState}` : "not configured";
-      console.log(`[WS] sendCanvasState BLOCKED for "${placement}": ${reason}`);
-      return false;
+      this.pendingStates.set(placement, { state, mockupCount, baseThrottleMs });
+      console.log(`[WS] sendCanvasState buffered for "${placement}" until configured: ${reason}`);
+      return true;
     }
+    this.pendingStates.delete(placement);
     this.canvasStates.set(placement, state);
     if (baseThrottleMs <= 0) {
       this.sendCanvasStateImmediately(placement, state);
@@ -486,34 +543,58 @@ var RealtimeMockupService = class {
     }
     this.lastSentVersion = ++this.requestVersion;
     this.latestSentVersionByPlacement[placement] = this.lastSentVersion;
+    const { requestId, traceparent } = newRenderCorrelation();
     const message = JSON.stringify({
       type: "canvas_state",
       placement,
       version: this.lastSentVersion,
+      requestId,
+      traceparent,
       stateId
     });
     this.ws.send(message);
+    this.recordRequestSent(requestId);
     this.lastBlobSentAt = Date.now();
-    this.addLog(`Sent canvas stateId "${stateId}" for "${placement}" (v${this.lastSentVersion})`, "sent");
+    console.log(`[WS] canvas_state(ref) SENT: placement="${placement}" v${this.lastSentVersion} req=${requestId} stateId=${stateId} at ${Date.now()}`);
+    this.addLog(`Sent canvas stateId "${stateId}" for "${placement}" (v${this.lastSentVersion}, req ${requestId})`, "sent");
     this.callbacks.onBlobSent?.(placement);
     return true;
   }
+  /** Stamp a request's send time for client round-trip measurement (capped). */
+  recordRequestSent(requestId) {
+    this.requestSendTimes.set(requestId, Date.now());
+    if (this.requestSendTimes.size > 50) {
+      const oldest = this.requestSendTimes.keys().next().value;
+      if (oldest !== void 0) this.requestSendTimes.delete(oldest);
+    }
+  }
   sendCanvasStateImmediately(placement, state) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
       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 { requestId, traceparent } = newRenderCorrelation();
     const message = JSON.stringify({
       type: "canvas_state",
       placement,
       version: this.lastSentVersion,
+      requestId,
+      traceparent,
       state
     });
     this.ws.send(message);
+    this.recordRequestSent(requestId);
+    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");
+    console.log(`[WS] canvas_state SENT: placement="${placement}" v${this.lastSentVersion} req=${requestId} (${(message.length / 1024).toFixed(1)}KB) at ${Date.now()}`);
+    this.addLog(`Sent canvas state for "${placement}" (${(message.length / 1024).toFixed(1)}KB, v${this.lastSentVersion}, req ${requestId})`, "sent");
     this.callbacks.onBlobSent?.(placement);
   }
   sendBlobImmediately(placement, blob, notifyCallback = true) {

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();
@@ -4820,6 +4818,16 @@ function createSvelteComponent(descriptor, svelte) {
 var REALTIME_WS_URL = "wss://cdn.snowcone.app/realtime";
 
 // src/realtime/websocket.ts
+function randHex(len) {
+  const arr = new Uint8Array(len);
+  globalThis.crypto.getRandomValues(arr);
+  return Array.from(arr, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function newRenderCorrelation() {
+  const traceId = randHex(16);
+  const spanId = randHex(8);
+  return { requestId: traceId, traceparent: `00-${traceId}-${spanId}-01` };
+}
 var RealtimeMockupService = class {
   constructor(wsUrl = REALTIME_WS_URL) {
     this.wsUrl = wsUrl;
@@ -4835,8 +4843,25 @@ var RealtimeMockupService = class {
   lastError = null;
   callbacks = {};
   lastBlobSentAt = 0;
+  // Per-request send timestamps keyed by requestId, for client-observed
+  // round-trip timing in the mockup_rendered log. Pruned to a small cap so an
+  // in-flight burst can't grow it unbounded.
+  requestSendTimes = /* @__PURE__ */ new Map();
   canvasBlobs = /* @__PURE__ */ new Map();
   canvasStates = /* @__PURE__ */ new Map();
+  // States sent BEFORE the session is connected+configured. The #1 recurring DX
+  // failure ("connect race"): a caller fires renderState/sendCanvasState during
+  // the WS handshake, the state was silently dropped, and the 30s watchdog fired
+  // with no mockup pointing at the wrong cause. Blobs were already buffered and
+  // auto-flushed on `configured`; states were not. We now buffer the latest
+  // state per placement and flush it on `configured`, so the first render
+  // survives the race on EVERY path through this service — the `RenderSession`
+  // facade and the `useRealtimeMockup` hook alike.
+  pendingStates = /* @__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 +4882,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 +4910,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 +4938,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 +4957,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) {
@@ -4991,6 +5026,16 @@ var RealtimeMockupService = class {
             });
           }, 100);
         }
+        if (this.pendingStates.size > 0) {
+          const pending = Array.from(this.pendingStates.entries());
+          this.pendingStates.clear();
+          this.addLog(`\u{1F4E6} Flushing ${pending.length} buffered canvas state(s)`);
+          setTimeout(() => {
+            for (const [placement, { state, mockupCount }] of pending) {
+              this.sendCanvasState(placement, state, mockupCount, 0);
+            }
+          }, 100);
+        }
         break;
       case "blob_received":
         const placementName = data.placement || "unknown";
@@ -5004,8 +5049,10 @@ var RealtimeMockupService = class {
       case "rendering_started":
         this.addLog("\u{1F3A8} Mockup rendering has started...");
         break;
-      case "mockup_rendered":
-        console.log(`[WS] mockup_rendered received: mockupId=${data.mockupId} hasImageUrl=${!!data.imageUrl} v=${data.requestVersion} placement="${data.placement}" renderMs=${data.renderMs}`);
+      case "mockup_rendered": {
+        const sentAt = data.requestId ? this.requestSendTimes.get(data.requestId) : void 0;
+        const clientRoundTripMs = sentAt !== void 0 ? Date.now() - sentAt : void 0;
+        console.log(`[WS] mockup_rendered received: mockupId=${data.mockupId} hasImageUrl=${!!data.imageUrl} v=${data.requestVersion} req=${data.requestId ?? "?"} placement="${data.placement}" renderMs=${data.renderMs} blobToRenderMs=${data.blobToRenderMs} clientRoundTripMs=${clientRoundTripMs ?? "?"} at ${Date.now()}`);
         if (data.imageUrl && data.mockupId) {
           const responseVersion = data.requestVersion;
           const responsePlacement = data.placement;
@@ -5023,6 +5070,7 @@ var RealtimeMockupService = class {
             imageUrl: data.imageUrl,
             renderUrl: data.renderUrl || data.imageUrl,
             imageSize: data.imageSize || 0,
+            requestId: data.requestId,
             requestVersion: responseVersion,
             placement: responsePlacement,
             renderMs: data.renderMs,
@@ -5045,6 +5093,7 @@ var RealtimeMockupService = class {
           this.addLog(`\u26A0\uFE0F mockup_rendered message dropped: missing required fields [${missing.join(", ")}]. Full data keys: [${Object.keys(data).join(", ")}]`);
         }
         break;
+      }
       case "all_mockups_rendered":
         console.log(`[WS] all_mockups_rendered received: ${data.mockups?.length ?? 0} mockups`);
         if (data.mockups) {
@@ -5078,7 +5127,10 @@ var RealtimeMockupService = class {
     }
   }
   disconnect() {
+    this.connectAttempt++;
+    this.isConnecting = false;
     this.clearRenew();
+    this.pendingStates.clear();
     if (this.ws) {
       this.ws.close();
       this.ws = null;
@@ -5116,6 +5168,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;
@@ -5249,9 +5302,11 @@ var RealtimeMockupService = class {
   sendCanvasState(placement, state, mockupCount = 1, baseThrottleMs = 1e3) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.isConfigured) {
       const reason = !this.ws ? "no WebSocket" : this.ws.readyState !== WebSocket.OPEN ? `ws.readyState=${this.ws.readyState}` : "not configured";
-      console.log(`[WS] sendCanvasState BLOCKED for "${placement}": ${reason}`);
-      return false;
+      this.pendingStates.set(placement, { state, mockupCount, baseThrottleMs });
+      console.log(`[WS] sendCanvasState buffered for "${placement}" until configured: ${reason}`);
+      return true;
     }
+    this.pendingStates.delete(placement);
     this.canvasStates.set(placement, state);
     if (baseThrottleMs <= 0) {
       this.sendCanvasStateImmediately(placement, state);
@@ -5304,34 +5359,58 @@ var RealtimeMockupService = class {
     }
     this.lastSentVersion = ++this.requestVersion;
     this.latestSentVersionByPlacement[placement] = this.lastSentVersion;
+    const { requestId, traceparent } = newRenderCorrelation();
     const message = JSON.stringify({
       type: "canvas_state",
       placement,
       version: this.lastSentVersion,
+      requestId,
+      traceparent,
       stateId
     });
     this.ws.send(message);
+    this.recordRequestSent(requestId);
     this.lastBlobSentAt = Date.now();
-    this.addLog(`Sent canvas stateId "${stateId}" for "${placement}" (v${this.lastSentVersion})`, "sent");
+    console.log(`[WS] canvas_state(ref) SENT: placement="${placement}" v${this.lastSentVersion} req=${requestId} stateId=${stateId} at ${Date.now()}`);
+    this.addLog(`Sent canvas stateId "${stateId}" for "${placement}" (v${this.lastSentVersion}, req ${requestId})`, "sent");
     this.callbacks.onBlobSent?.(placement);
     return true;
   }
+  /** Stamp a request's send time for client round-trip measurement (capped). */
+  recordRequestSent(requestId) {
+    this.requestSendTimes.set(requestId, Date.now());
+    if (this.requestSendTimes.size > 50) {
+      const oldest = this.requestSendTimes.keys().next().value;
+      if (oldest !== void 0) this.requestSendTimes.delete(oldest);
+    }
+  }
   sendCanvasStateImmediately(placement, state) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
       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 { requestId, traceparent } = newRenderCorrelation();
     const message = JSON.stringify({
       type: "canvas_state",
       placement,
       version: this.lastSentVersion,
+      requestId,
+      traceparent,
       state
     });
     this.ws.send(message);
+    this.recordRequestSent(requestId);
+    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");
+    console.log(`[WS] canvas_state SENT: placement="${placement}" v${this.lastSentVersion} req=${requestId} (${(message.length / 1024).toFixed(1)}KB) at ${Date.now()}`);
+    this.addLog(`Sent canvas state for "${placement}" (${(message.length / 1024).toFixed(1)}KB, v${this.lastSentVersion}, req ${requestId})`, "sent");
     this.callbacks.onBlobSent?.(placement);
   }
   sendBlobImmediately(placement, blob, notifyCallback = true) {
@@ -5548,6 +5627,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 +5750,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 +5763,7 @@ var RenderSession = class {
    */
   async renderSavedState(placement, stateId) {
     await this.connect();
+    this.warnPlacement(placement);
     this.svc.sendCanvasStateRef(placement, stateId);
     this.armWatchdog();
   }
@@ -5687,6 +5782,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
@@ -5698,11 +5815,32 @@ var RenderSession = class {
     if (this.renderTimeoutMs <= 0) return;
     this.watchdog = setTimeout(() => {
       this.watchdog = null;
-      this.errorCb?.(
-        `realtime render timed out after ${this.renderTimeoutMs}ms with no mockup \u2014 a product with a color/variant axis needs \`variantId\` in the product config (see RenderProduct.variantId)`
-      );
+      this.errorCb?.(this.timeoutMessage());
     }, this.renderTimeoutMs);
   }
+  /**
+   * Build the watchdog timeout message from the *observed* session state rather
+   * than a single hardcoded guess. The old message always blamed a missing
+   * `variantId` — which sent a clean-room dogfood chasing the wrong cause when
+   * the real problem was elsewhere. Report what's actually true: is the socket
+   * open, did config get acknowledged, and only then fall back to the
+   * variant/catalog hypotheses, naming the exact product so it's checkable.
+   */
+  timeoutMessage() {
+    const base = `realtime render timed out after ${this.renderTimeoutMs}ms with no mockup`;
+    const st = this.svc.getState();
+    if (!st.isConnected) {
+      return `${base} \u2014 the WebSocket is not open (it connected, then closed). Check the grant endpoint and network; the session needs a live socket to render.`;
+    }
+    if (!st.isConfigured) {
+      return `${base} \u2014 the server never acknowledged the session config. The socket is open but no \`configured\` message arrived; the render was never accepted.`;
+    }
+    const product = this.product;
+    if (product && variantIdsOf(product).length >= 2 && !product.variantId) {
+      return `${base} \u2014 product ${product.productId} has a color/variant axis but no \`variantId\` was set, so the server is waiting for a variant selection (see RenderProduct.variantId).`;
+    }
+    return `${base} \u2014 the server accepted the config but rendered nothing. Verify the product and mockupIds exist in the catalog (productId="${product?.productId}", mockupIds=[${product?.mockupIds?.join(", ") ?? ""}]) and that the placement name matches an artboard.`;
+  }
   /** Cancel the pending render watchdog, if any. */
   clearWatchdog() {
     if (this.watchdog) {
@@ -5802,7 +5940,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);