@tangle-network/charts 0.21.12 → 0.21.14

package/dist/react/flow-waterfall.css

@@ -222,6 +222,11 @@
 .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); }
+/* While searching, ancestors shown only for context recede and the matching names stand out. */
+.fw-root .fw-row[data-search="context"] .fw-label { opacity: 0.55; }
+.fw-root .fw-row[data-search="match"] .fw-name-text { font-weight: 600; }
 /* 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; }

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

@@ -2590,15 +2590,19 @@ function segmentOf(row) {
 		name: row.name
 	};
 }
+/** The rows a search term matches by themselves, before ancestor context is added. */
+function searchMatchIds(rows, query, matchSpan) {
+	const term = query.trim();
+	const lower = term.toLowerCase();
+	return new Set(rows.filter((row) => matchSpan ? matchSpan(row.span, term) : `${row.name} ${row.span.detail ?? ""} ${row.kind} ${row.ok ? "" : "failed"} ${row.span.status ?? ""}`.toLowerCase().includes(lower)).map((row) => row.id));
+}
 /** 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) {
+	if (query.trim()) {
 		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;
-			let cursor = row;
+		for (const id of searchMatchIds(rows, query, matchSpan)) {
+			let cursor = byId.get(id);
 			while (cursor && !matching.has(cursor.id)) {
 				matching.add(cursor.id);
 				cursor = cursor.parentId ? byId.get(cursor.parentId) : void 0;
@@ -2628,6 +2632,33 @@ 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) continue;
+		const siblings = children.get(row.parentId);
+		if (siblings) siblings.push(row);
+		else children.set(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 +3355,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, matched, active, focusable, selected, sticky, clockMs, renderIcon, fillByAgent, motion } = props;
 	const span = row.span;
 	const running = spanRunning(span);
 	const agentView = view === "agents";
@@ -3345,6 +3376,8 @@ 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-search": searching ? matched ? "match" : "context" : 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 +3510,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 +3572,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.matched === b.matched && 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);
@@ -3751,6 +3784,12 @@ function FlowBody(props) {
 		props.byId,
 		view
 	]);
+	const matched = useMemo(() => searching ? searchMatchIds(rows, props.query, props.matchSpan) : void 0, [
+		searching,
+		rows,
+		props.query,
+		props.matchSpan
+	]);
 	const index = useMemo(() => new Map(rows.map((row, i) => [row.id, i])), [rows]);
 	const motion = useRowMotion(rows);
 	const [jumped, setJumped] = useState();
@@ -3824,13 +3863,24 @@ function FlowBody(props) {
 	}, []);
 	const first = Math.max(0, chunk * CHUNK - OVERSCAN);
 	const last = Math.min(rows.length, chunk * CHUNK + Math.ceil(viewport / rowHeight) + CHUNK + OVERSCAN);
+	const scrollToRow = (i, element) => {
+		const offset = (view === "spans" ? Math.min(STICKY_LEVELS, rows[i].depth) : 0) * rowHeight;
+		if (i * rowHeight - offset < element.scrollTop) element.scrollTop = Math.max(0, i * rowHeight - offset);
+		else if ((i + 1) * rowHeight > element.scrollTop + element.clientHeight) element.scrollTop = (i + 1) * rowHeight - element.clientHeight;
+	};
+	const shownSelection = useRef(void 0);
+	useEffect(() => {
+		if (!selectedId || selectedId === shownSelection.current) return;
+		const i = index.get(selectedId);
+		if (i === void 0 || !scroller.current) return;
+		shownSelection.current = selectedId;
+		scrollToRow(i, scroller.current);
+	});
 	const focusRow = (id) => {
 		const i = index.get(id);
 		const element = scroller.current;
 		if (i === void 0 || !element) return;
-		const offset = (view === "spans" ? Math.min(STICKY_LEVELS, rows[i].depth) : 0) * rowHeight;
-		if (i * rowHeight - offset < element.scrollTop) element.scrollTop = Math.max(0, i * rowHeight - offset);
-		else if ((i + 1) * rowHeight > element.scrollTop + element.clientHeight) element.scrollTop = (i + 1) * rowHeight - element.clientHeight;
+		scrollToRow(i, element);
 		props.onActiveChange(id);
 		requestAnimationFrame(() => element.querySelector(`.fw-canvas [data-span-id="${CSS.escape(id)}"]`)?.focus({ preventScroll: true }));
 	};
@@ -3997,6 +4047,8 @@ function FlowBody(props) {
 		searching,
 		slowest: item.id === slowestId,
 		costliest: item.id === props.costliestId,
+		critical: props.criticalIds?.has(item.id),
+		matched: matched?.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 +4424,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 +4542,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 +4551,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 +4612,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 +4621,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) : {}, [
@@ -4933,6 +5003,8 @@ function FlowWaterfall({ trace, live, startedAt, label = "Trace waterfall", defa
 				maxHeight: rowsHeight,
 				collapsed,
 				searching: Boolean(query.trim()),
+				query,
+				matchSpan,
 				pauses: trace.pauses,
 				cursorLine: position !== null || playing,
 				sharedDetail,
@@ -4940,6 +5012,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.12",
+  "version": "0.21.14",
   "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",