@snowcone-app/ui 0.4.6 → 0.4.8

package/package.json

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

package/src/composed/HeroProductImage.tsx

@@ -16,6 +16,7 @@ import {
 import { useShopOptional } from "../patterns/ShopProvider";
 import { useRealtimeOptional } from "../patterns/RealtimeProvider";
 import { useMockupPriorityOptional } from "../patterns/MockupPriorityProvider";
+import { useMockupBackgroundOptional } from "../patterns/MockupBackground";
 import { LoadingOverlayPrismCandyInline } from "../components/LoadingOverlayPrismCandy";
 import {
   createDesignForPlacements,
@@ -82,6 +83,8 @@ function buildHeroMockupUrl(args: {
   mockupId: string;
   variantId: string;
   width: number;
+  /** Canonical 6-hex background (see MockupBackground) — painted behind alpha scenes. */
+  bg?: string;
 }): string | null {
   const snow =
     (typeof window !== "undefined" &&
@@ -97,6 +100,7 @@ function buildHeroMockupUrl(args: {
     width: args.width,
     view: args.mockupId,
     variant: args.variantId,
+    ...(args.bg ? { bg: args.bg } : {}),
     ...(snow.resolver ? { base: snow.resolver } : {}),
   });
 }
@@ -204,6 +208,8 @@ export const HeroProductImage = memo(function HeroProductImage({
   const shopContext = useShopOptional();
   const realtimeContext = useRealtimeOptional();
   const priorityContext = useMockupPriorityOptional();
+  // Page background baked into static mockup URLs (see MockupBackground).
+  const mockupBg = useMockupBackgroundOptional();
   const priorityContextRef = useRef(priorityContext);
   priorityContextRef.current = priorityContext;
 
@@ -295,6 +301,7 @@ export const HeroProductImage = memo(function HeroProductImage({
       mockupId: actualMockupId,
       variantId: actualGvid,
       width,
+      bg: mockupBg,
     });
   }, [
     realtimeUrl,
@@ -304,6 +311,7 @@ export const HeroProductImage = memo(function HeroProductImage({
     actualProductId,
     actualMockupId,
     actualGvid,
+    mockupBg,
     product?.placements,
     context?.product?.placements,
     images,
@@ -728,6 +736,7 @@ export const HeroProductImage = memo(function HeroProductImage({
       mockupId: actualMockupId,
       variantId: actualGvid,
       width: width,
+      bg: mockupBg,
     });
     if (!url) return;
 
@@ -815,6 +824,7 @@ export const HeroProductImage = memo(function HeroProductImage({
     actualProductId,
     actualMockupId,
     actualGvid,
+    mockupBg,
     images,
     width,
     effects,

package/src/index.ts

@@ -170,6 +170,13 @@ export type {
   PriorityLevel,
 } from "./patterns/MockupPriorityProvider";
 
+// MockupBackground - page background baked into static mockup URLs (bg=)
+export {
+  MockupBackground,
+  useMockupBackgroundOptional,
+} from "./patterns/MockupBackground";
+export type { MockupBackgroundProps } from "./patterns/MockupBackground";
+
 // ProductPageProvider - Quick-start providers for product pages
 export {
   ProductPageProvider,

package/src/patterns/MockupBackground.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+/**
+ * MockupBackground — page-level background color for mockup renders.
+ *
+ * Wrap a subtree to have every `HeroProductImage` inside it append
+ * `bg=<hex>` to the static mockup URLs it builds. The renderer paints the
+ * color at the bottom of the stage, so it only shows through mockup scenes
+ * whose background has alpha (studio cutouts) — opaque scenes are unaffected.
+ *
+ * Why: cutout mockups are transparent where the scene ends. Layout tricks
+ * that stack a blurred copy of the image behind the sharp one (the PDP
+ * edge-blur width extension) bleed through that transparency. Baking the
+ * page background into the render makes the image opaque and self-contained
+ * (zoom overlays, saved snapshots, and the blur layers all inherit it).
+ *
+ * `bg` must be the canonical public grammar: lowercase 6-hex, no "#"
+ * (URLs are cache keys). Invalid values throw at URL-build time via
+ * `getMockupUrl` — loudly, dev and prod.
+ */
+
+import React, { createContext, useContext } from "react";
+
+const MockupBackgroundContext = createContext<string | undefined>(undefined);
+
+export interface MockupBackgroundProps {
+  /** Canonical background hex (lowercase 6-hex, no "#"), or undefined to leave URLs untouched. */
+  bg?: string;
+  children: React.ReactNode;
+}
+
+export function MockupBackground({ bg, children }: MockupBackgroundProps) {
+  return (
+    <MockupBackgroundContext.Provider value={bg}>
+      {children}
+    </MockupBackgroundContext.Provider>
+  );
+}
+
+/** Background hex from the nearest MockupBackground, or undefined outside one. */
+export function useMockupBackgroundOptional(): string | undefined {
+  return useContext(MockupBackgroundContext);
+}

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;
@@ -273,6 +274,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 +309,7 @@ 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);
 
   // Track last sent colors to prevent duplicates
   const lastSentColorsRef = useRef<Record<string, string>>({});
@@ -577,6 +582,7 @@ export function RealtimeProvider({
         disconnect();
         configSentRef.current = false;
         lastSentVariantIdRef.current = null;
+        lastSentBgRef.current = undefined;
         lastSentColorsRef.current = {};
       };
     }
@@ -611,8 +617,10 @@ export function RealtimeProvider({
     const isFirstSend = !configSentRef.current;
     const variantChanged = lastSentVariantIdRef.current !== null &&
                            lastSentVariantIdRef.current !== variantId;
+    // 3. Background changed (theme flip swaps the MockupBackground hex)
+    const bgChanged = configSentRef.current && lastSentBgRef.current !== mockupBg;
 
-    if (!isFirstSend && !variantChanged) {
+    if (!isFirstSend && !variantChanged && !bgChanged) {
       return; // Nothing changed, skip
     }
 
@@ -637,6 +645,7 @@ export function RealtimeProvider({
           variantId,
           shop: shop as string,
           width: mockupWidth,
+          ...(mockupBg ? { bg: mockupBg } : {}),
           placementSettings: { ...placementSettingsOverridesRef.current },
         }
       : {
@@ -646,6 +655,7 @@ export function RealtimeProvider({
           shop: "hTidnpNnNa",
           seal: "bypass-sig-for-k6-load-test",
           width: mockupWidth,
+          ...(mockupBg ? { bg: mockupBg } : {}),
           placementSettings: { ...placementSettingsOverridesRef.current },
         };
 
@@ -662,6 +672,7 @@ export function RealtimeProvider({
 
     configSentRef.current = true;
     lastSentVariantIdRef.current = variantId;
+    lastSentBgRef.current = mockupBg;
 
     // Send default colors for color placements
     setTimeout(() => {
@@ -682,6 +693,7 @@ export function RealtimeProvider({
     sendConfigRaw,
     sendColorBlobTracked,
     mockupWidth,
+    mockupBg,
   ]);
 
   // Watch for color placement changes