@snowcone-app/ui 0.1.43 → 0.2.1

package/src/services/CanvasExportService.ts

@@ -0,0 +1,518 @@
+/**
+ * CanvasExportService - Singleton for zero-lag canvas exports
+ *
+ * This service provides a STABLE callback reference for SnowconeCanvas's onExport prop.
+ * By keeping the callback outside React's render cycle, we prevent re-renders from
+ * causing canvas drag lag.
+ *
+ * Architecture:
+ * - The service holds mutable state (refs to functions and values)
+ * - React components configure the service via `configure()` on mount/updates
+ * - The `handleExport` method is a stable reference that never changes
+ * - During drag, canvas calls `handleExport` which reads current values from instance
+ *
+ * Memory Management (iOS Safari crash prevention):
+ * - Blob URLs are revoked immediately when new ones arrive
+ * - ImageBitmap cache is cleared when exiting editor mode
+ * - DataURL conversion is lazy (only on getLastExportedArtwork call, not every export)
+ *
+ * Usage:
+ * ```tsx
+ * // In your component
+ * useEffect(() => {
+ *   canvasExportService.configure({
+ *     sendCanvasBlob: productContext.sendCanvasBlob,
+ *     mockupCount: productContext.product?.mockups?.length ?? 1,
+ *     isRealtimeEnabled: productContext.realtime?.isEnabled ?? false,
+ *     onArtworkChange: (src) => setCurrentArtwork({ src, type: 'regular' }),
+ *   });
+ * }, [productContext.sendCanvasBlob, ...]);
+ *
+ * // Pass stable reference - never causes re-render
+ * <SnowconeCanvas onExport={canvasExportService.handleExport} />
+ * ```
+ */
+
+export interface CanvasExportServiceConfig {
+  /** Function to send blob to realtime mockup service (PNG mode) */
+  sendCanvasBlob?: (placement: string, blob: Blob, expectedMockupCount: number, throttleMs?: number) => void;
+  /** Function to send canvas state JSON to realtime mockup service (JSON mode — server-side rendering) */
+  sendCanvasState?: (placement: string, state: object, expectedMockupCount: number, throttleMs?: number) => boolean;
+  /**
+   * Function to serialize canvas onChange state to server render format.
+   * Pass `serializeStateForServer` from @snowcone-app/canvas.
+   * Required for JSON mode — if not provided, falls back to PNG mode.
+   */
+  serializeStateForServer?: (state: any) => any;
+  /** Number of mockups to expect (for throttling) */
+  mockupCount?: number;
+  /** Whether realtime mockups are enabled */
+  isRealtimeEnabled?: boolean;
+  /** Current placement name (e.g., "Front") */
+  placementName?: string;
+  /** Callback when artwork changes (called on exit from editor, not during drag) */
+  onArtworkChange?: (src: string) => void;
+  /** Enable realtime function (called when entering editor mode) */
+  enableRealtime?: () => void;
+  /** Disable realtime function (called when exiting editor mode) */
+  disableRealtime?: () => void;
+  /**
+   * Function to clear ImageBitmap cache (memory management for iOS Safari)
+   * Pass clearImageBitmapCache from @snowcone-app/canvas
+   */
+  clearImageBitmapCache?: () => void;
+  /**
+   * Called when handleExport runs but ends up sending nothing (skipBlob=true
+   * AND no JSON state was sent in this call). Pairs with the optimistic
+   * `notifyPendingExport` from RealtimeProvider so consumers (loading
+   * overlays, shimmer effects) can roll back state when an export turns out
+   * to be a no-op. Wire to `realtimeContext.notifyPendingExportCancelled`.
+   */
+  notifyExportSkipped?: (placement: string) => void;
+}
+
+class CanvasExportService {
+  // Configuration - updated by React components
+  private sendCanvasBlob: CanvasExportServiceConfig['sendCanvasBlob'] = undefined;
+  private sendCanvasState: CanvasExportServiceConfig['sendCanvasState'] = undefined;
+  private serializeStateForServer: CanvasExportServiceConfig['serializeStateForServer'] = undefined;
+  private mockupCount = 1;
+  private isRealtimeEnabled = false;
+  private placementName = 'Front';
+  private onArtworkChange: CanvasExportServiceConfig['onArtworkChange'] = undefined;
+  private enableRealtime: CanvasExportServiceConfig['enableRealtime'] = undefined;
+  private disableRealtime: CanvasExportServiceConfig['disableRealtime'] = undefined;
+  private clearImageBitmapCache: CanvasExportServiceConfig['clearImageBitmapCache'] = undefined;
+  private notifyExportSkipped: CanvasExportServiceConfig['notifyExportSkipped'] = undefined;
+
+  // Cache latest canvas state for replay when WS connects
+  private pendingCanvasState: any = null;
+  // Track whether JSON mode has successfully sent at least once
+  private jsonModeSentSuccessfully = false;
+
+  // Debounce state for handleStateChange
+  private stateChangeThrottleTimeout: ReturnType<typeof setTimeout> | null = null;
+  private stateChangeLastSendTime = 0;
+  /** How long to wait after last change before sending (quick discrete actions) */
+  private static SETTLE_MS = 300;
+  /** During continuous activity (drag), force a send at least this often */
+  private static MAX_WAIT_MS = 1000;
+
+  // Internal state for tracking exports
+  private lastExportedArtwork: string | null = null;
+  private initialArtwork: string | null = null;
+  private blobUrl: string | null = null;
+  // Store the last blob directly instead of converting to DataURL on every export
+  // This reduces memory pressure on iOS Safari - DataURL conversion creates large strings
+  private lastExportedBlob: Blob | null = null;
+
+  /**
+   * Configure the service with current values from React context.
+   * Call this in useEffect when context values change.
+   * This does NOT cause re-renders - it just updates internal state.
+   */
+  configure(config: CanvasExportServiceConfig): void {
+    if (config.sendCanvasBlob !== undefined) {
+      this.sendCanvasBlob = config.sendCanvasBlob;
+    }
+    if (config.sendCanvasState !== undefined) {
+      this.sendCanvasState = config.sendCanvasState;
+    }
+    if (config.serializeStateForServer !== undefined) {
+      this.serializeStateForServer = config.serializeStateForServer;
+    }
+    if (config.mockupCount !== undefined) {
+      this.mockupCount = config.mockupCount;
+    }
+    if (config.isRealtimeEnabled !== undefined) {
+      this.isRealtimeEnabled = config.isRealtimeEnabled;
+    }
+    if (config.placementName !== undefined) {
+      this.placementName = config.placementName;
+    }
+    if (config.onArtworkChange !== undefined) {
+      this.onArtworkChange = config.onArtworkChange;
+    }
+    if (config.enableRealtime !== undefined) {
+      this.enableRealtime = config.enableRealtime;
+    }
+    if (config.disableRealtime !== undefined) {
+      this.disableRealtime = config.disableRealtime;
+    }
+    if (config.clearImageBitmapCache !== undefined) {
+      this.clearImageBitmapCache = config.clearImageBitmapCache;
+    }
+    if (config.notifyExportSkipped !== undefined) {
+      this.notifyExportSkipped = config.notifyExportSkipped;
+    }
+
+    // Replay pending canvas state when JSON mode becomes fully available
+    if (this.pendingCanvasState && this.isRealtimeEnabled && this.sendCanvasState && this.serializeStateForServer) {
+      const pending = this.pendingCanvasState;
+      this.pendingCanvasState = null;
+      // Defer to avoid calling sendCanvasState during configure
+      queueMicrotask(() => this.handleStateChange(pending));
+    }
+  }
+
+  /**
+   * Set the initial artwork when entering editor mode.
+   * This is used to detect if artwork changed when exiting.
+   */
+  setInitialArtwork(src: string | null): void {
+    this.initialArtwork = src;
+    this.lastExportedArtwork = src;
+  }
+
+  /**
+   * Get the last exported artwork (for saving on exit)
+   * Uses lazy DataURL conversion - only converts when called, not on every export
+   * Returns a Promise to support async blob-to-DataURL conversion
+   */
+  getLastExportedArtwork(): string | null {
+    // If we have a cached DataURL string, return it
+    if (this.lastExportedArtwork) {
+      return this.lastExportedArtwork;
+    }
+    return null;
+  }
+
+  /**
+   * Get the last exported artwork as DataURL (async version)
+   * Converts from blob on demand to reduce memory pressure during editing
+   */
+  async getLastExportedArtworkAsync(): Promise<string | null> {
+    // If we have a cached DataURL string, return it
+    if (this.lastExportedArtwork) {
+      return this.lastExportedArtwork;
+    }
+    // If we have a stored blob, convert it to DataURL now (lazy conversion)
+    if (this.lastExportedBlob) {
+      return new Promise((resolve) => {
+        const reader = new FileReader();
+        reader.onloadend = () => {
+          this.lastExportedArtwork = reader.result as string;
+          // Clear the blob after conversion to free memory
+          this.lastExportedBlob = null;
+          resolve(this.lastExportedArtwork);
+        };
+        reader.onerror = () => resolve(null);
+        reader.readAsDataURL(this.lastExportedBlob as Blob);
+      });
+    }
+    return null;
+  }
+
+  /**
+   * Check if artwork has changed since entering editor
+   */
+  hasArtworkChanged(): boolean {
+    // Check if we have any export (either cached DataURL or stored blob)
+    const hasExport = this.lastExportedArtwork !== null || this.lastExportedBlob !== null;
+    // Consider changed if we have an export and it differs from initial
+    // (or if we have a blob, meaning the user made edits)
+    return hasExport && (
+      this.lastExportedArtwork !== this.initialArtwork ||
+      this.lastExportedBlob !== null
+    );
+  }
+
+  /**
+   * Call when entering editor mode to enable realtime if available
+   */
+  onEnterEditorMode(): void {
+    if (this.enableRealtime && !this.isRealtimeEnabled) {
+      this.enableRealtime();
+    }
+  }
+
+  /**
+   * Call when exiting editor mode to cleanup and disable realtime
+   * CRITICAL: Clears ImageBitmap cache to prevent iOS Safari memory crashes
+   */
+  onExitEditorMode(): void {
+    // Disable realtime mode so hero images stop showing realtime mockups
+    if (this.disableRealtime) {
+      this.disableRealtime();
+    }
+
+    // Cleanup blob URL
+    if (this.blobUrl) {
+      URL.revokeObjectURL(this.blobUrl);
+      this.blobUrl = null;
+    }
+
+    // Clear ImageBitmap cache - CRITICAL for iOS Safari memory management
+    // Each cached ImageBitmap can consume 16MB+ for large images
+    // Without this cleanup, memory accumulates and causes Safari to crash
+    if (this.clearImageBitmapCache) {
+      this.clearImageBitmapCache();
+    }
+
+    // Reset state
+    this.initialArtwork = null;
+    this.lastExportedArtwork = null;
+    this.lastExportedBlob = null;
+  }
+
+  /**
+   * Cleanup realtime resources without disabling realtime mode
+   * Use for iOS Safari memory pressure situations where we need to free memory
+   * but want to keep realtime mode active
+   */
+  cleanupRealtimeResources(): void {
+    // Revoke any stored blob URL
+    if (this.blobUrl) {
+      URL.revokeObjectURL(this.blobUrl);
+      this.blobUrl = null;
+    }
+
+    // Clear stored blob to free memory
+    this.lastExportedBlob = null;
+
+    // Clear DataURL string if it's large
+    // Keep initialArtwork for change detection but clear lastExportedArtwork
+    // since the blob was already sent to realtime service
+    if (this.lastExportedArtwork && this.lastExportedArtwork.length > 100000) {
+      this.lastExportedArtwork = null;
+    }
+
+    // Clear ImageBitmap cache to release GPU memory
+    if (this.clearImageBitmapCache) {
+      this.clearImageBitmapCache();
+    }
+  }
+
+  /**
+   * STABLE export handler - pass this to SnowconeCanvas onExport prop.
+   * This method reference NEVER changes, preventing re-renders.
+   *
+   * CRITICAL: This is an arrow function assigned to an instance property,
+   * so `this` is always bound correctly and the reference is stable.
+   *
+   * Handles both single artboard exports and multi-artboard exports:
+   * - Single: { 'Front': blob } - sends as 'Front' placement
+   * - Multi: { 'Front': blob1, 'Back': blob2 } - sends each with its artboard name as placement
+   */
+  handleExport = async (exports: Record<string, string | Blob>): Promise<void> => {
+    const artboardNames = Object.keys(exports);
+    if (artboardNames.length === 0) return;
+
+    // Process the first (or active) artboard for local storage
+    const primaryArtboardName = artboardNames[0];
+    const primaryExportData = exports[artboardNames[0]];
+
+    // Store for saving on exit (works with both blob and dataUrl)
+    // MEMORY OPTIMIZATION: Store blob directly instead of converting to DataURL on every export
+    // DataURL conversion creates large strings (1.33x blob size due to base64 encoding)
+    // which causes memory pressure on iOS Safari. Conversion is done lazily in getLastExportedArtworkAsync()
+    if (primaryExportData instanceof Blob) {
+      // Store the blob directly - conversion to DataURL happens only when needed
+      this.lastExportedBlob = primaryExportData;
+      // Clear any cached DataURL since we have a newer blob
+      this.lastExportedArtwork = null;
+
+      // Store blob URL for potential future use
+      if (this.blobUrl) {
+        URL.revokeObjectURL(this.blobUrl);
+      }
+      this.blobUrl = URL.createObjectURL(primaryExportData);
+    } else if (typeof primaryExportData === 'string') {
+      // If it's already a DataURL string, store it directly
+      this.lastExportedArtwork = primaryExportData;
+      this.lastExportedBlob = null;
+    }
+
+    // Send blobs to realtime mockup service if enabled
+    // When JSON mode is active, handleStateChange sends state on every onChange.
+    // Only fall back to blob if JSON mode isn't configured at all.
+    const useJsonMode = this.isRealtimeEnabled && this.sendCanvasState && this.serializeStateForServer;
+    let jsonSentNow = false;
+    if (useJsonMode && this.pendingCanvasState) {
+      this.handleStateChange(this.pendingCanvasState);
+      jsonSentNow = !this.pendingCanvasState;
+    }
+    // Skip blob when JSON mode is configured — JSON is the primary realtime path.
+    // Blob is only used when JSON mode is not available (e.g., third-party canvas without serializeStateForServer).
+    const skipBlob = !!useJsonMode || this.jsonModeSentSuccessfully;
+    console.log(`[CES] handleExport: useJsonMode=${!!useJsonMode} pendingState=${!!this.pendingCanvasState} jsonSentNow=${jsonSentNow} jsonEverSent=${this.jsonModeSentSuccessfully} skipBlob=${skipBlob}`);
+
+    // If we ended up sending nothing — skipBlob is true AND no JSON state went
+    // out in this call — notify any optimistic pending-export listeners so
+    // they can roll back. Without this, an upstream `notifyPendingExport`
+    // would leave loading UI stuck (no `blobSent` / `mockupResults` will fire
+    // to clear it because no actual export happened).
+    if (skipBlob && !jsonSentNow) {
+      const placements = artboardNames.length > 0 ? artboardNames : [this.placementName];
+      placements.forEach((p) => {
+        try {
+          this.notifyExportSkipped?.(p);
+        } catch (err) {
+          console.warn(`[CES] notifyExportSkipped("${p}") threw:`, err);
+        }
+      });
+    }
+
+    if (this.isRealtimeEnabled && this.sendCanvasBlob && !skipBlob) {
+      // PNG fallback — used when sendCanvasState is not configured (third-party canvas)
+      for (const artboardName of artboardNames) {
+        const exportedData = exports[artboardName];
+        let blob: Blob;
+
+        if (exportedData instanceof Blob) {
+          blob = exportedData;
+        } else if (typeof exportedData === 'string') {
+          try {
+            const response = await fetch(exportedData);
+            blob = await response.blob();
+          } catch (error) {
+            console.error(`[CanvasExportService] Failed to convert dataURL to blob for artboard '${artboardName}':`, error);
+            continue;
+          }
+        } else {
+          continue;
+        }
+
+        const placement = artboardName;
+        this.sendCanvasBlob(placement, blob, this.mockupCount, 500);
+      }
+    }
+  };
+
+  /**
+   * STABLE state change handler - pass this to SnowconeCanvas onChange prop.
+   * Sends canvas state JSON to server for server-side rendering (JSON mode).
+   *
+   * When configured with sendCanvasState + serializeStateForServer, this replaces
+   * the blob upload path for realtime previews. The server renders the canvas
+   * instead of the client, eliminating the PNG upload bandwidth.
+   *
+   * handleExport still fires for local blob storage (save/exit, thumbnails).
+   */
+  private stateChangeCallCount = 0;
+
+  handleStateChange = (state: any): void => {
+    if (!state) return;
+
+    const hasElements = state.elements?.length > 0;
+    if (!hasElements) return;
+
+    // Don't send or cache state while any image is still loading —
+    // the serializer would skip it and the server would render without artwork
+    const hasLoadingImages = state.elements?.some(
+      (el: any) => (el.type === 'image' || el.transformType === 'image') && el.imageLoadState === 'loading'
+    );
+    if (hasLoadingImages) {
+      console.log(`[CES] handleStateChange: skipping — images still loading`);
+      return;
+    }
+
+    this.stateChangeCallCount++;
+    const callId = this.stateChangeCallCount;
+    const now = Date.now();
+    console.log(`[CES] handleStateChange #${callId} at ${now} (lastSend=${this.stateChangeLastSendTime}, elapsed=${this.stateChangeLastSendTime > 0 ? now - this.stateChangeLastSendTime : 'never'}ms, pendingTimer=${!!this.stateChangeThrottleTimeout})`);
+
+    // Cache for replay when WS connects
+    this.pendingCanvasState = state;
+
+    if (!this.isRealtimeEnabled || !this.sendCanvasState || !this.serializeStateForServer) {
+      console.log(`[CES] handleStateChange #${callId}: not ready (realtime=${this.isRealtimeEnabled} sendState=${!!this.sendCanvasState} serialize=${!!this.serializeStateForServer}) — state cached`);
+      return;
+    }
+
+    // Debounce with max wait: reset timer on each call so rapid drag frames
+    // coalesce, but if we haven't sent in >= throttleMs, flush immediately
+    // so long drags still get periodic updates.
+    const settleMs = CanvasExportService.SETTLE_MS;
+    const maxWaitMs = CanvasExportService.MAX_WAIT_MS;
+    const hasSentBefore = this.stateChangeLastSendTime > 0;
+    const timeSinceLastSend = hasSentBefore ? now - this.stateChangeLastSendTime : 0;
+
+    // Max wait: during a continuous drag, force a send if it's been >= maxWaitMs
+    // since last send. "Active" means last send was recent (within 3× maxWait).
+    const isActiveDrag = hasSentBefore && timeSinceLastSend < maxWaitMs * 3;
+    if (isActiveDrag && timeSinceLastSend >= maxWaitMs) {
+      console.log(`[CES] handleStateChange #${callId}: MAX-WAIT FLUSH (${timeSinceLastSend}ms >= ${maxWaitMs}ms)`);
+      if (this.stateChangeThrottleTimeout) {
+        clearTimeout(this.stateChangeThrottleTimeout);
+        this.stateChangeThrottleTimeout = null;
+      }
+      this.sendStateNow(state);
+      return;
+    }
+
+    // Settle timer: reset on every call, fires settleMs after last change.
+    // Handles discrete actions (type a letter, nudge, color pick).
+    if (this.stateChangeThrottleTimeout) {
+      clearTimeout(this.stateChangeThrottleTimeout);
+    }
+    console.log(`[CES] handleStateChange #${callId}: SETTLE scheduled ${settleMs}ms`);
+    this.stateChangeThrottleTimeout = setTimeout(() => {
+      this.stateChangeThrottleTimeout = null;
+      console.log(`[CES] handleStateChange #${callId}: SETTLE FIRED at ${Date.now()} (${Date.now() - now}ms after call)`);
+      if (this.pendingCanvasState) {
+        this.sendStateNow(this.pendingCanvasState);
+      }
+    }, settleMs);
+  };
+
+  private sendStateNow(state: any): void {
+    if (!this.sendCanvasState || !this.serializeStateForServer) {
+      console.log(`[CES] sendStateNow SKIPPED: sendCanvasState=${!!this.sendCanvasState} serializeStateForServer=${!!this.serializeStateForServer}`);
+      return;
+    }
+
+    this.stateChangeLastSendTime = Date.now();
+
+    const serverState = this.serializeStateForServer(state);
+    const artboards = serverState?.artboards;
+    if (!artboards || artboards.length === 0) {
+      console.log(`[CES] sendStateNow SKIPPED: no artboards in serialized state`);
+      return;
+    }
+
+    let sent = false;
+    for (const artboard of artboards) {
+      const placement = artboard.name || this.placementName;
+      const result = this.sendCanvasState(placement, serverState, this.mockupCount, 0);
+      console.log(`[CES] sendCanvasState("${placement}") → ${result ? 'OK' : 'FAILED (WS not ready)'}`);
+      if (result) {
+        sent = true;
+      }
+    }
+
+    if (sent) {
+      this.pendingCanvasState = null;
+      this.jsonModeSentSuccessfully = true;
+      console.log(`[CES] JSON state sent for ${artboards.length} artboard(s)`);
+    } else {
+      console.log(`[CES] JSON state send FAILED for all ${artboards.length} artboard(s) — state remains pending, jsonEverSent=${this.jsonModeSentSuccessfully}`);
+    }
+  }
+
+  /**
+   * Reset the service state (e.g., when unmounting)
+   */
+  reset(): void {
+    this.lastExportedArtwork = null;
+    this.lastExportedBlob = null;
+    this.initialArtwork = null;
+    if (this.blobUrl) {
+      URL.revokeObjectURL(this.blobUrl);
+      this.blobUrl = null;
+    }
+    // Clear pending state change throttle
+    if (this.stateChangeThrottleTimeout) {
+      clearTimeout(this.stateChangeThrottleTimeout);
+      this.stateChangeThrottleTimeout = null;
+    }
+    this.stateChangeLastSendTime = 0;
+    // Also clear ImageBitmap cache on full reset
+    if (this.clearImageBitmapCache) {
+      this.clearImageBitmapCache();
+    }
+  }
+}
+
+// Singleton instance - use this throughout the app
+export const canvasExportService = new CanvasExportService();