@snowcone-app/ui 0.9.3 → 0.9.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/ui",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "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

@@ -555,6 +555,9 @@ export const HeroProductImage = memo(function HeroProductImage({
   // 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);
@@ -571,13 +574,20 @@ export const HeroProductImage = memo(function HeroProductImage({
       return;
     }
     const rendered = renderVersionRef.current;
-    const behind = rendered < canvas;
+    // 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]);
+  }, [getCanvasVersion, getLatestSentVersions]);
   // Re-apply after every render (the root node can change; refusals are state).
   useEffect(() => {
     applyRenderStamp();
@@ -588,8 +598,9 @@ export const HeroProductImage = memo(function HeroProductImage({
     if (!actualMockupId || !subscribeSent || !subscribeResult) return;
     const offSent = subscribeSent(() => applyRenderStamp());
     const offResult = subscribeResult(actualMockupId, (result) => {
-      if (typeof result?.requestVersion === "number" && result.requestVersion > renderVersionRef.current) {
+      if (typeof result?.requestVersion === "number" && result.requestVersion >= renderVersionRef.current) {
         renderVersionRef.current = result.requestVersion;
+        renderVersionsRef.current = result.versions ?? null;
       }
       applyRenderStamp();
     });

package/src/patterns/RealtimeProvider.tsx

@@ -62,6 +62,9 @@ const DEFAULT_ARTBOARD_SIZE = 2000;
 // Enforce a conservative cap to prevent memory crashes
 const MAX_CONCURRENT_BLOBS = 5;
 
+/** How long a frame whose blob: URL was revoked waits for its newer frame before counting as a real failure. */
+const FRAME_SUPERSEDE_GRACE_MS = 2000;
+
 /** `current` in order, then any of `extra` not already in it. */
 function mergeMockupIds(current: readonly string[], extra: readonly string[]): string[] {
   const out = [...current];
@@ -75,6 +78,8 @@ export interface MockupResult {
   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
@@ -242,6 +247,13 @@ export interface RealtimeContextValue {
    */
   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;
@@ -450,6 +462,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) {
@@ -480,6 +500,8 @@ export function RealtimeProvider({
     flushPendingBlobs,
     hasPendingBlobs,
     getLastSentVersion,
+    getLatestSentVersions,
+    rerender: rerenderRaw,
   } = realtimeMockup;
 
   // PERFORMANCE: Store mockup results in ref only - NO STATE UPDATES
@@ -589,6 +611,12 @@ export function RealtimeProvider({
   // 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());
@@ -671,6 +699,50 @@ export function RealtimeProvider({
    * 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);
@@ -679,52 +751,32 @@ export function RealtimeProvider({
         fullFrameRerenderTimerRef.current = null;
         const failed = [...fullFrameRerenderIdsRef.current];
         fullFrameRerenderIdsRef.current.clear();
-        const base = lastConfigBaseRef.current;
-        if (!base || failed.length === 0) return;
+        if (!lastConfigBaseRef.current || 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);
+        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;
         }
-        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;
+        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 = [];
         }
-        send(step);
-        send(ids);
+        forceRerenderByConfig(failed);
       }, 0);
     },
-    [sendConfigRaw]
+    [sendFullFrameConfig, forceRerenderByConfig, rerenderRaw]
   );
 
   /** Flip to cropped delivery once every configured mockup has a frozen
@@ -772,6 +824,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) => {
@@ -890,6 +946,32 @@ export function RealtimeProvider({
         ) {
           return;
         }
+        // The FRAME (not the background) failed to load from a revoked blob:
+        // URL. The SDK revokes a mockup's frame only when that mockup's next
+        // frame arrives, so the newer frame exists even if React state hasn't
+        // delivered it here yet (prod 2026-11-11, phone: this race switched
+        // cropped delivery off for the whole session). Wait for it; if none
+        // shows up, it really failed.
+        const message = err instanceof Error ? err.message : String(err);
+        if (
+          result.imageUrl.startsWith("blob:") &&
+          message.startsWith("E_OVERLAY_FRAME_LOAD") &&
+          message.includes(result.imageUrl.slice(0, 160))
+        ) {
+          const failedUrl = result.imageUrl;
+          setTimeout(() => {
+            if (gen !== sceneGenRef.current) return;
+            if (compositeQueueRef.current.has(result.mockupId)) return;
+            if (processedFrameRef.current.get(result.mockupId) !== failedUrl) return;
+            console.error(
+              `[RealtimeProvider] E_OVERLAY_COMPOSITE_FAILED: frame for ${result.mockupId} failed to load and no newer frame arrived within ${FRAME_SUPERSEDE_GRACE_MS} ms — full-frame delivery for the rest of this session.`,
+              err
+            );
+            cropCapableRef.current = false;
+            rerenderFullFrame(result.mockupId);
+          }, FRAME_SUPERSEDE_GRACE_MS);
+          return;
+        }
         console.error(
           "[RealtimeProvider] E_OVERLAY_COMPOSITE_FAILED: cropped-frame composite failed — full-frame delivery for the rest of this session.",
           err
@@ -934,6 +1016,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`);
@@ -1610,6 +1695,9 @@ 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) => {
@@ -1664,6 +1752,7 @@ export function RealtimeProvider({
       getMockupUrl,
       getMockupUrls,
       getCanvasVersion,
+      getLatestSentVersions: getLatestSentVersionsStable,
       isMockupLoading,
       registerBlobUrl,
       // WebRTC streaming
@@ -1696,6 +1785,7 @@ export function RealtimeProvider({
       getMockupUrl,
       getMockupUrls,
       getCanvasVersion,
+      getLatestSentVersionsStable,
       isMockupLoading,
       registerBlobUrl,
     ]

package/src/patterns/__tests__/RealtimeProvider.cropDelivery.test.tsx

@@ -40,11 +40,17 @@ const h = vi.hoisted(() => {
     disconnect: vi.fn(),
     flushPendingBlobs: vi.fn(),
     hasPendingBlobs: vi.fn(() => false),
+    getLastSentVersion: vi.fn(() => 0),
+    getLatestSentVersions: vi.fn(() => ({})),
+    rerender: vi.fn((_ids: string[]) => true),
+    opts: null as null | { onError?: (msg: string, detail: Record<string, unknown>) => void },
   };
 });
 
 vi.mock("@snowcone-app/sdk/react", () => ({
-  useRealtimeMockup: () => ({
+  useRealtimeMockup: (opts: unknown) => {
+    h.opts = opts as typeof h.opts;
+    return {
     isConnected: true,
     isConfigured: true,
     renderError: null,
@@ -59,7 +65,11 @@ vi.mock("@snowcone-app/sdk/react", () => ({
     disconnect: h.disconnect,
     flushPendingBlobs: h.flushPendingBlobs,
     hasPendingBlobs: h.hasPendingBlobs,
-  }),
+    getLastSentVersion: h.getLastSentVersion,
+    getLatestSentVersions: h.getLatestSentVersions,
+    rerender: h.rerender,
+  };
+  },
 }));
 
 vi.mock("@snowcone-app/sdk", () => ({
@@ -359,4 +369,89 @@ describe("RealtimeProvider cropped delivery", () => {
     });
     expect(h.sendConfig).not.toHaveBeenCalled();
   });
+
+  it("with a box that stamps per-placement versions, a failed composite asks `rerender` for exactly that picture (no config trick)", async () => {
+    const { rerender } = render(<Harness version={1} />);
+    await waitFor(() => expect(h.sendConfig).toHaveBeenCalled());
+    // Seed with frames that carry versions: the box has rc#839/#840.
+    const v = { versions: { Front: 1 } };
+    h.state.results = [{ ...fullResult("m1", "https://r/m1-full"), ...v }];
+    await act(async () => rerender(<Harness version={2} />));
+    h.state.results = [{ ...fullResult("m1", "https://r/m1-full"), ...v }, { ...fullResult("m2", "https://r/m2-full"), ...v }];
+    await act(async () => rerender(<Harness version={3} />));
+    await waitFor(() => expect(sentConfigs().some((c) => c.overlayCrop === "auto")).toBe(true));
+    h.sendConfig.mockClear();
+
+    h.compositeCroppedFrame.mockRejectedValue(new Error("E_OVERLAY_ENCODE_FAILED"));
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    h.state.results = [croppedResult("m1", "https://r/m1-crop")];
+    await act(async () => rerender(<Harness version={4} />));
+    await waitFor(() => expect(h.rerender).toHaveBeenCalledWith(["m1"]));
+    // One config (crop dropped, same set), never an intermediate narrower one.
+    expect(sentConfigs().map((c) => c.mockupIds)).toEqual([["m1", "m2"]]);
+    expect(sentConfigs()[0].overlayCrop).toBeUndefined();
+
+    // The box refuses (rate limit): fall back to the config way for the same picture.
+    h.sendConfig.mockClear();
+    await act(async () => {
+      h.opts!.onError!("rate limited", { code: "E_RERENDER_RATE_LIMITED", message: "rate limited" });
+    });
+    expect(sentConfigs().map((c) => c.mockupIds)).toEqual([["m1"], ["m1", "m2"]]);
+    errSpy.mockRestore();
+  });
+
+  it("with a box that has no versions stamp, `rerender` is never sent (it would not understand it)", async () => {
+    const { rerender } = render(<Harness version={1} />);
+    await waitFor(() => expect(h.sendConfig).toHaveBeenCalled());
+    await seedAndFlip(rerender);
+    h.compositeCroppedFrame.mockRejectedValue(new Error("E_OVERLAY_ENCODE_FAILED"));
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    h.state.results = [croppedResult("m1", "https://r/m1-crop")];
+    await act(async () => rerender(<Harness version={4} />));
+    await waitFor(() => expect(sentConfigs().at(-1)?.mockupIds).toEqual(["m1", "m2"]));
+    expect(h.rerender).not.toHaveBeenCalled();
+    errSpy.mockRestore();
+  });
+
+  it("a frame whose blob: URL was revoked waits for its newer frame instead of switching the session to full frames (prod, phone, 2026-11-11)", async () => {
+    const { rerender } = render(<Harness version={1} />);
+    await waitFor(() => expect(h.sendConfig).toHaveBeenCalled());
+    await seedAndFlip(rerender);
+    h.sendConfig.mockClear();
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    // v3's frame was revoked by the SDK (its v4 already arrived there) before React state delivered v4 here.
+    h.compositeCroppedFrame.mockImplementationOnce(() =>
+      Promise.reject(new Error("E_OVERLAY_FRAME_LOAD: image failed to load: blob:v3-m1"))
+    );
+    h.state.results = [croppedResult("m1", "blob:v3-m1"), fullResult("m2", "https://r/m2-full")];
+    await act(async () => rerender(<Harness version={4} />));
+    // v4 lands within the grace window and composites.
+    h.state.results = [croppedResult("m1", "blob:v4-m1"), fullResult("m2", "https://r/m2-full")];
+    await act(async () => rerender(<Harness version={5} />));
+    await act(async () => { await new Promise((r) => setTimeout(r, 2300)); });
+    expect(h.compositeCroppedFrame).toHaveBeenLastCalledWith(expect.objectContaining({ frameUrl: "blob:v4-m1" }));
+    expect(h.sendConfig).not.toHaveBeenCalled(); // cropped delivery stays on, nothing re-rendered
+    errSpy.mockRestore();
+  });
+
+  it("a revoked frame with no newer frame within the grace window is a real failure: full-frame re-render", async () => {
+    const { rerender } = render(<Harness version={1} />);
+    await waitFor(() => expect(h.sendConfig).toHaveBeenCalled());
+    await seedAndFlip(rerender);
+    h.sendConfig.mockClear();
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    h.compositeCroppedFrame.mockImplementationOnce(() =>
+      Promise.reject(new Error("E_OVERLAY_FRAME_LOAD: image failed to load: blob:v3-m1"))
+    );
+    h.state.results = [croppedResult("m1", "blob:v3-m1"), fullResult("m2", "https://r/m2-full")];
+    await act(async () => rerender(<Harness version={4} />));
+    await act(async () => { await new Promise((r) => setTimeout(r, 200)); });
+    expect(h.sendConfig).not.toHaveBeenCalled(); // still inside the grace window
+    await act(async () => { await new Promise((r) => setTimeout(r, 2100)); });
+    await waitFor(() => expect(sentConfigs().at(-1)?.mockupIds).toEqual(["m1", "m2"]));
+    expect(sentConfigs().every((c) => c.overlayCrop === undefined)).toBe(true);
+    errSpy.mockRestore();
+  });
 });
+