@fragments-sdk/cli 0.7.13 → 0.7.15

package/src/core/preview-runtime.tsx

@@ -0,0 +1,144 @@
+import { useEffect, useState, type ReactNode } from "react";
+import type { VariantLoader, VariantRenderOptions } from "./types.js";
+
+/**
+ * Minimal contract for rendering a preview variant.
+ * Compatible with fragment variants and Storybook-adapted variants.
+ */
+export interface PreviewVariantLike {
+  render: (options?: VariantRenderOptions) => ReactNode;
+  loaders?: VariantLoader[];
+}
+
+export interface PreviewRuntimeState {
+  content: ReactNode | null;
+  isLoading: boolean;
+  error: Error | null;
+  loadedData?: Record<string, unknown>;
+}
+
+export interface PreviewRuntimeOptions {
+  variant?: PreviewVariantLike | null;
+  loadedData?: Record<string, unknown>;
+}
+
+const EMPTY_STATE: PreviewRuntimeState = {
+  content: null,
+  isLoading: false,
+  error: null,
+  loadedData: undefined,
+};
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+/**
+ * Execute all variant loaders and merge their payloads.
+ * `loadedData` is applied last so host-level overrides win.
+ */
+export async function executeVariantLoaders(
+  loaders: VariantLoader[] | undefined,
+  loadedData?: Record<string, unknown>,
+): Promise<Record<string, unknown> | undefined> {
+  const hasLoaders = !!loaders && loaders.length > 0;
+  if (!hasLoaders) {
+    return loadedData;
+  }
+
+  const results = await Promise.all(loaders.map((loader) => loader()));
+  const mergedFromLoaders = results.reduce<Record<string, unknown>>(
+    (acc, result) => ({ ...acc, ...result }),
+    {},
+  );
+
+  return loadedData ? { ...mergedFromLoaders, ...loadedData } : mergedFromLoaders;
+}
+
+/**
+ * Resolve a full runtime state (loader execution + render) in one async call.
+ * This is useful for testing and for hook/component orchestration.
+ */
+export async function resolvePreviewRuntimeState(
+  options: PreviewRuntimeOptions,
+): Promise<PreviewRuntimeState> {
+  const { variant, loadedData } = options;
+  if (!variant) {
+    return EMPTY_STATE;
+  }
+
+  try {
+    const mergedLoadedData = await executeVariantLoaders(variant.loaders, loadedData);
+    const content = variant.render({ loadedData: mergedLoadedData });
+    return {
+      content,
+      isLoading: false,
+      error: null,
+      loadedData: mergedLoadedData,
+    };
+  } catch (error) {
+    return {
+      content: null,
+      isLoading: false,
+      error: toError(error),
+      loadedData: undefined,
+    };
+  }
+}
+
+/**
+ * Hook for rendering a preview variant with loader support.
+ */
+export function usePreviewVariantRuntime(
+  options: PreviewRuntimeOptions,
+): PreviewRuntimeState {
+  const { variant, loadedData } = options;
+  const [state, setState] = useState<PreviewRuntimeState>(EMPTY_STATE);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    if (!variant) {
+      setState(EMPTY_STATE);
+      return () => {
+        cancelled = true;
+      };
+    }
+
+    const hasLoaders = !!variant.loaders && variant.loaders.length > 0;
+    setState({
+      content: null,
+      isLoading: hasLoaders,
+      error: null,
+      loadedData: undefined,
+    });
+
+    resolvePreviewRuntimeState({ variant, loadedData }).then((nextState) => {
+      if (!cancelled) {
+        setState(nextState);
+      }
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [variant, loadedData]);
+
+  return state;
+}
+
+interface PreviewVariantRuntimeProps extends PreviewRuntimeOptions {
+  children: (state: PreviewRuntimeState) => ReactNode;
+}
+
+/**
+ * Render-prop component wrapper around `usePreviewVariantRuntime`.
+ */
+export function PreviewVariantRuntime({
+  variant,
+  loadedData,
+  children,
+}: PreviewVariantRuntimeProps) {
+  const state = usePreviewVariantRuntime({ variant, loadedData });
+  return <>{children(state)}</>;
+}

package/src/viewer/components/App.tsx

@@ -20,20 +20,18 @@ import { PreviewToolbar } from "./PreviewToolbar.js";
 import { PreviewArea } from "./PreviewArea.js";
 import { BottomPanel } from "./BottomPanel.js";
 import { IsolatedRender } from "./IsolatedRender.js";
-import { StoryRenderer, LoaderIndicator } from "./StoryRenderer.js";
+import { FragmentRenderer, LoaderIndicator } from "./FragmentRenderer.js";
 import { HealthDashboard } from "./HealthDashboard.js";
 import { useAllFigmaUrls } from "./FigmaEmbed.js";
 import { ActionCapture } from "./ActionCapture.js";
 
 // Fragments UI
-import { Header, Stack, Text, Separator, Tooltip, Button, EmptyState, Box, Alert, Input, ThemeToggle } from "@fragments-sdk/ui";
+import { Header, Stack, Text, Separator, Tooltip, Button, EmptyState, Box, Alert, Input, ThemeToggle, FragmentsLogo } from "@fragments-sdk/ui";
 import { DeviceMobile, GridFour, Rows } from "@phosphor-icons/react";
 
 // Icons
 import { EmptyIcon, FigmaIcon, CompareIcon } from "./Icons.js";
 
-// Logo
-import { fragmentsLogo } from "../assets/fragments-logo.js";
 
 function GitHubIcon() {
   return (
@@ -342,14 +340,14 @@ export function App({ fragments }: AppProps) {
 
     return (
       <ActionCapture onAction={useActionsRef.current.logAction}>
-        <StoryRenderer variant={variant}>
+        <FragmentRenderer variant={variant}>
           {(content, isLoading, error) => {
             if (isLoading) return <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', padding: '32px' }}><LoaderIndicator /></div>;
             if (error) return <EmptyVariantMessage reason={`Error: ${error.message}`} variantName={variant.name} hint="Check the console for the full error stack trace." />;
             if (content === null || content === undefined) return <EmptyVariantMessage reason="render() returned null or undefined" variantName={variant.name} hint="The variant's render function didn't return any JSX." />;
             return content;
           }}
-        </StoryRenderer>
+        </FragmentRenderer>
       </ActionCapture>
     );
   }, []);
@@ -605,7 +603,7 @@ function ViewerHeader({ showHealth, searchQuery, onSearchChange, searchInputRef
       <Header.Trigger />
       <Header.Brand>
         <Stack direction="row" gap="sm" align="center">
-          <img src={fragmentsLogo} alt="" width={20} height={20} style={{ display: 'block' }} />
+          <FragmentsLogo size={20} />
           <Text weight="medium" size="sm">{BRAND.name}</Text>
           <Text size="xs" color="tertiary">{showHealth ? 'health dashboard' : 'preview'}</Text>
         </Stack>
@@ -761,7 +759,7 @@ function TopToolbar({
       <Header.Trigger />
       <Header.Brand>
         <Stack direction="row" align="center" gap="sm">
-          <img src={fragmentsLogo} alt="" width={20} height={20} style={{ display: 'block' }} />
+          <FragmentsLogo size={20} />
           <Text weight="medium" size="sm">{fragment.fragment.meta.name}</Text>
           <Text size="xs" color="tertiary">{fragment.fragment.meta.category}</Text>
         </Stack>

package/src/viewer/components/FragmentRenderer.tsx

@@ -0,0 +1,61 @@
+import type { ReactNode } from "react";
+import {
+  PreviewVariantRuntime,
+  type FragmentVariant,
+} from "../../core/index.js";
+
+interface FragmentRendererProps {
+  /** The variant to render */
+  variant: FragmentVariant;
+  /** Children render function - receives rendered content */
+  children: (content: ReactNode | null, isLoading: boolean, error: Error | null) => ReactNode;
+}
+
+/**
+ * Component that handles async loader execution before rendering a fragment variant.
+ *
+ * If the variant has loaders:
+ * 1. Shows loading state while loaders execute
+ * 2. Merges all loaded data
+ * 3. Passes loaded data to render function
+ *
+ * If no loaders, renders immediately.
+ */
+export function FragmentRenderer({ variant, children }: FragmentRendererProps) {
+  return (
+    <PreviewVariantRuntime variant={variant}>
+      {({ content, isLoading, error }) => children(content, isLoading, error)}
+    </PreviewVariantRuntime>
+  );
+}
+
+/**
+ * Loading indicator for fragment variants with loaders
+ */
+export function LoaderIndicator() {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '8px', color: 'var(--text-secondary)', fontSize: '14px' }}>
+      <svg
+        style={{ animation: 'spin 1s linear infinite', width: '16px', height: '16px' }}
+        xmlns="http://www.w3.org/2000/svg"
+        fill="none"
+        viewBox="0 0 24 24"
+      >
+        <circle
+          style={{ opacity: 0.25 }}
+          cx="12"
+          cy="12"
+          r="10"
+          stroke="currentColor"
+          strokeWidth="4"
+        />
+        <path
+          style={{ opacity: 0.75 }}
+          fill="currentColor"
+          d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+        />
+      </svg>
+      <span>Running loaders...</span>
+    </div>
+  );
+}

package/src/viewer/components/IsolatedPreviewFrame.tsx

@@ -70,9 +70,9 @@ export const IsolatedPreviewFrame = memo(function IsolatedPreviewFrame({
   const [frameError, setFrameError] = useState<string | null>(null);
   const [retryCount, setRetryCount] = useState(0);
   const [iframeKey, setIframeKey] = useState(0);
+  const [hasRenderedOnce, setHasRenderedOnce] = useState(false);
   const { isReady, isRendering, lastError, contentSize, render, setTheme, clearError } = usePreviewBridge(iframeRef);
   const lastRenderRef = useRef<string>('');
-  const isFirstLoad = useRef(true);
   const [isHovered, setIsHovered] = useState(false);
 
   // Build the preview URL
@@ -82,7 +82,6 @@ export const IsolatedPreviewFrame = memo(function IsolatedPreviewFrame({
   const handleLoad = useCallback(() => {
     setIsLoading(false);
     setFrameError(null);
-    isFirstLoad.current = false;
   }, []);
 
   // Handle iframe error
@@ -100,6 +99,7 @@ export const IsolatedPreviewFrame = memo(function IsolatedPreviewFrame({
     clearError();
     setRetryCount(c => c + 1);
     setIsLoading(true);
+    setHasRenderedOnce(false);
     lastRenderRef.current = ''; // Force re-render
     setIframeKey(k => k + 1); // Force iframe reload
   }, [retryCount, clearError]);
@@ -125,6 +125,7 @@ export const IsolatedPreviewFrame = memo(function IsolatedPreviewFrame({
   // Report content size changes
   useEffect(() => {
     if (contentSize) {
+      setHasRenderedOnce(true);
       onContentSize?.(contentSize);
     }
   }, [contentSize, onContentSize]);
@@ -142,11 +143,12 @@ export const IsolatedPreviewFrame = memo(function IsolatedPreviewFrame({
   const frameHeight = typeof height === 'number' ? `${height}px` : height;
   const frameMinHeight = typeof minHeight === 'number' ? `${minHeight}px` : minHeight;
 
-  // Determine if we should show skeleton vs spinner
-  // Skeleton for initial load, spinner for subsequent renders
-  const showSkeleton = isLoading && isFirstLoad.current;
-  const showSpinner = !showSkeleton && (isLoading || isRendering);
-  const showContent = isReady && !isRendering && !frameError;
+  // Keep first-load skeleton visible until the first successful render signal.
+  // After first render, preserve content visibility and show spinner overlays
+  // for later renders to avoid white/blank flashes.
+  const showSkeleton = !hasRenderedOnce && !frameError;
+  const showSpinner = hasRenderedOnce && !frameError && (isLoading || isRendering);
+  const showContent = !frameError && (hasRenderedOnce || (isReady && !isRendering));
 
   return (
     <div
@@ -259,7 +261,7 @@ export const IsolatedPreviewFrame = memo(function IsolatedPreviewFrame({
           border: 'none',
           display: 'block',
           background: 'transparent',
-          transition: 'opacity 150ms',
+          transition: 'opacity 120ms ease',
           opacity: showContent ? 1 : 0,
         }}
         // Security attributes

package/src/viewer/components/PreviewFrameHost.tsx

@@ -8,19 +8,15 @@
  * 4. Reports render status back to parent
  */
 
-import { useState, useEffect, useRef, type ReactNode } from 'react';
+import { useState, useEffect, useRef } from 'react';
+import {
+  usePreviewVariantRuntime,
+  type FragmentVariant,
+} from '../../core/index.js';
 import { useFrameBridge } from '../hooks/usePreviewBridge.js';
 
 // Types for fragment data
-interface FragmentVariant {
-  name: string;
-  render: (options?: { loadedData?: Record<string, unknown> }) => ReactNode;
-  loaders?: Array<() => Promise<Record<string, unknown>>>;
-  props?: Record<string, unknown>;
-  hasPlayFunction?: boolean;
-}
-
-interface FragmentDefinition {
+interface PreviewFragmentDefinition {
   meta: {
     name: string;
     description?: string;
@@ -31,7 +27,7 @@ interface FragmentDefinition {
 
 interface FragmentItem {
   path: string;
-  fragment: FragmentDefinition;
+  fragment: PreviewFragmentDefinition;
 }
 
 // Cached fragments
@@ -79,13 +75,13 @@ function findFragmentByPath(fragments: FragmentItem[], path: string): FragmentIt
 /**
  * Find a variant by name within a fragment
  */
-function findVariant(fragment: FragmentDefinition, variantName: string): FragmentVariant | undefined {
+function findVariant(fragment: PreviewFragmentDefinition, variantName: string): FragmentVariant | undefined {
   return fragment.variants?.find(v => v.name === variantName);
 }
 
 type PreviewMode = 'centered' | 'full-bleed';
 
-function resolvePreviewMode(fragment: FragmentDefinition): PreviewMode {
+function resolvePreviewMode(fragment: PreviewFragmentDefinition): PreviewMode {
   const name = fragment.meta.name.toLowerCase();
   const category = (fragment.meta.category || '').toLowerCase();
 
@@ -142,65 +138,36 @@ function VariantRenderer({
   onRendered: (width: number, height: number) => void;
   onError: (message: string, stack?: string) => void;
 }) {
-  const [content, setContent] = useState<ReactNode | null>(null);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<{ message: string; stack?: string } | null>(null);
+  const { content, isLoading, error } = usePreviewVariantRuntime({
+    variant,
+    loadedData: props,
+  });
   const containerRef = useRef<HTMLDivElement>(null);
   const hasReported = useRef(false);
+  const lastReportedError = useRef<string | null>(null);
 
   useEffect(() => {
     hasReported.current = false;
-    setContent(null);
-    setError(null);
-
-    const hasLoaders = variant.loaders && variant.loaders.length > 0;
-
-    if (!hasLoaders) {
-      // No loaders - render immediately
-      try {
-        const rendered = variant.render({ loadedData: props });
-        setContent(rendered);
-      } catch (err) {
-        const errorObj = err instanceof Error ? err : new Error(String(err));
-        setError({ message: errorObj.message, stack: errorObj.stack });
-        onError(errorObj.message, errorObj.stack);
-      }
+  }, [variant, props, mode]);
+
+  useEffect(() => {
+    if (!error) {
+      lastReportedError.current = null;
       return;
     }
 
-    // Has loaders - execute them first
-    setIsLoading(true);
-    let cancelled = false;
-
-    async function executeLoaders() {
-      try {
-        const results = await Promise.all(variant.loaders!.map(loader => loader()));
-        if (cancelled) return;
-
-        const merged = results.reduce((acc, result) => ({ ...acc, ...result }), {});
-        const rendered = variant.render({ loadedData: { ...merged, ...props } });
-
-        setContent(rendered);
-        setIsLoading(false);
-      } catch (err) {
-        if (cancelled) return;
-        const errorObj = err instanceof Error ? err : new Error(String(err));
-        setError({ message: errorObj.message, stack: errorObj.stack });
-        setIsLoading(false);
-        onError(errorObj.message, errorObj.stack);
-      }
+    const signature = `${error.message}:${error.stack ?? ''}`;
+    if (lastReportedError.current === signature) {
+      return;
     }
 
-    executeLoaders();
-
-    return () => {
-      cancelled = true;
-    };
-  }, [variant, props, onError]);
+    lastReportedError.current = signature;
+    onError(error.message, error.stack);
+  }, [error, onError]);
 
   // Report rendered size after content renders
   useEffect(() => {
-    if (!content || hasReported.current) return;
+    if (!content || hasReported.current || isLoading || error) return;
 
     // Wait for next frame to ensure DOM has updated
     requestAnimationFrame(() => {
@@ -210,7 +177,7 @@ function VariantRenderer({
         onRendered(rect.width, rect.height);
       }
     });
-  }, [content, onRendered]);
+  }, [content, error, isLoading, onRendered]);
 
   if (isLoading) {
     return <LoadingIndicator />;