@tangle-network/charts 0.21.11 → 0.21.13

package/dist/react/flow-waterfall.css

@@ -222,6 +222,8 @@
 .fw-root .fw-settle .fw-end { animation: fw-land 260ms var(--fw-ease); }
 /* A live bar grows with the clock instead of stepping each tick. */
 .fw-root .fw-row[data-running] .fw-bar { transition: width 120ms linear; }
+/* The chain that gates the trace's end: an accent edge under its bars, so cutting latency there is visibly what moves the end. */
+.fw-root .fw-row[data-critical] .fw-bar { box-shadow: inset 0 -2px 0 var(--fw-accent); }
 /* A restart: an amber notch through the bar at that moment; the bar keeps its own state. */
 .fw-root .fw-mark { position: absolute; z-index: 2; left: calc(var(--x0) - 1px); width: 2px; top: calc(50% + var(--fw-bar-shift) - var(--fw-bar-h) / 2 - 4px); height: calc(var(--fw-bar-h) + 8px);
   border-radius: 2px; background: var(--fw-amber); box-shadow: 0 0 0 1px var(--fw-surface); opacity: var(--on); pointer-events: auto; }
@@ -321,10 +323,6 @@
 
 /* Span card */
 .fw-root .fw-card-anchor { display: contents; }
-/* Agent view: the card docks under the lanes instead of floating over the plot (judges: "covers the data it describes"). */
-/* Two classes on the root so these win over the base .fw-root .fw-card rule that follows. */
-.fw-root.fw-root-agents .fw-card-anchor { display: block; padding: 0 24px 12px; }
-.fw-root.fw-root-agents .fw-card, .fw-root.fw-root-agents .fw-card-above .fw-card { position: relative; left: auto !important; top: auto !important; transform: none; animation-name: fw-arrive; width: auto; max-width: 560px; }
 .fw-root .fw-seg-alt { filter: brightness(.78); }
 /* Agent view: the scrubber track shows how far the run has played, so at rest it reads full, not empty. */
 .fw-root.fw-root-agents .fw-slider { background: linear-gradient(90deg, color-mix(in oklab, var(--fw-text) 32%, transparent) var(--fw-progress), var(--fw-well) var(--fw-progress)) 0 50% / 100% 4px no-repeat; }

package/dist/react/index.d.ts

@@ -376,6 +376,12 @@ export declare function DotMap({ positions, radii, colors, palette, extent, rect
 //#region src/react/flow-waterfall-row.d.ts
 type FlowView = 'spans' | 'agents';
 //#endregion
+//#region src/react/flow-waterfall-time.d.ts
+interface ViewWindow {
+  startMs: number;
+  endMs: number;
+}
+//#endregion
 //#region src/react/flow-waterfall.d.ts
 interface FlowWaterfallProps {
   trace: FlowTrace;
@@ -412,9 +418,22 @@ interface FlowWaterfallProps {
   onDeselect?: () => void;
   /** Show the stat strip (default); a page with its own stat row passes false. */
   summary?: boolean;
+  /** Mark the steps on the chain that gates the trace's end. */
+  criticalPath?: boolean;
+  /** Controlled search text; pass with `onQueryChange` to keep it in the host's state, such as the URL. */
+  query?: string;
+  onQueryChange?: (query: string) => void;
+  /** Controlled folded span ids; pass with `onCollapsedChange`. Overrides `defaultCollapsed`. */
+  collapsed?: ReadonlySet<string>;
+  onCollapsedChange?: (collapsed: ReadonlySet<string>) => void;
+  /** Controlled time window, `null` for the whole trace; pass with `onZoomChange`. */
+  zoom?: ViewWindow | null;
+  onZoomChange?: (zoom: ViewWindow | null) => void;
+  /** Replaces the built-in search match (name, model, kind, status), such as to search the host's attributes. */
+  matchSpan?: (span: FlowSpan, query: string) => boolean;
 }
 /** 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 }: FlowWaterfallProps): import("react").JSX.Element;
+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;
 //#endregion
-export type { BandKind, ChartBand, ChartMark, DotMapLabel, DotMapProps, DotMapRect, Figure, FigureAtWidth, FigureViewProps, FlowWaterfallProps, GapBand, GapProps, 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 };
+export type { BandKind, ChartBand, ChartMark, DotMapLabel, DotMapProps, DotMapRect, Figure, FigureAtWidth, FigureViewProps, FlowWaterfallProps, ViewWindow as FlowWaterfallWindow, GapBand, GapProps, 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

@@ -2591,13 +2591,13 @@ function segmentOf(row) {
 	};
 }
 /** Search keeps ancestor context and deliberately reveals matches inside collapsed branches. */
-function visibleFlowWaterfallRows(rows, query, collapsed) {
+function visibleFlowWaterfallRows(rows, query, collapsed, matchSpan) {
 	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.span.detail ?? ""} ${row.kind} ${row.ok ? "" : "failed"} ${row.span.status ?? ""}`.toLowerCase().includes(term)) continue;
+			if (matchSpan ? !matchSpan(row.span, query.trim()) : !`${row.name} ${row.span.detail ?? ""} ${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);
@@ -2628,6 +2628,28 @@ function slowestRow(rows, clockMs) {
 	}
 	return best;
 }
+/** The chain of steps that gates the trace's end: from each root, descend into the latest-ending child until a leaf; the root whose
+* chain ends last wins. Cutting latency anywhere else leaves the trace's end unchanged. */
+function criticalPathIds(rows) {
+	const children = /* @__PURE__ */ new Map();
+	for (const row of rows) if (row.parentId) children.set(row.parentId, [...children.get(row.parentId) ?? [], row]);
+	let best;
+	for (const root of rows) {
+		if (root.parentId) continue;
+		const chain = [];
+		let end = root.span.endMs;
+		for (let cursor = root; cursor;) {
+			chain.push(cursor.id);
+			end = Math.max(end, cursor.span.endMs);
+			cursor = children.get(cursor.id)?.reduce((latest, child) => !latest || child.span.endMs > latest.span.endMs ? child : latest, void 0);
+		}
+		if (!best || end > best.end) best = {
+			end,
+			chain
+		};
+	}
+	return new Set(best?.chain);
+}
 /** The agents a reader should look at first: the longest one by the clock, and the costliest when two or more are priced. */
 function agentCallouts(agents, clockMs) {
 	let slowest, slowestMs = -1, costliest, top = -1, priced = 0, timed = 0;
@@ -3324,7 +3346,7 @@ function endLabel(row, clockMs) {
 }
 /** One trace row. Geometry comes from CSS variables, so a row re-renders only when its own state changes. */
 const FlowRow = memo(function FlowRow(props) {
-	const { row, view, top, collapsed, searching, slowest, costliest, active, focusable, selected, sticky, clockMs, renderIcon, fillByAgent, motion } = props;
+	const { row, view, top, collapsed, searching, slowest, costliest, critical, active, focusable, selected, sticky, clockMs, renderIcon, fillByAgent, motion } = props;
 	const span = row.span;
 	const running = spanRunning(span);
 	const agentView = view === "agents";
@@ -3345,6 +3367,7 @@ const FlowRow = memo(function FlowRow(props) {
 		"data-span-id": row.id,
 		"data-span-kind": kind,
 		"data-slowest": slowest || void 0,
+		"data-critical": critical || void 0,
 		"data-running": running || void 0,
 		"aria-level": agentView ? void 0 : row.depth + 1,
 		"aria-expanded": row.hasChildren && !agentView ? !folded : void 0,
@@ -3477,7 +3500,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" : ""}`,
+			"aria-label": `${KIND_LABEL[span.kind]}, ${label}${slowest ? `, slowest ${agentView ? "agent" : "step"}` : ""}${costliest ? ", costliest agent" : ""}${critical ? ", critical path" : ""}`,
 			children: invalid ? /* @__PURE__ */ jsx("span", {
 				className: "fw-invalid",
 				children: "—"
@@ -3539,7 +3562,7 @@ const FlowRow = memo(function FlowRow(props) {
 			] })
 		})]
 	});
-}, (a, b) => a.row === b.row && a.view === b.view && a.top === b.top && a.collapsed === b.collapsed && a.searching === b.searching && a.slowest === b.slowest && a.costliest === b.costliest && a.active === b.active && a.focusable === b.focusable && a.selected === b.selected && a.sticky === b.sticky && a.motion === b.motion && a.renderIcon === b.renderIcon && a.fillByAgent === b.fillByAgent && a.sharedDetail === b.sharedDetail && a.expanded === b.expanded && (a.clockMs === b.clockMs || !open(a.row, a.clockMs) && !open(b.row, b.clockMs)));
+}, (a, b) => a.row === b.row && a.view === b.view && a.top === b.top && a.collapsed === b.collapsed && a.searching === b.searching && a.slowest === b.slowest && a.costliest === b.costliest && a.critical === b.critical && a.active === b.active && a.focusable === b.focusable && a.selected === b.selected && a.sticky === b.sticky && a.motion === b.motion && a.renderIcon === b.renderIcon && a.fillByAgent === b.fillByAgent && a.sharedDetail === b.sharedDetail && a.expanded === b.expanded && (a.clockMs === b.clockMs || !open(a.row, a.clockMs) && !open(b.row, b.clockMs)));
 /** An elbow connector between two rows at one moment, drawn in the row's tone; appears when the clock reaches it. */
 function LinkMark({ link, rowHeight, hot }) {
 	const upper = Math.min(link.from, link.to), lower = Math.max(link.from, link.to);
@@ -3997,6 +4020,7 @@ function FlowBody(props) {
 		searching,
 		slowest: item.id === slowestId,
 		costliest: item.id === props.costliestId,
+		critical: props.criticalIds?.has(item.id),
 		active: item.id === activeId,
 		focusable: !isSticky && (item.id === activeId || (activeId === void 0 || !index.has(activeId)) && i === 0),
 		selected: item.id === selectedId,
@@ -4372,6 +4396,22 @@ const NAME_WIDTH = {
 	spans: 320,
 	agents: 240
 };
+/** State the host may own: its value wins when given, and every change is reported either way. */
+function useHostable(value, onChange, initial) {
+	const [own, setOwn] = useState(initial);
+	const current = value === void 0 ? own : value;
+	const latest = useRef(current);
+	latest.current = current;
+	const report = useRef(onChange);
+	report.current = onChange;
+	const controlled = value !== void 0;
+	return [current, useCallback((next) => {
+		const resolved = typeof next === "function" ? next(latest.current) : next;
+		latest.current = resolved;
+		if (!controlled) setOwn(resolved);
+		report.current?.(resolved);
+	}, [controlled])];
+}
 /** The summary strip: as of the playhead while scrubbing, the producer's totals otherwise. */
 function summaryCells(trace, at, durationMs) {
 	const cost = costSummary(at ? at.costUsd : trace.costUsd, trace);
@@ -4474,7 +4514,7 @@ function OutcomeLegend({ agents }) {
 }
 /** 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 }) {
+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 }) {
 	const root = useRef(null);
 	const search = useRef(null);
 	const slider = useRef(null);
@@ -4483,12 +4523,12 @@ function FlowWaterfall({ trace, live, startedAt, label = "Trace waterfall", defa
 	const searchId = useId();
 	const cardId = useId();
 	const [view, setView] = useState(defaultView);
-	const [query, setQuery] = useState("");
-	const [collapsed, setCollapsed] = useState(() => new Set(defaultCollapsed ? trace.spans.flatMap((span) => span.parentId ? [span.parentId] : []) : []));
+	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);
 	const [playing, setPlaying] = useState(false);
 	const [position, setPosition] = useState(null);
-	const [zoom, setZoom] = useState(null);
+	const [zoom, setZoom] = useHostable(zoomProp, onZoomChange, null);
 	const [nameWidth, setNameWidth] = useState(NAME_WIDTH[defaultView]);
 	const [laneWidth, setLaneWidth] = useState(0);
 	const [card, setCard] = useState(null);
@@ -4544,6 +4584,7 @@ function FlowWaterfall({ trace, live, startedAt, label = "Trace waterfall", defa
 		resolution
 	]);
 	const byId = useMemo(() => new Map(rows.map((row) => [row.id, row])), [rows]);
+	const critical = useMemo(() => criticalPathIds(rows), [rows]);
 	const agents = useMemo(() => {
 		const pipelines = rows.filter((row) => row.kind === "pipeline");
 		return pipelines.length ? pipelines : rows.filter((row) => !row.parentId);
@@ -4552,14 +4593,15 @@ function FlowWaterfall({ trace, live, startedAt, label = "Trace waterfall", defa
 	const [flippedFamilies, setFlippedFamilies] = useState(/* @__PURE__ */ new Set());
 	const openFamilies = useMemo(() => defaultOpenFamilies(agents, UNFOLD_ROWS, flippedFamilies), [agents, flippedFamilies]);
 	const [openSteps, setOpenSteps] = useState(/* @__PURE__ */ new Set());
-	const visible = useMemo(() => view === "agents" ? agentViewRows(agents, rows, openFamilies, openSteps) : visibleFlowWaterfallRows(rows, query, collapsed), [
+	const visible = useMemo(() => view === "agents" ? agentViewRows(agents, rows, openFamilies, openSteps) : visibleFlowWaterfallRows(rows, query, collapsed, matchSpan), [
 		view,
 		agents,
 		rows,
 		openFamilies,
 		openSteps,
 		query,
-		collapsed
+		collapsed,
+		matchSpan
 	]);
 	const slowest = view === "spans" ? slowestRow(rows, clockMs) : void 0;
 	const callouts = useMemo(() => view === "agents" ? agentCallouts(visible, clockMs) : {}, [
@@ -4940,6 +4982,7 @@ function FlowWaterfall({ trace, live, startedAt, label = "Trace waterfall", defa
 				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),

package/package.json

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