insomni-plot 0.1.0-alpha.0

package/src/grammar/chart.ts

@@ -0,0 +1,1172 @@
+// ---------------------------------------------------------------------------
+// plot() — grammar-of-graphics chart builder
+// ---------------------------------------------------------------------------
+// `plot({ data, ... })` returns an immutable Chart<T>. Each builder method
+// returns a NEW chart with the addition recorded — no in-place mutation.
+// `.mount(canvas, opts?)` / `.render(layer)` / `.toSVG()` materialize the spec.
+
+import type { Color, Frame, FrameTiming, GlyphAtlas, Invalidator, Layer, Padding, Renderer2D } from "insomni";
+import type { AxisTickFormatter, TickSpec } from "../axis.ts";
+import type { AnnotationSpec } from "./annotations.ts";
+import { DEFAULT_PADDING } from "./constants.ts";
+import { coordCartesian, type Coord } from "./coord.ts";
+import type { FacetSpec } from "./facet.ts";
+import type { Geom } from "./geoms/index.ts";
+import type { HoveredHit } from "./geoms/types.ts";
+import { mountChart } from "./mount.ts";
+import { currentData, runPipeline, type ChartConfig } from "./pipeline.ts";
+import type {
+  AlphaScaleOptions,
+  Channel,
+  ColorScaleOptions,
+  PositionScaleOptions,
+  ShapeScaleOptions,
+  SizeScaleOptions,
+} from "./scales.ts";
+import type { Signal } from "insomni/reactivity";
+import { renderSVG } from "./svg.ts";
+import { themeDefault, type Theme } from "./theme.ts";
+
+export type Row = Record<string, unknown>;
+
+export interface PlotSpec<T> {
+  data: readonly T[] | Signal<readonly T[]>;
+  width?: number;
+  height?: number;
+  background?: Color;
+  padding?: Padding;
+  /**
+   * Inner padding inside the plot frame, in pixels. Adds slack between the
+   * axis lines and the data — as if the view were zoomed out a bit. Accepts a
+   * single number applied to all sides, or per-side overrides. Different from
+   * `padding`, which is the *outer* canvas inset before axes/legend/title.
+   */
+  framePadding?: number | { top?: number; right?: number; bottom?: number; left?: number };
+  device?: GPUDevice;
+  /** Initial theme; can be replaced via `.theme(...)`. */
+  theme?: Theme;
+}
+
+/**
+ * Per-axis options surfaced through `chart.axes({ ... })`. `title` accepts
+ * either a string or `{ text, maxWidth }`; `label.maxWidth` clips long tick
+ * labels with an ellipsis.
+ */
+// Re-exported from `../axis.ts` so consumers can pull it from either
+// `insomni-plot/core` (axis-level surface) or `insomni-plot` (grammar
+// surface). Defined in axis.ts to keep core.ts cycle-free.
+export type { AxisTickFormatter } from "../axis.ts";
+
+export interface AxisSpec {
+  title?: string | { text: string; maxWidth?: number };
+  format?: AxisTickFormatter;
+  /**
+   * How many ticks to render:
+   * - `number` — target count (default 5).
+   * - `"auto"` — pick the count from the axis's pixel span (~80px/tick
+   *   horizontal, ~50px/tick vertical). Useful for time-series so dense
+   *   per-day ticks decay to weeks / months / quarters as the view widens.
+   * - `{ interval, step? }` — explicit time interval (time scales only).
+   *   `interval: "quarter"` is sugar for `month, step: 3`.
+   */
+  ticks?: TickSpec;
+  gridLines?: boolean;
+  /** Draw the axis line itself (the spine along the plot frame). Default `true`. */
+  axisLine?: boolean;
+  label?: { maxWidth?: number };
+  /**
+   * Auto-decimate tick labels until they no longer visually overlap.
+   * `"auto"` measures the formatted labels and inflates the effective
+   * `labelStep` accordingly. Useful for dense band axes (≥15 categories)
+   * and time axes whose density shifts under zoom. Default off — opt in
+   * per axis.
+   */
+  labelCollision?: "auto";
+}
+
+export interface AxesSpec {
+  x?: AxisSpec;
+  y?: AxisSpec;
+}
+
+/**
+ * Chart title / subtitle. Each accepts a string or `{ text, maxWidth }` —
+ * the object form clips with an ellipsis when the rendered text exceeds the
+ * given pixel width.
+ */
+export interface TitleSpec {
+  title?: string | { text: string; maxWidth?: number };
+  subtitle?: string | { text: string; maxWidth?: number };
+}
+
+/**
+ * Float-over-plot position. `x` and `y` are normalized to the plot frame
+ * (`0..1`); `justify` controls which corner of the legend's bbox lands on
+ * that point. Inspired by ggplot2's `legend.position = c(x, y)`.
+ */
+export interface LegendInsidePosition {
+  inside: { x: number; y: number };
+  /** Default `"start"` — top-left of legend lands on the point. */
+  justify?: { x?: "start" | "center" | "end"; y?: "start" | "center" | "end" };
+}
+
+export type LegendPosition = "top" | "right" | "bottom" | "left" | LegendInsidePosition;
+
+/**
+ * Channels eligible for being merged into a single legend entry. When merged,
+ * each domain value's swatch shows the resolved value from every listed scale
+ * — e.g. `merge: ["color", "shape"]` produces one row per category whose
+ * swatch is colored by the color scale AND shaped by the shape scale.
+ *
+ * `size` participation is supported only when another categorical channel is
+ * also in the merge list (the entries are still iterated over the categorical
+ * domain; size is sampled from its numeric range at evenly-spaced positions).
+ */
+export type LegendMergeChannel = "color" | "shape" | "size" | "borderStyle" | "overlayGlyph";
+
+export interface LegendSpec {
+  /** Disable the auto-legend. */
+  show?: boolean;
+  /**
+   * Where the legend sits. Outer slots: `"top" | "right" | "bottom" | "left"`.
+   * For an over-plot legend, pass `{ inside: { x, y } }` with `x`/`y` in `0..1`
+   * (plot-frame coords). Default depends on legend type — `"right"` for
+   * continuous color bars, `"top"` for categorical swatches.
+   */
+  position?: LegendPosition;
+  /** Optional title rendered above the legend entries / color bar. */
+  title?: string;
+  /** Override color-bar long-axis pixel length. Default 160. */
+  length?: number;
+  /** Override color-bar thickness. Default 12. */
+  thickness?: number;
+  /** Continuous legend — major tick count target. Default `5`. */
+  ticks?: number;
+  /** Continuous legend — explicit major tick values (override `ticks`). */
+  tickValues?: readonly number[];
+  /**
+   * Continuous legend — minor (unlabeled) tick marks. Number subdivides each
+   * major interval (`2` = one minor halfway); array places ticks explicitly.
+   */
+  minorTicks?: number | readonly number[];
+  /**
+   * Continuous legend — render a tick label every `N`th major tick.
+   * Default `1`. Combine with `minorTicks` for "lines every 0.5, labels
+   * every 1.0" style guides.
+   */
+  labelStep?: number;
+  /** Continuous legend — tick label formatter. */
+  format?: (value: number) => string;
+  /**
+   * Continuous legend — override the color space used to interpolate the
+   * palette stops for the bar's gradient. Falls back to the chart's color
+   * scale (which itself defaults to `theme.paletteBlendSpace = "oklch"`).
+   */
+  blendSpace?: import("insomni").BlendSpace;
+  /**
+   * Merge the listed aesthetic channels into a single combined legend. When
+   * provided, every listed channel must encode the same field (the consumer
+   * is asserting this) and the merged legend iterates the primary scale's
+   * domain (priority: color → shape → borderStyle → overlayGlyph). Each
+   * entry's swatch combines the resolved values across every listed scale.
+   *
+   * Channels that are listed but have no active scale on the chart are
+   * silently skipped — they contribute nothing to the swatch. Omitting this
+   * option leaves the default behavior unchanged (color-only legend).
+   */
+  merge?: readonly LegendMergeChannel[];
+}
+
+export type ScaleOptionsByChannel<C extends Channel> = C extends "x" | "y"
+  ? PositionScaleOptions
+  : C extends "color"
+    ? ColorScaleOptions<unknown>
+    : C extends "size"
+      ? SizeScaleOptions
+      : C extends "alpha"
+        ? AlphaScaleOptions
+        : C extends "shape"
+          ? ShapeScaleOptions
+          : never;
+
+// ---------------------------------------------------------------------------
+// Mount API — what `chart.mount(canvas, opts?)` accepts and returns.
+// ---------------------------------------------------------------------------
+
+export interface TransitionsConfig {
+  /** Duration in milliseconds. Default: theme.motion.data duration (240ms). */
+  duration?: number;
+  /** Stable key for matching rows across data refreshes. Required for enter animations. */
+  key?: (datum: unknown, index: number) => string | number;
+}
+
+/** Handle exposed on MountedPlot to request manual transitions. */
+export interface TransitionsHandle {
+  /** Trigger a transition on the next draw (e.g. after a scale domain change). */
+  requestTransition(): void;
+}
+
+export interface MountPlotOptions<T> {
+  /**
+   * GPU device. Required when the mount has to create a `Renderer2D` or
+   * `GlyphAtlas` (i.e. when you don't pass them yourself). Either source
+   * works — `plot({ device })` or `mount(canvas, { device })`.
+   */
+  device?: GPUDevice;
+
+  /**
+   * Builder closure called on every `invalidate()`. Use this when chart
+   * settings live in module-scope state (controls, signals, etc.) and you
+   * want the chart to be re-derived on each draw. The closure should return
+   * a fresh `Chart<T>` (typically by calling the same `plot().layer()...`
+   * chain that produced this chart).
+   *
+   * If omitted, the mount renders the chart you mounted on, statically.
+   * Either way, `handle.update(newChart | newBuilder)` swaps it.
+   */
+  build?: () => Chart<T>;
+
+  // -----------------------------------------------------------------------
+  // Bring-your-own (advanced, optional)
+  // -----------------------------------------------------------------------
+
+  /**
+   * Use an externally owned renderer. The mount won't call `setBackground`,
+   * `resize`, `setDpr`, or `destroy()` on it — those become the caller's
+   * responsibility. Useful for sharing a single renderer across multiple
+   * charts or compositing a chart over a world-space scene.
+   */
+  renderer?: Renderer2D;
+
+  /**
+   * External layers (axis under, marks middle, hud over). Mount won't clear
+   * them outside the pipeline. The optional `overlay` layer sits on top of the
+   * hud and carries the cursor-driven overlays (tooltip / crosshair / brush /
+   * menu); omit it and the mount creates its own.
+   */
+  layers?: { axis: Layer; marks: Layer; hud: Layer; overlay?: Layer };
+
+  /**
+   * Extra layers rendered alongside the chart's own layers. Called each draw
+   * to read the current list, so callers can lazy-create or swap layers
+   * without re-mounting. Layers returned here are NOT cleared by the chart
+   * pipeline — they persist across draws until the caller clears them
+   * themselves. Use this for retained, world-anchored content (large label
+   * sets that ride the camera, scatter overlays driven by a separate camera
+   * viewport, etc.) where per-frame re-emission would dominate CPU cost.
+   *
+   * Two slots:
+   *   - `belowMarks`: rendered after axes, before chart marks. Behind data.
+   *   - `aboveMarks`: rendered after chart marks, before the HUD. Above
+   *     data but below tooltips / brushes / interactive overlays.
+   */
+  extraLayers?: () => {
+    belowMarks?: readonly Layer[];
+    aboveMarks?: readonly Layer[];
+  };
+
+  // -----------------------------------------------------------------------
+  // Sizing
+  // -----------------------------------------------------------------------
+
+  /** Fixed width (CSS px). When set with `height`, disables auto-resize by default. */
+  width?: number;
+  /** Fixed height (CSS px). When set with `width`, disables auto-resize by default. */
+  height?: number;
+  /** Override DPR. Default: `window.devicePixelRatio`. */
+  dpr?: number;
+  /** Track canvas size via `ResizeObserver`. Default: `true` unless `width` and `height` are both set. */
+  autoResize?: boolean;
+
+  // -----------------------------------------------------------------------
+  // Loop
+  // -----------------------------------------------------------------------
+
+  /** Run an internal `requestAnimationFrame` loop. Default `true`. Set false to call `update()` from your own loop. */
+  autoFrame?: boolean;
+  /** Pause draws while `document.hidden`. Default `true`. */
+  pauseOnHidden?: boolean;
+
+  // -----------------------------------------------------------------------
+  // Visual
+  // -----------------------------------------------------------------------
+
+  /** Background override. Falls back to `chart.background` then `theme.background`. */
+  background?: Color;
+
+  // -----------------------------------------------------------------------
+  // Telemetry
+  // -----------------------------------------------------------------------
+
+  /** Per-frame CPU/GPU timing callback. Forwarded to the underlying `Renderer2D`. */
+  onFrameTiming?: (t: FrameTiming) => void;
+  /** Enable detailed GPU pipeline-level profiling. Forwarded to the underlying `Renderer2D`. */
+  enablePipelineProfiling?: boolean;
+
+  // -----------------------------------------------------------------------
+  // Interactions
+  // -----------------------------------------------------------------------
+
+  /**
+   * Default interactions wired into the chart. Pass `false` to disable all of
+   * them. Pass `true` (or omit) to enable the defaults: a hover tooltip on
+   * geoms that support hit-testing (`point` / `bar` / `line` / `area`) plus a
+   * snapping crosshair on continuous x-scale charts. Pass an object to enable
+   * a subset and tune options.
+   */
+  interactions?: boolean | InteractionsConfig;
+
+  /**
+   * Animated transitions when data or chart config changes. On by default
+   * (inherits `theme.motion.data` duration and easing). Pass `false` to disable.
+   */
+  transitions?: boolean | TransitionsConfig;
+
+  // -----------------------------------------------------------------------
+  // Pan / zoom
+  // -----------------------------------------------------------------------
+
+  /**
+   * Wire up pan/zoom on the chart's x/y scales. Off by default. Pass `true`
+   * to enable with default zoom limits, or an object to override.
+   *
+   * Behavior when enabled:
+   *   - The mount creates a `DataViewport` seeded from the chart's x/y scale
+   *     domain options (the values you passed to `.scale("x", { domain })`).
+   *   - Pointer events on the canvas pan/zoom the viewport.
+   *   - The viewport's visible domains are written back into the chart's x/y
+   *     scale options on every draw, so axes/ticks update automatically.
+   *   - The viewport is exposed on `MountedPlot.viewport` for read-only
+   *     introspection (e.g. a `build:` closure that re-bins data into the
+   *     visible domain).
+   *
+   * Requires both x and y scales to be continuous (linear / log / sqrt /
+   * time). Throws if either scale is missing a numeric/date domain.
+   */
+  panZoom?: boolean | PanZoomConfig;
+
+  /**
+   * Clip marks to the inner plot panel rect. Default `true`. When on, the
+   * mount sets `marksLayer.setClipRect(plotFrame)` after each pipeline run
+   * so geom rects/lines/etc. don't bleed into axis / legend / title slots.
+   */
+  clipMarks?: boolean;
+
+  /**
+   * Damage-tracked partial redraw. On by default — set `false` to opt out,
+   * which renders byte-identically to the classic full-frame path.
+   *
+   * When on (and the mount owns its renderer), the renderer is given a
+   * persistent backbuffer and the static marks are baked to a texture, so
+   * cursor-driven overlays (tooltip / crosshair / brush / menu) repaint only
+   * their own damage rect instead of clearing + re-compiling the whole chart
+   * on every pointer move. View-changing events (data, pan/zoom, resize,
+   * selection, legend toggle, transitions) still run a full frame and re-bake.
+   *
+   * Silently ignored when an external `renderer` or `layers` is supplied (the
+   * mount can't reconfigure pieces it doesn't own); only an *explicit*
+   * `partialRedraw: true` in that situation logs a one-time warning.
+   */
+  partialRedraw?: boolean;
+}
+
+/**
+ * Per-axis pan / zoom enable. Either axis can be silenced independently.
+ * Sugar: `true` ≡ `"xy"`, `false` ≡ `"none"`.
+ */
+export type PanZoomAxes = "x" | "y" | "xy" | "none";
+
+/**
+ * Pan-bound margins, expressed as fractions of the visible span. A bare
+ * number applies to both axes. See `DataPanBoundsOptions` for the full
+ * `{ overshoot, drift }` shape inherited from the viewport.
+ */
+export type ChartPanBounds = ChartPanBoundsOptions | false;
+
+export interface ChartPanBoundsOptions {
+  /** Pan-past-content allowance when zoomed in (content > viewport). */
+  overshoot?: number | { x?: number; y?: number };
+  /** Drift allowance when zoomed out (content ≤ viewport). */
+  drift?: number | { x?: number; y?: number };
+}
+
+export interface PanZoomConfig {
+  /**
+   * Minimum zoom factor relative to the chart's base domain. `1` means the
+   * user cannot zoom *out* past the data extent — a sensible chart default.
+   * Smaller values (e.g. `0.1`) allow zooming out into empty space.
+   *
+   * Default `1` (zoom-out clamped to the data extent).
+   */
+  minZoom?: number;
+  /**
+   * Maximum zoom factor relative to the chart's base domain. `100` lets the
+   * user zoom in to 1% of the data range — usually a sane floor before axis
+   * ticks and labels collapse.
+   *
+   * Default `100`.
+   */
+  maxZoom?: number;
+  /**
+   * Pan-bound the visible domain to the chart's base (data) domain. When
+   * zoomed in, panning stops at content edges plus an `overshoot` margin;
+   * when zoomed out far enough that content fits in view, the viewport can
+   * still drift by `drift × visibleSpan`.
+   *
+   * Default `{ overshoot: 0.1 }` (the user can rubber-band 10% past the
+   * data edges but can't drag the chart fully off-screen). Pass `false`
+   * to opt out entirely.
+   */
+  panBounds?: ChartPanBounds;
+  /**
+   * Lock pan to a subset of axes. Default `"xy"` (both axes pan).
+   */
+  pan?: PanZoomAxes;
+  /**
+   * Lock zoom to a subset of axes. Default `"xy"` (both axes zoom).
+   */
+  zoom?: PanZoomAxes;
+  /**
+   * When set, the Y scale's domain is recomputed every frame from whatever
+   * data is currently visible along X (financial-chart "auto-Y" behavior).
+   * Implies `pan: "x"` and `zoom: "x"` — Y becomes read-only.
+   *
+   * `true` uses the default 5% padding around the visible Y extent; pass
+   * `{ padding }` to override (0..0.5).
+   *
+   * The Y scale must still declare an explicit `domain` (used as a fallback
+   * when no data is visible in the current X window).
+   */
+  yFit?: boolean | { padding?: number };
+}
+
+export interface InteractionsConfig {
+  tooltip?: boolean | TooltipConfig;
+  /**
+   * Hover crosshair (guide line). Default: enabled on charts whose x-scale
+   * is continuous (`linear` / `log` / `sqrt` / `time`); auto-disabled on
+   * band x-scales. Pass `false` to disable, `true` for defaults, or an
+   * object to tune. Snaps to the same hit positions the tooltip uses.
+   */
+  crosshair?: boolean | CrosshairConfig;
+  /**
+   * Click-to-select. Off by default — selection has app-level semantics so
+   * the chart shouldn't claim it silently. Pass `true` to enable defaults
+   * (plain click replaces, shift toggles, meta/ctrl removes, click-empty
+   * clears) or an object to tune. The active selection is exposed on
+   * `MountedPlot.selected` and surfaces to geoms via `CompileContext.selected`
+   * — selected rows get a stroke ring and unselected rows dim while a
+   * selection is active.
+   */
+  selection?: boolean | SelectionConfig;
+  /**
+   * Drag-to-rect brush. Off by default — like click-selection, brush semantics
+   * are app-specific. Pass `true` to enable defaults (xy rect, dismiss on
+   * background tap) or an object to tune. The active brushed rows are exposed
+   * on `MountedPlot.brushed`. Brush populates a separate signal from
+   * click-selection so the two coexist with different semantics (range query
+   * vs. discrete pick).
+   */
+  brush?: boolean | BrushConfig;
+  /**
+   * Legend interactivity. Default: enabled when `interactions` is on.
+   * Enables click-to-toggle visibility of categorical series.
+   */
+  legend?: boolean | LegendInteractionConfig;
+  /**
+   * Context-menu trigger. Off by default — requires an `onTrigger` handler so
+   * the host app can render its own menu UI. Fires for right-click, touch
+   * long-press (≥500ms), and the keyboard ContextMenu / Shift+F10 keys. The
+   * library only emits the event; menu rendering / positioning stays the
+   * consumer's responsibility.
+   */
+  contextMenu?: ContextMenuConfig;
+}
+
+export interface ContextMenuConfig {
+  /**
+   * Resolution policy for the trigger point. Default `"nearest-point"`.
+   *
+   * - `"nearest-point"`: snap to the nearest mark within its `pickRadius`
+   *   (skips region-based geoms like bars). When no mark is within range, the
+   *   trigger is **suppressed entirely** — matches the behavior of the hover
+   *   tooltip / crosshair (no popup unless something would be highlighted).
+   * - `"any-mark"`: include region-based geoms (bars, histograms, tiles).
+   *   Same suppression behavior as `"nearest-point"` when no mark is hit.
+   * - `"background"`: never resolve — `hit`/`datum`/`mark` are always null,
+   *   and the trigger always fires. Useful for "add a point here" menus.
+   */
+  hitMode?: "nearest-point" | "any-mark" | "background";
+  /** Touch long-press hold duration (ms). Default `500`. */
+  holdMs?: number;
+  /** Max pointer movement during long-press hold (CSS px). Default `5`. */
+  slopPx?: number;
+  /**
+   * Menu items. Static array or a per-trigger resolver. When provided, the
+   * library renders a GPU-drawn menu inside the canvas (no DOM, no host
+   * popover required) and routes clicks through `onAction`. When omitted the
+   * library only emits `onTrigger` and rendering is the consumer's problem.
+   */
+  items?:
+    | readonly ContextMenuItem[]
+    | ((info: ContextMenuTriggerPayload) => readonly ContextMenuItem[]);
+  /** Called when an item in the rendered menu is clicked. */
+  onAction?(itemId: string, info: ContextMenuTriggerPayload): void;
+  /** Placement of the rendered menu relative to the trigger point. */
+  placement?: import("insomni").MenuPlacement;
+  /** Style overrides for the rendered menu. */
+  style?: import("insomni").MenuStyle;
+  /**
+   * Low-level trigger callback. Fires even when `items` is set, so consumers
+   * can hook telemetry / aria-live announcements alongside the rendered menu.
+   * Required only when `items` is omitted (otherwise the library has no idea
+   * what menu to show).
+   */
+  onTrigger?(info: ContextMenuTriggerPayload): void;
+}
+
+export interface ContextMenuItem {
+  /** Stable id passed to `onAction`. Ignored for separators. */
+  id: string;
+  /** Display label. Ignored for separators. */
+  label: string;
+  /** Renders as a thin separator line; non-interactive. */
+  separator?: boolean;
+  /** Greyed out; ignored by hover/click. */
+  disabled?: boolean;
+  /** Tinted with the menu's `dangerColor` (destructive actions). */
+  danger?: boolean;
+  /** Optional swatch dot at the start of the row. */
+  swatch?: Color;
+  /** Optional right-aligned shortcut hint (e.g. "⌘D"). */
+  kbd?: string;
+}
+
+export interface ContextMenuTriggerPayload {
+  /**
+   * Resolved hit at the trigger point, or `null` for a background trigger /
+   * `hitMode: "background"`.
+   */
+  hit: HoveredHit | null;
+  /** Convenience: the data row at `hit.dataIndex`, or `null` for background. */
+  datum: unknown | null;
+  /** Convenience: the geom kind that produced the hit. */
+  mark: HoveredHit["geomKind"] | null;
+  /** Element-local CSS px where the menu should anchor. */
+  screenX: number;
+  screenY: number;
+  source: "mouse" | "touch" | "pen" | "keyboard";
+  mods: import("insomni").Mods;
+  originalEvent: Event | null;
+}
+
+export interface LegendInteractionConfig {
+  /** Default `0.2` — alpha for hidden series labels/swatches. */
+  dimAlpha?: number;
+}
+
+/**
+ * Semantic accents for `TooltipShorthandRow.accent`. `positive` / `negative`
+ * resolve through `theme.interactions.tooltipAccents`. `neutral` is a
+ * no-op marker — the row uses the default text color. Passing a raw `Color`
+ * bypasses theme tokens entirely.
+ */
+export type TooltipAccent = "positive" | "negative" | "neutral" | Color;
+
+export interface TooltipShorthandRow {
+  label?: string;
+  /**
+   * Row value. Numbers / Dates / null / undefined are formatted through the
+   * library's default formatter; strings are emitted verbatim.
+   */
+  value: string | number | Date | boolean | null | undefined;
+  /** Optional swatch dot to the left of the row. */
+  swatch?: Color;
+  /**
+   * Semantic accent applied to the row's text color (positive/negative tint
+   * for diffs, deltas, status changes). `neutral` is a no-op.
+   */
+  accent?: TooltipAccent;
+}
+
+/**
+ * Shorthand object form of `TooltipContent`. The grammar normalizes this into
+ * the canvas-tooltip's full `TooltipContent` shape, applying default
+ * formatting to non-string values and resolving accents through the theme.
+ */
+export interface TooltipContentShorthand {
+  title?: string;
+  rows: readonly TooltipShorthandRow[];
+}
+
+export interface TooltipContentInfo<T = unknown> {
+  /** The hovered datum (the row from the geom's data array). */
+  datum: T;
+  /** Index into the data array. */
+  dataIndex: number;
+  /** Geom kind (e.g. `"point"`, `"bar"`, `"line"`). */
+  mark: string;
+  /** Series key when the geom emits multiple segments per row (stacks, dodges). */
+  seriesKey?: string;
+  /**
+   * Resolved aesthetic accessors for the geom. Useful for advanced resolvers
+   * that need to read a channel's raw value or column name — most consumers
+   * can ignore this and just read fields off `datum`.
+   */
+  channels: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Override the auto-built tooltip content. Receives the hovered datum and
+ * returns either the canvas-tooltip's full `TooltipContent` (with
+ * `swatch`/`color`/`fontSize` per row), the shorthand `{ title, rows }` form
+ * with optional `accent` tokens, or a plain string (single-row body), or
+ * `null` to fall back to the default channel-driven content.
+ */
+export type TooltipContentResolver<T = unknown> = (
+  info: TooltipContentInfo<T>,
+) => TooltipContentResult | null | undefined;
+
+export type TooltipContentResult = TooltipContentShorthand | string;
+
+/** One auto-built series row in axis-mode tooltips (mirrors SeriesReadoutRow). */
+export interface AxisTooltipRow {
+  /** Series label (color-channel value, seriesKey, or layer label). */
+  label: string;
+  /** Formatted value at the snapped column. */
+  value: string;
+  /** Raw value at the snapped column (pre-format) for custom transforms. */
+  rawValue: unknown;
+  /** Series swatch color, when resolvable. */
+  color?: Color;
+  /** True for the row whose snapped position is closest to the cursor. */
+  active: boolean;
+  /** seriesKey when the row came from a stacked / dodged segment. */
+  seriesKey?: string;
+}
+
+/** Info handed to the axis-mode tooltip content hook. */
+export interface AxisTooltipInfo {
+  /** Raw snapped column value (the X for `axis:"x"`, the Y for `axis:"y"`). */
+  columnValue: unknown;
+  /** Formatted column value (`axisTitleFormat` / `defaultFormat`). */
+  columnLabel: string;
+  /** Which screen axis we snapped on. */
+  axis: "x" | "y";
+  /** Auto-built series rows (one per series at the snapped column). */
+  rows: readonly AxisTooltipRow[];
+  /**
+   * The snapped datum(s) — one entry per hit-testable layer that produced a
+   * group at this column, in layer order. Each carries the source datum, its
+   * data index, and the layer's mark label, so a consumer can read any field
+   * off a wide row (incl. fields belonging to ribbon/band/text layers that
+   * have no hit tests of their own). For wide rows, `data[0].datum` already
+   * holds every column.
+   */
+  data: readonly { datum: unknown; dataIndex: number; mark: string }[];
+}
+
+/**
+ * Axis-mode tooltip content hook. Return a `{ title?, rows }` shorthand (the
+ * same shape the item resolver returns) to REPLACE the auto rows, or
+ * `null` / `undefined` to keep them verbatim. `accent` / `swatch` per row
+ * resolve through the theme exactly like the item path.
+ */
+export type AxisTooltipContentResolver = (
+  info: AxisTooltipInfo,
+) => TooltipContentShorthand | null | undefined;
+
+export interface TooltipConfig {
+  showDelay?: number;
+  hideDelay?: number;
+  fadeMs?: number;
+  placement?: "top" | "bottom" | "left" | "right" | "auto";
+  /**
+   * Override the default channel-driven tooltip body. Receives the hovered
+   * datum and returns either:
+   *   - a plain string (single-row body, no label)
+   *   - a `{ title?, rows: [{label?, value, accent?, swatch?}] }` shorthand —
+   *     `accent: "positive" | "negative" | "neutral" | Color` tints the row
+   *     text via `theme.interactions.tooltipAccents`
+   *   - `null` / `undefined` to fall back to the auto-built content
+   *
+   * The library renders the canvas tooltip primitive — there's no HTML/CSS
+   * surface to style; row colors come from the theme.
+   *
+   * Ignored in `trigger:"axis"` mode (use `axisContent`).
+   */
+  content?: TooltipContentResolver;
+  /**
+   * Tooltip trigger model. Default `"item"` (today's behavior — one box per
+   * hovered mark, fully backward compatible). `"axis"` turns the tooltip into
+   * a floating, cursor-following unified readout: it snaps to the nearest data
+   * column across ALL hit-testable layers and lists one row per series in a
+   * single box.
+   */
+  trigger?: "item" | "axis";
+  /**
+   * Which screen axis to snap on in `trigger:"axis"` mode. `"x"` (default) =
+   * nearest-X (vertical time-series — pick the column under the cursor's x).
+   * `"y"` = nearest-Y (horizontal charts — pick the row under the cursor's y).
+   * Ignored when `trigger:"item"`.
+   */
+  axis?: "x" | "y";
+  /**
+   * Axis-mode content hook. Receives the snapped column plus the auto-built
+   * series rows AND the snapped datum(s), so a consumer can append rows that
+   * are NOT y-series (a wind-direction arrow, a day/night flag, a UV risk
+   * band) or transform the auto rows. Return value REPLACES the auto rows when
+   * non-null; return null/undefined to keep the auto-built rows verbatim.
+   * Ignored unless `trigger:"axis"`.
+   */
+  axisContent?: AxisTooltipContentResolver;
+  /** Format the snapped column value used as the tooltip title in axis mode. */
+  axisTitleFormat?: (value: unknown) => string;
+  /** Format each auto-built series row's value in axis mode. */
+  axisValueFormat?: (value: unknown) => string;
+}
+
+export interface CrosshairConfig {
+  /** Which guide line(s) to draw. Default `"x"` (vertical line tracking cursor). */
+  axis?: "x" | "y" | "xy";
+  /** Stroke color. Default theme.colors.muted at 0.6 alpha. */
+  color?: Color;
+  /** Stroke width in CSS px. Default 1. */
+  width?: number;
+  /**
+   * Track the raw pointer position even between data points (no snap). Useful
+   * for sparse line/area charts where the snapped-to-hit default leaves big
+   * gaps. Snapping still wins when the cursor is over a hit; outside hits the
+   * crosshair follows the cursor within the plot frame. Default `false`.
+   */
+  followPointer?: boolean;
+}
+
+export interface BrushConfig {
+  /** Which axes the brush spans. Default `"xy"`. */
+  axis?: "x" | "y" | "xy";
+  /** Translucent fill. Default theme axis color × 0.12 alpha. */
+  fillColor?: Color;
+  /** Outline color. Default theme axis color × 0.6 alpha. */
+  strokeColor?: Color;
+  /** Outline width in CSS px. Default 1. */
+  strokeWidth?: number;
+  /** Enable edge/corner resize handles. Default `true`. */
+  handles?: boolean;
+  /** Enable drag-the-rect-interior translate. Default `true`. */
+  translate?: boolean;
+  /**
+   * Snap brush rect edges to nearest hit-test position. `true` snaps on the
+   * brush's `axis`; pass `"x"` / `"y"` / `"xy"` to override. Default `false`.
+   */
+  snap?: boolean | "x" | "y" | "xy";
+}
+
+/**
+ * Read-only view of a `Signal<HoveredHit[]>` exposed on `MountedPlot.brushed`.
+ * Empty array when nothing is brushed; remains an empty array (never `null`)
+ * when brush is disabled. Independent of `selected` — click + brush coexist
+ * with different semantics.
+ */
+export interface BrushedSignal {
+  get(): readonly HoveredHit[];
+  peek(): readonly HoveredHit[];
+  subscribe(fn: (v: readonly HoveredHit[]) => void): () => void;
+  /** Imperatively clear the active brush. */
+  clear(): void;
+}
+
+export interface SelectionConfig {
+  /**
+   * Alpha applied to non-selected marks while a selection is active. Default
+   * `0.3`. Set `1` to disable dimming (selected rows still get a stroke ring).
+   */
+  dimAlpha?: number;
+  /** Stroke ring color override; defaults to theme.axis.color. */
+  ringColor?: Color;
+  /** Stroke ring width in CSS px. Default 2. */
+  ringWidth?: number;
+}
+
+/**
+ * Read-only view of a `Signal<HoveredHit[]>` exposed on `MountedPlot`. The
+ * array is empty when nothing is selected; `null` is never produced (use
+ * `length === 0` to detect the empty case).
+ */
+export interface SelectedSignal {
+  get(): readonly HoveredHit[];
+  peek(): readonly HoveredHit[];
+  subscribe(fn: (v: readonly HoveredHit[]) => void): () => void;
+  /** Imperatively clear the active selection. */
+  clear(): void;
+}
+
+/**
+ * Read-only view of a `Signal<ReadonlySet<string>>` exposed on `MountedPlot.hidden`.
+ * Empty set when all series are visible.
+ */
+export interface HiddenSignal {
+  get(): ReadonlySet<string>;
+  peek(): ReadonlySet<string>;
+  subscribe(fn: (v: ReadonlySet<string>) => void): () => void;
+  /** Clear the hidden set (show all). */
+  clear(): void;
+}
+
+/**
+ * Read-only view of a `Signal<HoveredHit | null>` exposed on `MountedPlot`.
+ * Drops `set`/`update` so callers can subscribe + peek without writing.
+ */
+export interface HoveredSignal {
+  get(): HoveredHit | null;
+  peek(): HoveredHit | null;
+  subscribe(fn: (v: HoveredHit | null) => void): () => void;
+}
+
+export interface MountedPlot<T> {
+  /** Schedule a redraw on the next animation frame. */
+  invalidate(): void;
+  /**
+   * Replace the active chart spec or builder.
+   * - Pass a `Chart<T>` to swap to a static spec.
+   * - Pass `() => Chart<T>` to swap the rebuild closure.
+   * - Pass nothing to force a rebuild via the existing builder.
+   *
+   * When `autoFrame: false`, also draws synchronously.
+   */
+  update(source?: Chart<T> | (() => Chart<T>)): void;
+  /** Replace the data array (drops any reactive data signal subscription). */
+  setData(data: readonly T[]): void;
+  /**
+   * Manual resize. If `autoResize` is on you usually don't need this.
+   * Pass no args to re-read the canvas's current bounding rect.
+   */
+  resize(w?: number, h?: number): void;
+  /** Override the background color. Pass `null` to revert to the chart/theme default. */
+  setBackground(color: Color | null): void;
+  /** Static SVG export from the current spec + data. */
+  toSVG(opts?: { width?: number; height?: number; atlas?: GlyphAtlas }): SVGSVGElement;
+  /** Tear down: cancels the rAF loop, ResizeObserver, signal subs; destroys what we created. */
+  destroy(): void;
+
+  // -----------------------------------------------------------------------
+  // Escape hatches — read-only refs to internal pieces.
+  // -----------------------------------------------------------------------
+
+  readonly renderer: Renderer2D;
+  readonly axisLayer: Layer;
+  readonly marksLayer: Layer;
+  readonly hudLayer: Layer;
+  /** Cursor-overlay layer (tooltip / crosshair / brush / menu), above the hud. */
+  readonly overlayLayer: Layer;
+  readonly invalidator: Invalidator;
+  /**
+   * Read-only signal carrying the currently hovered hit (geom kind, dataIndex,
+   * data array reference, snapped position) or `null` when nothing is
+   * hovered. Updated synchronously from pointer events. Geoms also receive
+   * the same value via `CompileContext.hovered` during compile.
+   */
+  readonly hovered: HoveredSignal;
+  /**
+   * Read-only signal carrying the currently selected rows (one `HoveredHit`
+   * per selected datum). Empty array when nothing is selected; remains an
+   * empty array (never `null`) when selection is disabled. Geoms receive
+   * the same payload via `CompileContext.selected` during compile.
+   */
+  readonly selected: SelectedSignal;
+  /**
+   * Read-only signal carrying the rows currently inside the brush rect.
+   * Empty array when nothing is brushed (or when brush is disabled).
+   * Independent of `selected`.
+   */
+  readonly brushed: BrushedSignal;
+  /**
+   * Read-only signal carrying the set of series keys currently hidden via
+   * legend toggle. Empty set when all series are visible; remains an empty
+   * set (never `null`) when legend interaction is disabled.
+   */
+  readonly hidden: HiddenSignal;
+
+  // -----------------------------------------------------------------------
+  // Transitions
+  // -----------------------------------------------------------------------
+
+  /**
+   * Handle for programmatic transition control. Always present even when
+   * transitions are disabled (calls become no-ops in that case).
+   */
+  readonly transitions: TransitionsHandle;
+
+  // -----------------------------------------------------------------------
+  // Stats
+  // -----------------------------------------------------------------------
+
+  /** CSS-pixel width currently rendered. */
+  readonly width: number;
+  /** CSS-pixel height currently rendered. */
+  readonly height: number;
+  /** Active device-pixel ratio. */
+  readonly dpr: number;
+  /** Combined shape count across the three internal layers. */
+  readonly shapeCount: number;
+  /** Combined triangle count across the three internal layers. */
+  readonly triangleCount: number;
+  /** True when `invalidate()` has been called and a draw hasn't happened yet. */
+  readonly needsFrame: boolean;
+  /**
+   * Inner plot panel rect (absolute element-CSS px) — the area enclosed by
+   * the axes, where geom marks draw. Updated each frame from the pipeline.
+   * For faceted charts this is the union of all panel frames. Returns a
+   * zero-rect before the first draw.
+   */
+  readonly plotFrame: Frame;
+
+  /**
+   * The chart's pan/zoom viewport, present only when `panZoom` was enabled
+   * on mount. Lets the caller subscribe to view changes, read the visible
+   * domain (e.g. for re-binning data), or call `.reset()`. The mount keeps
+   * its frame in sync with `plotFrame` automatically.
+   */
+  readonly viewport: import("../viewport.ts").DataViewport<number, number> | null;
+
+  /**
+   * Wire a `createRangePresets` controller against this chart's viewport and
+   * optionally render a chip strip into a host element. Throws if `panZoom`
+   * was not enabled at mount time (no `viewport` to drive).
+   *
+   * The headless flow is preserved — omit `opts.ui` and you get the same
+   * controller (`setActive` / `getActive` / `subscribe`) without any DOM
+   * construction. Strings in `presets` are expanded to `timePreset(key)`.
+   */
+  attachRangePresets(
+    opts: import("./attach-presets.ts").AttachRangePresetsOptions,
+  ): import("./attach-presets.ts").AttachedRangePresets;
+
+  /**
+   * Attach a dygraph-style pinned legend — a side panel that updates with each
+   * series' value at the cursor's snapped x. Reuses the chart's compiled
+   * hit-tests (no separate spatial index) so the snap stays aligned with what
+   * the tooltip would have shown.
+   *
+   * Headless: omit `opts.ui` and observe via `subscribe()` to render your own
+   * UI. With `opts.ui` set, a minimal absolute-positioned panel is appended
+   * into the mount element and disposed alongside this readout.
+   */
+  attachSeriesReadout(
+    opts: import("./interactions/series-readout.ts").AttachSeriesReadoutOptions,
+  ): import("./interactions/series-readout.ts").AttachedSeriesReadout;
+
+  /**
+   * Wire a drag-to-rect brush onto the chart imperatively. Mirrors the
+   * declarative `interactions: { brush: ... }` config path — the same
+   * `MountedPlot.brushed` signal observes the brushed set — but lets a
+   * consumer attach (and later dispose) a brush after mount without
+   * rebuilding the chart spec.
+   *
+   * Throws if a brush is already configured on this mount, either via
+   * `interactions.brush` or a prior `attachBrush` call that hasn't been
+   * disposed. The two surfaces are mutually exclusive: the brush rect is a
+   * singleton.
+   */
+  attachBrush(
+    opts: import("./attach-brush.ts").AttachBrushOptions,
+  ): import("./attach-brush.ts").AttachedBrush;
+
+  /**
+   * Convert an event-relative canvas coordinate (e.g. `event.offsetX/Y`, or
+   * `clientX - rect.left`) into the chart's data space, routing through the
+   * active coord's `unproject` (identity for Cartesian, polar inverse for
+   * `coordPolar` / `coordRadial`).
+   *
+   * Returns `null` when:
+   *   - the point falls outside the active plot frame, or
+   *   - `coord.unproject` returns null (e.g. polar point outside the radius
+   *     band), or
+   *   - the pipeline has not produced scales yet (no draw has happened), or
+   *   - either position scale lacks an `invert` (band scales).
+   *
+   * `dataX` / `dataY` are the result of `xScale.axisScale.invert(plotFrameX)`
+   * and `yScale.axisScale.invert(plotFrameY)` respectively. `plotFrameX/Y` are
+   * relative to the plot frame's top-left.
+   *
+   * This is the screen → data primitive consumers use to drive picking on top
+   * of their own spatial index. The mount doesn't know what's in the chart —
+   * downstream layers (phylo's `hitTestPhylo`, custom geoms, etc.) take it
+   * from here.
+   */
+  pickAt(
+    canvasX: number,
+    canvasY: number,
+  ): {
+    plotFrameX: number;
+    plotFrameY: number;
+    dataX: number;
+    dataY: number;
+    frame: Frame;
+  } | null;
+}
+
+/** @deprecated kept for back-compat; use `MountedPlot<T>`. */
+export type MountedChart<T = Row> = MountedPlot<T>;
+
+// ---------------------------------------------------------------------------
+// Render target — for hand-wired use without mount().
+// ---------------------------------------------------------------------------
+
+export interface RenderTarget {
+  axisLayer: Layer;
+  marksLayer: Layer;
+  hudLayer: Layer;
+  width?: number;
+  height?: number;
+}
+
+export interface Chart<T> {
+  layer(geom: Geom<T>): Chart<T>;
+  layers(geoms: readonly Geom<T>[]): Chart<T>;
+  /**
+   * Configure a scale. `domain` is always optional — when omitted it is
+   * inferred from the data, and when `panZoom` is enabled on `.mount()` the
+   * pipeline overrides the x/y position-scale domain each frame from the
+   * viewport's visible window. Consumers should NOT re-thread the viewport's
+   * visible domain back through `.scale()` from a `build:` closure; it's
+   * redundant and forces a rebuild on every dirty draw.
+   */
+  scale<C extends Channel>(channel: C, options: ScaleOptionsByChannel<C>): Chart<T>;
+  axes(spec: AxesSpec): Chart<T>;
+  title(spec: TitleSpec | string): Chart<T>;
+  legend(spec: LegendSpec | false): Chart<T>;
+  /** Add a free-form text/box annotation. Multiple calls accumulate. */
+  annotate(spec: AnnotationSpec): Chart<T>;
+  /** Split data into a grid of panels by `spec.by`. Replaces any prior facet. */
+  facet(spec: FacetSpec<T>): Chart<T>;
+  /**
+   * Set the coordinate system. Defaults to `coordCartesian()`. Polar / radial
+   * coords land in Phase 3 of the phylo-on-plot rewrite.
+   */
+  coord(coord: Coord): Chart<T>;
+  theme(theme: Theme): Chart<T>;
+  /**
+   * Bind this chart to a canvas. The mount owns the renderer, atlas, three
+   * layers, rAF loop, ResizeObserver and visibility-pause unless you pass
+   * your own pieces in `opts`. See `MountPlotOptions` for every escape hatch.
+   */
+  mount(canvas: HTMLCanvasElement, opts?: MountPlotOptions<T>): MountedPlot<T>;
+  /**
+   * Compile + emit into externally owned layers. Use when the host already
+   * owns a `Renderer2D` (and wants its own per-frame timing). For simpler
+   * cases, prefer `mount(canvas)`.
+   */
+  render(target: RenderTarget): void;
+  /** Static SVG export. Caller mounts the returned element where they want. */
+  toSVG(options?: { width?: number; height?: number; atlas?: GlyphAtlas }): SVGSVGElement;
+}
+
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+
+function resolveFramePadding(fp: PlotSpec<unknown>["framePadding"]): {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+} {
+  if (fp === undefined) return { top: 0, right: 0, bottom: 0, left: 0 };
+  if (typeof fp === "number") return { top: fp, right: fp, bottom: fp, left: fp };
+  return {
+    top: fp.top ?? 0,
+    right: fp.right ?? 0,
+    bottom: fp.bottom ?? 0,
+    left: fp.left ?? 0,
+  };
+}
+
+export function plot<T>(spec: PlotSpec<T>): Chart<T> {
+  const config: ChartConfig<T> = {
+    data: spec.data,
+    width: spec.width,
+    height: spec.height,
+    background: spec.background,
+    padding: spec.padding ?? DEFAULT_PADDING,
+    framePadding: resolveFramePadding(spec.framePadding),
+    device: spec.device,
+    externalAtlas: undefined,
+    theme: spec.theme ?? themeDefault,
+    layers: [],
+    axes: {},
+    titles: {},
+    legend: { show: true },
+    scaleOverrides: {},
+    annotations: [],
+    coord: coordCartesian(),
+  };
+  return makeChart(config);
+}
+
+function makeChart<T>(config: ChartConfig<T>): Chart<T> {
+  const chart: Chart<T> = {
+    layer(geom) {
+      return makeChart({ ...config, layers: [...config.layers, geom] });
+    },
+    layers(geoms) {
+      return makeChart({ ...config, layers: [...config.layers, ...geoms] });
+    },
+    scale(channel, options) {
+      return makeChart({
+        ...config,
+        scaleOverrides: { ...config.scaleOverrides, [channel]: options },
+      });
+    },
+    axes(spec) {
+      return makeChart({ ...config, axes: { ...config.axes, ...spec } });
+    },
+    title(spec) {
+      const next = typeof spec === "string" ? { title: spec } : spec;
+      return makeChart({ ...config, titles: { ...config.titles, ...next } });
+    },
+    legend(spec) {
+      const next: LegendSpec = spec === false ? { show: false } : { show: true, ...spec };
+      return makeChart({ ...config, legend: next });
+    },
+    annotate(spec) {
+      return makeChart({ ...config, annotations: [...config.annotations, spec] });
+    },
+    facet(spec) {
+      return makeChart({ ...config, facet: spec });
+    },
+    coord(coord) {
+      return makeChart({ ...config, coord });
+    },
+    theme(theme) {
+      return makeChart({ ...config, theme });
+    },
+    mount(canvas, opts) {
+      return mountChart(config, canvas, opts);
+    },
+    render(target) {
+      const data = currentData(config.data);
+      const snapshot: ChartConfig<T> = {
+        ...config,
+        width: target.width ?? config.width,
+        height: target.height ?? config.height,
+      };
+      runPipeline(
+        snapshot,
+        data,
+        target.axisLayer,
+        target.marksLayer,
+        target.hudLayer,
+        config.externalAtlas,
+      );
+    },
+    toSVG(options = {}) {
+      return renderSVG(config, options.width, options.height, options.atlas);
+    },
+  };
+  // Stash the frozen config so `mount()` can compile against it without
+  // re-deriving from the immutable builder chain. Non-enumerable to keep it
+  // out of devtools / spreads. See mount.ts:configOf().
+  Object.defineProperty(chart, "__config__", { value: config, enumerable: false });
+  return chart;
+}