@fragments-sdk/cli 0.6.0 → 0.7.0

package/src/viewer/components/App.tsx

@@ -3,8 +3,8 @@
  * Refactored for better performance and maintainability.
  */
 
-import { useState, useMemo, useEffect, useCallback, useRef } from "react";
-import type { SegmentDefinition } from "../../core/index.js";
+import { useState, useMemo, useEffect, useCallback, useRef, type RefObject } from "react";
+import { BRAND, type SegmentDefinition } from "../../core/index.js";
 
 // Layout & Navigation
 import { Layout } from "./Layout.js";
@@ -28,10 +28,10 @@ import { useAllFigmaUrls } from "./FigmaEmbed.js";
 import { ActionCapture } from "./ActionCapture.js";
 
 // Fragments UI
-import { Stack, Text, Separator, Tooltip, Button, EmptyState, Box, Alert } from "@fragments/ui";
+import { Header, Stack, Text, Separator, Tooltip, Button, EmptyState, Box, Alert, ScrollArea, Input } from "@fragments/ui";
 
 // Icons
-import { EmptyIcon, ExternalLinkIcon, CameraIcon, FigmaIcon, CompareIcon, CheckIcon, LinkIcon, GridIcon, DevicesIcon } from "./Icons.js";
+import { EmptyIcon, ExternalLinkIcon, FigmaIcon, CompareIcon, CheckIcon, LinkIcon, GridIcon, DevicesIcon } from "./Icons.js";
 
 // Hooks
 import { useAppState } from "../hooks/useAppState.js";
@@ -81,7 +81,7 @@ export function App({ segments }: AppProps) {
   const { resolvedTheme } = useTheme();
 
   // Toast notifications (via Fragments UI ToastProvider)
-  const { toast, info, success } = useToast();
+  const { info, success } = useToast();
 
   // Navigation state
   const [activeSegmentPath, setActiveSegmentPath] = useState<string | null>(() => {
@@ -99,6 +99,8 @@ export function App({ segments }: AppProps) {
     }
     return 0;
   });
+  const [searchQuery, setSearchQuery] = useState('');
+  const searchInputRef = useRef<HTMLInputElement>(null);
 
   // Derived values
   const activeSegment = useMemo(
@@ -192,6 +194,11 @@ export function App({ segments }: AppProps) {
     }
   }, [copyUrl, success, uiActions]);
 
+  const focusSearchInput = useCallback(() => {
+    searchInputRef.current?.focus();
+    searchInputRef.current?.select();
+  }, []);
+
   // Sorted segment paths for keyboard navigation
   const sortedSegmentPaths = useMemo(() => {
     return [...segments]
@@ -221,8 +228,18 @@ export function App({ segments }: AppProps) {
       togglePanel: uiActions.togglePanel,
       copyLink: handleCopyLink,
       showHelp: uiActions.toggleShortcutsHelp,
-      openSearch: () => uiActions.setCommandPalette(true),
-      escape: uiActions.closeAllModals,
+      openSearch: focusSearchInput,
+      escape: () => {
+        if (document.activeElement === searchInputRef.current) {
+          if (searchQuery) {
+            setSearchQuery('');
+          } else {
+            searchInputRef.current.blur();
+          }
+          return;
+        }
+        uiActions.closeAllModals();
+      },
     },
     { enabled: !uiState.showShortcutsHelp, variantCount }
   );
@@ -270,10 +287,35 @@ export function App({ segments }: AppProps) {
       />
 
       <Layout
+        header={
+          activeSegment && !uiState.showHealthDashboard ? (
+            <TopToolbar
+              segment={activeSegment}
+              variant={activeVariant}
+              viewSettings={viewSettings}
+              uiState={uiState}
+              uiActions={uiActions}
+              figmaUrl={figmaUrl}
+              linkCopied={uiState.linkCopied}
+              onCopyLink={handleCopyLink}
+              searchQuery={searchQuery}
+              onSearchChange={setSearchQuery}
+              searchInputRef={searchInputRef}
+            />
+          ) : (
+            <ViewerHeader
+              showHealth={uiState.showHealthDashboard}
+              searchQuery={searchQuery}
+              onSearchChange={setSearchQuery}
+              searchInputRef={searchInputRef}
+            />
+          )
+        }
         leftSidebar={
           <LeftSidebar
             segments={segments}
             activeSegment={uiState.showHealthDashboard ? null : activeSegmentPath}
+            searchQuery={searchQuery}
             onSelect={handleSelectSegment}
             showHealth={uiState.showHealthDashboard}
             onHealthClick={() => {
@@ -302,18 +344,6 @@ export function App({ segments }: AppProps) {
           <div 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 }}>
-              {/* Top Toolbar */}
-              <TopToolbar
-                segment={activeSegment}
-                variant={activeVariant}
-                viewSettings={viewSettings}
-                uiState={uiState}
-                uiActions={uiActions}
-                figmaUrl={figmaUrl}
-                linkCopied={uiState.linkCopied}
-                onCopyLink={handleCopyLink}
-              />
-
               {/* Variant Tabs */}
               {activeSegment.segment.variants && activeSegment.segment.variants.length > 0 && (
                 <VariantTabsBar
@@ -416,16 +446,82 @@ interface TopToolbarProps {
   figmaUrl?: string;
   linkCopied: boolean;
   onCopyLink: () => void;
+  searchQuery: string;
+  onSearchChange: (value: string) => void;
+  searchInputRef: RefObject<HTMLInputElement>;
+}
+
+interface ViewerHeaderProps {
+  showHealth: boolean;
+  searchQuery: string;
+  onSearchChange: (value: string) => void;
+  searchInputRef: RefObject<HTMLInputElement>;
+}
+
+interface HeaderSearchProps {
+  value: string;
+  onChange: (value: string) => void;
+  inputRef: RefObject<HTMLInputElement>;
 }
 
-function TopToolbar({ segment, variant, viewSettings, uiState, uiActions, figmaUrl, linkCopied, onCopyLink }: TopToolbarProps) {
+function HeaderSearch({ value, onChange, inputRef }: HeaderSearchProps) {
   return (
-    <Stack direction="row" align="center" justify="between" style={{ padding: '8px 16px', borderBottom: '1px solid var(--border)', backgroundColor: 'var(--bg-secondary)', flexShrink: 0 }}>
-      <Stack direction="row" align="center" gap="sm">
-        <Text weight="medium" size="sm">{segment.segment.meta.name}</Text>
-        <Text size="xs" color="tertiary">{segment.segment.meta.category}</Text>
-      </Stack>
-      <Stack direction="row" align="center" gap="sm">
+    <Header.Search expandable>
+      <Input
+        ref={inputRef}
+        value={value}
+        onChange={onChange}
+        placeholder="Search components"
+        aria-label="Search components"
+        size="sm"
+        shortcut="⌘K"
+        style={{ width: '220px' }}
+      />
+    </Header.Search>
+  );
+}
+
+function ViewerHeader({ showHealth, searchQuery, onSearchChange, searchInputRef }: ViewerHeaderProps) {
+  return (
+    <Header aria-label="Fragments viewer header">
+      <Header.Trigger />
+      <Header.Brand>
+        <Stack direction="row" gap="sm" align="center">
+          <Text weight="medium" size="sm">{BRAND.name}</Text>
+          <Text size="xs" color="tertiary">{showHealth ? 'health dashboard' : 'preview'}</Text>
+        </Stack>
+      </Header.Brand>
+      <HeaderSearch value={searchQuery} onChange={onSearchChange} inputRef={searchInputRef} />
+      <Header.Spacer />
+    </Header>
+  );
+}
+
+function TopToolbar({
+  segment,
+  variant,
+  viewSettings,
+  uiState,
+  uiActions,
+  figmaUrl,
+  linkCopied,
+  onCopyLink,
+  searchQuery,
+  onSearchChange,
+  searchInputRef,
+}: TopToolbarProps) {
+  return (
+    <Header aria-label="Component preview toolbar">
+      <Header.Trigger />
+      <Header.Brand>
+        <Stack direction="row" align="center" gap="sm">
+          <Text weight="medium" size="sm">{segment.segment.meta.name}</Text>
+          <Text size="xs" color="tertiary">{segment.segment.meta.category}</Text>
+        </Stack>
+      </Header.Brand>
+      <HeaderSearch value={searchQuery} onChange={onSearchChange} inputRef={searchInputRef} />
+      <Header.Spacer />
+      <Header.Actions>
         <PreviewToolbar
           zoom={viewSettings.zoom}
           background={viewSettings.background}
@@ -499,8 +595,8 @@ function TopToolbar({ segment, variant, viewSettings, uiState, uiActions, figmaU
             </Tooltip>
           </>
         )}
-      </Stack>
-    </Stack>
+      </Header.Actions>
+    </Header>
   );
 }
 
@@ -519,11 +615,13 @@ function VariantTabsBar({ variants, activeIndex, onSelect, showMatrixView, showM
   return (
     <Stack direction="row" align="center" justify="between" style={{ padding: '8px 16px', borderBottom: '1px solid var(--border)', backgroundColor: 'var(--bg-primary)', flexShrink: 0 }}>
       {!showMatrixView ? (
-        <VariantTabs variants={variants} activeIndex={activeIndex} onSelect={onSelect} />
+        <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' }}>
+      <Stack direction="row" align="center" gap="sm" style={{ marginLeft: '16px', flexShrink: 0 }}>
         {variants.length > 1 && (
           <Button
             onClick={onToggleMatrix}

package/src/viewer/components/Icons.tsx

@@ -199,6 +199,49 @@ export function ViewportIcon({ className, style }: IconProps) {
   );
 }
 
+export function ResponsiveIcon({ className, style }: IconProps) {
+  return (
+    <svg className={className} style={style} fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.7}>
+      <path strokeLinecap="round" strokeLinejoin="round" d="M7 12h10m0 0l-2.5-2.5M17 12l-2.5 2.5M7 12l2.5-2.5M7 12l2.5 2.5" />
+    </svg>
+  );
+}
+
+export function DesktopIcon({ className, style }: IconProps) {
+  return (
+    <svg className={className} style={style} fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+      <path strokeLinecap="round" strokeLinejoin="round" d="M3.75 5.25A2.25 2.25 0 016 3h12a2.25 2.25 0 012.25 2.25v8.25A2.25 2.25 0 0118 15.75H6a2.25 2.25 0 01-2.25-2.25V5.25zM9.75 20.25h4.5M12 15.75v4.5" />
+    </svg>
+  );
+}
+
+export function TabletIcon({ className, style }: IconProps) {
+  return (
+    <svg className={className} style={style} fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+      <rect x="6.75" y="3" width="10.5" height="18" rx="2.25" />
+      <circle cx="12" cy="17.25" r="0.85" fill="currentColor" stroke="none" />
+    </svg>
+  );
+}
+
+export function MobileIcon({ className, style }: IconProps) {
+  return (
+    <svg className={className} style={style} fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+      <rect x="8.25" y="2.25" width="7.5" height="19.5" rx="2.25" />
+      <circle cx="12" cy="18.75" r="0.8" fill="currentColor" stroke="none" />
+    </svg>
+  );
+}
+
+export function SettingsIcon({ className, style }: IconProps) {
+  return (
+    <svg className={className} style={style} fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+      <path strokeLinecap="round" strokeLinejoin="round" d="M10.343 3.94c.09-.542.56-.94 1.11-.94h1.094c.55 0 1.02.398 1.11.94l.18 1.09c.06.36.29.668.62.84l.94.5c.318.168.7.18 1.028.03l.998-.455c.5-.23 1.09-.048 1.38.42l.546.882c.29.468.19 1.074-.24 1.424l-.858.698a1.26 1.26 0 00-.456.985v1.046c0 .38.17.738.456.984l.858.699c.43.35.53.956.24 1.424l-.545.882a1.1 1.1 0 01-1.381.42l-.998-.455a1.26 1.26 0 00-1.028.03l-.94.5a1.26 1.26 0 00-.62.84l-.18 1.09a1.125 1.125 0 01-1.11.94h-1.094a1.124 1.124 0 01-1.11-.94l-.18-1.09a1.26 1.26 0 00-.62-.84l-.94-.5a1.26 1.26 0 00-1.028-.03l-.998.455a1.1 1.1 0 01-1.381-.42l-.545-.882a1.125 1.125 0 01.24-1.424l.858-.699a1.26 1.26 0 00.456-.984V9.878c0-.38-.17-.738-.456-.985l-.858-.698a1.125 1.125 0 01-.24-1.424l.545-.882c.29-.468.88-.65 1.381-.42l.998.455c.33.15.71.138 1.028-.03l.94-.5c.33-.172.56-.48.62-.84l.18-1.09z" />
+      <circle cx="12" cy="12" r="3" />
+    </svg>
+  );
+}
+
 // Misc
 export function ControlsIcon({ className, style }: IconProps) {
   return (
@@ -235,7 +278,16 @@ export function HeartPulseIcon({ className, style }: IconProps) {
 
 export function DashboardIcon({ className, style }: IconProps) {
   return (
-    <svg className={className} style={style} fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+    <svg
+      className={className}
+      style={style}
+      width="20"
+      height="20"
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke="currentColor"
+      strokeWidth={1.5}
+    >
       <path strokeLinecap="round" strokeLinejoin="round" d="M3.75 6A2.25 2.25 0 016 3.75h2.25A2.25 2.25 0 0110.5 6v2.25a2.25 2.25 0 01-2.25 2.25H6a2.25 2.25 0 01-2.25-2.25V6zM3.75 15.75A2.25 2.25 0 016 13.5h2.25a2.25 2.25 0 012.25 2.25V18a2.25 2.25 0 01-2.25 2.25H6A2.25 2.25 0 013.75 18v-2.25zM13.5 6a2.25 2.25 0 012.25-2.25H18A2.25 2.25 0 0120.25 6v2.25A2.25 2.25 0 0118 10.5h-2.25a2.25 2.25 0 01-2.25-2.25V6zM13.5 15.75a2.25 2.25 0 012.25-2.25H18a2.25 2.25 0 012.25 2.25V18A2.25 2.25 0 0118 20.25h-2.25A2.25 2.25 0 0113.5 18v-2.25z" />
     </svg>
   );

package/src/viewer/components/Layout.tsx

@@ -3,13 +3,17 @@ import { AppShell } from '@fragments/ui';
 
 interface LayoutProps {
   leftSidebar: ReactNode;
+  header: ReactNode;
   children: ReactNode;
 }
 
-export function Layout({ leftSidebar, children }: LayoutProps) {
+export function Layout({ leftSidebar, header, children }: LayoutProps) {
   return (
-    <AppShell layout="sidebar-inset">
-      <AppShell.Sidebar width="256px">
+    <AppShell layout="inset">
+      <AppShell.Header>
+        {header}
+      </AppShell.Header>
+      <AppShell.Sidebar width="256px" collapsible="icon">
         {leftSidebar}
       </AppShell.Sidebar>
       <AppShell.Main padding="none">

package/src/viewer/components/LeftSidebar.tsx

@@ -2,8 +2,7 @@ import { useState, useMemo, useRef, useEffect, useCallback } from 'react';
 import type { SegmentDefinition } from '../../core/index.js';
 import { BRAND } from '../../core/index.js';
 import { useTheme } from './ThemeProvider.js';
-import { SunIcon, MoonIcon, DashboardIcon } from './Icons.js';
-import { Sidebar, Input, Button, Badge, Text } from '@fragments/ui';
+import { Sidebar, useSidebar, Badge, Text, ThemeToggle } from '@fragments/ui';
 
 // Fuzzy matching utility
 interface FuzzyMatch {
@@ -122,19 +121,19 @@ function HighlightedText({ text, indices }: { text: string; indices: number[] })
 interface LeftSidebarProps {
   segments: Array<{ path: string; segment: SegmentDefinition }>;
   activeSegment: string | null;
+  searchQuery: string;
   onSelect: (path: string) => void;
   showHealth?: boolean;
   onHealthClick?: () => void;
 }
 
-export function LeftSidebar({ segments, activeSegment, onSelect, showHealth, onHealthClick }: LeftSidebarProps) {
-  const [search, setSearch] = useState('');
+export function LeftSidebar({ segments, activeSegment, searchQuery, onSelect, showHealth, onHealthClick }: LeftSidebarProps) {
   const [focusedIndex, setFocusedIndex] = useState(-1);
-  const { theme, setTheme, resolvedTheme } = useTheme();
-  const searchInputRef = useRef<HTMLInputElement>(null);
+  const { setTheme, resolvedTheme } = useTheme();
+  const { isMobile, setOpen } = useSidebar();
   const navRef = useRef<HTMLDivElement>(null);
 
-  const debouncedSearch = useDebounce(search, 150);
+  const debouncedSearch = useDebounce(searchQuery, 150);
 
   const searchResults = useMemo(() => {
     if (!debouncedSearch) return null;
@@ -175,11 +174,6 @@ export function LeftSidebar({ segments, activeSegment, onSelect, showHealth, onH
     return groups;
   }, [segments, searchResults]);
 
-  const toggleTheme = () => {
-    // Simple toggle between light and dark
-    setTheme(resolvedTheme === 'light' ? 'dark' : 'light');
-  };
-
   const flatItems = useMemo(() => {
     const items: Array<{ path: string; segment: SegmentDefinition }> = [];
     const sortedEntries = Object.entries(grouped).sort(([a], [b]) =>
@@ -196,60 +190,67 @@ export function LeftSidebar({ segments, activeSegment, onSelect, showHealth, onH
     return items;
   }, [grouped]);
 
+  const keyboardItems = useMemo(() => {
+    const componentItems = flatItems.map((item) => ({ type: 'component' as const, path: item.path }));
+    if (!onHealthClick) return componentItems;
+    return [{ type: 'dashboard' as const }, ...componentItems];
+  }, [flatItems, onHealthClick]);
+
   useEffect(() => {
-    if (focusedIndex >= 0 && focusedIndex < flatItems.length && navRef.current) {
+    if (focusedIndex >= 0 && focusedIndex < keyboardItems.length && navRef.current) {
       // Query all nav item buttons rendered by Sidebar.Item inside the nav
       const buttons = navRef.current.querySelectorAll<HTMLButtonElement>('li > button[type="button"]');
       if (buttons[focusedIndex]) {
         buttons[focusedIndex].focus();
       }
     }
-  }, [focusedIndex, flatItems.length]);
+  }, [focusedIndex, keyboardItems.length]);
 
   useEffect(() => {
     setFocusedIndex(-1);
-  }, [search]);
+  }, [searchQuery]);
 
-  const handleKeyDown = useCallback((e: KeyboardEvent) => {
-    const target = e.target as HTMLElement;
-    if ((target.tagName === 'INPUT' && target !== searchInputRef.current) ||
-        target.tagName === 'TEXTAREA' || target.isContentEditable) {
-      return;
+  const handleSelect = (path: string) => {
+    onSelect(path);
+    if (isMobile) {
+      setOpen(false);
     }
+  };
 
-    if ((e.key === '/' && !e.metaKey && !e.ctrlKey) ||
-        (e.key === 'k' && (e.metaKey || e.ctrlKey))) {
-      e.preventDefault();
-      searchInputRef.current?.focus();
-      searchInputRef.current?.select();
+  const handleHealthClick = () => {
+    onHealthClick?.();
+    if (isMobile) {
+      setOpen(false);
+    }
+  };
+
+  const handleKeyDown = useCallback((e: KeyboardEvent) => {
+    const target = e.target as HTMLElement;
+    if (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable) {
       return;
     }
 
     if (e.key === 'Escape') {
-      if (document.activeElement === searchInputRef.current) {
-        setSearch('');
-        searchInputRef.current?.blur();
-        if (flatItems.length > 0) setFocusedIndex(0);
-      } else {
-        setSearch('');
-        setFocusedIndex(-1);
-      }
+      setFocusedIndex(-1);
       return;
     }
 
-    if (document.activeElement === searchInputRef.current) return;
-
     if (e.key === 'ArrowDown') {
       e.preventDefault();
-      setFocusedIndex(prev => (prev + 1) >= flatItems.length ? 0 : prev + 1);
+      setFocusedIndex(prev => (prev + 1) >= keyboardItems.length ? 0 : prev + 1);
     } else if (e.key === 'ArrowUp') {
       e.preventDefault();
-      setFocusedIndex(prev => (prev - 1) < 0 ? flatItems.length - 1 : prev - 1);
-    } else if (e.key === 'Enter' && focusedIndex >= 0 && focusedIndex < flatItems.length) {
+      setFocusedIndex(prev => (prev - 1) < 0 ? keyboardItems.length - 1 : prev - 1);
+    } else if (e.key === 'Enter' && focusedIndex >= 0 && focusedIndex < keyboardItems.length) {
       e.preventDefault();
-      onSelect(flatItems[focusedIndex].path);
+      const currentItem = keyboardItems[focusedIndex];
+      if (currentItem.type === 'dashboard') {
+        handleHealthClick();
+      } else {
+        handleSelect(currentItem.path);
+      }
     }
-  }, [flatItems, focusedIndex, onSelect]);
+  }, [keyboardItems, focusedIndex, handleHealthClick, handleSelect]);
 
   useEffect(() => {
     document.addEventListener('keydown', handleKeyDown);
@@ -261,60 +262,37 @@ export function LeftSidebar({ segments, activeSegment, onSelect, showHealth, onH
   );
 
   return (
-    <Sidebar collapsible="none" style={{ height: '100%', backgroundColor: 'var(--bg-secondary)' }}>
+    <>
       {/* Header */}
       <Sidebar.Header>
         <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', width: '100%' }}>
           <Text size="sm" weight="medium">{BRAND.name}</Text>
-          <Button
-            variant="ghost"
-            size="sm"
-            icon
-            onClick={toggleTheme}
-            aria-label={`Theme: ${resolvedTheme}`}
-          >
-            {resolvedTheme === 'dark' ? (
-              <MoonIcon />
-            ) : (
-              <SunIcon />
-            )}
-          </Button>
+          <div style={{ display: 'flex', alignItems: 'center', gap: '6px' }}>
+            <ThemeToggle
+              size="sm"
+              value={resolvedTheme}
+              onValueChange={(value) => setTheme(value)}
+              aria-label={`Theme: ${resolvedTheme}`}
+            />
+            <Sidebar.CollapseToggle />
+          </div>
         </div>
       </Sidebar.Header>
 
-      {/* Search */}
-      <div style={{ padding: '12px' }}>
-        <Input
-          ref={searchInputRef}
-          value={search}
-          onChange={(value: string) => setSearch(value)}
-          placeholder="Search"
-          size="sm"
-        />
-      </div>
-
-      {/* Dashboard Link */}
-      {onHealthClick && (
-        <div style={{ padding: '0 8px 12px' }}>
-          <Button
-            variant="ghost"
-            size="sm"
-            onClick={onHealthClick}
-            style={{
-              width: '100%',
-              justifyContent: 'flex-start',
-              ...(showHealth ? { backgroundColor: 'var(--bg-hover)', color: 'var(--text-primary)' } : {}),
-            }}
-          >
-            <DashboardIcon />
-            <span style={{ marginLeft: '8px' }}>Dashboard</span>
-          </Button>
-        </div>
-      )}
-
       {/* Component list */}
-      <div ref={navRef}>
+      <div ref={navRef} style={{ flex: 1, minHeight: 0, display: 'flex', overflow: 'hidden' }}>
         <Sidebar.Nav aria-label="Components">
+          {onHealthClick && (
+            <Sidebar.Section>
+              <Sidebar.Item
+                active={!!showHealth}
+                onClick={handleHealthClick}
+              >
+                Dashboard
+              </Sidebar.Item>
+            </Sidebar.Section>
+          )}
+
           {sortedEntries.map(([category, items]) => {
             const sortedItems = [...items]
               .filter(item => item.segment?.meta?.name)
@@ -331,7 +309,7 @@ export function LeftSidebar({ segments, activeSegment, onSelect, showHealth, onH
                     <Sidebar.Item
                       key={item.path}
                       active={activeSegment === item.path}
-                      onClick={() => onSelect(item.path)}
+                      onClick={() => handleSelect(item.path)}
                     >
                       <HighlightedText
                         text={item.segment.meta.name}
@@ -356,6 +334,6 @@ export function LeftSidebar({ segments, activeSegment, onSelect, showHealth, onH
       <Sidebar.Footer>
         <Badge size="sm">{segments.length} components</Badge>
       </Sidebar.Footer>
-    </Sidebar>
+    </>
   );
 }

package/src/viewer/components/PreviewFrameHost.tsx

@@ -24,6 +24,7 @@ interface SegmentDefinition {
   meta: {
     name: string;
     description?: string;
+    category?: string;
   };
   variants?: SegmentVariant[];
 }
@@ -82,6 +83,23 @@ function findVariant(segment: SegmentDefinition, variantName: string): SegmentVa
   return segment.variants?.find(v => v.name === variantName);
 }
 
+type PreviewMode = 'centered' | 'full-bleed';
+
+function resolvePreviewMode(segment: SegmentDefinition): PreviewMode {
+  const name = segment.meta.name.toLowerCase();
+  const category = (segment.meta.category || '').toLowerCase();
+
+  if (category === 'layout' || category === 'navigation') {
+    return 'full-bleed';
+  }
+
+  if (name.includes('appshell') || name.includes('sidebar') || name.includes('header') || name.includes('layout')) {
+    return 'full-bleed';
+  }
+
+  return 'centered';
+}
+
 /**
  * Error boundary for catching render errors
  */
@@ -118,11 +136,13 @@ function LoadingIndicator() {
 function VariantRenderer({
   variant,
   props,
+  mode,
   onRendered,
   onError,
 }: {
   variant: SegmentVariant;
   props?: Record<string, unknown>;
+  mode: PreviewMode;
   onRendered: (width: number, height: number) => void;
   onError: (message: string, stack?: string) => void;
 }) {
@@ -208,7 +228,9 @@ function VariantRenderer({
     <div
       ref={containerRef}
       style={{
-        display: 'inline-block',
+        display: mode === 'full-bleed' ? 'block' : 'inline-block',
+        width: mode === 'full-bleed' ? '100%' : undefined,
+        minHeight: mode === 'full-bleed' ? '100vh' : undefined,
         transition: 'opacity 150ms',
         opacity: content ? 1 : 0,
       }}
@@ -227,6 +249,7 @@ export function PreviewFrameHost() {
   const [loadError, setLoadError] = useState<string | null>(null);
   const [currentVariant, setCurrentVariant] = useState<SegmentVariant | null>(null);
   const [currentProps, setCurrentProps] = useState<Record<string, unknown> | undefined>(undefined);
+  const [previewMode, setPreviewMode] = useState<PreviewMode>('centered');
 
   // Apply theme to document
   useEffect(() => {
@@ -237,6 +260,10 @@ export function PreviewFrameHost() {
     }
   }, [theme]);
 
+  useEffect(() => {
+    document.body.setAttribute('data-preview-mode', previewMode);
+  }, [previewMode]);
+
   // Load segments on mount
   useEffect(() => {
     loadSegments()
@@ -273,6 +300,7 @@ export function PreviewFrameHost() {
       return;
     }
 
+    setPreviewMode(resolvePreviewMode(segmentItem.segment));
     setCurrentVariant(variant);
     setCurrentProps(props);
   }, [renderRequest, segments, notifyError]);
@@ -302,6 +330,7 @@ export function PreviewFrameHost() {
       key={`${renderRequest?.segmentPath}-${renderRequest?.variantName}`}
       variant={currentVariant}
       props={currentProps}
+      mode={previewMode}
       onRendered={notifyRendered}
       onError={notifyError}
     />