@snowcone-app/ui 0.9.1 → 0.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/ui",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "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.3"
+    "@snowcone-app/sdk": "0.24.4"
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^4.1.2",

package/src/composed/ArtworkCustomizer.tsx

@@ -65,7 +65,7 @@ export type ArtworkCustomizerProps = {
  * // CORRECT: Use with ArtSelector to manage artwork via context
  * import { Product, ArtSelector, ArtworkCustomizer } from '@snowcone-app/ui';
  *
- * <Product productId="BEEB77">
+ * <Product productId="BC43BE">
  *   <ArtSelector artworks={[
  *     { type: 'regular', src: 'https://example.com/photo.jpg' },
  *     { type: 'pattern', src: 'https://example.com/pattern.jpg', tileCount: 1 }
@@ -79,7 +79,7 @@ export type ArtworkCustomizerProps = {
  * // CORRECT: Full example with ProductImage
  * import { Product, ProductImage, ArtSelector, ArtworkCustomizer } from '@snowcone-app/ui';
  *
- * <Product productId="BEEB77">
+ * <Product productId="BC43BE">
  *   <div className="grid grid-cols-2 gap-8">
  *     <ProductImage />
  *     <div>

package/src/composed/CurrentSelectionDisplay.tsx

@@ -36,7 +36,7 @@ export interface CurrentSelectionDisplayProps {
  * ```tsx
  * import { Product, ProductOptions, CurrentSelectionDisplay } from '@yourorg/ui-react';
  *
- * <Product productId="BEEB77">
+ * <Product productId="BC43BE">
  *   <ProductOptions />
  *   <CurrentSelectionDisplay />
  * </Product>

package/src/composed/HeroProductImage.tsx

@@ -545,6 +545,65 @@ 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);
+  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;
+    const behind = 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]);
+  // 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;
+      }
+      applyRenderStamp();
+    });
+    return () => {
+      offSent?.();
+      offResult?.();
+    };
+  }, [
+    actualMockupId,
+    realtimeContext?.subscribeBlobSent,
+    realtimeContext?.subscribeMockupResultById,
+    applyRenderStamp,
+  ]);
+
   // Register with priority context
   useEffect(() => {
     if (!priorityContext || !actualMockupId || !placement) return;

package/src/composed/ProductGallery.tsx

@@ -23,7 +23,7 @@ export interface ProductGalleryProps extends UseProductGalleryOptions {
  * 2. List all products: Pass empty array or omit productIds
  *
  * @example Specific products
- * <ProductGallery productIds={["BEEB77", "CAXHQC", "KMYKUK"]}>
+ * <ProductGallery productIds={["BC43BE", "CAXHQC", "XTNA6J"]}>
  *   {(products, loading, error) => (
  *     <div className="grid grid-cols-3 gap-4">
  *       {products.map(product => (

package/src/hooks/useProductGallery.ts

@@ -49,7 +49,7 @@ export interface UseProductGalleryReturn {
  * ```tsx
  * // Fetch specific products
  * const { products, loading, error, refetch } = useProductGallery(
- *   ['BEEB77', 'CAXHQC'],
+ *   ['BC43BE', 'CAXHQC'],
  *   { endpoint: 'http://localhost:3000', mode: 'mock' }
  * );
  *

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,19 @@ 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;
 }
 
 // Type alias for backward compatibility with code that imported RealtimeState from Product
@@ -225,6 +234,14 @@ 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;
+
   // Flush pending blobs immediately (call on mouse up, action complete, etc.)
   flushPendingBlobs: () => void;
   hasPendingBlobs: () => boolean;
@@ -568,6 +585,20 @@ 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[]>([]);
+  // 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 +645,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 +661,72 @@ 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 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();
+        const base = lastConfigBaseRef.current;
+        if (!base || failed.length === 0) return;
+        const previous = requestedMockupIdsRef.current;
+        const ids = mergeMockupIds(previous, failed);
+        croppedActiveRef.current = false;
+        requestedMockupIdsRef.current = ids;
+        const send = (mockupIds: string[]) =>
+          sendConfigRaw({
+            ...base,
+            mockupIds,
+            placementSettings: { ...placementSettingsOverridesRef.current },
+          } as Parameters<typeof sendConfigRaw>[0]);
+        // The box re-renders on a config only when its render fingerprint
+        // changes, and that fingerprint deliberately ignores overlayCrop and
+        // SORTS mockupIds. Dropping the crop with the same set is "no change":
+        // nothing re-renders and the failed picture stays on its old render
+        // until the next edit (BC43BE swap, prod, 2026-11-11: hero stuck at
+        // v1 while the canvas reached v3). So the re-render is forced with a
+        // config that differs from the one before it, then the full set,
+        // which also differs from its predecessor and is the one that stays
+        // in force.
+        // TODO(lane-editor): this is a trick on the fingerprint. Replace it
+        // with the box's explicit "re-render these mockups now" request
+        // (asked of lane-rc-dof with the realtime-versions change) as soon as
+        // the fleet has it.
+        const fingerprint = (list: readonly string[]) => [...list].sort().join(",");
+        if (fingerprint(ids) !== fingerprint(previous)) {
+          send(ids);
+          return;
+        }
+        const step = fingerprint(failed) !== fingerprint(previous) ? failed : ids.slice(0, -1);
+        if (step.length === 0) {
+          // One mockup, already the whole session: no differing config exists.
+          // The picture keeps its stale stamp (data-render-state="stale") 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); it updates on the next edit.`
+          );
+          send(ids);
+          return;
+        }
+        send(step);
+        send(ids);
+      }, 0);
+    },
+    [sendConfigRaw]
+  );
+
   /** Flip to cropped delivery once every configured mockup has a frozen
    *  background (a cropped frame can't seed one). */
   const maybeFlipCrop = useCallback(() => {
@@ -759,8 +857,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 +876,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). */
@@ -1068,6 +1178,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 +1258,7 @@ export function RealtimeProvider({
       ) {
         unflipCrop();
       }
+      requestedMockupIdsRef.current = [...mockupIds];
       return updateMockupIdsRaw(mockupIds);
     },
     [updateMockupIdsRaw, unflipCrop]
@@ -1495,6 +1607,10 @@ export function RealtimeProvider({
     []
   );
 
+  const getLastSentVersionRef = useRef(getLastSentVersion);
+  getLastSentVersionRef.current = getLastSentVersion;
+  const getCanvasVersion = useCallback(() => getLastSentVersionRef.current?.() ?? 0, []);
+
   const stableSubscribePipelineSettled = useCallback(
     (callback: () => void) => {
       return subscribePipelineSettledRef.current(callback);
@@ -1547,6 +1663,7 @@ export function RealtimeProvider({
       // Centralized URL management
       getMockupUrl,
       getMockupUrls,
+      getCanvasVersion,
       isMockupLoading,
       registerBlobUrl,
       // WebRTC streaming
@@ -1578,6 +1695,7 @@ export function RealtimeProvider({
       hasPendingBlobs,
       getMockupUrl,
       getMockupUrls,
+      getCanvasVersion,
       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());
+  });
+});
+