@fragments-sdk/cli 0.7.14 → 0.7.16

package/src/viewer/vite-plugin.ts

@@ -24,6 +24,7 @@ import {
   findStorybookDir,
   findPreviewConfigPath,
   generatePreviewModule,
+  parseFragmentFile,
 } from "../core/node.js";
 import svgr from "vite-plugin-svgr";
 import {
@@ -927,6 +928,24 @@ export function fragmentsPlugin(options: FragmentsPluginOptions): Plugin[] {
           return;
         }
 
+        // Handle /fragments/compiled.json endpoint for WebMCP integration
+        if (req.url === "/fragments/compiled.json") {
+          try {
+            const { join } = await import("node:path");
+            const fragmentsJsonPath = join(projectRoot, BRAND.outFile);
+            const content = await readFile(fragmentsJsonPath, "utf-8");
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(content);
+          } catch (error) {
+            console.warn(`[${BRAND.name}] Failed to serve compiled.json:`, error);
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+              error: `${BRAND.outFile} not found. Run '${BRAND.cliCommand} build' first.`,
+            }));
+          }
+          return;
+        }
+
         // Handle /fragments/context endpoint for AI context generation
         if (req.url?.startsWith("/fragments/context")) {
           try {
@@ -1617,6 +1636,33 @@ async function generateFragmentsModule(
   config: FragmentsConfig,
   previewConfigPath: string | null
 ): Promise<string> {
+  const authoredVariantCodeCache = new Map<string, Record<string, string>>();
+
+  async function loadAuthoredVariantCode(fragmentFilePath: string): Promise<Record<string, string>> {
+    if (authoredVariantCodeCache.has(fragmentFilePath)) {
+      return authoredVariantCodeCache.get(fragmentFilePath)!;
+    }
+
+    try {
+      const source = await readFile(fragmentFilePath, "utf-8");
+      const parsed = parseFragmentFile(source, fragmentFilePath);
+      const variantCodeByName: Record<string, string> = {};
+
+      for (const variant of parsed.variants) {
+        if (typeof variant.code !== "string") continue;
+        const normalized = variant.code.trim();
+        if (normalized.length === 0) continue;
+        variantCodeByName[variant.name] = normalized;
+      }
+
+      authoredVariantCodeCache.set(fragmentFilePath, variantCodeByName);
+      return variantCodeByName;
+    } catch {
+      authoredVariantCodeCache.set(fragmentFilePath, {});
+      return {};
+    }
+  }
+
   // Group files by base component path to identify pairs
   const filesByBasePath = new Map<string, {
     storyFile?: { absolutePath: string; relativePath: string };
@@ -1653,6 +1699,14 @@ async function generateFragmentsModule(
         ? files.fragmentFile.absolutePath
         : null;
 
+      const codeSourceFile = files.fragmentFile && files.fragmentFile.absolutePath
+        ? files.fragmentFile.absolutePath
+        : (!isStory ? primaryFile.absolutePath : null);
+
+      const authoredVariantCode = codeSourceFile
+        ? await loadAuthoredVariantCode(codeSourceFile)
+        : {};
+
       // Extract component name from file path
       const componentName = extractComponentName(primaryFile.relativePath);
 
@@ -1666,7 +1720,8 @@ async function generateFragmentsModule(
     componentName: ${JSON.stringify(componentName)},
     dependencies: ${JSON.stringify(dependencies)},
     loader: () => import("${primaryFile.absolutePath}"),
-    metadataLoader: ${metadataPath ? `() => import("${metadataPath}")` : 'null'}
+    metadataLoader: ${metadataPath ? `() => import("${metadataPath}")` : 'null'},
+    authoredVariantCode: ${JSON.stringify(authoredVariantCode)}
   }`;
     })
   );
@@ -1743,6 +1798,20 @@ function mergeMetadata(fragment, metadataModule) {
   return fragment;
 }
 
+function mergeAuthoredVariantCode(fragment, authoredVariantCode) {
+  if (!fragment?.variants || !authoredVariantCode) return fragment;
+
+  for (const variant of fragment.variants) {
+    if (!variant || variant.code) continue;
+    const code = authoredVariantCode[variant.name];
+    if (typeof code === "string" && code.trim().length > 0) {
+      variant.code = code;
+    }
+  }
+
+  return fragment;
+}
+
 // Load all fragments (for initial render)
 // Gracefully handles individual failures - one bad story won't break all fragments
 export async function loadAllFragments() {
@@ -1780,6 +1849,8 @@ export async function loadAllFragments() {
           }
         }
 
+        fragment = mergeAuthoredVariantCode(fragment, loader.authoredVariantCode);
+
         loadedFragments.set(loader.path, fragment);
         return { path: loader.path, fragment };
       } catch (error) {
@@ -1837,6 +1908,10 @@ export async function loadFragment(path) {
     }
   }
 
+  if (fragment) {
+    fragment = mergeAuthoredVariantCode(fragment, loader.authoredVariantCode);
+  }
+
   if (fragment) {
     loadedFragments.set(path, fragment);
   }

package/src/viewer/webmcp/__tests__/analytics.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest';
+import { ToolAnalyticsCollector } from '../analytics.js';
+import type { ToolCallEvent } from '@fragments-sdk/webmcp';
+
+function createEvent(overrides: Partial<ToolCallEvent> = {}): ToolCallEvent {
+  return {
+    toolName: 'fragments_discover',
+    input: {},
+    output: {},
+    error: null,
+    durationMs: 50,
+    timestamp: Date.now(),
+    ...overrides,
+  };
+}
+
+describe('ToolAnalyticsCollector', () => {
+  it('records events and computes summary', () => {
+    const collector = new ToolAnalyticsCollector();
+    collector.record(createEvent({ toolName: 'fragments_discover', durationMs: 10 }));
+    collector.record(createEvent({ toolName: 'fragments_discover', durationMs: 20 }));
+    collector.record(createEvent({ toolName: 'fragments_inspect', durationMs: 30 }));
+
+    const summary = collector.toSummary();
+    expect(summary.totalCalls).toBe(3);
+    expect(summary.uniqueTools).toBe(2);
+    expect(summary.toolStats.fragments_discover.callCount).toBe(2);
+    expect(summary.toolStats.fragments_discover.avgDuration).toBe(15);
+    expect(summary.toolStats.fragments_inspect.callCount).toBe(1);
+  });
+
+  it('tracks error rate', () => {
+    const collector = new ToolAnalyticsCollector();
+    collector.record(createEvent({ error: null }));
+    collector.record(createEvent({ error: 'fail' }));
+
+    const summary = collector.toSummary();
+    expect(summary.errorRate).toBe(0.5);
+  });
+
+  it('detects common flows', () => {
+    const collector = new ToolAnalyticsCollector();
+    const base = Date.now();
+
+    // Create a repeated flow: discover -> inspect -> discover -> inspect
+    collector.record(createEvent({ toolName: 'fragments_discover', timestamp: base }));
+    collector.record(createEvent({ toolName: 'fragments_inspect', timestamp: base + 100 }));
+    collector.record(createEvent({ toolName: 'fragments_discover', timestamp: base + 200 }));
+    collector.record(createEvent({ toolName: 'fragments_inspect', timestamp: base + 300 }));
+
+    const summary = collector.toSummary();
+    expect(summary.commonFlows.length).toBeGreaterThan(0);
+    expect(summary.commonFlows[0].sequence).toEqual(['fragments_discover', 'fragments_inspect']);
+    expect(summary.commonFlows[0].count).toBe(2);
+  });
+
+  it('splits sessions on 30s gap', () => {
+    const collector = new ToolAnalyticsCollector();
+    const base = Date.now();
+
+    collector.record(createEvent({ toolName: 'a', timestamp: base }));
+    collector.record(createEvent({ toolName: 'b', timestamp: base + 100 }));
+    // 31s gap
+    collector.record(createEvent({ toolName: 'a', timestamp: base + 31_100 }));
+    collector.record(createEvent({ toolName: 'b', timestamp: base + 31_200 }));
+
+    const summary = collector.toSummary();
+    // "a -> b" appears in both sessions
+    const abFlow = summary.commonFlows.find(f =>
+      f.sequence[0] === 'a' && f.sequence[1] === 'b'
+    );
+    expect(abFlow).toBeDefined();
+    expect(abFlow!.count).toBe(2);
+  });
+
+  it('computes percentiles', () => {
+    const collector = new ToolAnalyticsCollector();
+    for (let i = 1; i <= 100; i++) {
+      collector.record(createEvent({ durationMs: i }));
+    }
+
+    const summary = collector.toSummary();
+    const stat = summary.toolStats.fragments_discover;
+    expect(stat.p50).toBeGreaterThanOrEqual(49);
+    expect(stat.p50).toBeLessThanOrEqual(51);
+    expect(stat.p95).toBeGreaterThanOrEqual(94);
+    expect(stat.p95).toBeLessThanOrEqual(96);
+  });
+
+  it('produces PostHog properties', () => {
+    const collector = new ToolAnalyticsCollector();
+    collector.record(createEvent());
+
+    const props = collector.toPostHogProperties();
+    expect(props.webmcp_total_calls).toBe(1);
+    expect(props.webmcp_unique_tools).toBe(1);
+    expect(typeof props.webmcp_tool_breakdown).toBe('string');
+  });
+
+  it('resets state', () => {
+    const collector = new ToolAnalyticsCollector();
+    collector.record(createEvent());
+    collector.reset();
+
+    const summary = collector.toSummary();
+    expect(summary.totalCalls).toBe(0);
+  });
+});

package/src/viewer/webmcp/analytics.ts

@@ -0,0 +1,165 @@
+import type { ToolCallEvent } from '@fragments-sdk/webmcp';
+
+interface ToolStats {
+  callCount: number;
+  totalDuration: number;
+  durations: number[];
+  errorCount: number;
+}
+
+interface ToolFlow {
+  sequence: string[];
+  count: number;
+}
+
+interface AnalyticsSummary {
+  totalCalls: number;
+  uniqueTools: number;
+  sessionDurationMs: number;
+  errorRate: number;
+  toolStats: Record<string, {
+    callCount: number;
+    avgDuration: number;
+    p50: number;
+    p95: number;
+    errorCount: number;
+  }>;
+  commonFlows: ToolFlow[];
+}
+
+const SESSION_GAP_MS = 30_000;
+
+export class ToolAnalyticsCollector {
+  private stats = new Map<string, ToolStats>();
+  private events: ToolCallEvent[] = [];
+  private sessionStart: number | null = null;
+
+  record(event: ToolCallEvent): void {
+    this.events.push(event);
+
+    if (this.sessionStart === null) {
+      this.sessionStart = event.timestamp;
+    }
+
+    const existing = this.stats.get(event.toolName);
+    if (existing) {
+      existing.callCount++;
+      existing.totalDuration += event.durationMs;
+      existing.durations.push(event.durationMs);
+      if (event.error) existing.errorCount++;
+    } else {
+      this.stats.set(event.toolName, {
+        callCount: 1,
+        totalDuration: event.durationMs,
+        durations: [event.durationMs],
+        errorCount: event.error ? 1 : 0,
+      });
+    }
+  }
+
+  toSummary(): AnalyticsSummary {
+    let totalCalls = 0;
+    let totalErrors = 0;
+    const toolStats: AnalyticsSummary['toolStats'] = {};
+
+    for (const [name, stat] of this.stats) {
+      totalCalls += stat.callCount;
+      totalErrors += stat.errorCount;
+
+      const sorted = [...stat.durations].sort((a, b) => a - b);
+      toolStats[name] = {
+        callCount: stat.callCount,
+        avgDuration: Math.round(stat.totalDuration / stat.callCount),
+        p50: percentile(sorted, 50),
+        p95: percentile(sorted, 95),
+        errorCount: stat.errorCount,
+      };
+    }
+
+    const sessionDurationMs = this.sessionStart !== null && this.events.length > 0
+      ? this.events[this.events.length - 1].timestamp - this.sessionStart
+      : 0;
+
+    return {
+      totalCalls,
+      uniqueTools: this.stats.size,
+      sessionDurationMs,
+      errorRate: totalCalls > 0 ? Math.round((totalErrors / totalCalls) * 100) / 100 : 0,
+      toolStats,
+      commonFlows: this.detectFlows(),
+    };
+  }
+
+  toPostHogProperties(): Record<string, unknown> {
+    const summary = this.toSummary();
+    return {
+      webmcp_total_calls: summary.totalCalls,
+      webmcp_unique_tools: summary.uniqueTools,
+      webmcp_session_duration_ms: summary.sessionDurationMs,
+      webmcp_error_rate: summary.errorRate,
+      webmcp_tool_breakdown: JSON.stringify(summary.toolStats),
+      webmcp_common_flows: JSON.stringify(summary.commonFlows),
+    };
+  }
+
+  private detectFlows(): ToolFlow[] {
+    if (this.events.length < 2) return [];
+
+    // Split into sessions (30s gap)
+    const sessions: ToolCallEvent[][] = [];
+    let currentSession: ToolCallEvent[] = [this.events[0]];
+
+    for (let i = 1; i < this.events.length; i++) {
+      if (this.events[i].timestamp - this.events[i - 1].timestamp > SESSION_GAP_MS) {
+        sessions.push(currentSession);
+        currentSession = [];
+      }
+      currentSession.push(this.events[i]);
+    }
+    sessions.push(currentSession);
+
+    // Count 2-grams and 3-grams
+    const flowCounts = new Map<string, number>();
+
+    for (const session of sessions) {
+      const names = session.map(e => e.toolName);
+
+      // 2-grams
+      for (let i = 0; i < names.length - 1; i++) {
+        const key = `${names[i]} → ${names[i + 1]}`;
+        flowCounts.set(key, (flowCounts.get(key) ?? 0) + 1);
+      }
+
+      // 3-grams
+      for (let i = 0; i < names.length - 2; i++) {
+        const key = `${names[i]} → ${names[i + 1]} → ${names[i + 2]}`;
+        flowCounts.set(key, (flowCounts.get(key) ?? 0) + 1);
+      }
+    }
+
+    // Return top flows (count >= 2)
+    return [...flowCounts.entries()]
+      .filter(([, count]) => count >= 2)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 10)
+      .map(([key, count]) => ({
+        sequence: key.split(' → '),
+        count,
+      }));
+  }
+
+  reset(): void {
+    this.stats.clear();
+    this.events = [];
+    this.sessionStart = null;
+  }
+}
+
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const index = (p / 100) * (sorted.length - 1);
+  const lower = Math.floor(index);
+  const upper = Math.ceil(index);
+  if (lower === upper) return sorted[lower];
+  return Math.round(sorted[lower] + (sorted[upper] - sorted[lower]) * (index - lower));
+}

package/src/viewer/webmcp/index.ts

@@ -0,0 +1,3 @@
+export { runAxeScan, serializeViolation, type ScanResult } from './scan-utils.js';
+export { createRuntimeWebMCPTools, type RuntimeToolsOptions } from './runtime-tools.js';
+export { getViewerState, setViewerState, type ViewerState } from './viewer-state.js';

package/src/viewer/webmcp/posthog-bridge.ts

@@ -0,0 +1,39 @@
+import type { ToolCallEvent } from '@fragments-sdk/webmcp';
+import type { ToolAnalyticsCollector } from './analytics.js';
+
+interface PostHogLike {
+  capture(event: string, properties?: Record<string, unknown>): void;
+}
+
+interface PostHogBridge {
+  onToolCall(event: ToolCallEvent): void;
+  onSessionEnd(): void;
+  flush(): void;
+}
+
+export function createPostHogBridge(
+  posthog: PostHogLike,
+  collector: ToolAnalyticsCollector
+): PostHogBridge {
+  return {
+    onToolCall(event: ToolCallEvent): void {
+      posthog.capture('webmcp_tool_call', {
+        tool_name: event.toolName,
+        duration_ms: event.durationMs,
+        success: event.error === null,
+        error: event.error,
+      });
+    },
+
+    onSessionEnd(): void {
+      const props = collector.toPostHogProperties();
+      if ((props.webmcp_total_calls as number) > 0) {
+        posthog.capture('webmcp_session_summary', props);
+      }
+    },
+
+    flush(): void {
+      this.onSessionEnd();
+    },
+  };
+}

package/src/viewer/webmcp/runtime-tools.ts

@@ -0,0 +1,152 @@
+import type { WebMCPTool, InputSchema } from '@fragments-sdk/webmcp';
+import type { CompiledFragmentsFile } from '@fragments-sdk/context/types';
+import { runAxeScan } from './scan-utils.js';
+import { getViewerState } from './viewer-state.js';
+
+export interface RuntimeToolsOptions {
+  compiledData?: CompiledFragmentsFile | null;
+}
+
+export function createRuntimeWebMCPTools(options: RuntimeToolsOptions = {}): WebMCPTool[] {
+  const tools: WebMCPTool[] = [];
+
+  // --- fragments_a11y ---
+  tools.push({
+    name: 'fragments_a11y',
+    description: 'Run an accessibility audit on the currently previewed component. Returns axe-core violations, a WCAG compliance score, and severity counts. Runs directly on the live DOM for accurate results.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        component: { type: 'string', description: 'Component name to audit' },
+        variant: { type: 'string', description: 'Specific variant to audit' },
+        standard: { type: 'string', enum: ['AA', 'AAA'], default: 'AA', description: 'WCAG compliance level' },
+      },
+      required: ['component'],
+    } as InputSchema,
+    annotations: { readOnlyHint: true },
+    execute: async (input) => {
+      const component = input.component as string;
+      const standard = (input.standard as string) || 'AA';
+
+      const result = await runAxeScan('[data-preview-container="true"]');
+      if (!result) {
+        return { error: true, message: 'No preview container found. Navigate to a component first.' };
+      }
+
+      const total = result.passes + result.violations.length + result.incomplete;
+      const wcagScore = total > 0 ? Math.round((result.passes / total) * 100) : 100;
+
+      return {
+        component,
+        wcagScore,
+        standard,
+        violations: result.violations,
+        passCount: result.passes,
+        incompleteCount: result.incomplete,
+        counts: result.counts,
+      };
+    },
+  });
+
+  // --- fragments_theme ---
+  tools.push({
+    name: 'fragments_theme',
+    description: 'Inspect the current runtime theme state. Returns the resolved theme (light/dark), seed configuration values, and computed CSS token values from the live DOM.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        category: { type: 'string', description: 'Filter tokens by category (e.g., "colors", "spacing")' },
+        search: { type: 'string', description: 'Search token names' },
+        includeComputed: { type: 'boolean', default: true, description: 'Include computed CSS values' },
+      },
+    } as InputSchema,
+    annotations: { readOnlyHint: true },
+    execute: async (input) => {
+      const category = input.category as string | undefined;
+      const search = input.search as string | undefined;
+      const includeComputed = input.includeComputed !== false;
+
+      const root = document.documentElement;
+      const computedStyle = getComputedStyle(root);
+
+      // Detect theme
+      const resolvedTheme = root.classList.contains('dark') ? 'dark' : 'light';
+
+      // Read seed values
+      const seed = {
+        brand: computedStyle.getPropertyValue('--fui-seed-brand').trim() || null,
+        neutral: computedStyle.getPropertyValue('--fui-seed-neutral').trim() || null,
+        radius: computedStyle.getPropertyValue('--fui-seed-radius').trim() || null,
+        density: computedStyle.getPropertyValue('--fui-seed-density').trim() || null,
+      };
+
+      // Get tokens from compiled data
+      const compiledData = options.compiledData;
+      const tokenEntries: Array<{ name: string; value: string; computed?: string; category?: string }> = [];
+
+      if (compiledData?.tokens?.categories) {
+        for (const [cat, entries] of Object.entries(compiledData.tokens.categories)) {
+          if (category && cat.toLowerCase() !== category.toLowerCase()) continue;
+
+          for (const token of entries) {
+            if (search && !token.name.toLowerCase().includes(search.toLowerCase())) continue;
+
+            const entry: { name: string; value: string; computed?: string; category?: string } = {
+              name: token.name,
+              value: token.value,
+              category: cat,
+            };
+
+            if (includeComputed) {
+              entry.computed = computedStyle.getPropertyValue(token.name).trim() || token.value;
+            }
+
+            tokenEntries.push(entry);
+          }
+        }
+      }
+
+      return {
+        resolvedTheme,
+        seed,
+        tokens: tokenEntries,
+        tokenCount: tokenEntries.length,
+      };
+    },
+  });
+
+  // --- fragments_context ---
+  tools.push({
+    name: 'fragments_context',
+    description: 'Get information about what the developer is currently viewing in the Fragments dev viewer. Returns the active component, variant, viewport settings, theme, and panel state.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fields: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Specific fields to return (e.g., ["currentComponent", "theme"]). Returns all fields if omitted.',
+        },
+      },
+    } as InputSchema,
+    annotations: { readOnlyHint: true },
+    execute: async (input) => {
+      const state = getViewerState();
+      const fields = input.fields as string[] | undefined;
+
+      if (fields && fields.length > 0) {
+        const filtered: Record<string, unknown> = {};
+        for (const field of fields) {
+          if (field in state) {
+            filtered[field] = state[field as keyof typeof state];
+          }
+        }
+        return filtered;
+      }
+
+      return state;
+    },
+  });
+
+  return tools;
+}