@gntik-ai/blocks 0.0.0-stage → 0.5.0

package/src/ai/TokenCostCard/TokenCostCard.test.tsx

@@ -0,0 +1,36 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { TokenCostCard } from './TokenCostCard';
+
+describe('TokenCostCard', () => {
+  it('shows token counts, cost and the budget meter for the default period', async () => {
+    render(<TokenCostCard />);
+    expect(screen.getByText('8.9M')).toBeInTheDocument();
+    expect(screen.getByText('1.4M')).toBeInTheDocument();
+    expect(screen.getByText('$102.40')).toBeInTheDocument();
+    const meter = screen.getByRole('meter', { name: 'Budget' });
+    expect(meter).toHaveAttribute('aria-valuetext', '$102.40 of $250.00');
+    expect(screen.getByText('$147.60 left in this period')).toBeInTheDocument();
+    await expectNoAxeViolations();
+  });
+
+  it('switches period', async () => {
+    const user = userEvent.setup();
+    render(<TokenCostCard />);
+    await user.click(screen.getByRole('button', { name: '30d' }));
+    expect(screen.getByText('$431.75')).toBeInTheDocument();
+    expect(screen.getByRole('meter', { name: 'Budget' })).toHaveAttribute('aria-valuetext', '$431.75 of $500.00');
+  });
+
+  it('reports overspend and hides the switch for a single period', () => {
+    render(
+      <TokenCostCard
+        periods={[{ id: 'm', label: 'Month', inputTokens: 10, outputTokens: 0, cost: 60, budget: 50 }]}
+        currency="EUR"
+      />,
+    );
+    expect(screen.queryByRole('group', { name: 'Period' })).not.toBeInTheDocument();
+    expect(screen.getByText('€10.00 over budget')).toBeInTheDocument();
+  });
+});

package/src/ai/TokenCostCard/TokenCostCard.tsx

@@ -0,0 +1,130 @@
+import { useState } from 'react';
+import {
+  Card,
+  CardAction,
+  CardBody,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Meter,
+  Toggle,
+  ToggleGroup,
+  cn,
+} from '@gntik-ai/ui';
+import { tokenUsagePeriods, type TokenUsagePeriod } from './fixtures';
+
+export type { TokenUsagePeriod } from './fixtures';
+
+export interface TokenCostCardProps {
+  /** One entry per selectable period (a single entry hides the switch). */
+  periods?: TokenUsagePeriod[];
+  defaultPeriod?: string;
+  /** ISO 4217 currency code for cost and budget. */
+  currency?: string;
+  title?: string;
+  /** Subtitle, e.g. the model or project the usage belongs to. */
+  description?: string;
+  /** Heading level of the title, to fit the page outline (default h3). */
+  titleAs?: 'h2' | 'h3' | 'h4';
+  className?: string;
+}
+
+const compact = new Intl.NumberFormat('en-US', { notation: 'compact', maximumFractionDigits: 1 });
+const full = new Intl.NumberFormat('en-US');
+
+/** Token usage and spend for a period, with a budget meter. */
+export function TokenCostCard({
+  periods = tokenUsagePeriods,
+  defaultPeriod,
+  currency = 'USD',
+  title = 'Token usage',
+  description = 'All models · current project',
+  titleAs = 'h3',
+  className,
+}: TokenCostCardProps) {
+  const [periodId, setPeriodId] = useState(defaultPeriod ?? periods[1]?.id ?? periods[0]?.id ?? '');
+  const period = periods.find((p) => p.id === periodId) ?? periods[0];
+  const money = new Intl.NumberFormat('en-US', { style: 'currency', currency });
+  if (!period) return null;
+
+  const totalTokens = period.inputTokens + period.outputTokens;
+  const inputShare = totalTokens > 0 ? (period.inputTokens / totalTokens) * 100 : 0;
+  const remaining = period.budget - period.cost;
+
+  const stats = [
+    { label: 'Input tokens', value: period.inputTokens, swatch: 'bg-primary' },
+    { label: 'Output tokens', value: period.outputTokens, swatch: 'bg-category-violet' },
+  ];
+
+  return (
+    <Card className={cn('w-full', className)}>
+      <CardHeader>
+        <div>
+          <CardTitle as={titleAs}>{title}</CardTitle>
+          <CardDescription>{description}</CardDescription>
+        </div>
+        {periods.length > 1 && (
+          <CardAction>
+            <ToggleGroup
+              aria-label="Period"
+              size="sm"
+              value={[period.id]}
+              onValueChange={(v) => v[0] && setPeriodId(v[0])}
+            >
+              {periods.map((p) => (
+                <Toggle key={p.id} value={p.id}>
+                  {p.label}
+                </Toggle>
+              ))}
+            </ToggleGroup>
+          </CardAction>
+        )}
+      </CardHeader>
+      <CardBody className="flex flex-col gap-5">
+        <dl className="grid grid-cols-2 gap-4 sm:grid-cols-3">
+          {stats.map((s) => (
+            <div key={s.label}>
+              <dt className="flex items-center gap-1.5 text-[12px] text-muted-foreground">
+                <span aria-hidden className={cn('size-2 rounded-sm', s.swatch)} />
+                {s.label}
+              </dt>
+              <dd
+                className="mt-1 font-mono text-[20px] font-semibold tracking-tight text-foreground"
+                title={full.format(s.value)}
+              >
+                {compact.format(s.value)}
+              </dd>
+            </div>
+          ))}
+          <div className="col-span-2 sm:col-span-1">
+            <dt className="text-[12px] text-muted-foreground">Cost</dt>
+            <dd className="mt-1 font-mono text-[20px] font-semibold tracking-tight text-foreground">
+              {money.format(period.cost)}
+            </dd>
+          </div>
+        </dl>
+        <div>
+          <div aria-hidden className="flex h-2 overflow-hidden rounded-full bg-secondary">
+            <span className="bg-primary" style={{ width: `${inputShare}%` }} />
+            <span className="flex-1 bg-category-violet" />
+          </div>
+          <p className="mt-1.5 font-mono text-[11px] text-muted-foreground">
+            {Math.round(inputShare)}% input · {100 - Math.round(inputShare)}% output · {full.format(totalTokens)} tokens
+          </p>
+        </div>
+        <Meter
+          label="Budget"
+          value={period.cost}
+          max={period.budget}
+          valueLabel={`${money.format(period.cost)} of ${money.format(period.budget)}`}
+          aria-valuetext={`${money.format(period.cost)} of ${money.format(period.budget)}`}
+          note={
+            remaining >= 0
+              ? `${money.format(remaining)} left in this period`
+              : `${money.format(-remaining)} over budget`
+          }
+        />
+      </CardBody>
+    </Card>
+  );
+}

package/src/ai/TokenCostCard/block.meta.ts

@@ -0,0 +1,9 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Token cost card',
+  family: 'ai',
+  status: 'beta',
+  description: 'Input and output token counts, their split, total cost and a budget meter, with a period switch.',
+  uses: ['Card', 'ToggleGroup', 'Toggle', 'Meter'],
+};

package/src/ai/TokenCostCard/fixtures.ts

@@ -0,0 +1,18 @@
+export interface TokenUsagePeriod {
+  /** Stable id, e.g. "7d". */
+  id: string;
+  /** Toggle label, e.g. "7 days". */
+  label: string;
+  inputTokens: number;
+  outputTokens: number;
+  /** Spend in the period, in `currency`. */
+  cost: number;
+  /** Budget for the period, in `currency`. */
+  budget: number;
+}
+
+export const tokenUsagePeriods: TokenUsagePeriod[] = [
+  { id: '24h', label: '24h', inputTokens: 1_284_000, outputTokens: 212_400, cost: 14.82, budget: 40 },
+  { id: '7d', label: '7d', inputTokens: 8_930_500, outputTokens: 1_402_900, cost: 102.4, budget: 250 },
+  { id: '30d', label: '30d', inputTokens: 36_120_000, outputTokens: 6_015_300, cost: 431.75, budget: 500 },
+];

package/src/ai/TraceWaterfall/TraceWaterfall.test.tsx

@@ -0,0 +1,119 @@
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import NoDetails from './examples/no-details';
+import RunningTrace from './examples/running';
+import { TraceWaterfall, formatSpanDuration } from './TraceWaterfall';
+
+const spanList = () => screen.getByRole('list', { name: 'Spans' });
+
+describe('TraceWaterfall', () => {
+  it('renders the span tree with bars positioned on the time axis', async () => {
+    render(<TraceWaterfall />);
+    expect(within(spanList()).getAllByRole('listitem')).toHaveLength(8);
+    expect(screen.getByText('8 spans · 2.45s')).toBeInTheDocument();
+    expect(screen.getByText('1 error')).toBeInTheDocument();
+    const details = screen.getByRole('complementary', { name: 'Span details' });
+    expect(within(details).getByRole('heading', { name: 'POST /v1/answer' })).toBeInTheDocument();
+    const bar = screen
+      .getByRole('button', { name: /^generate answer/ })
+      .querySelector('[style*="width"]') as HTMLElement;
+    expect(bar.style.insetInlineStart).toBe(`${(440 / 2450) * 100}%`);
+    await expectNoAxeViolations();
+  });
+
+  it('collapses and expands spans, and selects a span to show its details', async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    render(<TraceWaterfall onSelect={onSelect} />);
+    const collapse = screen.getByRole('button', { name: 'Collapse retrieve context' });
+    expect(collapse).toHaveAttribute('aria-expanded', 'true');
+    await user.click(collapse);
+    expect(within(spanList()).getAllByRole('listitem')).toHaveLength(6);
+    expect(screen.queryByRole('button', { name: /^embed query/ })).not.toBeInTheDocument();
+    await user.click(screen.getByRole('button', { name: 'Expand retrieve context' }));
+    expect(within(spanList()).getAllByRole('listitem')).toHaveLength(8);
+
+    const span = screen.getByRole('button', { name: 'tool: lookup_order, 150ms, error' });
+    await user.click(span);
+    expect(span).toHaveAttribute('aria-pressed', 'true');
+    expect(onSelect).toHaveBeenCalledWith(expect.objectContaining({ id: 's6' }));
+    const details = screen.getByRole('complementary', { name: 'Span details' });
+    expect(within(details).getByText('timeout after 150ms')).toBeInTheDocument();
+  });
+
+  it('formats durations', () => {
+    expect(formatSpanDuration(412)).toBe('412ms');
+    expect(formatSpanDuration(2450)).toBe('2.45s');
+    expect(formatSpanDuration(12_500)).toBe('12.5s');
+  });
+
+  it('moves through spans with the arrow keys and selects with Enter (one tab stop)', async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    render(<TraceWaterfall onSelect={onSelect} />);
+    await user.tab();
+    const root = screen.getByRole('button', { name: 'POST /v1/answer, 2.45s' });
+    expect(root).toHaveFocus();
+    await user.keyboard('{ArrowDown}');
+    expect(screen.getByRole('button', { name: /^retrieve context,/ })).toHaveFocus();
+    await user.keyboard('{ArrowLeft}');
+    expect(screen.getByRole('button', { name: 'Expand retrieve context' })).toHaveAttribute('aria-expanded', 'false');
+    await user.keyboard('{ArrowRight}');
+    expect(screen.getByRole('button', { name: 'Collapse retrieve context' })).toHaveAttribute('aria-expanded', 'true');
+    await user.keyboard('{ArrowRight}');
+    expect(screen.getByRole('button', { name: /^embed query,/ })).toHaveFocus();
+    await user.keyboard('{ArrowLeft}');
+    expect(screen.getByRole('button', { name: /^retrieve context,/ })).toHaveFocus();
+    await user.keyboard('{End}');
+    const last = screen.getByRole('button', { name: /^format response,/ });
+    expect(last).toHaveFocus();
+    await user.keyboard('{Enter}');
+    expect(last).toHaveAttribute('aria-pressed', 'true');
+    expect(onSelect).toHaveBeenLastCalledWith(expect.objectContaining({ id: 's8' }));
+    await user.keyboard('{Home}');
+    expect(root).toHaveFocus();
+    // Only one span button is in the tab order.
+    expect(
+      within(spanList())
+        .getAllByRole('button')
+        .filter((b) => b.tabIndex === 0),
+    ).toHaveLength(1);
+  });
+
+  it('supports controlled selection and running spans (not colour-only)', async () => {
+    const user = userEvent.setup();
+    render(<RunningTrace />);
+    expect(screen.getByText('2 running')).toBeInTheDocument();
+    const generating = screen.getByRole('button', { name: 'generate answer, 1.39s, running' });
+    expect(generating).toHaveAttribute('aria-pressed', 'true');
+    expect(generating).toHaveTextContent('running');
+    expect(generating.querySelector('[data-span-bar]')).toHaveClass('motion-reduce:animate-none');
+    const details = screen.getByRole('complementary', { name: 'Span details' });
+    expect(within(details).getByText('Running')).toBeInTheDocument();
+    expect(within(details).getByText('Elapsed')).toBeInTheDocument();
+    await user.click(screen.getByRole('button', { name: /^tool: search_docs/ }));
+    expect(within(details).getByRole('heading', { name: 'tool: search_docs' })).toBeInTheDocument();
+    await expectNoAxeViolations();
+  });
+
+  it('ignores clicks in controlled mode until the parent updates selectedId', async () => {
+    const user = userEvent.setup();
+    const onSelectedIdChange = vi.fn();
+    render(<TraceWaterfall selectedId="s2" onSelectedIdChange={onSelectedIdChange} />);
+    await user.click(screen.getByRole('button', { name: /^format response,/ }));
+    expect(onSelectedIdChange).toHaveBeenCalledWith('s8');
+    expect(screen.getByRole('button', { name: /^retrieve context,/ })).toHaveAttribute('aria-pressed', 'true');
+  });
+
+  it('hides the details pane or renders custom details', async () => {
+    const { unmount } = render(<NoDetails />);
+    expect(screen.queryByRole('complementary')).toBeNull();
+    await expectNoAxeViolations();
+    unmount();
+    render(<TraceWaterfall renderDetails={(span) => <p>Custom {span.id}</p>} />);
+    expect(
+      within(screen.getByRole('complementary', { name: 'Span details' })).getByText('Custom s1'),
+    ).toBeInTheDocument();
+  });
+});

package/src/ai/TraceWaterfall/TraceWaterfall.tsx

@@ -0,0 +1,317 @@
+import { useId, useMemo, useRef, useState, type KeyboardEvent, type ReactNode } from 'react';
+import { ChevronRight } from '@gntik-ai/icons';
+import { Badge, cn, useI18n } from '@gntik-ai/ui';
+import { traceSpans, type SpanKind, type TraceSpan } from './fixtures';
+import { SpanDetails, formatSpanDuration } from './span-details';
+
+export type { SpanKind, TraceSpan } from './fixtures';
+export { SPAN_STATUSES, SpanDetails, formatSpanDuration, type SpanDetailsProps } from './span-details';
+
+/** Bar colour per span kind (category tokens; errors always use destructive). */
+const KIND_BAR: Record<SpanKind, string> = {
+  http: 'bg-muted-foreground/70',
+  chain: 'bg-category-amber',
+  llm: 'bg-primary',
+  tool: 'bg-category-violet',
+  retrieval: 'bg-category-cyan',
+};
+
+export interface TraceWaterfallProps {
+  spans?: TraceSpan[];
+  title?: string;
+  /** Selected span (controlled). `null` selects nothing. */
+  selectedId?: string | null;
+  /** Span selected initially (defaults to the first root). */
+  defaultSelectedId?: string;
+  /** Called with the span selected by click, Enter or Space. */
+  onSelect?: (span: TraceSpan) => void;
+  /** Called with the id of the span selected (pair with `selectedId`). */
+  onSelectedIdChange?: (id: string) => void;
+  /** Span ids collapsed initially. */
+  defaultCollapsed?: string[];
+  /** Shows the details pane of the selected span (default true). */
+  showDetails?: boolean;
+  /** Custom content of the details pane (default: name, kind, status, timing and attributes). */
+  renderDetails?: (span: TraceSpan) => ReactNode;
+  /** Heading level of the title, to fit the page outline (default h3); inner headings use the next level. */
+  titleAs?: 'h2' | 'h3' | 'h4';
+  className?: string;
+}
+
+interface Row {
+  span: TraceSpan;
+  depth: number;
+  hasChildren: boolean;
+}
+
+/** Depth-first rows, skipping the descendants of collapsed spans. */
+function flatten(spans: TraceSpan[], collapsed: Set<string>): Row[] {
+  const ids = new Set(spans.map((s) => s.id));
+  const children = new Map<string | undefined, TraceSpan[]>();
+  for (const s of spans) {
+    const key = s.parentId && ids.has(s.parentId) ? s.parentId : undefined;
+    children.set(key, [...(children.get(key) ?? []), s]);
+  }
+  const rows: Row[] = [];
+  const walk = (parent: string | undefined, depth: number) => {
+    const list = [...(children.get(parent) ?? [])].sort((a, b) => a.start - b.start);
+    for (const span of list) {
+      const hasChildren = (children.get(span.id)?.length ?? 0) > 0;
+      rows.push({ span, depth, hasChildren });
+      if (hasChildren && !collapsed.has(span.id)) walk(span.id, depth + 1);
+    }
+  };
+  walk(undefined, 0);
+  return rows;
+}
+
+const statusSuffix = (span: TraceSpan) =>
+  span.status === 'error' ? ', error' : span.status === 'running' ? ', running' : '';
+
+/**
+ * Trace waterfall: span tree + duration bars on a shared time axis + an optional details pane for
+ * the selected span. The span list is one tab stop: ↑/↓ move, Home/End jump, → expands or moves to
+ * the first child, ← collapses or moves to the parent, Enter/Space select.
+ */
+export function TraceWaterfall({
+  spans = traceSpans,
+  title = 'Trace',
+  selectedId: selectedProp,
+  defaultSelectedId,
+  onSelect,
+  onSelectedIdChange,
+  defaultCollapsed = [],
+  showDetails = true,
+  renderDetails,
+  titleAs: TitleTag = 'h3',
+  className,
+}: TraceWaterfallProps) {
+  const { t } = useI18n();
+  const SubTag = TitleTag === 'h2' ? 'h3' : TitleTag === 'h3' ? 'h4' : 'h5';
+  const titleId = useId();
+  const [collapsed, setCollapsed] = useState(() => new Set(defaultCollapsed));
+  const [innerSelected, setInnerSelected] = useState<string | undefined>(
+    defaultSelectedId ?? spans.find((s) => !s.parentId)?.id,
+  );
+  const [focusId, setFocusId] = useState<string | undefined>(undefined);
+  const buttons = useRef(new Map<string, HTMLButtonElement>());
+  const rows = useMemo(() => flatten(spans, collapsed), [spans, collapsed]);
+  const total = Math.max(1, ...spans.map((s) => s.start + s.duration));
+  const selectedId = selectedProp === undefined ? innerSelected : (selectedProp ?? undefined);
+  const selected = spans.find((s) => s.id === selectedId);
+  const errors = spans.filter((s) => s.status === 'error').length;
+  const running = spans.filter((s) => s.status === 'running').length;
+  // Roving tab stop: the focused span, else the selected one, else the first row.
+  const tabStop =
+    rows.find((r) => r.span.id === focusId)?.span.id ??
+    rows.find((r) => r.span.id === selectedId)?.span.id ??
+    rows[0]?.span.id;
+
+  const setOpen = (id: string, open: boolean) =>
+    setCollapsed((prev) => {
+      if (prev.has(id) === !open) return prev;
+      const next = new Set(prev);
+      if (open) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+
+  const select = (span: TraceSpan) => {
+    setInnerSelected(span.id);
+    onSelectedIdChange?.(span.id);
+    onSelect?.(span);
+  };
+
+  const focusSpan = (id: string | undefined) => {
+    if (!id) return;
+    setFocusId(id);
+    buttons.current.get(id)?.focus();
+  };
+
+  const onKeyDown = (e: KeyboardEvent<HTMLButtonElement>, index: number) => {
+    const row = rows[index];
+    if (!row) return;
+    const open = !collapsed.has(row.span.id);
+    let handled = true;
+    if (e.key === 'ArrowDown') focusSpan(rows[index + 1]?.span.id);
+    else if (e.key === 'ArrowUp') focusSpan(rows[index - 1]?.span.id);
+    else if (e.key === 'Home') focusSpan(rows[0]?.span.id);
+    else if (e.key === 'End') focusSpan(rows[rows.length - 1]?.span.id);
+    else if (e.key === 'ArrowRight' && row.hasChildren) {
+      if (open) focusSpan(rows[index + 1]?.span.id);
+      else setOpen(row.span.id, true);
+    } else if (e.key === 'ArrowLeft') {
+      if (row.hasChildren && open) setOpen(row.span.id, false);
+      else focusSpan(row.span.parentId);
+    } else handled = false;
+    if (handled) e.preventDefault();
+  };
+
+  return (
+    <section
+      aria-labelledby={titleId}
+      className={cn(
+        'grid overflow-hidden rounded-lg border border-border bg-card shadow-sm',
+        showDetails && 'lg:grid-cols-[minmax(0,1fr)_288px]',
+        className,
+      )}
+    >
+      <div className="min-w-0">
+        <header className="flex flex-wrap items-center gap-x-3 gap-y-1 border-b border-border bg-secondary/35 px-3 py-2.5">
+          <TitleTag id={titleId} className="text-[13px] font-semibold text-foreground">
+            {title}
+          </TitleTag>
+          <span className="font-mono text-[11px] text-muted-foreground">
+            {spans.length} spans · {formatSpanDuration(total)}
+          </span>
+          {running > 0 && (
+            <Badge tone="info" variant="soft" size="sm">
+              {running} running
+            </Badge>
+          )}
+          {errors > 0 && (
+            <Badge tone="destructive" variant="soft" size="sm">
+              {errors} {errors === 1 ? 'error' : 'errors'}
+            </Badge>
+          )}
+        </header>
+        <div
+          aria-hidden
+          className="grid grid-cols-[minmax(0,2fr)_minmax(0,3fr)] border-b border-border px-3 py-1.5 font-mono text-[10.5px] text-muted-foreground"
+        >
+          <span>Span</span>
+          <span className="relative h-3.5">
+            {[0, 0.25, 0.5, 0.75, 1].map((f) => (
+              <span
+                key={f}
+                className={cn(
+                  'absolute top-0',
+                  f === 1 ? '-translate-x-full rtl:translate-x-full' : f > 0 && '-translate-x-1/2 rtl:translate-x-1/2',
+                )}
+                style={{ insetInlineStart: `${f * 100}%` }}
+              >
+                {formatSpanDuration(total * f)}
+              </span>
+            ))}
+          </span>
+        </div>
+        <ol aria-label="Spans" className="py-1">
+          {rows.map(({ span, depth, hasChildren }, index) => {
+            const open = !collapsed.has(span.id);
+            const isSelected = span.id === selectedId;
+            const isRunning = span.status === 'running';
+            const indent = 12 + depth * 16;
+            const bar = span.status === 'error' ? 'bg-destructive' : KIND_BAR[span.kind];
+            const label = `${formatSpanDuration(span.duration)}${isRunning ? ' · running' : ''}`;
+            return (
+              <li key={span.id} className="relative">
+                {hasChildren && (
+                  <button
+                    type="button"
+                    tabIndex={-1}
+                    aria-expanded={open}
+                    aria-label={t(open ? 'common.collapseItem' : 'common.expandItem', { label: span.name })}
+                    onClick={() => setOpen(span.id, !open)}
+                    className="absolute top-1/2 z-10 grid size-6 -translate-y-1/2 place-items-center rounded text-muted-foreground hover:bg-secondary hover:text-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus-ring"
+                    style={{ insetInlineStart: indent - 4 }}
+                  >
+                    <ChevronRight
+                      size={13}
+                      aria-hidden
+                      className={cn(
+                        'transition-transform motion-reduce:transition-none',
+                        open ? 'rotate-90' : 'rtl:-scale-x-100',
+                      )}
+                    />
+                  </button>
+                )}
+                <button
+                  ref={(el) => {
+                    if (el) buttons.current.set(span.id, el);
+                    else buttons.current.delete(span.id);
+                  }}
+                  type="button"
+                  tabIndex={span.id === tabStop ? 0 : -1}
+                  aria-pressed={isSelected}
+                  aria-label={`${span.name}, ${formatSpanDuration(span.duration)}${statusSuffix(span)}`}
+                  data-status={span.status}
+                  onClick={() => select(span)}
+                  onFocus={() => setFocusId(span.id)}
+                  onKeyDown={(e) => onKeyDown(e, index)}
+                  className={cn(
+                    'grid h-8 w-full grid-cols-[minmax(0,2fr)_minmax(0,3fr)] items-center pe-3 text-start hover:bg-secondary/50',
+                    'focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring',
+                    isSelected && 'bg-primary/8 hover:bg-primary/12',
+                  )}
+                >
+                  <span className="flex min-w-0 items-center gap-1.5 pe-3" style={{ paddingInlineStart: indent + 22 }}>
+                    <span
+                      aria-hidden
+                      className={cn(
+                        'size-2 shrink-0 rounded-full',
+                        isRunning ? 'border-[1.5px] border-foreground bg-transparent' : bar,
+                      )}
+                    />
+                    <span
+                      className={cn(
+                        'truncate text-[12.5px]',
+                        span.status === 'error' ? 'text-destructive-text' : 'text-foreground',
+                      )}
+                    >
+                      {span.name}
+                    </span>
+                  </span>
+                  <span className="relative h-full">
+                    <span
+                      aria-hidden
+                      data-span-bar=""
+                      className={cn(
+                        'absolute top-1/2 h-2.5 min-w-0.5 -translate-y-1/2',
+                        bar,
+                        // In progress: an open (square, outlined) end and a soft pulse that stops under reduced motion.
+                        isRunning
+                          ? 'animate-pulse rounded-s-sm border-e-2 border-foreground opacity-70 motion-reduce:animate-none'
+                          : 'rounded-sm',
+                      )}
+                      style={{
+                        insetInlineStart: `${(span.start / total) * 100}%`,
+                        width: `${(span.duration / total) * 100}%`,
+                      }}
+                    />
+                    <span
+                      aria-hidden
+                      className="absolute top-1/2 -translate-y-1/2 ps-1.5 font-mono text-[10.5px] whitespace-nowrap text-muted-foreground"
+                      style={
+                        span.start + span.duration > total * 0.8
+                          ? { insetInlineEnd: `${(1 - span.start / total) * 100}%`, paddingInlineEnd: 6 }
+                          : { insetInlineStart: `${((span.start + span.duration) / total) * 100}%` }
+                      }
+                    >
+                      {label}
+                    </span>
+                  </span>
+                </button>
+              </li>
+            );
+          })}
+        </ol>
+      </div>
+      {showDetails && (
+        <aside
+          aria-label="Span details"
+          className="border-t border-border bg-secondary/20 p-4 lg:border-t-0 lg:border-s"
+        >
+          {selected ? (
+            renderDetails ? (
+              renderDetails(selected)
+            ) : (
+              <SpanDetails span={selected} headingAs={SubTag} />
+            )
+          ) : (
+            <p className="text-[12.5px] text-muted-foreground">Select a span to see its details.</p>
+          )}
+        </aside>
+      )}
+    </section>
+  );
+}

package/src/ai/TraceWaterfall/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Trace waterfall',
+  family: 'ai',
+  status: 'beta',
+  description:
+    'Span tree of a trace with indentation and duration bars positioned on a shared time axis; spans expand and collapse; the list is one tab stop with arrow-key navigation (←/→ collapse and expand), selection is controlled or uncontrolled, the details pane is optional or custom, and running spans show an in-progress bar (pulse stops under reduced motion) with a visible "running" label.',
+  uses: ['Badge', 'StatusTag'],
+};

package/src/ai/TraceWaterfall/examples/no-details.tsx

@@ -0,0 +1,6 @@
+import { TraceWaterfall } from '../TraceWaterfall';
+
+/** Waterfall only: the page shows the selected span elsewhere (e.g. a drawer). */
+export default function TraceWaterfallWithoutDetails() {
+  return <TraceWaterfall showDetails={false} onSelect={() => {}} />;
+}

package/src/ai/TraceWaterfall/examples/running.tsx

@@ -0,0 +1,16 @@
+import { useState } from 'react';
+import { TraceWaterfall } from '../TraceWaterfall';
+import { runningTraceSpans } from '../fixtures';
+
+/** A trace still in progress, with controlled selection driving the details pane. */
+export default function RunningTraceWaterfall() {
+  const [selected, setSelected] = useState<string | null>('r3');
+  return (
+    <TraceWaterfall
+      title="Live trace"
+      spans={runningTraceSpans}
+      selectedId={selected}
+      onSelectedIdChange={setSelected}
+    />
+  );
+}