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

package/dist/types/spotlight-ingest.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Spotlight experiment facts the parser extracts from a session journal, for the Spotlight dashboard
+ * (`spotlight-aggregator.ts`).
+ *
+ * A session is an experiment session from its first Spotlight marker on (see {@link experimentMarker}); from then the
+ * parser records every evaluated result, every tool call (target, order, result size, the artifacts its result names)
+ * and every main-loop request, so recoveries of hidden output can be detected later. Evaluated results come from two
+ * entries that may land in different tail parses: the `spotlight:shape` journal entry (Spotlight's bill, timing) and
+ * the result message's `details.spotlight` (what the model saw, the hidden lines). Both upsert the same row.
+ *
+ * Each shaped read (applied, held out or score-free) also collects the original lines the agent needed later (see
+ * {@link SpotlightCollector}): its open reads ride in the parser state, so a later tail parse keeps collecting, and the
+ * lines land in `spotlight_needs`.
+ */
+/**
+ * Whether a custom entry marks its session as a Spotlight experiment session: pi's `spotlight:session` entry, which
+ * every session with the experiment on writes. Journals from before the experiment became a toggle carry
+ * `spotlight:assignment` instead, naming the arm the session drew; only the arm that shipped shaped with the shipped
+ * algorithm, so sessions of any other arm (`native`, `plain`, …) are not experiment sessions.
+ */
+export declare function experimentMarker(customType: unknown, data: Record<string, unknown>): boolean;
+/** Longest stored call target. */
+export declare const SPOTLIGHT_TARGET_CHARS = 500;
+/** A shaped read still collecting the lines the agent needs later (see {@link SpotlightCollector}). */
+export interface SpotlightOpenRead {
+    toolCallId: string;
+    /** The read file, resolved against the session's working directory. */
+    file: string;
+    /** First file line of the original and its line count. */
+    start: number;
+    lines: number;
+    /** `original.url`: the session artifact holding the original text. */
+    url: string | null;
+}
+/** Spotlight state a tail parse needs from earlier bytes of the same transcript. */
+export interface SpotlightParserState {
+    /** A Spotlight marker was seen: results, calls and requests are recorded from here on. */
+    experiment: boolean;
+    /** Tool calls recorded so far (the next call's order). */
+    seq: number;
+    /** The session header's working directory, for resolving relative read paths. */
+    cwd: string | null;
+    /** Latest session title. */
+    title: string | null;
+    /** Shaped reads still collecting needed lines; absent in cursors persisted before them. */
+    open?: SpotlightOpenRead[];
+}
+export declare function emptySpotlightState(): SpotlightParserState;
+/** `spotlight_sessions` row: the session's first Spotlight marker. */
+export interface SpotlightSessionRow {
+    sessionFile: string;
+    folder: string;
+    markedAt: number;
+    cwd: string | null;
+    title: string | null;
+}
+/** `spotlight_results` row (upserted): one evaluated result, from its shape entry, its result details, or both. */
+export interface SpotlightShapeRow {
+    sessionFile: string;
+    toolCallId: string;
+    timestamp: number;
+    tool: string;
+    inChars: number;
+    outChars: number;
+    inTokens: number;
+    outTokens: number;
+    /** What pi would have shown unshaped (`plain`) for the call; null on traces written before pi recorded it. */
+    plainChars: number | null;
+    plainTokens: number | null;
+    /**
+     * A cut wider than `plain` that pi did not apply (steps end with `plain-cap`): the would-be cut's tokens; the model
+     * got `plain`'s text (`outTokens`). Null otherwise.
+     */
+    cappedTokens: number | null;
+    /** The score-free coin skipped Spotlight: the no-score fallback rules shaped the result. */
+    scoreFree: boolean;
+    steps: string[];
+    /** The result message carried `details.spotlight`. */
+    hasDetails: boolean;
+    /**
+     * Held out at random: Spotlight would have shortened it, but the model saw it unshaped; the token counts and
+     * `original` describe the would-be cut.
+     */
+    holdout: boolean;
+    /**
+     * A read pi's former edit gate (removed) kept whole, in transcripts journaled while it ran: the model saw
+     * `plain`'s page; like a held-out result, the token counts and `original` describe the would-be cut.
+     */
+    gated: boolean;
+    /** `details.spotlight.original` (present only when shaping changed the text). */
+    original: SpotlightOriginalFacts | null;
+    /** Artifact ids the result names (its text's `artifact://N` plus `original.url`); null before the result lands. */
+    artifacts: number[] | null;
+    /** Spotlight's own usage, from the shape entry; null before it lands. */
+    spotlight: {
+        calls: number;
+        failures: number;
+        ms: number;
+        costUsd: number;
+    } | null;
+    /** Wall time shaping took, from the shape entry. */
+    shapeMs: number | null;
+}
+export interface SpotlightOriginalFacts {
+    url: string | null;
+    path: string | null;
+    /** First original line of the window (1-based file line for reads, else 1). */
+    start: number;
+    lines: number;
+    /** Hidden absolute line ranges, inclusive: the window minus the kept ranges. */
+    hidden: [number, number][];
+    hiddenLines: number;
+    /** Spotlight's per-line heat (`0`–`9`, `-` unscored) over the first lines; null when the trace has none. */
+    heat: string | null;
+    /** Kept runs, 1-based positions in the original (of a held-out result: what the cut would have kept). */
+    kept: [number, number][];
+}
+/**
+ * `spotlight_needs` row (merged on upsert): original lines (1-based positions in the original) a shaped read's later
+ * calls needed. Ranges of later parses are added to the stored ones; `open` is the latest.
+ */
+export interface SpotlightNeedRow {
+    sessionFile: string;
+    toolCallId: string;
+    file: string;
+    /** Still collecting: no edit, whole-file read or later shaped read of the file yet. */
+    open: boolean;
+    /** Lines later `read` selections covered. */
+    reread: [number, number][];
+    /** Lines later `edit` Find blocks located in the original. */
+    edit: [number, number][];
+}
+/** `spotlight_calls` row: one tool call of an experiment session. */
+export interface SpotlightCallRow {
+    sessionFile: string;
+    toolCallId: string;
+    entryId: string;
+    timestamp: number;
+    seq: number;
+    toolName: string;
+    callsInTurn: number;
+    target: string;
+    /** Files an `edit`/`write`/`ast_edit` call changes, as written (relative paths unresolved); null for other calls. */
+    edits: string[] | null;
+    /** {@link argumentTokens} of the call, for the generic rerun rule; null for `read` and `bash` (own rules). */
+    argTokens: string[] | null;
+}
+/** Result facts of a recorded call, applied as an update (the result can land in a later tail parse). */
+export interface SpotlightCallResultLink {
+    sessionFile: string;
+    toolCallId: string;
+    resultChars: number;
+    artifacts: number[];
+}
+/** `spotlight_requests` row: a main-loop assistant message of an experiment session (side requests excluded). */
+export interface SpotlightRequestRow {
+    sessionFile: string;
+    entryId: string;
+    timestamp: number;
+}
+/** Everything one parse extracted for the Spotlight tables. */
+export interface SpotlightParseRows {
+    sessions: SpotlightSessionRow[];
+    /** Title changes of experiment sessions seen after their marker. */
+    titles: {
+        sessionFile: string;
+        title: string;
+    }[];
+    shapes: SpotlightShapeRow[];
+    calls: SpotlightCallRow[];
+    callResults: SpotlightCallResultLink[];
+    requests: SpotlightRequestRow[];
+    needs: SpotlightNeedRow[];
+}
+export declare function emptySpotlightRows(): SpotlightParseRows;
+export declare function spotlightRowCount(rows: SpotlightParseRows): number;
+/** Distinct `artifact://N` ids a text names, ascending. */
+export declare function artifactIds(text: string): number[];
+/**
+ * What a call asked for, as recovery detection compares it: a read's path with its selector, a bash command, a
+ * search pattern with its path, eval code. Clipped to {@link SPOTLIGHT_TARGET_CHARS}.
+ */
+export declare function callTarget(toolName: string, args: unknown): string;
+/**
+ * A call's arguments as a token set for the generic rerun rule (two calls of the same tool rerun when their sets'
+ * Jaccard similarity is high): every JSON leaf as `key=value`, the key being the nearest object key; strings split
+ * on whitespace except under path keys (`path`, `paths`, `file`, `cwd`, `url`, …), which stay whole; nulls dropped;
+ * the top-level intent note `i` left out. Distinct tokens in first-seen order, at most
+ * {@link ARGUMENT_TOKEN_LIMIT}, each clipped to {@link ARGUMENT_TOKEN_CHARS} chars.
+ */
+export declare function argumentTokens(args: unknown): string[];
+/**
+ * Files a call changes: an `edit`'s patch headers (or its `path`), a `write`'s `path`, an `ast_edit`'s `paths`
+ * (globs kept as written), also when `ast_edit` runs through `write xd://ast_edit`. Null when the call is no file
+ * edit (other tools, or a write to an internal URL such as `proc://…/kill`).
+ */
+export declare function editedPaths(toolName: string, args: unknown): string[] | null;
+/** A read target split into its path and selected lines. */
+export interface ReadSelection {
+    path: string;
+    /** Selected inclusive line ranges; empty with `tail` null means the whole file. */
+    ranges: [number, number][];
+    /** `:-N`: the last N lines. */
+    tail: number | null;
+}
+/** Split a read path into the path and its selector (`file.ts:10-40`, `:50+20`, `:-30`, `:5-9,20`, `:raw`). */
+export declare function parseReadSelection(target: string): ReadSelection;
+/** A read selection's lines; null for the whole file. */
+export declare function selectedLines(selection: ReadSelection): [number, number][] | null;
+/** A path as written, resolved against the session's working directory (URLs and absolute paths kept). */
+export declare function resolveReadPath(target: string, cwd: string | null): string;
+/** One `*** Find` block of an `edit` input and the file its section edits (null: the call's `path`). */
+export interface EditFindBlock {
+    file: string | null;
+    /** `*** Edit File: PATH all`: every occurrence is replaced. */
+    all: boolean;
+    lines: string[];
+}
+/** The `*** Find` blocks of an `edit` call's input, with the file each one's section edits. */
+export declare function editFindBlocks(input: string): EditFindBlock[];
+/**
+ * Where a Find block's text lies in `original` (lines): every match as 1-based inclusive `[first, last]` positions.
+ * A Find line ending in `…` (or a lone `…` line) may skip original lines before the next Find line matches; blank
+ * lines around the block are ignored.
+ */
+export declare function locateFind(original: readonly string[], find: readonly string[]): [number, number][];
+/** Union of inclusive ranges, sorted and merged (touching ranges join). */
+export declare function mergeRanges(ranges: readonly (readonly [number, number])[]): [number, number][];
+/** Hidden absolute ranges of a window `[start, start + lines - 1]` whose kept ranges are 1-based within it. */
+export declare function hiddenRanges(start: number, lines: number, kept: readonly [number, number][]): [number, number][];
+/** The row a `spotlight:shape` entry's data describes, or null when it names no call. */
+export declare function shapeFromEntry(sessionFile: string, data: Record<string, unknown>, timestamp: number): SpotlightShapeRow | null;
+/** The row a result message's `details.spotlight` describes, or null when it carries none. */
+export declare function shapeFromDetails(sessionFile: string, toolCallId: string, details: unknown, text: string, timestamp: number): SpotlightShapeRow | null;
+/**
+ * Reduces one transcript's entries to {@link SpotlightParseRows}, carrying {@link SpotlightParserState} across tail
+ * parses. With `record` false it only advances the state (a prefix scan that rebuilds the state of a cursor without
+ * one).
+ *
+ * Needed lines: once a shaped read's result lands (applied, held out or score-free: any read with
+ * `details.spotlight.original`), later calls of the session, all from later requests, add to its needs: a `read` of the
+ * same file with a line selection adds the selected lines; an `edit` of it adds the lines its `*** Find` blocks
+ * locate in the original (read from the session's artifact directory in {@link finish}). Collecting stops at the
+ * file's first edit (after recording its lines; any edit tool), a later whole-file read, or a later shaped read of
+ * the file (after recording its selection), which starts collecting for itself.
+ */
+export declare class SpotlightCollector {
+    #private;
+    readonly rows: SpotlightParseRows;
+    readonly state: SpotlightParserState;
+    constructor(sessionFile: string, folder: string, state: SpotlightParserState, record?: boolean);
+    /**
+     * Locate the parse's edit Find blocks in their reads' originals (artifact files) and add the lines to the needs;
+     * an original that cannot be read adds none.
+     */
+    finish(): Promise<void>;
+    visit(entry: unknown): void;
+}

package/dist/types/spotlight-measures.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The Spotlight dashboard's round-2 measures over the analyzed sessions of `spotlight-aggregator.ts`: the
+ * holdout-adjusted net, ranking quality against the lines the agent needed later, step × size economics, time cost
+ * and tool-output coverage. Metric definitions live on the types in `shared-types.ts`.
+ */
+import type { Database } from "bun:sqlite";
+import type { SpotlightAdjusted, SpotlightCompounding, SpotlightCoverageRow, SpotlightRanking, SpotlightStepCell, SpotlightTimeCost, SpotlightTool } from "./shared-types.js";
+import type { Evaluated, SessionAnalysis } from "./spotlight-aggregator.js";
+/** One experiment session's share of the range's savings and costs, for the adjusted net's joint bootstrap. */
+export interface SessionMoney {
+    sessionFile: string;
+    savedTokens: number;
+    savedUsd: number;
+    /** Recovery tokens carried and priced plus extra-turn cost (its share of compounding.recoveryUsd). */
+    recoveryUsd: number;
+    spotlightUsd: number;
+}
+/**
+ * Per-cut holdout baselines of the range's evaluated results (see {@link baselinePerCut}): what a cut of `tool`
+ * gets fetched back anyway.
+ */
+export declare function holdoutBaselines(evaluated: readonly Evaluated[]): (tool: SpotlightTool) => number;
+export declare function emptyAdjusted(): SpotlightAdjusted;
+/**
+ * Holdout-adjusted net savings: each tool's applied cuts (scored and score-free) recover tokens; held-out would-be
+ * cuts of the same tool show how many the agent fetches back anyway. Intervals resample experiment sessions
+ * jointly. `byTool` lists `tools` in their order.
+ */
+export declare function computeAdjusted(evaluated: readonly Evaluated[], money: readonly SessionMoney[], grossSavedTokens: number, compounding: SpotlightCompounding, tools: readonly SpotlightTool[]): SpotlightAdjusted;
+export declare function emptyRanking(): SpotlightRanking;
+/**
+ * Ranking quality per group over shaped reads with needed lines (see {@link SpotlightRankingCell}), mean heat by
+ * line position over every scored cut or would-be cut, and how the needs were observed.
+ */
+export declare function computeRanking(evaluated: readonly Evaluated[]): SpotlightRanking;
+/**
+ * What each step combination earns per tool and saved-token bin over the range's cuts; combinations with
+ * under {@link MIN_STEP_CUTS} cuts of a tool fold into `other`. The excess subtracts each cut's holdout baseline
+ * ({@link holdoutBaselines}). Cells follow `tools`' order, then the most common combination first.
+ */
+export declare function computeSteps(evaluated: readonly Evaluated[], baselineOf: (tool: SpotlightTool) => number, tools: readonly SpotlightTool[]): SpotlightStepCell[];
+/**
+ * Agent time of the experiment sessions in the range: the model time of their requests, of the requests that did
+ * nothing but fetch back cut output, and the time tool calls spent shaping.
+ */
+export declare function computeTimeCost(active: readonly SessionAnalysis[], cutoff: number): SpotlightTimeCost;
+/**
+ * Each tool's share of the tool output experiment sessions' models saw from their marker (and the range) on;
+ * `shaped` marks the tools with evaluated results in the range.
+ */
+export declare function computeCoverage(database: Database, active: readonly SessionAnalysis[], cutoff: number, shaped: ReadonlySet<SpotlightTool>): SpotlightCoverageRow[];

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/omp-stats",
-	"version": "18.16.0",
+	"version": "18.17.0",
 	"description": "Local observability dashboard for omp AI usage statistics",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -36,15 +36,15 @@
 		"build": "bun run build.ts",
 		"dev": "bun run src/index.ts",
 		"check": "oxlint . && oxfmt --check --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts' && bun run check:types",
-		"check:types": "tsgo -p tsconfig.json --noEmit && tsgo -p tsconfig.client.json --noEmit",
+		"check:types": "bun check --no-script -p tsconfig.json && bun check --no-script -p tsconfig.client.json",
 		"lint": "oxlint .",
 		"fix": "oxlint --fix --fix-suggestions . && bun run fmt",
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "18.16.0",
-		"@oh-my-pi/pi-catalog": "18.16.0",
-		"@oh-my-pi/pi-utils": "18.16.0",
+		"@oh-my-pi/pi-ai": "18.17.0",
+		"@oh-my-pi/pi-catalog": "18.17.0",
+		"@oh-my-pi/pi-utils": "18.17.0",
 		"lucide-react": "^1.24.0",
 		"react": "19.2.7",
 		"react-dom": "19.2.7"

package/src/aggregator.ts

@@ -41,6 +41,7 @@ import {
 	getToolTimeSeries,
 	type RangeWindow,
 } from "./rollup";
+import { spotlightRowCount } from "./spotlight-ingest";
 import type { SyncWorkerRequest, SyncWorkerResponse } from "./sync-worker";
 // Coding-agent binary/bundle workers route through the CLI entrypoint with a
 // hidden argv mode, so the compiled binary and npm bundle only need one
@@ -417,7 +418,8 @@ async function syncAllSessionsLocked(
 			result.userStats.length +
 			result.userLinks.length +
 			result.toolCalls.length +
-			result.toolResults.length;
+			result.toolResults.length +
+			spotlightRowCount(result.spotlight);
 		if (pending.length >= SYNC_BATCH_FILES || pendingRows >= SYNC_BATCH_ROWS) flush();
 	};
 

package/src/client/App.tsx

@@ -13,6 +13,7 @@ import {
 	ProjectsRoute,
 	ProvidersRoute,
 	RequestsRoute,
+	SpotlightRoute,
 	ToolsRoute,
 	TracesRoute,
 } from "./routes";
@@ -62,6 +63,8 @@ function Dashboard() {
 				return <ProjectsRoute active={active} range={range} />;
 			case "gain":
 				return <GainRoute active={active} range={range} />;
+			case "spotlight":
+				return <SpotlightRoute active={active} range={range} />;
 		}
 	};
 

package/src/client/api.ts

@@ -14,6 +14,9 @@ import type {
 	RequestDetails,
 	SessionSummary,
 	SessionTrace,
+	SpotlightAgentScope,
+	SpotlightDashboardStats,
+	SpotlightSessionContext,
 	TimeRange,
 	ToolDashboardStats,
 } from "./types";
@@ -184,6 +187,24 @@ export async function getGainDashboardStats(
 	return fetchJson<GainDashboardStats>(`${API_BASE}/stats/gain?${params}`, { signal });
 }
 
+export async function getSpotlightDashboardStats(
+	range: TimeRange = "24h",
+	agent: SpotlightAgentScope = "all",
+	signal?: AbortSignal,
+): Promise<SpotlightDashboardStats> {
+	return fetchJson<SpotlightDashboardStats>(
+		`${API_BASE}/stats/spotlight?range=${encodeURIComponent(range)}&agent=${encodeURIComponent(agent)}`,
+		{ signal },
+	);
+}
+
+/** One experiment session's context per request, with and without shaping. */
+export async function getSpotlightSessionContext(file: string, signal?: AbortSignal): Promise<SpotlightSessionContext> {
+	return fetchJson<SpotlightSessionContext>(`${API_BASE}/stats/spotlight/session?file=${encodeURIComponent(file)}`, {
+		signal,
+	});
+}
+
 export async function getToolDashboardStats(
 	range: TimeRange = "24h",
 	signal?: AbortSignal,

package/src/client/app/nav.ts

@@ -8,6 +8,7 @@ import {
 	LayoutGrid,
 	type LucideIcon,
 	PlugZap,
+	ScanSearch,
 	Sparkles,
 	SquareChartGantt,
 	Wrench,
@@ -24,7 +25,8 @@ export type DashboardSection =
 	| "tools"
 	| "frustration"
 	| "projects"
-	| "gain";
+	| "gain"
+	| "spotlight";
 
 export interface NavItem {
 	id: DashboardSection;
@@ -65,6 +67,7 @@ export const NAV: readonly NavGroup[] = [
 			{ id: "frustration", label: "Frustration", icon: Frown, hotkey: "f" },
 			{ id: "projects", label: "Projects", icon: FolderGit2, hotkey: "j" },
 			{ id: "gain", label: "Gain", icon: Sparkles, hotkey: "g" },
+			{ id: "spotlight", label: "Spotlight", icon: ScanSearch, hotkey: "s" },
 		],
 	},
 ];

package/src/client/charts/Chart.tsx

@@ -1,7 +1,8 @@
 /**
- * Core SVG chart: categorical x slots, stacked or grouped bars, stacked areas
- * and lines, an optional right axis, a hover cursor and a floating tooltip.
- * Marks are crisp and unsmoothed — square bars, straight segments.
+ * Core SVG chart: categorical x slots, stacked or grouped bars, stacked areas,
+ * lines and dots, an optional right axis, a hover cursor and a floating tooltip.
+ * Marks are crisp and unsmoothed — square bars, straight segments. Negative
+ * values extend the axis below zero (bars hang down from the baseline).
  *
  * `TimeChart` wraps this for bucketed time series; use `Chart` directly for
  * categorical axes (hour of day, model names).
@@ -9,7 +10,7 @@
 
 import { Fragment, type ReactNode, useId, useMemo, useState } from "react";
 import { formatCompact } from "../data/formatters";
-import type { ChartKind, ChartSeries, ReferenceLine } from "./types";
+import type { ChartKind, ChartSeries, ReferenceLine, SlotMarker } from "./types";
 import { useWidth } from "./useWidth";
 
 export interface ChartProps {
@@ -39,6 +40,8 @@ export interface ChartProps {
 	/** Show a total row in the tooltip. Default: stacked with 2+ series. */
 	showTotal?: boolean;
 	references?: readonly ReferenceLine[];
+	/** Vertical guides at x slots, labelled along the top edge. */
+	markers?: readonly SlotMarker[];
 	onSelect?: (index: number) => void;
 	/** Shown over empty axes when every visible value is zero. */
 	emptyLabel?: ReactNode;
@@ -67,6 +70,7 @@ export function Chart({
 	hidden,
 	showTotal,
 	references,
+	markers,
 	onSelect,
 	emptyLabel = "No data in this range",
 	tooltipExtra,
@@ -80,31 +84,58 @@ export function Chart({
 	const layout = useMemo(() => {
 		const left = visible.filter(s => s.axis !== "right");
 		const right = visible.filter(s => s.axis === "right");
-		const stackable = (s: ChartSeries) => stacked && (s.kind ?? kind) !== "line";
+		const stackable = (s: ChartSeries) => {
+			const mark = s.kind ?? kind;
+			return stacked && (mark === "bars" || mark === "area");
+		};
 
 		// Per-slot stack bases for stacked left series, in series order (first = bottom).
+		// Positive and negative values stack away from zero separately.
 		const bases = new Map<string, number[]>();
 		const tops = Array.from({ length: slots }, () => 0);
+		const bottoms = Array.from({ length: slots }, () => 0);
 		let leftMax = 0;
+		let leftMin = 0;
 		for (const s of left) {
 			if (stackable(s)) {
-				const base = tops.slice();
+				const base = Array.from({ length: slots }, () => 0);
+				for (let i = 0; i < slots; i++) {
+					const v = s.values[i] ?? 0;
+					if (v < 0) {
+						base[i] = bottoms[i];
+						bottoms[i] += v;
+					} else {
+						base[i] = tops[i];
+						tops[i] += v;
+					}
+				}
 				bases.set(s.key, base);
-				for (let i = 0; i < slots; i++) tops[i] += s.values[i] ?? 0;
 			} else {
-				for (let i = 0; i < slots; i++) leftMax = Math.max(leftMax, s.values[i] ?? 0);
+				for (let i = 0; i < slots; i++) {
+					leftMax = Math.max(leftMax, s.values[i] ?? 0);
+					leftMin = Math.min(leftMin, s.values[i] ?? 0);
+				}
 			}
 		}
-		for (const top of tops) leftMax = Math.max(leftMax, top);
+		for (let i = 0; i < slots; i++) {
+			leftMax = Math.max(leftMax, tops[i]);
+			leftMin = Math.min(leftMin, bottoms[i]);
+		}
 		let rightMax = 0;
-		for (const s of right) for (let i = 0; i < slots; i++) rightMax = Math.max(rightMax, s.values[i] ?? 0);
+		let rightMin = 0;
+		for (const s of right) {
+			for (let i = 0; i < slots; i++) {
+				rightMax = Math.max(rightMax, s.values[i] ?? 0);
+				rightMin = Math.min(rightMin, s.values[i] ?? 0);
+			}
+		}
 		for (const r of references ?? []) {
 			if (r.axis === "right") rightMax = Math.max(rightMax, r.value);
 			else leftMax = Math.max(leftMax, r.value);
 		}
 
-		const leftScale = niceScale(yMax ?? leftMax);
-		const rightScale = right.length > 0 ? niceScale(yMaxRight ?? rightMax) : null;
+		const leftScale = niceScale(yMax ?? leftMax, leftMin);
+		const rightScale = right.length > 0 ? niceScale(yMaxRight ?? rightMax, rightMin) : null;
 		const empty = visible.every(s => s.values.every(v => !v));
 		return { left, right, bases, stackable, leftScale, rightScale, empty };
 	}, [visible, slots, stacked, kind, yMax, yMaxRight, references]);
@@ -116,8 +147,10 @@ export function Chart({
 	const plotW = Math.max(0, width - padLeft - padRight);
 	const plotH = height - PAD_TOP - PAD_BOTTOM;
 	const slotW = slots > 0 ? plotW / slots : 0;
-	const yLeft = (v: number) => PAD_TOP + plotH - (v / layout.leftScale.max) * plotH;
-	const yRight = (v: number) => PAD_TOP + plotH - (v / (layout.rightScale?.max ?? 1)) * plotH;
+	const project = (scale: AxisScale, v: number) =>
+		PAD_TOP + plotH - ((v - scale.min) / (scale.max - scale.min)) * plotH;
+	const yLeft = (v: number) => project(layout.leftScale, v);
+	const yRight = (v: number) => (layout.rightScale ? project(layout.rightScale, v) : yLeft(v));
 	const cx = (i: number) => padLeft + (i + 0.5) * slotW;
 
 	const barSeries = visible.filter(s => (s.kind ?? kind) === "bars");
@@ -212,7 +245,12 @@ export function Chart({
 							return (
 								<g key={s.key}>
 									<path d={`${line}${floor}Z`} fill={fill} fillOpacity={s.pattern ? 1 : 0.2} />
-									<path className="chart-line" d={line} stroke={s.color} />
+									<path
+										className="chart-line"
+										d={line}
+										stroke={s.color}
+										strokeDasharray={s.dashed ? "4 3" : undefined}
+									/>
 								</g>
 							);
 						})}
@@ -280,6 +318,38 @@ export function Chart({
 							);
 						})}
 
+					{visible
+						.filter(s => (s.kind ?? kind) === "dots")
+						.map(s => {
+							const y = s.axis === "right" ? yRight : yLeft;
+							return (
+								<g key={s.key} className="chart-dots" fill={s.color}>
+									{s.values.map((v, i) =>
+										v === null || v === undefined ? null : (
+											<circle key={i} cx={cx(i)} cy={y(v)} r={hover === i ? 3.5 : 2.5} />
+										),
+									)}
+								</g>
+							);
+						})}
+
+					{markers?.map(m =>
+						m.index >= 0 && m.index < slots ? (
+							<g key={`marker:${m.index}`} className="chart-marker">
+								<line x1={cx(m.index)} x2={cx(m.index)} y1={PAD_TOP} y2={PAD_TOP + plotH} />
+								{m.label && (
+									<text
+										x={cx(m.index) + (cx(m.index) > padLeft + plotW / 2 ? -5 : 5)}
+										y={PAD_TOP + 9}
+										textAnchor={cx(m.index) > padLeft + plotW / 2 ? "end" : "start"}
+									>
+										{m.label}
+									</text>
+								)}
+							</g>
+						) : null,
+					)}
+
 					{references?.map(r => {
 						const y = r.axis === "right" ? yRight(r.value) : yLeft(r.value);
 						return (
@@ -351,16 +421,29 @@ export function Chart({
 	);
 }
 
-/** Round an axis maximum up to 1/2/2.5/5 × 10ⁿ and return evenly spaced ticks from 0. */
-export function niceScale(max: number): { max: number; ticks: number[] } {
-	if (!(max > 0)) return { max: 1, ticks: [0] };
-	const rough = max / Y_TICKS;
+export interface AxisScale {
+	min: number;
+	max: number;
+	ticks: number[];
+}
+
+/**
+ * Round an axis span out to 1/2/2.5/5 × 10ⁿ steps and return evenly spaced
+ * ticks. The span always includes zero; `min` (default 0) extends it below.
+ */
+export function niceScale(max: number, min = 0): AxisScale {
+	const hi = Math.max(0, max);
+	const lo = Math.min(0, min);
+	if (!(hi - lo > 0)) return { min: 0, max: 1, ticks: [0] };
+	const rough = (hi - lo) / Y_TICKS;
 	const magnitude = 10 ** Math.floor(Math.log10(rough));
 	const step = [1, 2, 2.5, 5, 10].map(m => m * magnitude).find(s => s >= rough) ?? 10 * magnitude;
-	const top = Math.ceil(max / step) * step;
+	const top = Math.ceil(hi / step) * step;
+	const bottom = Math.floor(lo / step) * step;
 	const ticks: number[] = [];
-	for (let t = 0; t <= top + step / 2; t += step) ticks.push(Number(t.toPrecision(12)));
-	return { max: top, ticks };
+	for (let t = bottom; t <= top + step / 2; t += step) ticks.push(Number(t.toPrecision(12)));
+	// An all-negative axis still needs a span above its lowest tick.
+	return { min: bottom, max: top > bottom ? top : bottom + step, ticks };
 }
 
 function labelWidth(labels: readonly string[]): number {