@fragments-sdk/viewer 0.2.1

package/src/utils/contrast.ts

@@ -0,0 +1,246 @@
+/**
+ * Color Contrast Utilities
+ *
+ * Pure TypeScript WCAG 2.1 color contrast math — zero dependencies.
+ * Handles hex (#rgb, #rrggbb), rgb(), rgba(), hsl(), hsla().
+ */
+
+export interface RGB {
+  r: number;
+  g: number;
+  b: number;
+}
+
+/**
+ * Parse a CSS color string into an RGB object.
+ * Supports: #rgb, #rrggbb, rgb(), rgba(), hsl(), hsla().
+ */
+export function parseColor(css: string): RGB {
+  const trimmed = css.trim().toLowerCase();
+
+  // Hex: #rgb or #rrggbb
+  const hexMatch = trimmed.match(/^#([0-9a-f]{3,8})$/);
+  if (hexMatch) {
+    const hex = hexMatch[1];
+    if (hex.length === 3) {
+      return {
+        r: parseInt(hex[0] + hex[0], 16),
+        g: parseInt(hex[1] + hex[1], 16),
+        b: parseInt(hex[2] + hex[2], 16),
+      };
+    }
+    if (hex.length === 6 || hex.length === 8) {
+      return {
+        r: parseInt(hex.substring(0, 2), 16),
+        g: parseInt(hex.substring(2, 4), 16),
+        b: parseInt(hex.substring(4, 6), 16),
+      };
+    }
+  }
+
+  // rgb() / rgba()
+  const rgbMatch = trimmed.match(
+    /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/
+  );
+  if (rgbMatch) {
+    return {
+      r: parseInt(rgbMatch[1], 10),
+      g: parseInt(rgbMatch[2], 10),
+      b: parseInt(rgbMatch[3], 10),
+    };
+  }
+
+  // hsl() / hsla()
+  const hslMatch = trimmed.match(
+    /^hsla?\(\s*([\d.]+)\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%/
+  );
+  if (hslMatch) {
+    return hslToRgb(
+      parseFloat(hslMatch[1]),
+      parseFloat(hslMatch[2]),
+      parseFloat(hslMatch[3])
+    );
+  }
+
+  throw new Error(`Cannot parse color: "${css}"`);
+}
+
+/**
+ * Convert HSL values to RGB.
+ */
+function hslToRgb(h: number, s: number, l: number): RGB {
+  const sNorm = s / 100;
+  const lNorm = l / 100;
+
+  const c = (1 - Math.abs(2 * lNorm - 1)) * sNorm;
+  const hPrime = (((h % 360) + 360) % 360) / 60;
+  const x = c * (1 - Math.abs((hPrime % 2) - 1));
+  const m = lNorm - c / 2;
+
+  let r1 = 0, g1 = 0, b1 = 0;
+  if (hPrime < 1)      { r1 = c; g1 = x; }
+  else if (hPrime < 2) { r1 = x; g1 = c; }
+  else if (hPrime < 3) { g1 = c; b1 = x; }
+  else if (hPrime < 4) { g1 = x; b1 = c; }
+  else if (hPrime < 5) { r1 = x; b1 = c; }
+  else                 { r1 = c; b1 = x; }
+
+  return {
+    r: Math.round((r1 + m) * 255),
+    g: Math.round((g1 + m) * 255),
+    b: Math.round((b1 + m) * 255),
+  };
+}
+
+/**
+ * Linearize an sRGB channel value (0-255) for luminance calculation.
+ */
+function linearize(channel: number): number {
+  const srgb = channel / 255;
+  return srgb <= 0.04045
+    ? srgb / 12.92
+    : Math.pow((srgb + 0.055) / 1.055, 2.4);
+}
+
+/**
+ * Calculate relative luminance per WCAG 2.1.
+ * @see https://www.w3.org/WAI/WCAG21/Techniques/general/G17#procedure
+ */
+export function relativeLuminance(r: number, g: number, b: number): number {
+  return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b);
+}
+
+/**
+ * Calculate the contrast ratio between two colors.
+ * Returns a value >= 1 (lighter / darker).
+ */
+export function contrastRatio(fg: RGB, bg: RGB): number {
+  const l1 = relativeLuminance(fg.r, fg.g, fg.b);
+  const l2 = relativeLuminance(bg.r, bg.g, bg.b);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Check whether a contrast ratio meets WCAG 2.1 AA.
+ * Normal text: 4.5:1. Large text (18pt / 14pt bold): 3:1.
+ */
+export function meetsAA(ratio: number, isLargeText = false): boolean {
+  return ratio >= (isLargeText ? 3.0 : 4.5);
+}
+
+/**
+ * Check whether a contrast ratio meets WCAG 2.1 AAA.
+ * Normal text: 7:1. Large text: 4.5:1.
+ */
+export function meetsAAA(ratio: number, isLargeText = false): boolean {
+  return ratio >= (isLargeText ? 4.5 : 7.0);
+}
+
+/**
+ * Convert an RGB object back to a hex string.
+ */
+export function rgbToHex(r: number, g: number, b: number): string {
+  const clamp = (v: number) => Math.max(0, Math.min(255, Math.round(v)));
+  const hex = (v: number) => clamp(v).toString(16).padStart(2, '0');
+  return `#${hex(r)}${hex(g)}${hex(b)}`;
+}
+
+/**
+ * Suggest a fixed foreground color that meets the target contrast ratio
+ * against the given background.
+ *
+ * Uses binary search: hold bg fixed, adjust fg luminance until the target
+ * ratio is met. Returns the adjusted foreground hex color.
+ */
+export function suggestFix(
+  fg: RGB,
+  bg: RGB,
+  targetRatio: number
+): string {
+  const bgLum = relativeLuminance(bg.r, bg.g, bg.b);
+  const fgLum = relativeLuminance(fg.r, fg.g, fg.b);
+
+  // Determine whether we need to go darker or lighter
+  const fgIsLighter = fgLum >= bgLum;
+
+  // Target luminance for the foreground to meet the required ratio
+  let targetLum: number;
+  if (fgIsLighter) {
+    // fg is lighter: ratio = (fgLum + 0.05) / (bgLum + 0.05)
+    // Try making fg lighter first
+    targetLum = targetRatio * (bgLum + 0.05) - 0.05;
+    if (targetLum > 1) {
+      // Can't go lighter enough — go darker instead
+      targetLum = (bgLum + 0.05) / targetRatio - 0.05;
+    }
+  } else {
+    // fg is darker: ratio = (bgLum + 0.05) / (fgLum + 0.05)
+    // Try making fg darker first
+    targetLum = (bgLum + 0.05) / targetRatio - 0.05;
+    if (targetLum < 0) {
+      // Can't go darker enough — go lighter instead
+      targetLum = targetRatio * (bgLum + 0.05) - 0.05;
+    }
+  }
+
+  targetLum = Math.max(0, Math.min(1, targetLum));
+
+  // Scale the fg color channels proportionally to reach target luminance
+  return adjustToLuminance(fg, targetLum);
+}
+
+/**
+ * Adjust an RGB color to reach the target relative luminance.
+ * Scales channels proportionally, clamping at boundaries.
+ */
+function adjustToLuminance(color: RGB, targetLum: number): string {
+  const currentLum = relativeLuminance(color.r, color.g, color.b);
+
+  if (currentLum === 0) {
+    // Pure black — can only go to grayscale
+    // Solve: 0.2126*L + 0.7152*L + 0.0722*L = targetLum where L = linearize(v)
+    // => L = targetLum, v = delinearize(targetLum)
+    const v = delinearize(targetLum);
+    const channel = Math.round(v * 255);
+    return rgbToHex(channel, channel, channel);
+  }
+
+  // Binary search for the right scale factor
+  let lo = 0;
+  let hi = 10;
+  let bestHex = rgbToHex(color.r, color.g, color.b);
+  let bestDiff = Infinity;
+
+  for (let i = 0; i < 40; i++) {
+    const mid = (lo + hi) / 2;
+    const r = Math.max(0, Math.min(255, Math.round(color.r * mid)));
+    const g = Math.max(0, Math.min(255, Math.round(color.g * mid)));
+    const b = Math.max(0, Math.min(255, Math.round(color.b * mid)));
+    const lum = relativeLuminance(r, g, b);
+    const diff = Math.abs(lum - targetLum);
+
+    if (diff < bestDiff) {
+      bestDiff = diff;
+      bestHex = rgbToHex(r, g, b);
+    }
+
+    if (lum < targetLum) {
+      lo = mid;
+    } else {
+      hi = mid;
+    }
+  }
+
+  return bestHex;
+}
+
+/**
+ * Reverse sRGB linearization: linear -> sRGB channel (0-1 range).
+ */
+function delinearize(linear: number): number {
+  return linear <= 0.0031308
+    ? linear * 12.92
+    : 1.055 * Math.pow(linear, 1 / 2.4) - 0.055;
+}

package/src/utils/detectRelationships.ts

@@ -0,0 +1,256 @@
+// @ts-nocheck
+/**
+ * Auto-detect component relationships from rendered elements
+ *
+ * Analyzes React elements to discover:
+ * - Composition relationships (components used within other components)
+ * - Sibling relationships (components in the same category)
+ * - Common usage patterns
+ */
+
+import { isValidElement, type ReactNode, type ReactElement, Children } from "react";
+import type { FragmentDefinition, ComponentRelation, RelationshipType } from '@fragments-sdk/core';
+
+interface DetectedRelationship {
+  component: string;
+  relationship: RelationshipType;
+  note: string;
+  confidence: number; // 0-1, how confident we are in this relationship
+}
+
+// Cache for relationship detection to avoid repeated expensive render() calls
+const relationshipCache = new Map<string, { timestamp: number; relationships: DetectedRelationship[] }>();
+const CACHE_TTL = 60000; // 1 minute cache
+
+// Cache for known component names (expensive to recompute for 98+ components)
+let knownComponentsCache: { count: number; set: Set<string> } | null = null;
+
+/**
+ * Extract component name from a React element
+ */
+function getComponentName(element: ReactElement): string | null {
+  const type = element.type;
+
+  if (typeof type === "string") {
+    // HTML element, not a component
+    return null;
+  }
+
+  if (typeof type === "function") {
+    // Function component or class component
+    return type.displayName || type.name || null;
+  }
+
+  if (typeof type === "object" && type !== null) {
+    // Could be forwardRef, memo, etc.
+    const innerType = (type as { $$typeof?: symbol; type?: unknown; render?: unknown })?.type ||
+                      (type as { render?: unknown })?.render;
+    if (typeof innerType === "function") {
+      return (innerType as { displayName?: string; name?: string }).displayName ||
+             (innerType as { name?: string }).name || null;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Recursively collect all component names from an element tree
+ */
+function collectComponentNames(
+  element: ReactNode,
+  collected: Set<string> = new Set()
+): Set<string> {
+  if (!isValidElement(element)) {
+    return collected;
+  }
+
+  const name = getComponentName(element as ReactElement);
+  if (name) {
+    collected.add(name);
+  }
+
+  // Traverse children
+  const children = (element.props as { children?: ReactNode })?.children;
+  if (children) {
+    Children.forEach(children, (child) => {
+      collectComponentNames(child, collected);
+    });
+  }
+
+  return collected;
+}
+
+/**
+ * Get cached set of known component names
+ */
+function getKnownComponents(
+  allFragments: Array<{ path: string; fragment: FragmentDefinition }>
+): Set<string> {
+  // Invalidate cache if fragment count changed
+  if (!knownComponentsCache || knownComponentsCache.count !== allFragments.length) {
+    knownComponentsCache = {
+      count: allFragments.length,
+      set: new Set(allFragments.map(s => s.fragment.meta.name)),
+    };
+  }
+  return knownComponentsCache.set;
+}
+
+/**
+ * Detect composition relationships from a fragment's variants
+ */
+export function detectCompositionRelationships(
+  fragment: FragmentDefinition,
+  allFragments: Array<{ path: string; fragment: FragmentDefinition }>
+): DetectedRelationship[] {
+  const relationships: DetectedRelationship[] = [];
+  const componentName = fragment.meta.name;
+  const knownComponents = getKnownComponents(allFragments);
+  const usedComponents = new Set<string>();
+
+  // Analyze each variant's render output
+  for (const variant of fragment.variants || []) {
+    try {
+      const rendered = variant.render();
+      const componentNames = collectComponentNames(rendered);
+
+      for (const name of componentNames) {
+        if (name !== componentName && knownComponents.has(name)) {
+          usedComponents.add(name);
+        }
+      }
+    } catch {
+      // Render might fail, skip this variant
+    }
+  }
+
+  // Create composition relationships for used components
+  for (const usedComponent of usedComponents) {
+    relationships.push({
+      component: usedComponent,
+      relationship: "composition",
+      note: `Used within ${componentName} variants`,
+      confidence: 0.8,
+    });
+  }
+
+  return relationships;
+}
+
+/**
+ * Detect sibling relationships based on semantic connections.
+ *
+ * NOTE: Category-based sibling detection was removed because it creates
+ * meaningless relationships (e.g., Card → Separator just because both are "layout").
+ *
+ * True sibling relationships should be defined manually in the fragment definition
+ * based on actual use cases (e.g., Table uses Badge for status columns).
+ *
+ * This function now only detects siblings when:
+ * - There's a bidirectional manual relationship (A references B AND B references A)
+ * - Components share overlapping variant patterns (future enhancement)
+ */
+export function detectSiblingRelationships(
+  _fragment: FragmentDefinition,
+  _allFragments: Array<{ path: string; fragment: FragmentDefinition }>
+): DetectedRelationship[] {
+  // Disabled: Category-based sibling detection creates noise
+  // Meaningful sibling relationships should be defined manually
+  return [];
+}
+
+/**
+ * Detect alternative relationships.
+ *
+ * NOTE: Pattern-based alternative detection was removed because it creates
+ * weak relationships based on naming conventions rather than actual use cases.
+ *
+ * True alternative relationships should be defined manually in the fragment
+ * definition based on actual decision criteria (e.g., "Use IconButton instead
+ * of Button when only an icon is needed").
+ *
+ * A better approach would analyze the `whenNot` guidelines for semantic matches,
+ * but that requires NLP/semantic analysis which is out of scope.
+ */
+export function detectAlternativeRelationships(
+  _fragment: FragmentDefinition,
+  _allFragments: Array<{ path: string; fragment: FragmentDefinition }>
+): DetectedRelationship[] {
+  // Disabled: Pattern-based alternative detection is too weak
+  // Meaningful alternatives should be defined manually with clear rationale
+  return [];
+}
+
+/**
+ * Combine all detected relationships and deduplicate
+ * Uses caching to avoid expensive render() calls on subsequent views
+ */
+export function detectAllRelationships(
+  fragment: FragmentDefinition,
+  allFragments: Array<{ path: string; fragment: FragmentDefinition }>
+): DetectedRelationship[] {
+  const cacheKey = fragment.meta.name;
+  const now = Date.now();
+
+  // Check cache first
+  const cached = relationshipCache.get(cacheKey);
+  if (cached && (now - cached.timestamp) < CACHE_TTL) {
+    return cached.relationships;
+  }
+
+  const all = [
+    ...detectCompositionRelationships(fragment, allFragments),
+    ...detectSiblingRelationships(fragment, allFragments),
+    ...detectAlternativeRelationships(fragment, allFragments),
+  ];
+
+  // Deduplicate by component name, keeping highest confidence
+  const byComponent = new Map<string, DetectedRelationship>();
+
+  for (const rel of all) {
+    const existing = byComponent.get(rel.component);
+    if (!existing || rel.confidence > existing.confidence) {
+      byComponent.set(rel.component, rel);
+    }
+  }
+
+  // Sort by confidence descending
+  const result = Array.from(byComponent.values()).sort((a, b) => b.confidence - a.confidence);
+
+  // Cache the result
+  relationshipCache.set(cacheKey, { timestamp: now, relationships: result });
+
+  return result;
+}
+
+/**
+ * Merge manual and auto-detected relationships
+ */
+export function mergeRelationships(
+  manual: ComponentRelation[] | undefined,
+  detected: DetectedRelationship[]
+): Array<ComponentRelation & { isDetected?: boolean; confidence?: number }> {
+  const result: Array<ComponentRelation & { isDetected?: boolean; confidence?: number }> = [];
+  const manualComponents = new Set((manual || []).map(r => r.component));
+
+  // Add manual relationships first
+  for (const rel of manual || []) {
+    result.push({ ...rel, isDetected: false });
+  }
+
+  // Add detected relationships that aren't already defined manually
+  for (const rel of detected) {
+    if (!manualComponents.has(rel.component)) {
+      result.push({
+        component: rel.component,
+        relationship: rel.relationship,
+        note: rel.note,
+        isDetected: true,
+        confidence: rel.confidence,
+      });
+    }
+  }
+
+  return result;
+}

package/src/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);
+  });
+});