@snowcone-app/ui 0.1.43 → 0.2.0

package/src/patterns/RealtimeProvider.tsx

@@ -0,0 +1,1162 @@
+"use client";
+
+/**
+ * RealtimeProvider - Separate context for realtime mockup state
+ *
+ * This provider is intentionally SEPARATE from ProductContext to prevent
+ * mockup result updates from causing re-renders in components that only
+ * care about product selection (options, price, etc.).
+ *
+ * Architecture:
+ * - RealtimeProvider wraps components that need realtime mockup updates
+ * - It subscribes to ProductContext for product data but manages its own state
+ * - Updates to mockupResults only re-render RealtimeContext consumers
+ * - ProductContext consumers are NOT affected by realtime updates
+ *
+ * Usage:
+ * ```tsx
+ * <Product productId="...">
+ *   <ProductOptions />  {/* Not affected by realtime updates *\/}
+ *   <ProductPrice />    {/* Not affected by realtime updates *\/}
+ *
+ *   <RealtimeProvider>
+ *     <HeroProductImage />  {/* Receives realtime updates *\/}
+ *     <CanvasEditor />      {/* Can send canvas blobs *\/}
+ *   </RealtimeProvider>
+ * </Product>
+ * ```
+ */
+
+import React, {
+  createContext,
+  useContext,
+  useState,
+  useEffect,
+  useCallback,
+  useRef,
+  useMemo,
+} from "react";
+import { useRealtimeMockup } from "@snowcone-app/sdk/react";
+import { resolveVariantId as resolveVariantIdUtil } from "@snowcone-app/sdk";
+import { readEnv } from "../lib/env";
+import { useProductOptional } from "./Product";
+import type { ReactProductContext } from "./Product";
+
+// Default artboard size for export calculations (matches @snowcone-app/canvas default)
+const DEFAULT_ARTBOARD_SIZE = 2000;
+
+// CANVAS_EXPORT_THROTTLE_MS removed - throttling now handled by @snowcone-app/canvas
+
+// iOS Safari has strict blob URL limits (~50-100 concurrent)
+// Enforce a conservative cap to prevent memory crashes
+const MAX_CONCURRENT_BLOBS = 5;
+
+// Realtime mockup types
+export interface MockupResult {
+  mockupId: string;
+  imageUrl: string;
+}
+
+// Type alias for backward compatibility with code that imported RealtimeState from Product
+export type RealtimeState = RealtimeContextValue;
+
+export interface RealtimeContextValue {
+  // Connection state
+  isEnabled: boolean;
+  isConnected: boolean;
+  isConfigured: boolean;
+
+  // Mockup results (use subscriptions for performance-critical components)
+  mockupResults: MockupResult[];
+
+  // Debug/tracking state (now refs, won't trigger re-renders)
+  isPendingMockups: boolean;
+  canvasBlobsSent: number;
+  colorBlobsSent: number;
+  lastBlobSentTime: string | null;
+
+  // Configuration
+  canvasExportSize: { width: number; height: number };
+  mockupWidth: number;
+  placementDimensions: Array<{
+    label: string;
+    width?: number;
+    height?: number;
+    type: string;
+  }>;
+
+  // Methods
+  enableRealtime: () => void;
+  disableRealtime: () => void;
+  sendCanvasBlob: (
+    placement: string,
+    blob: Blob,
+    mockupCount?: number,
+    baseThrottleMs?: number
+  ) => boolean;
+
+  /** Send canvas state JSON for server-side rendering (used by SnowconeCanvas JSON mode) */
+  sendCanvasState: (
+    placement: string,
+    state: object,
+    mockupCount?: number,
+    baseThrottleMs?: number
+  ) => boolean;
+
+  /**
+   * Update mockupIds to render specific mockups using cached blobs.
+   * Server will use already-uploaded blobs to render the requested mockups.
+   * This is the preferred method for priority-based rendering.
+   */
+  updateMockupIds: (mockupIds: string[]) => boolean;
+
+  /**
+   * Update placementSettings to override scaleMode, alignment, etc.
+   * Used to force scaleMode: "fill" when canvas editor exports images.
+   */
+  updatePlacementSettings: (settings: Record<string, { scaleMode?: 'fill' | 'fit'; tiles?: number; alignment?: string }>) => boolean;
+
+  // PERFORMANCE: Direct access without state updates
+  getMockupResultsImmediate: () => MockupResult[];
+
+  // PERFORMANCE: Subscription system for immediate notifications
+  subscribeMockupResults: (
+    callback: (results: MockupResult[]) => void
+  ) => () => void;
+
+  // PERFORMANCE: Filtered subscription for specific mockupId
+  subscribeMockupResultById: (
+    mockupId: string,
+    callback: (result: MockupResult) => void
+  ) => () => void;
+
+  // PERFORMANCE: Subscribe to pending blob notifications (for shimmer effects)
+  subscribePendingBlob: (
+    callback: (placement: string) => void
+  ) => () => void;
+
+  /**
+   * Notify that an export is starting for a placement.
+   * Call this immediately when a canvas change is detected to show shimmer
+   * before the export and network request complete.
+   */
+  notifyPendingExport: (placement: string) => void;
+
+  /**
+   * Notify that a previously-pending export was skipped or cancelled (e.g. the
+   * canvas decided the change is a no-op — `skipBlob=true` with no JSON sent).
+   * Clears the optimistic pending-state from `notifyPendingExport` so consumers
+   * subscribed via `subscribePendingExportCancelled` can drop their loading
+   * indicators without waiting for a server result that will never arrive.
+   */
+  notifyPendingExportCancelled: (placement: string) => void;
+
+  /**
+   * Subscribe to "previously-pending export was cancelled" notifications.
+   * Pairs with `subscribePendingBlob` — when an optimistic pending fires but
+   * the actual export turns out to be a no-op, this fires so subscribers can
+   * roll back their pending UI state.
+   */
+  subscribePendingExportCancelled: (
+    callback: (placement: string) => void
+  ) => () => void;
+
+  /**
+   * Subscribe to blob received notifications (when server confirms blob receipt).
+   * Use this to trigger mockup requests only after the server has the new blob.
+   */
+  subscribeBlobReceived: (
+    callback: (placement: string) => void
+  ) => () => void;
+
+  /**
+   * Subscribe to blob sent notifications (when blob is actually sent after throttle).
+   * Use this to trigger mockup requests - more reliable than blob_received for
+   * subsequent blobs to the same placement.
+   */
+  subscribeBlobSent: (
+    callback: (placement: string) => void
+  ) => () => void;
+
+  // Flush pending blobs immediately (call on mouse up, action complete, etc.)
+  flushPendingBlobs: () => void;
+  hasPendingBlobs: () => boolean;
+
+  subscribePipelineSettled: (callback: () => void) => () => void;
+  resetPipelineSettled: () => void;
+
+
+  // ============================================================================
+  // CENTRALIZED URL MANAGEMENT (NEW)
+  // ============================================================================
+
+  /**
+   * Get the current mockup URL for a given mockupId.
+   * Returns the realtime URL if available, null otherwise.
+   * Components should use this instead of subscribing directly.
+   */
+  getMockupUrl: (mockupId: string) => string | null;
+
+  // WebRTC streaming (Phase 2)
+
+  // Pipeline timing (debug)
+  subscribeRTCTiming: (callback: (timing: any) => void) => () => void;
+
+  /**
+   * Get multiple mockup URLs at once.
+   * Returns a record mapping mockupId to URL (or null if not available).
+   */
+  getMockupUrls: (mockupIds: string[]) => Record<string, string | null>;
+
+  /**
+   * Check if a mockup is currently loading (pending export/render).
+   * Use this to show shimmer/loading states.
+   */
+  isMockupLoading: (mockupId: string) => boolean;
+
+  /**
+   * Register a blob URL with centralized lifecycle management.
+   * Creates a blob URL if given a Blob, or stores the URL directly.
+   * Enforces MAX_CONCURRENT_BLOBS limit, revoking oldest URL when exceeded.
+   * @param blobOrUrl - Blob to create URL from, or existing URL string
+   * @param placementName - Optional placement name for tracking
+   * @returns The blob URL (created or passed through)
+   */
+  registerBlobUrl: (blobOrUrl: Blob | string, placementName?: string) => string;
+}
+
+const RealtimeContext = createContext<RealtimeContextValue | undefined>(
+  undefined
+);
+
+export interface RealtimeProviderProps {
+  children: React.ReactNode;
+  /** WebSocket URL for realtime mockups */
+  wsUrl?: string;
+  /** Width for realtime mockup generation */
+  mockupWidth?: number;
+  /** Auto-enable realtime on mount (default: false) */
+  autoEnable?: boolean;
+  /** The shop (publishable key = shop.id) the session bills to. */
+  shop?: string;
+  /**
+   * Endpoint that issues a realtime session grant (POST { shop } →
+   * { token, expiresAt }). When this + shop are set, the session authorizes
+   * via a renewable token. Without them, the legacy seal path runs (shim).
+   */
+  grantUrl?: string;
+}
+
+/**
+ * RealtimeProvider - Manages realtime mockup WebSocket connection
+ *
+ * Must be used inside a <Product> provider to access product data.
+ */
+export function RealtimeProvider({
+  children,
+  // Leave undefined when the env var isn't set so useRealtimeMockup's grant-path
+  // default (the public endpoint) applies. Pass wsUrl explicitly to self-host.
+  wsUrl = readEnv("NEXT_PUBLIC_MERCH_WS_URL"),
+  mockupWidth = 1400,
+  autoEnable = false,
+  shop,
+  grantUrl,
+}: RealtimeProviderProps) {
+  const productContext = useProductOptional();
+
+  const [isEnabled, setIsEnabled] = useState(autoEnable);
+
+  // When a shop + grant endpoint are wired, authorize the session with a
+  // renewable token instead of the legacy bypass seal. Stable identity.
+  const useSessionGrant = Boolean(shop && grantUrl);
+  const getToken = useCallback(async () => {
+    const res = await fetch(grantUrl as string, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ shop }),
+    });
+    if (!res.ok) {
+      throw new Error(`realtime grant failed: ${res.status}`);
+    }
+    return (await res.json()) as { token: string; expiresAt: number };
+  }, [shop, grantUrl]);
+
+  // Use refs for debug/tracking state to avoid re-renders during drag
+  const canvasBlobsSentRef = useRef(0);
+  const colorBlobsSentRef = useRef(0);
+  const lastBlobSentTimeRef = useRef<string | null>(null);
+  const isPendingMockupsRef = useRef(false);
+
+  // Track if config has been sent
+  const configSentRef = useRef(false);
+
+  // Track placement settings overrides (e.g., scaleMode: "fill" when canvas editor active)
+  const placementSettingsOverridesRef = useRef<Record<string, any>>({});
+
+  // Track last sent variantId to detect when we need to re-send config
+  const lastSentVariantIdRef = useRef<string | null>(null);
+
+  // Track last sent colors to prevent duplicates
+  const lastSentColorsRef = useRef<Record<string, string>>({});
+
+  // Initialize realtime mockup hook
+  const realtimeMockup = useRealtimeMockup({
+    wsUrl,
+    getToken: useSessionGrant ? getToken : undefined,
+    onConnected: (sessionId) => {
+    },
+    onDisconnected: () => {
+    },
+    onConfigReceived: () => {
+    },
+    onBlobReceived: (placement) => {
+      const subscriberCount = blobReceivedSubscribersRef.current.size;
+      // Notify all blob received subscribers (for priority-based mockup requests)
+      blobReceivedSubscribersRef.current.forEach((cb) => {
+        cb(placement);
+      });
+    },
+    onBlobSent: (placement) => {
+      if (blobQueuedGenRef.current === pipelineGenRef.current) {
+        hasBlobInFlightRef.current = true;
+      }
+      blobSentSubscribersRef.current.forEach((cb) => {
+        cb(placement);
+      });
+    },
+    onMockupRendered: (result) => {
+    },
+    onAllMockupsRendered: (results) => {
+    },
+    onError: (error) => {
+      console.error("[RealtimeProvider] Error:", error);
+    },
+  });
+
+  // RTC timing subscription (legacy — kept for API compatibility)
+  const subscribeRTCTiming = useCallback((_callback: (timing: any) => void) => {
+    return () => {}; // No-op since WebRTC was removed
+  }, []);
+
+  const {
+    isConnected,
+    isConfigured,
+    mockupResults: rawMockupResults,
+    sendCanvasBlob: sendCanvasBlobRaw,
+    sendCanvasState: sendCanvasStateRaw,
+    sendColorBlob,
+    sendConfig: sendConfigRaw,
+    updateMockupIds: updateMockupIdsRaw,
+    updatePlacementSettings: updatePlacementSettingsRaw,
+    connect,
+    disconnect,
+    flushPendingBlobs,
+    hasPendingBlobs,
+  } = realtimeMockup;
+
+  // PERFORMANCE: Store mockup results in ref only - NO STATE UPDATES
+  // This eliminates re-render cascades entirely. Components that need mockup results
+  // should use subscribeMockupResults() or subscribeMockupResultById() for immediate updates.
+  // The mockupResults on context is provided for backward compat but reads from ref.
+  const mockupResultsRef = useRef<MockupResult[]>([]);
+
+  // Subscription system for immediate mockup notifications
+  const mockupSubscribersRef = useRef<Set<(results: MockupResult[]) => void>>(
+    new Set()
+  );
+
+  // Filtered subscription system by mockupId
+  const mockupSubscribersByIdRef = useRef<
+    Map<string, Set<(result: MockupResult) => void>>
+  >(new Map());
+
+  // Subscription system for pending blob notifications (for shimmer effects)
+  const pendingExportCancelledSubscribersRef = useRef<
+    Set<(placement: string) => void>
+  >(new Set());
+
+  const pendingBlobSubscribersRef = useRef<Set<(placement: string) => void>>(
+    new Set()
+  );
+
+  // Subscription system for blob received notifications (when server confirms receipt)
+  const blobReceivedSubscribersRef = useRef<Set<(placement: string) => void>>(
+    new Set()
+  );
+
+  // Subscription system for blob sent notifications (when blob is actually sent after throttle)
+  const blobSentSubscribersRef = useRef<Set<(placement: string) => void>>(
+    new Set()
+  );
+
+
+  // ============================================================================
+  // CENTRALIZED URL MANAGEMENT (NEW)
+  // ============================================================================
+
+  // Pipeline-settled: fires when no pending blobs AND mockup results arrived since last send.
+  const pipelineSettledSubscribersRef = useRef<Set<() => void>>(new Set());
+  const pipelineGenRef = useRef(0);
+  const blobQueuedGenRef = useRef(0);
+  const hasBlobInFlightRef = useRef(false);
+  const pipelineResetCooldownRef = useRef(false);
+
+  // Centralized mockup URL cache - stores URLs by mockupId
+  // This is the single source of truth for all mockup URLs (realtime or static)
+  const mockupUrlCacheRef = useRef<Map<string, {
+    url: string;
+    isBlob: boolean;
+    timestamp: number;
+  }>>(new Map());
+
+  // Track all registered blob URLs for memory management
+  // Uses insertion order to determine oldest URL for eviction
+  const registeredBlobUrlsRef = useRef<Set<string>>(new Set());
+
+  // Track which placements have pending exports (for shimmer state)
+  const pendingPlacementsRef = useRef<Set<string>>(new Set());
+
+  // Track which mockupIds are pending (derived from placements)
+  const pendingMockupIdsRef = useRef<Set<string>>(new Set());
+
+  // Sync rawMockupResults to ref, update URL cache, and notify subscribers (NO STATE UPDATES)
+  useEffect(() => {
+    if (rawMockupResults.length === 0) {
+      if (mockupResultsRef.current.length > 0) {
+        mockupResultsRef.current = [];
+        mockupSubscribersRef.current.forEach((cb) => cb([]));
+      }
+      return;
+    }
+
+    console.log(`[RTP] rawMockupResults changed: ${rawMockupResults.length} result(s)`, rawMockupResults.map(r => `${r.mockupId}${r.imageUrl ? ' ✓url' : ' ✗NO-URL'}`));
+
+    // Update ref immediately
+    mockupResultsRef.current = rawMockupResults;
+
+    // Update centralized URL cache with new results
+    const now = Date.now();
+    rawMockupResults.forEach((result) => {
+      if (result.imageUrl) {
+        const wasPending = pendingMockupIdsRef.current.has(result.mockupId);
+        mockupUrlCacheRef.current.set(result.mockupId, {
+          url: result.imageUrl,
+          isBlob: false, // Server URLs are not blob URLs
+          timestamp: now,
+        });
+
+        // Clear pending state for this mockup
+        pendingMockupIdsRef.current.delete(result.mockupId);
+        if (wasPending) {
+          console.log(`[RTP] Cleared pending for ${result.mockupId} — url cached`);
+        }
+      } else {
+        console.log(`[RTP] Result for ${result.mockupId} has NO imageUrl — not caching, pending NOT cleared`);
+      }
+    });
+
+    // Clear pending placement state so notifyPendingExport can re-fire on next edit.
+    // We clear based on result placements when available, otherwise clear all.
+    const clearedPlacements = new Set<string>();
+    rawMockupResults.forEach((result) => {
+      if (result.placement) clearedPlacements.add(result.placement);
+    });
+    if (clearedPlacements.size > 0) {
+      clearedPlacements.forEach((p) => pendingPlacementsRef.current.delete(p));
+    } else {
+      pendingPlacementsRef.current.clear();
+    }
+
+    // Notify subscribers immediately (no throttle needed - no state updates!)
+    mockupSubscribersRef.current.forEach((cb) => cb(rawMockupResults));
+
+    // Notify filtered subscribers
+    rawMockupResults.forEach((result) => {
+      const subscribers = mockupSubscribersByIdRef.current.get(result.mockupId);
+      if (subscribers && subscribers.size > 0) {
+        console.log(`[RTP] Notifying ${subscribers.size} subscriber(s) for ${result.mockupId}`);
+        subscribers.forEach((cb) => cb(result));
+      } else {
+        console.log(`[RTP] No subscribers for ${result.mockupId} — result received but nobody listening`);
+      }
+    });
+
+    // Pipeline-settled check
+    if (hasBlobInFlightRef.current && !hasPendingBlobs() && !pipelineResetCooldownRef.current) {
+      hasBlobInFlightRef.current = false;
+      pipelineSettledSubscribersRef.current.forEach((cb) => cb());
+    }
+  }, [rawMockupResults]);
+
+  // Wrap sendCanvasBlob to track when blobs are sent
+  const sendCanvasBlob = useCallback(
+    (
+      placement: string,
+      blob: Blob,
+      mockupCount?: number,
+      baseThrottleMs?: number
+    ) => {
+      blobQueuedGenRef.current = pipelineGenRef.current;
+      const result = sendCanvasBlobRaw(
+        placement,
+        blob,
+        mockupCount,
+        baseThrottleMs
+      );
+      if (result) {
+        canvasBlobsSentRef.current += 1;
+        lastBlobSentTimeRef.current = new Date().toLocaleTimeString();
+        isPendingMockupsRef.current = true;
+        // Notify pending blob subscribers (for shimmer effects)
+        pendingBlobSubscribersRef.current.forEach((cb) => cb(placement));
+      }
+      return result;
+    },
+    [sendCanvasBlobRaw]
+  );
+
+  // Wrap sendCanvasState for JSON mode (server-side canvas rendering)
+  const sendCanvasState = useCallback(
+    (
+      placement: string,
+      state: object,
+      mockupCount?: number,
+      baseThrottleMs?: number
+    ) => {
+      blobQueuedGenRef.current = pipelineGenRef.current;
+      const result = sendCanvasStateRaw(
+        placement,
+        state,
+        mockupCount,
+        baseThrottleMs
+      );
+      if (result) {
+        canvasBlobsSentRef.current += 1;
+        lastBlobSentTimeRef.current = new Date().toLocaleTimeString();
+        isPendingMockupsRef.current = true;
+        pendingBlobSubscribersRef.current.forEach((cb) => cb(placement));
+      }
+      return result;
+    },
+    [sendCanvasStateRaw]
+  );
+
+  // Wrap sendColorBlob to track when colors are sent
+  const sendColorBlobTracked = useCallback(
+    (placement: string, color: string) => {
+      const result = sendColorBlob(placement, color);
+      if (result) {
+        colorBlobsSentRef.current += 1;
+        lastBlobSentTimeRef.current = new Date().toLocaleTimeString();
+        isPendingMockupsRef.current = true;
+      }
+      return result;
+    },
+    [sendColorBlob]
+  );
+
+  // Connect when enabled
+  useEffect(() => {
+    if (isEnabled) {
+      connect();
+
+      return () => {
+        disconnect();
+        configSentRef.current = false;
+        lastSentVariantIdRef.current = null;
+        lastSentColorsRef.current = {};
+      };
+    }
+  }, [isEnabled, connect, disconnect, wsUrl]);
+
+  // Clear pending state when mockup results arrive
+  useEffect(() => {
+    if (rawMockupResults.length > 0 && isPendingMockupsRef.current) {
+      isPendingMockupsRef.current = false;
+    }
+  }, [rawMockupResults.length]);
+
+  // Auto-send config when connected and product is available
+  // Also re-send when variantId changes (e.g., user selects different product options)
+  useEffect(() => {
+    if (!isEnabled || !isConnected || !productContext?.product) return;
+
+    const product = productContext.product;
+    const productId = product.id;
+    const placements = product.placements || [];
+
+    // Resolve variant ID based on current selection
+    const variantId = resolveVariantIdUtil(
+      productContext,
+      undefined,
+      undefined
+    );
+
+    // Check if we need to send config:
+    // 1. First time (configSentRef.current is false)
+    // 2. VariantId changed (user selected different options)
+    const isFirstSend = !configSentRef.current;
+    const variantChanged = lastSentVariantIdRef.current !== null &&
+                           lastSentVariantIdRef.current !== variantId;
+
+    if (!isFirstSend && !variantChanged) {
+      return; // Nothing changed, skip
+    }
+
+    // Get mockup IDs from product.mockups
+    const mockupIds: string[] = [];
+    if (product.mockups && Array.isArray(product.mockups)) {
+      product.mockups.forEach((mockup: any) => {
+        if (mockup.id) {
+          mockupIds.push(mockup.id);
+        }
+      });
+    }
+
+    // Authed sessions: the grant token (verified on connect) authorizes the
+    // session and the server self-signs the render, so no seal is sent and the
+    // server bills to the token's shop. Otherwise fall back to the legacy
+    // bypass seal + demo shop (shim) so existing setups keep working.
+    const configPayload = useSessionGrant
+      ? {
+          productId,
+          mockupIds,
+          variantId,
+          shop: shop as string,
+          width: mockupWidth,
+          placementSettings: { ...placementSettingsOverridesRef.current },
+        }
+      : {
+          productId,
+          mockupIds,
+          variantId,
+          shop: "hTidnpNnNa",
+          seal: "bypass-sig-for-k6-load-test",
+          width: mockupWidth,
+          placementSettings: { ...placementSettingsOverridesRef.current },
+        };
+
+    // If variant changed, trigger shimmer on all image placements
+    // This provides immediate visual feedback while waiting for new mockups
+    if (variantChanged) {
+      const imagePlacements = placements.filter((p: any) => p.type === "image");
+      imagePlacements.forEach((p: any) => {
+        pendingBlobSubscribersRef.current.forEach((cb) => cb(p.label));
+      });
+    }
+
+    sendConfigRaw(configPayload);
+
+    configSentRef.current = true;
+    lastSentVariantIdRef.current = variantId;
+
+    // Send default colors for color placements
+    setTimeout(() => {
+      const colorPlacements = placements.filter((p: any) => p.type === "color");
+      colorPlacements.forEach((p: any) => {
+        const defaultColor = productContext?.selection?.[p.label] || "#000000";
+        if (lastSentColorsRef.current[p.label] !== defaultColor) {
+          sendColorBlobTracked(p.label, defaultColor);
+          lastSentColorsRef.current[p.label] = defaultColor;
+        }
+      });
+    }, 600);
+  }, [
+    isEnabled,
+    isConnected,
+    productContext?.product,
+    productContext?.selection,
+    sendConfigRaw,
+    sendColorBlobTracked,
+    mockupWidth,
+  ]);
+
+  // Watch for color placement changes
+  useEffect(() => {
+    if (!isEnabled || !isConnected || !isConfigured || !productContext?.product)
+      return;
+
+    const placements = productContext.product.placements || [];
+    const colorPlacements = placements.filter((p: any) => p.type === "color");
+
+    const debounceTimeout = setTimeout(() => {
+      colorPlacements.forEach((p: any) => {
+        const selectedColor = productContext?.selection?.[p.label];
+        if (selectedColor && typeof selectedColor === "string") {
+          if (lastSentColorsRef.current[p.label] !== selectedColor) {
+            sendColorBlobTracked(p.label, selectedColor);
+            lastSentColorsRef.current[p.label] = selectedColor;
+          }
+        }
+      });
+    }, 500);
+
+    return () => clearTimeout(debounceTimeout);
+  }, [
+    isEnabled,
+    isConnected,
+    isConfigured,
+    productContext?.product,
+    productContext?.selection,
+    sendColorBlobTracked,
+  ]);
+
+  // Canvas integration uses @snowcone-app/canvas with sendCanvasBlob directly
+
+  // Wrap updatePlacementSettings to also track in ref (for config re-sends)
+  const updatePlacementSettingsWrapped = useCallback(
+    (settings: Record<string, any>) => {
+      placementSettingsOverridesRef.current = settings;
+      return updatePlacementSettingsRaw(settings);
+    },
+    [updatePlacementSettingsRaw]
+  );
+
+  const enableRealtime = useCallback(() => {
+    setIsEnabled(true);
+  }, []);
+
+  const disableRealtime = useCallback(() => {
+    setIsEnabled(false);
+  }, []);
+
+  // Calculate placement dimensions from product
+  const placementDimensions = useMemo(() => {
+    if (!productContext?.product?.placements) return [];
+    return productContext.product.placements.map((p: any) => ({
+      label: p.label,
+      width: p.width,
+      height: p.height,
+      type: p.type || "image",
+    }));
+  }, [productContext?.product?.placements]);
+
+  // Get canvas export size
+  const canvasExportSize = useMemo(() => {
+    const firstPlacement = productContext?.product?.placements?.[0];
+    if (firstPlacement?.width && firstPlacement?.height) {
+      return { width: firstPlacement.width, height: firstPlacement.height };
+    }
+
+    return { width: DEFAULT_ARTBOARD_SIZE, height: DEFAULT_ARTBOARD_SIZE };
+  }, [productContext?.product?.placements]);
+
+  // Subscribe functions
+  const subscribeMockupResults = useCallback(
+    (callback: (results: MockupResult[]) => void) => {
+      mockupSubscribersRef.current.add(callback);
+      return () => {
+        mockupSubscribersRef.current.delete(callback);
+      };
+    },
+    []
+  );
+
+  const subscribeMockupResultById = useCallback(
+    (mockupId: string, callback: (result: MockupResult) => void) => {
+      if (!mockupSubscribersByIdRef.current.has(mockupId)) {
+        mockupSubscribersByIdRef.current.set(mockupId, new Set());
+      }
+      mockupSubscribersByIdRef.current.get(mockupId)!.add(callback);
+      const subscriberCount = mockupSubscribersByIdRef.current.get(mockupId)!.size;
+      console.log(`[RTP] subscribeMockupResultById("${mockupId}"): now ${subscriberCount} subscriber(s)`);
+
+      // Check current results immediately
+      const currentResult = mockupResultsRef.current.find(
+        (r) => r.mockupId === mockupId
+      );
+      if (currentResult) {
+        console.log(`[RTP] subscribeMockupResultById("${mockupId}"): replaying cached result (hasUrl=${!!currentResult.imageUrl})`);
+        callback(currentResult);
+      }
+
+      return () => {
+        const subscribers = mockupSubscribersByIdRef.current.get(mockupId);
+        if (subscribers) {
+          subscribers.delete(callback);
+          if (subscribers.size === 0) {
+            mockupSubscribersByIdRef.current.delete(mockupId);
+          }
+        }
+      };
+    },
+    []
+  );
+
+  // Subscribe to pending blob notifications (for shimmer effects)
+  const subscribePendingBlob = useCallback(
+    (callback: (placement: string) => void) => {
+      pendingBlobSubscribersRef.current.add(callback);
+      return () => {
+        pendingBlobSubscribersRef.current.delete(callback);
+      };
+    },
+    []
+  );
+
+  // Subscribe to pending-export-cancelled notifications. Fires when an
+  // optimistic `notifyPendingExport` turns out to have been wrong (the actual
+  // export was a no-op).
+  const subscribePendingExportCancelled = useCallback(
+    (callback: (placement: string) => void) => {
+      pendingExportCancelledSubscribersRef.current.add(callback);
+      return () => {
+        pendingExportCancelledSubscribersRef.current.delete(callback);
+      };
+    },
+    []
+  );
+
+  // Subscribe to blob received notifications (when server confirms receipt)
+  const subscribeBlobReceived = useCallback(
+    (callback: (placement: string) => void) => {
+      blobReceivedSubscribersRef.current.add(callback);
+      return () => {
+        blobReceivedSubscribersRef.current.delete(callback);
+      };
+    },
+    []
+  );
+
+  // Subscribe to blob sent notifications (when blob is actually sent after throttle)
+  const subscribeBlobSent = useCallback(
+    (callback: (placement: string) => void) => {
+      blobSentSubscribersRef.current.add(callback);
+      return () => {
+        blobSentSubscribersRef.current.delete(callback);
+      };
+    },
+    []
+  );
+
+  const subscribePipelineSettled = useCallback(
+    (callback: () => void) => {
+      pipelineSettledSubscribersRef.current.add(callback);
+      return () => {
+        pipelineSettledSubscribersRef.current.delete(callback);
+      };
+    },
+    []
+  );
+
+  const resetPipelineSettled = useCallback(() => {
+    pipelineGenRef.current++;
+    hasBlobInFlightRef.current = false;
+    pipelineResetCooldownRef.current = true;
+    requestAnimationFrame(() => {
+      pipelineResetCooldownRef.current = false;
+    });
+  },
+    []
+  );
+
+
+  // Notify that an export is starting (called from external canvas components)
+  // This fires immediately when a change is detected, before the export completes
+  const notifyPendingExport = useCallback(
+    (placement: string) => {
+      // Skip if this placement is already pending — avoids spamming subscribers
+      // on every canvas change during drag
+      if (pendingPlacementsRef.current.has(placement)) {
+        return;
+      }
+
+      // Track pending placement
+      pendingPlacementsRef.current.add(placement);
+
+      // Also track pending mockupIds for this placement
+      const pendingIds: string[] = [];
+      if (productContext?.product?.mockups) {
+        productContext.product.mockups.forEach((mockup: any) => {
+          if (mockup.placement === placement || !mockup.placement) {
+            pendingMockupIdsRef.current.add(mockup.id);
+            pendingIds.push(mockup.id);
+          }
+        });
+      }
+      console.log(`[RTP] notifyPendingExport("${placement}"): marked ${pendingIds.length} mockup(s) pending — [${pendingIds.slice(0, 5).join(', ')}${pendingIds.length > 5 ? '...' : ''}]`);
+
+      pendingBlobSubscribersRef.current.forEach((cb) => cb(placement));
+    },
+    [productContext?.product?.mockups]
+  );
+
+  // Roll back a previous notifyPendingExport when the actual export turned
+  // out to be a no-op. Clears the placement / mockup pending tracking and
+  // notifies cancellation subscribers so loading UI can be dismissed.
+  const notifyPendingExportCancelled = useCallback(
+    (placement: string) => {
+      // If we never marked this placement as pending, nothing to do.
+      if (!pendingPlacementsRef.current.has(placement)) {
+        return;
+      }
+      pendingPlacementsRef.current.delete(placement);
+
+      // Also clear any mockupIds we tagged for this placement.
+      const clearedIds: string[] = [];
+      if (productContext?.product?.mockups) {
+        productContext.product.mockups.forEach((mockup: any) => {
+          if (mockup.placement === placement || !mockup.placement) {
+            if (pendingMockupIdsRef.current.has(mockup.id)) {
+              pendingMockupIdsRef.current.delete(mockup.id);
+              clearedIds.push(mockup.id);
+            }
+          }
+        });
+      }
+      console.log(
+        `[RTP] notifyPendingExportCancelled("${placement}"): cleared ${clearedIds.length} mockup(s) — [${clearedIds.slice(0, 5).join(", ")}${clearedIds.length > 5 ? "..." : ""}]`
+      );
+
+      pendingExportCancelledSubscribersRef.current.forEach((cb) => cb(placement));
+    },
+    [productContext?.product?.mockups]
+  );
+
+  // ============================================================================
+  // CENTRALIZED URL MANAGEMENT METHODS (NEW)
+  // ============================================================================
+
+  /**
+   * Get mockup URL from centralized cache
+   * Returns null if the mockup is currently pending (new export in progress)
+   * This prevents stale mockups from being displayed during artwork changes
+   */
+  const getMockupUrl = useCallback((mockupId: string): string | null => {
+    // Return null for pending mockups to avoid showing stale images
+    if (pendingMockupIdsRef.current.has(mockupId)) {
+      console.log(`[RTP] getMockupUrl("${mockupId}") → null (pending)`);
+      return null;
+    }
+    const cached = mockupUrlCacheRef.current.get(mockupId);
+    return cached?.url ?? null;
+  }, []);
+
+  /**
+   * Get multiple mockup URLs at once
+   * Returns null for any mockups that are currently pending
+   */
+  const getMockupUrls = useCallback((mockupIds: string[]): Record<string, string | null> => {
+    const result: Record<string, string | null> = {};
+    for (const mockupId of mockupIds) {
+      // Return null for pending mockups to avoid showing stale images
+      if (pendingMockupIdsRef.current.has(mockupId)) {
+        result[mockupId] = null;
+        continue;
+      }
+      const cached = mockupUrlCacheRef.current.get(mockupId);
+      result[mockupId] = cached?.url ?? null;
+    }
+    return result;
+  }, []);
+
+  /**
+   * Check if a mockup is currently loading
+   */
+  const isMockupLoading = useCallback((mockupId: string): boolean => {
+    return pendingMockupIdsRef.current.has(mockupId);
+  }, []);
+
+  /**
+   * Register a blob URL with lifecycle management
+   */
+  const registerBlobUrl = useCallback((blobOrUrl: Blob | string, placementName?: string): string => {
+    let url: string;
+
+    if (blobOrUrl instanceof Blob) {
+      // Enforce blob URL limit before creating new one
+      if (registeredBlobUrlsRef.current.size >= MAX_CONCURRENT_BLOBS) {
+        // Revoke oldest blob URL (first entry in Set maintains insertion order)
+        const oldest = registeredBlobUrlsRef.current.values().next().value;
+        if (oldest) {
+          URL.revokeObjectURL(oldest);
+          registeredBlobUrlsRef.current.delete(oldest);
+
+          // Also remove from URL cache if present
+          mockupUrlCacheRef.current.forEach((value, key) => {
+            if (value.url === oldest) {
+              mockupUrlCacheRef.current.delete(key);
+            }
+          });
+        }
+      }
+
+      url = URL.createObjectURL(blobOrUrl);
+      registeredBlobUrlsRef.current.add(url);
+    } else {
+      url = blobOrUrl;
+    }
+
+    return url;
+  }, []);
+
+  // Store subscription functions in refs so they remain stable across context recreations
+  // This prevents race conditions where notifications are lost during re-subscription
+  const subscribeMockupResultsRef = useRef(subscribeMockupResults);
+  const subscribeMockupResultByIdRef = useRef(subscribeMockupResultById);
+  const subscribePendingBlobRef = useRef(subscribePendingBlob);
+  const subscribeBlobReceivedRef = useRef(subscribeBlobReceived);
+  const subscribeBlobSentRef = useRef(subscribeBlobSent);
+  const subscribePipelineSettledRef = useRef(subscribePipelineSettled);
+  const subscribePendingExportCancelledRef = useRef(
+    subscribePendingExportCancelled,
+  );
+  subscribeMockupResultsRef.current = subscribeMockupResults;
+  subscribeMockupResultByIdRef.current = subscribeMockupResultById;
+  subscribePendingBlobRef.current = subscribePendingBlob;
+  subscribeBlobReceivedRef.current = subscribeBlobReceived;
+  subscribeBlobSentRef.current = subscribeBlobSent;
+  subscribePipelineSettledRef.current = subscribePipelineSettled;
+  subscribePendingExportCancelledRef.current = subscribePendingExportCancelled;
+
+  // Stable wrappers that delegate to the ref
+  const stableSubscribeMockupResults = useCallback(
+    (callback: (results: MockupResult[]) => void) => {
+      return subscribeMockupResultsRef.current(callback);
+    },
+    []
+  );
+
+  const stableSubscribeMockupResultById = useCallback(
+    (mockupId: string, callback: (result: MockupResult) => void) => {
+      return subscribeMockupResultByIdRef.current(mockupId, callback);
+    },
+    []
+  );
+
+  const stableSubscribePendingBlob = useCallback(
+    (callback: (placement: string) => void) => {
+      return subscribePendingBlobRef.current(callback);
+    },
+    []
+  );
+
+  const stableSubscribePendingExportCancelled = useCallback(
+    (callback: (placement: string) => void) => {
+      return subscribePendingExportCancelledRef.current(callback);
+    },
+    []
+  );
+
+  const stableSubscribeBlobReceived = useCallback(
+    (callback: (placement: string) => void) => {
+      return subscribeBlobReceivedRef.current(callback);
+    },
+    []
+  );
+
+  const stableSubscribeBlobSent = useCallback(
+    (callback: (placement: string) => void) => {
+      return subscribeBlobSentRef.current(callback);
+    },
+    []
+  );
+
+  const stableSubscribePipelineSettled = useCallback(
+    (callback: () => void) => {
+      return subscribePipelineSettledRef.current(callback);
+    },
+    []
+  );
+
+  // Create context value - STABLE reference when possible
+  // NOTE: mockupResults reads from ref - it won't trigger re-renders when mockups arrive.
+  // Components should use subscribeMockupResults() or subscribeMockupResultById() for reactive updates.
+  const contextValue = useMemo<RealtimeContextValue>(
+    () => ({
+      isEnabled,
+      isConnected,
+      isConfigured,
+      // Read from ref - this is a snapshot at render time, NOT reactive
+      // For reactive updates, use getMockupResultsImmediate() or subscribe functions
+      get mockupResults() {
+        return mockupResultsRef.current;
+      },
+      isPendingMockups: isPendingMockupsRef.current,
+      canvasBlobsSent: canvasBlobsSentRef.current,
+      colorBlobsSent: colorBlobsSentRef.current,
+      lastBlobSentTime: lastBlobSentTimeRef.current,
+      canvasExportSize,
+      mockupWidth,
+      placementDimensions,
+      enableRealtime,
+      disableRealtime,
+      sendCanvasBlob,
+      sendCanvasState,
+      updateMockupIds: updateMockupIdsRaw,
+      updatePlacementSettings: updatePlacementSettingsWrapped,
+      getMockupResultsImmediate: () => mockupResultsRef.current,
+      subscribeMockupResults: stableSubscribeMockupResults,
+      subscribeMockupResultById: stableSubscribeMockupResultById,
+      subscribePendingBlob: stableSubscribePendingBlob,
+      subscribeBlobReceived: stableSubscribeBlobReceived,
+      subscribeBlobSent: stableSubscribeBlobSent,
+      subscribePipelineSettled: stableSubscribePipelineSettled,
+      resetPipelineSettled,
+      notifyPendingExport,
+      notifyPendingExportCancelled,
+      subscribePendingExportCancelled: stableSubscribePendingExportCancelled,
+      flushPendingBlobs,
+      hasPendingBlobs,
+      // Centralized URL management
+      getMockupUrl,
+      getMockupUrls,
+      isMockupLoading,
+      registerBlobUrl,
+      // WebRTC streaming
+      subscribeRTCTiming,
+    }),
+    [
+      isEnabled,
+      isConnected,
+      isConfigured,
+      // mockupResults removed from deps - it's a getter that reads from ref
+      canvasExportSize,
+      mockupWidth,
+      placementDimensions,
+      enableRealtime,
+      disableRealtime,
+      sendCanvasBlob,
+      sendCanvasState,
+      updateMockupIdsRaw,
+      updatePlacementSettingsWrapped,
+      stableSubscribeMockupResults,
+      stableSubscribeMockupResultById,
+      notifyPendingExport,
+      notifyPendingExportCancelled,
+      stableSubscribePendingExportCancelled,
+      flushPendingBlobs,
+      hasPendingBlobs,
+      getMockupUrl,
+      getMockupUrls,
+      isMockupLoading,
+      registerBlobUrl,
+    ]
+  );
+
+  return (
+    <RealtimeContext.Provider value={contextValue}>
+      {children}
+    </RealtimeContext.Provider>
+  );
+}
+
+/**
+ * Hook to access realtime context
+ * Throws if not inside RealtimeProvider
+ */
+export function useRealtime(): RealtimeContextValue {
+  const context = useContext(RealtimeContext);
+  if (!context) {
+    throw new Error("useRealtime must be used within a RealtimeProvider");
+  }
+  return context;
+}
+
+/**
+ * Hook to optionally access realtime context
+ * Returns undefined if not inside RealtimeProvider
+ */
+export function useRealtimeOptional(): RealtimeContextValue | undefined {
+  return useContext(RealtimeContext);
+}