npm - @snowcone-app/ui - Versions diffs - 0.1.42 → 0.2.0 - Mend

@snowcone-app/ui 0.1.42 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (192) hide show

package/CHANGELOG.md +33 -0
package/README.md +18 -4
package/package.json +9 -5
package/src/components/CanvasIsolationBoundary.tsx +202 -0
package/src/components/LoadingOverlayPrism.tsx +251 -0
package/src/composed/AddToCart.tsx +229 -0
package/src/composed/ArtAlignment.tsx +703 -0
package/src/composed/ArtSelector.tsx +290 -0
package/src/composed/ArtworkCustomizer.tsx +212 -0
package/src/composed/CanvasEditor.tsx +79 -0
package/src/composed/ColorPicker.tsx +111 -0
package/src/composed/CurrentSelectionDisplay.tsx +86 -0
package/src/composed/HeroProductImage.tsx +1071 -0
package/src/composed/Lightbox.index.ts +2 -0
package/src/composed/Lightbox.tsx +230 -0
package/src/composed/PlacementClipShapeSelector.tsx +88 -0
package/src/composed/PlacementTabs.tsx +179 -0
package/src/composed/ProductCard.tsx +298 -0
package/src/composed/ProductGallery.tsx +54 -0
package/src/composed/ProductImage.tsx +129 -0
package/src/composed/ProductList.tsx +147 -0
package/src/composed/ProductOptions.tsx +305 -0
package/src/composed/RealtimeMockup.tsx +121 -0
package/src/composed/TileCount.tsx +348 -0
package/src/composed/carousels/HeroCarousel.tsx +240 -0
package/src/composed/carousels/MobileProductCarousel.tsx +1002 -0
package/src/composed/carousels/index.ts +11 -0
package/src/composed/carousels/types.ts +58 -0
package/src/composed/grids/MasonryGrid.tsx +238 -0
package/src/composed/grids/index.ts +9 -0
package/src/composed/search/CurrentRefinements.tsx +80 -0
package/src/composed/search/Filters.tsx +49 -0
package/src/composed/search/FiltersButton.tsx +57 -0
package/src/composed/search/FiltersDrawer.tsx +375 -0
package/src/composed/search/ProductGrid.tsx +118 -0
package/src/composed/search/ProductHit.tsx +56 -0
package/src/composed/search/SearchBox.tsx +109 -0
package/src/composed/search/SearchProvider.tsx +136 -0
package/src/composed/search/facetConfig.ts +16 -0
package/src/composed/search/index.ts +22 -0
package/src/composed/search/meilisearchAdapter.ts +20 -0
package/src/composed/search/types.ts +22 -0
package/src/composed/zoom/EnhancedImageViewer.tsx +505 -0
package/src/composed/zoom/ResponsiveZoom.tsx +134 -0
package/src/composed/zoom/ZoomOverlay.tsx +194 -0
package/src/composed/zoom/index.ts +12 -0
package/src/composed/zoom/types.ts +12 -0
package/src/design-system/ColorPalette.tsx +126 -0
package/src/design-system/ColorSwatch.tsx +49 -0
package/src/design-system/DesignSystemPage.tsx +130 -0
package/src/design-system/ThemeSwitcher.tsx +181 -0
package/src/design-system/TypographyScale.tsx +106 -0
package/src/design-system/index.ts +5 -0
package/src/ecommerce/stories/HeroProductImage.stories.tsx +66 -0
package/src/ecommerce/stories/PDPHeroGallery.stories.tsx +105 -0
package/src/ecommerce/stories/PDPInfoPanel.stories.tsx +472 -0
package/src/ecommerce/stories/PDPLayout.stories.tsx +365 -0
package/src/hooks/useBrand.ts +41 -0
package/src/hooks/useCanvasContext.ts +127 -0
package/src/hooks/useDeviceDetection.ts +64 -0
package/src/hooks/useFocusTrap.ts +70 -0
package/src/hooks/useImagePreloader.ts +268 -0
package/src/hooks/useImageTransition.ts +608 -0
package/src/hooks/usePlacementsProcessor.ts +74 -0
package/src/hooks/useProductGallery.ts +193 -0
package/src/hooks/useProductPage.ts +467 -0
package/src/hooks/useRenderGuard.ts +96 -0
package/src/hooks/useScrollDirection.ts +196 -0
package/src/hooks/viewport/index.ts +25 -0
package/src/hooks/viewport/useContainerWidth.ts +59 -0
package/src/hooks/viewport/useMediaQuery.ts +52 -0
package/src/hooks/viewport/useResponsiveImageCap.ts +149 -0
package/src/hooks/viewport/useViewportDimensions.ts +135 -0
package/src/hooks/viewport/useWideMonitorMode.ts +150 -0
package/src/hooks/visibility/index.ts +15 -0
package/src/hooks/visibility/observerPool.ts +150 -0
package/src/index.ts +240 -0
package/src/layouts/hero-zoom/HeroShrinkLayout.tsx +209 -0
package/src/layouts/hero-zoom/HeroZoomLayout.tsx +351 -0
package/src/layouts/hero-zoom/index.ts +30 -0
package/src/layouts/hero-zoom/stories/HeroZoomLayout.stories.tsx +350 -0
package/src/layouts/hero-zoom/types.ts +113 -0
package/src/layouts/hero-zoom/useHeroZoomScales.ts +156 -0
package/src/layouts/index.ts +9 -0
package/src/layouts/pdp/EdgeBlurBox.tsx +210 -0
package/src/layouts/pdp/ImageBlurExtension.tsx +215 -0
package/src/layouts/pdp/ImageEdgeBlur.tsx +215 -0
package/src/layouts/pdp/PDPLayout.tsx +246 -0
package/src/layouts/pdp/SimpleImageBlur.tsx +140 -0
package/src/layouts/pdp/index.ts +40 -0
package/src/lib/env.ts +15 -0
package/src/lib/locale.ts +167 -0
package/src/lib/router.tsx +46 -0
package/src/lib/utils.ts +6 -0
package/src/lightbox/README.md +77 -0
package/src/next/index.tsx +26 -0
package/src/patterns/MockupPriorityProvider.tsx +1014 -0
package/src/patterns/Product.tsx +850 -0
package/src/patterns/ProductPageProvider.tsx +224 -0
package/src/patterns/RealtimeProvider.tsx +1162 -0
package/src/patterns/ShopProvider.tsx +603 -0
package/src/personalization/PersonalizationBridge.tsx +235 -0
package/src/personalization/PersonalizationContext.ts +29 -0
package/src/personalization/PersonalizationInputs.tsx +110 -0
package/src/personalization/PersonalizationProvider.tsx +407 -0
package/src/personalization/canvas-stub.d.ts +22 -0
package/src/personalization/index.ts +43 -0
package/src/personalization/types.ts +48 -0
package/src/personalization/usePersonalization.ts +32 -0
package/src/personalization/usePersonalizationShimmer.ts +159 -0
package/src/personalization/utils.ts +59 -0
package/src/primitives/BrandLogo.tsx +65 -0
package/src/primitives/BrandName.tsx +51 -0
package/src/primitives/Button.tsx +123 -0
package/src/primitives/ColorSwatch.tsx +221 -0
package/src/primitives/DragHintAnimation.tsx +190 -0
package/src/primitives/EdgeSwipeGuards.tsx +60 -0
package/src/primitives/FloatingActionGroup.tsx +176 -0
package/src/primitives/ProductPrice.tsx +171 -0
package/src/primitives/ProgressiveBlur.tsx +295 -0
package/src/primitives/ThemeToggle.tsx +125 -0
package/src/primitives/__tests__/story-coverage.test.ts +98 -0
package/src/primitives/accordion.tsx +280 -0
package/src/primitives/badge.tsx +137 -0
package/src/primitives/card.tsx +61 -0
package/src/primitives/checkbox.tsx +56 -0
package/src/primitives/collapsible.tsx +51 -0
package/src/primitives/drawer.tsx +828 -0
package/src/primitives/dropdown-menu.tsx +197 -0
package/src/primitives/fieldset.tsx +73 -0
package/src/primitives/index.ts +138 -0
package/src/primitives/input.tsx +91 -0
package/src/primitives/kbd.tsx +130 -0
package/src/primitives/label.tsx +20 -0
package/src/primitives/link.tsx +182 -0
package/src/primitives/popover.tsx +80 -0
package/src/primitives/radio-group.tsx +79 -0
package/src/primitives/scroll-fade.tsx +159 -0
package/src/primitives/select.tsx +170 -0
package/src/primitives/separator.tsx +25 -0
package/src/primitives/slider.tsx +221 -0
package/src/primitives/spinner.tsx +72 -0
package/src/primitives/stories/Accordion.stories.tsx +121 -0
package/src/primitives/stories/Badge.stories.tsx +221 -0
package/src/primitives/stories/Button.stories.tsx +185 -0
package/src/primitives/stories/Card.stories.tsx +171 -0
package/src/primitives/stories/Checkbox.stories.tsx +214 -0
package/src/primitives/stories/Collapsible.stories.tsx +230 -0
package/src/primitives/stories/Drawer.stories.tsx +378 -0
package/src/primitives/stories/DropdownMenu.stories.tsx +182 -0
package/src/primitives/stories/Fieldset.stories.tsx +212 -0
package/src/primitives/stories/Input.stories.tsx +172 -0
package/src/primitives/stories/Kbd.stories.tsx +183 -0
package/src/primitives/stories/Label.stories.tsx +98 -0
package/src/primitives/stories/Link.stories.tsx +260 -0
package/src/primitives/stories/Popover.stories.tsx +178 -0
package/src/primitives/stories/RadioGroup.stories.tsx +205 -0
package/src/primitives/stories/Select.stories.tsx +222 -0
package/src/primitives/stories/Separator.stories.tsx +134 -0
package/src/primitives/stories/Slider.stories.tsx +203 -0
package/src/primitives/stories/Spinner.stories.tsx +142 -0
package/src/primitives/stories/Surface.stories.tsx +257 -0
package/src/primitives/stories/Switch.stories.tsx +131 -0
package/src/primitives/stories/Tabs.stories.tsx +275 -0
package/src/primitives/stories/TextField.stories.tsx +139 -0
package/src/primitives/stories/Textarea.stories.tsx +148 -0
package/src/primitives/stories/Tooltip.stories.tsx +119 -0
package/src/primitives/surface.tsx +86 -0
package/src/primitives/switch.tsx +35 -0
package/src/primitives/tabs.tsx +206 -0
package/src/primitives/text-field.tsx +84 -0
package/src/primitives/textarea.tsx +50 -0
package/src/primitives/tooltip.tsx +58 -0
package/src/services/CanvasExportService.ts +518 -0
package/src/styles/base.css +380 -0
package/src/styles/defaults.css +280 -0
package/src/styles/globals.css +1242 -0
package/src/styles/index.css +17 -0
package/src/styles/ne-themes.css +4740 -0
package/src/styles/tailwind.css +11 -0
package/src/styles/tokens.css +117 -0
package/src/styles/utilities.css +188 -0
package/src/themes/apply-theme.ts +449 -0
package/src/themes/getThemeStyles.ts +454 -0
package/src/themes/index.ts +48 -0
package/src/themes/oklch-theme.ts +283 -0
package/src/themes/presets.ts +989 -0
package/src/themes/types.ts +386 -0
package/src/themes/useTheme.tsx +450 -0
package/src/utils/dev-warnings.ts +161 -0
package/src/utils/devWarnings.ts +153 -0
package/dist/styles.css +0 -1

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,38 @@
 # Changelog
+## 0.2.0
+### Minor Changes
+- [#600](https://github.com/snowcone-app/snowcone-monorepo/pull/600) [`3349e6c`](https://github.com/snowcone-app/snowcone-monorepo/commit/3349e6cd6bc1cfa2e1b44bcbb5199eb2aa7dfc81) Thanks [@kevinsproles](https://github.com/kevinsproles)! - BREAKING: the zero-config prebuilt stylesheet is removed. `@snowcone-app/ui/styles.css` (compiled `dist/styles.css`) and the `.app-modern` theme-variable scope no longer exist — the package's unscoped compiled Tailwind utilities could collide with a host app's own classes, and the prebuilt sheet contradicted the primary host-compiled consumption mode.
+  The single supported setup is a **Tailwind v4 host** that compiles ui's styles:
+  ```css
+  /* app/globals.css — your Tailwind v4 entry */
+  @import "@snowcone-app/ui/styles/globals.css"; /* Tailwind + theme tokens + ui @source */
+  @source '../app/**/*.{js,ts,jsx,tsx}'; /* scan your own code too */
+  ```
+  ```ts
+  // next.config.ts
+  const nextConfig = { transpilePackages: ["@snowcone-app/ui"] };
+  ```
+  The published package now ships its `src/` (so the Tailwind `@source` scan and style imports work from npm) and exports `./styles/globals.css`, `./styles/defaults.css`, `./styles/base.css`, and `./styles/utilities.css`. Theme variables live on `:root` (dark on `.dark`) — no wrapper class. Full story: https://developers.snowcone.app/shop-setup
+### Patch Changes
+- Updated dependencies [[`b04c995`](https://github.com/snowcone-app/snowcone-monorepo/commit/b04c995d0a115760341f8b51f1ecbfb01deb8d6b), [`2adb836`](https://github.com/snowcone-app/snowcone-monorepo/commit/2adb836ef477809747d64053d55a84cfa166df9a)]:
+  - @snowcone-app/sdk@0.12.0
+## 0.1.43
+### Patch Changes
+- Updated dependencies [[`f15c421`](https://github.com/snowcone-app/snowcone-monorepo/commit/f15c421f11a793064fc5471f3286760f393ac4d7)]:
+  - @snowcone-app/sdk@0.11.0
 ## 0.1.42
 ### Patch Changes

package/README.md CHANGED Viewed

@@ -121,16 +121,30 @@ const pattern: SeamlessPattern = { type: 'pattern', src: 'https://…/p.jpg', ti
 Components use Tailwind CSS with semantic theme tokens (`bg-background`,
 `text-foreground`, `bg-primary`, `border-border`, …), so they inherit your theme.
-**Tailwind v4** must be told to scan the package for class names:
+The package requires a **Tailwind v4** host: your app compiles the styles, with
+ui's source as an extra `@source`. Import ui's stylesheet (it brings in
+Tailwind, the theme tokens, and an `@source` for the package's own components)
+and add an `@source` for your own code:
 ```css
 /* app/globals.css */
-@import "tailwindcss";
+@import "@snowcone-app/ui/styles/globals.css";
 @source "../app/**/*.{js,ts,jsx,tsx}";
-@source "../node_modules/@snowcone-app/ui/src/**/*.{js,ts,jsx,tsx}";
 ```
-(The `@snowcone-app/cli init` command writes this for you.)
+In Next.js, also transpile the package (it ships TypeScript source for the
+Tailwind scan):
+```ts
+// next.config.ts
+const nextConfig = {
+  transpilePackages: ["@snowcone-app/ui"],
+};
+```
+For dark mode, toggle the `dark` class on an ancestor (e.g. `<html
+class="dark">`). To customize the theme, override the CSS variables (declared
+on `:root`) in your own stylesheet after the import.
 ## Development with mock data

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/ui",
-  "version": "0.1.42",
+  "version": "0.2.0",
   "description": "React components for merchandise visualization and customization",
   "keywords": [
     "react",
@@ -41,6 +41,10 @@
       "require": "./dist/themes/index.cjs",
       "default": "./dist/themes/index.js"
     },
+    "./styles/defaults.css": "./src/styles/defaults.css",
+    "./styles/base.css": "./src/styles/base.css",
+    "./styles/utilities.css": "./src/styles/utilities.css",
+    "./styles/globals.css": "./src/styles/globals.css",
     "./personalization/bridge": {
       "types": "./dist/personalization/bridge.d.ts",
       "import": "./dist/personalization/bridge.js",
@@ -52,11 +56,11 @@
       "import": "./dist/next/index.js",
       "require": "./dist/next/index.cjs",
       "default": "./dist/next/index.js"
-    },
-    "./styles.css": "./dist/styles.css"
+    }
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -99,7 +103,7 @@
     "react-instantsearch": "^7.15.5",
     "react-zoom-pan-pinch": "^3.6.4",
     "tailwind-merge": "^3.0.0",
-    "@snowcone-app/sdk": "0.10.0"
+    "@snowcone-app/sdk": "0.12.0"
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^4.1.2",
@@ -130,7 +134,7 @@
     "@snowcone-app/brand": "0.1.0"
   },
   "scripts": {
-    "build": "tsup && vite build --config vite.css.config.ts && rimraf dist/_css-entry.mjs",
+    "build": "tsup",
     "clean": "rimraf dist",
     "build:sandpack": "tsup src/index.ts --format esm --minify --treeshake --splitting false --out-dir build-sandpack --clean --external react,react-dom,next/navigation",
     "test": "vitest run --environment=jsdom",

package/src/components/CanvasIsolationBoundary.tsx ADDED Viewed

@@ -0,0 +1,202 @@
+"use client";
+/**
+ * CanvasIsolationBoundary - Prevents React re-renders from reaching canvas
+ *
+ * This component creates an isolation boundary between React's render cycle
+ * and the SnowconeCanvas. It ensures that context updates (like mockup results
+ * arriving) don't cause the canvas to re-render and lag during drag operations.
+ *
+ * Architecture:
+ * - Uses React.memo with a custom comparison that ALWAYS returns true
+ * - Children are rendered once and never re-rendered due to parent changes
+ * - Configuration updates flow through the CanvasExportService singleton
+ * - The canvas reads current values from the service, not from props/context
+ *
+ * Usage:
+ * ```tsx
+ * <Product productId="...">
+ *   <RealtimeProvider>
+ *     <CanvasIsolationBoundary>
+ *       <SnowconeCanvas onExport={canvasExportService.handleExport} />
+ *     </CanvasIsolationBoundary>
+ *
+ *     {/* These can re-render freely without affecting canvas *\/}
+ *     <HeroProductImage />
+ *   </RealtimeProvider>
+ *   <ProductOptions />
+ * </Product>
+ * ```
+ *
+ * IMPORTANT: The children should use canvasExportService for callbacks,
+ * not props passed from parent components.
+ */
+import React, { useEffect } from 'react';
+import { useProductOptional } from '../patterns/Product';
+import { useRealtimeOptional } from '../patterns/RealtimeProvider';
+import { canvasExportService } from '../services/CanvasExportService';
+interface CanvasIsolationBoundaryProps {
+  children: React.ReactNode;
+  /** Optional: Override placement name (defaults to selectedPlacement from context) */
+  placementName?: string;
+  /** Optional: Callback when artwork changes (for updating parent state on exit) */
+  onArtworkChange?: (src: string) => void;
+  /**
+   * Optional: Function to clear ImageBitmap cache (memory management for iOS Safari)
+   * Pass clearImageBitmapCache from @snowcone-app/canvas
+   */
+  clearImageBitmapCache?: () => void;
+  /**
+   * Optional: Function to serialize canvas state for server-side rendering.
+   * Pass serializeStateForServer from @snowcone-app/canvas.
+   * When provided, enables JSON mode: canvas state is sent as JSON instead of PNG blob.
+   */
+  serializeStateForServer?: (state: any) => any;
+}
+/**
+ * Inner component that subscribes to contexts and configures the service.
+ * This component WILL re-render when context changes, but its children won't
+ * because they're wrapped in the isolation boundary.
+ *
+ * Can be used standalone (without CanvasIsolationBoundary) when you need
+ * to configure the singleton service but don't need isolation (e.g., when
+ * using a memoized canvas that handles its own re-render prevention).
+ */
+export function CanvasIsolationConfigurator({
+  placementName: placementNameProp,
+  onArtworkChange,
+  clearImageBitmapCache,
+  serializeStateForServer,
+}: Omit<CanvasIsolationBoundaryProps, 'children'>) {
+  const productContext = useProductOptional();
+  const realtimeContext = useRealtimeOptional();
+  // Configure the service whenever context values change
+  // This effect runs on re-renders but doesn't cause child re-renders
+  useEffect(() => {
+    canvasExportService.configure({
+      sendCanvasBlob: realtimeContext?.sendCanvasBlob,
+      sendCanvasState: realtimeContext?.sendCanvasState,
+      serializeStateForServer,
+      mockupCount: productContext?.product?.mockups?.length ?? 1,
+      isRealtimeEnabled: realtimeContext?.isEnabled ?? false,
+      placementName: placementNameProp || productContext?.selectedPlacement || productContext?.product?.placements?.[0]?.label || 'Front',
+      onArtworkChange,
+      enableRealtime: realtimeContext?.enableRealtime,
+      disableRealtime: realtimeContext?.disableRealtime,
+      clearImageBitmapCache,
+      // Wire CES's "I sent nothing" signal to the realtime context's
+      // cancellation broadcaster. Roll back any optimistic
+      // notifyPendingExport that didn't end up producing a real export.
+      notifyExportSkipped: realtimeContext?.notifyPendingExportCancelled,
+    });
+  }, [
+    realtimeContext?.sendCanvasBlob,
+    realtimeContext?.sendCanvasState,
+    serializeStateForServer,
+    productContext?.product?.mockups?.length,
+    realtimeContext?.isEnabled,
+    productContext?.selectedPlacement,
+    realtimeContext?.enableRealtime,
+    realtimeContext?.disableRealtime,
+    realtimeContext?.notifyPendingExportCancelled,
+    placementNameProp,
+    onArtworkChange,
+    clearImageBitmapCache,
+  ]);
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      canvasExportService.reset();
+    };
+  }, []);
+  return null; // This component doesn't render anything
+}
+/**
+ * The actual isolation boundary - NEVER re-renders children based on parent context changes
+ *
+ * NOTE: This prevents children from re-rendering when parent re-renders due to context
+ * changes (like mockup results arriving). Children can still re-render if their own
+ * props/state changes directly.
+ *
+ * However, since this uses React.memo with () => true, it blocks ALL re-renders
+ * from propagating to children. For artboard switching to work, the children must
+ * use a different mechanism (like refs or service calls) rather than props.
+ */
+const IsolatedChildren = React.memo(
+  function IsolatedChildren({ children }: { children: React.ReactNode }) {
+    return <>{children}</>;
+  },
+  // Custom comparison: ALWAYS return true (never re-render due to parent changes)
+  // This is intentional - children should use refs/services for updates that need to bypass this
+  () => true
+);
+/**
+ * Main component that combines configurator and isolation boundary
+ */
+export function CanvasIsolationBoundary({
+  children,
+  placementName,
+  onArtworkChange,
+  clearImageBitmapCache,
+  serializeStateForServer,
+}: CanvasIsolationBoundaryProps) {
+  return (
+    <>
+      {/* Configurator subscribes to context and updates service */}
+      <CanvasIsolationConfigurator
+        placementName={placementName}
+        onArtworkChange={onArtworkChange}
+        clearImageBitmapCache={clearImageBitmapCache}
+        serializeStateForServer={serializeStateForServer}
+      />
+      {/* Children are isolated from re-renders */}
+      <IsolatedChildren>{children}</IsolatedChildren>
+    </>
+  );
+}
+/**
+ * Hook to use inside the isolation boundary.
+ * Returns stable references that don't change during drag.
+ *
+ * Usage:
+ * ```tsx
+ * function MyCanvasComponent() {
+ *   const { handleExport, onEnterEditorMode, onExitEditorMode } = useIsolatedCanvas();
+ *
+ *   return (
+ *     <SnowconeCanvas
+ *       onExport={handleExport}
+ *       // ...
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useIsolatedCanvas() {
+  // These are stable references from the singleton
+  return {
+    /** Stable export handler - pass to SnowconeCanvas onExport */
+    handleExport: canvasExportService.handleExport,
+    /** Stable state change handler - pass to SnowconeCanvas onChange for JSON mode */
+    handleStateChange: canvasExportService.handleStateChange,
+    /** Call when entering editor mode */
+    onEnterEditorMode: () => canvasExportService.onEnterEditorMode(),
+    /** Call when exiting editor mode */
+    onExitEditorMode: () => canvasExportService.onExitEditorMode(),
+    /** Set initial artwork when entering editor */
+    setInitialArtwork: (src: string | null) => canvasExportService.setInitialArtwork(src),
+    /** Get last exported artwork */
+    getLastExportedArtwork: () => canvasExportService.getLastExportedArtwork(),
+    /** Check if artwork changed since entering editor */
+    hasArtworkChanged: () => canvasExportService.hasArtworkChanged(),
+  };
+}

package/src/components/LoadingOverlayPrism.tsx ADDED Viewed

@@ -0,0 +1,251 @@
+"use client";
+/**
+ * Loading overlay — frosted glass with soft prismatic color bands
+ * and twinkling sparkle particles. No center spinner or indicator.
+ */
+import { useState, useEffect, useCallback, useRef } from "react";
+type Particle = {
+  left: number;
+  top: number;
+  delay: string;
+  duration: string;
+  size: number;
+};
+function generateParticles(): Particle[] {
+  return Array.from({ length: 16 }, () => ({
+    left: 10 + Math.random() * 80,
+    top: 15 + Math.random() * 70,
+    delay: (Math.random() * 3.5).toFixed(1),
+    duration: (3 + Math.random() * 2).toFixed(1),
+    size: 2 + Math.random() * 2.5,
+  }));
+}
+const FADE_IN_MS = 600;
+const FADE_OUT_MS = 400;
+const STYLES = `
+.prism-loading-overlay {
+  background: rgba(255, 255, 255, 0.35);
+  opacity: 0;
+  z-index: 1;
+  pointer-events: none;
+  will-change: opacity;
+  transition: opacity ${FADE_IN_MS}ms ease-in;
+}
+.prism-loading-overlay.prism-fade-in {
+  opacity: 1;
+}
+.prism-loading-overlay.prism-fade-out {
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity ${FADE_OUT_MS}ms ease-out;
+}
+.prism-loading-rainbow {
+  position: absolute;
+  inset: 0;
+  overflow: hidden;
+}
+.prism-loading-band {
+  position: absolute;
+  width: 200%;
+  height: 45%;
+  left: -50%;
+  opacity: 0;
+  filter: blur(25px);
+  animation: prism-loading-sweep 6s ease-in-out infinite;
+}
+.prism-loading-band:nth-child(1) {
+  top: 5%;
+  background: linear-gradient(90deg, transparent, rgba(255, 50, 50, 0.15), transparent);
+  animation-delay: -0.6s;
+}
+.prism-loading-band:nth-child(2) {
+  top: 20%;
+  background: linear-gradient(90deg, transparent, rgba(255, 170, 30, 0.12), transparent);
+  animation-delay: -1.2s;
+}
+.prism-loading-band:nth-child(3) {
+  top: 35%;
+  background: linear-gradient(90deg, transparent, rgba(40, 200, 80, 0.12), transparent);
+  animation-delay: -2.4s;
+}
+.prism-loading-band:nth-child(4) {
+  top: 50%;
+  background: linear-gradient(90deg, transparent, rgba(40, 120, 255, 0.15), transparent);
+  animation-delay: -2.7s;
+}
+.prism-loading-band:nth-child(5) {
+  top: 65%;
+  background: linear-gradient(90deg, transparent, rgba(140, 50, 255, 0.12), transparent);
+  animation-delay: -3.0s;
+}
+@keyframes prism-loading-sweep {
+  0% { transform: translateX(-35%) rotate(-6deg); opacity: 0; }
+  25% { opacity: 1; }
+  75% { opacity: 1; }
+  100% { transform: translateX(35%) rotate(-6deg); opacity: 0; }
+}
+.prism-loading-particle {
+  position: absolute;
+  border-radius: 50%;
+  background: white;
+  opacity: 0;
+  animation: prism-loading-sparkle infinite ease-in-out;
+}
+@keyframes prism-loading-sparkle {
+  0% { opacity: 0; transform: scale(0); }
+  20% { opacity: 0.8; transform: scale(1); }
+  40% { opacity: 0.3; transform: scale(0.6); }
+  60% { opacity: 0.7; transform: scale(1.1); }
+  80% { opacity: 0.2; transform: scale(0.5); }
+  100% { opacity: 0; transform: scale(0); }
+}
+`;
+// Inject styles once
+let stylesInjected = false;
+function ensureStyles() {
+  if (stylesInjected || typeof document === "undefined") return;
+  const style = document.createElement("style");
+  style.textContent = STYLES;
+  document.head.appendChild(style);
+  stylesInjected = true;
+}
+export interface LoadingOverlayPrismProps {
+  /** When false, the overlay fades out then calls onExited. Default true. */
+  visible?: boolean;
+  /** Called after the fade-out transition completes. Use this to unmount. */
+  onExited?: () => void;
+}
+export function LoadingOverlayPrism({
+  visible = true,
+  onExited,
+}: LoadingOverlayPrismProps) {
+  ensureStyles();
+  console.log(`[Prism] render visible=${visible}`);
+  // Trigger fade-in on next frame after mount so the CSS transition plays
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => {
+    console.log(`[Prism] MOUNTED — scheduling fade-in`);
+    const raf = requestAnimationFrame(() => setMounted(true));
+    return () => cancelAnimationFrame(raf);
+  }, []);
+  // Empty on first render so SSR matches; populate after mount so each
+  // show of the loader gets a fresh random field.
+  const [particles, setParticles] = useState<Particle[]>([]);
+  useEffect(() => {
+    setParticles(generateParticles());
+  }, []);
+  // Log visibility changes
+  const prevVisibleRef = useRef(visible);
+  useEffect(() => {
+    if (prevVisibleRef.current && !visible) {
+      console.log(`[Prism] visible changed true→false — FADE-OUT STARTING`);
+    } else if (!prevVisibleRef.current && visible) {
+      console.log(`[Prism] visible changed false→true — FADE-IN RESTARTING`);
+    }
+    prevVisibleRef.current = visible;
+  }, [visible]);
+  const handleTransitionEnd = useCallback(() => {
+    if (!visible) {
+      console.log(`[Prism] FADE-OUT COMPLETE — calling onExited`);
+      onExited?.();
+    } else {
+      console.log(`[Prism] FADE-IN COMPLETE`);
+    }
+  }, [visible, onExited]);
+  let fadeClass = "";
+  if (!visible) {
+    fadeClass = " prism-fade-out";
+  } else if (mounted) {
+    fadeClass = " prism-fade-in";
+  }
+  return (
+    <div
+      className={`prism-loading-overlay absolute inset-0${fadeClass}`}
+      onTransitionEnd={handleTransitionEnd}
+    >
+      <div className="prism-loading-rainbow">
+        <div className="prism-loading-band" />
+        <div className="prism-loading-band" />
+        <div className="prism-loading-band" />
+        <div className="prism-loading-band" />
+        <div className="prism-loading-band" />
+      </div>
+      {particles.map((p, i) => (
+        <div
+          key={i}
+          className="prism-loading-particle"
+          style={{
+            left: `${p.left}%`,
+            top: `${p.top}%`,
+            animationDelay: `${p.delay}s`,
+            animationDuration: `${p.duration}s`,
+            width: `${p.size}px`,
+            height: `${p.size}px`,
+            boxShadow: `0 0 6px rgba(255, 255, 255, 0.5)`,
+          }}
+        />
+      ))}
+    </div>
+  );
+}
+/** How long to wait before showing the overlay (ms). If loading finishes
+ *  within this window (e.g. cached image), the overlay never appears. */
+const SHOW_DELAY_MS = 200;
+/**
+ * Hook that manages the mount/fade-out lifecycle with a grace period.
+ *
+ * - Waits `SHOW_DELAY_MS` before mounting the overlay so fast loads skip it entirely.
+ * - When loading ends, keeps overlay mounted for a smooth fade-out, then unmounts.
+ */
+export function useLoadingOverlay(isLoading: boolean) {
+  const [showOverlay, setShowOverlay] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => {
+    if (isLoading) {
+      timerRef.current = setTimeout(() => {
+        setShowOverlay(true);
+      }, SHOW_DELAY_MS);
+    } else {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+    }
+    return () => {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+    };
+  }, [isLoading]);
+  const handleExited = useCallback(() => {
+    setShowOverlay(false);
+  }, []);
+  return {
+    showOverlay,
+    overlayVisible: isLoading,
+    handleExited,
+  };
+}