@fragments-sdk/viewer 0.2.1

package/src/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'; fragmentPath: 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 (30 seconds)
+  const RENDER_TIMEOUT = 30000;
+
+  // 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((
+    fragmentPath: 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', fragmentPath, 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<{
+    fragmentPath: 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({
+            fragmentPath: message.fragmentPath,
+            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/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 };
+}

package/src/hooks/useShadowStyles.ts

@@ -0,0 +1,221 @@
+/**
+ * useShadowStyles - Mirrors document stylesheets into shadow roots
+ *
+ * Uses a **singleton observer** — one MutationObserver total, not one per
+ * shadow root. CSSStyleSheet instances are shared across all registered
+ * shadow roots (5 variants = 1 shared set of sheets).
+ *
+ * Updates to `adoptedStyleSheets` are debounced via microtask so rapid
+ * Vite HMR bursts (many style tags added/removed in one tick) result in
+ * a single assignment per shadow root.
+ */
+
+import { useEffect } from "react";
+
+// ---------------------------------------------------------------------------
+// Module-level singleton state
+// ---------------------------------------------------------------------------
+
+/** Shared CSSStyleSheet instances, keyed by data-vite-dev-id or href */
+const sharedSheets = new Map<string, CSSStyleSheet>();
+
+/** All currently registered shadow roots */
+const registeredRoots = new Set<ShadowRoot>();
+
+/** Head childList observer (singleton) */
+let headObserver: MutationObserver | null = null;
+
+/** Style textContent observer (singleton) */
+let contentObserver: MutationObserver | null = null;
+
+/** Microtask flush guard */
+let flushScheduled = false;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function syncStyleTag(style: HTMLStyleElement): boolean {
+  const id = style.getAttribute("data-vite-dev-id");
+  if (!id || !style.textContent) return false;
+
+  const existing = sharedSheets.get(id);
+  if (existing) {
+    try {
+      existing.replaceSync(style.textContent);
+    } catch {
+      // CSS parse errors are non-fatal
+    }
+    return true;
+  }
+
+  const sheet = new CSSStyleSheet();
+  try {
+    sheet.replaceSync(style.textContent);
+  } catch {
+    return false;
+  }
+  sharedSheets.set(id, sheet);
+  return true;
+}
+
+function syncLinkTag(link: HTMLLinkElement): boolean {
+  const href = link.getAttribute("href");
+  if (!href) return false;
+  if (sharedSheets.has(href)) return false;
+
+  try {
+    if (link.sheet) {
+      const sheet = new CSSStyleSheet();
+      const rules: string[] = [];
+      for (const rule of link.sheet.cssRules) {
+        rules.push(rule.cssText);
+      }
+      sheet.replaceSync(rules.join("\n"));
+      sharedSheets.set(href, sheet);
+      return true;
+    }
+  } catch {
+    // Cross-origin or security restriction
+  }
+  return false;
+}
+
+/** Push current sheets to every registered shadow root (debounced) */
+function scheduleFlush() {
+  if (flushScheduled) return;
+  flushScheduled = true;
+  queueMicrotask(() => {
+    flushScheduled = false;
+    const sheets = Array.from(sharedSheets.values());
+    for (const root of registeredRoots) {
+      root.adoptedStyleSheets = sheets;
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Observer lifecycle (starts with first root, stops when last root leaves)
+// ---------------------------------------------------------------------------
+
+function startObserving() {
+  if (headObserver) return;
+
+  // --- Initial sync ---
+  document.querySelectorAll<HTMLStyleElement>("style[data-vite-dev-id]").forEach(syncStyleTag);
+  document.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]').forEach(syncLinkTag);
+
+  // Plain <style> without data-vite-dev-id (e.g., injected globals)
+  document.querySelectorAll<HTMLStyleElement>("style:not([data-vite-dev-id])").forEach((style) => {
+    if (!style.textContent) return;
+    const key = `__plain__${style.textContent.slice(0, 64)}`;
+    if (sharedSheets.has(key)) return;
+    const sheet = new CSSStyleSheet();
+    try {
+      sheet.replaceSync(style.textContent);
+      sharedSheets.set(key, sheet);
+    } catch {
+      // ignore
+    }
+  });
+
+  // --- Head childList observer ---
+  headObserver = new MutationObserver((mutations) => {
+    let changed = false;
+
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) {
+        if (node instanceof HTMLStyleElement && node.hasAttribute("data-vite-dev-id")) {
+          if (syncStyleTag(node)) changed = true;
+          // Also observe this new tag's text content for in-place HMR updates
+          if (node.firstChild) {
+            contentObserver?.observe(node.firstChild, { characterData: true });
+          }
+        }
+        if (node instanceof HTMLLinkElement && node.rel === "stylesheet") {
+          if (syncLinkTag(node)) changed = true;
+        }
+      }
+
+      for (const node of mutation.removedNodes) {
+        if (node instanceof HTMLStyleElement) {
+          const id = node.getAttribute("data-vite-dev-id");
+          if (id && sharedSheets.has(id)) {
+            sharedSheets.delete(id);
+            changed = true;
+          }
+        }
+        if (node instanceof HTMLLinkElement && node.rel === "stylesheet") {
+          const href = node.getAttribute("href");
+          if (href && sharedSheets.has(href)) {
+            sharedSheets.delete(href);
+            changed = true;
+          }
+        }
+      }
+    }
+
+    if (changed) scheduleFlush();
+  });
+
+  headObserver.observe(document.head, { childList: true });
+
+  // --- Content observer for in-place textContent mutations (Vite HMR) ---
+  contentObserver = new MutationObserver((mutations) => {
+    let changed = false;
+    for (const mutation of mutations) {
+      if (
+        mutation.type === "characterData" &&
+        mutation.target.parentElement instanceof HTMLStyleElement
+      ) {
+        if (syncStyleTag(mutation.target.parentElement)) {
+          changed = true;
+        }
+      }
+    }
+    if (changed) scheduleFlush();
+  });
+
+  // Observe existing style tag text nodes
+  document.querySelectorAll<HTMLStyleElement>("style[data-vite-dev-id]").forEach((style) => {
+    if (style.firstChild) {
+      contentObserver!.observe(style.firstChild, { characterData: true });
+    }
+  });
+}
+
+function stopObserving() {
+  if (registeredRoots.size > 0) return; // Still have consumers
+
+  headObserver?.disconnect();
+  headObserver = null;
+  contentObserver?.disconnect();
+  contentObserver = null;
+  sharedSheets.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+export function useShadowStyles(shadowRoot: ShadowRoot | null) {
+  useEffect(() => {
+    if (!shadowRoot) return;
+
+    registeredRoots.add(shadowRoot);
+
+    // Start the singleton observer if this is the first root
+    if (registeredRoots.size === 1) {
+      startObserving();
+    }
+
+    // Apply current sheets to this root immediately
+    shadowRoot.adoptedStyleSheets = Array.from(sharedSheets.values());
+
+    return () => {
+      registeredRoots.delete(shadowRoot);
+      shadowRoot.adoptedStyleSheets = [];
+      stopObserving();
+    };
+  }, [shadowRoot]);
+}