@snowcone-app/ui 0.4.9 → 0.4.11

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

@@ -0,0 +1,261 @@
+/**
+ * Cropped-frame delivery state machine (RealtimeProvider internals).
+ *
+ * The sdk hook and the composite engine are mocked; these tests pin the
+ * provider's money-path invariants:
+ *  - the session flips to overlayCrop:'auto' only after EVERY configured
+ *    mockup has a frozen full-frame background
+ *  - cropped frames are composited and consumers only ever see full-frame
+ *    URLs (blob: URLs from the composite)
+ *  - any composite failure falls back to full-frame delivery for the session
+ *    and re-renders the affected mockup so the edit isn't lost
+ *  - priority requests for never-rendered mockups drop the session back to
+ *    full-frame before rendering
+ */
+import { describe, expect, it, beforeEach, vi } from "vitest";
+import React from "react";
+import { render, waitFor, act } from "@testing-library/react";
+import {
+  RealtimeProvider,
+  useRealtime,
+  type RealtimeContextValue,
+} from "../RealtimeProvider";
+
+const h = vi.hoisted(() => {
+  return {
+    state: {
+      results: [] as Array<Record<string, unknown>>,
+    },
+    sendConfig: vi.fn(),
+    updateMockupIds: vi.fn(),
+    compositeCroppedFrame: vi.fn(),
+    loadImageElement: vi.fn(),
+    // Stable identities across renders — the real hook returns stable
+    // callbacks; fresh fns per render would churn the provider's effects.
+    sendCanvasBlob: vi.fn(),
+    sendCanvasState: vi.fn(),
+    sendColorBlob: vi.fn(),
+    updatePlacementSettings: vi.fn(),
+    connect: vi.fn(),
+    disconnect: vi.fn(),
+    flushPendingBlobs: vi.fn(),
+    hasPendingBlobs: vi.fn(() => false),
+  };
+});
+
+vi.mock("@snowcone-app/sdk/react", () => ({
+  useRealtimeMockup: () => ({
+    isConnected: true,
+    isConfigured: true,
+    renderError: null,
+    mockupResults: h.state.results,
+    sendCanvasBlob: h.sendCanvasBlob,
+    sendCanvasState: h.sendCanvasState,
+    sendColorBlob: h.sendColorBlob,
+    sendConfig: h.sendConfig,
+    updateMockupIds: h.updateMockupIds,
+    updatePlacementSettings: h.updatePlacementSettings,
+    connect: h.connect,
+    disconnect: h.disconnect,
+    flushPendingBlobs: h.flushPendingBlobs,
+    hasPendingBlobs: h.hasPendingBlobs,
+  }),
+}));
+
+vi.mock("@snowcone-app/sdk", () => ({
+  resolveVariantId: () => "gv1",
+}));
+
+vi.mock("../Product", () => {
+  const product = {
+    id: "prod1",
+    placements: [{ label: "Front", type: "image" }],
+    mockups: [{ id: "m1" }, { id: "m2" }],
+  };
+  return {
+    useProductOptional: () => ({ product, selection: {} }),
+  };
+});
+
+vi.mock("../MockupBackground", () => ({
+  useMockupBackgroundOptional: () => undefined,
+}));
+
+vi.mock("../croppedFrameComposite", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../croppedFrameComposite")>();
+  return {
+    ...actual,
+    compositeCroppedFrame: h.compositeCroppedFrame,
+    loadImageElement: h.loadImageElement,
+  };
+});
+
+let capturedCtx: RealtimeContextValue;
+function Capture() {
+  capturedCtx = useRealtime();
+  return null;
+}
+
+function Harness({ version }: { version: number }) {
+  void version; // re-render trigger — the mocked hook returns h.state.results
+  return (
+    <RealtimeProvider autoEnable>
+      <Capture />
+    </RealtimeProvider>
+  );
+}
+
+function fullResult(mockupId: string, url: string) {
+  return { mockupId, imageUrl: url, renderUrl: url, imageSize: 1000, placement: "Front" };
+}
+
+function croppedResult(mockupId: string, url: string) {
+  return {
+    ...fullResult(mockupId, url),
+    cropRect: { x: 0.2, y: 0.1, w: 0.5, h: 0.6 },
+  };
+}
+
+/** sendConfig payloads observed since the last mock reset. */
+function sentConfigs(): Array<Record<string, unknown>> {
+  return h.sendConfig.mock.calls.map((c) => c[0] as Record<string, unknown>);
+}
+
+let blobCounter = 0;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  h.state.results = [];
+  blobCounter = 0;
+  h.loadImageElement.mockResolvedValue({ naturalWidth: 1400, naturalHeight: 782 });
+  h.compositeCroppedFrame.mockResolvedValue(new Blob(["x"], { type: "image/webp" }));
+  // jsdom has no createObjectURL
+  globalThis.URL.createObjectURL = vi.fn(() => `blob:composite-${++blobCounter}`);
+  globalThis.URL.revokeObjectURL = vi.fn();
+});
+
+async function seedAndFlip(rerender: (ui: React.ReactElement) => void) {
+  h.state.results = [fullResult("m1", "https://r/m1-full")];
+  await act(async () => rerender(<Harness version={2} />));
+  expect(sentConfigs().some((c) => c.overlayCrop)).toBe(false);
+
+  h.state.results = [
+    fullResult("m1", "https://r/m1-full"),
+    fullResult("m2", "https://r/m2-full"),
+  ];
+  await act(async () => rerender(<Harness version={3} />));
+  await waitFor(() => {
+    expect(sentConfigs().some((c) => c.overlayCrop === "auto")).toBe(true);
+  });
+}
+
+describe("RealtimeProvider cropped delivery", () => {
+  it("flips to overlayCrop:auto only after every configured mockup seeded", async () => {
+    const { rerender } = render(<Harness version={1} />);
+    // Initial config: no crop
+    await waitFor(() => expect(h.sendConfig).toHaveBeenCalled());
+    expect(sentConfigs()[0].overlayCrop).toBeUndefined();
+    await seedAndFlip(rerender);
+  });
+
+  it("decodes the frozen background at seed time, before the SDK can revoke its blob: URL", async () => {
+    // With ws binary delivery the full frame's imageUrl is the SDK's live
+    // blob: URL, revoked when the next frame for that mockup arrives. The
+    // background must be decoded while the URL is still alive.
+    const { rerender } = render(<Harness version={1} />);
+    await waitFor(() => expect(h.sendConfig).toHaveBeenCalled());
+    h.state.results = [fullResult("m1", "blob:live-m1"), fullResult("m2", "blob:live-m2")];
+    await act(async () => rerender(<Harness version={3} />));
+    await waitFor(() => {
+      expect(h.loadImageElement).toHaveBeenCalledWith("blob:live-m1");
+      expect(h.loadImageElement).toHaveBeenCalledWith("blob:live-m2");
+    });
+    // ...and not again at composite time — the decoded element is reused.
+    const loadsAfterSeed = h.loadImageElement.mock.calls.length;
+    await waitFor(() => expect(sentConfigs().some((c) => c.overlayCrop === "auto")).toBe(true));
+    h.state.results = [croppedResult("m1", "blob:live-m1-crop"), fullResult("m2", "blob:live-m2")];
+    await act(async () => rerender(<Harness version={4} />));
+    await waitFor(() => expect(h.compositeCroppedFrame).toHaveBeenCalled());
+    expect(h.loadImageElement.mock.calls.length).toBe(loadsAfterSeed);
+  });
+
+  it("composites cropped frames — consumers only ever see full-frame URLs", async () => {
+    const { rerender } = render(<Harness version={1} />);
+    await waitFor(() => expect(h.sendConfig).toHaveBeenCalled());
+    await seedAndFlip(rerender);
+
+    const seen: string[] = [];
+    capturedCtx.subscribeMockupResultById("m1", (r) => seen.push(r.imageUrl));
+
+    h.state.results = [
+      croppedResult("m1", "https://r/m1-crop-frame"),
+      fullResult("m2", "https://r/m2-full"),
+    ];
+    await act(async () => rerender(<Harness version={4} />));
+
+    await waitFor(() => {
+      expect(seen.some((u) => u.startsWith("blob:composite-"))).toBe(true);
+    });
+    // The raw cropped URL never reaches subscribers or the cache
+    expect(seen).not.toContain("https://r/m1-crop-frame");
+    expect(capturedCtx.getMockupUrl("m1")).toMatch(/^blob:composite-/);
+    expect(h.compositeCroppedFrame).toHaveBeenCalledWith(
+      expect.objectContaining({
+        frameUrl: "https://r/m1-crop-frame",
+        rect: { x: 0.2, y: 0.1, w: 0.5, h: 0.6 },
+      })
+    );
+  });
+
+  it("falls back to full-frame for the session when compositing fails, and re-renders the edit", async () => {
+    const { rerender } = render(<Harness version={1} />);
+    await waitFor(() => expect(h.sendConfig).toHaveBeenCalled());
+    await seedAndFlip(rerender);
+    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-frame")];
+    await act(async () => rerender(<Harness version={4} />));
+
+    await waitFor(() => {
+      // Unflipped: config re-sent WITHOUT overlayCrop
+      expect(sentConfigs().length).toBeGreaterThan(0);
+      expect(sentConfigs().every((c) => !c.overlayCrop)).toBe(true);
+      // The lost edit is re-rendered full-frame
+      expect(h.updateMockupIds).toHaveBeenCalledWith(["m1"]);
+    });
+
+    // Kill-switch: even after everything re-seeds, no flip this session
+    h.sendConfig.mockClear();
+    h.state.results = [
+      fullResult("m1", "https://r/m1-full-2"),
+      fullResult("m2", "https://r/m2-full-2"),
+    ];
+    await act(async () => rerender(<Harness version={5} />));
+    expect(sentConfigs().some((c) => c.overlayCrop === "auto")).toBe(false);
+    errSpy.mockRestore();
+  });
+
+  it("drops to full-frame before rendering a never-seeded mockup via updateMockupIds", async () => {
+    const { rerender } = render(<Harness version={1} />);
+    await waitFor(() => expect(h.sendConfig).toHaveBeenCalled());
+    await seedAndFlip(rerender);
+    h.sendConfig.mockClear();
+
+    act(() => {
+      capturedCtx.updateMockupIds(["m3"]);
+    });
+    // Config re-sent without crop BEFORE the render request goes out
+    expect(sentConfigs().length).toBe(1);
+    expect(sentConfigs()[0].overlayCrop).toBeUndefined();
+    expect(h.updateMockupIds).toHaveBeenCalledWith(["m3"]);
+
+    // Seeded mockups don't unflip
+    h.sendConfig.mockClear();
+    act(() => {
+      capturedCtx.updateMockupIds(["m1", "m2"]);
+    });
+    expect(h.sendConfig).not.toHaveBeenCalled();
+  });
+});

package/src/patterns/__tests__/croppedFrameComposite.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import {
+  allBackgroundsSeeded,
+  compositeOffset,
+  isFullRect,
+} from "../croppedFrameComposite";
+
+describe("isFullRect", () => {
+  it("treats a missing rect as full frame", () => {
+    expect(isFullRect(undefined)).toBe(true);
+    expect(isFullRect(null)).toBe(true);
+  });
+
+  it("treats the identity rect as full frame", () => {
+    expect(isFullRect({ x: 0, y: 0, w: 1, h: 1 })).toBe(true);
+  });
+
+  it("treats any real crop as cropped", () => {
+    expect(isFullRect({ x: 0.37, y: 0.1, w: 0.45, h: 0.87 })).toBe(false);
+    expect(isFullRect({ x: 0, y: 0, w: 0.999, h: 1 })).toBe(false);
+  });
+});
+
+describe("compositeOffset", () => {
+  it("recovers the server's integer pixel offsets from fractions", () => {
+    // Server cropped at x=518px, y=102px of a 1400×782 frame.
+    const rect = { x: 518 / 1400, y: 102 / 782, w: 0.4, h: 0.6 };
+    expect(compositeOffset(rect, 1400, 782)).toEqual({ dx: 518, dy: 102 });
+  });
+
+  it("survives fraction truncation to 4 decimals within ±1px", () => {
+    const rect = { x: 0.37, y: 0.1304, w: 0.4, h: 0.6 };
+    const { dx, dy } = compositeOffset(rect, 1400, 782);
+    expect(Math.abs(dx - 518)).toBeLessThanOrEqual(1);
+    expect(Math.abs(dy - 102)).toBeLessThanOrEqual(1);
+  });
+
+  it("is zero at the origin", () => {
+    expect(compositeOffset({ x: 0, y: 0, w: 1, h: 1 }, 1400, 782)).toEqual({
+      dx: 0,
+      dy: 0,
+    });
+  });
+});
+
+describe("allBackgroundsSeeded", () => {
+  it("requires every configured mockup", () => {
+    const seeded = new Set(["a", "b"]);
+    expect(allBackgroundsSeeded(["a", "b"], seeded)).toBe(true);
+    expect(allBackgroundsSeeded(["a", "b", "c"], seeded)).toBe(false);
+  });
+
+  it("never flips on an empty config", () => {
+    expect(allBackgroundsSeeded([], new Set(["a"]))).toBe(false);
+  });
+});

package/src/patterns/croppedFrameComposite.ts

@@ -0,0 +1,122 @@
+/**
+ * Cropped-frame compositing for the realtime provider (PDP fast delivery).
+ *
+ * With `overlayCrop: 'auto'` on the session config, the server ships only the
+ * pixels inside the product region (a fraction of the full frame's bytes) and
+ * reports the fractional rect it cropped with. The provider composites that
+ * frame over the mockup's frozen full-frame background on a canvas, so every
+ * consumer keeps receiving plain full-frame URLs — the delivery strategy is
+ * invisible outside the provider.
+ *
+ * The cropped frame is rendered at the same pixel scale as the full frame
+ * (crop width in px = rect.w × render width), so compositing is an integer
+ * translate + draw at natural size — no scaling, no resampling.
+ */
+
+export interface CropRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** WebP quality for composited frames (PNG fallback on Safari is lossless). */
+const COMPOSITE_QUALITY = 0.92;
+
+/** A missing rect or the identity rect both mean "this is a full frame". */
+export function isFullRect(rect: CropRect | null | undefined): boolean {
+  if (!rect) return true;
+  return rect.x === 0 && rect.y === 0 && rect.w === 1 && rect.h === 1;
+}
+
+/**
+ * Pixel offset to draw the cropped frame at. The server derived the fractions
+ * from integer pixel offsets at this same render width, so rounding recovers
+ * the original integers (worst case ±1px from fraction truncation, inside the
+ * crop's padded region).
+ */
+export function compositeOffset(
+  rect: CropRect,
+  bgWidth: number,
+  bgHeight: number
+): { dx: number; dy: number } {
+  return {
+    dx: Math.round(rect.x * bgWidth),
+    dy: Math.round(rect.y * bgHeight),
+  };
+}
+
+/** Every mockup the session renders must have a frozen background before the
+ *  session may flip to cropped delivery (a cropped frame can't seed one). */
+export function allBackgroundsSeeded(
+  mockupIds: string[],
+  seeded: ReadonlySet<string>
+): boolean {
+  return mockupIds.length > 0 && mockupIds.every((id) => seeded.has(id));
+}
+
+/** Load + decode an image for compositing (CORS-clean so the canvas stays
+ *  untainted — render hosts serve ACAO for the crossorigin display path). */
+export function loadImageElement(url: string): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.crossOrigin = "anonymous";
+    img.onload = () => {
+      // decode() forces full decode off the critical path; a decode rejection
+      // (e.g. Safari under memory pressure) still leaves a drawable image.
+      if (img.decode) {
+        img.decode().then(
+          () => resolve(img),
+          () => resolve(img)
+        );
+      } else {
+        resolve(img);
+      }
+    };
+    img.onerror = () =>
+      reject(
+        new Error(`E_OVERLAY_FRAME_LOAD: image failed to load: ${url.slice(0, 160)}`)
+      );
+    img.src = url;
+  });
+}
+
+/**
+ * Composite a cropped frame over its full-frame background. Returns an
+ * encoded Blob (WebP where the browser supports canvas WebP encode, PNG
+ * otherwise per the toBlob spec fallback). Throws typed `E_OVERLAY_*` errors —
+ * the provider treats any throw as "disable cropped delivery this session".
+ */
+export async function compositeCroppedFrame(args: {
+  background: HTMLImageElement;
+  frameUrl: string;
+  rect: CropRect;
+  /** Reusable canvas to avoid per-frame allocations. */
+  canvas?: HTMLCanvasElement;
+}): Promise<Blob> {
+  const frame = await loadImageElement(args.frameUrl);
+  const width = args.background.naturalWidth;
+  const height = args.background.naturalHeight;
+  if (!width || !height) {
+    throw new Error("E_OVERLAY_BG_EMPTY: background image has no pixels");
+  }
+  const canvas = args.canvas ?? document.createElement("canvas");
+  // Setting dimensions also clears any previous composite.
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) {
+    throw new Error("E_OVERLAY_NO_2D_CONTEXT: canvas 2d context unavailable");
+  }
+  ctx.drawImage(args.background, 0, 0);
+  const { dx, dy } = compositeOffset(args.rect, width, height);
+  // Natural size — pixel-exact overlay, no scaling.
+  ctx.drawImage(frame, dx, dy);
+  const blob = await new Promise<Blob | null>((resolve) =>
+    canvas.toBlob(resolve, "image/webp", COMPOSITE_QUALITY)
+  );
+  if (!blob) {
+    throw new Error("E_OVERLAY_ENCODE_FAILED: canvas.toBlob returned null");
+  }
+  return blob;
+}