@tangle-network/charts 2.0.0 → 2.0.2

package/README.md

@@ -6,6 +6,8 @@ The React entry also exports `DayBars`, `HBars`, `Histogram`, `Lines`, `Meter`,
 
 `FlowWaterfall` from `@tangle-network/charts/react` is the shared live trace inspector: an agent timeline (one row per agent, elbow handoffs, hatched waiting) and a virtualized span waterfall over one clock. It owns hierarchy layout, folding, search, playback, zoom, span cards 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. Every color, radius and shadow in it is a Brand role (text, card, hairline, well, chart grid, status inks, the categorical tones for agents), so the host loads `@tangle-network/brand` `tokens.css` (or `legacy-light.css`) and sets its theme; the stylesheet has no color of its own. The React-free root exports the `FlowSpan` and `FlowTrace` types.
 
+`FlowWaterfall` accepts optional `graph` and `latestEvents` React nodes. Supplying `graph` adds Graph to its existing Agents/Steps view control, including `defaultView="graph"`. The trace clock and controlled selection survive switches. Graph hides waterfall-only controls; `latestEvents` stays mounted in the header across all views.
+
 `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:
@@ -350,3 +352,4 @@ CHARTS_REACT_VERSION=19 CHARTS_PROOF_DIR=/tmp/charts-react19 node scripts/charts
 ```
 
 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/react/flow-waterfall.css

@@ -21,8 +21,8 @@
   --fw-h1: light-dark(oklch(from var(--tone-blue-icon) .58 .11 calc(h + 39)), oklch(from var(--tone-blue-icon) .67 .11 calc(h + 39)));
   --fw-h2: light-dark(oklch(from var(--tone-violet-icon) .55 .11 h), oklch(from var(--tone-violet-icon) .70 .11 h));
   --fw-h3: light-dark(oklch(from var(--tone-pink-icon) .55 .11 h), oklch(from var(--tone-pink-icon) .67 .11 calc(h - 16)));
-  --fw-h4: light-dark(oklch(from var(--tone-cyan-icon) .60 .11 calc(h - 16.256)), oklch(from var(--tone-cyan-icon) .67 .11 calc(h - 26.148)));
-  --fw-h5: light-dark(oklch(from var(--tone-blue-icon) .58 .03 calc(h + 37.6)), oklch(from var(--tone-blue-icon) .67 .03 calc(h + 29.5)));
+  --fw-h4: light-dark(oklch(from var(--tone-cyan-icon) .578 .11 calc(h - 22.894)), oklch(from var(--tone-cyan-icon) .67 .11 calc(h - 26.148)));
+  --fw-h5: light-dark(oklch(from var(--tone-blue-icon) .58 .11 calc(h + 37.6)), oklch(from var(--tone-blue-icon) .67 .11 calc(h + 29.5)));
   --fw-ease: var(--ease-standard, cubic-bezier(.2,.8,.2,1));
   --fw-bar-h: 20px;
   --fw-label-col: min(var(--fw-name-w), 42%);
@@ -83,11 +83,13 @@
 .fw-root .fw-search-input::placeholder { color: var(--fw-muted); }
 .fw-root .fw-search-input::-webkit-search-cancel-button { display: none; }
 
-.fw-root .fw-summary { display: grid; grid-template-columns: repeat(6, minmax(0, 1fr)); border-bottom: 1px solid var(--fw-border); }
+.fw-root .fw-summary { display: flex; flex-wrap: wrap; align-items: center; border-bottom: 1px solid var(--fw-border); }
 .fw-root .fw-summary > div { padding: 12px 16px; min-width: 0; }
-.fw-root .fw-summary > div + div { border-left: 1px solid var(--fw-border); }
-.fw-root .fw-summary dt { font-size: 14px; line-height: 18px; color: var(--fw-muted); }
-.fw-root .fw-value { margin-top: 4px; font-size: 18px; line-height: 24px; font-weight: 600; letter-spacing: -.01em; font-variant-numeric: tabular-nums; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.fw-root .fw-summary > div:nth-child(-n+2) { flex: 1; }
+.fw-root .fw-summary > div:nth-child(n+3) { display: flex; align-items: baseline; gap: 4px; padding: 8px 6px; color: var(--fw-muted); }
+.fw-root .fw-summary dt { font-size: 14px; line-height: 20px; color: var(--fw-muted); }
+.fw-root .fw-value { margin-top: 4px; font-size: 28px; line-height: 34px; font-weight: 600; letter-spacing: -.02em; font-variant-numeric: tabular-nums; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.fw-root .fw-summary > div:nth-child(n+3) .fw-value { margin: 0; font-size: 14px; line-height: 20px; font-weight: 500; letter-spacing: normal; }
 .fw-root .fw-has-errors .fw-value { color: var(--fw-failed); }
 
 .fw-root .fw-axis { display: grid; grid-template-columns: var(--fw-label-col) minmax(0, 1fr); height: 32px; color: var(--fw-muted); font-size: 14px; }
@@ -203,7 +205,7 @@
 .fw-root :is(.fw-bar, .fw-seg):hover { filter: brightness(1.18); box-shadow: inset 0 0 0 1px var(--line), 0 0 0 2px color-mix(in oklab, var(--line) 55%, transparent); z-index: 1; }
 .fw-root .fw-bar.fw-k-tool { background: var(--dim); box-shadow: inset 0 0 0 1px var(--dim-line); }
 .fw-root .fw-bar.fw-k-handoff { background: var(--line); height: 8px; top: calc(50% + var(--fw-bar-shift) - 4px); box-shadow: none; }
-.fw-root .fw-bar.fw-k-waiting { background: repeating-linear-gradient(-45deg, var(--fw-hatch) 0 1px, transparent 1px 5px); box-shadow: inset 0 0 0 1px var(--fw-hatch); }
+.fw-root .fw-bar.fw-k-waiting, .fw-root .fw-kinds .fw-swatch-wait { background: repeating-linear-gradient(-45deg, var(--fw-hatch) 0 1px, transparent 1px 5px); box-shadow: inset 0 0 0 1px var(--fw-hatch); }
 .fw-root .fw-bar.fw-k-failed { background: color-mix(in oklab, var(--fw-failed) 22%, var(--fw-surface)); box-shadow: inset 0 0 0 1px var(--fw-failed); color: var(--fw-failed); }
 .fw-root .fw-bar.fw-k-pipeline { background: linear-gradient(90deg, var(--fw-neutral-bar), color-mix(in oklab, var(--fw-neutral-bar) 55%, var(--fw-surface))); box-shadow: inset 0 0 0 1px color-mix(in oklab, var(--fw-text) 12%, transparent); }
 .fw-root .fw-bar.fw-k-pipeline.fw-has-marks { background: repeating-linear-gradient(-45deg, var(--fw-hatch) 0 1px, transparent 1px 5px); box-shadow: inset 0 0 0 1px var(--fw-hatch); }
@@ -227,7 +229,7 @@
 .fw-root.fw-fill-agent .fw-kinds .fw-swatch-model { background: var(--model-fill); }
 .fw-root.fw-fill-agent .fw-kinds .fw-swatch-tool { background: var(--tool-fill); }
 .fw-root .fw-kinds .fw-swatch-tool { width: 12px; height: 8px; border-radius: 2px; background: var(--fw-kind-tool); }
-.fw-root .fw-kinds .fw-swatch-wait { width: 12px; height: 8px; border-radius: 2px; background: color-mix(in oklab, var(--fw-text) 12%, transparent); box-shadow: inset 0 0 0 1px color-mix(in oklab, var(--fw-text) 18%, transparent); }
+.fw-root .fw-kinds .fw-swatch-wait { width: 12px; height: 8px; border-radius: 2px; }
 .fw-root .fw-kinds .fw-swatch-event { width: 8px; height: 8px; border-radius: 50%; background: var(--fw-muted); box-shadow: 0 0 0 2px var(--fw-surface); }
 .fw-root .fw-kinds .fw-swatch-handoff { width: 10px; height: 8px; border-left: 1.5px solid var(--fw-muted); border-bottom: 1.5px solid var(--fw-muted); border-bottom-left-radius: 3px; }
 .fw-root .fw-description { margin: 0; color: var(--fw-muted); font-size: 14px; line-height: 20px; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
@@ -266,11 +268,11 @@
 .fw-root .fw-glyph svg { width: 11px; height: 11px; stroke-width: 2; }
 .fw-root .fw-seg-model .fw-glyph, .fw-root .fw-k-model .fw-glyph { color: light-dark(var(--tone), var(--fw-text)); }
 .fw-root .fw-end { z-index: 2; display: inline-flex; align-items: center; gap: 8px; top: calc(50% + var(--fw-bar-shift) - var(--fw-bar-h) / 2); height: var(--fw-bar-h);
-  left: min(calc(var(--x0) + max(var(--w), 3px) + 4px), calc(100% - var(--fw-end-w, 0px) - var(--fw-badge-w, 0px) - 4px)); padding: 0 4px; border-radius: var(--radius-tag);
+  left: min(calc(var(--x0) + max(var(--w), 3px) + 4px), calc(100% - var(--fw-end-w, 0px) - 4px)); padding: 0 4px; border-radius: var(--radius-tag);
   background: linear-gradient(var(--fw-tint, transparent) 0 0), var(--fw-surface); white-space: nowrap; pointer-events: none; }
 .fw-root .fw-duration { font-size: 14px; color: var(--fw-muted); font-variant-numeric: tabular-nums; }
 .fw-root .fw-k-failed ~ .fw-end .fw-duration { color: var(--fw-failed); }
-.fw-root .fw-badge { height: 20px; padding: 0 8px; border-radius: var(--radius-pill); font-size: 14px; line-height: 20px; font-weight: 500; color: var(--fw-muted); background: transparent; box-shadow: inset 0 0 0 1px var(--fw-border); }
+.fw-root .fw-badge { display: inline-flex; flex: none; height: 18px; padding: 0 6px; border-radius: var(--radius-pill); font-size: 12px; line-height: 18px; font-weight: 500; color: var(--fw-muted); background: transparent; box-shadow: inset 0 0 0 1px var(--fw-border); }
 
 .fw-root .fw-links { position: absolute; top: 0; bottom: 0; left: var(--fw-label-col); right: 0; overflow: hidden; pointer-events: none; z-index: 0; }
 .fw-root .fw-link {
@@ -384,10 +386,7 @@
 .fw-root .fw-card .fw-agent-dot:not([data-outcome]) { background: transparent; box-shadow: inset 0 0 0 1.5px var(--fw-muted); }
 @container flow-waterfall (max-width: 599px) {
   .fw-root > * { --fw-label-col: 0px; --fw-bar-shift: 8px; --fw-bar-h: 8px; --fw-row-h: 44px; }
-  .fw-root .fw-summary { grid-template-columns: repeat(3, minmax(0, 1fr)); }
-  .fw-root .fw-summary > div { padding: 8px; }
-  .fw-root .fw-summary > div:nth-child(4) { border-left: 0; }
-  .fw-root .fw-summary > div:nth-child(n+4) { border-top: 1px solid var(--fw-border); }
+  .fw-root .fw-summary > div:nth-child(-n+2) { flex-basis: 50%; padding: 6px 8px; }
   .fw-root :is(.fw-zoom, .fw-branch-controls, .fw-resize, .fw-links, .fw-gridlayer, .fw-marker-layer, .fw-subtitle, .fw-badge, .fw-icon-tile) { display: none; }
   .fw-root .fw-row-state { display: inline; }
   .fw-root .fw-key > summary { display: flex; align-items: center; min-height: 32px; cursor: pointer; }

package/dist/react/index.d.ts

@@ -459,7 +459,7 @@ export declare function flowWaterfallRows(trace: FlowTrace, resolutionMs?: numbe
 export declare function criticalPathIds(rows: readonly FlowWaterfallRow[]): ReadonlySet<string>;
 //#endregion
 //#region src/react/flow-waterfall-row.d.ts
-type FlowView = 'spans' | 'agents';
+type FlowView = 'spans' | 'agents' | 'graph';
 //#endregion
 //#region src/react/flow-waterfall-time.d.ts
 interface ViewWindow {
@@ -480,6 +480,10 @@ interface FlowWaterfallProps {
   defaultCollapsed?: boolean;
   /** `agents` shows one row per agent (the agent timeline); expanding a row opens the full span tree. */
   defaultView?: FlowView;
+  /** Host graph rendered by the same view control, retaining the trace clock and selection. */
+  graph?: ReactNode;
+  /** Shared header feed, kept mounted across Agents, Steps and Graph. */
+  latestEvents?: ReactNode;
   /** Host brand marks by span; the inspector draws kind glyphs without it. */
   renderIcon?: (span: FlowSpan) => ReactNode;
   /** Scroll height of the rows; the tree is virtualized beyond it. Defaults to 20 agent rows, or 640 px of steps. */
@@ -519,7 +523,7 @@ interface FlowWaterfallProps {
 }
 /** Shared trace inspector: the agent timeline and the span waterfall over one clock.
  * Data remains producer-owned; playback, zoom and folding change presentation only. */
-export declare function FlowWaterfall({ trace, live, startedAt, label, defaultCollapsed, defaultView, renderIcon, maxHeight, onSelect, markers, onTimeChange, agentFill: fillProp, selectedId, onDeselect, description, summary: showSummary, criticalPath, query: queryProp, onQueryChange, collapsed: collapsedProp, onCollapsedChange, zoom: zoomProp, onZoomChange, matchSpan }: FlowWaterfallProps): import("react").JSX.Element;
+export declare function FlowWaterfall({ trace, live, startedAt, label, defaultCollapsed, defaultView, graph, latestEvents, renderIcon, maxHeight, onSelect, markers, onTimeChange, agentFill: fillProp, selectedId, onDeselect, description, summary: showSummary, criticalPath, query: queryProp, onQueryChange, collapsed: collapsedProp, onCollapsedChange, zoom: zoomProp, onZoomChange, matchSpan }: FlowWaterfallProps): import("react").JSX.Element;
 //#endregion
 //#region src/react/flow-waterfall-icons.d.ts
 /** Kind glyphs drawn when the host supplies no `renderIcon`. Brand marks belong to the host. */

package/dist/react/index.js

@@ -6822,17 +6822,15 @@ function criticalPathIds(rows) {
 function agentCallouts(agents, clockMs) {
 	let slowest, slowestMs = -1, costliest, top = -1, priced = 0, timed = 0;
 	for (const row of agents) {
-		if (row.durationLabel === "—" || row.span.startMs > clockMs || row.kind !== "pipeline" || row.id.startsWith("family:") || row.id.startsWith("run:")) continue;
-		if (row.parentId !== void 0) {
-			const ms = (spanRunning(row.span) ? Math.max(row.span.endMs, clockMs) : Math.min(row.span.endMs, clockMs)) - row.span.startMs;
-			timed += 1;
-			if (ms > slowestMs) {
-				slowest = row;
-				slowestMs = ms;
-			}
+		if (row.durationLabel === "—" || row.span.startMs > clockMs || row.kind !== "pipeline" || row.hasAgents || row.id.startsWith("family:") || row.id.startsWith("run:")) continue;
+		const ms = (spanRunning(row.span) ? Math.max(row.span.endMs, clockMs) : Math.min(row.span.endMs, clockMs)) - row.span.startMs;
+		timed += 1;
+		if (ms > slowestMs) {
+			slowest = row;
+			slowestMs = ms;
 		}
 		const cost = row.span.costUsd ?? row.rollupCostUsd;
-		if (cost === void 0) continue;
+		if (typeof cost !== "number" || !Number.isFinite(cost)) continue;
 		priced += 1;
 		if (cost > top) {
 			costliest = row;
@@ -6934,10 +6932,15 @@ function agentFamilies(agents, open) {
 	const hue = (row) => row.tone <= 0 || ++next > 5 ? 0 : 1 + [...roleOf(row.name)].reduce((hash, c) => hash * 31 + c.charCodeAt(0) >>> 0, 0) % 5;
 	for (const [role, members] of groups) {
 		if (members.length < 2) {
-			out.push(...members.map((row) => ({
+			const row = members[0], tone = hue(row);
+			out.push({
 				...row,
-				tone: hue(row)
-			})));
+				tone,
+				own: row.own.map((mark) => ({
+					...mark,
+					tone
+				}))
+			});
 			continue;
 		}
 		const tone = hue(members[0]);
@@ -7361,6 +7364,7 @@ function Table({ rows }) {
 /** The span card: what ran, for how long, on what tokens and at what recorded cost, then its input and output. */
 function SpanCard({ id, row, agent, clockMs, left, top, pinned, onClose, renderIcon, compact }) {
 	const span = row.span;
+	const failure = span.facts?.find((fact) => fact.label.toLowerCase() === "failure")?.value;
 	const state = runStatus(span.status ?? "unknown");
 	const meta = statusMeta(state);
 	const status = meta.label;
@@ -7433,14 +7437,14 @@ function SpanCard({ id, row, agent, clockMs, left, top, pinned, onClose, renderI
 						close
 					]
 				}),
-				/* @__PURE__ */ jsx(Table, { rows: metrics(who, clockMs, false) }),
+				/* @__PURE__ */ jsx(Table, { rows: metrics(who, clockMs, false).filter(([label]) => label.toLowerCase() !== "failure") }),
 				step && /* @__PURE__ */ jsx("p", {
 					className: "fw-card-step",
 					children: step
 				}),
-				!row.ok && /* @__PURE__ */ jsxs("p", {
+				!row.ok && /* @__PURE__ */ jsx("p", {
 					className: "fw-card-error",
-					children: ["Error: ", span.output ?? who.span.output ?? "No error detail reported"]
+					children: failure ? `Failure: ${failure}` : span.output ? `Recorded output: ${span.output}` : "Failure detail not reported"
 				}),
 				sentence && row.ok && /* @__PURE__ */ jsx("p", {
 					className: "fw-card-result",
@@ -7487,6 +7491,10 @@ function SpanCard({ id, row, agent, clockMs, left, top, pinned, onClose, renderI
 				]
 			}),
 			/* @__PURE__ */ jsx(Table, { rows: metrics(row, clockMs, true) }),
+			!row.ok && !span.output && !failure && /* @__PURE__ */ jsx("p", {
+				className: "fw-card-error",
+				children: "Failure detail not reported"
+			}),
 			span.input && /* @__PURE__ */ jsxs("div", {
 				className: "fw-card-text",
 				children: [/* @__PURE__ */ jsx("div", {
@@ -7498,7 +7506,7 @@ function SpanCard({ id, row, agent, clockMs, left, top, pinned, onClose, renderI
 				className: "fw-card-text",
 				children: [/* @__PURE__ */ jsx("div", {
 					className: "fw-card-label",
-					children: row.ok ? "Output" : "Error"
+					children: row.ok ? "Output" : "Recorded output"
 				}), /* @__PURE__ */ jsx("p", { children: span.output })]
 			})
 		]
@@ -7597,6 +7605,15 @@ const FlowRow = memo(function FlowRow(props) {
 	const step = agentView && row.stepOf !== void 0;
 	const opens = family || agentView && isAgent && row.own.length > 0;
 	const outcomes = row.outcomes ?? (span.outcome ? [span.outcome] : []);
+	const callouts = /* @__PURE__ */ jsxs(Fragment, { children: [slowest && /* @__PURE__ */ jsx("span", {
+		className: "fw-badge",
+		title: agentView ? "Longest elapsed leaf agent" : "Longest elapsed leaf step",
+		children: agentView ? "Longest leaf" : "Longest step"
+	}), costliest && /* @__PURE__ */ jsx("span", {
+		className: "fw-badge",
+		title: "Highest reported cost among priced leaf agents",
+		children: "Costliest leaf"
+	})] });
 	return /* @__PURE__ */ jsxs("div", {
 		role: "row",
 		"data-span-id": row.id,
@@ -7616,8 +7633,7 @@ const FlowRow = memo(function FlowRow(props) {
 		style: {
 			"--row-y": `${top}px`,
 			"--fw-enter-delay": `${motion?.enter ?? 0}ms`,
-			"--fw-end-w": `${endLabelWidth(label)}px`,
-			"--fw-badge-w": `${(slowest ? 80 : 0) + (costliest ? 90 : 0)}px`
+			"--fw-end-w": `${endLabelWidth(label)}px`
 		},
 		onFocus: (event) => {
 			if (event.target === event.currentTarget) props.onActivate(row);
@@ -7708,7 +7724,8 @@ const FlowRow = memo(function FlowRow(props) {
 								className: "fw-name-text",
 								children: row.name
 							}),
-							(state === "failed" || state === "needs-you") && /* @__PURE__ */ jsx("span", {
+							!agentView && callouts,
+							state !== "unknown" && !activity.quiet && /* @__PURE__ */ jsx("span", {
 								className: "fw-row-state",
 								style: { color: `var(${meta.token})` },
 								children: meta.label
@@ -7726,13 +7743,17 @@ const FlowRow = memo(function FlowRow(props) {
 							children: renderIcon(span)
 						}), /* @__PURE__ */ jsxs("span", {
 							className: "fw-subtitle-tail",
-							children: [/* @__PURE__ */ jsx("span", {
-								className: "fw-subtitle-text",
-								children: summary[0]
-							}), summary.slice(1).map((part) => /* @__PURE__ */ jsxs("span", {
-								className: "fw-subtitle-extra",
-								children: ["· ", part]
-							}, part))]
+							children: [
+								callouts,
+								/* @__PURE__ */ jsx("span", {
+									className: "fw-subtitle-text",
+									children: summary[0]
+								}),
+								summary.slice(1).map((part) => /* @__PURE__ */ jsxs("span", {
+									className: "fw-subtitle-extra",
+									children: ["· ", part]
+								}, part))
+							]
 						})]
 					})]
 				}),
@@ -7750,7 +7771,7 @@ const FlowRow = memo(function FlowRow(props) {
 			role: "gridcell",
 			className: "fw-lane",
 			"data-waterfall-track": true,
-			"aria-label": `${KIND_LABEL[span.kind]}, ${label}${slowest ? `, slowest ${agentView ? "agent" : "step"}` : ""}${costliest ? ", costliest agent" : ""}${critical ? ", critical path" : ""}`,
+			"aria-label": `${KIND_LABEL[span.kind]}, ${label}${slowest ? `, longest leaf ${agentView ? "agent" : "step"}` : ""}${costliest ? ", highest reported leaf-agent cost" : ""}${critical ? ", critical path" : ""}`,
 			children: invalid ? /* @__PURE__ */ jsx("span", {
 				className: "fw-invalid",
 				children: "—"
@@ -7792,23 +7813,13 @@ const FlowRow = memo(function FlowRow(props) {
 					events: props,
 					agentView
 				}, `${mark.id}-${i}`)),
-				/* @__PURE__ */ jsxs("span", {
+				/* @__PURE__ */ jsx("span", {
 					className: "fw-end",
 					style: at(span.startMs, running ? OPEN_END : span.endMs),
-					children: [
-						/* @__PURE__ */ jsx("span", {
-							className: "fw-duration",
-							children: label
-						}),
-						slowest && /* @__PURE__ */ jsx("span", {
-							className: "fw-badge",
-							children: "Slowest"
-						}),
-						costliest && /* @__PURE__ */ jsx("span", {
-							className: "fw-badge",
-							children: "Costliest"
-						})
-					]
+					children: /* @__PURE__ */ jsx("span", {
+						className: "fw-duration",
+						children: label
+					})
 				})
 			] })
 		})]
@@ -7960,7 +7971,8 @@ function clampWindow(view, limitMs) {
 //#region src/react/flow-waterfall-body.tsx
 const ROW_HEIGHT = {
 	spans: 36,
-	agents: 40
+	agents: 40,
+	graph: 40
 };
 const OVERSCAN = 8;
 /** Rows re-render once per CHUNK rows scrolled; overscan covers the rows in between. */
@@ -8690,11 +8702,13 @@ const AGENT_ROWS = 20;
 const UNFOLD_ROWS = 12;
 const END_LABEL_GUTTER = {
 	spans: 120,
-	agents: 176
+	agents: 176,
+	graph: 176
 };
 const NAME_WIDTH = {
 	spans: 320,
-	agents: 240
+	agents: 240,
+	graph: 240
 };
 /** State the host may own: its value wins when given, and every change is reported either way. */
 function useHostable(value, onChange, initial) {
@@ -8771,7 +8785,7 @@ const TONE_ORDER = [
 	"ok"
 ];
 /** What each mark means, as the agent view draws it; a key only for kinds the run has. */
-function KindLegend({ rows }) {
+function KindLegend({ rows, fill }) {
 	const has = (kind) => rows.some((row) => row.own.some((mark) => mark.kind === kind) || row.span.kind === kind);
 	const shown = [
 		["model", "Model call"],
@@ -8780,13 +8794,19 @@ function KindLegend({ rows }) {
 		["handoff", "Handoff"]
 	].filter(([kind]) => kind === "waiting" ? rows.some((row) => row.kind === "pipeline") : kind === "handoff" ? rows.some((row) => row.span.handoffTo || row.hasAgents) : has(kind));
 	if (shown.length === 0) return null;
-	return /* @__PURE__ */ jsx("ul", {
+	const example = rows.find((row) => toneKey(row.tone) > 0 && row.own.some((mark) => mark.kind === "model")) ?? rows.find((row) => row.own.length);
+	return /* @__PURE__ */ jsxs("ul", {
 		className: "fw-legend fw-kinds",
 		"aria-label": "Key",
-		children: shown.map(([kind, name]) => /* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("span", {
+		"data-tone": fill === "agent" ? toneKey(example?.tone ?? 0) : void 0,
+		"data-example": example?.id,
+		children: [shown.map(([kind, name]) => /* @__PURE__ */ jsxs("li", { children: [/* @__PURE__ */ jsx("span", {
 			className: `fw-swatch-${kind === "waiting" ? "wait" : kind}`,
 			"aria-hidden": true
-		}), name] }, kind))
+		}), name] }, kind)), /* @__PURE__ */ jsx("li", {
+			className: "fw-kind-rule",
+			children: fill === "agent" ? "Bar color identifies family; shade identifies work." : "Shade identifies work."
+		})]
 	});
 }
 /** The axis dots and the dashed lines they drop: one key naming what they mark (a release, or the kinds the host gave). */
@@ -8886,17 +8906,37 @@ function OutcomeLegend({ agents, selected, onFilter, neutral }) {
 		]
 	});
 }
+function ViewControl({ view, graph, onChange }) {
+	return /* @__PURE__ */ jsx("div", {
+		className: "fw-views",
+		role: "radiogroup",
+		"aria-label": "Trace view",
+		children: [
+			"agents",
+			"spans",
+			...graph ? ["graph"] : []
+		].map((option) => /* @__PURE__ */ jsx("button", {
+			type: "button",
+			role: "radio",
+			"aria-checked": view === option,
+			disabled: view === option,
+			className: "fw-view-button",
+			onClick: () => onChange(option),
+			children: option === "agents" ? "Agents" : option === "spans" ? "Steps" : "Graph"
+		}, option))
+	});
+}
 /** Shared trace inspector: the agent timeline and the span waterfall over one clock.
 * Data remains producer-owned; playback, zoom and folding change presentation only. */
-function FlowWaterfall({ trace, live, startedAt, label = "Trace waterfall", defaultCollapsed = false, defaultView = "spans", renderIcon, maxHeight, onSelect, markers, onTimeChange, agentFill: fillProp, selectedId, onDeselect, description, summary: showSummary = true, criticalPath = false, query: queryProp, onQueryChange, collapsed: collapsedProp, onCollapsedChange, zoom: zoomProp, onZoomChange, matchSpan }) {
+function FlowWaterfall({ trace, live, startedAt, label = "Trace waterfall", defaultCollapsed = false, defaultView = "spans", graph, latestEvents, renderIcon, maxHeight, onSelect, markers, onTimeChange, agentFill: fillProp, selectedId, onDeselect, description, summary: showSummary = true, criticalPath = false, query: queryProp, onQueryChange, collapsed: collapsedProp, onCollapsedChange, zoom: zoomProp, onZoomChange, matchSpan }) {
 	const root = useRef(null);
 	const search = useRef(null);
 	const slider = useRef(null);
 	const timeOutput = useRef(null);
 	const hideTimer = useRef(void 0);
-	const searchId = useId();
-	const cardId = useId();
-	const [view, setView] = useState(defaultView);
+	const searchId = useId(), cardId = useId();
+	const [requestedView, setView] = useState(defaultView);
+	const view = requestedView === "graph" && graph == null ? "agents" : requestedView;
 	const [query, setQuery] = useHostable(queryProp, onQueryChange, "");
 	const [collapsed, setCollapsed] = useHostable(collapsedProp, onCollapsedChange, () => new Set(defaultCollapsed ? trace.spans.flatMap((span) => span.parentId ? [span.parentId] : []) : []));
 	const [speed, setSpeed] = useState(1);
@@ -9012,6 +9052,7 @@ function FlowWaterfall({ trace, live, startedAt, label = "Trace waterfall", defa
 	}, [view, agents]);
 	useEffect(() => {
 		const keydown = (event) => {
+			if (view === "graph") return;
 			const active = document.activeElement;
 			const ownsFocus = root.current?.contains(active);
 			if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "f") {
@@ -9326,7 +9367,7 @@ function FlowWaterfall({ trace, live, startedAt, label = "Trace waterfall", defa
 									done && speedup >= 1.05 ? ` · ${speedup.toFixed(1)}x parallel` : ""
 								]
 							}),
-							failedAgents > 0 && /* @__PURE__ */ jsxs("button", {
+							view !== "graph" && failedAgents > 0 && /* @__PURE__ */ jsxs("button", {
 								type: "button",
 								className: "fw-text-button fw-alert",
 								"aria-pressed": filter === "__errors",
@@ -9338,7 +9379,7 @@ function FlowWaterfall({ trace, live, startedAt, label = "Trace waterfall", defa
 									" failed"
 								]
 							}),
-							quietAgents > 0 && /* @__PURE__ */ jsxs("button", {
+							view !== "graph" && quietAgents > 0 && /* @__PURE__ */ jsxs("button", {
 								type: "button",
 								className: "fw-text-button fw-quiet",
 								"aria-pressed": filter === "__quiet",
@@ -9351,7 +9392,7 @@ function FlowWaterfall({ trace, live, startedAt, label = "Trace waterfall", defa
 								children: "Live"
 							})
 						]
-					}), /* @__PURE__ */ jsxs("details", {
+					}), view !== "graph" && /* @__PURE__ */ jsxs("details", {
 						className: "fw-key",
 						open: root.current ? root.current.clientWidth >= 600 : true,
 						children: [/* @__PURE__ */ jsxs("summary", { children: ["Key", /* @__PURE__ */ jsx(ChevronGlyph, {})] }), /* @__PURE__ */ jsxs("div", {
@@ -9363,30 +9404,24 @@ function FlowWaterfall({ trace, live, startedAt, label = "Trace waterfall", defa
 									selected: filter,
 									onFilter: applyFilter
 								}),
-								view === "agents" && /* @__PURE__ */ jsx(KindLegend, { rows }),
+								view === "agents" && /* @__PURE__ */ jsx(KindLegend, {
+									rows: visible,
+									fill: agentFill
+								}),
 								/* @__PURE__ */ jsx(MarkerLegend, { markers })
 							]
 						})]
 					})]
 				}), /* @__PURE__ */ jsxs("div", {
 					className: "fw-tools",
-					children: [/* @__PURE__ */ jsx("div", {
-						className: "fw-views",
-						role: "radiogroup",
-						"aria-label": "Trace view",
-						children: ["agents", "spans"].map((option) => /* @__PURE__ */ jsx("button", {
-							type: "button",
-							role: "radio",
-							"aria-checked": view === option,
-							disabled: view === option,
-							className: "fw-view-button",
-							onClick: () => {
-								setView(option);
-								setNameWidth(NAME_WIDTH[option]);
-								setCard(null);
-							},
-							children: option === "agents" ? "Agents" : "Steps"
-						}, option))
+					children: [/* @__PURE__ */ jsx(ViewControl, {
+						view,
+						graph: graph != null,
+						onChange: (option) => {
+							setView(option);
+							setNameWidth(NAME_WIDTH[option]);
+							setCard(null);
+						}
 					}), view === "spans" && /* @__PURE__ */ jsxs("div", {
 						className: "fw-search",
 						children: [
@@ -9420,91 +9455,94 @@ function FlowWaterfall({ trace, live, startedAt, label = "Trace waterfall", defa
 					})]
 				})]
 			}),
-			showSummary && /* @__PURE__ */ jsx("dl", {
-				className: "fw-summary",
-				children: summary.map(([name, value, title]) => /* @__PURE__ */ jsxs("div", {
-					className: name === "Errors" && errors !== void 0 && errors > 0 ? "fw-has-errors" : void 0,
-					children: [/* @__PURE__ */ jsx("dt", { children: name }), /* @__PURE__ */ jsx("dd", {
-						className: "fw-value",
-						title,
-						children: name === "Errors" ? /* @__PURE__ */ jsx("button", {
-							type: "button",
-							"aria-pressed": filter === "__errors",
-							onClick: () => applyFilter("__errors"),
-							children: value
-						}) : value
-					})]
-				}, name))
-			}),
-			view === "agents" && playback,
-			/* @__PURE__ */ jsx(FlowBody, {
-				rows: visible,
-				byId,
-				totalRows: rows.length,
-				view,
-				maxHeight: rowsHeight,
-				collapsed,
-				searching: Boolean(query.trim()),
-				query,
-				matchSpan,
-				pauses: trace.pauses,
-				errorTimes,
-				cursorLine: isLive || position !== null || playing,
-				sharedDetail,
-				sharedOutcome,
-				expandedIds: view === "agents" ? /* @__PURE__ */ new Set([...openFamilies, ...openSteps]) : void 0,
-				holdHeight: isLive,
-				slowestId: slowest?.id ?? callouts.slowestId,
-				costliestId: callouts.costliestId,
-				criticalIds: criticalPath && view === "spans" ? critical : void 0,
-				activeId,
-				selectedId: selection,
-				focusId: cardAgent?.id ?? (view === "agents" ? activeId : void 0),
-				clockMs,
-				window: win,
-				trackPx,
-				showCursor,
-				markers,
-				fillByAgent: agentFill !== "outcome",
-				zoomed: zoom !== null,
-				renderIcon,
-				emptyText: rows.length === 0 ? "No spans yet. Waiting for trace events." : `No matching steps for “${query}”.`,
-				onToggle: toggle,
-				onInspect: inspect,
-				onLeave: leave,
-				onPin: pin,
-				onActivate: (row) => setActiveId(row.id),
-				onActiveChange: setActiveId,
-				onScrub: scrubTo,
-				onZoom: zoomBy,
-				onPan: pan,
-				nameWidth,
-				onNameWidth: (px) => {
-					resized.current = true;
-					setNameWidth(Math.max(140, Math.min(560, px)));
-				},
-				onTrack: setLaneElement,
-				onExpandAll: rows.some((row) => row.hasChildren) ? () => setCollapsed(/* @__PURE__ */ new Set()) : void 0,
-				onCollapseAll: () => setCollapsed(new Set(rows.filter((row) => row.hasChildren).map((row) => row.id)))
-			}),
-			card && cardRow && /* @__PURE__ */ jsx("div", {
-				className: `fw-card-anchor${card.above && card.top === void 0 ? " fw-card-above" : ""}`,
-				onPointerEnter: () => clearTimeout(hideTimer.current),
-				onPointerLeave: card.pinned ? void 0 : leave,
-				children: /* @__PURE__ */ jsx(SpanCard, {
-					id: cardId,
-					row: cardRow,
-					agent: cardAgent,
+			latestEvents,
+			view === "graph" ? graph : /* @__PURE__ */ jsxs(Fragment, { children: [
+				showSummary && /* @__PURE__ */ jsx("dl", {
+					className: "fw-summary",
+					children: summary.map(([name, value, title]) => /* @__PURE__ */ jsxs("div", {
+						className: name === "Errors" && errors !== void 0 && errors > 0 ? "fw-has-errors" : void 0,
+						children: [/* @__PURE__ */ jsx("dt", { children: name }), /* @__PURE__ */ jsx("dd", {
+							className: "fw-value",
+							title,
+							children: name === "Errors" ? /* @__PURE__ */ jsx("button", {
+								type: "button",
+								"aria-pressed": filter === "__errors",
+								onClick: () => applyFilter("__errors"),
+								children: value
+							}) : value
+						})]
+					}, name))
+				}),
+				view === "agents" && playback,
+				/* @__PURE__ */ jsx(FlowBody, {
+					rows: visible,
+					byId,
+					totalRows: rows.length,
+					view,
+					maxHeight: rowsHeight,
+					collapsed,
+					searching: Boolean(query.trim()),
+					query,
+					matchSpan,
+					pauses: trace.pauses,
+					errorTimes,
+					cursorLine: isLive || position !== null || playing,
+					sharedDetail,
+					sharedOutcome,
+					expandedIds: view === "agents" ? /* @__PURE__ */ new Set([...openFamilies, ...openSteps]) : void 0,
+					holdHeight: isLive,
+					slowestId: slowest?.id ?? callouts.slowestId,
+					costliestId: callouts.costliestId,
+					criticalIds: criticalPath && view === "spans" ? critical : void 0,
+					activeId,
+					selectedId: selection,
+					focusId: cardAgent?.id ?? (view === "agents" ? activeId : void 0),
 					clockMs,
-					left: card.left,
-					top: card.top ?? (card.above ? card.anchorTop - 8 : card.anchorBottom + 8),
-					pinned: card.pinned,
-					onClose: closeCard,
+					window: win,
+					trackPx,
+					showCursor,
+					markers,
+					fillByAgent: agentFill !== "outcome",
+					zoomed: zoom !== null,
 					renderIcon,
-					compact: view === "agents"
-				})
-			}),
-			view === "spans" && playback
+					emptyText: rows.length === 0 ? "No spans yet. Waiting for trace events." : `No matching steps for “${query}”.`,
+					onToggle: toggle,
+					onInspect: inspect,
+					onLeave: leave,
+					onPin: pin,
+					onActivate: (row) => setActiveId(row.id),
+					onActiveChange: setActiveId,
+					onScrub: scrubTo,
+					onZoom: zoomBy,
+					onPan: pan,
+					nameWidth,
+					onNameWidth: (px) => {
+						resized.current = true;
+						setNameWidth(Math.max(140, Math.min(560, px)));
+					},
+					onTrack: setLaneElement,
+					onExpandAll: rows.some((row) => row.hasChildren) ? () => setCollapsed(/* @__PURE__ */ new Set()) : void 0,
+					onCollapseAll: () => setCollapsed(new Set(rows.filter((row) => row.hasChildren).map((row) => row.id)))
+				}),
+				card && cardRow && /* @__PURE__ */ jsx("div", {
+					className: `fw-card-anchor${card.above && card.top === void 0 ? " fw-card-above" : ""}`,
+					onPointerEnter: () => clearTimeout(hideTimer.current),
+					onPointerLeave: card.pinned ? void 0 : leave,
+					children: /* @__PURE__ */ jsx(SpanCard, {
+						id: cardId,
+						row: cardRow,
+						agent: cardAgent,
+						clockMs,
+						left: card.left,
+						top: card.top ?? (card.above ? card.anchorTop - 8 : card.anchorBottom + 8),
+						pinned: card.pinned,
+						onClose: closeCard,
+						renderIcon,
+						compact: view === "agents"
+					})
+				}),
+				view === "spans" && playback
+			] })
 		]
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/charts",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "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",