@fragments-sdk/viewer 0.2.1

package/src/entry.tsx

@@ -0,0 +1,335 @@
+import { createRoot, type Root } from "react-dom/client";
+import { Component, type ReactNode, type ErrorInfo } from "react";
+import { App } from "./components/App.js";
+import { ThemeProvider } from "./components/ThemeProvider.js";
+import { ToastProvider } from "./components/Toast.js";
+import { AppSkeleton } from "./components/SkeletonLoader.js";
+import { WebMCPIntegration } from "./components/WebMCPIntegration.js";
+// Fragments UI globals - base resets (box-sizing, body, scrollbars) + --fui-* CSS variables
+import "@fragments-sdk/ui";
+// Viewer-specific token aliases and utility classes
+import "./styles/globals.css";
+
+// App-level error boundary that catches any unhandled errors
+class AppErrorBoundary extends Component<{ children: ReactNode }, { hasError: boolean; error: Error | null; errorInfo: ErrorInfo | null }> {
+  constructor(props: { children: ReactNode }) {
+    super(props);
+    this.state = { hasError: false, error: null, errorInfo: null };
+  }
+
+  static getDerivedStateFromError(error: Error) {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error('[Fragments] App Error:', error);
+    console.error('[Fragments] Component Stack:', errorInfo.componentStack);
+    this.setState({ errorInfo });
+  }
+
+  handleRetry = () => {
+    this.setState({ hasError: false, error: null, errorInfo: null });
+    window.location.reload();
+  };
+
+  render() {
+    if (this.state.hasError) {
+      const { error, errorInfo } = this.state;
+      return (
+        <div style={{
+          fontFamily: 'system-ui, -apple-system, sans-serif',
+          padding: '40px',
+          maxWidth: '800px',
+          margin: '0 auto',
+        }}>
+          <div style={{
+            background: '#fef2f2',
+            border: '1px solid #fecaca',
+            borderRadius: '12px',
+            padding: '24px',
+          }}>
+            <h1 style={{ color: '#dc2626', marginBottom: '16px', fontSize: '20px', fontWeight: 600 }}>
+              Application Error
+            </h1>
+            <p style={{ color: '#991b1b', marginBottom: '16px', fontSize: '14px' }}>
+              An error occurred while rendering the application:
+            </p>
+            <pre style={{
+              background: '#fee2e2',
+              border: '1px solid #fecaca',
+              borderRadius: '8px',
+              padding: '16px',
+              overflow: 'auto',
+              whiteSpace: 'pre-wrap',
+              wordBreak: 'break-word',
+              color: '#991b1b',
+              fontSize: '13px',
+              fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
+              marginBottom: '16px',
+            }}>
+              {error?.message || 'Unknown error'}
+            </pre>
+            {errorInfo?.componentStack && (
+              <details style={{ marginBottom: '16px' }}>
+                <summary style={{
+                  color: '#b91c1c',
+                  cursor: 'pointer',
+                  fontSize: '13px',
+                  marginBottom: '8px',
+                }}>
+                  Show component stack trace
+                </summary>
+                <pre style={{
+                  background: '#fee2e2',
+                  border: '1px solid #fecaca',
+                  borderRadius: '8px',
+                  padding: '12px',
+                  overflow: 'auto',
+                  whiteSpace: 'pre-wrap',
+                  wordBreak: 'break-word',
+                  color: '#7f1d1d',
+                  fontSize: '11px',
+                  fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
+                  maxHeight: '300px',
+                }}>
+                  {error?.stack || errorInfo.componentStack}
+                </pre>
+              </details>
+            )}
+            <button
+              onClick={this.handleRetry}
+              style={{
+                background: '#dc2626',
+                color: 'white',
+                border: 'none',
+                borderRadius: '6px',
+                padding: '10px 16px',
+                fontSize: '14px',
+                fontWeight: 500,
+                cursor: 'pointer',
+              }}
+            >
+              Reload Application
+            </button>
+          </div>
+          <p style={{ marginTop: '16px', color: '#6b7280', fontSize: '13px' }}>
+            Check the browser console for more details. Common causes:
+          </p>
+          <ul style={{ color: '#6b7280', marginTop: '8px', paddingLeft: '20px', fontSize: '13px' }}>
+            <li>Syntax errors in fragment or component files</li>
+            <li>Missing or undefined imports</li>
+            <li>Components that crash during render</li>
+            <li>Invalid props passed to components</li>
+          </ul>
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}
+
+// Declare global types
+declare global {
+  interface Window {
+    __FRAGMENTS__?: Array<{
+      path: string;
+      fragment: import("../core/index.js").FragmentDefinition;
+    }>;
+    __FRAGMENTS_CONFIG__?: import("../core/index.js").FragmentsConfig;
+    __FRAGMENTS_PACKAGE_NAME__?: string | null;
+    __FRAGMENTS_ERROR__?: string;
+  }
+}
+
+type FragmentItem = {
+  path: string;
+  fragment: import("../core/index.js").FragmentDefinition;
+};
+
+// Initialize fragments from window or empty array
+let fragments: FragmentItem[] = window.__FRAGMENTS__ ?? [];
+let loadError: string | null = window.__FRAGMENTS_ERROR__ ?? null;
+let appRoot: Root | null = null;
+const SKELETON_DELAY_MS = 120;
+const MIN_SKELETON_DISPLAY_MS = 220;
+
+// Filter helper
+function filterValidFragments(items: FragmentItem[]): FragmentItem[] {
+  return items.filter(s => s && s.fragment && s.fragment.meta);
+}
+
+// Async loader for virtual module (runs after initial render)
+async function loadFragmentsFromVirtualModule(): Promise<void> {
+  if (fragments.length > 0 || loadError) {
+    // Already have fragments or error from window
+    return;
+  }
+
+  try {
+    // @ts-expect-error Virtual module
+    const virtualModule = await import("virtual:fragments");
+    // Wait for lazy-loaded fragments
+    if (virtualModule.fragmentsPromise) {
+      fragments = await virtualModule.fragmentsPromise;
+    } else {
+      fragments = virtualModule.fragments;
+    }
+    fragments = filterValidFragments(fragments);
+    // Store consumer package name for import path display
+    if (virtualModule.projectPackageName) {
+      window.__FRAGMENTS_PACKAGE_NAME__ = virtualModule.projectPackageName;
+    }
+  } catch (e) {
+    const error = e as Error;
+    loadError = error.message || "Failed to load fragments";
+    console.error("[Fragments] Failed to load:", error);
+  }
+}
+
+// Filter initial fragments
+fragments = filterValidFragments(fragments);
+
+// Error display component
+function ErrorDisplay({ error }: { error: string }) {
+  return (
+    <div style={{
+      fontFamily: 'system-ui, -apple-system, sans-serif',
+      padding: '40px',
+      maxWidth: '600px',
+      margin: '0 auto',
+    }}>
+      <h1 style={{ color: '#dc2626', marginBottom: '16px' }}>
+        Failed to Load Fragments
+      </h1>
+      <pre style={{
+        background: '#fef2f2',
+        border: '1px solid #fecaca',
+        borderRadius: '8px',
+        padding: '16px',
+        overflow: 'auto',
+        whiteSpace: 'pre-wrap',
+        wordBreak: 'break-word',
+        color: '#991b1b',
+        fontSize: '14px',
+      }}>
+        {error}
+      </pre>
+      <p style={{ marginTop: '16px', color: '#6b7280' }}>
+        Check the console for more details. Common issues:
+      </p>
+      <ul style={{ color: '#6b7280', marginTop: '8px', paddingLeft: '20px' }}>
+        <li>Fragment files have syntax errors</li>
+        <li>Components are not exported correctly</li>
+        <li>Missing dependencies</li>
+      </ul>
+    </div>
+  );
+}
+
+// Render the app
+const rootElement = document.getElementById("root");
+if (rootElement) {
+  appRoot = createRoot(rootElement);
+
+  const renderApp = (showSkeleton = false) => {
+    const currentFragments = window.__FRAGMENTS__ ?? fragments;
+    const currentError = loadError || window.__FRAGMENTS_ERROR__;
+
+    // Show skeleton while loading
+    if (showSkeleton && currentFragments.length === 0 && !currentError) {
+      appRoot?.render(
+        <ThemeProvider>
+          <AppSkeleton />
+        </ThemeProvider>
+      );
+      return;
+    }
+
+    // Show error if we have one and no valid fragments
+    if (currentError && currentFragments.length === 0) {
+      appRoot?.render(<ErrorDisplay error={currentError} />);
+      return;
+    }
+
+    appRoot?.render(
+      <ThemeProvider>
+        <ToastProvider position="bottom-right" duration={3000}>
+          <WebMCPIntegration>
+            <AppErrorBoundary>
+              <App fragments={currentFragments} />
+            </AppErrorBoundary>
+          </WebMCPIntegration>
+        </ToastProvider>
+      </ThemeProvider>
+    );
+  };
+
+  // Show skeleton immediately if no fragments yet
+  if (fragments.length === 0 && !loadError) {
+    const loadStartedAt = Date.now();
+    let skeletonShown = false;
+
+    const skeletonTimer = setTimeout(() => {
+      skeletonShown = true;
+      renderApp(true);
+    }, SKELETON_DELAY_MS);
+
+    // Load fragments asynchronously and re-render
+    loadFragmentsFromVirtualModule().then(() => {
+      clearTimeout(skeletonTimer);
+
+      if (!skeletonShown) {
+        renderApp(false);
+        return;
+      }
+
+      const elapsed = Date.now() - loadStartedAt;
+      const remaining = Math.max(MIN_SKELETON_DISPLAY_MS - elapsed, 0);
+      if (remaining === 0) {
+        renderApp(false);
+        return;
+      }
+
+      setTimeout(() => {
+        renderApp(false);
+      }, remaining);
+    });
+  } else {
+    // We have fragments from window, render immediately
+    renderApp(false);
+  }
+
+  // Listen for HMR updates from Fragments plugin
+  window.addEventListener("fragments:update", () => {
+    console.log("[Fragments] Refreshing viewer...");
+    // Re-render with updated fragments
+    renderApp(false);
+  });
+}
+
+// HMR support for entry file and a11y invalidation
+// @ts-expect-error Vite HMR types
+if (import.meta.hot) {
+  // @ts-expect-error Vite HMR types
+  import.meta.hot.accept();
+
+  // Subscribe to a11y invalidation events from Vite plugin
+  // @ts-expect-error Vite HMR types
+  import.meta.hot.on("fragments:a11y-invalidate", (data: {
+    components: string[];
+    file: string;
+    timestamp: number;
+  }) => {
+    console.log("[Fragments] A11y invalidation triggered for:", data.components.join(", "));
+
+    // Dispatch custom event for a11y service to handle
+    window.dispatchEvent(new CustomEvent("a11y-cache-invalidated", {
+      detail: {
+        components: data.components,
+        file: data.file,
+        timestamp: data.timestamp,
+      },
+    }));
+  });
+}

package/src/hooks/index.ts

@@ -0,0 +1,2 @@
+export * from './useHmrStatus.js';
+export * from './usePreviewBridge.js';