@fragments-sdk/cli 0.7.15 → 0.7.16

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;
+}

package/src/viewer/webmcp/scan-utils.ts

@@ -0,0 +1,135 @@
+import type { Result } from 'axe-core';
+import type { SerializedViolation } from '../types/a11y.js';
+
+// Cache the axe-core module
+let axeModule: typeof import('axe-core') | null = null;
+
+export interface ScanResult {
+  violations: SerializedViolation[];
+  passes: number;
+  incomplete: number;
+  counts: {
+    critical: number;
+    serious: number;
+    moderate: number;
+    minor: number;
+  };
+}
+
+/**
+ * Convert axe-core Result to SerializedViolation
+ */
+export function serializeViolation(result: Result): SerializedViolation {
+  return {
+    id: result.id,
+    impact: result.impact || null,
+    description: result.description,
+    help: result.help,
+    helpUrl: result.helpUrl,
+    tags: result.tags,
+    nodes: result.nodes.map(node => ({
+      html: node.html,
+      target: node.target as string[],
+      failureSummary: node.failureSummary,
+      any: node.any?.map(check => ({
+        id: check.id,
+        data: check.data,
+        relatedNodes: check.relatedNodes?.map(rn => ({
+          html: rn.html,
+          target: rn.target as string[],
+        })),
+        impact: check.impact,
+        message: check.message,
+      })),
+      all: node.all?.map(check => ({
+        id: check.id,
+        data: check.data,
+        relatedNodes: check.relatedNodes?.map(rn => ({
+          html: rn.html,
+          target: rn.target as string[],
+        })),
+        impact: check.impact,
+        message: check.message,
+      })),
+      none: node.none?.map(check => ({
+        id: check.id,
+        data: check.data,
+        relatedNodes: check.relatedNodes?.map(rn => ({
+          html: rn.html,
+          target: rn.target as string[],
+        })),
+        impact: check.impact,
+        message: check.message,
+      })),
+    })),
+  };
+}
+
+/**
+ * Run axe-core scan on a target element
+ */
+export async function runAxeScan(targetSelector: string): Promise<ScanResult | null> {
+  // Load axe-core if not cached
+  if (!axeModule) {
+    axeModule = await import('axe-core');
+  }
+  // Handle both ESM default export and CommonJS module
+  const axe = (axeModule as { default?: typeof import('axe-core') }).default || axeModule;
+
+  const target = document.querySelector(targetSelector);
+  if (!target) {
+    console.warn(`[A11y] Target element not found: ${targetSelector}`);
+    return null;
+  }
+
+  // Configure axe-core
+  axe.configure({
+    rules: [
+      { id: 'color-contrast', enabled: true },
+      { id: 'image-alt', enabled: true },
+      { id: 'button-name', enabled: true },
+      { id: 'link-name', enabled: true },
+      { id: 'label', enabled: true },
+      { id: 'aria-valid-attr', enabled: true },
+      { id: 'aria-valid-attr-value', enabled: true },
+    ],
+  });
+
+  // Run the scan
+  const results = await axe.run(target as HTMLElement, {
+    resultTypes: ['violations', 'passes', 'incomplete', 'inapplicable'],
+  });
+
+  // Count violations by severity
+  const counts = {
+    critical: 0,
+    serious: 0,
+    moderate: 0,
+    minor: 0,
+  };
+
+  for (const violation of results.violations) {
+    switch (violation.impact) {
+      case 'critical':
+        counts.critical++;
+        break;
+      case 'serious':
+        counts.serious++;
+        break;
+      case 'moderate':
+        counts.moderate++;
+        break;
+      case 'minor':
+      default:
+        counts.minor++;
+        break;
+    }
+  }
+
+  return {
+    violations: results.violations.map(serializeViolation),
+    passes: results.passes.length,
+    incomplete: results.incomplete.length,
+    counts,
+  };
+}

package/src/viewer/webmcp/use-tool-analytics.ts

@@ -0,0 +1,69 @@
+import { useEffect, useRef, useState, useCallback } from 'react';
+import { useWebMCPContext } from '@fragments-sdk/webmcp/react';
+import type { ToolCallEvent } from '@fragments-sdk/webmcp';
+import { ToolAnalyticsCollector } from './analytics.js';
+import { createPostHogBridge } from './posthog-bridge.js';
+
+interface UseToolAnalyticsResult {
+  collector: ToolAnalyticsCollector;
+  summary: ReturnType<ToolAnalyticsCollector['toSummary']> | null;
+  refreshSummary: () => void;
+}
+
+export function useToolAnalytics(): UseToolAnalyticsResult {
+  const { shimRegistry } = useWebMCPContext();
+  const collectorRef = useRef(new ToolAnalyticsCollector());
+  const [summary, setSummary] = useState<ReturnType<ToolAnalyticsCollector['toSummary']> | null>(null);
+
+  const refreshSummary = useCallback(() => {
+    setSummary(collectorRef.current.toSummary());
+  }, []);
+
+  useEffect(() => {
+    if (!shimRegistry) return;
+
+    const posthog = (window as any).posthog as { capture(event: string, properties?: Record<string, unknown>): void } | undefined;
+    const bridge = posthog
+      ? createPostHogBridge(posthog, collectorRef.current)
+      : null;
+
+    const onToolCall = (event: ToolCallEvent) => {
+      collectorRef.current.record(event);
+      bridge?.onToolCall(event);
+      // Auto-refresh summary every 5 calls
+      const total = collectorRef.current.toSummary().totalCalls;
+      if (total % 5 === 0) {
+        setSummary(collectorRef.current.toSummary());
+      }
+    };
+
+    shimRegistry.addEventListener('toolcall', onToolCall);
+
+    // Fire session summary on page unload
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === 'hidden') {
+        bridge?.onSessionEnd();
+      }
+    };
+
+    const handleBeforeUnload = () => {
+      bridge?.flush();
+    };
+
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+    window.addEventListener('beforeunload', handleBeforeUnload);
+
+    return () => {
+      shimRegistry.removeEventListener('toolcall', onToolCall);
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
+      window.removeEventListener('beforeunload', handleBeforeUnload);
+      bridge?.onSessionEnd();
+    };
+  }, [shimRegistry]);
+
+  return {
+    collector: collectorRef.current,
+    summary,
+    refreshSummary,
+  };
+}

package/src/viewer/webmcp/viewer-state.ts

@@ -0,0 +1,45 @@
+export interface ViewerState {
+  currentComponent: string | null;
+  currentVariant: string | null;
+  variantIndex: number;
+  totalVariants: number;
+  viewport: string;
+  zoom: number;
+  theme: string;
+  panels: {
+    activePanel: string;
+    panelOpen: boolean;
+  };
+  viewMode: {
+    matrixView: boolean;
+    multiViewport: boolean;
+    comparison: boolean;
+  };
+  designSystem: {
+    name: string;
+    componentCount: number;
+  };
+}
+
+const DEFAULT_STATE: ViewerState = {
+  currentComponent: null,
+  currentVariant: null,
+  variantIndex: 0,
+  totalVariants: 0,
+  viewport: 'responsive',
+  zoom: 100,
+  theme: 'light',
+  panels: { activePanel: 'code', panelOpen: true },
+  viewMode: { matrixView: false, multiViewport: false, comparison: false },
+  designSystem: { name: 'Fragments', componentCount: 0 },
+};
+
+let currentState: ViewerState = { ...DEFAULT_STATE };
+
+export function setViewerState(state: Partial<ViewerState>): void {
+  currentState = { ...currentState, ...state };
+}
+
+export function getViewerState(): ViewerState {
+  return currentState;
+}