@tangle-network/charts 0.13.0 → 0.15.0

package/README.md

@@ -4,15 +4,9 @@ Benchmark figures as static SVG and HTML tables, plus optional React timing prim
 
 The React entry also exports `DayBars`, `HBars`, `Histogram`, `Lines`, `Meter`, `Spark`, and `Gantt` for live operational pages. Import `@tangle-network/charts/react/live.css` for their layout and set `--chart-live-*` theme tokens on an ancestor. Data, state colors, destination links, labels, and interpretation remain with the caller. `DayBars` accepts an `onOpen(index)` action with keyboard activation.
 
-`WaterfallHeader`, `WaterfallTimeAxis`, `WaterfallBar` and `WaterfallRow` from
-`@tangle-network/charts/react` own the timing presentation extracted from
-Intelligence's trace viewer. Supply actual span start/end milliseconds and the
-same `{ startMs, endMs }` window to every row. Hierarchy, selection, attribution,
-formatting and failure interpretation stay with the consumer. The original
-minimum/clipped marker remains visible; its tooltip reports the actual duration.
-Set `--waterfall-timing-width`, `--waterfall-duration-width` and the existing
-`--intel-waterfall-*` colors for the consumer's layout and theme. No stylesheet,
-router or React DOM dependency is required.
+`FlowWaterfall` from `@tangle-network/charts/react` is the shared live trace inspector. It owns hierarchy layout, folding, search, playback and running-span growth. Producers own identity, `parentId`, explicit `status` and observed totals. Import `@tangle-network/charts/react/flow-waterfall.css`; its `fw-*` classes and six-field summary support hosts without a Tailwind build. The React-free root exports the `FlowSpan` and `FlowTrace` types.
+
+`WaterfallHeader`, `WaterfallTimeAxis`, `WaterfallBar` and `WaterfallRow` remain available for existing consumers that own their own hierarchy and selection. All use the same `waterfallSpanGeometry` and `waterfallTicks`. Existing fixed-width cells, tones, formatting, attribution slots and unordered-time `—` marks are preserved. Optional fluid tracks, inner-bar colour/class, overlay and clipping fields support the shared inspector without changing existing calls. The primitives were extracted from Intelligence under [brand #211](https://github.com/tangle-network/brand/pull/211); the shared inspector extends that presentation ownership while leaving failure interpretation with producers.
 
 Five figures cover the decisions a benchmark reader makes:
 
@@ -44,7 +38,7 @@ phaseWaterfall([{ id: "route", label: "Route", ms: 5 }, { id: "restore", label:
 
 The producer maps its own blocked or absent states to `no-data`; Charts never assigns a status from a value. `latencyRange` refuses any row below `minN`; when the producer omits those rows, pass their reasons in `excluded` so the note names them. `phaseWaterfall` refuses phases whose sum exceeds the reported total because overlapping spans cannot be drawn as a cumulative waterfall. Its input order is retained, including zero-duration phases. The producer marks known unaccounted leaves with `kind: "unaccounted"`; Charts also marks any difference between their sum and `totalMs`.
 
-The library draws and never decides.
+Charts owns presentation and interaction; producers own interpretation and status. The library never derives failure or running state from metadata values.
 Ranks, intervals, frontier membership, estimate labels and pass counts come from the producer: a board record, a VerticalBench report or an agent-eval lens.
 A figure function returns a `Refusal` in place of a figure it cannot draw honestly, for example a bar over too few units, an interval that names no method, or a frontier the producer did not compute.
 
@@ -319,8 +313,31 @@ npm run build
 
 The package-boundary test builds and packs Charts, installs the tarball in an OS-temporary consumer with a normal offline npm install (no peer-omission flags), asserts React/React DOM/React types cannot resolve, and executes the static root without DOM globals. It compares root exports, static SVG/tables, Refusals, report/chart/plot HTML and CSS with the untouched source implementation, then compiles a static-only consumer with `lib: ["ES2022"]`, `types: []` and `skipLibCheck: false`. Only afterward does it supply the installed React peer/types to verify the packed React runtime and declarations. It runs under `npm test`.
 
-The component tests cover gap/zero/one/equal/negative cases, controlled identity, keyboard/touch selection, nonvisual values and resize contracts. The jsdom resize check verifies fluid/minimum-width attributes and preserved selection, **not browser-computed layout**; The retained packed-browser fixture checks Chromium at 1100px and 390px, keyboard selection, emulated touch, light/dark Brand tokens, reduced motion, and top-layer positioning inside a transformed, paint-contained panel. It passes with React 18 and React 19; the React 18 consumer also compiles the packed declarations with React 18 types. Physical touch hardware and screen-reader audio remain unchecked.
+The component tests cover gap/zero/one/equal/negative cases, controlled identity, keyboard/touch selection, nonvisual values and resize contracts. The jsdom resize check verifies fluid/minimum-width attributes and preserved selection, **not browser-computed layout**; The retained [packed-browser fixture](scripts/charts-browser-smoke.mjs), ported from brand, and its [browser proof](scripts/charts-browser-proof.mjs) check Chromium at 1100px and 390px, keyboard selection, emulated touch, light/dark Brand tokens, reduced motion, and top-layer positioning inside a transformed, paint-contained panel. It passes with React 18 and React 19; the React 18 consumer also compiles the packed declarations with React 18 types. Physical touch hardware and screen-reader audio remain unchecked.
 
 ### Figure browser proof
 
 `node scripts/render-figures.mjs` writes a comparison page from the retained fixtures and approved speed reference. `node scripts/capture-figures.mjs` uses Playwright Chromium to capture all three figures at phone and desktop widths in light and dark themes. The reviewed images are in [`docs/screenshots`](docs/screenshots).
+
+## Live trace waterfall
+
+```tsx
+import { FlowWaterfall } from '@tangle-network/charts/react';
+import type { FlowTrace } from '@tangle-network/charts';
+import '@tangle-network/charts/react/flow-waterfall.css';
+
+// The producer supplies stable identities, explicit status and measured totals.
+<FlowWaterfall trace={trace satisfies FlowTrace} live={running} />;
+```
+
+Search supports Cmd/Ctrl+F and keeps ancestor context. Folding, five playback speeds, scrubbing and Follow live affect presentation only. Running spans grow between snapshots. Missing cost and authoritative LLM counts stay Unknown. Invalid intervals retain a per-row `—` timing mark, preserving the rest of the trace. The static phase waterfall remains a separate chart for disjoint phases.
+
+**Provenance.** FlowWaterfall and its recorded Discovery fixture move from agent-app #1267/#1273 at `78a3e8f7fd9bf93b23afa8290db6d721db544237`; the independent implementation copied no paid reference assets. [Fixture provenance](docs/fixtures/discovery-waterfall-provenance.md) records measured timing, observed token totals and unknowns. The historical [baseline](docs/fixtures/live-playback-rates-baseline.json) and [fixed](docs/fixtures/live-playback-rates-fixed.json) rate measurements are retained. The packed public consumer proof measures all five rates against actual browser wall time during live growth, with ±15% acceptance, using React 18 and 19 at 1100px and 390px.
+
+```sh
+npm run build
+CHARTS_REACT_VERSION=18 CHARTS_PROOF_DIR=/tmp/charts-react18 node scripts/charts-browser-proof.mjs --record
+CHARTS_REACT_VERSION=19 CHARTS_PROOF_DIR=/tmp/charts-react19 node scripts/charts-browser-proof.mjs --record
+```
+
+Consumers: agent-record adapts record provenance; agent-app supplies application trace producers; Creative consumes both. Intelligence already uses the row/axis primitives with its controlled virtualized tree. Tangle Website’s `RecordedRunWaterfall` uses the Header/Row primitives; Blueprint Agent’s execution timeline is a separately owned follow-up. Keep these existing primitives exported. Agent-record’s earlier agent-app dependency increased its installed graph from 134 to 256 package versions (tangle-tools #1674); adopting the lower chart owner removes that framework dependency, with the actual new graph measured by the deployment owner.

package/dist/{timeline-BvVxPTGp.d.ts → flow-trace-B5dlYNsD.d.ts}

@@ -304,4 +304,33 @@ interface TimelineOptions {
 }
 declare function timeline(lanes: TimelineLane[], o: TimelineOptions): Figure | Refusal;
 //#endregion
-export { Exclusion as A, isRefusal as B, YScale as C, ComparisonRow as D, BreakdownInput as E, RateRow as F, Refusal as I, Setup as L, Interval as M, IntervalMethod as N, CostBasis as O, MatrixCell as P, Tier as R, XCategory as S, YTick as T, ChartBand as _, timeline as a, MarkVerdict as b, ENDING_ORDER as c, RunEnding as d, TickOutcome as f, BandKind as g, PointGlyph as h, TimelineTick as i, Figure as j, Estimate as k, OUTCOME_COLORS as l, PointFields as m, TimelineOptions as n, CHECKER_HUES as o, checkerColor as p, TimelineSpan as r, ENDING_COLORS as s, TimelineLane as t, OUTCOME_ORDER as u, ChartMark as v, YTarget as w, MarkerShape as x, MarkKind as y, TierCounts as z };
+//#region src/flow-trace.d.ts
+/** Producer-owned identities, explicit status and observed totals; no React dependency. */
+interface FlowSpan {
+  kind: 'pipeline' | 'model' | 'tool' | 'waiting' | 'handoff';
+  /** Stable identity and parent identity for nested, incrementally updated traces. */
+  id?: string;
+  parentId?: string;
+  /** Running spans extend from endMs to the viewer's observation time. */
+  status?: 'running' | 'done' | 'failed';
+  name: string;
+  startMs: number;
+  endMs: number;
+  approx?: boolean;
+  meta?: Record<string, unknown>;
+}
+/** Describe the structure of a flow trace including spans, timing, tokens, cost, and tool calls */
+interface FlowTrace {
+  spans: FlowSpan[];
+  totalMs: number;
+  promptTokens: number;
+  completionTokens: number;
+  /** Computed when per-token pricing is supplied. */
+  costUsd?: number;
+  toolCalls: number;
+  /** Authoritative LLM request count when supplied; absent means unknown. */
+  modelCalls?: number;
+  errors?: number;
+}
+//#endregion
+export { CostBasis as A, Tier as B, MarkerShape as C, YTick as D, YTarget as E, IntervalMethod as F, isRefusal as H, MatrixCell as I, RateRow as L, Exclusion as M, Figure as N, BreakdownInput as O, Interval as P, Refusal as R, MarkVerdict as S, YScale as T, TierCounts as V, PointGlyph as _, TimelineSpan as a, ChartMark as b, CHECKER_HUES as c, OUTCOME_COLORS as d, OUTCOME_ORDER as f, PointFields as g, checkerColor as h, TimelineOptions as i, Estimate as j, ComparisonRow as k, ENDING_COLORS as l, TickOutcome as m, FlowTrace as n, TimelineTick as o, RunEnding as p, TimelineLane as r, timeline as s, FlowSpan as t, ENDING_ORDER as u, BandKind as v, XCategory as w, MarkKind as x, ChartBand as y, Setup as z };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { A as Exclusion, B as isRefusal, C as YScale, D as ComparisonRow, E as BreakdownInput, F as RateRow, I as Refusal, L as Setup, M as Interval, N as IntervalMethod, O as CostBasis, P as MatrixCell, R as Tier, S as XCategory, T as YTick, _ as ChartBand, a as timeline, b as MarkVerdict, c as ENDING_ORDER, d as RunEnding, f as TickOutcome, g as BandKind, h as PointGlyph, i as TimelineTick, j as Figure, k as Estimate, l as OUTCOME_COLORS, m as PointFields, n as TimelineOptions, o as CHECKER_HUES, p as checkerColor, r as TimelineSpan, s as ENDING_COLORS, t as TimelineLane, u as OUTCOME_ORDER, v as ChartMark, w as YTarget, x as MarkerShape, y as MarkKind, z as TierCounts } from "./timeline-BvVxPTGp.js";
+import { A as CostBasis, B as Tier, C as MarkerShape, D as YTick, E as YTarget, F as IntervalMethod, H as isRefusal, I as MatrixCell, L as RateRow, M as Exclusion, N as Figure, O as BreakdownInput, P as Interval, R as Refusal, S as MarkVerdict, T as YScale, V as TierCounts, _ as PointGlyph, a as TimelineSpan, b as ChartMark, c as CHECKER_HUES, d as OUTCOME_COLORS, f as OUTCOME_ORDER, g as PointFields, h as checkerColor, i as TimelineOptions, j as Estimate, k as ComparisonRow, l as ENDING_COLORS, m as TickOutcome, n as FlowTrace, o as TimelineTick, p as RunEnding, r as TimelineLane, s as timeline, t as FlowSpan, u as ENDING_ORDER, v as BandKind, w as XCategory, x as MarkKind, y as ChartBand, z as Setup } from "./flow-trace-B5dlYNsD.js";
 //#region src/block.d.ts
 interface RenderFigureOptions {
   /** Chart uses a closed data disclosure; plot keeps only the SVG and accessible data. */
@@ -344,4 +344,4 @@ interface UnitDotOptions {
  */
 export declare function unitDotLayout(groups: DotGroup[], width: number, height: number, o?: UnitDotOptions): UnitDotLayout;
 //#endregion
-export { type BandKind, type BreakdownInput, type BreakdownOptions, CHECKER_HUES, type ChartBand, type ChartMark, type ComparisonIntervalsOptions, type ComparisonRow, type CostBasis, type CostFrontierOptions, type DotGroup, type DotGroupRect, ENDING_COLORS, ENDING_ORDER, type Estimate, type Exclusion, type Figure, type HeatmapCell, type HeatmapColumn, type HeatmapOptions, type HeatmapRow, type HeatmapStatus, type Interval, type IntervalMethod, type LatencyRangeOptions, type LatencyRangeRow, type MarkKind, type MarkVerdict, type MatrixCell, type MetricBarsOptions, type MetricRow, type MultiplePanel, OUTCOME_COLORS, OUTCOME_ORDER, type Observations, type PhaseWaterfallOptions, type PointFields, type PointGlyph, type RankedRatesOptions, type RateIdentity, type RateRow, type Refusal, type RenderFigureOptions, type RunEnding, type Setup, type SmallMultiplesOptions, type TaskMatrixOptions, type TickOutcome, type Tier, type TierCounts, type TimePoint, type TimeSeriesOptions, type TimeSeriesRow, type TimelineLane, type TimelineOptions, type TimelineSpan, type TimelineTick, type UnitDotLayout, type UnitDotOptions, type WaterfallPhase, type XCategory, type YScale, type YTarget, type YTick, checkerColor, isRefusal, timeline };
+export { type BandKind, type BreakdownInput, type BreakdownOptions, CHECKER_HUES, type ChartBand, type ChartMark, type ComparisonIntervalsOptions, type ComparisonRow, type CostBasis, type CostFrontierOptions, type DotGroup, type DotGroupRect, ENDING_COLORS, ENDING_ORDER, type Estimate, type Exclusion, type Figure, type FlowSpan, type FlowTrace, type HeatmapCell, type HeatmapColumn, type HeatmapOptions, type HeatmapRow, type HeatmapStatus, type Interval, type IntervalMethod, type LatencyRangeOptions, type LatencyRangeRow, type MarkKind, type MarkVerdict, type MatrixCell, type MetricBarsOptions, type MetricRow, type MultiplePanel, OUTCOME_COLORS, OUTCOME_ORDER, type Observations, type PhaseWaterfallOptions, type PointFields, type PointGlyph, type RankedRatesOptions, type RateIdentity, type RateRow, type Refusal, type RenderFigureOptions, type RunEnding, type Setup, type SmallMultiplesOptions, type TaskMatrixOptions, type TickOutcome, type Tier, type TierCounts, type TimePoint, type TimeSeriesOptions, type TimeSeriesRow, type TimelineLane, type TimelineOptions, type TimelineSpan, type TimelineTick, type UnitDotLayout, type UnitDotOptions, type WaterfallPhase, type XCategory, type YScale, type YTarget, type YTick, checkerColor, isRefusal, timeline };

package/dist/react/flow-waterfall.css

@@ -0,0 +1,76 @@
+/* Standalone surface: consumes Brand/Agent App tokens; no Tailwind build required. */
+.fw-root {
+  --waterfall-bar-height: 1rem;
+  --waterfall-bar-radius: .125rem;
+  --waterfall-duration-width: 100%;
+  --intel-waterfall-track: var(--fw-well);
+  --fw-text: var(--text-primary, hsl(var(--foreground)));
+  --fw-muted: var(--text-muted, hsl(var(--muted-foreground)));
+  --fw-surface: var(--bg-card, hsl(var(--background)));
+  --fw-border: var(--border-default, hsl(var(--border)));
+  --fw-well: var(--md3-surface-container, hsl(var(--secondary)));
+  --fw-accent: var(--accent-text, hsl(var(--primary)));
+  color: var(--fw-text);
+  background: var(--fw-surface);
+  border: 1px solid var(--fw-border);
+  border-radius: var(--radius-lg, .75rem);
+  min-width: 0;
+  font: inherit;
+  font-size: .8125rem;
+  line-height: 1.5;
+}
+.fw-root *, .fw-root *::before, .fw-root *::after { box-sizing: border-box; }
+.fw-root :is(p, dl, dd) { margin: 0; }
+.fw-root .fw-heading { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: .5rem; padding: .75rem; border-bottom: 1px solid var(--fw-border); }
+.fw-root .fw-title { display: flex; align-items: center; gap: .5rem; font-weight: 600; font-size: .875rem; }
+.fw-root .fw-search { display: flex; min-width: 0; gap: .25rem; align-items: center; }
+.fw-root .fw-control { appearance: auto; font: inherit; font-size: .75rem; line-height: 1.4; min-height: 2rem; padding: .25rem .5rem; border: 1px solid var(--fw-border); border-radius: var(--radius-sm, .375rem); color: var(--fw-text); background: var(--fw-surface); cursor: pointer; }
+.fw-root .fw-control:hover, .fw-root .fw-toggle:hover { background: var(--fw-well); }
+.fw-root :is(button, input, select, [tabindex]):focus-visible { outline: 2px solid var(--fw-accent); outline-offset: 2px; }
+.fw-root :is(button, input):disabled { opacity: .5; cursor: default; }
+.fw-root .fw-search-input { width: 10rem; min-width: 0; cursor: text; }
+.fw-root .fw-summary { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: .75rem 1rem; padding: .75rem; border-bottom: 1px solid var(--fw-border); }
+.fw-root .fw-muted { color: var(--fw-muted); font-size: .75rem; }
+.fw-root .fw-value { margin-top: .125rem; font-family: var(--font-mono, monospace); font-size: .875rem; font-variant-numeric: tabular-nums; overflow-wrap: anywhere; }
+.fw-root .fw-legend { display: flex; flex-wrap: wrap; gap: .25rem .75rem; padding: .5rem .75rem; border-bottom: 1px solid var(--fw-border); color: var(--fw-muted); font-size: .75rem; }
+.fw-root .fw-legend-item { display: inline-flex; align-items: center; gap: .25rem; }
+.fw-root .fw-dot { width: .375rem; height: .375rem; border-radius: 50%; }
+.fw-root .fw-orchestrator { --fw-bar-color: var(--fw-muted); background: var(--fw-bar-color); }
+.fw-root .fw-model { --fw-bar-color: var(--chart-accent, hsl(var(--primary))); background: var(--fw-bar-color); }
+.fw-root .fw-tool { --fw-bar-color: var(--status-cold, hsl(var(--accent))); background: var(--fw-bar-color); }
+.fw-root .fw-waiting { --fw-bar-color: var(--status-stopped, hsl(var(--warning-strong))); background: var(--fw-bar-color); }
+.fw-root .fw-handoff { --fw-bar-color: var(--status-running, hsl(var(--success))); background: var(--fw-bar-color); }
+.fw-root .fw-failed { --fw-bar-color: var(--status-error, hsl(var(--destructive))); background: var(--fw-bar-color); }
+.fw-root .fw-branches { display: flex; gap: .5rem; padding: .5rem .75rem 0; }
+.fw-root .fw-timeline { overflow-x: auto; padding: .75rem; }
+.fw-root .fw-track { min-width: 480px; }
+.fw-root .fw-grid { display: grid; grid-template-columns: minmax(0, 2fr) minmax(0, 3fr) 70px; align-items: center; gap: .5rem; }
+.fw-root .fw-axis { padding-bottom: .5rem; color: var(--fw-muted); font-size: .75rem; }
+.fw-root .fw-ticks { display: flex; justify-content: space-between; font-family: var(--font-mono, monospace); font-variant-numeric: tabular-nums; }
+.fw-root .fw-align-right { text-align: right; }
+.fw-root .fw-empty { padding: 2rem .5rem; text-align: center; color: var(--fw-muted); font-size: .875rem; }
+.fw-root .fw-row { border-radius: .25rem; padding: .375rem 0; }
+.fw-root .fw-slowest { background: var(--fw-well); outline: 1px solid var(--fw-border); }
+.fw-root .fw-pending { opacity: .4; }
+.fw-root .fw-name { display: flex; align-items: center; min-width: 0; }
+.fw-root .fw-toggle { appearance: none; width: 1.5rem; height: 1.5rem; margin-right: .25rem; flex-shrink: 0; border: 0; border-radius: .25rem; background: transparent; color: var(--fw-text); font: inherit; cursor: pointer; }
+.fw-root .fw-leaf { margin-right: .25rem; width: 1.5rem; flex-shrink: 0; text-align: center; color: var(--fw-muted); }
+.fw-root .fw-span-name { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: .75rem; }
+.fw-root .fw-error-text { color: var(--text-danger, var(--status-error)); }
+.fw-root .fw-bar-track { position: relative; height: 1rem; overflow: hidden; border-radius: .125rem; background: var(--fw-well); }
+.fw-root .fw-bar { position: absolute; top: 0; bottom: 0; border-radius: .125rem; }
+.fw-root .fw-approx { opacity: .7; }
+.fw-root .fw-playhead { position: absolute; top: 0; bottom: 0; width: 1px; background: var(--fw-text); }
+.fw-root .fw-duration { padding-right: .25rem; text-align: right; font-family: var(--font-mono, monospace); font-size: .75rem; font-variant-numeric: tabular-nums; }
+.fw-root .fw-slowest-caption { padding: 0 .75rem .5rem; color: var(--fw-muted); font-size: .75rem; overflow-wrap: anywhere; }
+.fw-root .fw-text { color: var(--fw-text); }
+.fw-root .fw-playback { display: flex; align-items: center; flex-wrap: wrap; gap: .5rem; border-top: 1px solid var(--fw-border); padding: .75rem; }
+.fw-root .fw-speed, .fw-root .fw-position { display: flex; align-items: center; gap: .25rem; color: var(--fw-muted); font-size: .75rem; }
+.fw-root .fw-position { flex: 1; min-width: 6rem; gap: .5rem; }
+.fw-root .fw-slider { min-width: 0; flex: 1; accent-color: var(--fw-accent); }
+.fw-root .fw-time { font-family: var(--font-mono, monospace); font-size: .75rem; font-variant-numeric: tabular-nums; color: var(--fw-muted); }
+.fw-root .fw-sr-only { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0; }
+@media (max-width: 480px) {
+  .fw-root .fw-summary { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .fw-root .fw-position { flex-basis: 100%; }
+}

package/dist/react/index.d.ts

@@ -1,5 +1,5 @@
-import { C as YScale, I as Refusal, S as XCategory, T as YTick, _ as ChartBand, b as MarkVerdict, f as TickOutcome, g as BandKind, h as PointGlyph, i as TimelineTick, j as Figure, m as PointFields, n as TimelineOptions, r as TimelineSpan, t as TimelineLane, v as ChartMark, w as YTarget, x as MarkerShape, y as MarkKind } from "../timeline-BvVxPTGp.js";
-import { ReactElement, ReactNode } from "react";
+import { C as MarkerShape, D as YTick, E as YTarget, N as Figure, R as Refusal, S as MarkVerdict, T as YScale, _ as PointGlyph, a as TimelineSpan, b as ChartMark, g as PointFields, i as TimelineOptions, m as TickOutcome, n as FlowTrace, o as TimelineTick, r as TimelineLane, v as BandKind, w as XCategory, x as MarkKind, y as ChartBand } from "../flow-trace-B5dlYNsD.js";
+import { CSSProperties, ReactElement, ReactNode } from "react";
 //#region src/react/sparkline.d.ts
 type SparklineDirection = "rising" | "falling" | "flat";
 type SparklineValues = readonly (number | null)[];
@@ -111,8 +111,10 @@ interface WaterfallTimeAxisProps {
   widthPx?: number;
   formatDuration?: (ms: number) => string;
   className?: string;
+  /** Fill the embedding grid track; the default retains Intelligence's fixed cell. */
+  fluid?: boolean;
 }
-export declare function WaterfallTimeAxis({ windowMs, originMs, widthPx, formatDuration, className }: WaterfallTimeAxisProps): import("react").JSX.Element | null;
+export declare function WaterfallTimeAxis({ windowMs, originMs, widthPx, formatDuration, className, fluid }: WaterfallTimeAxisProps): import("react").JSX.Element | null;
 interface WaterfallBarProps {
   startMs: number;
   endMs: number;
@@ -120,17 +122,26 @@ interface WaterfallBarProps {
   tone?: "default" | "error" | "critical";
   formatDuration?: (ms: number) => string;
   className?: string;
+  /** Presentation only; the producer continues to own status and tone. */
+  color?: string;
+  barClassName?: string;
+  overlay?: ReactNode;
+  fluid?: boolean;
+  /** Clip playback without changing the recorded duration or its tooltip. */
+  clipAtMs?: number;
 }
-export declare function WaterfallBar({ startMs, endMs, window, tone, formatDuration, className }: WaterfallBarProps): import("react").JSX.Element;
+export declare function WaterfallBar({ startMs, endMs, window, tone, formatDuration, className, color: suppliedColor, barClassName, overlay, fluid, clipAtMs }: WaterfallBarProps): import("react").JSX.Element;
 interface WaterfallRowProps extends Omit<WaterfallBarProps, "className"> {
   label: ReactNode;
   attribution?: ReactNode;
   timingClassName?: string;
   durationClassName?: string;
   className?: string;
+  style?: CSSProperties;
+  durationLabel?: ReactNode;
 }
 /** Non-interactive row body; its caller owns treeitems, buttons and selection. */
-export declare function WaterfallRow({ label, attribution, startMs, endMs, window, tone, formatDuration, className, timingClassName, durationClassName }: WaterfallRowProps): import("react").JSX.Element;
+export declare function WaterfallRow({ label, attribution, startMs, endMs, window, tone, formatDuration, className, timingClassName, durationClassName, style, durationLabel, ...bar }: WaterfallRowProps): import("react").JSX.Element;
 interface WaterfallHeaderProps extends WaterfallTimeAxisProps {
   label?: ReactNode;
   attribution?: ReactNode;
@@ -231,6 +242,19 @@ export declare function Spark({ points, max, color, label, format, time }: {
   format?: (v: number) => string;
   time?: (t: number) => string;
 }): import("react").JSX.Element;
+/** Recorded instants on one time axis, such as process restarts or deploys: a tick per event in `[from, to]`, with
+ * `ticks` evenly spaced axis labels under it. Hovering a tick names its time through `time`. The strip keeps its type
+ * size at any width, and `label` names it for assistive tech. */
+export declare function Events({ at, from, to, label, color, ticks, axis, time }: {
+  at: number[];
+  from: number;
+  to: number;
+  label: string;
+  color?: string;
+  ticks?: number;
+  axis?: (t: number) => string;
+  time?: (t: number) => string;
+}): import("react").JSX.Element;
 /** One bar per row on a shared time axis (who worked when): each row's bar spans its start to its end, coloured by its
  * state; hovering a span names it, its state and its span. Times are epoch ms; `axis` labels the time axis.
  * `lanes` give a row several spans (the same shape as the static `timeline`); a span with `end: null` is open and runs
@@ -323,4 +347,19 @@ interface DotMapProps {
 export declare const DOT_MAP_CATEGORIES: readonly string[];
 export declare function DotMap({ positions, radii, colors, palette, extent, rects, labels, dimmed, selected, minPixelRadius, onHover, onSelect, describe, height, ariaLabel }: DotMapProps): import("react").JSX.Element;
 //#endregion
-export type { BandKind, ChartBand, ChartMark, DotMapLabel, DotMapProps, DotMapRect, Figure, FigureAtWidth, FigureViewProps, LineSeries, MarkKind, MarkVerdict, MarkerShape, MeterSegment, PointFields, PointGlyph, Refusal, SparklineDirection, SparklineGeometry, SparklineGeometryOptions, SparklineLabelOptions, SparklinePoint, SparklineProps, SparklineValues, StackedBarBucket, StackedBarChartProps, StackedBarSegment, StackedBarSeries, TickOutcome, TimelineLane, TimelineOptions, TimelineSpan, TimelineTick, TimelineViewProps, WaterfallBarProps, WaterfallHeaderProps, WaterfallRowProps, WaterfallSpanGeometry, WaterfallTimeAxisProps, WaterfallWindow, XCategory, YScale, YTarget, YTick };
+//#region src/react/flow-waterfall.d.ts
+interface FlowWaterfallProps {
+  trace: FlowTrace;
+  /** Extend running spans between incoming snapshots. Inferred from span status by default. */
+  live?: boolean;
+  /** Epoch-ms origin when the producer supplies one; otherwise advance from the latest snapshot. */
+  startedAt?: number;
+  /** Accessible name also distinguishes multiple waterfalls on one page. */
+  label?: string;
+  /** Fold all branches on first mount for large traces; search still reveals matches. */
+  defaultCollapsed?: boolean;
+}
+/** Shared trace inspector. Data remains producer-owned; playback only clips its presentation. */
+export declare function FlowWaterfall({ trace, live, startedAt, label, defaultCollapsed }: FlowWaterfallProps): import("react").JSX.Element;
+//#endregion
+export type { BandKind, ChartBand, ChartMark, DotMapLabel, DotMapProps, DotMapRect, Figure, FigureAtWidth, FigureViewProps, FlowWaterfallProps, LineSeries, MarkKind, MarkVerdict, MarkerShape, MeterSegment, PointFields, PointGlyph, Refusal, SparklineDirection, SparklineGeometry, SparklineGeometryOptions, SparklineLabelOptions, SparklinePoint, SparklineProps, SparklineValues, StackedBarBucket, StackedBarChartProps, StackedBarSegment, StackedBarSeries, TickOutcome, TimelineLane, TimelineOptions, TimelineSpan, TimelineTick, TimelineViewProps, WaterfallBarProps, WaterfallHeaderProps, WaterfallRowProps, WaterfallSpanGeometry, WaterfallTimeAxisProps, WaterfallWindow, XCategory, YScale, YTarget, YTick };

package/dist/react/index.js

@@ -653,7 +653,7 @@ const durationStyle = {
 	fontVariantNumeric: "tabular-nums"
 };
 const ordered = (start, end) => Number.isFinite(start) && Number.isFinite(end) && end >= start;
-function WaterfallTimeAxis({ windowMs, originMs = 0, widthPx = 208, formatDuration = formatWaterfallDuration, className }) {
+function WaterfallTimeAxis({ windowMs, originMs = 0, widthPx = 208, formatDuration = formatWaterfallDuration, className, fluid = false }) {
 	if (!ordered(0, windowMs) || !Number.isFinite(originMs)) return null;
 	const ticks = waterfallTicks(windowMs, widthPx);
 	if (windowMs === 0) return null;
@@ -662,7 +662,10 @@ function WaterfallTimeAxis({ windowMs, originMs = 0, widthPx = 208, formatDurati
 		"data-waterfall-axis": "",
 		"aria-hidden": "true",
 		style: {
-			...timingCell,
+			...fluid ? {
+				minWidth: 0,
+				flex: "1 1 0%"
+			} : timingCell,
 			position: "relative",
 			height: "var(--waterfall-axis-height, 1.5rem)"
 		},
@@ -698,34 +701,40 @@ function WaterfallTimeAxis({ windowMs, originMs = 0, widthPx = 208, formatDurati
 		})
 	});
 }
-function WaterfallBar({ startMs, endMs, window, tone = "default", formatDuration = formatWaterfallDuration, className }) {
+function WaterfallBar({ startMs, endMs, window, tone = "default", formatDuration = formatWaterfallDuration, className, color: suppliedColor, barClassName, overlay, fluid = false, clipAtMs }) {
+	const cell = fluid ? {
+		minWidth: 0,
+		flex: "1 1 0%"
+	} : timingCell;
 	if (!ordered(startMs, endMs) || !ordered(window.startMs, window.endMs)) return /* @__PURE__ */ jsx("span", {
 		className,
 		"data-waterfall-track": "",
 		"data-unavailable": "true",
 		title: "Timing unavailable",
 		style: {
-			...timingCell,
+			...cell,
 			textAlign: "center"
 		},
 		children: "—"
 	});
 	const geometry = waterfallSpanGeometry(startMs, endMs, window);
-	const color = tone === "error" ? "var(--intel-waterfall-error, #dc2626)" : tone === "critical" ? "var(--intel-waterfall-critical, #0891b2)" : "var(--intel-waterfall-bar, #2563eb)";
-	return /* @__PURE__ */ jsx("span", {
+	const color = suppliedColor ?? (tone === "error" ? "var(--intel-waterfall-error, #dc2626)" : tone === "critical" ? "var(--intel-waterfall-critical, #0891b2)" : "var(--intel-waterfall-bar, #2563eb)");
+	const visible = clipAtMs === void 0 ? geometry : waterfallSpanGeometry(startMs, Math.max(startMs, Math.min(endMs, clipAtMs)), window);
+	return /* @__PURE__ */ jsxs("span", {
 		className,
 		"data-waterfall-track": "",
 		"data-tone": tone,
 		title: `+${formatDuration(geometry.startOffsetMs)} · ${formatDuration(geometry.durationMs)}${tone === "critical" ? " · critical path" : ""}`,
 		style: {
-			...timingCell,
+			...cell,
 			position: "relative",
 			height: "var(--waterfall-bar-height, 0.875rem)",
 			overflow: "hidden",
 			borderRadius: "var(--waterfall-bar-radius, 999px)",
 			background: "var(--intel-waterfall-track, rgb(148 163 184 / 22%))"
 		},
-		children: /* @__PURE__ */ jsx("span", {
+		children: [/* @__PURE__ */ jsx("span", {
+			className: barClassName,
 			"data-waterfall-bar": "",
 			"data-clipped": geometry.clipped || void 0,
 			style: {
@@ -735,18 +744,21 @@ function WaterfallBar({ startMs, endMs, window, tone = "default", formatDuration
 				borderRadius: "inherit",
 				background: color,
 				left: `${geometry.offsetPct}%`,
-				width: `${geometry.widthPct}%`,
+				width: `${clipAtMs !== void 0 && clipAtMs <= startMs ? 0 : visible.widthPct}%`,
 				boxShadow: tone === "default" ? void 0 : `0 0 0 1px ${color}`
 			}
-		})
+		}), overlay]
 	});
 }
 /** Non-interactive row body; its caller owns treeitems, buttons and selection. */
-function WaterfallRow({ label, attribution, startMs, endMs, window, tone, formatDuration = formatWaterfallDuration, className, timingClassName, durationClassName }) {
+function WaterfallRow({ label, attribution, startMs, endMs, window, tone, formatDuration = formatWaterfallDuration, className, timingClassName, durationClassName, style, durationLabel, ...bar }) {
 	return /* @__PURE__ */ jsxs("span", {
 		"data-waterfall-row": "",
 		className,
-		style: rowStyle,
+		style: style ? {
+			...rowStyle,
+			...style
+		} : rowStyle,
 		children: [
 			/* @__PURE__ */ jsx("span", {
 				"data-waterfall-label": "",
@@ -760,13 +772,14 @@ function WaterfallRow({ label, attribution, startMs, endMs, window, tone, format
 				window,
 				tone,
 				formatDuration,
-				className: timingClassName
+				className: timingClassName,
+				...bar
 			}),
 			/* @__PURE__ */ jsx("span", {
 				"data-waterfall-duration": "",
 				className: durationClassName,
 				style: durationStyle,
-				children: ordered(startMs, endMs) ? formatDuration(endMs - startMs) : "—"
+				children: durationLabel ?? (ordered(startMs, endMs) ? formatDuration(endMs - startMs) : "—")
 			})
 		]
 	});
@@ -1501,6 +1514,70 @@ function Spark({ points, max = 1, color = LIVE_SERIES[0], label, format = format
 		]
 	});
 }
+/** Recorded instants on one time axis, such as process restarts or deploys: a tick per event in `[from, to]`, with
+* `ticks` evenly spaced axis labels under it. Hovering a tick names its time through `time`. The strip keeps its type
+* size at any width, and `label` names it for assistive tech. */
+function Events({ at, from, to, label, color = LIVE_SERIES[0], ticks = 7, axis = (t) => new Date(t).toLocaleDateString(void 0, { weekday: "short" }), time = (t) => new Date(t).toLocaleString() }) {
+	const [ref, width, em] = useWidth();
+	if (!Number.isFinite(from) || !Number.isFinite(to) || to <= from) throw new RangeError("Events needs a window with to after from.");
+	const shown = at.filter((t) => Number.isFinite(t) && t >= from && t <= to).sort((a, b) => a - b);
+	const strip = Math.round(2.2 * em);
+	const height = strip + Math.round(1.5 * em);
+	const pad = 6;
+	const x = (t) => pad + (t - from) / (to - from) * Math.max(0, width - 12);
+	const steps = Math.max(1, Math.round(ticks));
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		className: "ov-plot",
+		children: width > 0 && /* @__PURE__ */ jsxs("svg", {
+			width,
+			height,
+			role: "img",
+			"aria-label": `${label}: ${shown.length} in the window`,
+			children: [
+				/* @__PURE__ */ jsx("line", {
+					x1: pad,
+					x2: width - pad,
+					y1: strip / 2,
+					y2: strip / 2,
+					className: "ov-gridline"
+				}),
+				shown.map((t, i) => /* @__PURE__ */ jsxs("g", {
+					"data-event": t,
+					children: [
+						/* @__PURE__ */ jsx("title", { children: time(t) }),
+						/* @__PURE__ */ jsx("rect", {
+							x: x(t) - 6,
+							y: 0,
+							width: 12,
+							height: strip,
+							fill: "transparent"
+						}),
+						/* @__PURE__ */ jsx("line", {
+							x1: x(t),
+							x2: x(t),
+							y1: 4,
+							y2: strip - 4,
+							stroke: color,
+							strokeWidth: 2,
+							strokeLinecap: "round"
+						})
+					]
+				}, `${t}-${i}`)),
+				Array.from({ length: steps + 1 }, (_, i) => {
+					const t = from + i / steps * (to - from);
+					return /* @__PURE__ */ jsx("text", {
+						x: x(t),
+						y: height - em * .35,
+						className: "ov-axis",
+						textAnchor: i === 0 ? "start" : i === steps ? "end" : "middle",
+						children: axis(t)
+					}, i);
+				})
+			]
+		})
+	});
+}
 /** One bar per row on a shared time axis (who worked when): each row's bar spans its start to its end, coloured by its
 * state; hovering a span names it, its state and its span. Times are epoch ms; `axis` labels the time axis.
 * `lanes` give a row several spans (the same shape as the static `timeline`); a span with `end: null` is open and runs
@@ -2228,4 +2305,494 @@ function DotMap({ positions, radii, colors, palette, extent, rects, labels, dimm
 	});
 }
 //#endregion
-export { DEFAULT_SPARKLINE_EMPTY_LABEL, DEFAULT_SPARKLINE_HEIGHT, DEFAULT_SPARKLINE_LABEL, DEFAULT_SPARKLINE_UNAVAILABLE_LABEL, DEFAULT_SPARKLINE_WIDTH, DOT_MAP_CATEGORIES, DayBars, DotMap, FigureView, Gantt, HBars, Histogram, LIVE_SERIES, Lines, Meter, Spark, Sparkline, StackedBarChart, TimelineView, WaterfallBar, WaterfallHeader, WaterfallRow, WaterfallTimeAxis, formatCompact, formatSparklineValue, formatWaterfallDuration, sparklineGeometry, sparklineLabel, sparklinePointsAttribute, sparklineReadings, waterfallSpanGeometry, waterfallTicks };
+//#region src/react/flow-waterfall-model.ts
+const spanFailed = (span) => span.status === "failed";
+const spanRunning = (span) => span.status === "running";
+/** Hierarchy only; the shared timing primitives own all bar geometry.
+* Orphaned parents become roots; cycles are broken without dropping any span. */
+function flowWaterfallRows(trace) {
+	const ids = /* @__PURE__ */ new Set();
+	const rows = [...trace.spans].map((span, i) => ({
+		span,
+		key: span.id ?? `span-${i}`
+	})).sort((a, b) => a.span.startMs - b.span.startMs).map(({ span, key }, index) => {
+		let id = key;
+		let suffix = index;
+		while (ids.has(id)) id = `${key}:${suffix++}`;
+		ids.add(id);
+		return {
+			id,
+			parentId: span.parentId,
+			name: span.name,
+			kind: span.kind,
+			durationLabel: Number.isFinite(span.startMs) && Number.isFinite(span.endMs) && span.endMs >= span.startMs ? `${((span.endMs - span.startMs) / 1e3).toFixed(1)}s${span.approx ? "~" : ""}` : "—",
+			approx: span.approx === true,
+			ok: !spanFailed(span),
+			depth: 0,
+			hasChildren: false,
+			span
+		};
+	});
+	const byId = new Map(rows.map((row) => [row.id, row]));
+	const children = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const seen = /* @__PURE__ */ new Set([row.id]);
+		let parent = row.parentId;
+		while (parent && byId.has(parent)) {
+			if (seen.has(parent)) {
+				row.parentId = void 0;
+				break;
+			}
+			seen.add(parent);
+			parent = byId.get(parent)?.parentId;
+		}
+		if (row.parentId && !byId.has(row.parentId)) row.parentId = void 0;
+		if (row.parentId) {
+			const siblings = children.get(row.parentId) ?? [];
+			siblings.push(row);
+			children.set(row.parentId, siblings);
+		}
+	}
+	const ordered = [];
+	const visit = (row, depth) => {
+		row.depth = depth;
+		row.hasChildren = children.has(row.id);
+		ordered.push(row);
+		for (const child of children.get(row.id) ?? []) visit(child, depth + 1);
+	};
+	for (const row of rows) if (!row.parentId) visit(row, 0);
+	return ordered;
+}
+/** Search keeps ancestor context and deliberately reveals matches inside collapsed branches. */
+function visibleFlowWaterfallRows(rows, query, collapsed) {
+	const byId = new Map(rows.map((row) => [row.id, row]));
+	const term = query.trim().toLowerCase();
+	if (term) {
+		const matching = /* @__PURE__ */ new Set();
+		for (const row of rows) {
+			if (!`${row.name} ${row.kind} ${row.ok ? "" : "failed"} ${row.span.status ?? ""}`.toLowerCase().includes(term)) continue;
+			let cursor = row;
+			while (cursor && !matching.has(cursor.id)) {
+				matching.add(cursor.id);
+				cursor = cursor.parentId ? byId.get(cursor.parentId) : void 0;
+			}
+		}
+		return rows.filter((row) => matching.has(row.id));
+	}
+	const hidden = /* @__PURE__ */ new Set();
+	return rows.filter((row) => {
+		const isHidden = row.parentId !== void 0 && (collapsed.has(row.parentId) || hidden.has(row.parentId));
+		if (isHidden) hidden.add(row.id);
+		return !isHidden;
+	});
+}
+//#endregion
+//#region src/react/flow-waterfall.tsx
+const TONES = {
+	pipeline: {
+		label: "Orchestrator",
+		color: "fw-orchestrator"
+	},
+	model: {
+		label: "Model call",
+		color: "fw-model"
+	},
+	tool: {
+		label: "Tool call",
+		color: "fw-tool"
+	},
+	waiting: {
+		label: "Waiting",
+		color: "fw-waiting"
+	},
+	handoff: {
+		label: "Handoff",
+		color: "fw-handoff"
+	},
+	failed: {
+		label: "Failed",
+		color: "fw-failed"
+	}
+};
+const SPEEDS = [
+	.5,
+	1,
+	1.5,
+	2,
+	4
+];
+const controlClass = "fw-control";
+const seconds = (ms) => `${(ms / 1e3).toFixed(1)}s`;
+/** Shared trace inspector. Data remains producer-owned; playback only clips its presentation. */
+function FlowWaterfall({ trace, live, startedAt, label = "Trace waterfall", defaultCollapsed = false }) {
+	const root = useRef(null);
+	const search = useRef(null);
+	const searchId = useId();
+	const [query, setQuery] = useState("");
+	const [collapsed, setCollapsed] = useState(() => new Set(defaultCollapsed ? trace.spans.flatMap((span) => span.parentId ? [span.parentId] : []) : []));
+	const [speed, setSpeed] = useState(1);
+	const [playing, setPlaying] = useState(false);
+	const [position, setPosition] = useState(null);
+	const observedTotal = Number.isFinite(trace.totalMs) && trace.totalMs >= 0 ? trace.totalMs : 0;
+	const [elapsed, setElapsed] = useState(observedTotal);
+	const isLive = live ?? trace.spans.some(spanRunning);
+	useEffect(() => {
+		setElapsed(observedTotal);
+		if (!isLive) return;
+		const receivedAt = Date.now();
+		const tick = () => setElapsed(Math.max(observedTotal, startedAt === void 0 ? observedTotal + Date.now() - receivedAt : Date.now() - startedAt));
+		tick();
+		const timer = setInterval(tick, 100);
+		return () => clearInterval(timer);
+	}, [
+		trace,
+		observedTotal,
+		isLive,
+		startedAt
+	]);
+	const currentTrace = useMemo(() => {
+		const totalMs = Math.max(observedTotal, isLive ? elapsed : 0, ...trace.spans.map((span) => Number.isFinite(span.endMs) ? span.endMs : 0));
+		return {
+			...trace,
+			totalMs,
+			spans: trace.spans.map((span) => isLive && spanRunning(span) && Number.isFinite(span.endMs) && span.endMs >= span.startMs ? {
+				...span,
+				endMs: Math.max(span.endMs, totalMs)
+			} : span)
+		};
+	}, [
+		trace,
+		observedTotal,
+		elapsed,
+		isLive
+	]);
+	const totalMs = currentTrace.totalMs;
+	const playhead = Math.min(position ?? totalMs, totalMs);
+	const playbackLimit = useRef(totalMs);
+	useEffect(() => {
+		playbackLimit.current = totalMs;
+	}, [totalMs]);
+	useEffect(() => {
+		if (!playing) return;
+		let last = performance.now();
+		const timer = setInterval(() => {
+			const now = performance.now();
+			const delta = (now - last) * speed;
+			last = now;
+			setPosition((previous) => Math.min(playbackLimit.current, (previous ?? 0) + delta));
+		}, 50);
+		return () => clearInterval(timer);
+	}, [playing, speed]);
+	useEffect(() => {
+		if (playing && position !== null && position >= totalMs) setPlaying(false);
+	}, [
+		position,
+		playing,
+		totalMs
+	]);
+	useEffect(() => {
+		const keydown = (event) => {
+			if (!(event.metaKey || event.ctrlKey) || event.key.toLowerCase() !== "f") return;
+			const active = document.activeElement;
+			const ownsFocus = root.current?.contains(active);
+			const first = Array.from(document.querySelectorAll("[data-flow-waterfall]")).find((element) => element.getClientRects().length > 0);
+			if (!ownsFocus && (active !== document.body || first !== root.current)) return;
+			event.preventDefault();
+			search.current?.focus();
+			search.current?.select();
+		};
+		document.addEventListener("keydown", keydown);
+		return () => document.removeEventListener("keydown", keydown);
+	}, []);
+	const rows = useMemo(() => flowWaterfallRows(currentTrace), [currentTrace]);
+	const visible = visibleFlowWaterfallRows(rows, query, collapsed);
+	const slowest = rows.filter((row) => !row.hasChildren && row.kind !== "pipeline" && row.durationLabel !== "—").reduce((best, row) => !best || row.span.endMs - row.span.startMs > best.span.endMs - best.span.startMs ? row : best, void 0);
+	const summary = [
+		["Duration", seconds(totalMs)],
+		["Cost", trace.costUsd === void 0 ? "Unknown" : `$${trace.costUsd.toFixed(trace.costUsd < .01 ? 6 : 4)}`],
+		["Tokens", (trace.promptTokens + trace.completionTokens).toLocaleString()],
+		["LLM calls", trace.modelCalls === void 0 ? "Unknown" : String(trace.modelCalls)],
+		["Tool calls", String(trace.toolCalls)],
+		["Errors", String(trace.errors ?? trace.spans.filter(spanFailed).length)]
+	];
+	const toggle = (id) => setCollapsed((previous) => {
+		const next = new Set(previous);
+		if (next.has(id)) next.delete(id);
+		else next.add(id);
+		return next;
+	});
+	return /* @__PURE__ */ jsxs("section", {
+		ref: root,
+		"data-flow-waterfall": true,
+		"aria-label": label,
+		className: "fw-root",
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "fw-heading",
+				children: [/* @__PURE__ */ jsxs("div", {
+					className: "fw-title",
+					children: [label, isLive && /* @__PURE__ */ jsx("span", {
+						className: "fw-muted",
+						children: "Live"
+					})]
+				}), /* @__PURE__ */ jsxs("div", {
+					className: "fw-search",
+					children: [
+						/* @__PURE__ */ jsx("label", {
+							htmlFor: searchId,
+							className: "fw-sr-only",
+							children: "Search trace"
+						}),
+						/* @__PURE__ */ jsx("input", {
+							ref: search,
+							id: searchId,
+							type: "search",
+							value: query,
+							placeholder: "Search trace…",
+							"aria-keyshortcuts": "Meta+f Control+f",
+							onChange: (event) => setQuery(event.target.value),
+							onKeyDown: (event) => {
+								if (event.key === "Escape") {
+									setQuery("");
+									event.stopPropagation();
+								}
+							},
+							className: `${controlClass} fw-search-input`
+						}),
+						/* @__PURE__ */ jsx("button", {
+							type: "button",
+							"aria-label": "Focus trace search",
+							title: "Search trace (⌘F / Ctrl+F)",
+							onClick: () => search.current?.focus(),
+							className: controlClass,
+							children: "⌘F"
+						})
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsx("dl", {
+				className: "fw-summary",
+				children: summary.map(([name, value]) => /* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("dt", {
+					className: "fw-muted",
+					children: name
+				}), /* @__PURE__ */ jsx("dd", {
+					className: "fw-value",
+					title: name === "LLM calls" && trace.modelCalls === void 0 ? "Model output windows do not establish the number of LLM requests" : void 0,
+					children: value
+				})] }, name))
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "fw-legend",
+				"aria-label": "Span types",
+				children: Object.entries(TONES).map(([kind, tone]) => /* @__PURE__ */ jsxs("span", {
+					className: "fw-legend-item",
+					children: [/* @__PURE__ */ jsx("span", {
+						"aria-hidden": true,
+						className: `fw-dot ${tone.color}`
+					}), tone.label]
+				}, kind))
+			}),
+			rows.some((row) => row.hasChildren) && /* @__PURE__ */ jsxs("div", {
+				className: "fw-branches",
+				children: [/* @__PURE__ */ jsx("button", {
+					type: "button",
+					className: controlClass,
+					onClick: () => setCollapsed(/* @__PURE__ */ new Set()),
+					children: "Expand all"
+				}), /* @__PURE__ */ jsx("button", {
+					type: "button",
+					className: controlClass,
+					onClick: () => setCollapsed(new Set(rows.filter((row) => row.hasChildren).map((row) => row.id))),
+					children: "Collapse all"
+				})]
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "fw-timeline",
+				role: "region",
+				"aria-label": "Trace timeline",
+				tabIndex: 0,
+				children: /* @__PURE__ */ jsxs("div", {
+					className: "fw-track",
+					children: [
+						/* @__PURE__ */ jsxs("div", {
+							className: "fw-axis fw-grid",
+							children: [
+								/* @__PURE__ */ jsxs("span", { children: [
+									"Steps · ",
+									visible.length,
+									"/",
+									rows.length
+								] }),
+								/* @__PURE__ */ jsx("div", { children: /* @__PURE__ */ jsx(WaterfallTimeAxis, {
+									fluid: true,
+									windowMs: totalMs,
+									widthPx: 240,
+									formatDuration: seconds
+								}) }),
+								/* @__PURE__ */ jsx("span", {
+									className: "fw-align-right",
+									children: "Duration"
+								})
+							]
+						}),
+						visible.length === 0 && /* @__PURE__ */ jsx("p", {
+							role: "status",
+							className: "fw-empty",
+							children: rows.length === 0 ? "No spans yet. Waiting for trace events." : `No matching steps for “${query}”.`
+						}),
+						visible.map((row) => {
+							const tone = !row.ok ? TONES.failed : TONES[row.kind];
+							const pending = row.span.startMs > playhead;
+							const running = spanRunning(row.span);
+							return /* @__PURE__ */ jsx("div", {
+								"data-span-id": row.id,
+								"data-span-kind": !row.ok ? "failed" : row.kind,
+								"data-slowest": row.id === slowest?.id || void 0,
+								className: `fw-row ${row.id === slowest?.id ? "fw-slowest" : ""} ${pending ? "fw-pending" : ""}`,
+								children: /* @__PURE__ */ jsx(WaterfallRow, {
+									className: "fw-grid",
+									style: { display: "grid" },
+									startMs: row.span.startMs,
+									endMs: row.span.endMs,
+									window: {
+										startMs: 0,
+										endMs: totalMs
+									},
+									fluid: true,
+									color: "var(--fw-bar-color)",
+									barClassName: `fw-bar ${tone.color} ${row.approx ? "fw-approx" : ""}`,
+									timingClassName: "fw-bar-track",
+									durationClassName: "fw-duration",
+									durationLabel: row.durationLabel,
+									formatDuration: seconds,
+									clipAtMs: position === null ? void 0 : playhead,
+									overlay: position !== null && /* @__PURE__ */ jsx("span", {
+										className: "fw-playhead",
+										style: { left: `${playhead / (totalMs || 1) * 100}%` }
+									}),
+									label: /* @__PURE__ */ jsxs("div", {
+										className: "fw-name",
+										style: { paddingLeft: Math.min(row.depth, 8) * 12 },
+										children: [row.hasChildren ? /* @__PURE__ */ jsx("button", {
+											type: "button",
+											"aria-label": `${collapsed.has(row.id) && !query ? "Expand" : "Collapse"} ${row.name}`,
+											"aria-expanded": query ? true : !collapsed.has(row.id),
+											onClick: () => toggle(row.id),
+											disabled: Boolean(query.trim()),
+											className: "fw-toggle",
+											children: collapsed.has(row.id) && !query ? "›" : "⌄"
+										}) : /* @__PURE__ */ jsx("span", {
+											className: "fw-leaf",
+											"aria-hidden": true,
+											children: "·"
+										}), /* @__PURE__ */ jsxs("span", {
+											title: `${row.name} · ${tone.label}${running ? " · running" : ""}`,
+											className: "fw-span-name",
+											children: [
+												row.name,
+												!row.ok && /* @__PURE__ */ jsx("span", {
+													className: "fw-error-text",
+													children: " · failed"
+												}),
+												running && /* @__PURE__ */ jsx("span", {
+													className: "fw-muted",
+													children: " · running"
+												})
+											]
+										})]
+									})
+								})
+							}, row.id);
+						})
+					]
+				})
+			}),
+			slowest && /* @__PURE__ */ jsxs("p", {
+				className: "fw-slowest-caption",
+				children: [
+					"Slowest step: ",
+					/* @__PURE__ */ jsx("span", {
+						className: "fw-text",
+						children: slowest.name
+					}),
+					" · ",
+					slowest.durationLabel
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "fw-playback",
+				children: [
+					/* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: controlClass,
+						disabled: totalMs === 0,
+						onClick: () => {
+							if (playing) setPlaying(false);
+							else {
+								if (position === null || position >= totalMs) setPosition(0);
+								setPlaying(true);
+							}
+						},
+						children: playing ? "Pause" : "Play"
+					}),
+					/* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: controlClass,
+						disabled: totalMs === 0,
+						onClick: () => {
+							setPosition(0);
+							setPlaying(false);
+						},
+						children: "Restart"
+					}),
+					/* @__PURE__ */ jsxs("label", {
+						className: "fw-speed",
+						children: ["Speed", /* @__PURE__ */ jsx("select", {
+							"aria-label": "Playback speed",
+							className: controlClass,
+							value: speed,
+							onChange: (event) => setSpeed(Number(event.target.value)),
+							children: SPEEDS.map((value) => /* @__PURE__ */ jsxs("option", {
+								value,
+								children: [value, "x"]
+							}, value))
+						})]
+					}),
+					/* @__PURE__ */ jsxs("label", {
+						className: "fw-position",
+						children: ["Position", /* @__PURE__ */ jsx("input", {
+							"aria-label": "Playback position",
+							type: "range",
+							min: 0,
+							max: totalMs || 1,
+							step: "any",
+							value: playhead,
+							disabled: totalMs === 0,
+							onChange: (event) => {
+								setPosition(Number(event.target.value));
+								setPlaying(false);
+							},
+							className: "fw-slider"
+						})]
+					}),
+					/* @__PURE__ */ jsx("output", {
+						className: "fw-time",
+						"aria-label": "Playback time",
+						children: seconds(playhead)
+					}),
+					position !== null && /* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: controlClass,
+						onClick: () => {
+							setPosition(null);
+							setPlaying(false);
+						},
+						children: isLive ? "Follow live" : "Show full trace"
+					})
+				]
+			})
+		]
+	});
+}
+//#endregion
+export { DEFAULT_SPARKLINE_EMPTY_LABEL, DEFAULT_SPARKLINE_HEIGHT, DEFAULT_SPARKLINE_LABEL, DEFAULT_SPARKLINE_UNAVAILABLE_LABEL, DEFAULT_SPARKLINE_WIDTH, DOT_MAP_CATEGORIES, DayBars, DotMap, Events, FigureView, FlowWaterfall, Gantt, HBars, Histogram, LIVE_SERIES, Lines, Meter, Spark, Sparkline, StackedBarChart, TimelineView, WaterfallBar, WaterfallHeader, WaterfallRow, WaterfallTimeAxis, formatCompact, formatSparklineValue, formatWaterfallDuration, sparklineGeometry, sparklineLabel, sparklinePointsAttribute, sparklineReadings, waterfallSpanGeometry, waterfallTicks };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/charts",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Static SVG and HTML figures for benchmarks and operational timing. Draws from producer data and refuses what it cannot draw honestly.",
   "type": "module",
   "license": "MIT",
@@ -14,7 +14,8 @@
   "homepage": "https://github.com/tangle-network/charts",
   "sideEffects": [
     "./dist/figure.css",
-    "./dist/react/live.css"
+    "./dist/react/live.css",
+    "./dist/react/flow-waterfall.css"
   ],
   "files": [
     "dist",
@@ -32,7 +33,8 @@
       "types": "./dist/react/index.d.ts",
       "import": "./dist/react/index.js",
       "default": "./dist/react/index.js"
-    }
+    },
+    "./react/flow-waterfall.css": "./dist/react/flow-waterfall.css"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"
@@ -44,7 +46,7 @@
   },
   "scripts": {
     "gen:css": "node scripts/gen-css.mjs",
-    "build": "node scripts/gen-css.mjs --check && tsdown && cp src/figure.css dist/figure.css && cp src/react/live.css dist/react/live.css",
+    "build": "node scripts/gen-css.mjs --check && tsdown && cp src/figure.css dist/figure.css && cp src/react/live.css dist/react/live.css && cp src/react/flow-waterfall.css dist/react/flow-waterfall.css",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
@@ -55,6 +57,7 @@
     "@types/node": "^26.6.3",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.2.3",
+    "esbuild": "^0.28.2",
     "jsdom": "^30.1.1",
     "playwright": "^1.63.0",
     "react": "^19.3.0",