@snowcone-app/ui 0.4.14 → 0.8.0

package/dist/index.d.cts

@@ -2894,6 +2894,13 @@ interface RealtimeContextValue {
      * than blanking it or logging console-only.
      */
     renderError: RealtimeRenderError | null;
+    /**
+     * Mockups the server refused for this session (`E_MOCKUP_NOT_BLESSED`: the
+     * mockup's scene failed render parity and is served on no path). Keyed by
+     * mockupId; the other mockups keep streaming. Render these as unavailable
+     * — never as a stale or blank image.
+     */
+    unavailableMockups: ReadonlyMap<string, RealtimeRenderError>;
     isPendingMockups: boolean;
     canvasBlobsSent: number;
     colorBlobsSent: number;
@@ -3030,6 +3037,16 @@ interface RealtimeProviderProps {
      * via a renewable token. Without them, the legacy seal path runs (shim).
      */
     grantUrl?: string;
+    /**
+     * A grant minted server-side while the page rendered (POST grantUrl during
+     * SSR). Used for the FIRST connection so the socket opens without a
+     * grant round trip (382–566 ms on the PDP, 2026-09-05); renewals and
+     * reconnects go through `grantUrl`. Ignored when already expired.
+     */
+    initialGrant?: {
+        token: string;
+        expiresAt: number;
+    };
     /**
      * Frame delivery strategy. `"cropped"` (default, the fast path): once every
      * configured mockup has rendered one full frame (frozen internally as its
@@ -3048,7 +3065,7 @@ interface RealtimeProviderProps {
  *
  * Must be used inside a <Product> provider to access product data.
  */
-declare function RealtimeProvider({ children, wsUrl, mockupWidth, autoEnable, shop, grantUrl, delivery, }: RealtimeProviderProps): react_jsx_runtime.JSX.Element;
+declare function RealtimeProvider({ children, wsUrl, mockupWidth, autoEnable, shop, grantUrl, initialGrant, delivery, }: RealtimeProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Hook to access realtime context
  * Throws if not inside RealtimeProvider
@@ -3625,6 +3642,21 @@ interface CanvasExportServiceConfig {
     enableRealtime?: () => void;
     /** Disable realtime function (called when exiting editor mode) */
     disableRealtime?: () => void;
+    /**
+     * Subscribe to "the frame for the last send landed" (RealtimeProvider's
+     * pipeline-settled signal). Drives the one-in-flight send policy: a state
+     * held while a frame is in flight goes out the moment this fires.
+     */
+    subscribePipelineSettled?: (callback: () => void) => () => void;
+    /**
+     * Pipeline depth: edits allowed in flight before the latest state is held
+     * (default 2). The box's window is ~30 ms of a ~96 ms edit→frame at w4000 —
+     * the rest is wire and decode — so with one in flight the box idles ~70% of
+     * every cycle. Two keeps it busy and never queues on the box while its
+     * window stays under half the round trip (the lab's rt_coalesce says when
+     * it does not).
+     */
+    maxInFlight?: number;
     /**
      * Function to clear ImageBitmap cache (memory management for iOS Safari)
      * Pass clearImageBitmapCache from @snowcone-app/canvas
@@ -3655,9 +3687,17 @@ declare class CanvasExportService {
     private jsonModeSentSuccessfully;
     private stateChangeThrottleTimeout;
     private stateChangeLastSendTime;
-    /** How long to wait after last change before sending (quick discrete actions) */
-    private static SETTLE_MS;
-    /** During continuous activity (drag), force a send at least this often */
+    /** Send policy: send times of the edits whose frames have not landed yet, oldest first. */
+    private inFlightSentAt;
+    private maxInFlight;
+    private subscribePipelineSettled;
+    private unsubscribePipelineSettled;
+    /**
+     * Safety net for the one-in-flight policy: a held state never waits longer
+     * than this for the in-flight frame (a swallowed render error would
+     * otherwise hold the pipeline forever), and a change arriving while a
+     * frame has been in flight this long is sent regardless.
+     */
     private static MAX_WAIT_MS;
     private lastExportedArtwork;
     private initialArtwork;
@@ -3728,6 +3768,19 @@ declare class CanvasExportService {
      */
     private stateChangeCallCount;
     handleStateChange: (state: any) => void;
+    /** A send landed (every mockup of it): free its slot, release the held state if any. */
+    private onPipelineSettled;
+    /**
+     * The pointer was released (drag end, slider release, key up). Send the held
+     * state NOW instead of waiting for the in-flight frame: the server coalesces
+     * (latest wins), and the "let go" frame is the one the shopper waits for.
+     * A no-op when nothing is held, so it is safe on every pointerup.
+     */
+    handleInteractionEnd: () => void;
+    private armFlushTimer;
+    /** A send whose frame has not landed within MAX_WAIT_MS no longer occupies a slot. */
+    private dropStalledSends;
+    private clearFlushTimer;
     private sendStateNow;
     /**
      * Reset the service state (e.g., when unmounting)
@@ -3791,6 +3844,8 @@ declare function useIsolatedCanvas(): {
     handleExport: (exports: Record<string, string | Blob>) => Promise<void>;
     /** Stable state change handler - pass to SnowconeCanvas onChange for JSON mode */
     handleStateChange: (state: any) => void;
+    /** Pointer released (drag end): flush a state held behind an in-flight frame. Safe on every pointerup. */
+    handleInteractionEnd: () => void;
     /** Call when entering editor mode */
     onEnterEditorMode: () => void;
     /** Call when exiting editor mode */

package/dist/index.d.ts

@@ -2894,6 +2894,13 @@ interface RealtimeContextValue {
      * than blanking it or logging console-only.
      */
     renderError: RealtimeRenderError | null;
+    /**
+     * Mockups the server refused for this session (`E_MOCKUP_NOT_BLESSED`: the
+     * mockup's scene failed render parity and is served on no path). Keyed by
+     * mockupId; the other mockups keep streaming. Render these as unavailable
+     * — never as a stale or blank image.
+     */
+    unavailableMockups: ReadonlyMap<string, RealtimeRenderError>;
     isPendingMockups: boolean;
     canvasBlobsSent: number;
     colorBlobsSent: number;
@@ -3030,6 +3037,16 @@ interface RealtimeProviderProps {
      * via a renewable token. Without them, the legacy seal path runs (shim).
      */
     grantUrl?: string;
+    /**
+     * A grant minted server-side while the page rendered (POST grantUrl during
+     * SSR). Used for the FIRST connection so the socket opens without a
+     * grant round trip (382–566 ms on the PDP, 2026-09-05); renewals and
+     * reconnects go through `grantUrl`. Ignored when already expired.
+     */
+    initialGrant?: {
+        token: string;
+        expiresAt: number;
+    };
     /**
      * Frame delivery strategy. `"cropped"` (default, the fast path): once every
      * configured mockup has rendered one full frame (frozen internally as its
@@ -3048,7 +3065,7 @@ interface RealtimeProviderProps {
  *
  * Must be used inside a <Product> provider to access product data.
  */
-declare function RealtimeProvider({ children, wsUrl, mockupWidth, autoEnable, shop, grantUrl, delivery, }: RealtimeProviderProps): react_jsx_runtime.JSX.Element;
+declare function RealtimeProvider({ children, wsUrl, mockupWidth, autoEnable, shop, grantUrl, initialGrant, delivery, }: RealtimeProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * Hook to access realtime context
  * Throws if not inside RealtimeProvider
@@ -3625,6 +3642,21 @@ interface CanvasExportServiceConfig {
     enableRealtime?: () => void;
     /** Disable realtime function (called when exiting editor mode) */
     disableRealtime?: () => void;
+    /**
+     * Subscribe to "the frame for the last send landed" (RealtimeProvider's
+     * pipeline-settled signal). Drives the one-in-flight send policy: a state
+     * held while a frame is in flight goes out the moment this fires.
+     */
+    subscribePipelineSettled?: (callback: () => void) => () => void;
+    /**
+     * Pipeline depth: edits allowed in flight before the latest state is held
+     * (default 2). The box's window is ~30 ms of a ~96 ms edit→frame at w4000 —
+     * the rest is wire and decode — so with one in flight the box idles ~70% of
+     * every cycle. Two keeps it busy and never queues on the box while its
+     * window stays under half the round trip (the lab's rt_coalesce says when
+     * it does not).
+     */
+    maxInFlight?: number;
     /**
      * Function to clear ImageBitmap cache (memory management for iOS Safari)
      * Pass clearImageBitmapCache from @snowcone-app/canvas
@@ -3655,9 +3687,17 @@ declare class CanvasExportService {
     private jsonModeSentSuccessfully;
     private stateChangeThrottleTimeout;
     private stateChangeLastSendTime;
-    /** How long to wait after last change before sending (quick discrete actions) */
-    private static SETTLE_MS;
-    /** During continuous activity (drag), force a send at least this often */
+    /** Send policy: send times of the edits whose frames have not landed yet, oldest first. */
+    private inFlightSentAt;
+    private maxInFlight;
+    private subscribePipelineSettled;
+    private unsubscribePipelineSettled;
+    /**
+     * Safety net for the one-in-flight policy: a held state never waits longer
+     * than this for the in-flight frame (a swallowed render error would
+     * otherwise hold the pipeline forever), and a change arriving while a
+     * frame has been in flight this long is sent regardless.
+     */
     private static MAX_WAIT_MS;
     private lastExportedArtwork;
     private initialArtwork;
@@ -3728,6 +3768,19 @@ declare class CanvasExportService {
      */
     private stateChangeCallCount;
     handleStateChange: (state: any) => void;
+    /** A send landed (every mockup of it): free its slot, release the held state if any. */
+    private onPipelineSettled;
+    /**
+     * The pointer was released (drag end, slider release, key up). Send the held
+     * state NOW instead of waiting for the in-flight frame: the server coalesces
+     * (latest wins), and the "let go" frame is the one the shopper waits for.
+     * A no-op when nothing is held, so it is safe on every pointerup.
+     */
+    handleInteractionEnd: () => void;
+    private armFlushTimer;
+    /** A send whose frame has not landed within MAX_WAIT_MS no longer occupies a slot. */
+    private dropStalledSends;
+    private clearFlushTimer;
     private sendStateNow;
     /**
      * Reset the service state (e.g., when unmounting)
@@ -3791,6 +3844,8 @@ declare function useIsolatedCanvas(): {
     handleExport: (exports: Record<string, string | Blob>) => Promise<void>;
     /** Stable state change handler - pass to SnowconeCanvas onChange for JSON mode */
     handleStateChange: (state: any) => void;
+    /** Pointer released (drag end): flush a state held behind an in-flight frame. Safe on every pointerup. */
+    handleInteractionEnd: () => void;
     /** Call when entering editor mode */
     onEnterEditorMode: () => void;
     /** Call when exiting editor mode */

package/dist/index.js

@@ -39,7 +39,7 @@ var brand_default = {
       display_name: "Snowcone",
       tagline: "Your art, on everything.",
       seo_title: "Snowcone \u2014 Your art, on everything.",
-      legal_entity: "Snowcone Inc.",
+      legal_entity: "Art Shop AI LLC",
       lang: "en",
       wordmark: "/assets/wordmark-en.svg"
     },
@@ -49,7 +49,7 @@ var brand_default = {
       display_name: "\u96EA\u7ED8 (Snowcone)",
       tagline: "\u5728\u96EA\u767D\u4E4B\u4E0A\uFF0C\u7ED8\u51FA\u4F60\u7684\u8272\u5F69\u3002",
       seo_title: "\u96EA\u7ED8 (Snowcone) \u2014 \u5728\u96EA\u767D\u4E4B\u4E0A\uFF0C\u7ED8\u51FA\u4F60\u7684\u8272\u5F69",
-      legal_entity: "\u96EA\u7ED8\u79D1\u6280\u6709\u9650\u516C\u53F8",
+      legal_entity: "Art Shop AI LLC",
       lang: "zh",
       wordmark: "/assets/wordmark-zh.svg"
     },
@@ -59,7 +59,7 @@ var brand_default = {
       display_name: "Snowcone",
       tagline: "Tu arte, en todo.",
       seo_title: "Snowcone \u2014 Tu arte, en todo.",
-      legal_entity: "Snowcone Inc.",
+      legal_entity: "Art Shop AI LLC",
       lang: "es",
       wordmark: "/assets/wordmark-en.svg"
     },
@@ -69,7 +69,7 @@ var brand_default = {
       display_name: "Snowcone",
       tagline: "Votre art, sur tout.",
       seo_title: "Snowcone \u2014 Votre art, sur tout.",
-      legal_entity: "Snowcone Inc.",
+      legal_entity: "Art Shop AI LLC",
       lang: "fr",
       wordmark: "/assets/wordmark-en.svg"
     }
@@ -5648,13 +5648,18 @@ function RealtimeProvider({
   autoEnable = false,
   shop,
   grantUrl,
+  initialGrant,
   delivery = "cropped"
 }) {
   const productContext = useProductOptional();
   const mockupBg = useMockupBackgroundOptional();
   const [isEnabled, setIsEnabled] = useState17(autoEnable);
   const useSessionGrant = Boolean(shop && grantUrl);
+  const initialGrantRef = useRef12(initialGrant);
   const getToken = useCallback10(async () => {
+    const minted = initialGrantRef.current;
+    initialGrantRef.current = void 0;
+    if (minted && minted.expiresAt * 1e3 - Date.now() > 3e4) return minted;
     const res = await fetch(grantUrl, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
@@ -5677,6 +5682,9 @@ function RealtimeProvider({
   const [spreadCropsVersion, setSpreadCropsVersion] = useState17(0);
   const lastSentSpreadCropsRef = useRef12("null");
   const lastSentColorsRef = useRef12({});
+  const [unavailableMockups, setUnavailableMockups] = useState17(
+    () => /* @__PURE__ */ new Map()
+  );
   const realtimeMockup = useRealtimeMockup2({
     wsUrl,
     getToken: useSessionGrant ? getToken : void 0,
@@ -5706,6 +5714,10 @@ function RealtimeProvider({
     },
     onError: (error, detail) => {
       console.error(`[RealtimeProvider] Render error [${detail.code}]:`, error);
+      if (detail.mockupId) {
+        const id = detail.mockupId;
+        setUnavailableMockups((prev) => prev.get(id)?.code === detail.code ? prev : new Map(prev).set(id, detail));
+      }
     }
   });
   const subscribeRTCTiming = useCallback10((_callback) => {
@@ -5726,7 +5738,8 @@ function RealtimeProvider({
     connect,
     disconnect,
     flushPendingBlobs,
-    hasPendingBlobs
+    hasPendingBlobs,
+    getLastSentVersion
   } = realtimeMockup;
   const mockupResultsRef = useRef12([]);
   const mockupSubscribersRef = useRef12(
@@ -5748,6 +5761,8 @@ function RealtimeProvider({
   const blobQueuedGenRef = useRef12(0);
   const hasBlobInFlightRef = useRef12(false);
   const pipelineResetCooldownRef = useRef12(false);
+  const dueByVersionRef = useRef12(/* @__PURE__ */ new Map());
+  const configuredMockupIdsRef = useRef12([]);
   const mockupUrlCacheRef = useRef12(/* @__PURE__ */ new Map());
   const registeredBlobUrlsRef = useRef12(/* @__PURE__ */ new Set());
   const pendingPlacementsRef = useRef12(/* @__PURE__ */ new Set());
@@ -5866,7 +5881,29 @@ function RealtimeProvider({
           console.log(`[RTP] No subscribers for ${result.mockupId} \u2014 result received but nobody listening`);
         }
       });
-      if (hasBlobInFlightRef.current && !hasPendingBlobs() && !pipelineResetCooldownRef.current) {
+      let settledVersions = 0;
+      const due = dueByVersionRef.current;
+      results.forEach((result) => {
+        const v = result.requestVersion;
+        if (v === void 0) return;
+        const entry = due.get(v);
+        if (!entry) return;
+        if (entry.due <= 1) {
+          due.delete(v);
+          settledVersions += 1;
+        } else {
+          entry.due -= 1;
+        }
+      });
+      due.forEach((entry, v) => {
+        if (now - entry.at > 1e4) due.delete(v);
+      });
+      if (settledVersions > 0) {
+        if (!pipelineResetCooldownRef.current) {
+          hasBlobInFlightRef.current = false;
+          for (let i = 0; i < settledVersions; i++) pipelineSettledSubscribersRef.current.forEach((cb) => cb());
+        }
+      } else if (due.size === 0 && hasBlobInFlightRef.current && !hasPendingBlobs() && !pipelineResetCooldownRef.current) {
         hasBlobInFlightRef.current = false;
         pipelineSettledSubscribersRef.current.forEach((cb) => cb());
       }
@@ -5995,11 +6032,17 @@ function RealtimeProvider({
         canvasBlobsSentRef.current += 1;
         lastBlobSentTimeRef.current = (/* @__PURE__ */ new Date()).toLocaleTimeString();
         isPendingMockupsRef.current = true;
+        const version = getLastSentVersion();
+        if (version > 0) {
+          const configured = configuredMockupIdsRef.current.length;
+          const expected = Math.max(1, Math.min(configured || Infinity, mockupCount || Infinity));
+          dueByVersionRef.current.set(version, { due: Number.isFinite(expected) ? expected : 1, at: Date.now() });
+        }
         pendingBlobSubscribersRef.current.forEach((cb) => cb(placement));
       }
       return result;
     },
-    [sendCanvasStateRaw]
+    [sendCanvasStateRaw, getLastSentVersion]
   );
   const sendColorBlobTracked = useCallback10(
     (placement, color) => {
@@ -6019,6 +6062,8 @@ function RealtimeProvider({
       return () => {
         disconnect();
         configSentRef.current = false;
+        dueByVersionRef.current.clear();
+        setUnavailableMockups((prev) => prev.size ? /* @__PURE__ */ new Map() : prev);
         lastSentVariantIdRef.current = null;
         lastSentBgRef.current = void 0;
         lastSentSpreadCropsRef.current = "null";
@@ -6062,6 +6107,7 @@ function RealtimeProvider({
         }
       });
     }
+    configuredMockupIdsRef.current = mockupIds;
     const configPayload = useSessionGrant ? {
       productId,
       mockupIds,
@@ -6277,6 +6323,7 @@ function RealtimeProvider({
     () => {
       pipelineGenRef.current++;
       hasBlobInFlightRef.current = false;
+      dueByVersionRef.current.clear();
       pipelineResetCooldownRef.current = true;
       requestAnimationFrame(() => {
         pipelineResetCooldownRef.current = false;
@@ -6415,6 +6462,7 @@ function RealtimeProvider({
       isConnected,
       isConfigured,
       renderError,
+      unavailableMockups,
       // Read from ref - this is a snapshot at render time, NOT reactive
       // For reactive updates, use getMockupResultsImmediate() or subscribe functions
       get mockupResults() {
@@ -6460,6 +6508,7 @@ function RealtimeProvider({
       isConnected,
       isConfigured,
       renderError,
+      unavailableMockups,
       // mockupResults removed from deps - it's a getter that reads from ref
       canvasExportSize,
       mockupWidth,
@@ -8308,9 +8357,18 @@ var CanvasExportService = class _CanvasExportService {
   // Debounce state for handleStateChange
   stateChangeThrottleTimeout = null;
   stateChangeLastSendTime = 0;
-  /** How long to wait after last change before sending (quick discrete actions) */
-  static SETTLE_MS = 300;
-  /** During continuous activity (drag), force a send at least this often */
+  /** Send policy: send times of the edits whose frames have not landed yet, oldest first. */
+  inFlightSentAt = [];
+  maxInFlight = 2;
+  // CanvasExportServiceConfig.maxInFlight
+  subscribePipelineSettled = null;
+  unsubscribePipelineSettled = null;
+  /**
+   * Safety net for the one-in-flight policy: a held state never waits longer
+   * than this for the in-flight frame (a swallowed render error would
+   * otherwise hold the pipeline forever), and a change arriving while a
+   * frame has been in flight this long is sent regardless.
+   */
   static MAX_WAIT_MS = 1e3;
   // Internal state for tracking exports
   lastExportedArtwork = null;
@@ -8352,6 +8410,14 @@ var CanvasExportService = class _CanvasExportService {
     if (config.disableRealtime !== void 0) {
       this.disableRealtime = config.disableRealtime;
     }
+    if (config.maxInFlight !== void 0) {
+      this.maxInFlight = config.maxInFlight;
+    }
+    if (config.subscribePipelineSettled !== void 0 && config.subscribePipelineSettled !== this.subscribePipelineSettled) {
+      this.unsubscribePipelineSettled?.();
+      this.subscribePipelineSettled = config.subscribePipelineSettled;
+      this.unsubscribePipelineSettled = config.subscribePipelineSettled?.(this.onPipelineSettled) ?? null;
+    }
     if (config.clearImageBitmapCache !== void 0) {
       this.clearImageBitmapCache = config.clearImageBitmapCache;
     }
@@ -8555,42 +8621,62 @@ var CanvasExportService = class _CanvasExportService {
       console.log(`[CES] handleStateChange #${callId}: not ready (realtime=${this.isRealtimeEnabled} sendState=${!!this.sendCanvasState} serialize=${!!this.serializeStateForServer}) \u2014 state cached`);
       return;
     }
-    const settleMs = _CanvasExportService.SETTLE_MS;
-    const maxWaitMs = _CanvasExportService.MAX_WAIT_MS;
-    const hasSentBefore = this.stateChangeLastSendTime > 0;
-    const timeSinceLastSend = hasSentBefore ? now - this.stateChangeLastSendTime : 0;
-    const isActiveDrag = hasSentBefore && timeSinceLastSend < maxWaitMs * 3;
-    if (isActiveDrag && timeSinceLastSend >= maxWaitMs) {
-      console.log(`[CES] handleStateChange #${callId}: MAX-WAIT FLUSH (${timeSinceLastSend}ms >= ${maxWaitMs}ms)`);
-      if (this.stateChangeThrottleTimeout) {
-        clearTimeout(this.stateChangeThrottleTimeout);
-        this.stateChangeThrottleTimeout = null;
-      }
+    this.dropStalledSends(now);
+    const inFlight = this.inFlightSentAt.length;
+    if (inFlight < this.maxInFlight) {
+      console.log(`[CES] handleStateChange #${callId}: SEND now (${inFlight} in flight)`);
+      this.clearFlushTimer();
       this.sendStateNow(state);
       return;
     }
-    const isIdle = !this.stateChangeThrottleTimeout && (!hasSentBefore || timeSinceLastSend >= settleMs);
-    if (isIdle) {
-      console.log(`[CES] handleStateChange #${callId}: LEADING send (idle ${hasSentBefore ? timeSinceLastSend : "forever"}ms)`);
-      this.sendStateNow(state);
-      this.stateChangeThrottleTimeout = setTimeout(() => {
-        this.stateChangeThrottleTimeout = null;
-        if (this.pendingCanvasState) this.sendStateNow(this.pendingCanvasState);
-      }, settleMs);
-      return;
-    }
-    if (this.stateChangeThrottleTimeout) {
-      clearTimeout(this.stateChangeThrottleTimeout);
+    const oldestMs = now - this.inFlightSentAt[0];
+    console.log(`[CES] handleStateChange #${callId}: HELD (${inFlight} in flight, oldest ${oldestMs}ms) \u2014 sends when one lands`);
+    this.armFlushTimer(_CanvasExportService.MAX_WAIT_MS - oldestMs);
+  };
+  /** A send landed (every mockup of it): free its slot, release the held state if any. */
+  onPipelineSettled = () => {
+    this.inFlightSentAt.shift();
+    this.clearFlushTimer();
+    if (this.pendingCanvasState && this.isRealtimeEnabled) {
+      console.log(`[CES] pipeline settled \u2192 sending held state`);
+      this.sendStateNow(this.pendingCanvasState);
     }
-    console.log(`[CES] handleStateChange #${callId}: SETTLE scheduled ${settleMs}ms`);
+  };
+  /**
+   * The pointer was released (drag end, slider release, key up). Send the held
+   * state NOW instead of waiting for the in-flight frame: the server coalesces
+   * (latest wins), and the "let go" frame is the one the shopper waits for.
+   * A no-op when nothing is held, so it is safe on every pointerup.
+   */
+  handleInteractionEnd = () => {
+    if (!this.pendingCanvasState || !this.isRealtimeEnabled || !this.sendCanvasState || !this.serializeStateForServer) return;
+    if (this.inFlightSentAt.length < this.maxInFlight) return;
+    console.log(`[CES] interaction end \u2192 flushing held state`);
+    this.clearFlushTimer();
+    this.sendStateNow(this.pendingCanvasState);
+  };
+  armFlushTimer(ms) {
+    this.clearFlushTimer();
     this.stateChangeThrottleTimeout = setTimeout(() => {
       this.stateChangeThrottleTimeout = null;
-      console.log(`[CES] handleStateChange #${callId}: SETTLE FIRED at ${Date.now()} (${Date.now() - now}ms after call)`);
       if (this.pendingCanvasState) {
+        console.log(`[CES] flush timer \u2192 sending held state (no frame landed within ${_CanvasExportService.MAX_WAIT_MS}ms)`);
+        this.dropStalledSends(Date.now());
         this.sendStateNow(this.pendingCanvasState);
       }
-    }, settleMs);
-  };
+    }, Math.max(0, ms));
+  }
+  /** A send whose frame has not landed within MAX_WAIT_MS no longer occupies a slot. */
+  dropStalledSends(now) {
+    if (this.inFlightSentAt.length === 0) return;
+    this.inFlightSentAt = this.inFlightSentAt.filter((t) => now - t < _CanvasExportService.MAX_WAIT_MS);
+  }
+  clearFlushTimer() {
+    if (this.stateChangeThrottleTimeout) {
+      clearTimeout(this.stateChangeThrottleTimeout);
+      this.stateChangeThrottleTimeout = null;
+    }
+  }
   sendStateNow(state) {
     if (!this.sendCanvasState || !this.serializeStateForServer) {
       console.log(`[CES] sendStateNow SKIPPED: sendCanvasState=${!!this.sendCanvasState} serializeStateForServer=${!!this.serializeStateForServer}`);
@@ -8615,6 +8701,7 @@ var CanvasExportService = class _CanvasExportService {
     if (sent) {
       this.pendingCanvasState = null;
       this.jsonModeSentSuccessfully = true;
+      this.inFlightSentAt.push(Date.now());
       console.log(`[CES] JSON state sent for ${artboards.length} artboard(s)`);
     } else {
       console.log(`[CES] JSON state send FAILED for all ${artboards.length} artboard(s) \u2014 state remains pending, jsonEverSent=${this.jsonModeSentSuccessfully}`);
@@ -8636,6 +8723,7 @@ var CanvasExportService = class _CanvasExportService {
       this.stateChangeThrottleTimeout = null;
     }
     this.stateChangeLastSendTime = 0;
+    this.inFlightSentAt = [];
     this.jsonModeSentSuccessfully = false;
     this.pendingCanvasState = null;
     if (this.clearImageBitmapCache) {
@@ -8671,7 +8759,10 @@ function CanvasIsolationConfigurator({
       // Wire CES's "I sent nothing" signal to the realtime context's
       // cancellation broadcaster. Roll back any optimistic
       // notifyPendingExport that didn't end up producing a real export.
-      notifyExportSkipped: realtimeContext?.notifyPendingExportCancelled
+      notifyExportSkipped: realtimeContext?.notifyPendingExportCancelled,
+      // One-in-flight send policy: the held state goes out when the last
+      // send's frame lands.
+      subscribePipelineSettled: realtimeContext?.subscribePipelineSettled
     });
   }, [
     realtimeContext?.sendCanvasBlob,
@@ -8683,6 +8774,7 @@ function CanvasIsolationConfigurator({
     realtimeContext?.enableRealtime,
     realtimeContext?.disableRealtime,
     realtimeContext?.notifyPendingExportCancelled,
+    realtimeContext?.subscribePipelineSettled,
     placementNameProp,
     onArtworkChange,
     clearImageBitmapCache
@@ -8728,6 +8820,8 @@ function useIsolatedCanvas() {
     handleExport: canvasExportService.handleExport,
     /** Stable state change handler - pass to SnowconeCanvas onChange for JSON mode */
     handleStateChange: canvasExportService.handleStateChange,
+    /** Pointer released (drag end): flush a state held behind an in-flight frame. Safe on every pointerup. */
+    handleInteractionEnd: canvasExportService.handleInteractionEnd,
     /** Call when entering editor mode */
     onEnterEditorMode: () => canvasExportService.onEnterEditorMode(),
     /** Call when exiting editor mode */
@@ -10019,6 +10113,7 @@ var HeroProductImage = memo3(function HeroProductImage2({
   const actualMockupId = useMemo14(() => {
     return resolveMockupId(context, actualGvid, mockupId);
   }, [mockupId, actualGvid, context]);
+  const unavailable = actualMockupId ? realtimeContext?.unavailableMockups?.get(actualMockupId) ?? null : null;
   const artworkSrc = artwork?.src;
   const selectedArtworkSrc = designContext?.selectedArtwork?.src;
   const effectiveArtworkSrc = artworkSrc || selectedArtworkSrc;
@@ -10467,7 +10562,17 @@ var HeroProductImage = memo3(function HeroProductImage2({
       className: `relative overflow-hidden ${className || ""}`,
       style,
       "data-hero-image": "true",
+      "data-mockup-unavailable": unavailable ? unavailable.code : void 0,
       children: [
+        unavailable && /* @__PURE__ */ jsx61(
+          "div",
+          {
+            role: "status",
+            title: unavailable.message,
+            className: "absolute inset-0 z-20 flex items-center justify-center bg-white/80 text-sm text-neutral-700",
+            children: "Mockup unavailable"
+          }
+        ),
         renderedUrl && !imgFailed && /* @__PURE__ */ jsx61(
           "img",
           {