insomni-plot 0.1.0-alpha.0

package/src/grammar/chart.d.ts

@@ -0,0 +1,952 @@
+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 { 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 type { AlphaScaleOptions, Channel, ColorScaleOptions, PositionScaleOptions, ShapeScaleOptions, SizeScaleOptions } from "./scales.ts";
+import type { Signal } from "insomni/reactivity";
+import { 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.
+ */
+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;
+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>;
+    /**
+     * 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[];
+    };
+    /** 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;
+    /** 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;
+    /** Background override. Falls back to `chart.background` then `theme.background`. */
+    background?: Color;
+    /** 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    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;
+    /**
+     * Handle for programmatic transition control. Always present even when
+     * transitions are disabled (calls become no-ops in that case).
+     */
+    readonly transitions: TransitionsHandle;
+    /** 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>;
+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;
+}
+export declare function plot<T>(spec: PlotSpec<T>): Chart<T>;