@tangle-network/charts 0.7.0 → 0.9.0

package/README.md

@@ -164,36 +164,93 @@ A run page draws recorded events, never inferred ones. Every addition below has
 
 | Need | Static | React |
 |---|---|---|
-| Vertical events (first pass, deadline, died) and shaded spans (after pass, idle, no data) | `timeSeries(rows, { ..., marks, bands })` | `<Lines marks bands>` |
+| Vertical events (first pass, deadline, died, release, steer, ruling, wake) and shaded spans (after pass, idle, no data, blocked) | `timeSeries(rows, { ..., marks, bands })` | `<Lines marks bands>` |
 | Lanes of spans with marks; an open span runs to `now` | `timeline(lanes, { measure, now, marks })` | `<Gantt lanes now marks>` |
+| An agent tree over time: lanes under their parents, attempt ticks with ok and failed counts, walls across every lane, folding by subtree | `timeline(lanes, { measure, start, now, marks, bands, collapsed })` | `<TimelineView lanes options defaultCollapsed>` |
 | Part of a whole with untraced time hatched | `phaseWaterfall` (unaccounted leaves and the remainder are hatched) | `<Meter total segments>` |
 | One panel per arm on shared axes, with no-data panels and early ends | `smallMultiples(panels, { x, y, shared })` | `<FigureView figure>` |
 | Series that stay distinct without colour | later series add a dash and a marker shape | `series[].dash`, `series[].marker` |
 
 ```ts
-type ChartMark = { at: number; label: string; kind: "pass" | "deadline" | "died" | "event" };
-type ChartBand = { from: number; to: number; label: string; kind: "after-pass" | "idle" | "missing" };
-type TimelineLane = { id: string; label: string; spans: Array<{ start: number; end: number | null; state: string; note?: string }> };
+type ChartMark = { at: number; label: string; kind: "pass" | "deadline" | "died" | "event" | "release" | "steer" | "ruling" | "wake";
+  verdict?: "pass" | "fail" | "unknown"; source?: string; lane?: string };
+type ChartBand = { from: number; to: number; label: string; kind: "after-pass" | "idle" | "missing" | "blocked" };
+type TimelineLane = { id: string; label: string; spans: Array<{ start: number; end: number | null; state: string; note?: string }>;
+  parent?: string; depth?: number; ticks?: TimelineTick[]; detail?: string[] };
+type TimelineTick = { at: number; outcome: "ok" | "quota" | "lost" | "rate-limit" | "oom" | "refused" | "aborted" | "other"; note?: string };
 type MultiplePanel = { id: string; label: string; unit?: string; domain?: [number, number]; points?: TimePoint[];
   missing?: { why: string; detail?: string }; end?: { at: number; kind: ChartMark["kind"]; label?: string }; marks?: ChartMark[] };
 type MeterSegment = { label: string; value: number | null; color?: string; kind?: "measured" | "untraced" };
 ```
 
 Mark kinds differ by stroke as well as colour: pass is solid, deadline dashed, died ends in a cross, and other events are dotted.
+A release carries a diamond head, a steer a triangle, a ruling a square and a wake a circle; releases, steers and wakes stop at the plot's edge so frequent events never wall off the data, and a ruling crosses it.
+A recorded `verdict` colours a mark (pass and fail take the status tones, unknown the muted tone), and a `source`, such as the operator or the keeper, follows its label.
+Mark labels take up to three rows above the data, placed by measured width so none overlap; marks of one kind and verdict at one place share a rule and a label (`rc17 (+18)`), and a label with no room is left to the hover and the table.
+A `blocked` band is a system-wide wall, such as a quota window: a breach wash across every lane under a solid top edge.
 Marks and bands appear in the figure's table (`Recorded events by …`) and, for React, in a text list under the plot.
-Static figures refuse marks or bands outside the x domain; React components throw `RangeError` for the same input, as `StackedBarChart` does.
+`timeSeries` and `smallMultiples` refuse marks or bands outside the x domain, and `timeline` names them at its edge instead (below); React components throw `RangeError` for marks or bands they cannot place, as `StackedBarChart` does.
+Axis labels never overlap at 720 or 358 px: `timeSeries` labels recorded positions spread evenly across the plot, and `timeline` uses the smallest clock step (1 min to 7 days) whose labels fit, naming the date at midnight.
 
-`timeline` refuses an open span without `now`, a span outside a supplied `start`/`end` window and reversed times. States named in `hatch` (default `missing`, `untraced`) are hatched; states in `muted` (default `idle`) use the muted tone.
-`Gantt` keeps its single-span `rows` input; `lanes` takes the same shape as `timeline`.
+`timeline` refuses an open span without `now`, a span, tick or `now` outside a supplied `start`/`end` window and reversed times. States named in `hatch` (default `missing`, `untraced`) are hatched; states in `muted` (default `idle`) use the muted tone.
+The window defaults to the extent of the data (spans, ticks and `now`), so a run that ended early is not drawn out to its deadline: a mark past the window, such as the deadline, is named at the edge it falls past with its distance (`Deadline +21.9 h →`), listed in the note, and not drawn; bands are clipped to the window.
+Pass `start` (the run's start) to show time before the first span.
+
+Lanes form a tree through `parent`: each lane is drawn under its parent with a connector, siblings and roots keep their input order, and `depth` defaults to the parent's depth plus one. A stated depth that disagrees with the parent, a parent that is not a lane and a parent chain that loops are refused.
+`ticks` are recorded attempts, such as driver turns, at the time each ended: ok ticks rise above the bar and failed ticks drop below it in their outcome's colour from the shared outcome palette (below), and the lane ends with its counts, `21✓ 250✗`. A lane without `ticks` shows no counts; an empty `ticks` shows `0✓ 0✗`. Ticks of one outcome within 2 px are drawn as one, with the count and the commonest `note` in its hover. An unknown outcome is refused.
+A mark with a `lane` is drawn on that lane only (a steer to one agent, a wake of the root) instead of across every lane; a lane that is not in the figure is refused.
+`detail` is the caller's facts about a lane (profile, model, status, attempts, cost, top error), one hover line each on the lane's label and every span, and a column of the lanes table.
+`collapsed` folds the named lanes' subtrees: descendants are hidden, the label gains `+N`, and the folded lane's ticks and counts total its subtree. Passing `collapsed`, even empty, makes each parent lane's label a fold toggle (`data-toggle`, a button with `aria-expanded`); `TimelineView` keeps the fold state and wires the toggles to a click, Enter or Space, returning focus to the toggle.
+`Gantt` keeps its single-span `rows` input; `lanes` takes the same shape as `timeline` and draws spans only.
 
 `Meter` with `segments` draws each recorded part of `total`; the remainder no segment accounts for is hatched and labelled `untraced` (rename it with `untraced`). A null segment is listed as `not recorded` and takes no width; a missing total hatches the whole track. Parts that sum past the total throw.
 
 `smallMultiples` draws one panel per arm. A `missing` panel is hatched and reads `no data: <why>`; an `end` stops the line at a mark of its kind. It refuses mixed units, values outside the shared domain, points after an end and a missing panel that also carries data. `shared: "x"` keeps one x domain and requires each panel's own y `domain`. The lede counts `n of m <noun>s have data`.
 
+`TimelineView` is `FigureView` around `timeline(lanes, { ...options, collapsed })`; `defaultCollapsed` names the lanes folded on first render.
+
 `FigureView` embeds any static `Figure | Refusal` in React: the wide render in containers of 720 px or more, the phone render (or the table, when a figure has none) below that, and the data, reading and method in a closed disclosure. A refusal renders as its sentence. Import `figure.css` for its styles.
 
 `node scripts/capture-run-page.mjs [dir]` (after `npm run build`) captures each addition at 1440 px light and 390 px dark; the reviewed images are `docs/screenshots/run-page-*.png`.
 
+### Release checks: the climb and the bar
+
+A play's page asks how close its releases are to the check and to the goal's bar. `timeSeries` and `smallMultiples` draw it from the producer's recorded rows; Charts decides no verdict, comparability or checker.
+
+```ts
+const climb = timeSeries(rows, {
+  x: { label: "release", domain: [-0.5, 16.5], categories: tags.map((tag, at) => ({ at, label: tag })) },
+  y: { label: "check progress", unit: "", domain: [-0.05, 1.06], strip: "no score",
+    ticks: [...stages.map((label, i) => ({ at: i / stages.length, label })), { at: 1, label: "SOLVED" }] },
+  bands: [{ from: 0, to: 16, label: "18b · 5 published, 7 withheld", kind: "group" }],
+  marks: [{ at: 9.5, label: "10.5 h", kind: "event", source: "gap" }, { at: 13.47, label: "v4 · operator amendment 20:52Z", kind: "ruling" }],
+  markers: { circle: "check", diamond: "gate" },
+});
+// rows: one per checker (and run), `colorIndex` 0 for the current checker; points such as
+// { x: 13, y: 1, verdict: "pass", glyph: "check", marker: "circle", count: 3, firstAt, lastAt, annotation: line }
+// { x: 15, y: null, verdict: "unknown", marker: "diamond", label: "6/15", count: 12 }   → the strip, never a height
+```
+
+| Field | Drawn as |
+|---|---|
+| `verdict` | `pass` filled, `fail` outlined, `unknown` dashed; with `y: null`, a square in the strip under the plot (hatched when unknown) |
+| `count`, `firstAt`, `lastAt` | `×n` beside the mark; first and last times in the hover and the table |
+| `comparable` | `false` outlined with `*`, `null` outlined with `?` |
+| `glyph` | `✓` (`check`) or `✕` (`cross`), the only marks in the status tones |
+| `marker`, `label` | the mark's shape, named by the figure's `markers`; a short direct label such as `9/15` |
+| `y.scale`, `y.targets`, `y.ticks` | log10 y; target bands (dashed when `stretch`); caller-named gridlines |
+| `x.categories` | an ordinal axis of weighted columns; points sharing a column are spread across it |
+| `colorIndex` (row) | the checker palette, 0 current; dashes follow the index |
+
+The bar panels share the climb's columns: `smallMultiples(panels, { shared: "x", x: { label, domain, categories }, columns: 2, connect: false, markers })`, each panel with its own `unit`, `format`, `scale: "log"`, `domain` and `targets`. `docs/fixtures/magnetar-play.json` holds the Magnetar play's real 17c, 18b and 19b rows in these shapes (`docs/fixtures/export-magnetar-play.mjs` exports them on the Lab host), and `src/run-page-figures.test.ts` draws them.
+
+Attempt outcomes and checkers have one palette in every view. `OUTCOME_ORDER` is the stack order (ok, quota, lost, rate-limit, oom, refused, aborted, other; an open attempt is hatched, never an outcome); `OUTCOME_COLORS[outcome]` and `checkerColor(index)` return the `var(--chart-outcome-*)` and `var(--chart-checker-*)` tokens `figure.css` defines as `light-dark()` pairs, so they follow the page's `color-scheme`. Aborted and other share the neutral tone and always carry a label. `node scripts/palette-check.mjs <dataviz validate_palette.js>` checks both palettes, adjacent pairs in order, on the light surface and on #161616.
+
+| Play page figure | 1440 light | 390 dark |
+|---|---|---|
+| Climb | ![climb](docs/screenshots/run-page-play-climb-1440-light.png) | ![climb phone](docs/screenshots/run-page-play-climb-390-dark.png) |
+| Against the bar | ![bar](docs/screenshots/run-page-play-bar-1440-light.png) | ![bar phone](docs/screenshots/run-page-play-bar-390-dark.png) |
+
 ### Plots without visible report controls
 
 Use `renderFigure(figure, noteNumber, { presentation: "plot" })` to show the responsive plot alone.

package/dist/figure.css

@@ -310,8 +310,8 @@
 .tgc-tip-bg { fill: var(--chart-ink); }
 .tgc-tip-ink { fill: var(--chart-canvas); }
 
-.tgc-series-line { fill: none; stroke: var(--chart-accent); stroke-width: 2; stroke-linejoin: round; }
-.tgc-series-point, .tgc-series-key { fill: var(--chart-accent); stroke: var(--chart-canvas); stroke-width: 2; }
+.tgc-series-line { fill: none; stroke: var(--tgc-series, var(--chart-accent)); stroke-width: 2; stroke-linejoin: round; }
+.tgc-series-point, .tgc-series-key { fill: var(--tgc-series, var(--chart-accent)); stroke: var(--chart-canvas); stroke-width: 2; }
 
 /* Semantic states stay tied to Brand status tokens. No-data has its own neutral mark. */
 .tgc-heat-pass { fill: color-mix(in srgb, var(--chart-pass, var(--status-running)) 19%, var(--chart-canvas)); stroke: var(--chart-pass, var(--status-running)); stroke-width: .8; }
@@ -352,9 +352,27 @@
 .tgc-mark-deadline { stroke: var(--chart-ink); stroke-dasharray: 5 3; }
 .tgc-mark-died { stroke: var(--chart-breach, var(--status-error)); stroke-width: 2; }
 .tgc-mark-event { stroke: var(--chart-ink-muted); stroke-dasharray: 1 3; stroke-linecap: round; }
+.tgc-mark-release { stroke: var(--chart-ink-muted); }
+.tgc-mark-steer { stroke: var(--chart-accent); stroke-dasharray: 1 3; stroke-linecap: round; }
+.tgc-mark-ruling { stroke: var(--chart-ink); stroke-dasharray: 6 2 1 2; }
+.tgc-mark-wake { stroke: var(--chart-ink-muted); stroke-dasharray: 1 3; stroke-linecap: round; }
+.tgc-mark-head { fill: var(--chart-ink-muted); stroke: var(--chart-canvas); stroke-width: 1; }
+[data-mark="steer"] .tgc-mark-head { fill: var(--chart-accent); }
+[data-mark="ruling"] .tgc-mark-head { fill: var(--chart-ink); }
+/* A recorded verdict colours the rule and head: pass and fail take the status tones, unknown the muted tone. */
+.tgc-verdict-pass .tgc-mark { stroke: var(--chart-pass, var(--status-running)); }
+.tgc-verdict-pass .tgc-mark-head { fill: var(--chart-pass, var(--status-running)); }
+.tgc-verdict-fail .tgc-mark { stroke: var(--chart-breach, var(--status-error)); }
+.tgc-verdict-fail .tgc-mark-head { fill: var(--chart-breach, var(--status-error)); }
+.tgc-verdict-unknown .tgc-mark { stroke: var(--chart-muted); }
+.tgc-verdict-unknown .tgc-mark-head { fill: var(--chart-muted); }
 .tgc-mark-label { fill: var(--chart-ink); paint-order: stroke; stroke: var(--chart-canvas); stroke-width: 3px; stroke-linejoin: round; }
+.tgc-mark-edge { fill: var(--chart-ink-muted); }
 .tgc-band-after-pass { fill: color-mix(in srgb, var(--chart-pass, var(--status-running)) 12%, transparent); }
 .tgc-band-idle { fill: var(--chart-shade); }
+/* A system-wide wall, such as a quota window: a breach wash across every lane, topped by a solid edge. */
+.tgc-band-blocked { fill: color-mix(in srgb, var(--chart-breach, var(--status-error)) 9%, transparent); }
+.tgc-band-wall { stroke: var(--chart-breach, var(--status-error)); stroke-width: 2; }
 /* Missing data: a neutral wash under hatch lines, never a zero-height mark. */
 .tgc-hatch-bg { fill: color-mix(in srgb, var(--chart-muted) 10%, transparent); }
 .tgc-hatch { fill: none; stroke: var(--chart-muted); stroke-width: 1; }
@@ -362,9 +380,85 @@
 .tgc-span-muted { fill: var(--chart-muted); }
 .tgc-span-open { stroke: var(--chart-ink); stroke-width: 1.5; stroke-dasharray: 3 2; }
 .tgc-now { stroke: var(--chart-ink); stroke-width: 1.5; }
+/* Timeline trees and attempts. Ok ticks rise above the bar and failed ticks drop below it, so they read without colour. */
+.tgc-tree { fill: none; stroke: var(--chart-muted); stroke-width: 1; }
+.tgc-caret { fill: var(--chart-ink-muted); }
+.tgc-lane-toggle { cursor: pointer; }
+.tgc-lane-toggle:focus-visible { outline: none; }
+.tgc-lane-hit { fill: transparent; stroke: transparent; stroke-width: 2; }
+.tgc-lane-toggle:hover .tgc-lane-hit { fill: var(--chart-shade); }
+.tgc-lane-toggle:focus-visible .tgc-lane-hit { stroke: var(--chart-accent); }
+.tgc-tick { stroke-width: 1.5; }
+.tgc-tick-ok { stroke: var(--chart-outcome-ok); }
+.tgc-tick-quota { stroke: var(--chart-outcome-quota); }
+.tgc-tick-lost { stroke: var(--chart-outcome-lost); }
+.tgc-tick-rate-limit { stroke: var(--chart-outcome-rate-limit); }
+.tgc-tick-oom { stroke: var(--chart-outcome-oom); }
+.tgc-tick-refused { stroke: var(--chart-outcome-refused); }
+.tgc-tick-aborted, .tgc-tick-other { stroke: var(--chart-outcome-neutral); }
+/* Lane labels and counts keep a canvas halo, so rules and ticks under them never strike through the text. */
+.tgc-lane-label, .tgc-count { paint-order: stroke; stroke: var(--chart-canvas); stroke-width: 3px; stroke-linejoin: round; }
+.tgc-count { fill: var(--chart-ink); }
+.tgc-count-ok { fill: var(--chart-pass, var(--status-running)); }
+.tgc-count-failed { fill: var(--chart-breach, var(--status-error)); }
 
 /* FigureView (React) picks the render by measured width; the wide plot fills its container. */
 .tgc-figure-view { max-width: none; margin: 0; }
 .tgc-view-plot svg { display: block; overflow: visible; }
 .tgc-view-wide svg { width: 100%; height: auto; }
 .tgc-view-narrow svg { max-width: 100%; height: auto; }
+
+/*
+ * One fixed palette for attempt outcomes and check versions in every view (src/outcomes.ts names them). Each is a
+ * light-dark() pair picked by the page's color-scheme. Outcomes pass the dataviz colour-vision checks as adjacent
+ * pairs in stack order (ok, quota, lost, rate-limit, oom, refused) on the light surface and on #161616; checkers pass
+ * as adjacent series (current, then older). `scripts/palette-check.mjs` re-runs the validator. A page may override
+ * any of these properties; :where() keeps them at zero specificity.
+ */
+:where(:root) {
+  --chart-outcome-ok: light-dark(#2a78d6, #3987e5);
+  --chart-outcome-quota: light-dark(#eb6834, #d95926);
+  --chart-outcome-lost: light-dark(#1baf7a, #199e70);
+  --chart-outcome-rate-limit: light-dark(#eda100, #c98500);
+  --chart-outcome-oom: light-dark(#e87ba4, #d55181);
+  --chart-outcome-refused: light-dark(#6250d6, #9085e9);
+  --chart-outcome-neutral: #898781;
+  --chart-checker-0: light-dark(#2a78d6, #3987e5);
+  --chart-checker-1: light-dark(#1baf7a, #199e70);
+  --chart-checker-2: light-dark(#6250d6, #9085e9);
+  --chart-checker-3: light-dark(#eda100, #c98500);
+}
+/* A series drawn in a checker's hue; past the fourth hue it is muted and named by its label. */
+.tgc-checker-0 { --tgc-series: var(--chart-checker-0); }
+.tgc-checker-1 { --tgc-series: var(--chart-checker-1); }
+.tgc-checker-2 { --tgc-series: var(--chart-checker-2); }
+.tgc-checker-3 { --tgc-series: var(--chart-checker-3); }
+.tgc-checker-other { --tgc-series: var(--chart-muted); }
+/* Recorded verdicts: a pass is filled, a fail or an incomparable value is an outline, an undecided one dashed. */
+.tgc-series-point.tgc-point-outline { fill: var(--chart-canvas); stroke: var(--tgc-series, var(--chart-accent)); stroke-width: 1.75; }
+.tgc-series-point.tgc-point-undecided { fill: var(--chart-canvas); stroke: var(--tgc-series, var(--chart-accent)); stroke-width: 1.5; stroke-dasharray: 2 1.5; }
+.tgc-strip-hatch .tgc-hatch { stroke: var(--tgc-series, var(--chart-muted)); }
+.tgc-strip-edge { fill: none; stroke: var(--tgc-series, var(--chart-muted)); stroke-width: 1.25; }
+.tgc-strip-observation:focus-visible { outline: none; }
+.tgc-strip-observation:focus-visible .tgc-series-hit { stroke: var(--chart-ink); stroke-width: 2; }
+.tgc-point-badge { paint-order: stroke; stroke: var(--chart-canvas); stroke-width: 3px; stroke-linejoin: round; font-family: var(--font-mono, "JetBrains Mono", ui-monospace, monospace); }
+.tgc-point-label { fill: var(--chart-ink-muted); }
+.tgc-glyph-note { fill: var(--chart-ink); font-weight: 600; }
+/* Status colours appear only on these glyphs. */
+.tgc-glyph-check { fill: var(--chart-pass, var(--status-running)); font-weight: 600; }
+.tgc-glyph-cross { fill: var(--chart-breach, var(--status-error)); font-weight: 600; }
+/* Recorded targets sit under the data: a target is a soft band between solid edges, a stretch a dashed outline. */
+.tgc-target-target { fill: color-mix(in srgb, var(--chart-ink) 7%, transparent); }
+.tgc-target-stretch { fill: none; }
+.tgc-target-target-edge, .tgc-target-target.tgc-target-line { stroke: var(--chart-ink-muted); stroke-width: 1; }
+.tgc-target-stretch-edge, .tgc-target-stretch.tgc-target-line { stroke: var(--chart-ink-muted); stroke-width: 1; stroke-dasharray: 4 3; }
+.tgc-target-label { fill: var(--chart-ink-muted); paint-order: stroke; stroke: var(--chart-canvas); stroke-width: 3px; stroke-linejoin: round; }
+/* Group headers: a labelled bracket above the plot and a light rule at each inner edge. */
+.tgc-group-rule { stroke: var(--chart-ink-muted); stroke-width: 1.5; }
+.tgc-group-edge { stroke: var(--chart-rule); stroke-width: 1; }
+.tgc-group-label { fill: var(--chart-ink); paint-order: stroke; stroke: var(--chart-canvas); stroke-width: 3px; stroke-linejoin: round; }
+/* The verdict key: glyphs in the neutral ink, so they describe a mark's form, not a series. */
+.tgc-key-mark { stroke-width: 1.5; }
+.tgc-key-filled { fill: var(--chart-ink-muted); stroke: none; }
+.tgc-key-outline { fill: none; stroke: var(--chart-ink-muted); }
+.tgc-key-dashed { fill: none; stroke: var(--chart-ink-muted); stroke-dasharray: 2 1.5; }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { C as isRefusal, S as TierCounts, _ as MatrixCell, a as BandKind, b as Setup, c as MarkKind, d as CostBasis, f as Estimate, g as IntervalMethod, h as Interval, i as timeline, l as BreakdownInput, m as Figure, n as TimelineOptions, o as ChartBand, p as Exclusion, r as TimelineSpan, s as ChartMark, t as TimelineLane, u as ComparisonRow, v as RateRow, x as Tier, y as Refusal } from "./timeline-BAjzF-wL.js";
+import { A as IntervalMethod, C as BreakdownInput, D as Exclusion, E as Estimate, F as Tier, I as TierCounts, L as isRefusal, M as RateRow, N as Refusal, O as Figure, P as Setup, S as YTick, T as CostBasis, _ as MarkVerdict, a as timeline, b as YScale, c as OUTCOME_ORDER, d as PointFields, f as PointGlyph, g as MarkKind, h as ChartMark, i as TimelineTick, j as MatrixCell, k as Interval, l as TickOutcome, m as ChartBand, n as TimelineOptions, o as CHECKER_HUES, p as BandKind, r as TimelineSpan, s as OUTCOME_COLORS, t as TimelineLane, u as checkerColor, v as MarkerShape, w as ComparisonRow, x as YTarget, y as XCategory } from "./timeline-CNHABOS1.js";
 //#region src/block.d.ts
 interface RenderFigureOptions {
   /** Chart uses a closed data disclosure; plot keeps only the SVG and accessible data. */
@@ -185,7 +185,7 @@ interface MetricBarsOptions {
 export declare function metricBars(rows: MetricRow[], o: MetricBarsOptions): Figure | Refusal;
 //#endregion
 //#region src/time-series.d.ts
-interface TimePoint {
+interface TimePoint extends PointFields {
   x: number;
   y: number | null;
   observations?: Observations;
@@ -197,16 +197,32 @@ interface TimeSeriesRow {
   id: string;
   label: string;
   points: TimePoint[];
+  /** Draw this series in checker `colorIndex`'s hue (0 is the current checker); past the fourth hue it is muted. */
+  colorIndex?: number;
 }
 interface TimeSeriesOptions {
   x: {
     label: string;
     domain: [number, number];
+    /**
+     * An ordinal axis: one column per category, its width proportional to `weight`. Every point sits at a category's
+     * `at`; several points may share a column and are spread across it. Marks and bands between categories are placed
+     * between their columns, and a band bound that names a category covers that column.
+     */
+    categories?: XCategory[];
   };
   y: {
     label: string;
     unit: string;
     domain: [number, number];
+    /** `log` places values on a log10 scale and needs a positive domain. Default: linear. */
+    scale?: YScale;
+    /** Caller-named gridlines, such as check stages, in place of evenly spaced values. */
+    ticks?: YTick[];
+    /** Recorded goals drawn under the data: a shaded band (target) or a dashed one (stretch), a line when from equals to. */
+    targets?: YTarget[];
+    /** The label of the strip under the plot that holds verdicts recorded without a value. Default: no value. */
+    strip?: string;
   };
   formatX?: (value: number) => string;
   formatY?: (value: number) => string;
@@ -214,6 +230,8 @@ interface TimeSeriesOptions {
   marks?: ChartMark[];
   /** Recorded shaded spans on the x axis, such as time after the first pass or idle time; `missing` is hatched. */
   bands?: ChartBand[];
+  /** What each point `marker` stands for, such as `{ circle: "check", diamond: "gate" }`, named in the figure's key. */
+  markers?: Partial<Record<MarkerShape, string>>;
   id?: string;
 }
 export declare function timeSeries(rows: TimeSeriesRow[], o: TimeSeriesOptions): Figure | Refusal;
@@ -222,10 +240,19 @@ export declare function timeSeries(rows: TimeSeriesRow[], o: TimeSeriesOptions):
 interface MultiplePanel {
   id: string;
   label: string;
-  /** The panel's recorded unit. Every panel must match the figure's y unit. */
+  /**
+   * The panel's recorded unit. With `shared: "both"` it must match the figure's y unit; with `shared: "x"` each panel
+   * may record its own (a rate, a size, a time), and the figure's y unit is the default for panels that set none.
+   */
   unit?: string;
+  /** `shared: "x"` only: formats this panel's y values in place of the figure's `formatY`. */
+  format?: (value: number) => string;
   /** The panel's own y domain; required when only the x axis is shared. */
   domain?: [number, number];
+  /** `log` places values on a log10 scale and needs a positive domain. Default: linear. */
+  scale?: YScale;
+  /** Recorded goals drawn under the panel's data, such as a paper's bar: a shaded band, dashed for a stretch. */
+  targets?: YTarget[];
   points?: TimePoint[];
   /** The arm produced no data. The panel is hatched and names the reason. */
   missing?: {
@@ -241,9 +268,11 @@ interface MultiplePanel {
   marks?: ChartMark[];
 }
 interface SmallMultiplesOptions {
+  /** `categories` makes x ordinal, as in `timeSeries`: every panel shares the same columns. */
   x: {
     label: string;
     domain: [number, number];
+    categories?: XCategory[];
   };
   y: {
     label: string;
@@ -254,10 +283,16 @@ interface SmallMultiplesOptions {
   shared: "both" | "x";
   /** What one panel is, for the lede: "3 of 4 arms have data". Default: panel. */
   noun?: string;
+  /** Panels per row in the wide render (default 3); the phone render is one column. */
+  columns?: number;
+  /** false draws points without joining them, for values that are not one trajectory. Default true. */
+  connect?: boolean;
+  /** What each point `marker` stands for, such as `{ circle: "check", diamond: "gate" }`, named in the figure's key. */
+  markers?: Partial<Record<MarkerShape, string>>;
   formatX?: (value: number) => string;
   formatY?: (value: number) => string;
   id?: string;
 }
 export declare function smallMultiples(panels: MultiplePanel[], o: SmallMultiplesOptions): Figure | Refusal;
 //#endregion
-export { type BandKind, type BreakdownInput, type BreakdownOptions, type ChartBand, type ChartMark, type ComparisonIntervalsOptions, type ComparisonRow, type CostBasis, type CostFrontierOptions, type Estimate, type Exclusion, type Figure, type HeatmapCell, type HeatmapColumn, type HeatmapOptions, type HeatmapRow, type HeatmapStatus, type Interval, type IntervalMethod, type LatencyRangeOptions, type LatencyRangeRow, type MarkKind, type MatrixCell, type MetricBarsOptions, type MetricRow, type MultiplePanel, type Observations, type PhaseWaterfallOptions, type RankedRatesOptions, type RateIdentity, type RateRow, type Refusal, type RenderFigureOptions, type Setup, type SmallMultiplesOptions, type TaskMatrixOptions, type Tier, type TierCounts, type TimePoint, type TimeSeriesOptions, type TimeSeriesRow, type TimelineLane, type TimelineOptions, type TimelineSpan, type WaterfallPhase, isRefusal, timeline };
+export { type BandKind, type BreakdownInput, type BreakdownOptions, CHECKER_HUES, type ChartBand, type ChartMark, type ComparisonIntervalsOptions, type ComparisonRow, type CostBasis, type CostFrontierOptions, type Estimate, type Exclusion, type Figure, type HeatmapCell, type HeatmapColumn, type HeatmapOptions, type HeatmapRow, type HeatmapStatus, type Interval, type IntervalMethod, type LatencyRangeOptions, type LatencyRangeRow, type MarkKind, type MarkVerdict, type MatrixCell, type MetricBarsOptions, type MetricRow, type MultiplePanel, OUTCOME_COLORS, OUTCOME_ORDER, type Observations, type PhaseWaterfallOptions, type PointFields, type PointGlyph, type RankedRatesOptions, type RateIdentity, type RateRow, type Refusal, type RenderFigureOptions, type Setup, type SmallMultiplesOptions, type TaskMatrixOptions, type TickOutcome, type Tier, type TierCounts, type TimePoint, type TimeSeriesOptions, type TimeSeriesRow, type TimelineLane, type TimelineOptions, type TimelineSpan, type TimelineTick, type WaterfallPhase, type XCategory, type YScale, type YTarget, type YTick, checkerColor, isRefusal, timeline };