@fragments-sdk/cli 0.7.9 → 0.7.11

package/src/viewer/components/App.tsx

@@ -3,20 +3,19 @@
  * Refactored for better performance and maintainability.
  */
 
-import { useState, useMemo, useEffect, useCallback, useRef, type RefObject } from "react";
-import { BRAND, type FragmentDefinition } from "../../core/index.js";
+import { useState, useMemo, useEffect, useCallback, useRef, type CSSProperties, type ReactNode, type RefObject } from "react";
+import { BRAND, type FragmentDefinition, type FragmentVariant } from "../../core/index.js";
 
 // Layout & Navigation
 import { Layout } from "./Layout.js";
 import { LeftSidebar } from "./LeftSidebar.js";
-import { VariantTabs } from "./VariantTabs.js";
 import { CommandPalette } from "./CommandPalette.js";
 import { KeyboardShortcutsHelp } from "./KeyboardShortcutsHelp.js";
 import { useToast } from "./Toast.js";
 
 // Toolbar
-import { PreviewToolbar, getBackgroundStyle } from "./PreviewToolbar.js";
-import { ViewportSelector } from "./ViewportSelector.js";
+import { PreviewToolbar } from "./PreviewToolbar.js";
+import { getBackgroundStyle } from "../constants/ui.js";
 
 // Preview & Rendering
 import { PreviewArea } from "./PreviewArea.js";
@@ -28,10 +27,11 @@ import { useAllFigmaUrls } from "./FigmaEmbed.js";
 import { ActionCapture } from "./ActionCapture.js";
 
 // Fragments UI
-import { Header, Stack, Text, Separator, Tooltip, Button, EmptyState, Box, Alert, ScrollArea, Input, ThemeToggle } from "@fragments/ui";
+import { Header, Stack, Text, Separator, Tooltip, Button, EmptyState, Box, Alert, Input, ThemeToggle } from "@fragments-sdk/ui";
+import { DeviceMobile, GridFour, Rows } from "@phosphor-icons/react";
 
 // Icons
-import { EmptyIcon, ExternalLinkIcon, FigmaIcon, CompareIcon, CheckIcon, LinkIcon, GridIcon, DevicesIcon } from "./Icons.js";
+import { EmptyIcon, FigmaIcon, CompareIcon } from "./Icons.js";
 
 // Logo
 import { fragmentsLogo } from "../assets/fragments-logo.js";
@@ -54,9 +54,6 @@ import { useUrlState, findFragmentByName, findVariantIndex } from "../hooks/useU
 import { usePanelDock } from "./ResizablePanel.js";
 import { useTheme } from "./ThemeProvider.js";
 
-// Utilities
-import { ScreenshotButton } from "./ScreenshotButton.js";
-
 interface AppProps {
   fragments: Array<{ path: string; fragment: FragmentDefinition }>;
 }
@@ -102,6 +99,8 @@ export function App({ fragments }: AppProps) {
     }
     return fragments[0]?.path ?? null;
   });
+  const activeFragmentPathRef = useRef(activeFragmentPath);
+  activeFragmentPathRef.current = activeFragmentPath;
 
   const [activeVariantIndex, setActiveVariantIndex] = useState<number>(() => {
     const fragment = fragments.find(s => s.path === activeFragmentPath);
@@ -118,7 +117,11 @@ export function App({ fragments }: AppProps) {
     () => fragments.find((s) => s.path === activeFragmentPath),
     [fragments, activeFragmentPath]
   );
-  const activeVariant = activeFragment?.fragment.variants?.[activeVariantIndex];
+  const variants = activeFragment?.fragment.variants ?? [];
+  const variantCount = variants.length;
+  const safeVariantIndex = variantCount > 0 ? Math.min(activeVariantIndex, variantCount - 1) : 0;
+  const activeVariant = variants[safeVariantIndex];
+  const isAllVariantsMode = !urlState.variant;
   const figmaUrl = activeVariant?.figma || activeFragment?.fragment.meta.figma;
 
   // Figma integration
@@ -149,17 +152,34 @@ export function App({ fragments }: AppProps) {
     }
   }, [uiState.showComparison, activeVariant, figmaIntegration.extractRenderedStyles, uiState.previewKey]);
 
+  // Keep focused variant index in range when variant lists change.
+  useEffect(() => {
+    if (variantCount === 0) {
+      setActiveVariantIndex(0);
+      return;
+    }
+    if (activeVariantIndex >= variantCount) {
+      setActiveVariantIndex(variantCount - 1);
+    }
+  }, [activeVariantIndex, variantCount]);
+
   // Sync URL state on browser navigation
   useEffect(() => {
     if (urlState.component) {
       const found = findFragmentByName(fragments, urlState.component);
-      if (found && found.path !== activeFragmentPath) {
-        setActiveFragmentPath(found.path);
+      if (!found) return;
+
+      const pathChanged = found.path !== activeFragmentPathRef.current;
+      setActiveFragmentPath(found.path);
+      uiActions.setHealthDashboard(false);
+
+      // Keep focused variant when entering "All" on the same component.
+      if (urlState.variant || pathChanged) {
         const variantIndex = findVariantIndex(found.fragment.variants, urlState.variant);
         setActiveVariantIndex(variantIndex);
       }
     }
-  }, [urlState.component, urlState.variant, fragments, activeFragmentPath]);
+  }, [urlState.component, urlState.variant, fragments, uiActions]);
 
   // HMR toast notifications
   useEffect(() => {
@@ -181,19 +201,64 @@ export function App({ fragments }: AppProps) {
   const handleSelectFragment = useCallback((path: string) => {
     const fragment = fragments.find((s) => s.path === path);
     const componentName = fragment?.fragment.meta.name || path;
-    const firstVariant = fragment?.fragment.variants?.[0]?.name;
 
     setActiveFragmentPath(path);
     setActiveVariantIndex(0);
     uiActions.setHealthDashboard(false);
-    setUrlComponent(componentName, firstVariant);
+    setUrlComponent(componentName, null);
   }, [fragments, setUrlComponent, uiActions]);
 
+  const scrollToVariantSection = useCallback(
+    (index: number, behavior: ScrollBehavior = "smooth") => {
+      if (!activeFragment || variantCount === 0) return;
+      const normalizedIndex = ((index % variantCount) + variantCount) % variantCount;
+      const targetVariant = variants[normalizedIndex];
+      if (!targetVariant) return;
+
+      const sectionId = getVariantSectionId(activeFragment.fragment.meta.name, targetVariant.name);
+      document.getElementById(sectionId)?.scrollIntoView({ behavior, block: "start" });
+    },
+    [activeFragment, variantCount, variants]
+  );
+
+  const focusVariantInAllMode = useCallback(
+    (index: number, shouldScroll = false) => {
+      if (variantCount === 0) return;
+      const normalizedIndex = ((index % variantCount) + variantCount) % variantCount;
+      setActiveVariantIndex(normalizedIndex);
+      if (shouldScroll) {
+        scrollToVariantSection(normalizedIndex);
+      }
+    },
+    [variantCount, scrollToVariantSection]
+  );
+
   const handleSelectVariant = useCallback((index: number) => {
-    const variantName = activeFragment?.fragment.variants?.[index]?.name;
-    setActiveVariantIndex(index);
+    if (variantCount === 0) return;
+    const normalizedIndex = ((index % variantCount) + variantCount) % variantCount;
+    const variantName = variants[normalizedIndex]?.name;
+    setActiveVariantIndex(normalizedIndex);
     setUrlVariant(variantName || null);
-  }, [activeFragment, setUrlVariant]);
+  }, [variantCount, variants, setUrlVariant]);
+
+  const handleSelectAllVariants = useCallback(() => {
+    setUrlVariant(null);
+    requestAnimationFrame(() => {
+      const previewCanvas = document.getElementById("preview-canvas");
+      if (previewCanvas instanceof HTMLElement) {
+        previewCanvas.scrollTo({ top: 0, behavior: "smooth" });
+      }
+    });
+  }, [setUrlVariant]);
+
+  const handleSelectVariantLink = useCallback((index: number) => {
+    if (isAllVariantsMode) {
+      // In All mode, selecting a variant link exits All and opens that single variant.
+      handleSelectVariant(index);
+      return;
+    }
+    handleSelectVariant(index);
+  }, [handleSelectVariant, isAllVariantsMode]);
 
   // Copy link handler
   const handleCopyLink = useCallback(async () => {
@@ -219,7 +284,6 @@ export function App({ fragments }: AppProps) {
   }, [fragments]);
 
   const currentFragmentIndex = sortedFragmentPaths.indexOf(activeFragmentPath || '');
-  const variantCount = activeFragment?.fragment.variants?.length || 0;
 
   // Keyboard shortcuts
   useKeyboardShortcuts(
@@ -232,11 +296,36 @@ export function App({ fragments }: AppProps) {
         const prevIndex = currentFragmentIndex > 0 ? currentFragmentIndex - 1 : sortedFragmentPaths.length - 1;
         handleSelectFragment(sortedFragmentPaths[prevIndex]);
       },
-      nextVariant: () => handleSelectVariant(activeVariantIndex < variantCount - 1 ? activeVariantIndex + 1 : 0),
-      prevVariant: () => handleSelectVariant(activeVariantIndex > 0 ? activeVariantIndex - 1 : variantCount - 1),
-      goToVariant: (index) => index < variantCount && handleSelectVariant(index),
+      nextVariant: () => {
+        if (variantCount === 0) return;
+        const nextIndex = activeVariantIndex < variantCount - 1 ? activeVariantIndex + 1 : 0;
+        if (isAllVariantsMode) {
+          focusVariantInAllMode(nextIndex, true);
+          return;
+        }
+        handleSelectVariant(nextIndex);
+      },
+      prevVariant: () => {
+        if (variantCount === 0) return;
+        const prevIndex = activeVariantIndex > 0 ? activeVariantIndex - 1 : variantCount - 1;
+        if (isAllVariantsMode) {
+          focusVariantInAllMode(prevIndex, true);
+          return;
+        }
+        handleSelectVariant(prevIndex);
+      },
+      goToVariant: (index) => {
+        if (index >= variantCount) return;
+        if (isAllVariantsMode) {
+          focusVariantInAllMode(index, true);
+          return;
+        }
+        handleSelectVariant(index);
+      },
       toggleTheme: viewSettings.toggleTheme,
       togglePanel: uiActions.togglePanel,
+      toggleMatrix: () => uiActions.setMatrixView(!uiState.showMatrixView),
+      toggleResponsive: () => uiActions.setMultiViewport(!uiState.showMultiViewport),
       copyLink: handleCopyLink,
       showHelp: uiActions.toggleShortcutsHelp,
       openSearch: focusSearchInput,
@@ -256,22 +345,22 @@ export function App({ fragments }: AppProps) {
   );
 
   // Render variant with action logging via DOM event capture
-  const renderVariantWithProps = useCallback(() => {
-    if (!activeVariant) return null;
+  const renderVariantWithProps = useCallback((variant: FragmentVariant | undefined) => {
+    if (!variant) return null;
 
     return (
       <ActionCapture onAction={useActionsRef.current.logAction}>
-        <StoryRenderer variant={activeVariant}>
+        <StoryRenderer 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={activeVariant.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={activeVariant.name} hint="The variant's render function didn't return any JSX." />;
+            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>
       </ActionCapture>
     );
-  }, [activeVariant]);
+  }, []);
 
   // Check if isolated mode
   const isIsolated = useMemo(() => {
@@ -302,13 +391,9 @@ export function App({ fragments }: AppProps) {
           activeFragment && !uiState.showHealthDashboard ? (
             <TopToolbar
               fragment={activeFragment}
-              variant={activeVariant}
-              viewSettings={viewSettings}
               uiState={uiState}
               uiActions={uiActions}
               figmaUrl={figmaUrl}
-              linkCopied={uiState.linkCopied}
-              onCopyLink={handleCopyLink}
               searchQuery={searchQuery}
               onSearchChange={setSearchQuery}
               searchInputRef={searchInputRef}
@@ -335,6 +420,21 @@ export function App({ fragments }: AppProps) {
             }}
           />
         }
+        aside={
+          activeFragment && !uiState.showHealthDashboard ? (
+            <PreviewAside
+              fragment={activeFragment.fragment}
+              variants={variants}
+              focusedVariantIndex={safeVariantIndex}
+              isAllVariantsMode={isAllVariantsMode}
+              activePanel={uiState.activePanel}
+              onSelectAllVariants={handleSelectAllVariants}
+              onSelectVariant={handleSelectVariantLink}
+              onCopyLink={handleCopyLink}
+              onShowShortcuts={uiActions.toggleShortcutsHelp}
+            />
+          ) : null
+        }
       >
         {uiState.showHealthDashboard ? (
           <div style={{ height: '100%', overflow: 'auto', backgroundColor: 'var(--bg-primary)' }}>
@@ -352,24 +452,25 @@ export function App({ fragments }: AppProps) {
             </Box>
           </div>
         ) : activeFragment ? (
-          <div style={{ display: 'flex', height: '100%', flexDirection: panelDock === "bottom" ? 'column' : 'row' }}>
+          <div id="preview-layout" style={{ display: 'flex', height: '100%', flexDirection: panelDock === "bottom" ? 'column' : 'row' }}>
             {/* Main Content Area */}
             <div style={{ flex: 1, display: 'flex', flexDirection: 'column', minWidth: 0, minHeight: 0 }}>
-              {/* Variant Tabs */}
-              {activeFragment.fragment.variants && activeFragment.fragment.variants.length > 0 && (
-                <VariantTabsBar
-                  variants={activeFragment.fragment.variants}
-                  activeIndex={activeVariantIndex}
-                  onSelect={handleSelectVariant}
-                  showMatrixView={uiState.showMatrixView}
-                  showMultiViewport={uiState.showMultiViewport}
-                  onToggleMatrix={() => uiActions.setMatrixView(!uiState.showMatrixView)}
-                  onToggleMultiViewport={() => uiActions.setMultiViewport(!uiState.showMultiViewport)}
-                />
-              )}
+              <PreviewControlsBar
+                zoom={viewSettings.zoom}
+                background={viewSettings.background}
+                onZoomChange={viewSettings.setZoom}
+                onBackgroundChange={viewSettings.setBackground}
+                showMatrixView={uiState.showMatrixView}
+                showMultiViewport={uiState.showMultiViewport}
+                panelOpen={uiState.panelOpen}
+                onToggleMatrix={() => uiActions.setMatrixView(!uiState.showMatrixView)}
+                onToggleMultiViewport={() => uiActions.setMultiViewport(!uiState.showMultiViewport)}
+                onTogglePanel={uiActions.togglePanel}
+              />
 
               {/* Preview Area */}
               <div
+                id="preview-canvas"
                 style={{
                   flex: 1,
                   overflow: 'auto',
@@ -377,12 +478,32 @@ export function App({ fragments }: AppProps) {
                   ...(uiState.showMatrixView ? {} : getBackgroundStyle(viewSettings.background)),
                 }}
               >
-                {activeVariant ? (
+                {variantCount === 0 ? (
+                  <NoVariantsMessage fragment={activeFragment?.fragment} />
+                ) : isAllVariantsMode && !uiState.showMatrixView && !uiState.showMultiViewport ? (
+                  <AllVariantsPreview
+                    componentName={activeFragment.fragment.meta.name}
+                    fragmentPath={activeFragment.path}
+                    variants={variants}
+                    focusedVariantIndex={safeVariantIndex}
+                    zoom={viewSettings.zoom}
+                    background={viewSettings.background}
+                    viewport={viewSettings.viewport}
+                    customSize={viewSettings.customSize}
+                    previewTheme={resolvedTheme}
+                    showComparison={uiState.showComparison}
+                    allFigmaUrls={allFigmaUrls}
+                    fallbackFigmaUrl={activeFragment.fragment.meta.figma}
+                    onRetry={uiActions.incrementPreviewKey}
+                    renderVariantContent={renderVariantWithProps}
+                    previewKeyBase={`${activeFragmentPath}-${uiState.previewKey}`}
+                  />
+                ) : (
                   <PreviewArea
                     componentName={activeFragment.fragment.meta.name}
                     fragmentPath={activeFragment.path}
                     variant={activeVariant}
-                    variants={activeFragment.fragment.variants}
+                    variants={variants}
                     zoom={viewSettings.zoom}
                     background={viewSettings.background}
                     viewport={viewSettings.viewport}
@@ -398,40 +519,40 @@ export function App({ fragments }: AppProps) {
                       handleSelectVariant(index);
                     }}
                     onRetry={uiActions.incrementPreviewKey}
-                    renderContent={renderVariantWithProps}
-                    previewKey={`${activeFragmentPath}-${activeVariantIndex}-${uiState.previewKey}`}
+                    renderContent={() => renderVariantWithProps(activeVariant)}
+                    previewKey={`${activeFragmentPath}-${safeVariantIndex}-${uiState.previewKey}`}
                   />
-                ) : (
-                  <NoVariantsMessage fragment={activeFragment?.fragment} />
                 )}
               </div>
             </div>
 
             {/* Bottom Panel */}
-            {activeVariant && (
-              <BottomPanel
-                fragment={activeFragment.fragment}
-                variant={activeVariant}
-                fragments={fragments}
-                activePanel={uiState.activePanel}
-                onPanelChange={uiActions.setActivePanel}
-                figmaUrl={figmaUrl}
-                figmaStyles={figmaIntegration.figmaStyles.status === 'success' ? figmaIntegration.figmaStyles.styles || null : null}
-                renderedStyles={figmaIntegration.renderedStyles}
-                figmaLoading={figmaIntegration.isLoading}
-                figmaError={figmaIntegration.errorMessage}
-                onFetchFigma={figmaIntegration.fetchFigmaStyles}
-                onRefreshRendered={figmaIntegration.extractRenderedStyles}
-                actionLogs={actionLogs}
-                onClearActionLogs={clearActionLogs}
-                onNavigateToComponent={(name) => {
-                  const target = fragments.find(s => s.fragment.meta.name === name);
-                  if (target) handleSelectFragment(target.path);
-                }}
-                previewKey={uiState.previewKey}
-                fragmentKey={`${activeFragmentPath}-${activeVariantIndex}`}
-              />
-            )}
+            <div id="preview-tools">
+              {uiState.panelOpen && activeVariant && (
+                <BottomPanel
+                  fragment={activeFragment.fragment}
+                  variant={activeVariant}
+                  fragments={fragments}
+                  activePanel={uiState.activePanel}
+                  onPanelChange={uiActions.setActivePanel}
+                  figmaUrl={figmaUrl}
+                  figmaStyles={figmaIntegration.figmaStyles.status === 'success' ? figmaIntegration.figmaStyles.styles || null : null}
+                  renderedStyles={figmaIntegration.renderedStyles}
+                  figmaLoading={figmaIntegration.isLoading}
+                  figmaError={figmaIntegration.errorMessage}
+                  onFetchFigma={figmaIntegration.fetchFigmaStyles}
+                  onRefreshRendered={figmaIntegration.extractRenderedStyles}
+                  actionLogs={actionLogs}
+                  onClearActionLogs={clearActionLogs}
+                  onNavigateToComponent={(name) => {
+                    const target = fragments.find(s => s.fragment.meta.name === name);
+                    if (target) handleSelectFragment(target.path);
+                  }}
+                  previewKey={uiState.previewKey}
+                  fragmentKey={`${activeFragmentPath}-${safeVariantIndex}`}
+                />
+              )}
+            </div>
           </div>
         ) : (
           <EmptyState style={{ height: '100%' }}>
@@ -450,13 +571,9 @@ export function App({ fragments }: AppProps) {
 // Top Toolbar Component
 interface TopToolbarProps {
   fragment: { path: string; fragment: FragmentDefinition };
-  variant: any;
-  viewSettings: ReturnType<typeof useViewSettings>;
   uiState: ReturnType<typeof useAppState>['state'];
   uiActions: ReturnType<typeof useAppState>['actions'];
   figmaUrl?: string;
-  linkCopied: boolean;
-  onCopyLink: () => void;
   searchQuery: string;
   onSearchChange: (value: string) => void;
   searchInputRef: RefObject<HTMLInputElement>;
@@ -475,6 +592,18 @@ interface HeaderSearchProps {
   inputRef: RefObject<HTMLInputElement>;
 }
 
+interface PreviewAsideProps {
+  fragment: FragmentDefinition;
+  variants: FragmentVariant[];
+  focusedVariantIndex: number;
+  isAllVariantsMode: boolean;
+  activePanel: string;
+  onSelectAllVariants: () => void;
+  onSelectVariant: (index: number) => void;
+  onCopyLink: () => void;
+  onShowShortcuts: () => void;
+}
+
 function HeaderSearch({ value, onChange, inputRef }: HeaderSearchProps) {
   return (
     <Header.Search expandable>
@@ -536,15 +665,113 @@ function ViewerHeader({ showHealth, searchQuery, onSearchChange, searchInputRef
   );
 }
 
+function PreviewAside({
+  fragment,
+  variants,
+  focusedVariantIndex,
+  isAllVariantsMode,
+  activePanel,
+  onSelectAllVariants,
+  onSelectVariant,
+  onCopyLink,
+  onShowShortcuts,
+}: PreviewAsideProps) {
+  const focusedVariant = variants[focusedVariantIndex] || null;
+
+  const baseLinkStyle: CSSProperties = {
+    color: 'var(--text-secondary)',
+    textDecoration: 'none',
+    fontSize: '13px',
+    borderRadius: '6px',
+    padding: '4px 8px',
+    display: 'block',
+  };
+
+  const getLinkStyle = (isActive = false): CSSProperties => (
+    isActive
+      ? { ...baseLinkStyle, color: 'var(--text-primary)', backgroundColor: 'var(--bg-hover)' }
+      : baseLinkStyle
+  );
+
+  return (
+    <Box padding="md" style={{ position: 'sticky', top: '80px' }}>
+      <Stack gap="md">
+        <Stack gap="xs">
+          <Text size="xs" color="tertiary" style={{ textTransform: 'uppercase', letterSpacing: '0.08em' }}>
+            On this page
+          </Text>
+          <a href="#preview-canvas" style={baseLinkStyle}>
+            Preview
+          </a>
+          <a href="#preview-tools" style={baseLinkStyle}>
+            Panels
+          </a>
+          {variants.length > 0 && (
+            <>
+              <Text size="xs" color="tertiary" style={{ textTransform: 'uppercase', letterSpacing: '0.08em', marginTop: '8px' }}>
+                Variants
+              </Text>
+              <a
+                href="#preview-canvas"
+                style={getLinkStyle(isAllVariantsMode)}
+                onClick={(event) => {
+                  event.preventDefault();
+                  onSelectAllVariants();
+                }}
+              >
+                All
+              </a>
+              {variants.map((variant, index) => {
+                const active = index === focusedVariantIndex;
+
+                return (
+                  <a
+                    key={variant.name}
+                    href="#preview-canvas"
+                    style={getLinkStyle(active)}
+                    onClick={(event) => {
+                      event.preventDefault();
+                      onSelectVariant(index);
+                    }}
+                  >
+                    {variant.name}
+                  </a>
+                );
+              })}
+            </>
+          )}
+        </Stack>
+        <Separator />
+        <Stack gap="xs">
+          <Text size="sm" weight="medium">{fragment.meta.name}</Text>
+          <Text size="xs" color="secondary">
+            {isAllVariantsMode
+              ? `Variant: All${focusedVariant ? ` (focused: ${focusedVariant.name})` : ''}`
+              : focusedVariant ? `Variant: ${focusedVariant.name}` : 'Select a variant'}
+          </Text>
+          <Text size="xs" color="tertiary">
+            Active panel: {activePanel}
+          </Text>
+        </Stack>
+        <Separator />
+        <Stack gap="xs">
+          <Button variant="ghost" size="sm" onClick={onCopyLink}>
+            Copy Link
+          </Button>
+          <Button variant="ghost" size="sm" onClick={onShowShortcuts}>
+            Keyboard Shortcuts
+          </Button>
+        </Stack>
+      </Stack>
+    </Box>
+  );
+}
+
 function TopToolbar({
   fragment,
-  variant,
-  viewSettings,
   uiState,
   uiActions,
   figmaUrl,
-  linkCopied,
-  onCopyLink,
   searchQuery,
   onSearchChange,
   searchInputRef,
@@ -563,21 +790,6 @@ function TopToolbar({
       <HeaderSearch value={searchQuery} onChange={onSearchChange} inputRef={searchInputRef} />
       <Header.Spacer />
       <Header.Actions>
-        <PreviewToolbar
-          zoom={viewSettings.zoom}
-          background={viewSettings.background}
-          onZoomChange={viewSettings.setZoom}
-          onBackgroundChange={viewSettings.setBackground}
-        />
-        <Separator orientation="vertical" style={{ height: '16px' }} />
-        <ViewportSelector
-          viewport={viewSettings.viewport}
-          customSize={viewSettings.customSize}
-          onViewportChange={viewSettings.setViewport}
-          onCustomSizeChange={viewSettings.setCustomSize}
-        />
-        <Separator orientation="vertical" style={{ height: '16px' }} />
-
         {figmaUrl && (
           <>
             <Tooltip content={uiState.showComparison ? "Hide Figma comparison" : "Compare with Figma design"}>
@@ -602,41 +814,6 @@ function TopToolbar({
             <Separator orientation="vertical" style={{ height: '16px' }} />
           </>
         )}
-
-        {variant && (
-          <>
-            <Tooltip content="Open in new window">
-              <Button
-                onClick={() => {
-                  const url = new URL(window.location.href);
-                  url.hash = '';
-                  url.searchParams.set('isolated', 'true');
-                  url.searchParams.set('component', fragment.fragment.meta.name);
-                  url.searchParams.set('variant', variant.name);
-                  if (viewSettings.zoom !== 100) url.searchParams.set('zoom', String(viewSettings.zoom));
-                  if (viewSettings.background !== 'transparent') url.searchParams.set('bg', viewSettings.background);
-                  window.open(url.toString(), '_blank', 'noopener,noreferrer');
-                }}
-                variant="ghost"
-                size="sm"
-              >
-                <ExternalLinkIcon style={{ width: '16px', height: '16px' }} />
-              </Button>
-            </Tooltip>
-            <ScreenshotButton componentName={fragment.fragment.meta.name} variantName={variant.name} />
-            <Tooltip content="Copy link to share">
-              <Button
-                onClick={onCopyLink}
-                variant="ghost"
-                size="sm"
-                style={linkCopied ? { color: '#16a34a', backgroundColor: 'rgba(22, 163, 74, 0.1)' } : {}}
-              >
-                {linkCopied ? <CheckIcon style={{ width: '16px', height: '16px' }} /> : <LinkIcon style={{ width: '16px', height: '16px' }} />}
-              </Button>
-            </Tooltip>
-          </>
-        )}
-        <Separator orientation="vertical" style={{ height: '16px' }} />
         <ThemeToggle
           size="sm"
           value={resolvedTheme}
@@ -666,52 +843,180 @@ function TopToolbar({
   );
 }
 
-// Variant Tabs Bar Component
-interface VariantTabsBarProps {
-  variants: any[];
-  activeIndex: number;
-  onSelect: (index: number) => void;
+function normalizeAnchorSegment(value: string): string {
+  const normalized = value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized || "variant";
+}
+
+function getVariantSectionId(componentName: string, variantName: string): string {
+  return `preview-${normalizeAnchorSegment(componentName)}-${normalizeAnchorSegment(variantName)}`;
+}
+
+interface PreviewControlsBarProps {
+  zoom: ReturnType<typeof useViewSettings>["zoom"];
+  background: ReturnType<typeof useViewSettings>["background"];
+  onZoomChange: ReturnType<typeof useViewSettings>["setZoom"];
+  onBackgroundChange: ReturnType<typeof useViewSettings>["setBackground"];
   showMatrixView: boolean;
   showMultiViewport: boolean;
+  panelOpen: boolean;
   onToggleMatrix: () => void;
   onToggleMultiViewport: () => void;
+  onTogglePanel: () => void;
 }
 
-function VariantTabsBar({ variants, activeIndex, onSelect, showMatrixView, showMultiViewport, onToggleMatrix, onToggleMultiViewport }: VariantTabsBarProps) {
+function PreviewControlsBar({
+  zoom,
+  background,
+  onZoomChange,
+  onBackgroundChange,
+  showMatrixView,
+  showMultiViewport,
+  panelOpen,
+  onToggleMatrix,
+  onToggleMultiViewport,
+  onTogglePanel,
+}: PreviewControlsBarProps) {
+  const toggleButtonStyle = (active: boolean): CSSProperties => (
+    active ? { color: 'var(--color-accent)', backgroundColor: 'var(--bg-hover)' } : {}
+  );
+
   return (
-    <Stack direction="row" align="center" justify="between" style={{ padding: '8px 16px', borderBottom: '1px solid var(--border)', backgroundColor: 'var(--bg-primary)', flexShrink: 0 }}>
-      {!showMatrixView ? (
-        <ScrollArea orientation="horizontal" showFades style={{ flex: 1, minWidth: 0 }}>
-          <VariantTabs variants={variants} activeIndex={activeIndex} onSelect={onSelect} />
-        </ScrollArea>
-      ) : (
-        <Text size="sm" color="secondary">Showing all {variants.length} variants</Text>
-      )}
-      <Stack direction="row" align="center" gap="sm" style={{ marginLeft: '16px', flexShrink: 0 }}>
-        {variants.length > 1 && (
+    <div style={{ padding: '8px 16px', borderBottom: '1px solid var(--border)', backgroundColor: 'var(--bg-primary)', flexShrink: 0 }}>
+      <Stack direction="row" gap="sm" align="center" justify="end">
+        <PreviewToolbar
+          zoom={zoom}
+          background={background}
+          onZoomChange={onZoomChange}
+          onBackgroundChange={onBackgroundChange}
+        />
+        <Separator orientation="vertical" style={{ height: '16px' }} />
+        <Tooltip content={showMatrixView ? "Disable matrix view" : "Enable matrix view"}>
           <Button
+            variant="ghost"
+            size="sm"
+            aria-pressed={showMatrixView}
+            aria-label="Toggle matrix view"
             onClick={onToggleMatrix}
+            style={toggleButtonStyle(showMatrixView)}
+          >
+            <GridFour size={16} />
+          </Button>
+        </Tooltip>
+        <Tooltip content={showMultiViewport ? "Disable responsive view" : "Enable responsive view"}>
+          <Button
             variant="ghost"
             size="sm"
-            title={showMatrixView ? "Show single variant" : "Show all variants in grid"}
-            style={showMatrixView ? { backgroundColor: 'rgba(59, 130, 246, 0.1)', color: 'var(--color-accent)' } : {}}
+            aria-pressed={showMultiViewport}
+            aria-label="Toggle responsive view"
+            onClick={onToggleMultiViewport}
+            style={toggleButtonStyle(showMultiViewport)}
           >
-            <GridIcon style={{ width: '16px', height: '16px' }} />
-            {showMatrixView ? "Exit Matrix" : "Matrix"}
+            <DeviceMobile size={16} />
           </Button>
-        )}
-        <Button
-          onClick={onToggleMultiViewport}
-          variant="ghost"
-          size="sm"
-          title={showMultiViewport ? "Exit multi-viewport" : "Show at multiple screen sizes"}
-          style={showMultiViewport ? { backgroundColor: 'rgba(34, 197, 94, 0.1)', color: '#16a34a' } : {}}
-        >
-          <DevicesIcon style={{ width: '16px', height: '16px' }} />
-          {showMultiViewport ? "Exit Responsive" : "Responsive"}
-        </Button>
+        </Tooltip>
+        <Tooltip content={panelOpen ? "Hide addons panel" : "Show addons panel"}>
+          <Button
+            variant="ghost"
+            size="sm"
+            aria-pressed={panelOpen}
+            aria-label="Toggle addons panel"
+            onClick={onTogglePanel}
+            style={toggleButtonStyle(panelOpen)}
+          >
+            <Rows size={16} />
+          </Button>
+        </Tooltip>
       </Stack>
-    </Stack>
+    </div>
+  );
+}
+
+interface AllVariantsPreviewProps {
+  componentName: string;
+  fragmentPath: string;
+  variants: FragmentVariant[];
+  focusedVariantIndex: number;
+  zoom: ReturnType<typeof useViewSettings>["zoom"];
+  background: ReturnType<typeof useViewSettings>["background"];
+  viewport: ReturnType<typeof useViewSettings>["viewport"];
+  customSize: ReturnType<typeof useViewSettings>["customSize"];
+  previewTheme: ReturnType<typeof useTheme>["resolvedTheme"];
+  showComparison: boolean;
+  allFigmaUrls: string[];
+  fallbackFigmaUrl?: string;
+  onRetry: () => void;
+  renderVariantContent: (variant: FragmentVariant) => ReactNode;
+  previewKeyBase: string;
+}
+
+function AllVariantsPreview({
+  componentName,
+  fragmentPath,
+  variants,
+  focusedVariantIndex,
+  zoom,
+  background,
+  viewport,
+  customSize,
+  previewTheme,
+  showComparison,
+  allFigmaUrls,
+  fallbackFigmaUrl,
+  onRetry,
+  renderVariantContent,
+  previewKeyBase,
+}: AllVariantsPreviewProps) {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '20px', padding: '20px' }}>
+      {variants.map((variant, index) => {
+        const isFocused = index === focusedVariantIndex;
+
+        return (
+          <section
+            id={getVariantSectionId(componentName, variant.name)}
+            key={variant.name}
+            style={{
+              border: '1px solid var(--border)',
+              borderColor: isFocused ? 'var(--color-accent)' : 'var(--border)',
+              borderRadius: '10px',
+              overflow: 'hidden',
+              backgroundColor: 'var(--bg-primary)',
+              boxShadow: isFocused ? '0 0 0 1px color-mix(in srgb, var(--color-accent) 40%, transparent)' : undefined,
+            }}
+          >
+            <Stack direction="row" align="baseline" gap="sm" style={{ padding: '12px 14px', borderBottom: '1px solid var(--border-subtle)', backgroundColor: 'var(--bg-secondary)' }}>
+              <Text size="sm" weight="medium">{variant.name}</Text>
+              <Text size="xs" color="secondary">{variant.description}</Text>
+            </Stack>
+            <PreviewArea
+              componentName={componentName}
+              fragmentPath={fragmentPath}
+              variant={variant}
+              variants={variants}
+              zoom={zoom}
+              background={background}
+              viewport={viewport}
+              customSize={customSize}
+              previewTheme={previewTheme}
+              showMatrixView={false}
+              showMultiViewport={false}
+              showComparison={showComparison}
+              figmaUrl={variant.figma || fallbackFigmaUrl}
+              allFigmaUrls={allFigmaUrls}
+              onSelectVariant={() => {}}
+              onRetry={onRetry}
+              renderContent={() => renderVariantContent(variant)}
+              previewKey={`${previewKeyBase}-${index}`}
+            />
+          </section>
+        );
+      })}
+    </div>
   );
 }
 
@@ -721,6 +1026,12 @@ interface NoVariantsMessageProps {
 }
 
 function NoVariantsMessage({ fragment }: NoVariantsMessageProps) {
+  // Check for load error (missing dependencies, schema errors, etc.)
+  const loadError = (fragment as any)?._loadError;
+  if (loadError) {
+    return <LoadErrorMessage error={loadError} componentName={fragment?.meta?.name} />;
+  }
+
   const skippedVariants = (fragment?._generated as any)?.skippedVariants;
 
   if (!skippedVariants || skippedVariants.length === 0) {
@@ -761,6 +1072,92 @@ function NoVariantsMessage({ fragment }: NoVariantsMessageProps) {
   );
 }
 
+// Load error message — shown when a fragment failed to import (missing deps, schema errors, etc.)
+function LoadErrorMessage({ error, componentName }: { error: { message: string; dependencies: string[] }; componentName?: string }) {
+  const deps = error.dependencies || [];
+  const errorMessage = error.message || 'Unknown error';
+
+  // Determine if the error is a missing module/dependency issue
+  const isModuleError = /Failed to resolve import|Cannot find module|Module not found|does not provide an export/.test(errorMessage);
+
+  // Only suggest packages if the error is actually about missing modules
+  let suggestedPackages: string[] = [];
+  if (isModuleError) {
+    if (deps.length > 0) {
+      suggestedPackages = [...deps];
+    } else {
+      const match = errorMessage.match(/Failed to resolve import ["']([^"']+)["']/);
+      if (match) {
+        suggestedPackages = [match[1]];
+      }
+    }
+  }
+
+  const hasMissingDeps = suggestedPackages.length > 0;
+  const installCmd = `pnpm add ${suggestedPackages.join(' ')}`;
+
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', height: '100%', padding: '24px' }}>
+      <Alert variant="warning">
+        <Alert.Body>
+          <Alert.Title>
+            {hasMissingDeps ? 'Missing Dependencies' : 'Failed to Load'}
+          </Alert.Title>
+          <Alert.Content>
+            <Stack direction="column" gap="sm">
+              {hasMissingDeps ? (
+                <>
+                  <Text size="xs" color="secondary">
+                    {componentName ? `${componentName} requires` : 'This component requires'} packages that are not installed in your project.
+                  </Text>
+                  <Text size="xs" weight="semibold" color="secondary">Install with:</Text>
+                  <code style={{
+                    display: 'block',
+                    padding: '8px 12px',
+                    borderRadius: '6px',
+                    backgroundColor: 'var(--bg-tertiary, #f3f4f6)',
+                    fontFamily: 'monospace',
+                    fontSize: '12px',
+                    color: 'var(--text-primary, #111827)',
+                    userSelect: 'all',
+                  }}>
+                    {installCmd}
+                  </code>
+                  <Text size="xs" color="tertiary">
+                    After installing, restart the dev server.
+                  </Text>
+                </>
+              ) : (
+                <>
+                  <Text size="xs" color="secondary">
+                    {componentName ? `${componentName} couldn't` : 'This component couldn\'t'} be loaded. This may be due to a schema validation error or missing imports.
+                  </Text>
+                  <Text size="xs" weight="semibold" color="secondary">Error:</Text>
+                  <pre style={{
+                    padding: '8px 12px',
+                    borderRadius: '6px',
+                    backgroundColor: 'var(--bg-tertiary, #f3f4f6)',
+                    fontFamily: 'monospace',
+                    fontSize: '11px',
+                    color: 'var(--text-secondary, #374151)',
+                    whiteSpace: 'pre-wrap',
+                    wordBreak: 'break-word',
+                    margin: 0,
+                    maxHeight: '200px',
+                    overflow: 'auto',
+                  }}>
+                    {errorMessage}
+                  </pre>
+                </>
+              )}
+            </Stack>
+          </Alert.Content>
+        </Alert.Body>
+      </Alert>
+    </div>
+  );
+}
+
 // Empty variant message
 interface EmptyVariantMessageProps {
   reason: string;