@oh-my-pi/omp-stats 18.15.0 → 18.17.0

package/src/client/charts/DotWhisker.tsx

@@ -0,0 +1,149 @@
+import type { ReactNode } from "react";
+import { niceScale } from "./Chart";
+
+/** One estimate on a row: a point and its interval. */
+export interface DotWhiskerMark {
+	key: string;
+	value: number | null;
+	lo: number | null;
+	hi: number | null;
+	color: string;
+	/** `dot` (default) filled; `ring` hollow (a counterfactual); `diamond` a reference level; `square` a variant. */
+	shape?: "dot" | "ring" | "diamond" | "square";
+	/** Vertical offset from the row's center in px, to keep several marks of one row apart. */
+	offset?: number;
+	/** Hover text naming the mark. */
+	title?: string;
+}
+
+export interface DotWhiskerRow {
+	key: string;
+	label: ReactNode;
+	marks: readonly DotWhiskerMark[];
+	/** Right-column figure; defaults to the first mark's value. */
+	figure?: ReactNode;
+	/** Small print under the figure; defaults to the first mark's interval. */
+	detail?: ReactNode;
+}
+
+export interface DotWhiskerGuide {
+	key: string;
+	value: number;
+	color: string;
+}
+
+/** A shaded span through every row (e.g. a reference's interval). */
+export interface DotWhiskerBand {
+	lo: number;
+	hi: number;
+	color: string;
+}
+
+export interface DotWhiskerProps {
+	rows: readonly DotWhiskerRow[];
+	/** Vertical guides through every row (e.g. chance levels). */
+	guides?: readonly DotWhiskerGuide[];
+	band?: DotWhiskerBand;
+	format: (value: number) => string;
+	/** Axis tick formatter; defaults to `format`. */
+	formatTick?: (value: number) => string;
+}
+
+/**
+ * Point estimates with their intervals on one shared axis that always spans
+ * zero (and extends below it for signed values), one row per group. Layout is
+ * percentage-based, so it never measures the DOM.
+ */
+export function DotWhisker({ rows, guides, band, format, formatTick }: DotWhiskerProps) {
+	let max = 0;
+	let min = 0;
+	const extend = (v: number | null) => {
+		if (v === null) return;
+		max = Math.max(max, v);
+		min = Math.min(min, v);
+	};
+	for (const row of rows) {
+		for (const mark of row.marks) {
+			extend(mark.value);
+			extend(mark.lo);
+			extend(mark.hi);
+		}
+	}
+	for (const guide of guides ?? []) extend(guide.value);
+	if (band) {
+		extend(band.lo);
+		extend(band.hi);
+	}
+	const scale = niceScale(max, min);
+	const span = scale.max - scale.min;
+	const at = (v: number) => ((Math.min(scale.max, Math.max(scale.min, v)) - scale.min) / span) * 100;
+	const pct = (v: number) => `${at(v)}%`;
+	const underlay = (
+		<>
+			{band && (
+				<span
+					className="dw-band"
+					style={{ left: pct(band.lo), width: `${at(band.hi) - at(band.lo)}%`, "--band": band.color }}
+				/>
+			)}
+			{guides?.map(guide => (
+				<span key={guide.key} className="dw-guide" style={{ left: pct(guide.value), "--guide": guide.color }} />
+			))}
+		</>
+	);
+
+	return (
+		<div className="dw">
+			{rows.map(row => {
+				const first = row.marks[0];
+				const interval =
+					first !== undefined && first.lo !== null && first.hi !== null
+						? `${format(first.lo)}–${format(first.hi)}`
+						: "";
+				return (
+					<div key={row.key} className="dw-row">
+						<div className="dw-label">{row.label}</div>
+						<div className="dw-track">
+							{underlay}
+							{row.marks.map(mark => (
+								<span
+									key={mark.key}
+									className="dw-mark"
+									data-shape={mark.shape ?? "dot"}
+									style={{ "--dot": mark.color, "--dy": `${mark.offset ?? 0}px` }}
+								>
+									{mark.lo !== null && mark.hi !== null && (
+										<span
+											className="dw-whisker"
+											style={{ left: pct(mark.lo), width: `${at(mark.hi) - at(mark.lo)}%` }}
+										/>
+									)}
+									{mark.value !== null && (
+										<span className="dw-dot" style={{ left: pct(mark.value) }} title={mark.title} />
+									)}
+								</span>
+							))}
+						</div>
+						<div className="dw-value">
+							<span className="num">
+								{row.figure ?? (first?.value === null || first === undefined ? "–" : format(first.value))}
+							</span>
+							<span className="dw-detail">{row.detail ?? interval}</span>
+						</div>
+					</div>
+				);
+			})}
+			<div className="dw-row dw-axis" aria-hidden="true">
+				<div />
+				<div className="dw-track">
+					{scale.ticks.map(t => (
+						<span key={t} className="dw-tick" style={{ left: pct(t) }}>
+							{(formatTick ?? format)(t)}
+						</span>
+					))}
+				</div>
+				<div />
+			</div>
+		</div>
+	);
+}

package/src/client/charts/Sparkline.tsx

@@ -10,18 +10,19 @@ export interface SparklineProps {
 	area?: boolean;
 }
 
-/** Axis-free trend line for stat tiles and table cells. */
+/** Axis-free trend line for stat tiles and table cells; negative values dip below the zero line. */
 export function Sparkline({ values, color = "var(--chart-primary)", height = 28, width, area = true }: SparklineProps) {
 	const [ref, measured] = useWidth<HTMLDivElement>();
 	const w = width ?? measured;
 	const max = Math.max(0, ...values);
+	const min = Math.min(0, ...values);
 	const n = values.length;
 	let line = "";
 	if (w > 0 && n > 0) {
 		const step = n > 1 ? w / (n - 1) : 0;
 		for (let i = 0; i < n; i++) {
 			const x = n > 1 ? i * step : w / 2;
-			const y = max > 0 ? height - 2 - (values[i] / max) * (height - 4) : height - 2;
+			const y = max > min ? height - 2 - ((values[i] - min) / (max - min)) * (height - 4) : height - 2;
 			line += `${i === 0 ? "M" : "L"}${x.toFixed(1)},${y.toFixed(1)}`;
 		}
 	}

package/src/client/charts/Waterfall.tsx

@@ -0,0 +1,86 @@
+import type { ReactNode } from "react";
+
+export interface WaterfallStep {
+	key: string;
+	label: ReactNode;
+	/** `total` bars start at zero and reset the running total; `delta` bars float from it. */
+	kind: "total" | "delta";
+	/** A total's level, or a delta's signed change. */
+	value: number;
+	/** Any CSS background (solid color or gradient). */
+	color: string;
+	/** Dim figure after the value (e.g. share of the first total). */
+	note?: ReactNode;
+	title?: string;
+}
+
+export interface WaterfallProps {
+	steps: readonly WaterfallStep[];
+	/** Formats magnitudes; deltas get their sign from the component. */
+	format: (value: number) => string;
+}
+
+interface PlacedStep extends WaterfallStep {
+	from: number;
+	to: number;
+	/** Running total before this step (the connector's position). */
+	before: number;
+}
+
+/**
+ * Horizontal bridge chart: a total, the changes that eat into it, and the
+ * total left at the end. Rows read top to bottom; dashed connectors carry the
+ * running total from one bar to the next. Pure layout (percentages), so it
+ * never measures the DOM and reflows with its column.
+ */
+export function Waterfall({ steps, format }: WaterfallProps) {
+	let running = 0;
+	const placed: PlacedStep[] = steps.map(step => {
+		const before = running;
+		if (step.kind === "total") {
+			running = step.value;
+			return { ...step, from: 0, to: step.value, before };
+		}
+		running += step.value;
+		return { ...step, from: before, to: running, before };
+	});
+	let lo = 0;
+	let hi = 0;
+	for (const step of placed) {
+		lo = Math.min(lo, step.from, step.to);
+		hi = Math.max(hi, step.from, step.to);
+	}
+	const span = hi - lo || 1;
+	const pct = (v: number) => ((v - lo) / span) * 100;
+
+	return (
+		<ol className="waterfall">
+			{placed.map((step, i) => {
+				const left = pct(Math.min(step.from, step.to));
+				const width = Math.abs(pct(step.to) - pct(step.from));
+				const sign = step.kind === "delta" ? (step.value < 0 ? "−" : "+") : step.value < 0 ? "−" : "";
+				return (
+					<li key={step.key} className="waterfall-row" data-kind={step.kind} title={step.title}>
+						<span className="waterfall-label">{step.label}</span>
+						<span className="waterfall-track">
+							{lo < 0 && <span className="waterfall-zero" style={{ left: `${pct(0)}%` }} />}
+							{i > 0 && <span className="waterfall-link" style={{ left: `${pct(step.before)}%` }} />}
+							<span
+								className="waterfall-bar"
+								data-empty={step.value === 0}
+								style={{ left: `${left}%`, width: `${width}%`, "--bar": step.color }}
+							/>
+						</span>
+						<span className="waterfall-value">
+							<span className="num">
+								{sign}
+								{format(Math.abs(step.value))}
+							</span>
+							{step.note !== undefined && <span className="waterfall-note">{step.note}</span>}
+						</span>
+					</li>
+				);
+			})}
+		</ol>
+	);
+}

package/src/client/charts/index.ts

@@ -1,7 +1,9 @@
 export * from "./BarList";
 export * from "./Chart";
+export * from "./DotWhisker";
 export * from "./Legend";
 export * from "./ShareBar";
 export * from "./Sparkline";
 export * from "./TimeChart";
 export * from "./types";
+export * from "./Waterfall";

package/src/client/charts/types.ts

@@ -11,13 +11,20 @@ export interface ChartSeries {
 	axis?: "left" | "right";
 	/** Diagonal hatching instead of a solid fill (bars/areas). */
 	pattern?: "hatch";
-	/** Dashed stroke (lines). */
+	/** Dashed stroke (lines, area outlines). */
 	dashed?: boolean;
 	/** Leave this series out of the tooltip (e.g. a trend line that repeats a bar). */
 	tooltip?: false;
 }
 
-export type ChartKind = "bars" | "area" | "line";
+/** `dots` marks each value with a point and no connecting segment (raw samples under a trend line). */
+export type ChartKind = "bars" | "area" | "line" | "dots";
+
+/** Vertical guide at an x slot (e.g. an experiment start or a compaction). */
+export interface SlotMarker {
+	index: number;
+	label?: string;
+}
 
 /** Horizontal guide drawn across the plot (e.g. a 100% capacity line). */
 export interface ReferenceLine {

package/src/client/data/query.ts

@@ -15,6 +15,7 @@
  *   can resolve to that same object; an unchanged reference does not re-render.
  */
 
+import { toError } from "@oh-my-pi/pi-utils/type-guards";
 import { startTransition, useCallback, useEffect, useReducer, useRef, useState } from "react";
 import { currentLiveVersion, useLiveVersion } from "./live";
 import { cachedEntry, type Inflight, inflightRequest, loadQuery, type QueryFetcher, releaseQuery } from "./query-store";
@@ -60,6 +61,7 @@ export function useQuery<T>(key: readonly unknown[], fetcher: QueryFetcher<T>, o
 	const version = useLiveVersion(enabled);
 
 	const [, rerender] = useReducer((n: number) => n + 1, 0);
+	const [settled, recheck] = useReducer((n: number) => n + 1, 0);
 	const [error, setError] = useState<{ key: string; error: Error } | null>(null);
 	const [refreshing, setRefreshing] = useState(false);
 
@@ -82,8 +84,10 @@ export function useQuery<T>(key: readonly unknown[], fetcher: QueryFetcher<T>, o
 		waiting.current = { key: targetKey, request };
 		// Join the new request before leaving the old one, so a shared request isn't aborted in between.
 		if (current) releaseQuery(current.key, current.request);
+		let succeeded = false;
 		request.promise
 			.then(data => {
+				succeeded = true;
 				if (keyRef.current !== targetKey) return;
 				// Revalidated to the very same object: nothing on screen changes.
 				if (data === shownBefore) {
@@ -97,11 +101,15 @@ export function useQuery<T>(key: readonly unknown[], fetcher: QueryFetcher<T>, o
 			})
 			.catch((err: unknown) => {
 				if (keyRef.current !== targetKey || request.controller.signal.aborted) return;
-				setError({ key: targetKey, error: err instanceof Error ? err : new Error(String(err)) });
+				setError({ key: targetKey, error: toError(err) });
 			})
 			.finally(() => {
-				if (waiting.current?.request === request) waiting.current = null;
-				if (keyRef.current === targetKey) setRefreshing(false);
+				if (waiting.current?.request !== request) return;
+				waiting.current = null;
+				if (keyRef.current !== targetKey) return;
+				setRefreshing(false);
+				// A newer live version may have arrived while this older request was in flight.
+				if (succeeded && (cachedEntry(targetKey)?.version ?? -1) < currentLiveVersion()) recheck();
 			});
 	}, []);
 
@@ -128,7 +136,7 @@ export function useQuery<T>(key: readonly unknown[], fetcher: QueryFetcher<T>, o
 		}
 		const timer = setTimeout(() => run(keyString), wait);
 		return () => clearTimeout(timer);
-	}, [keyString, enabled, version, run, leave]);
+	}, [keyString, enabled, version, settled, run, leave]);
 
 	useEffect(() => {
 		if (!enabled || !pollMs) return;

package/src/client/react-css.d.ts

@@ -1,7 +1,7 @@
 import "react";
 
 declare module "react" {
-	/** Custom properties (`--arm`, `--i` …) in `style` objects, which React passes through to the element. */
+	/** Custom properties (`--kind`, `--i` …) in `style` objects, which React passes through to the element. */
 	interface CSSProperties {
 		[property: `--${string}`]: string | number | undefined;
 	}

package/src/client/routes/SpotlightRoute.tsx

@@ -0,0 +1,138 @@
+import { ScanSearch } from "lucide-react";
+import { useState } from "react";
+import { getSpotlightDashboardStats } from "../api";
+import { useQuery } from "../data/query";
+import { rangeMeta } from "../data/range";
+import { Compounding } from "../spotlight/Compounding";
+import { Coverage } from "../spotlight/Coverage";
+import { Economics } from "../spotlight/Economics";
+import { FetchBack, FetchBackGaps } from "../spotlight/FetchBack";
+import { SpotlightHero } from "../spotlight/Hero";
+import { Overhead } from "../spotlight/Overhead";
+import { Ranking } from "../spotlight/Ranking";
+import { ResultsFeed } from "../spotlight/ResultsFeed";
+import { SavingsOverTime, WhereSavingsWent } from "../spotlight/Savings";
+import { ShareTrend } from "../spotlight/ShareTrend";
+import { Steps } from "../spotlight/Steps";
+import { TimeCost } from "../spotlight/TimeCost";
+import type { SpotlightAgentScope, TimeRange } from "../types";
+import { Card, ChartSkeleton, PageHeader, QueryView, Segmented } from "../ui";
+import "../spotlight/spotlight.css";
+
+export interface SpotlightRouteProps {
+	active: boolean;
+	range: TimeRange;
+}
+
+const AGENT_OPTIONS = [
+	{ value: "all", label: "All", title: "Every experiment session, subagents and advisors included" },
+	{ value: "main", label: "Main", title: "Sessions you drove: the main agent only" },
+	{ value: "subagent", label: "Subagents", title: "Sessions the task tool spawned" },
+] as const;
+
+/** Prose for the scope in empty states ("main-agent "). */
+const AGENT_SCOPE_PROSE: Record<SpotlightAgentScope, string> = { all: "", main: "main-agent ", subagent: "subagent " };
+
+/** The page reads as four questions, in order; each heading opens the cards that answer one. */
+function SectionHeading({ id, title, children }: { id: string; title: string; children: string }) {
+	return (
+		<header className="spot-section rise" id={id}>
+			<h2 className="spot-section-title">{title}</h2>
+			<p className="spot-section-copy">{children}</p>
+		</header>
+	);
+}
+
+export function SpotlightRoute({ active, range }: SpotlightRouteProps) {
+	// Every experiment session shapes, subagents included; scoping keeps their very different workloads apart.
+	const [agent, setAgent] = useState<SpotlightAgentScope>("all");
+	const stats = useQuery(
+		["spotlight", range, agent],
+		({ signal }) => getSpotlightDashboardStats(range, agent, signal),
+		{ enabled: active },
+	);
+	const meta = rangeMeta(range);
+	const experimentStart = stats.data?.experimentStart ?? null;
+
+	return (
+		<div className="page spot-page">
+			<PageHeader
+				title="Spotlight"
+				description={`What shaping tool output saved in ${meta.windowLabel} against what pi would have shown unshaped, after taking back what the agent fetched again because of a cut.`}
+				actions={<Segmented aria-label="Sessions" options={AGENT_OPTIONS} value={agent} onChange={setAgent} />}
+			/>
+
+			<QueryView
+				query={stats}
+				skeleton={<ChartSkeleton height={220} />}
+				isEmpty={data => data.sessions === 0 && data.recent.length === 0}
+				empty={
+					<Card>
+						<div className="spot-empty">
+							<span className="spot-empty-icon" aria-hidden="true">
+								<ScanSearch size={20} />
+							</span>
+							<h2 className="spot-empty-title">
+								{experimentStart === null
+									? "The Spotlight experiment hasn't run yet"
+									: `No ${AGENT_SCOPE_PROSE[agent]}experiment sessions in ${meta.windowLabel}`}
+							</h2>
+							<p className="spot-empty-hint">
+								{experimentStart === null ? (
+									<>
+										Turn it on with <code>spotlight.experiment.enabled</code> in your settings or{" "}
+										<code>PI_SPOTLIGHT_EXPERIMENT=1</code>. Every session then shapes tool output, a random
+										share of results is held out unshaped as the counterfactual, and this page tracks what the
+										cuts save as you work.
+									</>
+								) : agent === "all" ? (
+									"Try a longer range, or start a session with the experiment enabled."
+								) : (
+									"Try a longer range, or switch to All sessions."
+								)}
+							</p>
+						</div>
+					</Card>
+				}
+			>
+				{data => (
+					<>
+						<SpotlightHero stats={data} windowLabel={meta.windowLabel} stale={stats.stale} />
+
+						<SectionHeading id="spot-saved" title="What it saved">
+							Where the saving came from, what fetch-backs took back, and what later requests no longer carry.
+						</SectionHeading>
+						<div className="grid grid-main-side">
+							<SavingsOverTime stats={data} range={range} stale={stats.stale} />
+							<WhereSavingsWent stats={data} stale={stats.stale} />
+						</div>
+						<Compounding stats={data} active={active} stale={stats.stale} />
+						<ShareTrend stats={data} range={range} stale={stats.stale} />
+
+						<SectionHeading id="spot-cost" title="What it cost">
+							Agent time, Spotlight's latency and failures, and whether shaped sessions got worse.
+						</SectionHeading>
+						<TimeCost stats={data} stale={stats.stale} />
+						<Overhead stats={data} stale={stats.stale} />
+
+						<SectionHeading id="spot-work" title="Is Spotlight doing the work?">
+							Whether its heat finds the lines the agent needs, and whether its cuts come back less than cuts
+							made without it.
+						</SectionHeading>
+						<Ranking stats={data} stale={stats.stale} />
+						<FetchBack stats={data} stale={stats.stale} />
+						<FetchBackGaps stats={data} stale={stats.stale} />
+
+						<SectionHeading id="spot-tune" title="Where to tune">
+							Which steps, sizes and tools pay, and which tools Spotlight doesn't shape yet.
+						</SectionHeading>
+						<Steps stats={data} stale={stats.stale} />
+						<Economics stats={data} stale={stats.stale} />
+						<Coverage stats={data} stale={stats.stale} />
+						<ResultsFeed rows={data.recent} stale={stats.stale} />
+					</>
+				)}
+			</QueryView>
+		</div>
+	);
+}

package/src/client/routes/index.ts

@@ -7,5 +7,6 @@ export * from "./OverviewRoute";
 export * from "./ProjectsRoute";
 export * from "./ProvidersRoute";
 export * from "./RequestsRoute";
+export * from "./SpotlightRoute";
 export * from "./ToolsRoute";
 export * from "./TracesRoute";