@fragments-sdk/cli 0.10.1 → 0.12.1

package/src/commands/scan.ts

@@ -56,6 +56,8 @@ export interface ScanOptions {
   skipStorybook?: boolean;
   /** Verbose output */
   verbose?: boolean;
+  /** Suppress all console output (for use as a sub-step) */
+  quiet?: boolean;
 }
 
 export interface ScanResult {
@@ -78,6 +80,9 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
   const errors: Array<{ component: string; error: string }> = [];
   const warnings: Array<{ component: string; warning: string }> = [];
 
+  // In quiet mode, suppress all console output
+  const log = options.quiet ? (() => {}) : console.log.bind(console);
+
   // Load config or use defaults
   let configDir: string;
   let outputFile: string;
@@ -95,11 +100,11 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
     componentPatterns = options.componentPatterns;
   }
 
-  console.log(pc.cyan(`\n${BRAND.name} Scan\n`));
-  console.log(pc.dim("Zero-config fragments.json generation from source code\n"));
+  log(pc.cyan(`\n${BRAND.name} Scan\n`));
+  log(pc.dim("Zero-config fragments.json generation from source code\n"));
 
   // Phase 1: Discover components
-  console.log(pc.dim("Phase 1: Discovering components..."));
+  log(pc.dim("Phase 1: Discovering components..."));
   const components = await discoverAllComponents(configDir, {
     patterns: componentPatterns,
     exclude: ["**/*.test.*", "**/*.spec.*", "**/__tests__/**"],
@@ -107,7 +112,7 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
   });
 
   if (components.length === 0) {
-    console.log(pc.yellow("No components found. Check your patterns or config."));
+    log(pc.yellow("No components found. Check your patterns or config."));
     return {
       success: false,
       outputPath: resolve(configDir, outputFile),
@@ -121,18 +126,18 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
     };
   }
 
-  console.log(pc.green(`  Found ${components.length} components`));
+  log(pc.green(`  Found ${components.length} components`));
   if (options.verbose) {
     for (const comp of components.slice(0, 10)) {
-      console.log(pc.dim(`    - ${comp.name}: ${comp.relativePath}`));
+      log(pc.dim(`    - ${comp.name}: ${comp.relativePath}`));
     }
     if (components.length > 10) {
-      console.log(pc.dim(`    ... and ${components.length - 10} more`));
+      log(pc.dim(`    ... and ${components.length - 10} more`));
     }
   }
 
   // Phase 2: Extract props from TypeScript
-  console.log(pc.dim("\nPhase 2: Extracting props from TypeScript..."));
+  log(pc.dim("\nPhase 2: Extracting props from TypeScript..."));
   const propsMap = new Map<string, ReturnType<typeof convertToFragmentProps>>();
   const propsResults = new Map<string, PropsExtractionResult>();
   let propsExtracted = 0;
@@ -159,7 +164,7 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
     }
   }
 
-  console.log(pc.green(`  Extracted props for ${propsExtracted} components`));
+  log(pc.green(`  Extracted props for ${propsExtracted} components`));
 
   // Phase 3: Scan for usage patterns
   let usageAnalysis: UsageAnalysis | undefined;
@@ -167,7 +172,7 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
   let allRelations = new Map<string, ComponentRelation[]>();
 
   if (!options.skipUsage) {
-    console.log(pc.dim("\nPhase 3: Scanning for usage patterns..."));
+    log(pc.dim("\nPhase 3: Scanning for usage patterns..."));
     const usageDir = options.usageDir || configDir;
 
     try {
@@ -196,17 +201,17 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
 
       // Infer relations
       allRelations = inferAllRelations(usageAnalysis);
-      console.log(pc.green(`  Found ${usagesFound} usages across ${usageAnalysis.totalFiles} files`));
-      console.log(pc.green(`  Inferred relations for ${allRelations.size} components`));
+      log(pc.green(`  Found ${usagesFound} usages across ${usageAnalysis.totalFiles} files`));
+      log(pc.green(`  Inferred relations for ${allRelations.size} components`));
     } catch (e) {
       warnings.push({
         component: "*",
         warning: `Usage scanning failed: ${e instanceof Error ? e.message : String(e)}`,
       });
-      console.log(pc.yellow(`  Usage scanning failed: ${e instanceof Error ? e.message : "unknown error"}`));
+      log(pc.yellow(`  Usage scanning failed: ${e instanceof Error ? e.message : "unknown error"}`));
     }
   } else {
-    console.log(pc.dim("\nPhase 3: Skipping usage analysis"));
+    log(pc.dim("\nPhase 3: Skipping usage analysis"));
   }
 
   // Phase 4: Parse Storybook stories
@@ -214,7 +219,7 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
   let storiesParsed = 0;
 
   if (!options.skipStorybook) {
-    console.log(pc.dim("\nPhase 4: Parsing Storybook stories..."));
+    log(pc.dim("\nPhase 4: Parsing Storybook stories..."));
 
     try {
       const allStories = await parseAllStories(configDir);
@@ -226,20 +231,20 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
         }
       }
 
-      console.log(pc.green(`  Parsed stories for ${storiesParsed} components`));
+      log(pc.green(`  Parsed stories for ${storiesParsed} components`));
     } catch (e) {
       warnings.push({
         component: "*",
         warning: `Storybook parsing failed: ${e instanceof Error ? e.message : String(e)}`,
       });
-      console.log(pc.yellow(`  Storybook parsing failed: ${e instanceof Error ? e.message : "unknown error"}`));
+      log(pc.yellow(`  Storybook parsing failed: ${e instanceof Error ? e.message : "unknown error"}`));
     }
   } else {
-    console.log(pc.dim("\nPhase 4: Skipping Storybook parsing"));
+    log(pc.dim("\nPhase 4: Skipping Storybook parsing"));
   }
 
   // Phase 5: Generate fragments
-  console.log(pc.dim("\nPhase 5: Generating fragments..."));
+  log(pc.dim("\nPhase 5: Generating fragments..."));
   const fragments: Record<string, CompiledFragment> = {};
 
   for (const comp of components) {
@@ -277,32 +282,32 @@ export async function scan(options: ScanOptions = {}): Promise<ScanResult> {
   const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
 
   // Summary
-  console.log(pc.dim("\n────────────────────────────────────────"));
-  console.log(pc.green(`\n✓ Generated fragments.json in ${elapsed}s`));
-  console.log(pc.dim(`  Output: ${relative(process.cwd(), outputPath)}`));
-  console.log(pc.dim(`  Components: ${Object.keys(fragments).length}`));
-  console.log(pc.dim(`  Props extracted: ${propsExtracted}`));
-  console.log(pc.dim(`  Usages found: ${usagesFound}`));
-  console.log(pc.dim(`  Relations inferred: ${allRelations.size}`));
-  console.log(pc.dim(`  Stories parsed: ${storiesParsed}`));
+  log(pc.dim("\n────────────────────────────────────────"));
+  log(pc.green(`\n✓ Generated fragments.json in ${elapsed}s`));
+  log(pc.dim(`  Output: ${relative(process.cwd(), outputPath)}`));
+  log(pc.dim(`  Components: ${Object.keys(fragments).length}`));
+  log(pc.dim(`  Props extracted: ${propsExtracted}`));
+  log(pc.dim(`  Usages found: ${usagesFound}`));
+  log(pc.dim(`  Relations inferred: ${allRelations.size}`));
+  log(pc.dim(`  Stories parsed: ${storiesParsed}`));
 
   if (warnings.length > 0) {
-    console.log(pc.yellow(`\n  ${warnings.length} warning(s)`));
+    log(pc.yellow(`\n  ${warnings.length} warning(s)`));
     if (options.verbose) {
       for (const w of warnings) {
-        console.log(pc.dim(`    ${w.component}: ${w.warning}`));
+        log(pc.dim(`    ${w.component}: ${w.warning}`));
       }
     }
   }
 
   if (errors.length > 0) {
-    console.log(pc.red(`\n  ${errors.length} error(s)`));
+    log(pc.red(`\n  ${errors.length} error(s)`));
     for (const e of errors) {
-      console.log(pc.dim(`    ${e.component}: ${e.error}`));
+      log(pc.dim(`    ${e.component}: ${e.error}`));
     }
   }
 
-  console.log();
+  log();
 
   return {
     success: errors.length === 0,

package/src/commands/setup.ts

@@ -36,13 +36,13 @@ export interface SetupResult {
   errors: string[];
 }
 
-type Framework = 'nextjs-app' | 'nextjs-pages' | 'vite' | 'unknown';
+export type Framework = 'nextjs-app' | 'nextjs-pages' | 'vite' | 'remix' | 'astro' | 'unknown';
 
 // ============================================
 // Detection
 // ============================================
 
-async function fileExists(path: string): Promise<boolean> {
+export async function fileExists(path: string): Promise<boolean> {
   try {
     await access(path);
     return true;
@@ -51,7 +51,7 @@ async function fileExists(path: string): Promise<boolean> {
   }
 }
 
-async function detectFramework(root: string): Promise<Framework> {
+export async function detectSetupFramework(root: string): Promise<Framework> {
   // Next.js App Router
   if (
     await fileExists(join(root, 'app/layout.tsx')) ||
@@ -77,7 +77,23 @@ async function detectFramework(root: string): Promise<Framework> {
     return 'nextjs-app';
   }
 
-  // Vite
+  // Remix
+  if (
+    await fileExists(join(root, 'app/root.tsx')) ||
+    await fileExists(join(root, 'app/root.ts'))
+  ) {
+    return 'remix';
+  }
+
+  // Astro
+  if (
+    await fileExists(join(root, 'astro.config.mjs')) ||
+    await fileExists(join(root, 'astro.config.ts'))
+  ) {
+    return 'astro';
+  }
+
+  // Vite (check after Remix/Astro since they also use Vite under the hood)
   if (
     await fileExists(join(root, 'vite.config.ts')) ||
     await fileExists(join(root, 'vite.config.js'))
@@ -85,10 +101,25 @@ async function detectFramework(root: string): Promise<Framework> {
     return 'vite';
   }
 
+  // Fallback: check package.json for framework deps
+  try {
+    const pkgPath = join(root, 'package.json');
+    const pkgContent = await readFile(pkgPath, 'utf-8');
+    const pkg = JSON.parse(pkgContent);
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+    if (allDeps['next']) return 'nextjs-app';
+    if (allDeps['@remix-run/react']) return 'remix';
+    if (allDeps['astro']) return 'astro';
+    if (allDeps['vite']) return 'vite';
+  } catch {
+    // No package.json or parse error
+  }
+
   return 'unknown';
 }
 
-async function findEntryFile(root: string, framework: Framework): Promise<string | null> {
+export async function findEntryFile(root: string, framework: Framework): Promise<string | null> {
   const candidates: string[] = [];
 
   switch (framework) {
@@ -101,6 +132,16 @@ async function findEntryFile(root: string, framework: Framework): Promise<string
     case 'nextjs-pages':
       candidates.push('pages/_app.tsx', 'pages/_app.ts');
       break;
+    case 'remix':
+      candidates.push('app/root.tsx', 'app/root.ts');
+      break;
+    case 'astro':
+      candidates.push(
+        'src/layouts/Layout.astro',
+        'src/layouts/BaseLayout.astro',
+        'src/pages/index.astro'
+      );
+      break;
     case 'vite':
       candidates.push(
         'src/main.tsx', 'src/main.ts',
@@ -138,7 +179,7 @@ async function findNextConfig(root: string): Promise<string | null> {
 // Actions
 // ============================================
 
-async function addStylesImport(root: string, entryFile: string): Promise<{ modified: boolean; message: string }> {
+export async function addStylesImport(root: string, entryFile: string): Promise<{ modified: boolean; message: string }> {
   const fullPath = join(root, entryFile);
   const content = await readFile(fullPath, 'utf-8');
 
@@ -146,22 +187,37 @@ async function addStylesImport(root: string, entryFile: string): Promise<{ modif
     return { modified: false, message: `Styles already imported in ${entryFile}` };
   }
 
-  // Add import at the top of the file, after any 'use client' directive
   const stylesImport = "import '@fragments-sdk/ui/styles';";
   let newContent: string;
 
-  if (content.startsWith("'use client'") || content.startsWith('"use client"')) {
-    const directiveEnd = content.indexOf('\n') + 1;
-    newContent = content.slice(0, directiveEnd) + stylesImport + '\n' + content.slice(directiveEnd);
+  // Astro files: insert inside frontmatter block (between --- fences)
+  if (entryFile.endsWith('.astro')) {
+    const fenceStart = content.indexOf('---');
+    if (fenceStart !== -1) {
+      const insertPos = fenceStart + 4; // after "---\n"
+      newContent = content.slice(0, insertPos) + stylesImport + '\n' + content.slice(insertPos);
+    } else {
+      // No frontmatter — add one
+      newContent = `---\n${stylesImport}\n---\n${content}`;
+    }
   } else {
-    newContent = stylesImport + '\n' + content;
+    const useClientMatch = content.match(/^(?:\uFEFF)?[ \t]*['"]use client['"]\s*;?[ \t]*$/m);
+
+    if (useClientMatch && useClientMatch.index != null) {
+      const directiveLineEnd = content.indexOf('\n', useClientMatch.index);
+      const directiveEnd = directiveLineEnd === -1 ? content.length : directiveLineEnd + 1;
+      const separator = directiveLineEnd === -1 ? '\n' : '';
+      newContent = content.slice(0, directiveEnd) + separator + stylesImport + '\n' + content.slice(directiveEnd);
+    } else {
+      newContent = stylesImport + '\n' + content;
+    }
   }
 
   await writeFile(fullPath, newContent, 'utf-8');
   return { modified: true, message: `Added styles import to ${entryFile}` };
 }
 
-async function addThemeProvider(root: string, entryFile: string, framework: Framework): Promise<{ modified: boolean; message: string }> {
+export async function addThemeProvider(root: string, entryFile: string, framework: Framework): Promise<{ modified: boolean; message: string }> {
   const fullPath = join(root, entryFile);
   const content = await readFile(fullPath, 'utf-8');
 
@@ -169,49 +225,81 @@ async function addThemeProvider(root: string, entryFile: string, framework: Fram
     return { modified: false, message: `ThemeProvider already present in ${entryFile}` };
   }
 
-  // For Next.js App Router, add import and wrap children
-  if (framework === 'nextjs-app') {
-    // Add import
-    const providerImport = "import { ThemeProvider, TooltipProvider, ToastProvider } from '@fragments-sdk/ui';";
+  // Astro uses .astro files — can't inject React imports
+  if (framework === 'astro') {
+    return { modified: false, message: 'Add ThemeProvider in your React island — see https://usefragments.com/getting-started#astro' };
+  }
 
-    let newContent = content;
+  // Add provider import after the last import line
+  const providerImport = "import { ThemeProvider, TooltipProvider, ToastProvider } from '@fragments-sdk/ui';";
 
-    // Find the last import line to add our import after it
-    const importLines = content.split('\n');
-    let lastImportIdx = -1;
-    for (let i = 0; i < importLines.length; i++) {
-      if (importLines[i].startsWith('import ') || importLines[i].startsWith("import '") || importLines[i].startsWith('import "')) {
-        lastImportIdx = i;
-      }
-    }
+  let newContent = content;
+  const lines = content.split('\n');
 
-    if (lastImportIdx >= 0) {
-      importLines.splice(lastImportIdx + 1, 0, providerImport);
-      newContent = importLines.join('\n');
-    } else {
-      newContent = providerImport + '\n' + content;
+  // Prefer placing right after the @fragments-sdk/ui/styles import if it exists
+  let insertIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes('@fragments-sdk/ui/styles')) {
+      insertIdx = i;
+      break;
     }
+  }
 
-    // Add suppressHydrationWarning hint and provider wrapping in a comment
-    // We can't safely auto-wrap JSX, so we add a guide comment instead
-    if (!content.includes('suppressHydrationWarning')) {
-      await writeFile(fullPath, newContent, 'utf-8');
-      return {
-        modified: true,
-        message: `Added provider imports to ${entryFile}. Wrap your {children} with:\n` +
-          `    <ThemeProvider defaultMode="system"><TooltipProvider><ToastProvider>{children}</ToastProvider></TooltipProvider></ThemeProvider>\n` +
-          `    Add suppressHydrationWarning to your <html> tag`,
-      };
+  // Otherwise, place after the last import line
+  if (insertIdx === -1) {
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].startsWith('import ') || lines[i].startsWith("import '") || lines[i].startsWith('import "')) {
+        insertIdx = i;
+      }
     }
+  }
 
-    await writeFile(fullPath, newContent, 'utf-8');
-    return { modified: true, message: `Added provider imports to ${entryFile}. Wrap {children} with ThemeProvider.` };
+  if (insertIdx >= 0) {
+    lines.splice(insertIdx + 1, 0, providerImport);
+    newContent = lines.join('\n');
+  } else {
+    newContent = providerImport + '\n' + content;
   }
 
-  return { modified: false, message: 'Manual ThemeProvider setup needed — see https://usefragments.com/getting-started#provider-setup' };
+  await writeFile(fullPath, newContent, 'utf-8');
+
+  // Framework-specific wrap instructions
+  if (framework === 'nextjs-app') {
+    const hint = !content.includes('suppressHydrationWarning')
+      ? `\n    Add suppressHydrationWarning to your <html> tag`
+      : '';
+    return {
+      modified: true,
+      message: `Added provider imports to ${entryFile}. Wrap {children} with:\n` +
+        `    <ThemeProvider defaultMode="system"><TooltipProvider><ToastProvider>{children}</ToastProvider></TooltipProvider></ThemeProvider>${hint}`,
+    };
+  }
+
+  if (framework === 'nextjs-pages') {
+    return {
+      modified: true,
+      message: `Added provider imports to ${entryFile}. Wrap <Component {...pageProps} /> with:\n` +
+        `    <ThemeProvider defaultMode="system"><TooltipProvider><ToastProvider>...</ToastProvider></TooltipProvider></ThemeProvider>`,
+    };
+  }
+
+  if (framework === 'remix') {
+    return {
+      modified: true,
+      message: `Added provider imports to ${entryFile}. Wrap <Outlet /> with:\n` +
+        `    <ThemeProvider defaultMode="system"><TooltipProvider><ToastProvider>...</ToastProvider></TooltipProvider></ThemeProvider>`,
+    };
+  }
+
+  // Vite and unknown — generic instruction
+  return {
+    modified: true,
+    message: `Added provider imports to ${entryFile}. Wrap your app root with:\n` +
+      `    <ThemeProvider defaultMode="system"><TooltipProvider><ToastProvider>...</ToastProvider></TooltipProvider></ThemeProvider>`,
+  };
 }
 
-async function addTranspilePackages(root: string): Promise<{ modified: boolean; message: string }> {
+export async function addTranspilePackages(root: string): Promise<{ modified: boolean; message: string }> {
   const configFile = await findNextConfig(root);
   if (!configFile) {
     return { modified: false, message: 'No next.config found' };
@@ -235,8 +323,8 @@ async function addTranspilePackages(root: string): Promise<{ modified: boolean;
   // Add transpilePackages to the config
   // Try to find the config object and add the property
   const patterns = [
-    // const nextConfig = { ... }
-    { search: /const\s+\w+\s*=\s*\{/, replacement: (match: string) => `${match}\n  transpilePackages: ['@fragments-sdk/ui'],` },
+    // const nextConfig: NextConfig = { ... } (with optional type annotation)
+    { search: /const\s+\w+\s*(?::\s*\w+)?\s*=\s*\{/, replacement: (match: string) => `${match}\n  transpilePackages: ['@fragments-sdk/ui'],` },
     // module.exports = { ... }
     { search: /module\.exports\s*=\s*\{/, replacement: (match: string) => `${match}\n  transpilePackages: ['@fragments-sdk/ui'],` },
     // export default { ... }
@@ -380,12 +468,15 @@ export async function setup(options: SetupOptions = {}): Promise<SetupResult> {
   console.log(pc.cyan(`\n${BRAND.name} Setup\n`));
 
   // 1. Detect framework
-  const framework = await detectFramework(root);
-  const frameworkLabel =
-    framework === 'nextjs-app' ? 'Next.js (App Router)' :
-    framework === 'nextjs-pages' ? 'Next.js (Pages Router)' :
-    framework === 'vite' ? 'Vite' :
-    'Unknown';
+  const framework = await detectSetupFramework(root);
+  const frameworkLabels: Record<string, string> = {
+    'nextjs-app': 'Next.js (App Router)',
+    'nextjs-pages': 'Next.js (Pages Router)',
+    'vite': 'Vite',
+    'remix': 'Remix',
+    'astro': 'Astro',
+  };
+  const frameworkLabel = frameworkLabels[framework] || 'Unknown';
 
   console.log(`  ${pc.dim('Framework:')} ${frameworkLabel}`);
 

package/src/commands/snapshot.ts

@@ -0,0 +1,197 @@
+/**
+ * fragments snapshot - Run visual snapshot tests per component variant
+ *
+ * Starts the dev server (if not already running), then runs Playwright
+ * snapshot tests against all component variants discovered in fragments.json.
+ */
+
+import { resolve } from "node:path";
+import { execSync, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import pc from "picocolors";
+import { BRAND } from "../core/index.js";
+
+export interface SnapshotOptions {
+  /** Port of a running dev server (skips starting one) */
+  port?: number | string;
+  /** Update existing snapshots instead of comparing */
+  update?: boolean;
+  /** Filter to a specific component name */
+  component?: string;
+  /** Path to Playwright config (auto-detected if omitted) */
+  config?: string;
+  /** Path to the snapshot spec file */
+  spec?: string;
+  /** CI mode — non-interactive, exit 1 on mismatch */
+  ci?: boolean;
+}
+
+export interface SnapshotResult {
+  success: boolean;
+  totalTests: number;
+  passed: number;
+  failed: number;
+}
+
+/**
+ * Find the snapshot spec file.
+ * Checks project root e2e/ first, then falls back to the CLI's bundled spec.
+ */
+function findSnapshotSpec(projectRoot: string, explicitPath?: string): string | null {
+  if (explicitPath) {
+    const resolved = resolve(projectRoot, explicitPath);
+    return existsSync(resolved) ? resolved : null;
+  }
+
+  // Check common locations
+  const candidates = [
+    resolve(projectRoot, "e2e/component-visual-snapshots.spec.ts"),
+    resolve(projectRoot, "tests/visual-snapshots.spec.ts"),
+    resolve(projectRoot, "test/visual-snapshots.spec.ts"),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Run visual snapshot tests.
+ */
+export async function snapshot(options: SnapshotOptions = {}): Promise<SnapshotResult> {
+  const projectRoot = process.cwd();
+  const {
+    port,
+    update = false,
+    component,
+    ci = false,
+  } = options;
+
+  console.log(pc.cyan(`\n${BRAND.name} Visual Snapshots\n`));
+
+  // Check that fragments.json exists
+  const fragmentsJson = resolve(projectRoot, BRAND.outFile);
+  if (!existsSync(fragmentsJson)) {
+    console.error(
+      pc.red(`${BRAND.outFile} not found. Run ${pc.bold(`${BRAND.cliCommand} build`)} first.`)
+    );
+    return { success: false, totalTests: 0, passed: 0, failed: 0 };
+  }
+
+  // Find the snapshot spec
+  const specPath = findSnapshotSpec(projectRoot, options.spec);
+  if (!specPath) {
+    console.error(
+      pc.red("No snapshot spec found.") + "\n" +
+      pc.dim("Expected: e2e/component-visual-snapshots.spec.ts\n") +
+      pc.dim(`Create one or specify with --spec <path>`)
+    );
+    return { success: false, totalTests: 0, passed: 0, failed: 0 };
+  }
+
+  console.log(pc.dim(`Spec: ${specPath}`));
+
+  // Check for Playwright
+  try {
+    execSync("npx playwright --version", { stdio: "pipe" });
+  } catch {
+    console.error(
+      pc.red("Playwright not found.") + "\n" +
+      pc.dim("Install it: pnpm add -D @playwright/test && npx playwright install chromium")
+    );
+    return { success: false, totalTests: 0, passed: 0, failed: 0 };
+  }
+
+  // Build Playwright args
+  const args = ["playwright", "test", specPath];
+
+  if (update) {
+    args.push("--update-snapshots");
+    console.log(pc.yellow("Updating snapshots (baselines will be overwritten)"));
+  }
+
+  if (component) {
+    args.push("--grep", component);
+    console.log(pc.dim(`Filtering: ${component}`));
+  }
+
+  // If a port is specified, set the BASE_URL env var so the spec
+  // can connect to an already-running dev server
+  const env: Record<string, string> = { ...process.env as Record<string, string> };
+  if (port) {
+    env.FRAGMENTS_DEV_PORT = String(port);
+    console.log(pc.dim(`Using running dev server on port ${port}`));
+  }
+
+  console.log(pc.dim("\nRunning snapshot tests...\n"));
+
+  // Run Playwright
+  return new Promise<SnapshotResult>((resolveResult) => {
+    const child = spawn("npx", args, {
+      cwd: projectRoot,
+      stdio: ci ? "pipe" : "inherit",
+      env,
+    });
+
+    let stdout = "";
+
+    if (ci && child.stdout) {
+      child.stdout.on("data", (data) => {
+        stdout += data.toString();
+      });
+    }
+    if (ci && child.stderr) {
+      child.stderr.on("data", (data) => {
+        stdout += data.toString();
+      });
+    }
+
+    child.on("close", (code) => {
+      const success = code === 0;
+
+      if (ci) {
+        // Parse Playwright output for test counts
+        const passedMatch = stdout.match(/(\d+) passed/);
+        const failedMatch = stdout.match(/(\d+) failed/);
+        const passed = passedMatch ? parseInt(passedMatch[1], 10) : 0;
+        const failed = failedMatch ? parseInt(failedMatch[1], 10) : 0;
+
+        if (!success) {
+          process.stdout.write(stdout);
+        }
+
+        resolveResult({
+          success,
+          totalTests: passed + failed,
+          passed,
+          failed,
+        });
+      } else {
+        if (success) {
+          console.log(pc.green("\n✓ All snapshots match\n"));
+        } else if (update) {
+          console.log(pc.green("\n✓ Snapshots updated\n"));
+        } else {
+          console.log(pc.red("\n✗ Snapshot mismatches detected"));
+          console.log(pc.dim(`Run ${pc.bold(`${BRAND.cliCommand} snapshot --update`)} to accept changes\n`));
+        }
+
+        resolveResult({
+          success: success || update,
+          totalTests: 0,
+          passed: 0,
+          failed: 0,
+        });
+      }
+    });
+
+    child.on("error", (err) => {
+      console.error(pc.red(`Failed to run Playwright: ${err.message}`));
+      resolveResult({ success: false, totalTests: 0, passed: 0, failed: 0 });
+    });
+  });
+}