@snowcone-app/sdk 0.3.3 → 0.3.5

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-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;
@@ -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
@@ -2763,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-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-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;
@@ -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
@@ -2763,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-D5ZRGKA5.js";
+} from "./chunk-YTOTCNEW.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
@@ -4864,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) {
@@ -4968,7 +5025,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

@@ -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,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 = {};
@@ -71,6 +98,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 +126,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 +154,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 +173,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) {
@@ -205,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";
@@ -218,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;
@@ -237,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,
@@ -259,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) {
@@ -292,7 +343,10 @@ var RealtimeMockupService = class {
     }
   }
   disconnect() {
+    this.connectAttempt++;
+    this.isConnecting = false;
     this.clearRenew();
+    this.pendingStates.clear();
     if (this.ws) {
       this.ws.close();
       this.ws = null;
@@ -330,6 +384,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;
@@ -463,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);
@@ -518,34 +575,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/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-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-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-hXpNcyEn.js';
 
 interface UseRealtimeMockupOptions {
     wsUrl?: string;

package/dist/react.js

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

package/dist/{websocket-Poy8LZNA.d.cts → websocket-hXpNcyEn.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;
 /**
@@ -229,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 */
@@ -251,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 */
@@ -304,8 +309,11 @@ declare class RealtimeMockupService {
     private lastError;
     private callbacks;
     private lastBlobSentAt;
+    private requestSendTimes;
     private canvasBlobs;
     private canvasStates;
+    private pendingStates;
+    private lastSentStateJson;
     private colors;
     private lastSendTime;
     private throttleTimeouts;
@@ -316,6 +324,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). */
@@ -363,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-Poy8LZNA.d.ts → websocket-hXpNcyEn.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;
 /**
@@ -229,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 */
@@ -251,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 */
@@ -304,8 +309,11 @@ declare class RealtimeMockupService {
     private lastError;
     private callbacks;
     private lastBlobSentAt;
+    private requestSendTimes;
     private canvasBlobs;
     private canvasStates;
+    private pendingStates;
+    private lastSentStateJson;
     private colors;
     private lastSendTime;
     private throttleTimeouts;
@@ -316,6 +324,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). */
@@ -363,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;
     /**