@snowcone-app/ui 0.9.2 → 0.9.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/ui",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "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.24.4"
+    "@snowcone-app/sdk": "0.25.0"
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^4.1.2",

package/src/composed/HeroProductImage.tsx

@@ -545,6 +545,76 @@ export const HeroProductImage = memo(function HeroProductImage({
     };
   }, [mode, realtimeContext?.subscribePendingBlob, placement]);
 
+  // RENDER-VERSION STAMP — machine-readable truth about this picture, written
+  // straight to the DOM (no re-renders mid-drag):
+  //   data-canvas-version  the canvas version the session last sent
+  //   data-render-version  the version the shown picture was rendered from
+  //                        (0 = no live render yet: the pre-edit image)
+  //   data-render-state    current | stale | refused
+  // A check asserts every visible picture reaches `current` after an edit; a
+  // picture stuck on `stale` is the "editor updates, pictures don't" defect
+  // (snowcone.app phone case, 2026-11-11). Absent until the first edit.
+  const renderVersionRef = useRef(0);
+  // Per-placement versions of the shown frame (servers that stamp them).
+  const renderVersionsRef = useRef<Record<string, number> | null>(null);
+  const getLatestSentVersions = realtimeContext?.getLatestSentVersions;
+  const refusalCodeRef = useRef<string | null>(null);
+  refusalCodeRef.current = unavailable?.code ?? null;
+  const sessionErrorCodeRef = useRef<string | null>(null);
+  sessionErrorCodeRef.current = realtimeContext?.renderError?.code ?? null;
+  const getCanvasVersion = realtimeContext?.getCanvasVersion;
+  const applyRenderStamp = useCallback(() => {
+    const node = containerRef.current;
+    if (!node) return;
+    const canvas = getCanvasVersion?.() ?? 0;
+    if (canvas <= 0) {
+      delete node.dataset.canvasVersion;
+      delete node.dataset.renderVersion;
+      delete node.dataset.renderState;
+      return;
+    }
+    const rendered = renderVersionRef.current;
+    // With per-placement stamps, current = every placement at (or past) the
+    // latest version SENT for it. A single max can't say that: a frame can
+    // hold one group's newest state and another group's older one.
+    const versions = renderVersionsRef.current;
+    const sent = versions ? getLatestSentVersions?.() : undefined;
+    const behind = versions && sent
+      ? Object.entries(sent).some(([placement, v]) => (versions[placement] ?? -1) < v)
+      : rendered < canvas;
+    node.dataset.canvasVersion = String(canvas);
+    node.dataset.renderVersion = String(rendered);
+    node.dataset.renderState = refusalCodeRef.current || (behind && sessionErrorCodeRef.current)
+      ? "refused"
+      : behind ? "stale" : "current";
+  }, [getCanvasVersion, getLatestSentVersions]);
+  // Re-apply after every render (the root node can change; refusals are state).
+  useEffect(() => {
+    applyRenderStamp();
+  });
+  useEffect(() => {
+    const subscribeSent = realtimeContext?.subscribeBlobSent;
+    const subscribeResult = realtimeContext?.subscribeMockupResultById;
+    if (!actualMockupId || !subscribeSent || !subscribeResult) return;
+    const offSent = subscribeSent(() => applyRenderStamp());
+    const offResult = subscribeResult(actualMockupId, (result) => {
+      if (typeof result?.requestVersion === "number" && result.requestVersion >= renderVersionRef.current) {
+        renderVersionRef.current = result.requestVersion;
+        renderVersionsRef.current = result.versions ?? null;
+      }
+      applyRenderStamp();
+    });
+    return () => {
+      offSent?.();
+      offResult?.();
+    };
+  }, [
+    actualMockupId,
+    realtimeContext?.subscribeBlobSent,
+    realtimeContext?.subscribeMockupResultById,
+    applyRenderStamp,
+  ]);
+
   // Register with priority context
   useEffect(() => {
     if (!priorityContext || !actualMockupId || !placement) return;

package/src/patterns/MockupPriorityProvider.tsx

@@ -4,9 +4,10 @@
  * MockupPriorityProvider - Priority-based mockup rendering coordinator
  *
  * Manages a 3-level priority system for mockup rendering:
- * - Level 1: Single most visible mockup (highest priority, pauses others)
- * - Level 2: Other visible/partially visible mockups
- * - Level 3: Off-screen mockups (max 5 prefetch, sorted by likelihood)
+ * - Level 1: Every mockup in view, the most visible first (one request)
+ * - Level 2: The rest of the near-view set (preload zone / carousel neighbours)
+ * - Level 3: Every other registered mockup — after an edit stops, none is
+ *            left on an older canvas version
  *
  * Architecture:
  * - Uses refs for visibility state to avoid re-renders during scroll
@@ -200,17 +201,44 @@ export function MockupPriorityProvider({ children }: MockupPriorityProviderProps
       return;
     }
 
+    // Each level is ONE request for a SET: the server renders exactly the
+    // last request's mockupIds, so a level is never split into several
+    // requests racing where the last wins.
+    //  1 — every picture actually in view (the most visible first). On a wide
+    //      gallery that is several pictures; level 1 alone was the single
+    //      largest, so the others in view stayed on the old render mid-drag.
+    //  2 — the rest of the near-view set (preload zone / carousel neighbours).
+    //  3 — EVERY other registered picture, not just the scroll prefetch: after
+    //      an edit stops, no picture may be left on an older canvas version.
+    const mobile = mobileCarouselRef.current;
+    const universe = mobile && mobile.mockupIds.length > 0
+      ? mobile.mockupIds
+      : registrationOrderRef.current;
+    const inView: string[] = [];
+    if (level1MockupRef.current) {
+      inView.push(level1MockupRef.current);
+      if (!mobile || mobile.mockupIds.length === 0) {
+        visibilityMapRef.current.forEach((info, id) => {
+          if (info.visibleArea > 0 && !inView.includes(id)) inView.push(id);
+        });
+      }
+    }
     let mockupIds: string[];
     switch (level) {
       case 1:
-        mockupIds = level1MockupRef.current ? [level1MockupRef.current] : [];
+        mockupIds = inView;
         break;
       case 2:
-        mockupIds = [...level2MockupsRef.current];
+        mockupIds = level2MockupsRef.current.filter((id) => !inView.includes(id));
         break;
-      case 3:
-        mockupIds = [...level3QueueRef.current];
+      case 3: {
+        const earlier = new Set([...inView, ...level2MockupsRef.current]);
+        mockupIds = [
+          ...level3QueueRef.current.filter((id) => !earlier.has(id)),
+          ...universe.filter((id) => !earlier.has(id) && !level3QueueRef.current.includes(id)),
+        ];
         break;
+      }
       default:
         mockupIds = [];
     }
@@ -253,6 +281,20 @@ export function MockupPriorityProvider({ children }: MockupPriorityProviderProps
         // Still dragging - stay on Level 1, don't advance to Level 2
         // The next pending blob will re-request Level 1
         currentRenderingLevelRef.current = null; // Ready for next Level 1 request
+        // ...but the edit may already be over. A fast render (the CUDA lane answers in ~10 ms) lands the LAST
+        // level-1 result inside the debounce window, and no later blob comes to re-trigger: Levels 2/3 — every
+        // other picture, the hero included when level 1 isn't it — were never re-rendered after an edit
+        // (snowcone.app, phone case, 2026-11-11). Re-check once the window closes; a new pending blob cancels it.
+        if (levelAdvanceTimeoutRef.current) {
+          clearTimeout(levelAdvanceTimeoutRef.current);
+        }
+        levelAdvanceTimeoutRef.current = setTimeout(() => {
+          levelAdvanceTimeoutRef.current = null;
+          const quiet = Date.now() - lastPendingBlobTimeRef.current >= DRAG_STOP_DEBOUNCE_MS;
+          if (quiet && currentRenderingLevelRef.current === null && pendingMockupsRef.current.size === 0) {
+            requestMockupsForLevel(2);
+          }
+        }, DRAG_STOP_DEBOUNCE_MS - timeSinceLastPendingBlob + 10);
         return;
       }
 

package/src/patterns/RealtimeProvider.tsx

@@ -62,10 +62,21 @@ const DEFAULT_ARTBOARD_SIZE = 2000;
 // Enforce a conservative cap to prevent memory crashes
 const MAX_CONCURRENT_BLOBS = 5;
 
+/** `current` in order, then any of `extra` not already in it. */
+function mergeMockupIds(current: readonly string[], extra: readonly string[]): string[] {
+  const out = [...current];
+  for (const id of extra) if (!out.includes(id)) out.push(id);
+  return out;
+}
+
 // Realtime mockup types
 export interface MockupResult {
   mockupId: string;
   imageUrl: string;
+  /** The canvas version this frame was rendered from (see getCanvasVersion). */
+  requestVersion?: number;
+  /** Per-placement versions folded into this frame (servers with per-placement stamps; see getLatestSentVersions). */
+  versions?: Record<string, number>;
 }
 
 // Type alias for backward compatibility with code that imported RealtimeState from Product
@@ -225,6 +236,21 @@ export interface RealtimeContextValue {
     callback: (placement: string) => void
   ) => () => void;
 
+  /**
+   * The canvas version the session last sent (0 before the first edit
+   * reaches the server). Every rendered result carries the `requestVersion`
+   * it was rendered from: a picture whose version is below this one shows an
+   * older design. Read it after a `subscribeBlobSent` notification.
+   */
+  getCanvasVersion: () => number;
+
+  /**
+   * The latest canvas version sent per placement. With a server that stamps
+   * `versions` on every frame, a picture is current exactly when, for every
+   * placement here, its frame's `versions[placement]` is at least this.
+   */
+  getLatestSentVersions: () => Record<string, number>;
+
   // Flush pending blobs immediately (call on mouse up, action complete, etc.)
   flushPendingBlobs: () => void;
   hasPendingBlobs: () => boolean;
@@ -433,6 +459,14 @@ 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);
+      // The box refused a `rerender` (rate limit, incomplete placements, …):
+      // force the re-render the older way so the failed pictures still update.
+      if (detail.code.startsWith("E_RERENDER_") && pendingRerenderRef.current.length > 0) {
+        const ids = pendingRerenderRef.current;
+        pendingRerenderRef.current = [];
+        forceRerenderByConfigRef.current?.(ids);
+        return;
+      }
       // A per-mockup refusal names the mockup: remember it so that card shows
       // "unavailable" while the others keep streaming.
       if (detail.mockupId) {
@@ -463,6 +497,8 @@ export function RealtimeProvider({
     flushPendingBlobs,
     hasPendingBlobs,
     getLastSentVersion,
+    getLatestSentVersions,
+    rerender: rerenderRaw,
   } = realtimeMockup;
 
   // PERFORMANCE: Store mockup results in ref only - NO STATE UPDATES
@@ -568,6 +604,26 @@ export function RealtimeProvider({
   const compositeQueueRef = useRef<Map<string, SdkMockupResult>>(new Map());
   const compositeBusyRef = useRef<Set<string>>(new Set());
   const compositeCanvasRef = useRef<HTMLCanvasElement | null>(null);
+  // The mockupIds the session renders on every edit right now: the last
+  // config's set, or the last updateMockupIds set. A full-frame fallback
+  // re-sends this set (plus the failed mockups) — it must never shrink it.
+  const requestedMockupIdsRef = useRef<string[]>([]);
+  // True once a frame carries per-placement `versions`: the box then also
+  // understands `rerender` (rendercenter rc#839 + rc#840, one roll).
+  const serverStampsVersionsRef = useRef(false);
+  // Mockups a `rerender` was sent for, until it is answered or refused.
+  const pendingRerenderRef = useRef<string[]>([]);
+  const forceRerenderByConfigRef = useRef<((failed: string[]) => void) | null>(null);
+  // Cropped frames that could not be shown, waiting for one batched
+  // full-frame re-render (see rerenderFullFrame).
+  const fullFrameRerenderIdsRef = useRef<Set<string>>(new Set());
+  const fullFrameRerenderTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(
+    () => () => {
+      if (fullFrameRerenderTimerRef.current) clearTimeout(fullFrameRerenderTimerRef.current);
+    },
+    []
+  );
 
   /**
    * Register a blob URL with lifecycle management
@@ -614,6 +670,7 @@ export function RealtimeProvider({
       const base = lastConfigBaseRef.current;
       if (!base) return;
       croppedActiveRef.current = withCrop;
+      requestedMockupIdsRef.current = (base.mockupIds as string[] | undefined) ?? [];
       sendConfigRaw({
         ...base,
         placementSettings: { ...placementSettingsOverridesRef.current },
@@ -629,6 +686,96 @@ export function RealtimeProvider({
     sendCropConfig(false);
   }, [sendCropConfig]);
 
+  /**
+   * A cropped frame could not be shown (no frozen background, or the
+   * composite failed): drop to full-frame and re-render it WITHOUT narrowing
+   * the session. The server renders exactly the last config's mockupIds, so
+   * one config per failed mockup left the session rendering only the last
+   * one — every later edit re-rendered one off-screen picture and the hero
+   * never updated (snowcone.app phone case BC43BE, 2026-11-11: five
+   * single-mockup configs in a row, last wins). Failures are batched into ONE
+   * full-frame config: everything the session was rendering plus the failed.
+   */
+  const sendFullFrameConfig = useCallback(
+    (mockupIds: string[]) => {
+      const base = lastConfigBaseRef.current;
+      if (!base) return;
+      sendConfigRaw({
+        ...base,
+        mockupIds,
+        placementSettings: { ...placementSettingsOverridesRef.current },
+      } as Parameters<typeof sendConfigRaw>[0]);
+    },
+    [sendConfigRaw]
+  );
+
+  /**
+   * Force a re-render of `failed` with configs alone (boxes without the
+   * `rerender` message, or one that refused it). The box re-renders on a
+   * config only when its render fingerprint changes, and that fingerprint
+   * ignores overlayCrop and SORTS mockupIds, so "same set, crop dropped" is no
+   * change: nothing re-renders and the failed picture stays old until the next
+   * edit (BC43BE swap, prod, 2026-11-11: hero stuck at v1, canvas v3). So: a
+   * config that differs from the one in force, then the set in force again,
+   * which differs from its predecessor and stays.
+   */
+  const forceRerenderByConfig = useCallback(
+    (failed: string[]) => {
+      const inForce = requestedMockupIdsRef.current;
+      const fp = (list: readonly string[]) => [...list].sort().join(",");
+      const step = fp(failed) !== fp(inForce) ? failed : inForce.slice(0, -1);
+      if (step.length === 0) {
+        // One mockup, already the whole session: no differing config exists.
+        // The picture keeps its stale stamp and the next edit re-renders it.
+        console.error(
+          `[RealtimeProvider] E_OVERLAY_RERENDER_UNAVAILABLE: cannot force a full-frame re-render of ${failed.join(", ")} (single-mockup session on a box without \`rerender\`); it updates on the next edit.`
+        );
+        sendFullFrameConfig(inForce);
+        return;
+      }
+      sendFullFrameConfig(step);
+      sendFullFrameConfig(inForce);
+    },
+    [sendFullFrameConfig]
+  );
+  forceRerenderByConfigRef.current = forceRerenderByConfig;
+
+  const rerenderFullFrame = useCallback(
+    (mockupId: string) => {
+      fullFrameRerenderIdsRef.current.add(mockupId);
+      if (fullFrameRerenderTimerRef.current) return;
+      fullFrameRerenderTimerRef.current = setTimeout(() => {
+        fullFrameRerenderTimerRef.current = null;
+        const failed = [...fullFrameRerenderIdsRef.current];
+        fullFrameRerenderIdsRef.current.clear();
+        if (!lastConfigBaseRef.current || failed.length === 0) return;
+        const previous = requestedMockupIdsRef.current;
+        const ids = mergeMockupIds(previous, failed);
+        croppedActiveRef.current = false;
+        requestedMockupIdsRef.current = ids;
+        const fp = (list: readonly string[]) => [...list].sort().join(",");
+        if (fp(ids) !== fp(previous)) {
+          // A wider set: the config itself is a render-relevant change, and it
+          // re-renders every picture full-frame.
+          sendFullFrameConfig(ids);
+          return;
+        }
+        if (serverStampsVersionsRef.current) {
+          // The box has `rerender` (rc#840, same roll as the versions stamp
+          // seen on its frames): drop the crop (no render by itself), then ask
+          // for exactly the failed pictures. A refusal (E_RERENDER_*) falls
+          // back to the config way (see onError).
+          sendFullFrameConfig(ids);
+          pendingRerenderRef.current = failed;
+          if (rerenderRaw(failed)) return;
+          pendingRerenderRef.current = [];
+        }
+        forceRerenderByConfig(failed);
+      }, 0);
+    },
+    [sendFullFrameConfig, forceRerenderByConfig, rerenderRaw]
+  );
+
   /** Flip to cropped delivery once every configured mockup has a frozen
    *  background (a cropped frame can't seed one). */
   const maybeFlipCrop = useCallback(() => {
@@ -674,6 +821,10 @@ export function RealtimeProvider({
         else merged.push(result);
       });
       mockupResultsRef.current = merged;
+      if (pendingRerenderRef.current.length > 0) {
+        const delivered = new Set(results.map((r) => r.mockupId));
+        pendingRerenderRef.current = pendingRerenderRef.current.filter((id) => !delivered.has(id));
+      }
 
       const clearedPlacements = new Set<string>();
       results.forEach((result) => {
@@ -759,8 +910,7 @@ export function RealtimeProvider({
         console.error(
           `[RealtimeProvider] E_OVERLAY_NO_BACKGROUND: cropped frame for ${result.mockupId} has no frozen background — falling back to full-frame and re-rendering it.`
         );
-        unflipCrop();
-        updateMockupIdsRaw([result.mockupId]);
+        rerenderFullFrame(result.mockupId);
         return;
       }
       try {
@@ -779,17 +929,30 @@ export function RealtimeProvider({
         if (gen !== sceneGenRef.current) return;
         deliverResults([{ ...result, imageUrl: registerBlobUrl(blob) }]);
       } catch (err) {
+        // A newer frame for this mockup already arrived: the SDK revokes a
+        // mockup's previous blob: frame the moment the next one lands, so a
+        // composite still loading the old frame fails mid-drag. That is
+        // supersession, not a broken pipeline — the newer frame composites
+        // next (latest wins). Treating it as a failure killed cropped delivery
+        // and re-requested the stale mockup (BC43BE trace, 2026-11-11: five v3
+        // composites failed as v4 arrived 0.6 s later).
+        if (
+          gen !== sceneGenRef.current ||
+          compositeQueueRef.current.has(result.mockupId) ||
+          processedFrameRef.current.get(result.mockupId) !== result.imageUrl
+        ) {
+          return;
+        }
         console.error(
           "[RealtimeProvider] E_OVERLAY_COMPOSITE_FAILED: cropped-frame composite failed — full-frame delivery for the rest of this session.",
           err
         );
         cropCapableRef.current = false;
-        unflipCrop();
         // Re-render the affected mockup full-frame so this edit isn't lost.
-        updateMockupIdsRaw([result.mockupId]);
+        rerenderFullFrame(result.mockupId);
       }
     },
-    [deliverResults, registerBlobUrl, unflipCrop, updateMockupIdsRaw]
+    [deliverResults, registerBlobUrl, rerenderFullFrame]
   );
 
   /** Serial per-mockup composite pump (latest-wins). */
@@ -824,6 +987,9 @@ export function RealtimeProvider({
     console.log(`[RTP] rawMockupResults changed: ${rawMockupResults.length} result(s)`, rawMockupResults.map(r => `${r.mockupId}${r.imageUrl ? ' ✓url' : ' ✗NO-URL'}${r.cropRect ? ' [crop]' : ''}`));
 
     const displayable: SdkMockupResult[] = [];
+    if (!serverStampsVersionsRef.current && rawMockupResults.some((r) => r.versions && typeof r.versions === "object")) {
+      serverStampsVersionsRef.current = true;
+    }
     rawMockupResults.forEach((result) => {
       if (!result.imageUrl) {
         console.log(`[RTP] Result for ${result.mockupId} has NO imageUrl — not caching, pending NOT cleared`);
@@ -1068,6 +1234,7 @@ export function RealtimeProvider({
     // send — preserving cropped delivery across re-sends that kept the scene
     // (e.g. spread-crop changes).
     lastConfigBaseRef.current = configPayload as unknown as Record<string, unknown>;
+    requestedMockupIdsRef.current = mockupIds;
     sendConfigRaw(
       (croppedActiveRef.current
         ? { ...configPayload, overlayCrop: "auto" as const }
@@ -1147,6 +1314,7 @@ export function RealtimeProvider({
       ) {
         unflipCrop();
       }
+      requestedMockupIdsRef.current = [...mockupIds];
       return updateMockupIdsRaw(mockupIds);
     },
     [updateMockupIdsRaw, unflipCrop]
@@ -1495,6 +1663,13 @@ export function RealtimeProvider({
     []
   );
 
+  const getLastSentVersionRef = useRef(getLastSentVersion);
+  getLastSentVersionRef.current = getLastSentVersion;
+  const getCanvasVersion = useCallback(() => getLastSentVersionRef.current?.() ?? 0, []);
+  const getLatestSentVersionsRef = useRef(getLatestSentVersions);
+  getLatestSentVersionsRef.current = getLatestSentVersions;
+  const getLatestSentVersionsStable = useCallback(() => getLatestSentVersionsRef.current?.() ?? {}, []);
+
   const stableSubscribePipelineSettled = useCallback(
     (callback: () => void) => {
       return subscribePipelineSettledRef.current(callback);
@@ -1547,6 +1722,8 @@ export function RealtimeProvider({
       // Centralized URL management
       getMockupUrl,
       getMockupUrls,
+      getCanvasVersion,
+      getLatestSentVersions: getLatestSentVersionsStable,
       isMockupLoading,
       registerBlobUrl,
       // WebRTC streaming
@@ -1578,6 +1755,8 @@ export function RealtimeProvider({
       hasPendingBlobs,
       getMockupUrl,
       getMockupUrls,
+      getCanvasVersion,
+      getLatestSentVersionsStable,
       isMockupLoading,
       registerBlobUrl,
     ]

package/src/patterns/__tests__/MockupPriorityProvider.dragStop.test.tsx

@@ -0,0 +1,112 @@
+/**
+ * After an edit, every picture re-renders — not only level 1 (snowcone.app phone case, 2026-11-11).
+ *
+ * The CUDA lane answers a level-1 render in ~10 ms, so the LAST level-1 result of an edit lands inside the 250 ms
+ * drag-stop window. The provider used to treat that as "still dragging" and wait for the next blob to re-trigger —
+ * but after the last edit none comes, so levels 2/3 (the other pictures; the hero, whenever level 1 wasn't it) were
+ * never requested again: the editor "updated" and the pictures stayed old.
+ */
+import { describe, expect, it, beforeEach, afterEach, vi } from "vitest";
+import React, { useEffect } from "react";
+import { render, act, cleanup } from "@testing-library/react";
+
+const rt = vi.hoisted(() => ({
+  updateMockupIds: vi.fn((_ids: string[]) => true),
+  results: new Set<(r: Array<{ mockupId: string }>) => void>(),
+  pending: new Set<(placement: string) => void>(),
+  sent: new Set<(placement: string) => void>(),
+}));
+
+vi.mock("../RealtimeProvider", () => ({
+  useRealtimeOptional: () => ({
+    isConfigured: true,
+    updateMockupIds: rt.updateMockupIds,
+    subscribeMockupResults: (cb: (r: Array<{ mockupId: string }>) => void) => { rt.results.add(cb); return () => rt.results.delete(cb); },
+    subscribePendingBlob: (cb: (p: string) => void) => { rt.pending.add(cb); return () => rt.pending.delete(cb); },
+    subscribeBlobSent: (cb: (p: string) => void) => { rt.sent.add(cb); return () => rt.sent.delete(cb); },
+  }),
+}));
+
+const { MockupPriorityProvider, useMockupPriority } = await import("../MockupPriorityProvider");
+
+const IDS = ["HERO", "SECOND", "THIRD", "FOURTH"];
+function Carousel() {
+  const p = useMockupPriority();
+  useEffect(() => { p.reportMobileCarouselIndex(0, IDS); }, [p]);
+  return null;
+}
+const edit = () => { rt.pending.forEach((cb) => cb("Front")); rt.sent.forEach((cb) => cb("Front")); };
+const rendered = (ids: string[]) => rt.results.forEach((cb) => cb(ids.map((mockupId) => ({ mockupId }))));
+const lastRequest = () => rt.updateMockupIds.mock.calls.at(-1)?.[0];
+
+describe("MockupPriorityProvider: the pictures catch up after the last edit", () => {
+  beforeEach(() => { vi.useFakeTimers(); rt.updateMockupIds.mockClear(); });
+  afterEach(() => { cleanup(); vi.useRealTimers(); });
+
+  it("a level-1 result inside the drag window still leads to levels 2 and 3 once the edit stops", async () => {
+    render(<MockupPriorityProvider><Carousel /></MockupPriorityProvider>);
+    await act(async () => { vi.advanceTimersByTime(100); });
+    rt.updateMockupIds.mockClear();
+
+    // the last edit: blob sent → level 1 requested → its render lands 10 ms later (inside the 250 ms window)
+    await act(async () => { edit(); });
+    expect(lastRequest()).toEqual(["HERO"]);
+    await act(async () => { vi.advanceTimersByTime(10); rendered(["HERO"]); });
+    expect(lastRequest()).toEqual(["HERO"]); // still in the window: nothing more yet
+
+    // the window closes with no further edit → level 2 (the neighbour), then level 3 (the rest)
+    await act(async () => { vi.advanceTimersByTime(260); });
+    expect(lastRequest()).toEqual(["SECOND"]);
+    await act(async () => { rendered(["SECOND"]); });
+    expect(lastRequest()).toEqual(["THIRD", "FOURTH"]);
+  });
+
+  it("a further edit inside the window cancels the catch-up (level 1 is re-requested instead)", async () => {
+    render(<MockupPriorityProvider><Carousel /></MockupPriorityProvider>);
+    await act(async () => { vi.advanceTimersByTime(100); });
+    await act(async () => { edit(); vi.advanceTimersByTime(10); rendered(["HERO"]); });
+    rt.updateMockupIds.mockClear();
+    await act(async () => { vi.advanceTimersByTime(100); edit(); }); // the drag goes on
+    expect(lastRequest()).toEqual(["HERO"]);
+    await act(async () => { vi.advanceTimersByTime(200); });
+    expect(rt.updateMockupIds.mock.calls.every((c) => (c[0] as string[]).includes("HERO"))).toBe(true); // no level 2 mid-drag
+  });
+
+  it("desktop: the drag renders every picture in view in ONE request, and the catch-up reaches every registered picture", async () => {
+    // A wide gallery: HERO and SECOND in view, THIRD in the preload zone,
+    // seven more far below. Level 3 used to stop at 5 prefetches.
+    const ids = ["HERO", "SECOND", "THIRD", ...Array.from({ length: 7 }, (_, i) => `FAR${i}`)];
+    const rect = (top: number) => ({ top, bottom: top + 400, left: 0, right: 500, width: 500, height: 400, x: 0, y: top, toJSON: () => ({}) }) as DOMRect;
+    const tops: Record<string, number> = { HERO: 0, SECOND: 300, THIRD: 900 };
+    ids.forEach((id, i) => { if (!(id in tops)) tops[id] = 3000 + i * 500; });
+    function Gallery() {
+      const p = useMockupPriority();
+      useEffect(() => {
+        ids.forEach((id) => {
+          const el = document.createElement("div");
+          el.getBoundingClientRect = () => rect(tops[id]);
+          p.registerMockup(id, "Front", undefined, el);
+          p.updateElementRef(id, el);
+        });
+      }, [p]);
+      return null;
+    }
+    render(<MockupPriorityProvider><Gallery /></MockupPriorityProvider>);
+    await act(async () => { vi.advanceTimersByTime(200); });
+    rt.updateMockupIds.mockClear();
+
+    await act(async () => { edit(); });
+    expect(rt.updateMockupIds).toHaveBeenCalledTimes(1); // one request, not one per picture
+    expect(lastRequest()).toEqual(["HERO", "SECOND"]);
+
+    await act(async () => { vi.advanceTimersByTime(10); rendered(["HERO", "SECOND"]); });
+    await act(async () => { vi.advanceTimersByTime(260); });
+    expect(lastRequest()).toEqual(["THIRD"]);
+    await act(async () => { rendered(["THIRD"]); });
+    expect([...(lastRequest() ?? [])].sort()).toEqual(ids.filter((id) => id.startsWith("FAR")).sort());
+
+    const requested = new Set(rt.updateMockupIds.mock.calls.flatMap((c) => c[0] as string[]));
+    expect([...requested].sort()).toEqual([...ids].sort());
+  });
+});
+