@fragments-sdk/cli 0.9.0 → 0.9.1

package/src/viewer/components/VariantMatrix.tsx

@@ -12,6 +12,7 @@
 
 import { useState, useMemo, useRef, useCallback } from "react";
 import { useVirtualizer } from "@tanstack/react-virtual";
+import { Box, Stack, Text, Button, Badge, EmptyState } from "@fragments-sdk/ui";
 import type { FragmentVariant } from "../../core/index.js";
 import { ErrorBoundary } from "./ErrorBoundary.js";
 import { FragmentRenderer, LoaderIndicator } from "./FragmentRenderer.js";
@@ -65,7 +66,6 @@ export function VariantMatrix({
 }: VariantMatrixProps) {
   const [gridSize, setGridSize] = useState<GridSize>("medium");
   const [hoveredIndex, setHoveredIndex] = useState<number | null>(null);
-  const [hoveredButton, setHoveredButton] = useState<GridSize | null>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
 
   const gridConfig = GRID_SIZES[gridSize];
@@ -90,79 +90,43 @@ export function VariantMatrix({
 
   if (variants.length === 0) {
     return (
-      <div style={{
-        display: 'flex',
-        alignItems: 'center',
-        justifyContent: 'center',
-        height: '100%',
-        color: 'var(--text-muted)',
-      }}>
-        No variants to display
-      </div>
+      <EmptyState style={{ height: '100%' }}>
+        <EmptyState.Title>No variants to display</EmptyState.Title>
+      </EmptyState>
     );
   }
 
   return (
-    <div style={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
+    <Stack style={{ height: '100%' }}>
       {/* Toolbar */}
-      <div style={{
-        flexShrink: 0,
-        padding: '8px 16px',
-        borderBottom: '1px solid var(--border)',
-        background: 'var(--bg-secondary)',
-        display: 'flex',
-        alignItems: 'center',
-        justifyContent: 'space-between',
-      }}>
-        <div style={{ fontSize: 14, color: 'var(--text-secondary)' }}>
-          {variants.length} variant{variants.length !== 1 ? "s" : ""}
-          {useVirtualization && (
-            <span style={{ marginLeft: 8, fontSize: 12, color: 'var(--text-tertiary)' }}>(virtualized)</span>
-          )}
-        </div>
-        <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
-          <span style={{ fontSize: 12, color: 'var(--text-tertiary)' }}>Grid size:</span>
-          <div style={{
-            display: 'flex',
-            borderRadius: 6,
-            border: '1px solid var(--border)',
-            overflow: 'hidden',
-          }}>
-            {(["small", "medium", "large"] as GridSize[]).map((size) => (
-              <button
-                key={size}
-                onClick={() => setGridSize(size)}
-                onMouseEnter={() => setHoveredButton(size)}
-                onMouseLeave={() => setHoveredButton(null)}
-                style={{
-                  padding: '4px 8px',
-                  fontSize: 12,
-                  textTransform: 'capitalize',
-                  transition: 'background-color 0.15s, color 0.15s',
-                  border: 'none',
-                  cursor: 'pointer',
-                  background: gridSize === size
-                    ? 'var(--bg-hover)'
-                    : hoveredButton === size
-                      ? 'var(--bg-hover)'
-                      : 'transparent',
-                  color: gridSize === size
-                    ? 'var(--text-primary)'
-                    : hoveredButton === size
-                      ? 'var(--text-secondary)'
-                      : 'var(--text-tertiary)',
-                }}
-              >
-                {size}
-              </button>
-            ))}
-          </div>
-        </div>
-      </div>
+      <Box paddingX="md" paddingY="sm" borderBottom background="secondary" style={{ flexShrink: 0 }}>
+        <Stack direction="row" align="center" justify="between">
+          <Text size="sm" color="secondary">
+            {variants.length} variant{variants.length !== 1 ? "s" : ""}
+            {useVirtualization && <Text as="span" size="xs" color="tertiary"> (virtualized)</Text>}
+          </Text>
+          <Stack direction="row" align="center" gap="sm">
+            <Text size="xs" color="tertiary">Grid size:</Text>
+            <Stack direction="row" style={{ borderRadius: 6, border: '1px solid var(--border)', overflow: 'hidden' }}>
+              {(["small", "medium", "large"] as GridSize[]).map((size) => (
+                <Button
+                  key={size}
+                  variant={gridSize === size ? "secondary" : "ghost"}
+                  size="sm"
+                  onClick={() => setGridSize(size)}
+                  style={{ textTransform: 'capitalize', borderRadius: 0 }}
+                >
+                  {size}
+                </Button>
+              ))}
+            </Stack>
+          </Stack>
+        </Stack>
+      </Box>
 
       {/* Grid - Virtualized or Regular */}
       {useVirtualization ? (
-        <div ref={scrollRef} style={{ flex: 1, overflow: 'auto', padding: 16 }}>
+        <Box ref={scrollRef} overflow="auto" padding="md" style={{ flex: 1 }}>
           <div
             style={{
               height: `${rowVirtualizer.getTotalSize()}px`,
@@ -217,9 +181,9 @@ export function VariantMatrix({
               );
             })}
           </div>
-        </div>
+        </Box>
       ) : (
-        <div style={{ flex: 1, overflow: 'auto', padding: 16 }}>
+        <Box overflow="auto" padding="md" style={{ flex: 1 }}>
           <div style={{
             display: 'grid',
             gap: 16,
@@ -243,9 +207,9 @@ export function VariantMatrix({
               />
             ))}
           </div>
-        </div>
+        </Box>
       )}
-    </div>
+    </Stack>
   );
 }
 
@@ -298,7 +262,7 @@ function VariantCard({
       onMouseLeave={onLeave}
       onClick={onClick}
     >
-      {/* Header */}
+      {/* Header overlay - keep inline styles (CSS art) */}
       <div style={{
         position: 'absolute',
         top: 0,
@@ -384,25 +348,25 @@ function VariantCard({
             <ErrorBoundary
               componentName={componentName}
               fallback={
-                <div style={{ fontSize: 12, color: '#ef4444', padding: 8 }}>
+                <Text size="xs" style={{ color: 'var(--color-danger)' }}>
                   Error rendering variant
-                </div>
+                </Text>
               }
             >
               <FragmentRenderer variant={variant}>
                 {(content, isLoading, error) => {
                   if (isLoading) {
                     return (
-                      <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 16 }}>
+                      <Stack align="center" justify="center" style={{ padding: 16 }}>
                         <LoaderIndicator />
-                      </div>
+                      </Stack>
                     );
                   }
                   if (error) {
                     return (
-                      <div style={{ fontSize: 12, color: '#ef4444', padding: 8 }}>
+                      <Text size="xs" style={{ color: 'var(--color-danger)', padding: 8 }}>
                         {error.message}
-                      </div>
+                      </Text>
                     );
                   }
                   return content;
@@ -416,15 +380,7 @@ function VariantCard({
       {/* Tags/badges */}
       {variant.hasPlayFunction && (
         <div style={{ position: 'absolute', bottom: 8, right: 8, zIndex: 10 }}>
-          <span style={{
-            padding: '2px 6px',
-            fontSize: 10,
-            background: '#9333ea',
-            color: '#ffffff',
-            borderRadius: 4,
-          }}>
-            play
-          </span>
+          <Badge variant="info" size="sm">play</Badge>
         </div>
       )}
     </div>

package/src/viewer/components/VariantTabs.tsx

@@ -1,4 +1,4 @@
-import { Tabs } from '@fragments-sdk/ui';
+import { Tabs, Stack } from '@fragments-sdk/ui';
 import type { FragmentVariant } from '../../core/index.js';
 import { PlayIcon } from './Icons.js';
 
@@ -24,14 +24,14 @@ export function VariantTabs({ variants, activeIndex, onSelect }: VariantTabsProp
       <Tabs.List variant="pills">
         {variants.map((variant) => (
           <Tabs.Tab key={variant.name} value={variant.name}>
-            <span style={{ display: 'flex', alignItems: 'center', gap: '6px' }}>
+            <Stack direction="row" align="center" gap="xs" as="span">
               {variant.name}
               {variant.hasPlayFunction && (
                 <span style={{ display: 'inline-flex', width: '12px', height: '12px', color: 'var(--color-accent)' }}>
                   <PlayIcon />
                 </span>
               )}
-            </span>
+            </Stack>
           </Tabs.Tab>
         ))}
       </Tabs.List>

package/src/viewer/components/ViewerHeader.tsx

@@ -0,0 +1,69 @@
+import type { RefObject } from "react";
+import { BRAND } from "../../core/index.js";
+import {
+  Header,
+  Stack,
+  Text,
+  Button,
+  ThemeToggle,
+  FragmentsLogo,
+} from "@fragments-sdk/ui";
+import { GitHubIcon } from "./Icons.js";
+import { HeaderSearch } from "./HeaderSearch.js";
+import { useTheme } from "./ThemeProvider.js";
+import { WebMCPStatusIndicator } from "./WebMCPStatusIndicator.js";
+
+interface ViewerHeaderProps {
+  showHealth: boolean;
+  searchQuery: string;
+  onSearchChange: (value: string) => void;
+  searchInputRef: RefObject<HTMLInputElement>;
+}
+
+export function ViewerHeader({
+  showHealth,
+  searchQuery,
+  onSearchChange,
+  searchInputRef,
+}: ViewerHeaderProps) {
+  const { setTheme, resolvedTheme } = useTheme();
+  return (
+    <Header aria-label="Fragments viewer header">
+      <Header.Trigger />
+      <Header.Brand>
+        <Stack direction="row" gap="sm" align="center">
+          <FragmentsLogo size={20} />
+          <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.Actions>
+        <WebMCPStatusIndicator />
+        <ThemeToggle
+          size="sm"
+          value={resolvedTheme}
+          onValueChange={(value) => setTheme(value)}
+          aria-label={`Theme: ${resolvedTheme}`}
+        />
+        <Button
+          as="a"
+          variant="ghost"
+          size="sm"
+          icon
+          href="https://github.com/ConanMcN/fragments"
+          target="_blank"
+          rel="noopener noreferrer"
+          aria-label="View on GitHub"
+        >
+          <GitHubIcon />
+        </Button>
+      </Header.Actions>
+    </Header>
+  );
+}

package/src/viewer/components/WebMCPDevTools.tsx

@@ -190,17 +190,15 @@ export function WebMCPDevTools() {
                                 ([name, prop]) => (
                                   <Box
                                     key={name}
-                                    style={{
-                                      padding: "6px 8px",
-                                      borderRadius: "var(--radius-sm)",
-                                      backgroundColor: "var(--bg-secondary)",
-                                    }}
+                                    padding="sm"
+                                    rounded="sm"
+                                    background="secondary"
                                   >
                                     <Stack direction="row" gap="xs" align="center">
                                       <Text
                                         size="xs"
                                         weight="medium"
-                                        style={{ fontFamily: "monospace" }}
+                                        font="mono"
                                       >
                                         {name}
                                       </Text>
@@ -219,7 +217,7 @@ export function WebMCPDevTools() {
                                       </Text>
                                     )}
                                     {prop.enum && (
-                                      <Text size="2xs" color="tertiary" style={{ marginTop: "2px", fontFamily: "monospace" }}>
+                                      <Text size="2xs" color="tertiary" font="mono" style={{ marginTop: "2px" }}>
                                         enum: {prop.enum.join(" | ")}
                                       </Text>
                                     )}
@@ -292,9 +290,9 @@ export function WebMCPDevTools() {
                   />
                 ) : (
                   <Box
+                    padding="sm"
+                    rounded="md"
                     style={{
-                      padding: "12px",
-                      borderRadius: "var(--radius-md)",
                       backgroundColor: "var(--bg-danger, #fef2f2)",
                     }}
                   >
@@ -425,14 +423,12 @@ export function WebMCPDevTools() {
                       .map(([name, stat]) => (
                         <Box
                           key={name}
-                          style={{
-                            padding: "8px 10px",
-                            borderRadius: "var(--radius-sm)",
-                            backgroundColor: "var(--bg-secondary)",
-                          }}
+                          padding="sm"
+                          rounded="sm"
+                          background="secondary"
                         >
-                          <Stack direction="row" gap="sm" align="center" style={{ justifyContent: "space-between" }}>
-                            <Text size="xs" weight="medium" style={{ fontFamily: "monospace" }}>
+                          <Stack direction="row" gap="sm" align="center" justify="between">
+                            <Text size="xs" weight="medium" font="mono">
                               {name}
                             </Text>
                             <Stack direction="row" gap="xs">
@@ -461,14 +457,12 @@ export function WebMCPDevTools() {
                       {summary.commonFlows.map((flow, i) => (
                         <Box
                           key={i}
-                          style={{
-                            padding: "6px 8px",
-                            borderRadius: "var(--radius-sm)",
-                            backgroundColor: "var(--bg-secondary)",
-                          }}
+                          padding="sm"
+                          rounded="sm"
+                          background="secondary"
                         >
                           <Stack direction="row" gap="xs" align="center">
-                            <Text size="2xs" style={{ fontFamily: "monospace" }}>
+                            <Text size="2xs" font="mono">
                               {flow.sequence.join(' → ')}
                             </Text>
                             <Badge size="sm" variant="info">{flow.count}x</Badge>
@@ -486,10 +480,10 @@ export function WebMCPDevTools() {
 
       {/* Protocol Status Footer */}
       <Box
+        borderTop
         style={{
           marginTop: "auto",
           paddingTop: "12px",
-          borderTop: "1px solid var(--border-subtle)",
         }}
       >
         <Stack direction="row" gap="sm" align="center">

package/src/viewer/components/viewer-utils.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared utility functions for viewer components.
+ */
+
+export function normalizeAnchorSegment(value: string): string {
+  const normalized = value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized || "variant";
+}
+
+export function getVariantSectionId(componentName: string, variantName: string): string {
+  return `preview-${normalizeAnchorSegment(componentName)}-${normalizeAnchorSegment(variantName)}`;
+}

package/src/viewer/entry.tsx

@@ -137,6 +137,7 @@ declare global {
       fragment: import("../core/index.js").FragmentDefinition;
     }>;
     __FRAGMENTS_CONFIG__?: import("../core/index.js").FragmentsConfig;
+    __FRAGMENTS_PACKAGE_NAME__?: string | null;
     __FRAGMENTS_ERROR__?: string;
   }
 }
@@ -175,6 +176,10 @@ async function loadFragmentsFromVirtualModule(): Promise<void> {
       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";

package/src/viewer/hooks/useAppState.ts

@@ -5,7 +5,7 @@
 
 import { useReducer, useCallback, useMemo } from 'react';
 
-export type ActivePanel = 'code' | 'styles' | 'accessibility' | 'interactions' | 'actions' | 'graph' | 'contract' | 'performance';
+export type ActivePanel = 'styles' | 'accessibility' | 'interactions' | 'graph' | 'performance';
 
 interface AppUIState {
   activePanel: ActivePanel;
@@ -16,6 +16,7 @@ interface AppUIState {
   showMatrixView: boolean;
   showCommandPalette: boolean;
   showMultiViewport: boolean;
+  showAside: boolean;
   linkCopied: boolean;
   previewKey: number;
 }
@@ -34,17 +35,28 @@ type AppUIAction =
   | { type: 'SET_MULTI_VIEWPORT'; payload: boolean }
   | { type: 'SET_LINK_COPIED'; payload: boolean }
   | { type: 'INCREMENT_PREVIEW_KEY' }
+  | { type: 'TOGGLE_ASIDE' }
+  | { type: 'SET_ASIDE'; payload: boolean }
   | { type: 'CLOSE_ALL_MODALS' };
 
+function getInitialAsideState(): boolean {
+  try {
+    const stored = localStorage.getItem('fragments-aside-visible');
+    if (stored !== null) return stored === 'true';
+  } catch { /* noop */ }
+  return true;
+}
+
 const initialState: AppUIState = {
-  activePanel: 'code',
-  panelOpen: true,
+  activePanel: 'accessibility',
+  panelOpen: false,
   showHealthDashboard: false,
-  showComparison: true,
+  showComparison: false,
   showShortcutsHelp: false,
   showMatrixView: false,
   showCommandPalette: false,
   showMultiViewport: false,
+  showAside: getInitialAsideState(),
   linkCopied: false,
   previewKey: 0,
 };
@@ -87,6 +99,15 @@ function appUIReducer(state: AppUIState, action: AppUIAction): AppUIState {
       return { ...state, linkCopied: action.payload };
     case 'INCREMENT_PREVIEW_KEY':
       return { ...state, previewKey: state.previewKey + 1 };
+    case 'TOGGLE_ASIDE': {
+      const next = !state.showAside;
+      try { localStorage.setItem('fragments-aside-visible', String(next)); } catch { /* noop */ }
+      return { ...state, showAside: next };
+    }
+    case 'SET_ASIDE': {
+      try { localStorage.setItem('fragments-aside-visible', String(action.payload)); } catch { /* noop */ }
+      return { ...state, showAside: action.payload };
+    }
     case 'CLOSE_ALL_MODALS':
       return {
         ...state,
@@ -115,6 +136,8 @@ export function useAppState() {
     setMultiViewport: (show: boolean) => dispatch({ type: 'SET_MULTI_VIEWPORT', payload: show }),
     setLinkCopied: (copied: boolean) => dispatch({ type: 'SET_LINK_COPIED', payload: copied }),
     incrementPreviewKey: () => dispatch({ type: 'INCREMENT_PREVIEW_KEY' }),
+    toggleAside: () => dispatch({ type: 'TOGGLE_ASIDE' }),
+    setAside: (show: boolean) => dispatch({ type: 'SET_ASIDE', payload: show }),
     closeAllModals: () => dispatch({ type: 'CLOSE_ALL_MODALS' }),
   }), []);
 

package/src/viewer/hooks/usePreviewBridge.ts

@@ -57,8 +57,8 @@ export function usePreviewBridge(iframeRef: RefObject<HTMLIFrameElement | null>)
   const initSentRef = useRef(false);
   const currentRenderIdRef = useRef<string | null>(null);
 
-  // Render timeout duration (5 seconds)
-  const RENDER_TIMEOUT = 5000;
+  // Render timeout duration (30 seconds)
+  const RENDER_TIMEOUT = 30000;
 
   // Listen for messages from iframe
   useEffect(() => {

package/src/viewer/preview-frame.html

@@ -28,24 +28,18 @@
 
       #preview-root {
         width: 100%;
-        min-height: 100vh;
+        height: 100%;
+        min-height: 400px;
+        padding: 16px;
         display: flex;
-        align-items: center;
-        justify-content: center;
-        padding: 24px;
+        flex-direction: column;
         box-sizing: border-box;
         overflow: auto;
       }
 
-      body[data-preview-mode='full-bleed'] #preview-root {
-        align-items: flex-start;
-        justify-content: flex-start;
-        padding: 0;
-        min-height: 100vh;
-      }
-
-      body[data-preview-mode='full-bleed'] #preview-root > * {
+      #preview-root > * {
         width: 100%;
+        flex: 1;
       }
 
       /* Hide scrollbars but allow scrolling */