npm - @assistant-ui/mcp-docs-server - Versions diffs - 0.1.22 → 0.1.23 - Mend

@assistant-ui/mcp-docs-server 0.1.22 → 0.1.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (74) hide show

package/.docs/organized/code-examples/waterfall.md ADDED Viewed

@@ -0,0 +1,801 @@
+# Example: waterfall
+## app/globals.css
+```css
+@import "tailwindcss";
+:root {
+  --background: #ffffff;
+  --foreground: #171717;
+  --muted-foreground: #737373;
+  --border: #e5e5e5;
+  --accent: #f5f5f5;
+}
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-border: var(--border);
+  --color-accent: var(--accent);
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: #0a0a0a;
+    --foreground: #ededed;
+    --muted-foreground: #a3a3a3;
+    --border: #2e2e2e;
+    --accent: #1a1a1a;
+  }
+}
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: Arial, Helvetica, sans-serif;
+}
+```
+## app/layout.tsx
+```tsx
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import "./globals.css";
+const geistSans = Geist({
+  variable: "--font-geist-sans",
+  subsets: ["latin"],
+});
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+export const metadata: Metadata = {
+  title: "Waterfall Example",
+  description: "Span waterfall visualization with @assistant-ui/react-o11y",
+};
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body
+        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
+      >
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+## app/page.tsx
+```tsx
+import { WaterfallPage } from "@/lib/waterfall-page";
+export default function Home() {
+  return (
+    <div className="min-h-screen bg-background p-8">
+      <div className="mx-auto max-w-6xl">
+        <div className="mb-8">
+          <h1 className="mb-2 font-bold text-4xl text-foreground">
+            Waterfall Timeline
+          </h1>
+          <p className="text-lg text-muted-foreground">
+            Span visualization powered by @assistant-ui/react-o11y
+          </p>
+        </div>
+        <WaterfallPage />
+      </div>
+    </div>
+  );
+}
+```
+## lib/mock-data.ts
+```typescript
+import type { SpanData } from "@assistant-ui/react-o11y";
+const BASE = Date.now() - 5000;
+export const mockSpans: SpanData[] = [
+  {
+    id: "span-1",
+    parentSpanId: null,
+    name: "POST /api/chat",
+    type: "api",
+    status: "completed",
+    startedAt: BASE,
+    endedAt: BASE + 4200,
+    latencyMs: 4200,
+  },
+  {
+    id: "span-2",
+    parentSpanId: "span-1",
+    name: "authenticate",
+    type: "action",
+    status: "completed",
+    startedAt: BASE + 50,
+    endedAt: BASE + 200,
+    latencyMs: 150,
+  },
+  {
+    id: "span-3",
+    parentSpanId: "span-1",
+    name: "agent-pipeline",
+    type: "pipeline",
+    status: "completed",
+    startedAt: BASE + 220,
+    endedAt: BASE + 4100,
+    latencyMs: 3880,
+  },
+  {
+    id: "span-4",
+    parentSpanId: "span-3",
+    name: "retrieve-context",
+    type: "tool",
+    status: "completed",
+    startedAt: BASE + 250,
+    endedAt: BASE + 900,
+    latencyMs: 650,
+  },
+  {
+    id: "span-5",
+    parentSpanId: "span-3",
+    name: "llm-generate",
+    type: "action",
+    status: "completed",
+    startedAt: BASE + 920,
+    endedAt: BASE + 2800,
+    latencyMs: 1880,
+  },
+  {
+    id: "span-6",
+    parentSpanId: "span-3",
+    name: "web-search",
+    type: "tool",
+    status: "completed",
+    startedAt: BASE + 2850,
+    endedAt: BASE + 3500,
+    latencyMs: 650,
+  },
+  {
+    id: "span-7",
+    parentSpanId: "span-3",
+    name: "llm-summarize",
+    type: "action",
+    status: "completed",
+    startedAt: BASE + 3520,
+    endedAt: BASE + 4050,
+    latencyMs: 530,
+  },
+  {
+    id: "span-8",
+    parentSpanId: "span-1",
+    name: "log-response",
+    type: "action",
+    status: "completed",
+    startedAt: BASE + 4110,
+    endedAt: BASE + 4180,
+    latencyMs: 70,
+  },
+  {
+    id: "span-9",
+    parentSpanId: null,
+    name: "POST /api/feedback",
+    type: "api",
+    status: "completed",
+    startedAt: BASE + 4500,
+    endedAt: BASE + 4700,
+    latencyMs: 200,
+  },
+  {
+    id: "span-10",
+    parentSpanId: "span-9",
+    name: "validate-input",
+    type: "action",
+    status: "completed",
+    startedAt: BASE + 4520,
+    endedAt: BASE + 4560,
+    latencyMs: 40,
+  },
+  {
+    id: "span-11",
+    parentSpanId: "span-9",
+    name: "store-feedback",
+    type: "action",
+    status: "failed",
+    startedAt: BASE + 4570,
+    endedAt: BASE + 4680,
+    latencyMs: 110,
+  },
+  {
+    id: "span-12",
+    parentSpanId: null,
+    name: "GET /api/status",
+    type: "api",
+    status: "running",
+    startedAt: BASE + 4800,
+    endedAt: null,
+    latencyMs: null,
+  },
+  {
+    id: "span-13",
+    parentSpanId: "span-12",
+    name: "health-check",
+    type: "flow",
+    status: "running",
+    startedAt: BASE + 4830,
+    endedAt: null,
+    latencyMs: null,
+  },
+  {
+    id: "span-14",
+    parentSpanId: "span-4",
+    name: "vector-search",
+    type: "tool",
+    status: "completed",
+    startedAt: BASE + 280,
+    endedAt: BASE + 700,
+    latencyMs: 420,
+  },
+  {
+    id: "span-15",
+    parentSpanId: "span-4",
+    name: "rerank",
+    type: "action",
+    status: "completed",
+    startedAt: BASE + 710,
+    endedAt: BASE + 880,
+    latencyMs: 170,
+  },
+];
+```
+## lib/waterfall-bar.tsx
+```tsx
+"use client";
+import { useCallback, useEffect, useRef } from "react";
+import { useAuiState } from "@assistant-ui/store";
+import type { SpanItemState } from "@assistant-ui/react-o11y";
+import { useWaterfallLayout } from "./waterfall-timeline";
+const TYPE_COLORS: Record<string, string> = {
+  action: "hsl(221 83% 53%)",
+  api: "hsl(262 83% 58%)",
+  tool: "hsl(142 71% 45%)",
+  flow: "hsl(25 95% 53%)",
+  pipeline: "hsl(340 75% 55%)",
+};
+const FALLBACK_COLOR = "hsl(220 9% 46%)";
+const STATUS_OPACITY: Record<SpanItemState["status"], number> = {
+  running: 0.7,
+  completed: 1,
+  failed: 1,
+  skipped: 0.5,
+};
+export function WaterfallBar() {
+  const { barWidth, timeRange, barHeight } = useWaterfallLayout();
+  const startedAt = useAuiState((s) => s.span.startedAt);
+  const endedAt = useAuiState((s) => s.span.endedAt) as number | null;
+  const status = useAuiState((s) => s.span.status) as SpanItemState["status"];
+  const type = useAuiState((s) => s.span.type);
+  const barRef = useRef<SVGRectElement>(null);
+  const scale = useCallback(
+    (t: number) => {
+      const range = timeRange.max - timeRange.min || 1;
+      return ((t - timeRange.min) / range) * barWidth;
+    },
+    [timeRange, barWidth],
+  );
+  const x = scale(startedAt);
+  useEffect(() => {
+    if (status !== "running") return;
+    let frameId: number;
+    const tick = () => {
+      const width = scale(Date.now()) - x;
+      barRef.current?.setAttribute("width", String(Math.max(0, width)));
+      frameId = requestAnimationFrame(tick);
+    };
+    frameId = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(frameId);
+  }, [status, x, scale]);
+  const rawWidth = endedAt ? scale(endedAt) - x : 0;
+  const width = Math.max(rawWidth, 4);
+  const fill = TYPE_COLORS[type] ?? FALLBACK_COLOR;
+  const opacity = STATUS_OPACITY[status];
+  return (
+    <g>
+      <rect
+        ref={barRef}
+        x={x}
+        y={4}
+        width={width}
+        height={barHeight - 8}
+        rx={3}
+        fill={fill}
+        opacity={opacity}
+        className={status === "running" ? "animate-pulse" : ""}
+      />
+      {status === "failed" && (
+        <rect
+          x={x}
+          y={4}
+          width={width}
+          height={barHeight - 8}
+          rx={3}
+          fill="none"
+          stroke="hsl(0 84% 60%)"
+          strokeWidth={2}
+        />
+      )}
+    </g>
+  );
+}
+```
+## lib/waterfall-page.tsx
+```tsx
+"use client";
+import { useAui, AuiProvider } from "@assistant-ui/store";
+import { SpanResource } from "@assistant-ui/react-o11y";
+import { mockSpans } from "./mock-data";
+import { WaterfallTimeline } from "./waterfall-timeline";
+export function WaterfallPage() {
+  const aui = useAui({
+    span: SpanResource({ spans: mockSpans }),
+  });
+  return (
+    <AuiProvider value={aui}>
+      <WaterfallTimeline />
+    </AuiProvider>
+  );
+}
+```
+## lib/waterfall-row.tsx
+```tsx
+"use client";
+import { SpanPrimitive } from "@assistant-ui/react-o11y";
+import { AuiIf } from "@assistant-ui/store";
+import { WaterfallBar } from "./waterfall-bar";
+import { useWaterfallLayout } from "./waterfall-timeline";
+const LABEL_WIDTH = 200;
+export function WaterfallRow() {
+  const { barWidth, contentWidth, barHeight } = useWaterfallLayout();
+  return (
+    <SpanPrimitive.Root
+      className="group flex cursor-pointer items-center"
+      style={{ width: contentWidth, height: barHeight }}
+    >
+      <SpanPrimitive.Indent
+        baseIndent={8}
+        indentPerLevel={12}
+        className="sticky left-0 z-10 flex shrink-0 items-center gap-1 overflow-hidden border-border border-r bg-background px-2 group-hover:bg-accent/50"
+        style={{ width: LABEL_WIDTH, height: barHeight }}
+      >
+        <AuiIf condition={(s) => s.span.hasChildren}>
+          <SpanPrimitive.CollapseToggle className="flex shrink-0 items-center justify-center rounded p-0.5 text-muted-foreground hover:text-foreground">
+            <svg
+              className="size-3.5 transition-transform data-[collapsed=true]:[-rotate-90]"
+              viewBox="0 0 16 16"
+              fill="currentColor"
+            >
+              <path d="M4 6l4 4 4-4H4z" />
+            </svg>
+          </SpanPrimitive.CollapseToggle>
+        </AuiIf>
+        <AuiIf condition={(s) => !s.span.hasChildren}>
+          <span className="w-4.5 shrink-0" />
+        </AuiIf>
+        <SpanPrimitive.StatusIndicator className="size-1.5 shrink-0 rounded-full bg-current" />
+        <SpanPrimitive.TypeBadge className="shrink-0 rounded border border-border px-1 text-[10px] text-muted-foreground" />
+        <SpanPrimitive.Name className="truncate text-sm" />
+      </SpanPrimitive.Indent>
+      {/* Timeline bar */}
+      <div
+        className="group-hover:bg-accent/30"
+        style={{ width: barWidth, height: barHeight }}
+      >
+        <svg width={barWidth} height={barHeight}>
+          <WaterfallBar />
+        </svg>
+      </div>
+    </SpanPrimitive.Root>
+  );
+}
+```
+## lib/waterfall-timeline.tsx
+```tsx
+"use client";
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { useAuiState } from "@assistant-ui/store";
+import { SpanPrimitive, type SpanState } from "@assistant-ui/react-o11y";
+import { WaterfallRow } from "./waterfall-row";
+const LABEL_WIDTH = 200;
+const MAX_LIST_HEIGHT = 400;
+const MIN_ZOOM = 1;
+const MAX_ZOOM = 20;
+const RIGHT_PADDING_RATIO = 0.08;
+export type WaterfallLayoutContextValue = {
+  barWidth: number;
+  timeRange: { min: number; max: number };
+  barHeight: number;
+  contentWidth: number;
+  selectedSpanId: string | null;
+  onSelectSpan: (spanId: string) => void;
+};
+export const WaterfallLayoutContext =
+  createContext<WaterfallLayoutContextValue | null>(null);
+export function useWaterfallLayout(): WaterfallLayoutContextValue {
+  const ctx = useContext(WaterfallLayoutContext);
+  if (!ctx) {
+    throw new Error(
+      "useWaterfallLayout must be used within WaterfallLayoutContext",
+    );
+  }
+  return ctx;
+}
+function formatTime(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)} ms`;
+  return `${(ms / 1000).toFixed(1)} s`;
+}
+function TimeAxisTicks({
+  timeRange,
+  barWidth,
+}: {
+  timeRange: { min: number; max: number };
+  barWidth: number;
+}) {
+  const duration = timeRange.max - timeRange.min;
+  const tickCount = Math.min(5, Math.max(2, Math.floor(barWidth / 100)));
+  const ticks = Array.from({ length: tickCount + 1 }, (_, i) => {
+    const t = (i / tickCount) * duration;
+    const x = (i / tickCount) * barWidth;
+    return { t, x };
+  });
+  return (
+    <svg width={barWidth} height={28} className="overflow-visible">
+      {ticks.map(({ t, x }) => (
+        <g key={x}>
+          <line
+            x1={x}
+            y1={20}
+            x2={x}
+            y2={28}
+            stroke="currentColor"
+            className="text-border"
+          />
+          <text
+            x={x}
+            y={14}
+            textAnchor="middle"
+            className="fill-muted-foreground text-[10px]"
+          >
+            {formatTime(t)}
+          </text>
+        </g>
+      ))}
+    </svg>
+  );
+}
+export function WaterfallTimeline() {
+  const outerRef = useRef<HTMLDivElement>(null);
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const [baseBarWidth, setBaseBarWidth] = useState(400);
+  const [zoom, setZoom] = useState(1);
+  const zoomRef = useRef(1);
+  const baseBarWidthRef = useRef(400);
+  const scrollAdjustRef = useRef<{
+    mouseX: number;
+    ratio: number;
+  } | null>(null);
+  const [selectedSpanId, setSelectedSpanId] = useState<string | null>(null);
+  const barWidth = Math.max(200, Math.round(baseBarWidth * zoom));
+  const hasSpans = useAuiState((s) => s.span.hasChildren);
+  const timeRange = useAuiState(
+    (s) => s.span.timeRange,
+  ) as SpanState["timeRange"];
+  // Measure outer container width — re-attach when scroll container mounts
+  // biome-ignore lint/correctness/useExhaustiveDependencies: hasSpans triggers re-attach when scroll container mounts
+  useEffect(() => {
+    const el = outerRef.current;
+    if (!el) return;
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (entry) {
+        const w = Math.max(200, entry.contentRect.width - LABEL_WIDTH);
+        baseBarWidthRef.current = w;
+        setBaseBarWidth(w);
+      }
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [hasSpans]);
+  // Cmd + scroll wheel zoom — re-attach when scroll container mounts
+  // biome-ignore lint/correctness/useExhaustiveDependencies: hasSpans triggers re-attach when scroll container mounts
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const handleWheel = (e: WheelEvent) => {
+      if (!e.metaKey) return;
+      e.preventDefault();
+      const rect = el.getBoundingClientRect();
+      const mouseXInView = e.clientX - rect.left - LABEL_WIDTH;
+      const mouseXInContent = el.scrollLeft + mouseXInView;
+      const currentBarWidth = baseBarWidthRef.current * zoomRef.current;
+      const ratio = currentBarWidth > 0 ? mouseXInContent / currentBarWidth : 0;
+      const newZoom = Math.max(
+        MIN_ZOOM,
+        Math.min(MAX_ZOOM, zoomRef.current * 2 ** (-e.deltaY * 0.003)),
+      );
+      scrollAdjustRef.current = { mouseX: mouseXInView, ratio };
+      zoomRef.current = newZoom;
+      setZoom(newZoom);
+    };
+    el.addEventListener("wheel", handleWheel, { passive: false });
+    return () => el.removeEventListener("wheel", handleWheel);
+  }, [hasSpans]);
+  // Adjust scroll after zoom
+  useLayoutEffect(() => {
+    const adj = scrollAdjustRef.current;
+    const el = scrollRef.current;
+    if (!adj || !el) return;
+    scrollAdjustRef.current = null;
+    const newBarX = adj.ratio * barWidth;
+    el.scrollLeft = newBarX - adj.mouseX;
+  }, [barWidth]);
+  const renderTimeRange = useMemo(() => {
+    const duration = timeRange.max - timeRange.min;
+    return {
+      min: timeRange.min,
+      max: timeRange.max + duration * RIGHT_PADDING_RATIO,
+    };
+  }, [timeRange]);
+  const contentWidth = LABEL_WIDTH + barWidth;
+  const scrollMaxHeight = MAX_LIST_HEIGHT + 28;
+  const layoutValue = useMemo(
+    () => ({
+      barWidth,
+      timeRange: renderTimeRange,
+      barHeight: 32,
+      contentWidth,
+      selectedSpanId,
+      onSelectSpan: setSelectedSpanId,
+    }),
+    [barWidth, renderTimeRange, contentWidth, selectedSpanId],
+  );
+  if (!hasSpans) {
+    return (
+      <div className="rounded-lg border border-border py-12 text-center text-muted-foreground text-sm">
+        No spans recorded.
+      </div>
+    );
+  }
+  return (
+    <div ref={outerRef} className="rounded-lg border border-border">
+      <div
+        ref={scrollRef}
+        className="overflow-auto"
+        style={{ maxHeight: scrollMaxHeight }}
+      >
+        {/* Time axis */}
+        <div
+          className="sticky top-0 z-20 flex border-border border-b bg-background"
+          style={{ width: contentWidth }}
+        >
+          <div
+            className="sticky left-0 z-30 shrink-0 border-border border-r bg-background px-2 py-1.5 text-muted-foreground text-xs"
+            style={{ width: LABEL_WIDTH }}
+          >
+            Span
+          </div>
+          <div style={{ width: barWidth, height: 28 }}>
+            <TimeAxisTicks timeRange={renderTimeRange} barWidth={barWidth} />
+          </div>
+        </div>
+        {/* Span rows */}
+        <WaterfallLayoutContext.Provider value={layoutValue}>
+          <div
+            style={{ width: contentWidth }}
+            onClick={(e) => {
+              const target = e.target as HTMLElement;
+              const el = target.closest("[data-span-id]") as HTMLElement | null;
+              if (el?.dataset.spanId) {
+                setSelectedSpanId(el.dataset.spanId);
+              }
+            }}
+          >
+            <SpanPrimitive.Children components={{ Span: WaterfallRow }} />
+          </div>
+        </WaterfallLayoutContext.Provider>
+      </div>
+      {/* Legend */}
+      <div className="flex items-center gap-4 border-border border-t px-3 py-2 text-muted-foreground text-xs">
+        <div className="flex items-center gap-1.5">
+          <span
+            className="size-2.5 rounded-sm"
+            style={{ background: "hsl(221 83% 53%)" }}
+          />
+          <span>action</span>
+        </div>
+        <div className="flex items-center gap-1.5">
+          <span
+            className="size-2.5 rounded-sm"
+            style={{ background: "hsl(262 83% 58%)" }}
+          />
+          <span>api</span>
+        </div>
+        <div className="flex items-center gap-1.5">
+          <span
+            className="size-2.5 rounded-sm"
+            style={{ background: "hsl(142 71% 45%)" }}
+          />
+          <span>tool</span>
+        </div>
+        <div className="flex items-center gap-1.5">
+          <span
+            className="size-2.5 rounded-sm"
+            style={{ background: "hsl(25 95% 53%)" }}
+          />
+          <span>flow</span>
+        </div>
+        <div className="flex items-center gap-1.5">
+          <span
+            className="size-2.5 rounded-sm"
+            style={{ background: "hsl(340 75% 55%)" }}
+          />
+          <span>pipeline</span>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+## next.config.ts
+```typescript
+import type { NextConfig } from "next";
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+export default nextConfig;
+```
+## package.json
+```json
+{
+  "name": "waterfall",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@assistant-ui/react-o11y": "workspace:*",
+    "@assistant-ui/store": "workspace:*",
+    "@assistant-ui/tap": "workspace:*",
+    "next": "^16.1.6",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "devDependencies": {
+    "@assistant-ui/x-buildutils": "workspace:*",
+    "@tailwindcss/postcss": "^4.2.1",
+    "@types/node": "^25.3.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^4.2.1",
+    "typescript": "^5.9.3"
+  }
+}
+```
+## tsconfig.json
+```json
+{
+  "extends": "@assistant-ui/x-buildutils/ts/next",
+  "compilerOptions": {
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+```