@fragments-sdk/cli 0.2.2

package/src/viewer/hooks/usePreviewBridge.ts

@@ -0,0 +1,347 @@
+/**
+ * usePreviewBridge - Communication hook for parent-iframe messaging
+ *
+ * This hook provides utilities for bidirectional communication between
+ * the parent viewer shell and the isolated iframe preview.
+ */
+
+import { useRef, useEffect, useCallback, useState, type RefObject } from 'react';
+
+/**
+ * Message types sent from parent to iframe
+ */
+export type ParentMessage =
+  | { type: 'init'; frameId: string }
+  | { type: 'render'; segmentPath: string; variantName: string; props?: Record<string, unknown> }
+  | { type: 'theme'; theme: 'light' | 'dark' }
+  | { type: 'resize'; width: number; height: number };
+
+/**
+ * Message types sent from iframe to parent
+ */
+export type FrameMessage =
+  | { type: 'ready'; frameId?: string }
+  | { type: 'rendered'; height: number; width: number; frameId?: string }
+  | { type: 'error'; message: string; stack?: string; frameId?: string };
+
+/**
+ * Origin used for postMessage (same origin for Vite dev server)
+ */
+const PREVIEW_ORIGIN = '*'; // In dev, we use * since it's same origin
+
+/**
+ * Message channel ID to ensure we only respond to our own messages
+ */
+export const PREVIEW_CHANNEL = 'fragments-preview';
+
+/**
+ * Generate a unique frame ID
+ */
+let frameIdCounter = 0;
+function generateFrameId(): string {
+  return `frame-${++frameIdCounter}-${Date.now()}`;
+}
+
+/**
+ * Hook for the parent window to communicate with the iframe
+ */
+export function usePreviewBridge(iframeRef: RefObject<HTMLIFrameElement | null>) {
+  const [isReady, setIsReady] = useState(false);
+  const [lastError, setLastError] = useState<string | null>(null);
+  const [contentSize, setContentSize] = useState<{ width: number; height: number } | null>(null);
+  const [isRendering, setIsRendering] = useState(false);
+  const pendingCallbacks = useRef<Map<string, (response: FrameMessage) => void>>(new Map());
+  const pendingTimeouts = useRef<Map<string, NodeJS.Timeout>>(new Map());
+  const messageId = useRef(0);
+  const frameIdRef = useRef<string>(generateFrameId());
+  const initSentRef = useRef(false);
+  const currentRenderIdRef = useRef<string | null>(null);
+
+  // Render timeout duration (5 seconds)
+  const RENDER_TIMEOUT = 5000;
+
+  // Listen for messages from iframe
+  useEffect(() => {
+    function handleMessage(event: MessageEvent) {
+      // Validate message structure
+      if (!event.data || event.data.channel !== PREVIEW_CHANNEL) {
+        return;
+      }
+
+      const message = event.data as FrameMessage & { channel: string; id?: string; frameId?: string };
+
+      // For "ready" messages (no frameId yet), check if it's from our iframe
+      if (message.type === 'ready' && !message.frameId) {
+        // Only process ready from our iframe by checking event.source
+        if (event.source !== iframeRef.current?.contentWindow) {
+          return;
+        }
+        // Send init message with our frameId
+        if (!initSentRef.current && iframeRef.current?.contentWindow) {
+          initSentRef.current = true;
+          iframeRef.current.contentWindow.postMessage(
+            { type: 'init', frameId: frameIdRef.current, channel: PREVIEW_CHANNEL },
+            PREVIEW_ORIGIN
+          );
+        }
+        setIsReady(true);
+        setLastError(null);
+        return;
+      }
+
+      // For all other messages, filter by frameId
+      if (message.frameId && message.frameId !== frameIdRef.current) {
+        return;
+      }
+
+      switch (message.type) {
+        case 'ready':
+          // Ready with frameId - just update state
+          setIsReady(true);
+          setLastError(null);
+          break;
+
+        case 'rendered':
+          setContentSize({ width: message.width, height: message.height });
+          setLastError(null);
+          setIsRendering(false);
+          // Clear any pending timeout for this render
+          if (currentRenderIdRef.current) {
+            const timeout = pendingTimeouts.current.get(currentRenderIdRef.current);
+            if (timeout) {
+              clearTimeout(timeout);
+              pendingTimeouts.current.delete(currentRenderIdRef.current);
+            }
+            currentRenderIdRef.current = null;
+          }
+          break;
+
+        case 'error':
+          setLastError(message.message);
+          break;
+      }
+
+      // Call any pending callbacks
+      if (message.id && pendingCallbacks.current.has(message.id)) {
+        const callback = pendingCallbacks.current.get(message.id);
+        pendingCallbacks.current.delete(message.id);
+        callback?.(message);
+      }
+    }
+
+    window.addEventListener('message', handleMessage);
+    return () => window.removeEventListener('message', handleMessage);
+  }, [iframeRef]);
+
+  // Reset ready state when iframe changes
+  useEffect(() => {
+    setIsReady(false);
+    setLastError(null);
+    setContentSize(null);
+    initSentRef.current = false;
+  }, [iframeRef.current]);
+
+  /**
+   * Send a message to the iframe
+   */
+  const sendMessage = useCallback((message: ParentMessage) => {
+    if (!iframeRef.current?.contentWindow) {
+      console.warn('[PreviewBridge] Cannot send message - iframe not ready');
+      return;
+    }
+
+    const id = `msg-${++messageId.current}`;
+    iframeRef.current.contentWindow.postMessage(
+      { ...message, channel: PREVIEW_CHANNEL, id, frameId: frameIdRef.current },
+      PREVIEW_ORIGIN
+    );
+  }, [iframeRef]);
+
+  /**
+   * Send a render request to the iframe
+   */
+  const render = useCallback((
+    segmentPath: string,
+    variantName: string,
+    props?: Record<string, unknown>
+  ) => {
+    // Clear any existing timeout
+    if (currentRenderIdRef.current) {
+      const existingTimeout = pendingTimeouts.current.get(currentRenderIdRef.current);
+      if (existingTimeout) {
+        clearTimeout(existingTimeout);
+        pendingTimeouts.current.delete(currentRenderIdRef.current);
+      }
+    }
+
+    // Generate new render ID
+    const renderId = `render-${++messageId.current}`;
+    currentRenderIdRef.current = renderId;
+    setIsRendering(true);
+    setLastError(null);
+
+    sendMessage({ type: 'render', segmentPath, variantName, props });
+
+    // Set timeout
+    const timeoutId = setTimeout(() => {
+      if (currentRenderIdRef.current === renderId) {
+        setLastError('Render timeout - component took too long to load');
+        setIsRendering(false);
+        currentRenderIdRef.current = null;
+      }
+    }, RENDER_TIMEOUT);
+
+    pendingTimeouts.current.set(renderId, timeoutId);
+  }, [sendMessage]);
+
+  /**
+   * Set the theme in the iframe
+   */
+  const setTheme = useCallback((theme: 'light' | 'dark') => {
+    sendMessage({ type: 'theme', theme });
+  }, [sendMessage]);
+
+  /**
+   * Resize the iframe viewport
+   */
+  const resize = useCallback((width: number, height: number) => {
+    sendMessage({ type: 'resize', width, height });
+  }, [sendMessage]);
+
+  /**
+   * Clear the last error
+   */
+  const clearError = useCallback(() => {
+    setLastError(null);
+  }, []);
+
+  // Cleanup timeouts on unmount
+  useEffect(() => {
+    return () => {
+      pendingTimeouts.current.forEach(timeout => clearTimeout(timeout));
+      pendingTimeouts.current.clear();
+    };
+  }, []);
+
+  return {
+    isReady,
+    isRendering,
+    lastError,
+    contentSize,
+    sendMessage,
+    render,
+    setTheme,
+    resize,
+    clearError,
+  };
+}
+
+/**
+ * Hook for the iframe to communicate with the parent
+ * Used by PreviewFrameHost
+ */
+export function useFrameBridge() {
+  const [renderRequest, setRenderRequest] = useState<{
+    segmentPath: string;
+    variantName: string;
+    props?: Record<string, unknown>;
+  } | null>(null);
+  const [theme, setThemeState] = useState<'light' | 'dark'>('light');
+  const [viewportSize, setViewportSize] = useState<{ width: number; height: number } | null>(null);
+  const frameIdRef = useRef<string | null>(null);
+
+  // Listen for messages from parent
+  useEffect(() => {
+    function handleMessage(event: MessageEvent) {
+      // Validate message structure
+      if (!event.data || event.data.channel !== PREVIEW_CHANNEL) {
+        return;
+      }
+
+      const message = event.data as ParentMessage & { channel: string; id?: string; frameId?: string };
+
+      // Store frameId from init message or any message with frameId
+      if (message.frameId && !frameIdRef.current) {
+        frameIdRef.current = message.frameId;
+      }
+
+      // Skip init messages - they're just for setting frameId
+      if (message.type === 'init') {
+        return;
+      }
+
+      switch (message.type) {
+        case 'render':
+          setRenderRequest({
+            segmentPath: message.segmentPath,
+            variantName: message.variantName,
+            props: message.props,
+          });
+          break;
+
+        case 'theme':
+          setThemeState(message.theme);
+          // Apply theme class to document
+          if (message.theme === 'dark') {
+            document.documentElement.classList.add('dark');
+          } else {
+            document.documentElement.classList.remove('dark');
+          }
+          break;
+
+        case 'resize':
+          setViewportSize({ width: message.width, height: message.height });
+          break;
+      }
+    }
+
+    window.addEventListener('message', handleMessage);
+    return () => window.removeEventListener('message', handleMessage);
+  }, []);
+
+  /**
+   * Send a message to the parent window
+   */
+  const sendToParent = useCallback((message: FrameMessage) => {
+    if (!window.parent || window.parent === window) {
+      console.warn('[FrameBridge] Not running in iframe');
+      return;
+    }
+
+    window.parent.postMessage(
+      { ...message, channel: PREVIEW_CHANNEL, frameId: frameIdRef.current },
+      PREVIEW_ORIGIN
+    );
+  }, []);
+
+  /**
+   * Notify parent that the frame is ready
+   */
+  const notifyReady = useCallback(() => {
+    sendToParent({ type: 'ready' });
+  }, [sendToParent]);
+
+  /**
+   * Notify parent that rendering is complete
+   */
+  const notifyRendered = useCallback((width: number, height: number) => {
+    sendToParent({ type: 'rendered', width, height });
+  }, [sendToParent]);
+
+  /**
+   * Notify parent of a render error
+   */
+  const notifyError = useCallback((message: string, stack?: string) => {
+    sendToParent({ type: 'error', message, stack });
+  }, [sendToParent]);
+
+  return {
+    renderRequest,
+    theme,
+    viewportSize,
+    notifyReady,
+    notifyRendered,
+    notifyError,
+    setTheme: setThemeState,
+  };
+}

package/src/viewer/hooks/useScrollSpy.ts

@@ -0,0 +1,78 @@
+import { useState, useEffect, useRef } from 'react';
+
+interface UseScrollSpyOptions {
+  /** IDs of sections to observe */
+  sectionIds: string[];
+  /** Offset from top of viewport to consider section as active */
+  offset?: number;
+  /** Root element to observe within (default: document) */
+  root?: Element | null;
+}
+
+export function useScrollSpy({ sectionIds, offset = 100, root = null }: UseScrollSpyOptions) {
+  const [activeId, setActiveId] = useState<string | null>(sectionIds[0] ?? null);
+  const observerRef = useRef<IntersectionObserver | null>(null);
+
+  useEffect(() => {
+    const elements = sectionIds
+      .map((id) => document.getElementById(id))
+      .filter((el): el is HTMLElement => el !== null);
+
+    if (elements.length === 0) return;
+
+    // Track which sections are currently visible
+    const visibleSections = new Map<string, number>();
+
+    observerRef.current = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          const id = entry.target.id;
+          if (entry.isIntersecting) {
+            // Store the top position of visible sections
+            visibleSections.set(id, entry.boundingClientRect.top);
+          } else {
+            visibleSections.delete(id);
+          }
+        });
+
+        // Find the section closest to the top
+        if (visibleSections.size > 0) {
+          let closestId = '';
+          let closestDistance = Infinity;
+
+          visibleSections.forEach((top, id) => {
+            const distance = Math.abs(top - offset);
+            if (distance < closestDistance) {
+              closestDistance = distance;
+              closestId = id;
+            }
+          });
+
+          if (closestId) {
+            setActiveId(closestId);
+          }
+        }
+      },
+      {
+        root,
+        rootMargin: `-${offset}px 0px -50% 0px`,
+        threshold: [0, 0.25, 0.5, 0.75, 1],
+      }
+    );
+
+    elements.forEach((el) => observerRef.current?.observe(el));
+
+    return () => {
+      observerRef.current?.disconnect();
+    };
+  }, [sectionIds, offset, root]);
+
+  const scrollToSection = (id: string) => {
+    const element = document.getElementById(id);
+    if (element) {
+      element.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
+  };
+
+  return { activeId, scrollToSection };
+}