@snowcone-app/ui 0.4.7 → 0.4.9

package/package.json

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

package/src/patterns/RealtimeProvider.tsx

@@ -42,6 +42,7 @@ import type { RealtimeRenderError } from "@snowcone-app/sdk";
 import { readEnv } from "../lib/env";
 import { useProductOptional } from "./Product";
 import type { ReactProductContext } from "./Product";
+import { useMockupBackgroundOptional } from "./MockupBackground";
 
 // Default artboard size for export calculations (matches @snowcone-app/canvas default)
 const DEFAULT_ARTBOARD_SIZE = 2000;
@@ -126,6 +127,26 @@ export interface RealtimeContextValue {
    */
   updatePlacementSettings: (settings: Record<string, { scaleMode?: 'fill' | 'fit'; tiles?: number; alignment?: string }>) => boolean;
 
+  /**
+   * Declare spread-mode crop geometry (ADR-0060) for canvases that run
+   * combined spread/group artboards: artboard name → artboard dims + piece
+   * rects keyed by the product's placement labels. Sent on the realtime
+   * config (re-sent when it changes) so the server can slice each rendered
+   * spread canvas_state into per-placement images. Pass undefined to clear.
+   */
+  setSpreadCrops: (
+    crops:
+      | Record<
+          string,
+          {
+            width: number;
+            height: number;
+            pieces: Array<{ placement: string; x: number; y: number; width: number; height: number }>;
+          }
+        >
+      | undefined
+  ) => void;
+
   // PERFORMANCE: Direct access without state updates
   getMockupResultsImmediate: () => MockupResult[];
 
@@ -273,6 +294,9 @@ export function RealtimeProvider({
   grantUrl,
 }: RealtimeProviderProps) {
   const productContext = useProductOptional();
+  // Page background for renders (see MockupBackground) — sent on the config so
+  // realtime results match static `bg=` mockup URLs.
+  const mockupBg = useMockupBackgroundOptional();
 
   const [isEnabled, setIsEnabled] = useState(autoEnable);
 
@@ -305,6 +329,22 @@ export function RealtimeProvider({
 
   // Track last sent variantId to detect when we need to re-send config
   const lastSentVariantIdRef = useRef<string | null>(null);
+  const lastSentBgRef = useRef<string | undefined>(undefined);
+  // Spread crop geometry (ADR-0060) declared via setSpreadCrops. Ref holds
+  // the payload; the version state re-runs the config effect on change.
+  const spreadCropsRef = useRef<
+    | Record<
+        string,
+        {
+          width: number;
+          height: number;
+          pieces: Array<{ placement: string; x: number; y: number; width: number; height: number }>;
+        }
+      >
+    | undefined
+  >(undefined);
+  const [spreadCropsVersion, setSpreadCropsVersion] = useState(0);
+  const lastSentSpreadCropsRef = useRef<string>("null");
 
   // Track last sent colors to prevent duplicates
   const lastSentColorsRef = useRef<Record<string, string>>({});
@@ -577,6 +617,8 @@ export function RealtimeProvider({
         disconnect();
         configSentRef.current = false;
         lastSentVariantIdRef.current = null;
+        lastSentBgRef.current = undefined;
+        lastSentSpreadCropsRef.current = "null";
         lastSentColorsRef.current = {};
       };
     }
@@ -611,8 +653,14 @@ export function RealtimeProvider({
     const isFirstSend = !configSentRef.current;
     const variantChanged = lastSentVariantIdRef.current !== null &&
                            lastSentVariantIdRef.current !== variantId;
-
-    if (!isFirstSend && !variantChanged) {
+    // 3. Background changed (theme flip swaps the MockupBackground hex)
+    const bgChanged = configSentRef.current && lastSentBgRef.current !== mockupBg;
+    // 4. Spread crop geometry changed (spread-mode editor mounted/unmounted)
+    const spreadCropsJson = JSON.stringify(spreadCropsRef.current ?? null);
+    const spreadCropsChanged =
+      configSentRef.current && lastSentSpreadCropsRef.current !== spreadCropsJson;
+
+    if (!isFirstSend && !variantChanged && !bgChanged && !spreadCropsChanged) {
       return; // Nothing changed, skip
     }
 
@@ -637,6 +685,8 @@ export function RealtimeProvider({
           variantId,
           shop: shop as string,
           width: mockupWidth,
+          ...(mockupBg ? { bg: mockupBg } : {}),
+          ...(spreadCropsRef.current ? { spreadCrops: spreadCropsRef.current } : {}),
           placementSettings: { ...placementSettingsOverridesRef.current },
         }
       : {
@@ -646,6 +696,8 @@ export function RealtimeProvider({
           shop: "hTidnpNnNa",
           seal: "bypass-sig-for-k6-load-test",
           width: mockupWidth,
+          ...(mockupBg ? { bg: mockupBg } : {}),
+          ...(spreadCropsRef.current ? { spreadCrops: spreadCropsRef.current } : {}),
           placementSettings: { ...placementSettingsOverridesRef.current },
         };
 
@@ -662,6 +714,8 @@ export function RealtimeProvider({
 
     configSentRef.current = true;
     lastSentVariantIdRef.current = variantId;
+    lastSentBgRef.current = mockupBg;
+    lastSentSpreadCropsRef.current = spreadCropsJson;
 
     // Send default colors for color placements
     setTimeout(() => {
@@ -682,6 +736,8 @@ export function RealtimeProvider({
     sendConfigRaw,
     sendColorBlobTracked,
     mockupWidth,
+    mockupBg,
+    spreadCropsVersion,
   ]);
 
   // Watch for color placement changes
@@ -725,6 +781,32 @@ export function RealtimeProvider({
     [updatePlacementSettingsRaw]
   );
 
+  // Declare spread crop geometry (ADR-0060). Stored in a ref; bumping the
+  // version state re-runs the config effect, which re-sends the config when
+  // the serialized geometry actually changed.
+  const setSpreadCrops = useCallback(
+    (
+      crops:
+        | Record<
+            string,
+            {
+              width: number;
+              height: number;
+              pieces: Array<{ placement: string; x: number; y: number; width: number; height: number }>;
+            }
+          >
+        | undefined
+    ) => {
+      const next = crops && Object.keys(crops).length > 0 ? crops : undefined;
+      if (JSON.stringify(next ?? null) === JSON.stringify(spreadCropsRef.current ?? null)) {
+        return;
+      }
+      spreadCropsRef.current = next;
+      setSpreadCropsVersion((v) => v + 1);
+    },
+    []
+  );
+
   const enableRealtime = useCallback(() => {
     setIsEnabled(true);
   }, []);
@@ -1099,6 +1181,7 @@ export function RealtimeProvider({
       sendCanvasState,
       updateMockupIds: updateMockupIdsRaw,
       updatePlacementSettings: updatePlacementSettingsWrapped,
+      setSpreadCrops,
       getMockupResultsImmediate: () => mockupResultsRef.current,
       subscribeMockupResults: stableSubscribeMockupResults,
       subscribeMockupResultById: stableSubscribeMockupResultById,
@@ -1135,6 +1218,7 @@ export function RealtimeProvider({
       sendCanvasState,
       updateMockupIdsRaw,
       updatePlacementSettingsWrapped,
+      setSpreadCrops,
       stableSubscribeMockupResults,
       stableSubscribeMockupResultById,
       notifyPendingExport,