@snowcone-app/sdk 0.3.4 → 0.3.5

package/CHANGELOG.md

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

package/dist/{chunk-IMJKV4YO.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,21 @@ 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.
@@ -187,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";
@@ -200,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;
@@ -219,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,
@@ -241,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) {
@@ -277,6 +314,7 @@ var RealtimeMockupService = class {
     this.connectAttempt++;
     this.isConnecting = false;
     this.clearRenew();
+    this.pendingStates.clear();
     if (this.ws) {
       this.ws.close();
       this.ws = null;
@@ -448,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);
@@ -503,18 +543,31 @@ 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`);
@@ -527,16 +580,21 @@ 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,
       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

@@ -4818,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;
@@ -4833,8 +4843,21 @@ 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.
@@ -5003,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";
@@ -5016,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;
@@ -5035,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,
@@ -5057,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) {
@@ -5093,6 +5130,7 @@ var RealtimeMockupService = class {
     this.connectAttempt++;
     this.isConnecting = false;
     this.clearRenew();
+    this.pendingStates.clear();
     if (this.ws) {
       this.ws.close();
       this.ws = null;
@@ -5264,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);
@@ -5319,18 +5359,31 @@ 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`);
@@ -5343,16 +5396,21 @@ 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,
       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) {
@@ -5757,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) {

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-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';
+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-hXpNcyEn.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-hXpNcyEn.cjs';
 
 interface CatalogProduct$2 {
     id: string;
@@ -2780,6 +2780,15 @@ declare class RenderSession {
      * server/transport errors — with a hint at the most common cause.
      */
     private armWatchdog;
+    /**
+     * 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.
+     */
+    private timeoutMessage;
     /** Cancel the pending render watchdog, if any. */
     private clearWatchdog;
     /** Escape hatch: the underlying low-level service. */

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-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';
+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-hXpNcyEn.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-hXpNcyEn.js';
 
 interface CatalogProduct$2 {
     id: string;
@@ -2780,6 +2780,15 @@ declare class RenderSession {
      * server/transport errors — with a hint at the most common cause.
      */
     private armWatchdog;
+    /**
+     * 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.
+     */
+    private timeoutMessage;
     /** Cancel the pending render watchdog, if any. */
     private clearWatchdog;
     /** Escape hatch: the underlying low-level service. */

package/dist/index.js

@@ -4,7 +4,7 @@ import {
 import {
   REALTIME_WS_URL,
   RealtimeMockupService
-} from "./chunk-IMJKV4YO.js";
+} from "./chunk-YTOTCNEW.js";
 
 // src/validation.ts
 import { z } from "zod";
@@ -4900,11 +4900,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) {

package/dist/react.cjs

@@ -34,6 +34,16 @@ var import_react = require("react");
 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;
@@ -49,8 +59,21 @@ 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.
@@ -219,6 +242,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";
@@ -232,8 +265,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;
@@ -251,6 +286,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,
@@ -273,6 +309,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) {
@@ -309,6 +346,7 @@ var RealtimeMockupService = class {
     this.connectAttempt++;
     this.isConnecting = false;
     this.clearRenew();
+    this.pendingStates.clear();
     if (this.ws) {
       this.ws.close();
       this.ws = null;
@@ -480,9 +518,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);
@@ -535,18 +575,31 @@ 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`);
@@ -559,16 +612,21 @@ 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,
       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/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-DTRStLRH.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-hXpNcyEn.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-DTRStLRH.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-hXpNcyEn.js';
 
 interface UseRealtimeMockupOptions {
     wsUrl?: string;

package/dist/react.js

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

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

@@ -230,6 +230,8 @@ interface MockupResult {
     imageUrl: string;
     renderUrl: string;
     imageSize: number;
+    /** Per-render correlation id (== OTel trace-id) echoed back by the server */
+    requestId?: string;
     /** The request version this mockup corresponds to (for stale detection) */
     requestVersion?: number;
     /** The placement this mockup corresponds to */
@@ -252,6 +254,8 @@ interface WebSocketMessage {
     message?: string;
     placement?: string;
     missingPlacements?: string[];
+    /** Per-render correlation id (== OTel trace-id) echoed back by the server */
+    requestId?: string;
     /** The request version this response corresponds to (for stale detection) */
     requestVersion?: number;
     /** Server-side PIXI render time in ms */
@@ -305,8 +309,10 @@ declare class RealtimeMockupService {
     private lastError;
     private callbacks;
     private lastBlobSentAt;
+    private requestSendTimes;
     private canvasBlobs;
     private canvasStates;
+    private pendingStates;
     private lastSentStateJson;
     private colors;
     private lastSendTime;
@@ -367,6 +373,8 @@ declare class RealtimeMockupService {
      * canvas JSON. One-shot (no throttle). Results arrive like any other render.
      */
     sendCanvasStateRef(placement: string, stateId: string): boolean;
+    /** Stamp a request's send time for client round-trip measurement (capped). */
+    private recordRequestSent;
     private sendCanvasStateImmediately;
     private sendBlobImmediately;
     /**

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

@@ -230,6 +230,8 @@ interface MockupResult {
     imageUrl: string;
     renderUrl: string;
     imageSize: number;
+    /** Per-render correlation id (== OTel trace-id) echoed back by the server */
+    requestId?: string;
     /** The request version this mockup corresponds to (for stale detection) */
     requestVersion?: number;
     /** The placement this mockup corresponds to */
@@ -252,6 +254,8 @@ interface WebSocketMessage {
     message?: string;
     placement?: string;
     missingPlacements?: string[];
+    /** Per-render correlation id (== OTel trace-id) echoed back by the server */
+    requestId?: string;
     /** The request version this response corresponds to (for stale detection) */
     requestVersion?: number;
     /** Server-side PIXI render time in ms */
@@ -305,8 +309,10 @@ declare class RealtimeMockupService {
     private lastError;
     private callbacks;
     private lastBlobSentAt;
+    private requestSendTimes;
     private canvasBlobs;
     private canvasStates;
+    private pendingStates;
     private lastSentStateJson;
     private colors;
     private lastSendTime;
@@ -367,6 +373,8 @@ declare class RealtimeMockupService {
      * canvas JSON. One-shot (no throttle). Results arrive like any other render.
      */
     sendCanvasStateRef(placement: string, stateId: string): boolean;
+    /** Stamp a request's send time for client round-trip measurement (capped). */
+    private recordRequestSent;
     private sendCanvasStateImmediately;
     private sendBlobImmediately;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/sdk",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Snowcone SDK for product mockups and print-on-demand",
   "keywords": [
     "merch",
@@ -68,8 +68,14 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
     "@types/node": "^20.11.0",
     "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "happy-dom": "^15.11.7",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "tsup": "^8.1.0",
     "typescript": "^5.5.4",
     "vitest": "^2.0.5",