@snowcone-app/ui 0.4.6 → 0.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/ui",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "React components for merchandise visualization and customization",
   "keywords": [
     "react",

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);
+}