@snowcone-app/ui 0.4.13 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/ui",
-  "version": "0.4.13",
+  "version": "0.8.0",
   "description": "React components for merchandise visualization and customization",
   "keywords": [
     "react",
@@ -103,7 +103,7 @@
     "react-instantsearch": "^7.15.5",
     "react-zoom-pan-pinch": "^3.6.4",
     "tailwind-merge": "^3.0.0",
-    "@snowcone-app/sdk": "0.20.3"
+    "@snowcone-app/sdk": "0.23.0"
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^4.1.2",

package/src/components/CanvasIsolationBoundary.tsx

@@ -92,6 +92,9 @@ export function CanvasIsolationConfigurator({
       // cancellation broadcaster. Roll back any optimistic
       // notifyPendingExport that didn't end up producing a real export.
       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,
@@ -103,6 +106,7 @@ export function CanvasIsolationConfigurator({
     realtimeContext?.enableRealtime,
     realtimeContext?.disableRealtime,
     realtimeContext?.notifyPendingExportCancelled,
+    realtimeContext?.subscribePipelineSettled,
     placementNameProp,
     onArtworkChange,
     clearImageBitmapCache,
@@ -188,6 +192,8 @@ export 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 */

package/src/composed/HeroProductImage.tsx

@@ -240,6 +240,11 @@ export const HeroProductImage = memo(function HeroProductImage({
     return resolveMockupId(context, actualGvid, mockupId);
   }, [mockupId, actualGvid, context]);
 
+  // The server refused THIS mockup for the session (its scene failed render
+  // parity — E_MOCKUP_NOT_BLESSED). Shown as unavailable on top of whatever
+  // was last rendered; never a blank or a silently stale image.
+  const unavailable = actualMockupId ? (realtimeContext?.unavailableMockups?.get(actualMockupId) ?? null) : null;
+
   // Extract artwork source for initial URL computation
   const artworkSrc = artwork?.src;
   const selectedArtworkSrc = designContext?.selectedArtwork?.src;
@@ -1026,7 +1031,17 @@ export const HeroProductImage = memo(function HeroProductImage({
       className={`relative overflow-hidden ${className || ""}`}
       style={style}
       data-hero-image="true"
+      data-mockup-unavailable={unavailable ? unavailable.code : undefined}
     >
+      {unavailable && (
+        <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"
+        >
+          Mockup unavailable
+        </div>
+      )}
       {/* Current image — shows `renderedUrl`, which the crossfade effect only
           advances after the next image has finished preloading. This prevents
           the new → old → new flash that happened when displayUrl was bound

package/src/ecommerce/stories/PDPInfoPanel.stories.tsx

@@ -270,7 +270,8 @@ const PDPInfoPanel = ({
               </AccordionTrigger>
               <AccordionContent>
                 <p className="text-base font-caption text-muted-foreground leading-relaxed">
-                  Free shipping on orders over $50. 30-day return policy.
+                  Made to order just for you. Free shipping on all orders. See
+                  our Returns Policy for details.
                 </p>
               </AccordionContent>
             </AccordionItem>

package/src/ecommerce/stories/PDPLayout.stories.tsx

@@ -240,7 +240,8 @@ const PDPLayout = ({
                     </AccordionTrigger>
                     <AccordionContent>
                       <p className="text-sm text-muted-foreground leading-relaxed">
-                        Free shipping on orders over $50. 30-day returns.
+                        Made to order just for you. Free shipping on all
+                        orders. See our Returns Policy for details.
                       </p>
                     </AccordionContent>
                   </AccordionItem>

package/src/patterns/RealtimeProvider.tsx

@@ -88,6 +88,13 @@ export 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>;
 
   // Debug/tracking state (now refs, won't trigger re-renders)
   isPendingMockups: boolean;
@@ -285,6 +292,13 @@ export 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
@@ -313,6 +327,7 @@ export function RealtimeProvider({
   autoEnable = false,
   shop,
   grantUrl,
+  initialGrant,
   delivery = "cropped",
 }: RealtimeProviderProps) {
   const productContext = useProductOptional();
@@ -325,7 +340,14 @@ export function RealtimeProvider({
   // When a shop + grant endpoint are wired, authorize the session with a
   // renewable token instead of the legacy bypass seal. Stable identity.
   const useSessionGrant = Boolean(shop && grantUrl);
+  // The SSR-minted grant is spent once: the first connect takes it if it has
+  // life left; everything after (renew ~15 s before expiry, reconnects)
+  // fetches a fresh one. Ref, not state: consumed inside the token provider.
+  const initialGrantRef = useRef(initialGrant);
   const getToken = useCallback(async () => {
+    const minted = initialGrantRef.current;
+    initialGrantRef.current = undefined;
+    if (minted && minted.expiresAt * 1000 - Date.now() > 30_000) return minted;
     const res = await fetch(grantUrl as string, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
@@ -372,6 +394,13 @@ export function RealtimeProvider({
   const lastSentColorsRef = useRef<Record<string, string>>({});
 
   // Initialize realtime mockup hook
+  // Mockups the server refused this session (E_MOCKUP_NOT_BLESSED): keyed by
+  // mockupId so a card can show exactly that one as unavailable. Cleared on
+  // reconnect (a fixed mockup recompiles and stops being refused).
+  const [unavailableMockups, setUnavailableMockups] = useState<ReadonlyMap<string, RealtimeRenderError>>(
+    () => new Map(),
+  );
+
   const realtimeMockup = useRealtimeMockup({
     wsUrl,
     getToken: useSessionGrant ? getToken : undefined,
@@ -404,6 +433,12 @@ export function RealtimeProvider({
       // Logged for traces; the actionable surface is `renderError` on the
       // context (and the hook state), which consumers must render visibly.
       console.error(`[RealtimeProvider] Render error [${detail.code}]:`, error);
+      // A per-mockup refusal names the mockup: remember it so that card shows
+      // "unavailable" while the others keep streaming.
+      if (detail.mockupId) {
+        const id = detail.mockupId;
+        setUnavailableMockups((prev) => (prev.get(id)?.code === detail.code ? prev : new Map(prev).set(id, detail)));
+      }
     },
   });
 
@@ -427,6 +462,7 @@ export function RealtimeProvider({
     disconnect,
     flushPendingBlobs,
     hasPendingBlobs,
+    getLastSentVersion,
   } = realtimeMockup;
 
   // PERFORMANCE: Store mockup results in ref only - NO STATE UPDATES
@@ -475,6 +511,12 @@ export function RealtimeProvider({
   const blobQueuedGenRef = useRef(0);
   const hasBlobInFlightRef = useRef(false);
   const pipelineResetCooldownRef = useRef(false);
+  // JSON-mode settle: a canvas_state send's version → mockups still due for
+  // it (+ when it went out). "Settled" fires once per version, when its last
+  // mockup lands, so the export service can keep N edits in flight (pipeline
+  // depth) and count landings exactly. Blob sends keep the throttle-queue rule.
+  const dueByVersionRef = useRef<Map<number, { due: number; at: number }>>(new Map());
+  const configuredMockupIdsRef = useRef<string[]>([]);
 
   // Centralized mockup URL cache - stores URLs by mockupId
   // This is the single source of truth for all mockup URLs (realtime or static)
@@ -670,8 +712,33 @@ export function RealtimeProvider({
         }
       });
 
-      // Pipeline-settled check
-      if (hasBlobInFlightRef.current && !hasPendingBlobs() && !pipelineResetCooldownRef.current) {
+      // Pipeline-settled check. A JSON send settles when every mockup of its
+      // version has landed (one settle per send, in order); a version whose
+      // frames never all arrive (a failed mockup) is forgotten after 10 s so
+      // it cannot wedge the policy. Blob sends keep the throttle-queue rule.
+      let settledVersions = 0;
+      const due = dueByVersionRef.current;
+      results.forEach((result) => {
+        const v = result.requestVersion;
+        if (v === undefined) 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 > 10_000) 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());
       }
@@ -853,11 +920,19 @@ export function RealtimeProvider({
         canvasBlobsSentRef.current += 1;
         lastBlobSentTimeRef.current = new Date().toLocaleTimeString();
         isPendingMockupsRef.current = true;
+        // Frames due for this send: the session's mockups, or the caller's
+        // count when it is smaller (a subset shown via updateMockupIds).
+        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]
   );
 
   // Wrap sendColorBlob to track when colors are sent
@@ -882,6 +957,8 @@ export function RealtimeProvider({
       return () => {
         disconnect();
         configSentRef.current = false;
+        dueByVersionRef.current.clear(); // versions restart at 1 on the next socket
+        setUnavailableMockups((prev) => (prev.size ? new Map() : prev)); // a fixed mockup stops being refused
         lastSentVariantIdRef.current = null;
         lastSentBgRef.current = undefined;
         lastSentSpreadCropsRef.current = "null";
@@ -950,6 +1027,7 @@ export function RealtimeProvider({
         }
       });
     }
+    configuredMockupIdsRef.current = mockupIds;
 
     // Authed sessions: the grant token (verified on connect) authorizes the
     // session and the server self-signs the render, so no seal is sent and the
@@ -1240,6 +1318,7 @@ export function RealtimeProvider({
   const resetPipelineSettled = useCallback(() => {
     pipelineGenRef.current++;
     hasBlobInFlightRef.current = false;
+    dueByVersionRef.current.clear();
     pipelineResetCooldownRef.current = true;
     requestAnimationFrame(() => {
       pipelineResetCooldownRef.current = false;
@@ -1433,6 +1512,7 @@ export 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() {
@@ -1478,6 +1558,7 @@ export function RealtimeProvider({
       isConnected,
       isConfigured,
       renderError,
+      unavailableMockups,
       // mockupResults removed from deps - it's a getter that reads from ref
       canvasExportSize,
       mockupWidth,

package/src/primitives/stories/Accordion.stories.tsx

@@ -104,8 +104,8 @@ export const FAQ: Story = {
         <AccordionItem value="q3">
           <AccordionTrigger>What is your return policy?</AccordionTrigger>
           <AccordionContent>
-            We offer a 30-day return policy for all unused items in their original
-            packaging. Custom orders are final sale and cannot be returned.
+            Returns and exchanges are handled according to our published returns
+            policy. See the Returns page for eligibility details.
           </AccordionContent>
         </AccordionItem>
         <AccordionItem value="q4">

package/src/services/CanvasExportService.ts

@@ -56,6 +56,21 @@ export 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
@@ -93,9 +108,17 @@ class CanvasExportService {
   // Debounce state for handleStateChange
   private stateChangeThrottleTimeout: ReturnType<typeof setTimeout> | null = null;
   private stateChangeLastSendTime = 0;
-  /** How long to wait after last change before sending (quick discrete actions) */
-  private 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. */
+  private inFlightSentAt: number[] = [];
+  private maxInFlight = 2; // CanvasExportServiceConfig.maxInFlight
+  private subscribePipelineSettled: ((callback: () => void) => () => void) | null = null;
+  private unsubscribePipelineSettled: (() => void) | null = 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.
+   */
   private static MAX_WAIT_MS = 1000;
 
   // Internal state for tracking exports
@@ -139,6 +162,14 @@ class CanvasExportService {
     if (config.disableRealtime !== undefined) {
       this.disableRealtime = config.disableRealtime;
     }
+    if (config.maxInFlight !== undefined) {
+      this.maxInFlight = config.maxInFlight;
+    }
+    if (config.subscribePipelineSettled !== undefined && config.subscribePipelineSettled !== this.subscribePipelineSettled) {
+      this.unsubscribePipelineSettled?.();
+      this.subscribePipelineSettled = config.subscribePipelineSettled;
+      this.unsubscribePipelineSettled = config.subscribePipelineSettled?.(this.onPipelineSettled) ?? null;
+    }
     if (config.clearImageBitmapCache !== undefined) {
       this.clearImageBitmapCache = config.clearImageBitmapCache;
     }
@@ -425,41 +456,77 @@ class CanvasExportService {
       return;
     }
 
-    // Debounce with max wait: reset timer on each call so rapid drag frames
-    // coalesce, but if we haven't sent in >= throttleMs, flush immediately
-    // so long drags still get periodic updates.
-    const settleMs = CanvasExportService.SETTLE_MS;
-    const maxWaitMs = CanvasExportService.MAX_WAIT_MS;
-    const hasSentBefore = this.stateChangeLastSendTime > 0;
-    const timeSinceLastSend = hasSentBefore ? now - this.stateChangeLastSendTime : 0;
-
-    // Max wait: during a continuous drag, force a send if it's been >= maxWaitMs
-    // since last send. "Active" means last send was recent (within 3× maxWait).
-    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;
-      }
+    // PIPELINE DEPTH (2026-09-05/06, render-speed lab): the box turns an edit
+    // into a frame in ~30 ms; the rest of an edit→frame (~96 ms at w4000) is
+    // wire and decode. Up to maxInFlight edits go out immediately; beyond that
+    // the LATEST state is held and goes out the moment a frame lands (pipeline
+    // settled fires once per landed send), so the box is never idle and never
+    // more than a frame behind — it renders a session serially and coalesces
+    // latest-wins if edits ever pile up. handleInteractionEnd() flushes a held
+    // state on pointer release without waiting. Two safety nets: a send whose
+    // frame never lands stops counting after MAX_WAIT_MS, and a held state
+    // with no further changes flushes on a MAX_WAIT_MS timer.
+    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 oldestMs = now - this.inFlightSentAt[0];
+    console.log(`[CES] handleStateChange #${callId}: HELD (${inFlight} in flight, oldest ${oldestMs}ms) — sends when one lands`);
+    this.armFlushTimer(CanvasExportService.MAX_WAIT_MS - oldestMs);
+  };
 
-    // Settle timer: reset on every call, fires settleMs after last change.
-    // Handles discrete actions (type a letter, nudge, color pick).
-    if (this.stateChangeThrottleTimeout) {
-      clearTimeout(this.stateChangeThrottleTimeout);
+  /** A send landed (every mockup of it): free its slot, release the held state if any. */
+  private onPipelineSettled = (): void => {
+    this.inFlightSentAt.shift();
+    this.clearFlushTimer();
+    if (this.pendingCanvasState && this.isRealtimeEnabled) {
+      console.log(`[CES] pipeline settled → 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 = (): void => {
+    if (!this.pendingCanvasState || !this.isRealtimeEnabled || !this.sendCanvasState || !this.serializeStateForServer) return;
+    if (this.inFlightSentAt.length < this.maxInFlight) return; // nothing held: the last change already went out
+    console.log(`[CES] interaction end → flushing held state`);
+    this.clearFlushTimer();
+    this.sendStateNow(this.pendingCanvasState);
+  };
+
+  private armFlushTimer(ms: number): void {
+    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 → 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. */
+  private dropStalledSends(now: number): void {
+    if (this.inFlightSentAt.length === 0) return;
+    this.inFlightSentAt = this.inFlightSentAt.filter((t) => now - t < CanvasExportService.MAX_WAIT_MS);
+  }
+
+  private clearFlushTimer(): void {
+    if (this.stateChangeThrottleTimeout) {
+      clearTimeout(this.stateChangeThrottleTimeout);
+      this.stateChangeThrottleTimeout = null;
+    }
+  }
 
   private sendStateNow(state: any): void {
     if (!this.sendCanvasState || !this.serializeStateForServer) {
@@ -489,6 +556,7 @@ 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) — state remains pending, jsonEverSent=${this.jsonModeSentSuccessfully}`);
@@ -512,6 +580,7 @@ class CanvasExportService {
       this.stateChangeThrottleTimeout = null;
     }
     this.stateChangeLastSendTime = 0;
+    this.inFlightSentAt = [];
     // A new editor session starts with nothing sent: its first empty state
     // is a blank mount again, not a deletion (see handleStateChange).
     this.jsonModeSentSuccessfully = false;

package/src/services/__tests__/CanvasExportService.leadingEdge.test.ts

@@ -0,0 +1,132 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { canvasExportService } from "../CanvasExportService";
+
+const state = (n: number) => ({
+  elements: [{ type: "shape", n }],
+  artboards: [{ name: "Front", width: 100, height: 100 }],
+  activeArtboard: "Front",
+});
+const nOf = (call: unknown[]) => (call[1] as { elements: { n: number }[] }).elements[0].n;
+
+/**
+ * Pipeline-depth send policy (2026-09-06): up to maxInFlight (default 2)
+ * edits go out immediately; beyond that the latest state is held and goes
+ * out when a frame lands (pipeline settled, once per landed send); pointer
+ * release flushes a held state immediately; MAX_WAIT (1 s) bounds every
+ * hold and retires a send whose frame never lands.
+ */
+describe("CanvasExportService — pipeline-depth send policy", () => {
+  let send: ReturnType<typeof vi.fn>;
+  let settled: (() => void) | null;
+  const configure = (maxInFlight?: number) =>
+    canvasExportService.configure({
+      isRealtimeEnabled: true,
+      sendCanvasState: send as never,
+      serializeStateForServer: ((s: unknown) => s) as never,
+      mockupCount: 1,
+      placementName: "Front",
+      ...(maxInFlight !== undefined ? { maxInFlight } : {}),
+      subscribePipelineSettled: (cb) => {
+        settled = cb;
+        return () => {
+          settled = null;
+        };
+      },
+    });
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    canvasExportService.reset();
+    send = vi.fn(() => true);
+    settled = null;
+    configure(2);
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("sends two changes immediately, holds the third, releases the latest when a frame lands", () => {
+    canvasExportService.handleStateChange(state(1));
+    canvasExportService.handleStateChange(state(2));
+    expect(send).toHaveBeenCalledTimes(2); // two slots, nothing held
+
+    vi.advanceTimersByTime(50);
+    canvasExportService.handleStateChange(state(3)); // held: two in flight
+    vi.advanceTimersByTime(50);
+    canvasExportService.handleStateChange(state(4)); // replaces the held state
+    expect(send).toHaveBeenCalledTimes(2);
+
+    settled!(); // frame 1 landed → one slot free → the LATEST goes out
+    expect(send).toHaveBeenCalledTimes(3);
+    expect(nOf(send.mock.calls[2])).toBe(4);
+
+    settled!(); // frame 2 landed, nothing held → nothing sent
+    expect(send).toHaveBeenCalledTimes(3);
+    canvasExportService.handleStateChange(state(5)); // one slot free → immediate
+    expect(send).toHaveBeenCalledTimes(4);
+  });
+
+  it("a lone change sends exactly once, and its settle sends nothing more", () => {
+    canvasExportService.handleStateChange(state(1));
+    settled!();
+    vi.advanceTimersByTime(2000);
+    expect(send).toHaveBeenCalledTimes(1);
+  });
+
+  it("a drag streams one edit per landed frame with two always in flight: never idle, never more than two ahead", () => {
+    // 60 Hz changes; each send's frame lands 400 ms after it went out, so the
+    // two leading sends (t=0, 16) land at 400/416, their replacements at 800/816…
+    let t = 0;
+    for (let i = 0; i < 90; i++) {
+      canvasExportService.handleStateChange(state(i));
+      vi.advanceTimersByTime(16);
+      t += 16;
+      if (t % 400 < 16 || (t - 16) % 400 < 16) settled!();
+    }
+    // ~1.44 s of drag: 2 leading + 2 per 400 ms round trip (at 400, 800, 1200)
+    expect(send.mock.calls.length).toBeGreaterThanOrEqual(7);
+    expect(send.mock.calls.length).toBeLessThanOrEqual(9);
+  });
+
+  it("pointer release flushes the held state without waiting for a frame", () => {
+    canvasExportService.handleStateChange(state(1));
+    canvasExportService.handleStateChange(state(2));
+    canvasExportService.handleStateChange(state(3)); // held
+    canvasExportService.handleInteractionEnd();
+    expect(send).toHaveBeenCalledTimes(3);
+    expect(nOf(send.mock.calls[2])).toBe(3);
+    canvasExportService.handleInteractionEnd(); // nothing held now → no-op
+    expect(send).toHaveBeenCalledTimes(3);
+  });
+
+  it("frames that never land stop holding after MAX_WAIT (1 s)", () => {
+    canvasExportService.handleStateChange(state(1));
+    canvasExportService.handleStateChange(state(2));
+    canvasExportService.handleStateChange(state(3)); // held, no settle ever
+    vi.advanceTimersByTime(999);
+    expect(send).toHaveBeenCalledTimes(2);
+    vi.advanceTimersByTime(1);
+    expect(send).toHaveBeenCalledTimes(3); // flush timer
+    expect(nOf(send.mock.calls[2])).toBe(3);
+  });
+
+  it("a change arriving after the in-flight sends have aged past MAX_WAIT is sent regardless", () => {
+    canvasExportService.handleStateChange(state(1));
+    canvasExportService.handleStateChange(state(2));
+    vi.advanceTimersByTime(1000);
+    canvasExportService.handleStateChange(state(3));
+    expect(send).toHaveBeenCalledTimes(3);
+  });
+
+  it("maxInFlight: 1 is the one-in-flight policy: leading send, hold, release on settle", () => {
+    configure(1);
+    canvasExportService.handleStateChange(state(1));
+    canvasExportService.handleStateChange(state(2)); // held
+    expect(send).toHaveBeenCalledTimes(1);
+    settled!();
+    expect(send).toHaveBeenCalledTimes(2);
+    expect(nOf(send.mock.calls[1])).toBe(2);
+  });
+});