@fragments-sdk/cli 0.7.14 → 0.7.16

package/src/viewer/components/WebMCPDevTools.tsx

@@ -0,0 +1,509 @@
+import { useState, useEffect, useCallback, useRef } from "react";
+import {
+  Tabs,
+  Select,
+  Textarea,
+  Button,
+  CodeBlock,
+  Badge,
+  Card,
+  Stack,
+  Box,
+  Text,
+} from "@fragments-sdk/ui";
+import { useWebMCPContext } from "@fragments-sdk/webmcp/react";
+import type {
+  WebMCPTool,
+  JSONSchemaInput,
+  ToolCallEvent,
+} from "@fragments-sdk/webmcp";
+import { SPEC_VERSION } from "@fragments-sdk/webmcp";
+import { useToolAnalytics } from "../webmcp/use-tool-analytics.js";
+
+function generateInputSkeleton(tool: WebMCPTool): string {
+  const schema = tool.inputSchema as JSONSchemaInput | undefined;
+  if (!schema?.properties) return "{}";
+  const obj: Record<string, unknown> = {};
+  for (const [key, prop] of Object.entries(schema.properties)) {
+    if (prop.default !== undefined) obj[key] = prop.default;
+    else if (prop.enum?.length) obj[key] = prop.enum[0];
+    else if (prop.type === "string") obj[key] = "";
+    else if (prop.type === "number" || prop.type === "integer") obj[key] = 0;
+    else if (prop.type === "boolean") obj[key] = false;
+    else if (prop.type === "array") obj[key] = [];
+    else obj[key] = null;
+  }
+  return JSON.stringify(obj, null, 2);
+}
+
+function formatTimestamp(ts: number): string {
+  return new Date(ts).toLocaleTimeString();
+}
+
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${(ms / 60_000).toFixed(1)}m`;
+}
+
+const MAX_ACTIVITY_ENTRIES = 50;
+
+export function WebMCPDevTools() {
+  const { shimRegistry, isShim } = useWebMCPContext();
+  const { summary, refreshSummary } = useToolAnalytics();
+  const [tools, setTools] = useState<WebMCPTool[]>([]);
+  const [selectedTool, setSelectedTool] = useState<string>("");
+  const [inputJson, setInputJson] = useState("{}");
+  const [executing, setExecuting] = useState(false);
+  const [result, setResult] = useState<{ type: "success" | "error"; data: string } | null>(null);
+  const [activity, setActivity] = useState<ToolCallEvent[]>([]);
+  const [expandedEntry, setExpandedEntry] = useState<number | null>(null);
+  const activityRef = useRef(activity);
+  activityRef.current = activity;
+
+  // Sync tools from registry
+  useEffect(() => {
+    if (!shimRegistry) return;
+
+    const update = () => {
+      setTools(Array.from(shimRegistry.tools.values()));
+    };
+    update();
+
+    shimRegistry.addEventListener("toolchange", update);
+    return () => shimRegistry.removeEventListener("toolchange", update);
+  }, [shimRegistry]);
+
+  // Subscribe to toolcall events
+  useEffect(() => {
+    if (!shimRegistry) return;
+
+    const onToolCall = (event: ToolCallEvent) => {
+      setActivity((prev) => [event, ...prev].slice(0, MAX_ACTIVITY_ENTRIES));
+    };
+
+    shimRegistry.addEventListener("toolcall", onToolCall);
+    return () => shimRegistry.removeEventListener("toolcall", onToolCall);
+  }, [shimRegistry]);
+
+  // Update input skeleton when tool selection changes
+  useEffect(() => {
+    if (!selectedTool) return;
+    const tool = tools.find((t) => t.name === selectedTool);
+    if (tool) {
+      setInputJson(generateInputSkeleton(tool));
+      setResult(null);
+    }
+  }, [selectedTool, tools]);
+
+  // Auto-select first tool
+  useEffect(() => {
+    if (tools.length > 0 && !selectedTool) {
+      setSelectedTool(tools[0].name);
+    }
+  }, [tools, selectedTool]);
+
+  const handleExecute = useCallback(async () => {
+    const tool = tools.find((t) => t.name === selectedTool);
+    if (!tool) return;
+
+    setExecuting(true);
+    setResult(null);
+
+    try {
+      const input = JSON.parse(inputJson);
+      const output = await tool.execute(input, {} as any);
+      setResult({
+        type: "success",
+        data: JSON.stringify(output, null, 2),
+      });
+    } catch (err) {
+      setResult({
+        type: "error",
+        data: err instanceof Error ? err.message : String(err),
+      });
+    } finally {
+      setExecuting(false);
+    }
+  }, [tools, selectedTool, inputJson]);
+
+  const currentTool = tools.find((t) => t.name === selectedTool);
+  const schema = currentTool?.inputSchema as JSONSchemaInput | undefined;
+
+  return (
+    <Stack direction="column" gap="md" style={{ height: "100%" }}>
+      <Tabs defaultValue="tools">
+        <Tabs.List variant="underline">
+          <Tabs.Tab value="tools">Tools</Tabs.Tab>
+          <Tabs.Tab value="execute">Execute</Tabs.Tab>
+          <Tabs.Tab value="activity">
+            Activity{activity.length > 0 ? ` (${activity.length})` : ""}
+          </Tabs.Tab>
+          <Tabs.Tab value="analytics">Analytics</Tabs.Tab>
+        </Tabs.List>
+
+        {/* Tab 1: Tool Catalog */}
+        <Tabs.Panel value="tools">
+          <Stack direction="column" gap="md" style={{ paddingTop: "12px" }}>
+            {tools.length === 0 ? (
+              <Text color="secondary">No tools registered yet.</Text>
+            ) : (
+              <>
+                <Select
+                  value={selectedTool}
+                  onValueChange={setSelectedTool}
+                  placeholder="Select a tool"
+                >
+                  <Select.Trigger />
+                  <Select.Content>
+                    {tools.map((tool) => (
+                      <Select.Item key={tool.name} value={tool.name}>
+                        {tool.name}
+                      </Select.Item>
+                    ))}
+                  </Select.Content>
+                </Select>
+
+                {currentTool && (
+                  <Card variant="outlined">
+                    <Card.Body>
+                      <Stack direction="column" gap="sm">
+                        <Text weight="semibold">{currentTool.name}</Text>
+                        <Text color="secondary" size="sm">
+                          {currentTool.description}
+                        </Text>
+                        {currentTool.annotations?.readOnlyHint && (
+                          <div>
+                            <Badge variant="info" size="sm">
+                              readOnly
+                            </Badge>
+                          </div>
+                        )}
+
+                        {schema?.properties && (
+                          <Box style={{ marginTop: "8px" }}>
+                            <Text size="xs" weight="semibold" color="secondary" style={{ marginBottom: "4px" }}>
+                              Parameters
+                            </Text>
+                            <Stack direction="column" gap="xs">
+                              {Object.entries(schema.properties).map(
+                                ([name, prop]) => (
+                                  <Box
+                                    key={name}
+                                    style={{
+                                      padding: "6px 8px",
+                                      borderRadius: "var(--radius-sm)",
+                                      backgroundColor: "var(--bg-secondary)",
+                                    }}
+                                  >
+                                    <Stack direction="row" gap="xs" align="center">
+                                      <Text
+                                        size="xs"
+                                        weight="medium"
+                                        style={{ fontFamily: "monospace" }}
+                                      >
+                                        {name}
+                                      </Text>
+                                      <Text size="2xs" color="tertiary">
+                                        {prop.type}
+                                      </Text>
+                                      {schema.required?.includes(name) && (
+                                        <Badge variant="warning" size="sm">
+                                          required
+                                        </Badge>
+                                      )}
+                                    </Stack>
+                                    {prop.description && (
+                                      <Text size="2xs" color="secondary" style={{ marginTop: "2px" }}>
+                                        {prop.description}
+                                      </Text>
+                                    )}
+                                    {prop.enum && (
+                                      <Text size="2xs" color="tertiary" style={{ marginTop: "2px", fontFamily: "monospace" }}>
+                                        enum: {prop.enum.join(" | ")}
+                                      </Text>
+                                    )}
+                                    {prop.default !== undefined && (
+                                      <Text size="2xs" color="tertiary" style={{ marginTop: "2px" }}>
+                                        default: {JSON.stringify(prop.default)}
+                                      </Text>
+                                    )}
+                                  </Box>
+                                )
+                              )}
+                            </Stack>
+                          </Box>
+                        )}
+                      </Stack>
+                    </Card.Body>
+                  </Card>
+                )}
+              </>
+            )}
+          </Stack>
+        </Tabs.Panel>
+
+        {/* Tab 2: Manual Execution */}
+        <Tabs.Panel value="execute">
+          <Stack direction="column" gap="md" style={{ paddingTop: "12px" }}>
+            <Select
+              value={selectedTool}
+              onValueChange={setSelectedTool}
+              placeholder="Select a tool"
+            >
+              <Select.Trigger />
+              <Select.Content>
+                {tools.map((tool) => (
+                  <Select.Item key={tool.name} value={tool.name}>
+                    {tool.name}
+                  </Select.Item>
+                ))}
+              </Select.Content>
+            </Select>
+
+            <Textarea
+              label="Input (JSON)"
+              rows={8}
+              value={inputJson}
+              onChange={setInputJson}
+              resize="vertical"
+              style={{ fontFamily: "monospace", fontSize: "12px" }}
+            />
+
+            <Button
+              variant="primary"
+              onClick={handleExecute}
+              disabled={executing || !selectedTool}
+              data-testid="webmcp-execute-btn"
+            >
+              {executing ? "Executing..." : "Execute"}
+            </Button>
+
+            {result && (
+              <Box style={{ marginTop: "4px" }}>
+                {result.type === "success" ? (
+                  <CodeBlock
+                    code={result.data}
+                    language="json"
+                    maxHeight={300}
+                    wordWrap
+                    showCopy
+                    compact
+                  />
+                ) : (
+                  <Box
+                    style={{
+                      padding: "12px",
+                      borderRadius: "var(--radius-md)",
+                      backgroundColor: "var(--bg-danger, #fef2f2)",
+                    }}
+                  >
+                    <Text size="sm" style={{ color: "var(--color-danger, #dc2626)" }}>
+                      {result.data}
+                    </Text>
+                  </Box>
+                )}
+              </Box>
+            )}
+          </Stack>
+        </Tabs.Panel>
+
+        {/* Tab 3: Activity Log */}
+        <Tabs.Panel value="activity">
+          <Stack direction="column" gap="xs" style={{ paddingTop: "12px" }}>
+            {activity.length === 0 ? (
+              <Text color="secondary" size="sm">
+                No tool calls yet. Execute a tool or wait for an agent to call
+                one.
+              </Text>
+            ) : (
+              activity.map((entry, i) => (
+                <Card
+                  key={`${entry.timestamp}-${i}`}
+                  variant="outlined"
+                  style={{ padding: "8px 12px", cursor: "pointer" }}
+                  onClick={() => setExpandedEntry(expandedEntry === i ? null : i)}
+                >
+                  <Stack direction="row" gap="xs" align="center">
+                    <Badge
+                      size="sm"
+                      variant={entry.error ? "error" : "success"}
+                    >
+                      {entry.toolName}
+                    </Badge>
+                    <Text size="2xs" color="tertiary">
+                      {formatTimestamp(entry.timestamp)}
+                    </Text>
+                    <Text size="2xs" color="secondary">
+                      {entry.durationMs}ms
+                    </Text>
+                  </Stack>
+                  {expandedEntry === i && (
+                    <Stack direction="column" gap="xs" style={{ marginTop: "8px" }}>
+                      <Text size="2xs" weight="semibold" color="secondary">
+                        Input
+                      </Text>
+                      <CodeBlock
+                        code={JSON.stringify(entry.input, null, 2)}
+                        language="json"
+                        compact
+                        maxHeight={150}
+                      />
+                      <Text size="2xs" weight="semibold" color="secondary">
+                        {entry.error ? "Error" : "Output"}
+                      </Text>
+                      <CodeBlock
+                        code={
+                          entry.error
+                            ? entry.error
+                            : JSON.stringify(entry.output, null, 2)
+                        }
+                        language={entry.error ? "plaintext" : "json"}
+                        compact
+                        maxHeight={150}
+                      />
+                    </Stack>
+                  )}
+                </Card>
+              ))
+            )}
+          </Stack>
+        </Tabs.Panel>
+
+        {/* Tab 4: Analytics */}
+        <Tabs.Panel value="analytics">
+          <Stack direction="column" gap="md" style={{ paddingTop: "12px" }}>
+            <Stack direction="row" gap="sm" align="center">
+              <Text weight="semibold" size="sm">Session Analytics</Text>
+              <Button variant="ghost" size="sm" onClick={refreshSummary}>
+                Refresh
+              </Button>
+            </Stack>
+
+            {!summary || summary.totalCalls === 0 ? (
+              <Text color="secondary" size="sm">
+                No tool calls recorded yet. Analytics will appear after tools are used.
+              </Text>
+            ) : (
+              <Stack direction="column" gap="md">
+                {/* Summary Cards */}
+                <Stack direction="row" gap="sm" style={{ flexWrap: 'wrap' }}>
+                  <Card variant="outlined" style={{ flex: '1 1 120px', padding: '12px' }}>
+                    <Card.Body>
+                      <Text size="2xs" color="tertiary">Total Calls</Text>
+                      <Text size="lg" weight="bold">{summary.totalCalls}</Text>
+                    </Card.Body>
+                  </Card>
+                  <Card variant="outlined" style={{ flex: '1 1 120px', padding: '12px' }}>
+                    <Card.Body>
+                      <Text size="2xs" color="tertiary">Unique Tools</Text>
+                      <Text size="lg" weight="bold">{summary.uniqueTools}</Text>
+                    </Card.Body>
+                  </Card>
+                  <Card variant="outlined" style={{ flex: '1 1 120px', padding: '12px' }}>
+                    <Card.Body>
+                      <Text size="2xs" color="tertiary">Error Rate</Text>
+                      <Text size="lg" weight="bold">{(summary.errorRate * 100).toFixed(0)}%</Text>
+                    </Card.Body>
+                  </Card>
+                  <Card variant="outlined" style={{ flex: '1 1 120px', padding: '12px' }}>
+                    <Card.Body>
+                      <Text size="2xs" color="tertiary">Duration</Text>
+                      <Text size="lg" weight="bold">{formatDuration(summary.sessionDurationMs)}</Text>
+                    </Card.Body>
+                  </Card>
+                </Stack>
+
+                {/* Tool Breakdown */}
+                <Box>
+                  <Text size="xs" weight="semibold" color="secondary" style={{ marginBottom: "8px" }}>
+                    Tool Usage
+                  </Text>
+                  <Stack direction="column" gap="xs">
+                    {Object.entries(summary.toolStats)
+                      .sort(([, a], [, b]) => b.callCount - a.callCount)
+                      .map(([name, stat]) => (
+                        <Box
+                          key={name}
+                          style={{
+                            padding: "8px 10px",
+                            borderRadius: "var(--radius-sm)",
+                            backgroundColor: "var(--bg-secondary)",
+                          }}
+                        >
+                          <Stack direction="row" gap="sm" align="center" style={{ justifyContent: "space-between" }}>
+                            <Text size="xs" weight="medium" style={{ fontFamily: "monospace" }}>
+                              {name}
+                            </Text>
+                            <Stack direction="row" gap="xs">
+                              <Badge size="sm" variant="info">{stat.callCount}x</Badge>
+                              <Text size="2xs" color="tertiary">avg {stat.avgDuration}ms</Text>
+                              {stat.errorCount > 0 && (
+                                <Badge size="sm" variant="error">{stat.errorCount} err</Badge>
+                              )}
+                            </Stack>
+                          </Stack>
+                          <Text size="2xs" color="tertiary" style={{ marginTop: "2px" }}>
+                            p50: {stat.p50}ms | p95: {stat.p95}ms
+                          </Text>
+                        </Box>
+                      ))}
+                  </Stack>
+                </Box>
+
+                {/* Common Flows */}
+                {summary.commonFlows.length > 0 && (
+                  <Box>
+                    <Text size="xs" weight="semibold" color="secondary" style={{ marginBottom: "8px" }}>
+                      Common Flows
+                    </Text>
+                    <Stack direction="column" gap="xs">
+                      {summary.commonFlows.map((flow, i) => (
+                        <Box
+                          key={i}
+                          style={{
+                            padding: "6px 8px",
+                            borderRadius: "var(--radius-sm)",
+                            backgroundColor: "var(--bg-secondary)",
+                          }}
+                        >
+                          <Stack direction="row" gap="xs" align="center">
+                            <Text size="2xs" style={{ fontFamily: "monospace" }}>
+                              {flow.sequence.join(' → ')}
+                            </Text>
+                            <Badge size="sm" variant="info">{flow.count}x</Badge>
+                          </Stack>
+                        </Box>
+                      ))}
+                    </Stack>
+                  </Box>
+                )}
+              </Stack>
+            )}
+          </Stack>
+        </Tabs.Panel>
+      </Tabs>
+
+      {/* Protocol Status Footer */}
+      <Box
+        style={{
+          marginTop: "auto",
+          paddingTop: "12px",
+          borderTop: "1px solid var(--border-subtle)",
+        }}
+      >
+        <Stack direction="row" gap="sm" align="center">
+          <Badge variant="success" size="sm" dot>
+            {isShim ? "Connected" : "Native"}
+          </Badge>
+          <Text size="2xs" color="tertiary">
+            W3C Draft
+          </Text>
+          <Text size="2xs" color="tertiary">
+            {tools.length} tool{tools.length !== 1 ? "s" : ""}
+          </Text>
+        </Stack>
+      </Box>
+    </Stack>
+  );
+}

package/src/viewer/components/WebMCPIntegration.tsx

@@ -0,0 +1,47 @@
+import { useEffect, type ReactNode } from "react";
+import { WebMCPProvider, useWebMCPContext } from "@fragments-sdk/webmcp/react";
+import { useFragmentTools } from "@fragments-sdk/webmcp/fragments";
+import { useCompiledFragments } from "../hooks/useCompiledFragments.js";
+import { useToolAnalytics } from "../webmcp/use-tool-analytics.js";
+import { RuntimeToolsRegistrar } from "./RuntimeToolsRegistrar.js";
+
+function FragmentToolsRegistrar() {
+  const { data } = useCompiledFragments();
+  const { shimRegistry } = useWebMCPContext();
+  const { count } = useFragmentTools(data);
+
+  // Expose registry on window for E2E testing (dev-only)
+  useEffect(() => {
+    if (!shimRegistry || typeof window === "undefined") return;
+    (window as any).__WEBMCP_REGISTRY__ = shimRegistry;
+    (window as any).__WEBMCP_TOOL_COUNT__ = shimRegistry.tools.size;
+
+    const onToolChange = () => {
+      (window as any).__WEBMCP_TOOL_COUNT__ = shimRegistry.tools.size;
+    };
+    shimRegistry.addEventListener("toolchange", onToolChange);
+    return () => shimRegistry.removeEventListener("toolchange", onToolChange);
+  }, [shimRegistry]);
+
+  return null;
+}
+
+function AnalyticsWiring() {
+  useToolAnalytics();
+  return null;
+}
+
+interface WebMCPIntegrationProps {
+  children: ReactNode;
+}
+
+export function WebMCPIntegration({ children }: WebMCPIntegrationProps) {
+  return (
+    <WebMCPProvider devShim>
+      <FragmentToolsRegistrar />
+      <RuntimeToolsRegistrar />
+      <AnalyticsWiring />
+      {children}
+    </WebMCPProvider>
+  );
+}

package/src/viewer/components/WebMCPStatusIndicator.tsx

@@ -0,0 +1,60 @@
+import { useState, useEffect } from "react";
+import { useWebMCPContext } from "@fragments-sdk/webmcp/react";
+import { Badge, Drawer } from "@fragments-sdk/ui";
+import { WebMCPDevTools } from "./WebMCPDevTools.js";
+
+export function WebMCPStatusIndicator() {
+  const { shimRegistry, isSupported, isShim } = useWebMCPContext();
+  const [toolCount, setToolCount] = useState(0);
+  const [drawerOpen, setDrawerOpen] = useState(false);
+
+  useEffect(() => {
+    if (!shimRegistry) return;
+
+    const update = () => setToolCount(shimRegistry.tools.size);
+    update();
+
+    shimRegistry.addEventListener("toolchange", update);
+    return () => shimRegistry.removeEventListener("toolchange", update);
+  }, [shimRegistry]);
+
+  if (!isSupported || toolCount === 0) return null;
+
+  return (
+    <>
+      <button
+        onClick={() => setDrawerOpen(true)}
+        title={`WebMCP: ${toolCount} tool${toolCount !== 1 ? "s" : ""} registered`}
+        data-testid="webmcp-status"
+        style={{
+          display: "inline-flex",
+          alignItems: "center",
+          background: "none",
+          border: "none",
+          padding: 0,
+          cursor: "pointer",
+        }}
+      >
+        <Badge variant="success" size="sm" dot>
+          WebMCP {toolCount}
+        </Badge>
+      </button>
+
+      <Drawer open={drawerOpen} onOpenChange={setDrawerOpen} modal={false}>
+        <Drawer.Content side="right" size="lg">
+          <Drawer.Close />
+          <Drawer.Header>
+            <Drawer.Title>WebMCP DevTools</Drawer.Title>
+            <Drawer.Description>
+              {toolCount} tool{toolCount !== 1 ? "s" : ""} registered via{" "}
+              {isShim ? "dev shim" : "native API"}
+            </Drawer.Description>
+          </Drawer.Header>
+          <Drawer.Body>
+            <WebMCPDevTools />
+          </Drawer.Body>
+        </Drawer.Content>
+      </Drawer>
+    </>
+  );
+}

package/src/viewer/entry.tsx

@@ -4,6 +4,7 @@ import { App } from "./components/App.js";
 import { ThemeProvider } from "./components/ThemeProvider.js";
 import { ToastProvider } from "./components/Toast.js";
 import { AppSkeleton } from "./components/SkeletonLoader.js";
+import { WebMCPIntegration } from "./components/WebMCPIntegration.js";
 // Fragments UI globals - base resets (box-sizing, body, scrollbars) + --fui-* CSS variables
 import "@fragments-sdk/ui";
 // Viewer-specific token aliases and utility classes
@@ -149,6 +150,8 @@ type FragmentItem = {
 let fragments: FragmentItem[] = window.__FRAGMENTS__ ?? [];
 let loadError: string | null = window.__FRAGMENTS_ERROR__ ?? null;
 let appRoot: Root | null = null;
+const SKELETON_DELAY_MS = 120;
+const MIN_SKELETON_DISPLAY_MS = 220;
 
 // Filter helper
 function filterValidFragments(items: FragmentItem[]): FragmentItem[] {
@@ -247,9 +250,11 @@ if (rootElement) {
     appRoot?.render(
       <ThemeProvider>
         <ToastProvider position="bottom-right" duration={3000}>
-          <AppErrorBoundary>
-            <App fragments={currentFragments} />
-          </AppErrorBoundary>
+          <WebMCPIntegration>
+            <AppErrorBoundary>
+              <App fragments={currentFragments} />
+            </AppErrorBoundary>
+          </WebMCPIntegration>
         </ToastProvider>
       </ThemeProvider>
     );
@@ -257,11 +262,33 @@ if (rootElement) {
 
   // Show skeleton immediately if no fragments yet
   if (fragments.length === 0 && !loadError) {
-    renderApp(true);
+    const loadStartedAt = Date.now();
+    let skeletonShown = false;
+
+    const skeletonTimer = setTimeout(() => {
+      skeletonShown = true;
+      renderApp(true);
+    }, SKELETON_DELAY_MS);
 
     // Load fragments asynchronously and re-render
     loadFragmentsFromVirtualModule().then(() => {
-      renderApp(false);
+      clearTimeout(skeletonTimer);
+
+      if (!skeletonShown) {
+        renderApp(false);
+        return;
+      }
+
+      const elapsed = Date.now() - loadStartedAt;
+      const remaining = Math.max(MIN_SKELETON_DISPLAY_MS - elapsed, 0);
+      if (remaining === 0) {
+        renderApp(false);
+        return;
+      }
+
+      setTimeout(() => {
+        renderApp(false);
+      }, remaining);
     });
   } else {
     // We have fragments from window, render immediately