@fragments-sdk/cli 0.7.15 → 0.7.16

package/src/commands/init-framework.ts

@@ -0,0 +1,414 @@
+/**
+ * Framework detection and auto-configuration for fragments init.
+ *
+ * Detects the consumer's framework (Next.js, Vite, Remix, Astro)
+ * and generates appropriate configuration files.
+ */
+
+import { readFile, writeFile, access } from "node:fs/promises";
+import { join } from "node:path";
+import pc from "picocolors";
+
+// ============================================
+// Types
+// ============================================
+
+export type Framework = "nextjs" | "vite" | "remix" | "astro" | "unknown";
+
+export interface FrameworkDetection {
+  framework: Framework;
+  /** Package that triggered the detection */
+  detectedBy: string | null;
+}
+
+export interface FrameworkSetupOptions {
+  /** Project root directory */
+  projectRoot: string;
+  /** Override auto-detected framework */
+  framework?: Framework;
+  /** Seed overrides for globals.scss generation */
+  seeds?: {
+    brand?: string;
+    neutral?: string;
+    density?: string;
+    radiusStyle?: string;
+  };
+}
+
+export interface FrameworkSetupResult {
+  framework: Framework;
+  filesCreated: string[];
+  packagesToInstall: string[];
+  configModified: string[];
+  warnings: string[];
+}
+
+// ============================================
+// Framework Detection
+// ============================================
+
+/**
+ * Detect framework from package.json dependencies
+ */
+export async function detectFramework(
+  projectRoot: string
+): Promise<FrameworkDetection> {
+  try {
+    const pkgPath = join(projectRoot, "package.json");
+    const pkgContent = await readFile(pkgPath, "utf-8");
+    const pkg = JSON.parse(pkgContent);
+
+    const allDeps = {
+      ...pkg.dependencies,
+      ...pkg.devDependencies,
+    };
+
+    // Check in order of specificity
+    if (allDeps["next"]) {
+      return { framework: "nextjs", detectedBy: "next" };
+    }
+    if (allDeps["@remix-run/react"]) {
+      return { framework: "remix", detectedBy: "@remix-run/react" };
+    }
+    if (allDeps["astro"]) {
+      return { framework: "astro", detectedBy: "astro" };
+    }
+    if (allDeps["vite"]) {
+      return { framework: "vite", detectedBy: "vite" };
+    }
+
+    return { framework: "unknown", detectedBy: null };
+  } catch {
+    return { framework: "unknown", detectedBy: null };
+  }
+}
+
+// ============================================
+// Globals SCSS Generation
+// ============================================
+
+function generateGlobalsSCSS(seeds?: FrameworkSetupOptions["seeds"]): string {
+  const withClauses: string[] = [];
+
+  if (seeds?.brand) {
+    withClauses.push(`  $fui-brand: ${seeds.brand}`);
+  }
+  if (seeds?.neutral) {
+    withClauses.push(`  $fui-neutral: "${seeds.neutral}"`);
+  }
+  if (seeds?.density) {
+    withClauses.push(`  $fui-density: "${seeds.density}"`);
+  }
+  if (seeds?.radiusStyle) {
+    withClauses.push(`  $fui-radius-style: "${seeds.radiusStyle}"`);
+  }
+
+  const useStatement =
+    withClauses.length > 0
+      ? `@use '@fragments-sdk/ui/styles' with (\n${withClauses.join(",\n")}\n);`
+      : `@use '@fragments-sdk/ui/styles';`;
+
+  return `// Fragments SDK Global Styles
+// Customize seed values to theme the entire design system.
+// See: https://usefragments.com/docs/theming
+${useStatement}
+`;
+}
+
+// ============================================
+// Providers Component Generation
+// ============================================
+
+function generateProviders(): string {
+  return `'use client';
+
+import { ThemeProvider } from '@fragments-sdk/ui';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider defaultTheme="system" attribute="data-theme">
+      {children}
+    </ThemeProvider>
+  );
+}
+`;
+}
+
+// ============================================
+// Per-Framework Configuration
+// ============================================
+
+async function setupNextJS(
+  projectRoot: string,
+  options: FrameworkSetupOptions
+): Promise<FrameworkSetupResult> {
+  const result: FrameworkSetupResult = {
+    framework: "nextjs",
+    filesCreated: [],
+    packagesToInstall: [],
+    configModified: [],
+    warnings: [],
+  };
+
+  // Check if sass is installed
+  try {
+    const pkgContent = await readFile(
+      join(projectRoot, "package.json"),
+      "utf-8"
+    );
+    const pkg = JSON.parse(pkgContent);
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (!allDeps["sass"]) {
+      result.packagesToInstall.push("sass");
+    }
+  } catch {
+    // Proceed without checking
+  }
+
+  // Update next.config if transpilePackages is needed
+  const nextConfigPaths = [
+    "next.config.ts",
+    "next.config.mjs",
+    "next.config.js",
+  ];
+
+  for (const configName of nextConfigPaths) {
+    const configPath = join(projectRoot, configName);
+    try {
+      await access(configPath);
+      const content = await readFile(configPath, "utf-8");
+
+      if (!content.includes("transpilePackages")) {
+        // Add transpilePackages to the config
+        if (content.includes("const nextConfig")) {
+          const updated = content.replace(
+            /const nextConfig\s*=\s*\{/,
+            `const nextConfig = {\n  transpilePackages: ['@fragments-sdk/ui'],`
+          );
+          await writeFile(configPath, updated, "utf-8");
+          result.configModified.push(configName);
+        } else {
+          result.warnings.push(
+            `Could not auto-modify ${configName}. Add transpilePackages: ['@fragments-sdk/ui'] manually.`
+          );
+        }
+      }
+      break;
+    } catch {
+      continue;
+    }
+  }
+
+  // Generate globals.scss
+  const globalsPath = join(projectRoot, "src", "styles", "globals.scss");
+  try {
+    await access(globalsPath);
+    result.warnings.push(
+      "src/styles/globals.scss already exists. Skipped generation."
+    );
+  } catch {
+    await writeFile(globalsPath, generateGlobalsSCSS(options.seeds), "utf-8");
+    result.filesCreated.push("src/styles/globals.scss");
+  }
+
+  // Generate providers.tsx
+  const providersPath = join(projectRoot, "src", "providers.tsx");
+  try {
+    await access(providersPath);
+    result.warnings.push("src/providers.tsx already exists. Skipped.");
+  } catch {
+    await writeFile(providersPath, generateProviders(), "utf-8");
+    result.filesCreated.push("src/providers.tsx");
+  }
+
+  return result;
+}
+
+async function setupVite(
+  projectRoot: string,
+  options: FrameworkSetupOptions
+): Promise<FrameworkSetupResult> {
+  const result: FrameworkSetupResult = {
+    framework: "vite",
+    filesCreated: [],
+    packagesToInstall: [],
+    configModified: [],
+    warnings: [],
+  };
+
+  // Check if sass is installed
+  try {
+    const pkgContent = await readFile(
+      join(projectRoot, "package.json"),
+      "utf-8"
+    );
+    const pkg = JSON.parse(pkgContent);
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (!allDeps["sass"]) {
+      result.packagesToInstall.push("sass");
+    }
+  } catch {
+    // Proceed
+  }
+
+  // Generate globals.scss
+  const globalsPath = join(projectRoot, "src", "styles", "globals.scss");
+  try {
+    await access(globalsPath);
+    result.warnings.push(
+      "src/styles/globals.scss already exists. Skipped generation."
+    );
+  } catch {
+    await writeFile(globalsPath, generateGlobalsSCSS(options.seeds), "utf-8");
+    result.filesCreated.push("src/styles/globals.scss");
+  }
+
+  // Generate providers.tsx
+  const providersPath = join(projectRoot, "src", "providers.tsx");
+  try {
+    await access(providersPath);
+    result.warnings.push("src/providers.tsx already exists. Skipped.");
+  } catch {
+    await writeFile(providersPath, generateProviders(), "utf-8");
+    result.filesCreated.push("src/providers.tsx");
+  }
+
+  return result;
+}
+
+async function setupRemix(
+  projectRoot: string,
+  options: FrameworkSetupOptions
+): Promise<FrameworkSetupResult> {
+  const result: FrameworkSetupResult = {
+    framework: "remix",
+    filesCreated: [],
+    packagesToInstall: [],
+    configModified: [],
+    warnings: [],
+  };
+
+  result.packagesToInstall.push("sass");
+
+  // Generate globals.scss in app/styles
+  const globalsPath = join(projectRoot, "app", "styles", "globals.scss");
+  try {
+    await access(globalsPath);
+    result.warnings.push(
+      "app/styles/globals.scss already exists. Skipped generation."
+    );
+  } catch {
+    await writeFile(globalsPath, generateGlobalsSCSS(options.seeds), "utf-8");
+    result.filesCreated.push("app/styles/globals.scss");
+  }
+
+  // Generate providers.tsx
+  const providersPath = join(projectRoot, "app", "providers.tsx");
+  try {
+    await access(providersPath);
+    result.warnings.push("app/providers.tsx already exists. Skipped.");
+  } catch {
+    await writeFile(providersPath, generateProviders(), "utf-8");
+    result.filesCreated.push("app/providers.tsx");
+  }
+
+  result.warnings.push(
+    'Add @fragments-sdk/ui to serverDependenciesToBundle in remix.config if using source imports.'
+  );
+
+  return result;
+}
+
+async function setupAstro(
+  projectRoot: string,
+  options: FrameworkSetupOptions
+): Promise<FrameworkSetupResult> {
+  const result: FrameworkSetupResult = {
+    framework: "astro",
+    filesCreated: [],
+    packagesToInstall: [],
+    configModified: [],
+    warnings: [],
+  };
+
+  result.packagesToInstall.push("sass");
+
+  // Generate globals.scss
+  const globalsPath = join(projectRoot, "src", "styles", "globals.scss");
+  try {
+    await access(globalsPath);
+    result.warnings.push(
+      "src/styles/globals.scss already exists. Skipped generation."
+    );
+  } catch {
+    await writeFile(globalsPath, generateGlobalsSCSS(options.seeds), "utf-8");
+    result.filesCreated.push("src/styles/globals.scss");
+  }
+
+  return result;
+}
+
+// ============================================
+// Main Setup Function
+// ============================================
+
+/**
+ * Set up framework-specific configuration for @fragments-sdk/ui
+ */
+export async function setupFramework(
+  options: FrameworkSetupOptions
+): Promise<FrameworkSetupResult> {
+  const { projectRoot } = options;
+
+  // Detect or use provided framework
+  let framework = options.framework;
+  if (!framework || framework === "unknown") {
+    const detection = await detectFramework(projectRoot);
+    framework = detection.framework;
+
+    if (detection.detectedBy) {
+      console.log(
+        pc.green(`  Detected ${frameworkLabel(framework)}`) +
+          pc.dim(` (via ${detection.detectedBy})`)
+      );
+    }
+  } else {
+    console.log(pc.green(`  Framework: ${frameworkLabel(framework)}`));
+  }
+
+  switch (framework) {
+    case "nextjs":
+      return setupNextJS(projectRoot, options);
+    case "vite":
+      return setupVite(projectRoot, options);
+    case "remix":
+      return setupRemix(projectRoot, options);
+    case "astro":
+      return setupAstro(projectRoot, options);
+    default:
+      return {
+        framework: "unknown",
+        filesCreated: [],
+        packagesToInstall: ["sass"],
+        configModified: [],
+        warnings: [
+          "Could not detect framework. Install sass and import @fragments-sdk/ui/styles manually.",
+        ],
+      };
+  }
+}
+
+function frameworkLabel(framework: Framework): string {
+  switch (framework) {
+    case "nextjs":
+      return "Next.js";
+    case "vite":
+      return "Vite";
+    case "remix":
+      return "Remix";
+    case "astro":
+      return "Astro";
+    default:
+      return "Unknown";
+  }
+}

package/src/commands/init.ts

@@ -14,6 +14,11 @@ import pc from "picocolors";
 import { BRAND } from "../core/index.js";
 import fg from "fast-glob";
 import { input, confirm, select } from "@inquirer/prompts";
+import {
+  setupFramework,
+  detectFramework,
+  type Framework,
+} from "./init-framework.js";
 
 export interface InitOptions {
   /** Project root directory */
@@ -22,6 +27,8 @@ export interface InitOptions {
   force?: boolean;
   /** Non-interactive mode - auto-detect and use defaults */
   yes?: boolean;
+  /** Explicit framework override */
+  framework?: string;
 }
 
 export interface InitResult {
@@ -596,7 +603,40 @@ export async function init(options: InitOptions = {}): Promise<InitResult> {
     }
   }
 
-  // Step 6: Show next steps or start server
+  // Step 6: Framework-specific configuration
+  console.log(pc.dim("\nConfiguring framework integration...\n"));
+
+  const frameworkOverride = options.framework as Framework | undefined;
+  const frameworkResult = await setupFramework({
+    projectRoot,
+    framework: frameworkOverride,
+  });
+
+  if (frameworkResult.filesCreated.length > 0) {
+    for (const file of frameworkResult.filesCreated) {
+      console.log(pc.green(`✓ Created ${file}`));
+    }
+  }
+
+  if (frameworkResult.configModified.length > 0) {
+    for (const file of frameworkResult.configModified) {
+      console.log(pc.green(`✓ Updated ${file}`));
+    }
+  }
+
+  if (frameworkResult.packagesToInstall.length > 0) {
+    const pkgs = frameworkResult.packagesToInstall.join(" ");
+    console.log(
+      pc.yellow(`\n⚠ Install required dependencies: `) +
+        pc.bold(`pnpm add -D ${pkgs}`)
+    );
+  }
+
+  for (const warning of frameworkResult.warnings) {
+    console.log(pc.yellow(`  Note: ${warning}`));
+  }
+
+  // Step 7: Show next steps or start server
   if (errors.length === 0) {
     console.log(pc.green("\n✓ Setup complete!\n"));
 

package/src/viewer/components/App.tsx

@@ -50,6 +50,8 @@ import { useActions } from "../hooks/useActions.js";
 import { useUrlState, findFragmentByName, findVariantIndex } from "../hooks/useUrlState.js";
 import { usePanelDock } from "./ResizablePanel.js";
 import { useTheme } from "./ThemeProvider.js";
+import { WebMCPStatusIndicator } from "./WebMCPStatusIndicator.js";
+import { ViewerStateSync } from "./ViewerStateSync.js";
 
 interface AppProps {
   fragments: Array<{ path: string; fragment: FragmentDefinition }>;
@@ -364,6 +366,7 @@ export function App({ fragments }: AppProps) {
 
   return (
     <>
+      <ViewerStateSync fragments={fragments} activeVariantIndex={safeVariantIndex} />
       <KeyboardShortcutsHelp isOpen={uiState.showShortcutsHelp} onClose={() => uiActions.setShortcutsHelp(false)} />
       <CommandPalette
         isOpen={uiState.showCommandPalette}
@@ -611,6 +614,7 @@ function ViewerHeader({ showHealth, searchQuery, onSearchChange, searchInputRef
       <HeaderSearch value={searchQuery} onChange={onSearchChange} inputRef={searchInputRef} />
       <Header.Spacer />
       <Header.Actions>
+        <WebMCPStatusIndicator />
         <ThemeToggle
           size="sm"
           value={resolvedTheme}
@@ -833,6 +837,7 @@ function TopToolbar({
             <Separator orientation="vertical" style={{ height: '16px' }} />
           </>
         )}
+        <WebMCPStatusIndicator />
         <ThemeToggle
           size="sm"
           value={resolvedTheme}

package/src/viewer/components/HealthDashboard.tsx

@@ -7,7 +7,7 @@
 import { useMemo, useState, useCallback, useEffect } from 'react';
 import type { FragmentDefinition } from '../../core/index.js';
 import type { ImpactValue } from 'axe-core';
-import { Badge, Progress, Stack, Text, Card, EmptyState, Table } from '@fragments-sdk/ui';
+import { Badge, Progress, Stack, Text, Card, EmptyState } from '@fragments-sdk/ui';
 import {
   getAllA11yData,
   getA11ySummary,

package/src/viewer/components/PropsTable.tsx

@@ -1,6 +1,6 @@
 import { useMemo } from 'react';
 import type { PropDefinition } from '../../core/index.js';
-import { Table, createColumns, Badge, Text, Stack } from '@fragments-sdk/ui';
+import { DataTable, createColumns, Badge, Text, Stack } from '@fragments-sdk/ui';
 import { WarningIcon } from './Icons.js';
 
 interface PropsTableProps {
@@ -99,7 +99,7 @@ export function PropsTable({ props }: PropsTableProps) {
   return (
     <section id="props" style={{ scrollMarginTop: '96px' }}>
       <Text as="h2" size="md" weight="semibold" style={{ marginBottom: '16px' }}>Props</Text>
-      <Table
+      <DataTable
         columns={columns}
         data={data}
         size="sm"

package/src/viewer/components/RuntimeToolsRegistrar.tsx

@@ -0,0 +1,17 @@
+import { useMemo } from 'react';
+import { useWebMCPTools } from '@fragments-sdk/webmcp/react';
+import { useCompiledFragments } from '../hooks/useCompiledFragments.js';
+import { createRuntimeWebMCPTools } from '../webmcp/runtime-tools.js';
+
+export function RuntimeToolsRegistrar() {
+  const { data } = useCompiledFragments();
+
+  const tools = useMemo(() => {
+    if (!data) return [];
+    return createRuntimeWebMCPTools({ compiledData: data });
+  }, [data]);
+
+  useWebMCPTools(tools);
+
+  return null;
+}

package/src/viewer/components/ViewerStateSync.tsx

@@ -0,0 +1,52 @@
+import { useEffect } from 'react';
+import { setViewerState } from '../webmcp/viewer-state.js';
+import { useUrlState } from '../hooks/useUrlState.js';
+import { useAppState } from '../hooks/useAppState.js';
+import { useViewSettings } from '../hooks/useViewSettings.js';
+import { useTheme } from './ThemeProvider.js';
+import { BRAND, type FragmentDefinition } from '../../core/index.js';
+
+interface ViewerStateSyncProps {
+  fragments: Array<{ path: string; fragment: FragmentDefinition }>;
+  activeVariantIndex: number;
+}
+
+export function ViewerStateSync({ fragments, activeVariantIndex }: ViewerStateSyncProps) {
+  const { state: urlState } = useUrlState();
+  const { state: uiState } = useAppState();
+  const viewSettings = useViewSettings();
+  const { resolvedTheme } = useTheme();
+
+  useEffect(() => {
+    const activeFragment = urlState.component
+      ? fragments.find(f => f.fragment.meta.name.toLowerCase() === urlState.component!.toLowerCase())
+      : null;
+
+    const variants = activeFragment?.fragment.variants ?? [];
+
+    setViewerState({
+      currentComponent: activeFragment?.fragment.meta.name ?? null,
+      currentVariant: variants[activeVariantIndex]?.name ?? null,
+      variantIndex: activeVariantIndex,
+      totalVariants: variants.length,
+      viewport: viewSettings.viewport,
+      zoom: viewSettings.zoom,
+      theme: resolvedTheme,
+      panels: {
+        activePanel: uiState.activePanel,
+        panelOpen: uiState.panelOpen,
+      },
+      viewMode: {
+        matrixView: uiState.showMatrixView,
+        multiViewport: uiState.showMultiViewport,
+        comparison: uiState.showComparison,
+      },
+      designSystem: {
+        name: BRAND.name,
+        componentCount: fragments.length,
+      },
+    });
+  }, [urlState, uiState, viewSettings, resolvedTheme, fragments, activeVariantIndex]);
+
+  return null;
+}