@snowcone-app/ui 0.1.42 → 0.2.0

package/src/hooks/viewport/useViewportDimensions.ts

@@ -0,0 +1,135 @@
+"use client";
+
+import { useState, useEffect, useLayoutEffect } from "react";
+
+export interface ViewportDimensions {
+  width: number;
+  height: number;
+  aspectRatio: number;
+  /** Increments on each resize event - use for Safari mask repaint workaround */
+  resizeVersion: number;
+}
+
+/**
+ * Single source of truth for viewport dimensions.
+ * Only registers resize listener on desktop to avoid mobile jank.
+ *
+ * On mobile:
+ * - Returns initial dimensions (measured once on mount)
+ * - No resize listener is registered (saves performance)
+ * - Dimensions are static since mobile layouts don't depend on resize
+ *
+ * On desktop:
+ * - Registers a single resize listener
+ * - Updates dimensions on viewport changes
+ * - Used by useWideMonitorMode, useResponsiveImageCap, etc.
+ *
+ * @param isDesktop - Pass the result of useMediaQuery("(min-width: 768px)")
+ *                    null = SSR/unknown, false = mobile, true = desktop
+ * @returns Viewport dimensions (or defaults if SSR)
+ *
+ * @example
+ * ```tsx
+ * const isDesktop = useMediaQuery("(min-width: 768px)");
+ * const dimensions = useViewportDimensions(isDesktop);
+ *
+ * // dimensions.width, dimensions.height, dimensions.aspectRatio
+ * ```
+ */
+export function useViewportDimensions(
+  isDesktop: boolean | null
+): ViewportDimensions {
+  // Always start with zeros to match server render and avoid hydration mismatch.
+  // The useEffect below will update with actual dimensions after mount.
+  const [dimensions, setDimensions] = useState<ViewportDimensions>({
+    width: 0,
+    height: 0,
+    aspectRatio: 0,
+    resizeVersion: 0,
+  });
+
+  // Measure dimensions on initial mount (runs once after hydration)
+  useEffect(() => {
+    const width = window.innerWidth;
+    const height = window.innerHeight;
+    setDimensions((prev) => ({
+      width,
+      height,
+      aspectRatio: height > 0 ? width / height : 0,
+      resizeVersion: prev.resizeVersion, // Keep at 0 for initial mount
+    }));
+  }, []);
+
+  // Synchronously measure dimensions when switching to desktop mode
+  // useLayoutEffect runs BEFORE paint, ensuring correct dimensions on first render
+  useLayoutEffect(() => {
+    if (isDesktop !== true) return;
+
+    // Immediately measure when switching to desktop mode
+    // This handles iPad split view changes where isDesktop changes without a resize event
+    const width = window.innerWidth;
+    const height = window.innerHeight;
+    setDimensions((prev) => ({
+      width,
+      height,
+      aspectRatio: height > 0 ? width / height : 0,
+      // Increment to force Safari mask repaint
+      resizeVersion: prev.resizeVersion + 1,
+    }));
+  }, [isDesktop]);
+
+  // Register resize listener only on desktop (can use regular useEffect)
+  useEffect(() => {
+    if (isDesktop !== true) return;
+
+    let resizeTimeout: ReturnType<typeof setTimeout> | null = null;
+    let lastWidth = window.innerWidth;
+    let lastHeight = window.innerHeight;
+
+    const handleResize = () => {
+      const width = window.innerWidth;
+      const height = window.innerHeight;
+
+      // Check if this is likely an address bar show/hide (height-only change < 150px)
+      const widthChanged = Math.abs(width - lastWidth) > 1;
+      const heightChange = Math.abs(height - lastHeight);
+      const isAddressBarChange = !widthChanged && heightChange > 0 && heightChange < 150;
+
+      if (isAddressBarChange) {
+        // Safari iPad address bar show/hide - ignore completely to prevent flash
+        // Don't update dimensions, don't schedule resizeVersion increment
+        return;
+      }
+
+      // Real resize - update tracking variables
+      lastWidth = width;
+      lastHeight = height;
+
+      // Update dimensions immediately for responsive layout
+      setDimensions((prev) => ({
+        width,
+        height,
+        aspectRatio: height > 0 ? width / height : 0,
+        resizeVersion: prev.resizeVersion, // Don't increment yet
+      }));
+
+      // Debounce resizeVersion increment for real resizes only
+      // This is for Safari mask repaint workaround
+      if (resizeTimeout) clearTimeout(resizeTimeout);
+      resizeTimeout = setTimeout(() => {
+        setDimensions((prev) => ({
+          ...prev,
+          resizeVersion: prev.resizeVersion + 1,
+        }));
+      }, 300); // Wait 300ms after last resize
+    };
+
+    window.addEventListener("resize", handleResize);
+    return () => {
+      window.removeEventListener("resize", handleResize);
+      if (resizeTimeout) clearTimeout(resizeTimeout);
+    };
+  }, [isDesktop]);
+
+  return dimensions;
+}

package/src/hooks/viewport/useWideMonitorMode.ts

@@ -0,0 +1,150 @@
+"use client";
+
+import { useMemo } from "react";
+import type { ResponsiveImageCapInfo } from "./useResponsiveImageCap";
+
+/**
+ * Layout configuration for gap calculations.
+ * Must match DesktopHeroImages LAYOUT_CONFIG.
+ */
+const LAYOUT_CONFIG = {
+  SIDEBAR_MAX_PX: 384,
+  SIDEBAR_MARGIN_PX: 32,
+  IMAGE_WIDTH_VW: 140, // Image width in vw units (matches DesktopHeroImages)
+  /**
+   * Gap threshold for wide monitor mode activation.
+   *
+   * This is intentionally HIGHER than ImageEdgeBlur's 10px threshold.
+   * - ImageEdgeBlur shows blur at 10px gap (fills small gaps)
+   * - useWideMonitorMode activates at 100px gap (changes layout behavior)
+   *
+   * This separation allows blur to fill small gaps while keeping
+   * the sidebar sticky at moderate viewport sizes like 937px.
+   */
+  WIDE_MONITOR_GAP_THRESHOLD: 100,
+} as const;
+
+/**
+ * Calculate the gap between the image right edge and viewport right edge.
+ * This is the core calculation used by both isWideMonitor and hasEdgeBlur.
+ */
+function calculateEdgeGap(
+  viewportWidth: number,
+  maxWidthPx: number,
+  sidebarPercent: number,
+  sidebarWidthPx?: number
+): number {
+  if (viewportWidth === 0 || maxWidthPx === 0) return 0;
+
+  // Use exact pixel width if provided, otherwise calculate from percent with cap
+  const sidebarPx = sidebarWidthPx ?? Math.min(
+    viewportWidth * sidebarPercent,
+    LAYOUT_CONFIG.SIDEBAR_MAX_PX
+  );
+  const contentAreaWidth = viewportWidth - sidebarPx - LAYOUT_CONFIG.SIDEBAR_MARGIN_PX;
+
+  // Image width is min(140vw, maxWidthPx) - matches DesktopHeroImages CSS
+  const imageWidthFromVw = (viewportWidth * LAYOUT_CONFIG.IMAGE_WIDTH_VW) / 100;
+  const imageWidth = Math.min(imageWidthFromVw, maxWidthPx);
+  const leftOffset = (contentAreaWidth - imageWidth) / 2;
+  const imageRightEdge = leftOffset + imageWidth;
+
+  return viewportWidth - imageRightEdge;
+}
+
+/**
+ * Check if we're in "wide monitor mode" where images don't cover the full viewport.
+ * Uses a HIGHER threshold (100px) than ImageEdgeBlur (10px).
+ *
+ * This is used for header stickiness - we want the header to stay sticky
+ * at moderate viewport sizes even if there's a small blur gap.
+ *
+ * @param viewportWidth - Current viewport width in pixels
+ * @param maxWidthPx - Maximum image width from imageCapInfo
+ * @param sidebarPercent - Sidebar width as a percentage (default: 0.35 for XL)
+ * @param sidebarWidthPx - Optional: exact sidebar width in pixels (bypasses 384px cap)
+ * @returns true if in wide monitor mode (uncovered gap > 100px)
+ */
+export function isWideMonitor(
+  viewportWidth: number,
+  maxWidthPx: number,
+  sidebarPercent: number = 0.35,
+  sidebarWidthPx?: number
+): boolean {
+  const gap = calculateEdgeGap(viewportWidth, maxWidthPx, sidebarPercent, sidebarWidthPx);
+  // Higher threshold to keep header sticky at moderate viewports
+  return gap > LAYOUT_CONFIG.WIDE_MONITOR_GAP_THRESHOLD;
+}
+
+/**
+ * Check if ImageEdgeBlur would render (gap > 10px).
+ * Uses the SAME threshold as ImageEdgeBlur component.
+ *
+ * This is used for sidebar minHeight - we want the sidebar to fill
+ * the vertical space whenever blur is visible.
+ *
+ * @param viewportWidth - Current viewport width in pixels
+ * @param maxWidthPx - Maximum image width from imageCapInfo
+ * @param sidebarPercent - Sidebar width as a percentage (default: 0.35 for XL)
+ * @param sidebarWidthPx - Optional: exact sidebar width in pixels (bypasses 384px cap)
+ * @returns true if edge blur would be visible (gap > 10px)
+ */
+export function hasEdgeBlur(
+  viewportWidth: number,
+  maxWidthPx: number,
+  sidebarPercent: number = 0.35,
+  sidebarWidthPx?: number
+): boolean {
+  const gap = calculateEdgeGap(viewportWidth, maxWidthPx, sidebarPercent, sidebarWidthPx);
+  // Same 10px threshold as ImageEdgeBlur
+  return gap > 10;
+}
+
+/**
+ * Hook to detect "wide monitor mode" - when the viewport is wide enough that
+ * images are capped and don't cover the full width (ImageEdgeBlur kicks in).
+ *
+ * In this mode:
+ * - Header should NOT be sticky (users scroll to get back to header)
+ * - Sidebar should have minHeight to fill the gap
+ * - ImageEdgeBlur renders to fill the gap on the right side
+ *
+ * This hook uses the same calculation as ImageEdgeBlur to ensure they always agree.
+ *
+ * @param imageCapInfo - Image cap info from useResponsiveImageCap hook
+ * @param sidebarPercent - Sidebar width as a percentage (auto-detects based on breakpoint if not provided)
+ * @returns boolean indicating if in wide monitor mode
+ *
+ * @example
+ * ```tsx
+ * const isDesktop = useMediaQuery("(min-width: 768px)");
+ * const dimensions = useViewportDimensions(isDesktop);
+ * const imageCapInfo = useResponsiveImageCap(dimensions);
+ * const isWideMonitorMode = useWideMonitorMode(imageCapInfo);
+ *
+ * // Adjust layout based on wide monitor mode
+ * <div style={isWideMonitorMode ? { minHeight: '...' } : {}}>
+ *   ...
+ * </div>
+ * ```
+ */
+export function useWideMonitorMode(
+  imageCapInfo: ResponsiveImageCapInfo,
+  sidebarPercent?: number
+): boolean {
+  return useMemo(() => {
+    const { viewportWidth, maxWidthPx } = imageCapInfo;
+
+    // Early return for mobile/SSR (dimensions will be 0 or small)
+    // Wide monitor mode is never true on mobile devices
+    if (viewportWidth < 768) return false;
+
+    // Use provided sidebarPercent, or auto-detect based on breakpoint:
+    // - MD (768-1279px): 30% sidebar
+    // - XL (1280px+): 35% sidebar
+    // This matches the breakpoint behavior in DesktopHeroImages
+    const effectiveSidebarPercent = sidebarPercent ?? (viewportWidth >= 1280 ? 0.35 : 0.3);
+
+    return isWideMonitor(viewportWidth, maxWidthPx, effectiveSidebarPercent);
+  }, [imageCapInfo.viewportWidth, imageCapInfo.maxWidthPx, sidebarPercent]);
+}

package/src/hooks/visibility/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Visibility detection utilities
+ *
+ * Provides shared IntersectionObserver infrastructure for tracking
+ * element visibility across the mockup rendering system.
+ */
+
+export {
+  observe,
+  isObserved,
+  getObserverCount,
+  getObservedElementCount,
+  VISIBILITY_THRESHOLDS,
+  DEFAULT_VISIBILITY_OPTIONS,
+} from './observerPool';

package/src/hooks/visibility/observerPool.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared IntersectionObserver Pool
+ *
+ * Creates a pool of IntersectionObservers that can be reused across multiple elements.
+ * This is more efficient than creating one observer per element, especially for pages
+ * with many mockup images.
+ *
+ * Key features:
+ * - Observers are pooled by options (rootMargin + threshold)
+ * - WeakMap for automatic cleanup when elements are garbage collected
+ * - Supports multiple threshold arrays for granular visibility tracking
+ *
+ * @example
+ * ```tsx
+ * const unobserve = observe(
+ *   element,
+ *   (entry) => console.log('Visibility:', entry.intersectionRatio),
+ *   { threshold: [0, 0.25, 0.5, 0.75, 1.0] }
+ * );
+ *
+ * // Cleanup
+ * unobserve();
+ * ```
+ */
+
+type VisibilityCallback = (entry: IntersectionObserverEntry) => void;
+
+// Store callbacks for each observed element
+// Using WeakMap allows automatic cleanup when elements are garbage collected
+const observerCallbacks = new WeakMap<Element, VisibilityCallback>();
+
+// Pool observers by their options (rootMargin + threshold combination)
+const observersByKey = new Map<string, IntersectionObserver>();
+
+// Track which elements are observed by which observer (for cleanup)
+const elementsByObserver = new Map<IntersectionObserver, Set<Element>>();
+
+/**
+ * Generate a unique key for observer options
+ */
+function getOptionsKey(options: IntersectionObserverInit): string {
+  const root = options.root ? 'custom' : 'viewport';
+  const rootMargin = options.rootMargin || '0px';
+  const threshold = Array.isArray(options.threshold)
+    ? options.threshold.join(',')
+    : String(options.threshold || 0);
+
+  return `${root}|${rootMargin}|${threshold}`;
+}
+
+/**
+ * Get or create an observer for the given options
+ */
+function getObserver(options: IntersectionObserverInit): IntersectionObserver {
+  const key = getOptionsKey(options);
+
+  if (!observersByKey.has(key)) {
+    const observer = new IntersectionObserver((entries) => {
+      entries.forEach((entry) => {
+        const callback = observerCallbacks.get(entry.target);
+        if (callback) {
+          callback(entry);
+        }
+      });
+    }, options);
+
+    observersByKey.set(key, observer);
+    elementsByObserver.set(observer, new Set());
+  }
+
+  return observersByKey.get(key)!;
+}
+
+/**
+ * Default threshold array for visibility tracking
+ * Provides callbacks at 0%, 25%, 50%, 75%, and 100% visibility
+ */
+export const VISIBILITY_THRESHOLDS = [0, 0.25, 0.5, 0.75, 1.0];
+
+/**
+ * Default options for visibility observation
+ */
+export const DEFAULT_VISIBILITY_OPTIONS: IntersectionObserverInit = {
+  threshold: VISIBILITY_THRESHOLDS,
+  rootMargin: '0px',
+};
+
+/**
+ * Observe an element for visibility changes using a pooled IntersectionObserver
+ *
+ * @param element - The DOM element to observe
+ * @param callback - Called when visibility changes (receives IntersectionObserverEntry)
+ * @param options - IntersectionObserver options (optional, uses default thresholds)
+ * @returns Unobserve function - call to stop observing
+ */
+export function observe(
+  element: Element,
+  callback: VisibilityCallback,
+  options: IntersectionObserverInit = DEFAULT_VISIBILITY_OPTIONS
+): () => void {
+  const observer = getObserver(options);
+  const elements = elementsByObserver.get(observer)!;
+
+  // Store the callback for this element
+  observerCallbacks.set(element, callback);
+
+  // Track and observe
+  elements.add(element);
+  observer.observe(element);
+
+  // Return unobserve function
+  return () => {
+    observerCallbacks.delete(element);
+    elements.delete(element);
+    observer.unobserve(element);
+
+    // Clean up empty observers (optional optimization)
+    // Commented out to avoid observer recreation overhead
+    // if (elements.size === 0) {
+    //   observer.disconnect();
+    //   observersByKey.delete(getOptionsKey(options));
+    //   elementsByObserver.delete(observer);
+    // }
+  };
+}
+
+/**
+ * Check if an element is currently being observed
+ */
+export function isObserved(element: Element): boolean {
+  return observerCallbacks.has(element);
+}
+
+/**
+ * Get the number of active observers (for debugging)
+ */
+export function getObserverCount(): number {
+  return observersByKey.size;
+}
+
+/**
+ * Get the total number of observed elements (for debugging)
+ */
+export function getObservedElementCount(): number {
+  let count = 0;
+  elementsByObserver.forEach((elements) => {
+    count += elements.size;
+  });
+  return count;
+}

package/src/index.ts

@@ -0,0 +1,240 @@
+// Brand — Protected brand identity components (ADR-0035)
+export * from "./primitives/BrandName";
+export * from "./primitives/BrandLogo";
+export { useBrand } from "./hooks/useBrand";
+export type { UseBrandResult } from "./hooks/useBrand";
+
+// Locale — Formatting utilities (i18n foundation)
+export {
+  formatCurrency,
+  formatDate,
+  formatDateTime,
+  getBrand,
+  brandAssets,
+} from "./lib/locale";
+export type {
+  SupportedLanguage,
+  SupportedCountry,
+  SupportedLocale,
+  BrandLocale,
+  BrandAssets,
+  FormatCurrencyOptions,
+} from "./lib/locale";
+
+// Router — framework-agnostic navigation. ui never imports next/navigation in
+// the main entry; inject your framework's router here (Next apps: use
+// UiNextRouterProvider from "@snowcone-app/ui/next"), else it falls back to the
+// browser History API.
+export { UiRouterProvider, type UiRouter } from "./lib/router";
+
+// Primitives - Basic building blocks (all components with stories)
+export * from "./primitives/Button";
+export * from "./primitives/ColorSwatch";
+export * from "./primitives/ProductPrice";
+export * from "./primitives/FloatingActionGroup";
+export * from "./primitives/ThemeToggle";
+export * from "./primitives/DragHintAnimation";
+export * from "./primitives/ProgressiveBlur";
+// EdgeSwipeGuards - iOS Safari back/forward gesture prevention
+export * from "./primitives/EdgeSwipeGuards";
+
+// UI Primitives - Radix-based components
+export * from "./primitives/accordion";
+export * from "./primitives/badge";
+export * from "./primitives/card";
+export * from "./primitives/checkbox";
+export * from "./primitives/collapsible";
+// Drawer - Mobile-optimized drawer component (works on all platforms including iOS Safari)
+export * from "./primitives/drawer";
+// ScrollFade - Container with gradient fade indicator for scrollable content
+export * from "./primitives/scroll-fade";
+export * from "./primitives/dropdown-menu";
+export * from "./primitives/fieldset";
+export * from "./primitives/input";
+export * from "./primitives/kbd";
+export * from "./primitives/label";
+export * from "./primitives/link";
+export * from "./primitives/popover";
+export * from "./primitives/radio-group";
+export * from "./primitives/select";
+export * from "./primitives/separator";
+export * from "./primitives/slider";
+export * from "./primitives/spinner";
+export * from "./primitives/surface";
+export * from "./primitives/switch";
+export * from "./primitives/tabs";
+export * from "./primitives/textarea";
+export * from "./primitives/text-field";
+export * from "./primitives/tooltip";
+
+// Composed - Pre-built component combinations
+export * from "./composed/ProductOptions";
+export * from "./composed/ProductCard";
+export * from "./composed/ProductList";
+export * from "./composed/ProductGallery";
+export * from "./composed/AddToCart";
+export * from "./composed/TileCount";
+export * from "./composed/CurrentSelectionDisplay";
+export * from "./composed/ArtSelector";
+export * from "./composed/ColorPicker";
+export * from "./composed/RealtimeMockup";
+export type { RealtimeMockupProps } from './composed/RealtimeMockup';
+export { Lightbox } from './composed/Lightbox.index';
+export type { LightboxProps } from './composed/Lightbox.index';
+export * from "./composed/PlacementClipShapeSelector";
+// PlacementTabs - Responsive placement selection with floating toolbar placeholder
+export * from "./composed/PlacementTabs";
+
+// Hooks
+export * from "./hooks/useProductGallery";
+export * from "./hooks/usePlacementsProcessor";
+export * from "./hooks/useFocusTrap";
+export * from "./hooks/useCanvasContext";
+export * from "./hooks/useRenderGuard";
+export * from "./hooks/useScrollDirection";
+export * from "./hooks/useImageTransition";
+// useImagePreloader - Preload images before they enter viewport (cross-browser consistent)
+export * from "./hooks/useImagePreloader";
+// useDeviceDetection - Touch device and Safari browser detection
+export * from "./hooks/useDeviceDetection";
+
+// useProductPage - Unified hook for building product pages (facade over all contexts)
+export {
+  useProductPage,
+  useProductPageOptional,
+  useProviderStatus,
+  useCurrentPlacements,
+  useArtworkAlignment,
+  useSetArtworkAlignment,
+  useSelectedArtwork,
+  useProductSelection,
+  usePlacementClipShape,
+} from "./hooks/useProductPage";
+export type { ProductPageContext, ProviderStatus } from "./hooks/useProductPage";
+
+// Visibility - Shared IntersectionObserver pool for efficient multi-element observation
+export * from "./hooks/visibility";
+
+// Viewport - Consolidated viewport handling hooks for responsive layouts
+export * from "./hooks/viewport";
+
+// Services - Singletons for zero-lag canvas operations
+export { canvasExportService } from "./services/CanvasExportService";
+export type { CanvasExportServiceConfig } from "./services/CanvasExportService";
+
+// Components - Isolation boundaries for performance
+export { CanvasIsolationBoundary, CanvasIsolationConfigurator, useIsolatedCanvas } from "./components/CanvasIsolationBoundary";
+export { LoadingOverlayPrism, useLoadingOverlay } from "./components/LoadingOverlayPrism";
+export type { LoadingOverlayPrismProps } from "./components/LoadingOverlayPrism";
+
+// Re-export realtime mockup hook from SDK for convenience
+export { useRealtimeMockup } from "@snowcone-app/sdk/react";
+export type { UseRealtimeMockupOptions } from "@snowcone-app/sdk/react";
+
+// Re-export commonly used SDK functions for convenience
+export { getProduct, listProducts, getMockupUrl } from "@snowcone-app/sdk";
+export type { WebSocketConfig } from "@snowcone-app/sdk";
+
+// Patterns - Context providers and shared patterns
+export * from "./patterns/ShopProvider";
+export { useShopOptional } from "./patterns/ShopProvider";
+export * from "./patterns/Product";
+export type { PlacementDesign, Artwork } from "./patterns/Product";
+// RealtimeProvider - separate context for realtime mockup updates (prevents re-render cascades)
+export {
+  RealtimeProvider,
+  useRealtime,
+  useRealtimeOptional,
+} from "./patterns/RealtimeProvider";
+export type {
+  RealtimeContextValue,
+  RealtimeProviderProps,
+  MockupResult,
+  RealtimeState,
+} from "./patterns/RealtimeProvider";
+
+// MockupPriorityProvider - priority-based mockup rendering coordination
+export {
+  MockupPriorityProvider,
+  useMockupPriority,
+  useMockupPriorityOptional,
+} from "./patterns/MockupPriorityProvider";
+export type {
+  MockupPriorityContextValue,
+  MockupPriorityProviderProps,
+  PriorityLevel,
+} from "./patterns/MockupPriorityProvider";
+
+// ProductPageProvider - Quick-start providers for product pages
+export {
+  ProductPageProvider,
+  ProductPageProviderMinimal,
+} from "./patterns/ProductPageProvider";
+export type {
+  ProductPageProviderProps,
+  ProductPageProviderMinimalProps,
+} from "./patterns/ProductPageProvider";
+
+
+// Composed - Product-related composed components (moved from product/)
+export * from "./composed/ProductImage";
+export type { RegularArtwork, SeamlessPattern, Artwork as ProductImageArtwork, AspectRatio } from "./composed/ProductImage";
+// Export ArtAlignment for advanced use cases (prefer ArtworkCustomizer for most cases)
+export * from "./composed/ArtAlignment";
+export * from "./composed/ArtworkCustomizer";
+export type { ArtworkCustomizerProps } from "./composed/ArtworkCustomizer";
+// TEMPORARY: Canvas editor mockup for testing
+export * from "./composed/CanvasEditor";
+export * from "./composed/HeroProductImage";
+
+// Re-export types from SDK for convenience
+export type {
+  ProductPlacement,
+  ProductVariant,
+  ProductMockupData,
+  ArtworkData,
+  ImageAlignment,
+  ProductData,
+  ProductArtAlignmentOptions,
+  ProductArtAlignmentContext,
+} from "@snowcone-app/sdk";
+
+// Re-export utility functions from SDK that are commonly used with React components
+export {
+  describeProductArtAlignment,
+  getSnapPoints,
+} from "@snowcone-app/sdk";
+
+// Search - Composable search components for InstantSearch + Meilisearch
+export * from "./composed/search";
+
+// Zoom - Responsive image zoom components
+export * from "./composed/zoom";
+
+// Carousels - Production-grade image carousels for product display
+export * from "./composed/carousels";
+
+// Grids - Layout primitives for grid-based displays
+export * from "./composed/grids";
+
+// Development utilities (tree-shaken in production)
+export {
+  runConfigChecks,
+  checkTailwindConfig,
+  checkThemeTokens,
+  checkComponentStyles,
+} from "./utils/dev-warnings";
+
+// Theme system — import from "@snowcone-app/ui/themes" for runtime theme switching.
+// For CSS-only theming, use defaults.css instead. See CUSTOMIZATION.md.
+// Types re-exported here for convenience:
+export type { ThemeConfig, ThemePreset, FontPairing } from "./themes";
+
+// Layouts - Pre-built layout patterns
+export * from "./layouts";
+
+// Design System - Visual reference for theme tokens
+export * from "./design-system";
+
+// Personalization - Buyer customization system for product designs
+export * from "./personalization";