@fragments-sdk/viewer 0.2.1

package/src/components/ResizablePanel.tsx

@@ -0,0 +1,271 @@
+/**
+ * ResizablePanel - A bottom-docked panel that can be resized by dragging
+ *
+ * Features:
+ * - Drag-to-resize from the top edge
+ * - Collapsible via chevron toggle
+ * - Persists size and open state to localStorage
+ */
+
+import {
+  useState,
+  useEffect,
+  useCallback,
+  useRef,
+  type ReactNode,
+  type CSSProperties,
+} from "react";
+import { BRAND } from '@fragments-sdk/core';
+import { ChevronDownIcon } from "./Icons.js";
+import { Box, Stack, Button } from "@fragments-sdk/ui";
+
+// Storage key for persisting panel state
+const STORAGE_KEY = `${BRAND.storagePrefix}panel-state`;
+
+interface PanelState {
+  height: number;
+  isOpen: boolean;
+}
+
+const DEFAULT_STATE: PanelState = {
+  height: 180,
+  isOpen: true,
+};
+
+const MIN_HEIGHT = 120;
+const MAX_HEIGHT = 600;
+
+function loadPanelState(): PanelState {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored) {
+      const parsed = JSON.parse(stored);
+      return { ...DEFAULT_STATE, ...parsed };
+    }
+  } catch {
+    // Ignore parse errors
+  }
+  return DEFAULT_STATE;
+}
+
+function savePanelState(state: PanelState): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+  } catch {
+    // Ignore storage errors
+  }
+}
+
+interface ResizablePanelProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Panel header content (tabs, title, etc.) */
+  header: ReactNode;
+  /** Panel body content */
+  children: ReactNode;
+  /** Whether to show the panel at all */
+  visible?: boolean;
+  /** Additional class name for the panel container */
+  className?: string;
+}
+
+export function ResizablePanel({
+  header,
+  children,
+  visible = true,
+  className,
+  ...props
+}: ResizablePanelProps) {
+  const [state, setState] = useState<PanelState>(loadPanelState);
+  const [isResizing, setIsResizing] = useState(false);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const startYRef = useRef(0);
+  const startHeightRef = useRef(0);
+
+  // Save state changes to localStorage
+  useEffect(() => {
+    savePanelState(state);
+  }, [state]);
+
+  const handleMouseDown = useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault();
+      setIsResizing(true);
+      startYRef.current = e.clientY;
+      startHeightRef.current = state.height;
+    },
+    [state.height]
+  );
+
+  const handleMouseMove = useCallback(
+    (e: MouseEvent) => {
+      if (!isResizing) return;
+
+      const deltaY = startYRef.current - e.clientY;
+      const newHeight = Math.max(MIN_HEIGHT, Math.min(MAX_HEIGHT, startHeightRef.current + deltaY));
+      setState((s) => ({ ...s, height: newHeight }));
+    },
+    [isResizing]
+  );
+
+  const handleMouseUp = useCallback(() => {
+    setIsResizing(false);
+  }, []);
+
+  // Add global mouse event listeners during resize
+  useEffect(() => {
+    if (isResizing) {
+      document.addEventListener("mousemove", handleMouseMove);
+      document.addEventListener("mouseup", handleMouseUp);
+      document.body.style.cursor = "ns-resize";
+      document.body.style.userSelect = "none";
+
+      return () => {
+        document.removeEventListener("mousemove", handleMouseMove);
+        document.removeEventListener("mouseup", handleMouseUp);
+        document.body.style.cursor = "";
+        document.body.style.userSelect = "";
+      };
+    }
+  }, [isResizing, handleMouseMove, handleMouseUp]);
+
+  const toggleOpen = useCallback(() => {
+    setState((s) => ({ ...s, isOpen: !s.isOpen }));
+  }, []);
+
+  if (!visible) return null;
+
+  const isOpen = state.isOpen;
+
+  // Heights for layout calculation
+  const headerHeight = 40; // h-10 = 2.5rem = 40px
+  const grabHandleHeight = 12; // 6px top padding + 4px pill + 2px bottom padding
+
+  // Compute container styles — drawer appearance
+  const containerStyle: CSSProperties = {
+    flexShrink: 0,
+    backgroundColor: "var(--bg-secondary)",
+    // Only transition when NOT resizing (for smooth open/close animations)
+    transition: isResizing ? "none" : "height 300ms ease",
+    height: isOpen ? state.height : headerHeight,
+    // Prevent content from being selected during resize
+    ...(isResizing && { pointerEvents: "none" as const }),
+    position: "sticky",
+    bottom: 0,
+    // Drawer visual treatment
+    borderTopLeftRadius: "12px",
+    borderTopRightRadius: "12px",
+    boxShadow: "0 -4px 16px rgba(0, 0, 0, 0.08), 0 -1px 4px rgba(0, 0, 0, 0.04)",
+    borderTop: "1px solid var(--border)",
+  };
+
+  // Resize handle styles — extends above panel for easier grabbing
+  const resizeHandleStyle: CSSProperties = {
+    position: "absolute",
+    zIndex: 20,
+    top: "-8px",
+    left: 0,
+    right: 0,
+    height: "16px",
+    cursor: "ns-resize",
+    ...(isResizing && { backgroundColor: "rgba(var(--color-accent-rgb, 59, 130, 246), 0.2)" }),
+  };
+
+  // Grab handle pill — always visible in drawer style
+  const grabHandleStyle: CSSProperties = {
+    width: "100%",
+    display: "flex",
+    justifyContent: "center",
+    padding: "6px 0 2px",
+    cursor: "ns-resize",
+  };
+
+  const grabPillStyle: CSSProperties = {
+    width: "36px",
+    height: "4px",
+    borderRadius: "9999px",
+    backgroundColor: "var(--text-muted)",
+    opacity: isResizing ? 0.8 : 0.3,
+    transition: "opacity 150ms ease",
+  };
+
+  // Chevron icon rotation
+  const chevronStyle: CSSProperties = {
+    width: "16px",
+    height: "16px",
+    transition: "transform 150ms ease",
+    ...(!isOpen && { transform: "rotate(180deg)" }),
+  };
+
+  return (
+    <div ref={panelRef} className={className} style={containerStyle} {...props}>
+      {/* Full-viewport overlay during resize - prevents iframes from capturing events */}
+      {isResizing && (
+        <div
+          style={{
+            position: "fixed",
+            inset: 0,
+            zIndex: 50,
+            cursor: "ns-resize",
+            // Must explicitly enable pointer events since parent has pointerEvents: none
+            pointerEvents: "auto",
+          }}
+        />
+      )}
+
+      {/* Resize Handle - extends above panel for easier grabbing */}
+      {isOpen && (
+        <div
+          style={resizeHandleStyle}
+          onMouseDown={handleMouseDown}
+        />
+      )}
+
+      {/* Grab handle pill — always visible drawer indicator */}
+      {isOpen && (
+        <div
+          style={grabHandleStyle}
+          onMouseDown={handleMouseDown}
+          onMouseEnter={(e) => {
+            const pill = e.currentTarget.querySelector("[data-grab-pill]") as HTMLElement;
+            if (pill) pill.style.opacity = "0.6";
+          }}
+          onMouseLeave={(e) => {
+            const pill = e.currentTarget.querySelector("[data-grab-pill]") as HTMLElement;
+            if (pill) pill.style.opacity = isResizing ? "0.8" : "0.3";
+          }}
+        >
+          <div data-grab-pill style={grabPillStyle} />
+        </div>
+      )}
+
+      {/* Panel Header */}
+      <Stack direction="row" align="center" justify="between" style={{ padding: '0 16px', height: '40px', borderBottom: '1px solid var(--border-subtle)' }}>
+        <Stack direction="row" align="center" gap="xs" style={{ flex: 1, overflow: 'hidden' }}>
+          {header}
+        </Stack>
+        <Stack direction="row" align="center" gap="xs">
+          {/* Collapse toggle button */}
+          <Button
+            variant="ghost"
+            size="sm"
+            icon
+            onClick={toggleOpen}
+            aria-label={isOpen ? "Collapse panel" : "Expand panel"}
+          >
+            <span style={chevronStyle}>
+              <ChevronDownIcon />
+            </span>
+          </Button>
+        </Stack>
+      </Stack>
+
+      {/* Panel Content */}
+      {isOpen && (
+        <Box overflow="auto" style={{ height: `calc(100% - ${headerHeight}px)`, width: '100%' }}>
+          {children}
+        </Box>
+      )}
+    </div>
+  );
+}
+
+export default ResizablePanel;

package/src/components/RightSidebar.tsx

@@ -0,0 +1,102 @@
+import type { FragmentDefinition } from '@fragments-sdk/core';
+import { useScrollSpy } from '../hooks/useScrollSpy.js';
+import { Sidebar, Text } from '@fragments-sdk/ui';
+
+interface RightSidebarProps {
+  fragment: FragmentDefinition;
+}
+
+interface TocItem {
+  id: string;
+  label: string;
+  children?: TocItem[];
+}
+
+export function RightSidebar({ fragment }: RightSidebarProps) {
+  // Build table of contents from fragment
+  const tocItems: TocItem[] = [];
+
+  // Overview section
+  tocItems.push({ id: 'overview', label: 'Overview' });
+
+  // Variants section with nested items
+  if (fragment.variants && fragment.variants.length > 0) {
+    tocItems.push({
+      id: 'variants',
+      label: 'Variants',
+      children: fragment.variants.map((variant, index) => ({
+        id: `variant-${index}`,
+        label: variant.name,
+      })),
+    });
+  }
+
+  // Usage section
+  if (fragment.usage) {
+    tocItems.push({ id: 'usage', label: 'Usage' });
+  }
+
+  // Props section
+  if (fragment.props && Object.keys(fragment.props).length > 0) {
+    tocItems.push({ id: 'props', label: 'Props' });
+  }
+
+  // Relations section
+  if (fragment.relations && fragment.relations.length > 0) {
+    tocItems.push({ id: 'relations', label: 'Relations' });
+  }
+
+  // Flatten for scroll spy
+  const allIds = tocItems.flatMap((item) => [
+    item.id,
+    ...(item.children?.map((child) => child.id) ?? []),
+  ]);
+
+  const { activeId, scrollToSection } = useScrollSpy({
+    sectionIds: allIds,
+    offset: 100,
+  });
+
+  return (
+    <Sidebar position="right" collapsible="none" style={{ padding: '8px 0' }}>
+      <Sidebar.Header>
+        <Text size="2xs" weight="medium" color="tertiary" style={{ textTransform: 'uppercase', letterSpacing: '0.05em' }}>
+          On this page
+        </Text>
+      </Sidebar.Header>
+      <Sidebar.Nav aria-label="On this page">
+        {tocItems.map((item) => {
+          const isActive = activeId === item.id;
+          const hasActiveChild = item.children?.some((child) => activeId === child.id);
+
+          return (
+            <Sidebar.Section key={item.id}>
+              <Sidebar.Item
+                active={isActive || !!hasActiveChild}
+                onClick={() => scrollToSection(item.id)}
+              >
+                {item.label}
+              </Sidebar.Item>
+              {item.children && item.children.length > 0 && (
+                <>
+                  {item.children.map((child) => {
+                    const isChildActive = activeId === child.id;
+                    return (
+                      <Sidebar.SubItem
+                        key={child.id}
+                        active={isChildActive}
+                        onClick={() => scrollToSection(child.id)}
+                      >
+                        {child.label}
+                      </Sidebar.SubItem>
+                    );
+                  })}
+                </>
+              )}
+            </Sidebar.Section>
+          );
+        })}
+      </Sidebar.Nav>
+    </Sidebar>
+  );
+}

package/src/components/RuntimeToolsRegistrar.tsx

@@ -0,0 +1,17 @@
+import { useMemo } from 'react';
+import { useWebMCPTools } from '@fragments-sdk/webmcp/react';
+import { useCompiledFragments } from '../hooks/useCompiledFragments.js';
+import { createRuntimeWebMCPTools } from '../webmcp/runtime-tools.js';
+
+export function RuntimeToolsRegistrar() {
+  const { data } = useCompiledFragments();
+
+  const tools = useMemo(() => {
+    if (!data) return [];
+    return createRuntimeWebMCPTools({ compiledData: data });
+  }, [data]);
+
+  useWebMCPTools(tools);
+
+  return null;
+}

package/src/components/ScreenshotButton.tsx

@@ -0,0 +1,90 @@
+/**
+ * ScreenshotButton component - captures screenshots of the preview area.
+ * Saves directly to file.
+ */
+
+import { useState, memo } from 'react';
+import html2canvas from 'html2canvas';
+import { Button, Tooltip } from '@fragments-sdk/ui';
+import { CameraIcon } from './Icons.js';
+
+interface ScreenshotButtonProps {
+  componentName: string;
+  variantName: string;
+}
+
+export const ScreenshotButton = memo(function ScreenshotButton({ componentName, variantName }: ScreenshotButtonProps) {
+  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
+
+  const handleSaveToFile = async () => {
+    setStatus('loading');
+    try {
+      const previewContainer = document.querySelector('[data-preview-container="true"]');
+      if (!previewContainer) throw new Error('Preview container not found');
+
+      await document.fonts.ready;
+
+      const canvas = await html2canvas(previewContainer as HTMLElement, {
+        backgroundColor: null,
+        scale: 2,
+        logging: false,
+        useCORS: true,
+        allowTaint: true,
+        onclone: (clonedDoc) => {
+          const clonedElement = clonedDoc.querySelector('[data-preview-container="true"]');
+          if (clonedElement) {
+            const style = clonedDoc.createElement('style');
+            style.textContent = Array.from(document.styleSheets)
+              .map(sheet => {
+                try {
+                  return Array.from(sheet.cssRules)
+                    .map(rule => rule.cssText)
+                    .join('\n');
+                } catch {
+                  return '';
+                }
+              })
+              .join('\n');
+            clonedDoc.head.appendChild(style);
+          }
+        },
+      });
+
+      const blob = await new Promise<Blob>((resolve, reject) => {
+        canvas.toBlob((b) => {
+          if (b) resolve(b);
+          else reject(new Error('Failed to create blob'));
+        }, 'image/png');
+      });
+
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = `${componentName}-${variantName}.png`;
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+      URL.revokeObjectURL(url);
+      setStatus('success');
+      setTimeout(() => setStatus('idle'), 2000);
+    } catch (err) {
+      console.error('Screenshot save failed:', err);
+      setStatus('error');
+      setTimeout(() => setStatus('idle'), 2000);
+    }
+  };
+
+  return (
+    <Tooltip content="Save screenshot">
+      <Button
+        variant="ghost"
+        size="sm"
+        icon
+        disabled={status === 'loading'}
+        onClick={handleSaveToFile}
+      >
+        <CameraIcon style={{ width: '16px', height: '16px' }} />
+      </Button>
+    </Tooltip>
+  );
+});

package/src/components/ShadowPreview.tsx

@@ -0,0 +1,204 @@
+/**
+ * ShadowPreview - Shadow DOM based preview isolation
+ *
+ * Replaces IsolatedPreviewFrame as the default preview isolation mechanism.
+ * Same JS context (instant rendering) + shadow boundary (CSS encapsulation).
+ *
+ * Uses `createPortal` (not `createRoot`) to maintain the React context tree —
+ * ThemeProvider, ErrorBoundary, ActionCapture all propagate through the portal.
+ *
+ * Keyboard events are stopped at the shadow host boundary to prevent preview
+ * interactions from triggering app-level shortcuts (same isolation as iframes).
+ */
+
+import {
+  useRef,
+  useEffect,
+  useState,
+  type ReactNode,
+} from "react";
+import { createPortal } from "react-dom";
+import { useShadowStyles } from "../hooks/useShadowStyles.js";
+
+export interface ShadowPreviewProps {
+  /** React elements to render (from renderContent()) */
+  children: ReactNode;
+  /** Theme for the preview */
+  theme: "light" | "dark";
+  /** Width of the preview (CSS value) */
+  width?: number | string;
+  /** Height of the preview (CSS value) */
+  height?: number | string;
+  /** Minimum height of the preview */
+  minHeight?: number | string;
+  /** Called when content size changes */
+  onContentSize?: (size: { width: number; height: number }) => void;
+  /** Additional class name for the host element */
+  className?: string;
+  /** Additional styles for the host element */
+  style?: React.CSSProperties;
+  /** Show size indicator on hover */
+  showSizeIndicator?: boolean;
+}
+
+function toCss(value: number | string | undefined): string | undefined {
+  if (value == null) return undefined;
+  return typeof value === "number" ? `${value}px` : value;
+}
+
+export function ShadowPreview({
+  children,
+  theme,
+  width = "100%",
+  height = "100%",
+  minHeight,
+  onContentSize,
+  className,
+  style,
+  showSizeIndicator = false,
+}: ShadowPreviewProps) {
+  const hostRef = useRef<HTMLDivElement>(null);
+  const shadowRootRef = useRef<ShadowRoot | null>(null);
+  const renderTargetRef = useRef<HTMLDivElement | null>(null);
+  const [renderTarget, setRenderTarget] = useState<HTMLDivElement | null>(null);
+  const [isHovered, setIsHovered] = useState(false);
+  const [contentSize, setContentSize] = useState<{
+    width: number;
+    height: number;
+  } | null>(null);
+
+  // Initialize shadow root (once)
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host || shadowRootRef.current) return;
+
+    const shadow = host.attachShadow({ mode: "open" });
+    shadowRootRef.current = shadow;
+
+    // Base reset styles for the shadow root
+    const baseSheet = new CSSStyleSheet();
+    baseSheet.replaceSync(`
+      *, *::before, *::after {
+        box-sizing: border-box;
+      }
+      :host {
+        display: block;
+        -webkit-font-smoothing: antialiased;
+      }
+      #shadow-preview-root {
+        width: 100%;
+        height: 100%;
+      }
+    `);
+    shadow.adoptedStyleSheets = [baseSheet];
+
+    // Create render target inside shadow
+    const target = document.createElement("div");
+    target.id = "shadow-preview-root";
+    shadow.appendChild(target);
+
+    renderTargetRef.current = target;
+    setRenderTarget(target);
+  }, []);
+
+  // Mirror document styles into shadow root
+  useShadowStyles(shadowRootRef.current);
+
+  // Sync theme attribute on the render target
+  useEffect(() => {
+    if (renderTargetRef.current) {
+      renderTargetRef.current.setAttribute("data-theme", theme);
+    }
+  }, [theme]);
+
+  // ResizeObserver for content size reporting
+  // Uses requestAnimationFrame to avoid "ResizeObserver loop" browser warning
+  const lastSizeRef = useRef<string>("");
+  useEffect(() => {
+    const target = renderTargetRef.current;
+    if (!target) return;
+
+    let rafId = 0;
+    const observer = new ResizeObserver((entries) => {
+      // Defer state update to next frame to avoid ResizeObserver loop warning
+      cancelAnimationFrame(rafId);
+      rafId = requestAnimationFrame(() => {
+        for (const entry of entries) {
+          const { width: w, height: h } = entry.contentRect;
+          const rounded = { width: Math.round(w), height: Math.round(h) };
+          const key = `${rounded.width}x${rounded.height}`;
+          if (key === lastSizeRef.current) return;
+          lastSizeRef.current = key;
+          setContentSize(rounded);
+          onContentSize?.(rounded);
+        }
+      });
+    });
+
+    observer.observe(target);
+    return () => {
+      cancelAnimationFrame(rafId);
+      observer.disconnect();
+    };
+  }, [onContentSize, renderTarget]);
+
+  // Keyboard event isolation — prevent preview key events from reaching
+  // the document-level listener in useKeyboardShortcuts
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host) return;
+
+    const stopKeyboard = (e: Event) => {
+      e.stopPropagation();
+    };
+
+    host.addEventListener("keydown", stopKeyboard);
+    host.addEventListener("keyup", stopKeyboard);
+    return () => {
+      host.removeEventListener("keydown", stopKeyboard);
+      host.removeEventListener("keyup", stopKeyboard);
+    };
+  }, []);
+
+  return (
+    <div
+      ref={hostRef}
+      className={className}
+      onMouseEnter={() => setIsHovered(true)}
+      onMouseLeave={() => setIsHovered(false)}
+      style={{
+        position: "relative",
+        width: toCss(width),
+        height: toCss(height),
+        minHeight: toCss(minHeight),
+        ...style,
+      }}
+    >
+      {/* Portal children into shadow DOM — maintains React context tree */}
+      {renderTarget && createPortal(children, renderTarget)}
+
+      {/* Size indicator */}
+      {showSizeIndicator && contentSize && (
+        <div
+          style={{
+            position: "absolute",
+            bottom: 4,
+            right: 4,
+            padding: "2px 6px",
+            borderRadius: 4,
+            fontFamily: "monospace",
+            opacity: isHovered ? 1 : 0,
+            transition: "opacity 150ms",
+            background: "rgba(0, 0, 0, 0.5)",
+            color: "white",
+            fontSize: 10,
+            zIndex: 10,
+            pointerEvents: "none",
+          }}
+        >
+          {contentSize.width} x {contentSize.height}px
+        </div>
+      )}
+    </div>
+  );
+}