insomni-plot 0.1.0-alpha.0

package/dist/index.d.mts

@@ -0,0 +1,3426 @@
+import { $t as SwatchSpec, C as KdeBandwidth, D as QuantileMethod, Dn as LineDashStyle, Dr as TimeIntervalUnit, Jn as StackOrder, Nn as PointShapeKind, O as WhiskerRule, Or as TimeScale, Qn as LineCurve, S as HistogramMeasure, Sn as BarOrientation, Tr as NumericRange, U as RollingWindow, V as RollingStatistic, bn as BarBorderStyle, br as ContinuousScale, c as RangePresetsSubscriber, cn as LabelBoxStyle, cr as AxisTickFormatter, dn as ValueLabelAlign, dr as TickSpec, ft as CategoricalPalette, g as BinClosed, i as RangePresetDataDomain, jn as PointBorderStyle, kn as MarkBuilder, l as TimePresetKey, or as AxisOptions, pt as ContinuousPalette, t as RangePreset, tt as DataViewport, ur as TickIntervalSpec, v as BinResult, vr as BandScale, w as KdeKernel, y as BinRule, z as RollingAxis } from "./range-presets-CzECsu3V.mjs";
+import * as _$insomni from "insomni";
+import { BlendSpace, BlendSpace as BlendSpace$1, BrushAxis, BrushRect, Color, Easing, Frame, FrameTiming, GlyphAtlas, InteractionManager, Invalidator, Layer, Padding, Renderer2D } from "insomni";
+import { Signal } from "insomni/reactivity";
+
+//#region src/grammar/accessibility.d.ts
+type AccessibilityMode = "auto-color" | "outline" | "shadow" | "none";
+type ContrastMetric = "wcag" | "apca";
+interface Accessibility {
+  /**
+   * Master switch. When `false`, `resolveTextColor` never alters colors —
+   * but if `warn` is also true it logs the failing site once per session so
+   * authors can see what would have been fixed.
+   */
+  enabled: boolean;
+  /**
+   * Which contrast metric to enforce.
+   *
+   * `"apca"` (default) uses APCA Lc — perceptually uniform and
+   * polarity-aware, so equalizing produces labels that read with the same
+   * weight whether they sit on a dark or a light cell.
+   *
+   * `"wcag"` uses the WCAG 2.1 ratio formula. Kept for backwards
+   * compatibility; equalizing on WCAG ratio looks visually unbalanced
+   * across polarities.
+   */
+  metric: ContrastMetric;
+  /**
+   * WCAG-mode target. `"AA"` = 4.5:1 normal / 3:1 large; `"AAA"` = 7:1 / 4.5:1.
+   * A raw number sets an absolute minimum ratio (1–21) applied to all text
+   * regardless of size. Ignored when `metric === "apca"`.
+   */
+  wcagLevel: "AA" | "AAA" | number;
+  /**
+   * APCA-mode target |Lc|. `"auto"` (default) looks up the recommended
+   * minimum from APCA's font/weight table for each site (typical body text
+   * lands around Lc 75–90). A raw number applies a single |Lc| floor to
+   * every site. Ignored when `metric === "wcag"`.
+   */
+  apcaTarget: number | "auto";
+  /**
+   * How to fix low-contrast text. `auto-color` nudges the color toward an
+   * accessible shade preserving hue/saturation. `outline` / `shadow` are
+   * reserved API hooks — both currently degrade to `auto-color` since the
+   * SDF text pipeline doesn't render text effects yet. `none` leaves text
+   * untouched (and warns when `warn` is on).
+   */
+  mode: AccessibilityMode;
+  /** Whether to console.warn on contrast failures the system isn't fixing. */
+  warn: boolean;
+  /**
+   * When true, every *mark* label (geom-rendered, sitting on a data-driven
+   * fill) is normalized to *exactly* the target contrast — not just `>=`.
+   * Equalizing prevents cells with high contrast from visually outweighing
+   * neighbors. Hue and saturation are preserved; only lightness shifts.
+   *
+   * Chrome text (titles, axis, legend) skips this — those sit on the
+   * panel background and equalizing them just dims legible chrome.
+   */
+  equalize: boolean;
+  /**
+   * How strongly the auto-fixer pulls toward colors already in the theme.
+   * `0` keeps the original hue/sat untouched. `1` snaps to the nearest
+   * passing theme accent. Intermediate values blend in `blendSpace`,
+   * keeping the label feeling "of the same family" as the chart's palette.
+   *
+   * The pull is only applied when at least one accent independently meets
+   * the contrast target — biasing toward an unreadable accent would defeat
+   * the fix. When `equalize` is on, the L-channel is re-fit after the blend
+   * so the final contrast still lands at the target.
+   */
+  themeBias: number;
+  /**
+   * Optional explicit accent palette for the bias. When unset, the
+   * resolver derives accents from the active theme (text/title/legend
+   * colors plus a sample of the categorical palette).
+   */
+  accents?: readonly Color[];
+  /**
+   * Color space used for the theme-bias blend. Defaults to `"oklch"` —
+   * perceptually uniform with hue preserved along the blend.
+   */
+  blendSpace: BlendSpace$1;
+}
+declare const DEFAULT_ACCESSIBILITY: Accessibility;
+/**
+ * Stub for SDF text effects. Setting these on the theme today has no visual
+ * effect — the renderer will pick them up once outline/shadow are wired into
+ * the text pipeline. Kept on the public API so call sites and themes can
+ * declare intent now without a follow-up breaking change.
+ */
+interface TextEffects {
+  outline?: {
+    color: Color;
+    width: number;
+  };
+  shadow?: {
+    color: Color;
+    blur?: number;
+    dx?: number;
+    dy?: number;
+  };
+}
+interface ResolveTextColorOptions {
+  /** Font size in CSS pixels. */
+  fontSizePx: number;
+  /** Treat the text as bold (affects WCAG large-text and APCA weight lookup). */
+  bold?: boolean;
+  /**
+   * Short label identifying the draw site (e.g. `"axis-label"`,
+   * `"tile-label"`). Used to namespace dedupe keys for warnings.
+   */
+  site: string;
+  /**
+   * Whether this site sits on a *data-driven* background (mark fills,
+   * heatmap cells) versus chrome on the panel background. `equalize`
+   * normalization applies only to mark sites — chrome text always sits on
+   * the same panel background, so equalizing it would just lower legible
+   * titles/axis/legend text down toward the contrast floor for no gain.
+   * Default `false`.
+   */
+  markLabel?: boolean;
+  /**
+   * Override the engine-computed target. When set, the resolver uses this
+   * value instead of the font/level lookup. Used by geoms that need to
+   * coordinate a layer-wide equalize floor (e.g. tile pulls every label
+   * down to the worst cell's max-achievable contrast so the layer reads
+   * uniformly, instead of saturating each label at its own per-cell max).
+   */
+  targetOverride?: number;
+  /** @internal — APCA polarity, computed inside the resolver. */
+  _apcaReverse?: boolean;
+}
+/**
+ * Resolve the actual color that should be drawn for a piece of text given
+ * the requested foreground, the known background, and the chart's
+ * accessibility policy. Pure — does not draw anything.
+ */
+declare function resolveTextColor(fg: Color, bg: Color, theme: Theme, opts: ResolveTextColorOptions): Color;
+//#endregion
+//#region src/grammar/theme.d.ts
+interface ThemeText {
+  color: Color;
+  fontFamily: string;
+}
+interface ThemeTitle {
+  fontSize: number;
+  fontWeight: string;
+  color: Color;
+}
+interface ThemeSubtitle {
+  fontSize: number;
+  color: Color;
+}
+interface ThemeAxis {
+  color: Color;
+  gridColor: Color;
+  labelFontSize: number;
+  labelColor: Color;
+  titleFontSize: number;
+  titleColor: Color;
+}
+interface ThemeLegend {
+  fontSize: number;
+  labelColor: Color;
+  swatchGap: number;
+  entryGap: number;
+}
+interface ThemeMarks {
+  pointRadius: number;
+  pointStroke: Color | undefined;
+  pointStrokeWidth: number;
+  /**
+   * Default stroke width for line-based marks (`line`, `smooth`, `statRolling`,
+   * `area` outline, `aggregate` line geom). Geom-level `strokeWidth` options
+   * override this token per layer.
+   */
+  strokeWidth: number;
+  barCornerRadius: number;
+  fillAlpha: number;
+  /** Font size for value/total labels rendered alongside marks (bar, text). */
+  labelFontSize: number;
+  /** Default stroke width for `rule()` lines. */
+  ruleStrokeWidth: number;
+  /** Default label inset for `rule()` annotations. */
+  ruleLabelInset: number;
+  /** Default font size for inline annotations (rule, band labels). */
+  annotationFontSize: number;
+  /** Default fill alpha for `ribbon()`. */
+  ribbonFillAlpha: number;
+  /** Default fill alpha for `band()` highlight regions. */
+  bandFillAlpha: number;
+  /** Default size-channel pixel range. */
+  sizeRange: readonly [number, number];
+  /** Default alpha-channel range. */
+  alphaRange: readonly [number, number];
+}
+type ThemeDurationKey = "fast" | "base" | "slow";
+type ThemeEasingKey = "standard" | "emphasized" | "decelerate" | "linear";
+interface ThemeDurations {
+  fast: number;
+  base: number;
+  slow: number;
+}
+interface ThemeEasings {
+  standard: Easing;
+  emphasized: Easing;
+  decelerate: Easing;
+  linear: Easing;
+}
+interface ThemeMotionChannel {
+  duration: ThemeDurationKey;
+  easing: ThemeEasingKey;
+}
+interface ThemeMotionTooltip {
+  showDelay: number;
+  hideDelay: number;
+  fadeMs: number;
+  /**
+   * Hover-intent settle (ms). Rapid enter/leave/switch events are coalesced —
+   * the tooltip only commits a show/hide after the cursor holds a target this
+   * long. Prevents an overlay re-render per cell while sweeping across a dense
+   * mark grid or through gaps. 0 disables (commit immediately).
+   */
+  settleDelay: number;
+}
+interface ThemeMotion {
+  /** Master switch. False → snap, no scheduled motion. */
+  enabled: boolean;
+  duration: ThemeDurations;
+  easing: ThemeEasings;
+  /** Data update / scale change transitions. */
+  data: ThemeMotionChannel;
+  /** Axis tick / domain transitions. */
+  axis: ThemeMotionChannel;
+  tooltip: ThemeMotionTooltip;
+}
+interface ThemeInteractionEmphasis {
+  /** Master enable. `false` skips both halo and dim. */
+  enabled: boolean;
+  /** Multiplier on non-active rows' fill alpha. `1` = no dim. */
+  dim: number;
+  /** Halo stroke width in CSS px. `0` skips the halo. */
+  haloStrokeWidth: number;
+  /**
+   * Halo ring color. When omitted, geoms fall back to a high-contrast
+   * foreground (`theme.text.color`) so the focus ring reads against the
+   * marks rather than blending in with the datum's own color. Set a `Color`
+   * to pin the ring (e.g. a brand accent).
+   */
+  haloColor?: Color;
+  /**
+   * Duration (ms) of the GPU dim animation driven through the core's emphasis
+   * uniform (P5-T3). On a hover hit-change over a dim-participating geom the
+   * mount ramps the emphasis `t` 0→1 (ease-out cubic) over this window; on
+   * hover exit it ramps t→0. Only consumed by `hover` (selection dim stays a
+   * compile-time treatment). `<= 0` snaps. Default ~120ms.
+   */
+  durationMs?: number;
+}
+/**
+ * Semantic row-tint tokens for tooltip rows that use the
+ * `accent: "positive" | "negative" | "neutral"` shorthand. `neutral` is
+ * intentionally omitted — it means "no override, use the default row text
+ * color from the underlying tooltip style." Consumers can also pass a raw
+ * `Color` per row to bypass these tokens entirely.
+ */
+interface ThemeTooltipAccents {
+  positive: Color;
+  negative: Color;
+}
+interface ThemeInteractions {
+  /** Visual treatment applied while a row is hovered. */
+  hover: ThemeInteractionEmphasis;
+  /** Visual treatment applied while rows are selected. */
+  selection: ThemeInteractionEmphasis;
+  /**
+   * Grace window (ms) applied when hover transitions to "nothing" before
+   * propagating the null state to dim/halo and crosshair. If a new hit lands
+   * within this window, the swap goes directly from prev → next without
+   * passing through null — eliminates the un-dim → re-dim flash when the
+   * cursor crosses between adjacent or near-adjacent geoms. `0` disables.
+   */
+  hoverSwapGraceMs: number;
+  /** Semantic row colors for the tooltip `accent` shorthand. */
+  tooltipAccents: ThemeTooltipAccents;
+}
+interface ThemePalettes {
+  categorical: CategoricalPalette;
+  continuous: ContinuousPalette;
+  diverging: ContinuousPalette;
+}
+/**
+ * Semantic accent palette consumed by chart-level marks that carry meaning
+ * (reference regions, threshold rules, callouts, tooltip rows). Geoms that
+ * accept an accent key (`fill: "positive"`, `stroke: "warn"`) resolve through
+ * this block; literal `Color` values still bypass it.
+ *
+ * Naming exception to the "name geoms by what they are, not what they do"
+ * principle: these tokens exist explicitly to carry semantics. The names
+ * follow conventional status vocabulary so any reader can predict the role.
+ *
+ * `neutral` is intentionally omitted — it means "no override, use the
+ * surrounding default" (mark fill, axis label color, …) so consumers can fall
+ * back without spelling out a token.
+ *
+ * Distinct from {@link ThemeTooltipAccents} (under `interactions.tooltipAccents`)
+ * which is sized for tooltip-text contrast and may differ in luminance.
+ */
+interface ThemeAccents {
+  positive: Color;
+  negative: Color;
+  warn: Color;
+  info: Color;
+}
+type ThemeAccentKey = keyof ThemeAccents;
+interface Theme {
+  background: Color;
+  text: ThemeText;
+  title: ThemeTitle;
+  subtitle: ThemeSubtitle;
+  axis: ThemeAxis;
+  legend: ThemeLegend;
+  marks: ThemeMarks;
+  palettes: ThemePalettes;
+  /** Semantic accent palette for chart-level marks (reference regions, threshold rules, callouts). */
+  accents: ThemeAccents;
+  /**
+   * Text-readability policy. Applied at every draw site where the chart
+   * knows the local background color (titles/axis/legend versus the panel
+   * background; tile labels versus their cell color).
+   */
+  accessibility: Accessibility;
+  /**
+   * Default text effects (outline / drop shadow). API stub today — the SDF
+   * text path doesn't render these yet. See
+   * dev_docs/2026-04-30-text-accessibility.md.
+   */
+  textEffects?: TextEffects;
+  /**
+   * Color space used to interpolate continuous palettes (`viridis`, etc.)
+   * when sampled by color scales and color bars. `oklch` is the default —
+   * perceptually uniform with hue preserved along the gradient. Override
+   * per chart (`theme({ paletteBlendSpace: "srgb" })`) or per call (the
+   * `blendSpace` option on color-scale and `colorBar` specs).
+   */
+  paletteBlendSpace: BlendSpace$1;
+  /**
+   * Motion tokens — durations, easings, and per-channel defaults consumed by
+   * interactions (hover, tooltip), data transitions, and axis updates. See
+   * {@link defaultMotion} and {@link applyReducedMotion}.
+   */
+  motion: ThemeMotion;
+  /**
+   * Hover / selection emphasis tokens. Geoms read these to render the active
+   * row's halo and optionally dim the rest. See {@link defaultInteractions}.
+   */
+  interactions: ThemeInteractions;
+}
+declare const themeDefault: Theme;
+/**
+ * Light/minimal theme — white plot background, soft gray gridlines, dark
+ * labels. Pairs well with the `category10` palette and is a good default for
+ * scatter / smooth charts that should read like a ggplot2 / R reference.
+ */
+declare const themeMinimalGrid: Theme;
+type DeepPartial<T> = { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K] };
+/**
+ * Compose a theme by deep-merging overrides into a base theme. Accepts a
+ * shallow override on any nested group (e.g. `{ marks: { strokeWidth: 2 } }`).
+ */
+declare function theme(overrides: DeepPartial<Theme>, base?: Theme): Theme;
+//#endregion
+//#region src/grammar/attach-presets.d.ts
+/** Where the chip strip sits inside its mount element. */
+type AttachRangePresetsPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+interface AttachRangePresetsUi {
+  /** Element to append the chip strip into (typically the chart's stage). */
+  mount: HTMLElement;
+  /** Corner placement inside `mount`. Defaults to `"top-left"`. */
+  position?: AttachRangePresetsPosition;
+  /** Inset (px) from the chosen corner. Defaults to `12`. */
+  inset?: number;
+}
+interface AttachRangePresetsOptions {
+  axis: "x" | "y";
+  /**
+   * Presets to expose. A `TimePresetKey` string is expanded to `timePreset(key)`;
+   * pass a full `RangePreset` for custom presets (label override, linear/log
+   * presets, etc.).
+   */
+  presets: readonly (TimePresetKey | RangePreset)[];
+  dataDomain?: RangePresetDataDomain;
+  now?: () => number;
+  /** Omit to skip DOM construction — returns the same controller, headless. */
+  ui?: AttachRangePresetsUi;
+}
+interface AttachedRangePresets {
+  setActive(key: string | null): void;
+  getActive(): string | null;
+  subscribe(fn: RangePresetsSubscriber): () => void;
+  dispose(): void;
+}
+declare function attachRangePresets(viewport: DataViewport<any, any>, theme: Theme, opts: AttachRangePresetsOptions): AttachedRangePresets;
+//#endregion
+//#region src/grammar/coord.d.ts
+interface Point {
+  x: number;
+  y: number;
+}
+/**
+ * Inputs to `Coord.renderAxes`. The pipeline owns scale construction and
+ * layout; the coord owns axis dispatch (Cartesian → bottom + left; polar →
+ * angular ring + radial spokes).
+ */
+interface CoordAxesArgs {
+  axisLayer: Layer;
+  scales: ScaleBundle;
+  /** Inner plot frame — coords project relative to this. */
+  plotFrame: _$insomni.Frame;
+  /** True when the chart actually has a column on this channel. Skipped axes are not drawn. */
+  hasX: boolean;
+  hasY: boolean;
+  xAxisOptions: AxisOptions<unknown>;
+  yAxisOptions: AxisOptions<unknown>;
+  atlas: GlyphAtlas | undefined;
+}
+/**
+ * Inputs to `Coord.handlePan`. The mount / interactions layer passes a pointer
+ * delta in plot-frame pixels plus the active plot frame and a viewport handle
+ * the coord can use to mutate scale state. Cartesian delegates the whole
+ * thing to `viewport.panBy(dx, dy)`; polar decomposes into tangential
+ * (rotate `startAngle`) and radial (translate radius domain via the viewport).
+ */
+interface CoordPanArgs {
+  dx: number;
+  dy: number;
+  /** Plot frame in absolute layer-pixel space (x, y are screen-space origin). */
+  plotFrame: _$insomni.Frame;
+  /** Viewport handle for scale-domain mutations. */
+  viewport: CoordViewportHandle;
+}
+interface CoordZoomArgs {
+  /**
+   * Multiplicative zoom factor — `> 1` zooms in, `< 1` zooms out. May be a
+   * scalar (both axes) or a `{ x?, y? }` per-axis form (matches
+   * `viewport.zoomAt` and the masking that `bindDataViewport` performs).
+   */
+  factor: number | {
+    x?: number;
+    y?: number;
+  };
+  /** Cursor position in absolute layer-pixel space (matches `viewport.zoomAt`). */
+  cx: number;
+  cy: number;
+  plotFrame: _$insomni.Frame;
+  viewport: CoordViewportHandle;
+}
+/**
+ * Minimal facade over `DataViewport` so the coord can mutate scale state
+ * without depending on the full viewport surface. The two methods polar
+ * uses (`panBy`, `zoomAt`) match `DataViewport` semantics 1:1; Cartesian's
+ * implementation forwards through them so behavior is byte-identical to the
+ * pre-`handlePan` path.
+ */
+interface CoordViewportHandle {
+  panBy(dxPx: number, dyPx: number): void;
+  zoomAt(anchorSx: number, anchorSy: number, factor: number | {
+    x?: number;
+    y?: number;
+  }): void;
+}
+/**
+ * A coordinate system. Polar / cartesian today; future room for log-polar /
+ * geographic projections behind the same interface.
+ */
+interface Coord {
+  readonly kind: "cartesian" | "polar";
+  /**
+   * Bind the coord to a specific plot frame for the upcoming render.
+   * Polar's `project` / `segment` / `renderAxes` need the plot-frame
+   * dimensions and centre to compute (cx, cy) and the default outerRadius.
+   * Called by the pipeline once per panel (faceted) or once per chart
+   * (unfaceted) before any `project` / `renderAxes` call. Cartesian no-ops.
+   */
+  bindFrame(plotFrame: _$insomni.Frame): void;
+  /**
+   * Map a single point from plot-frame pixel space (0..plotFrame.width on x,
+   * 0..plotFrame.height on y — i.e. the raw output of `xScale.fn` / `yScale.fn`)
+   * to layer-pixel space (still relative to the plot frame's origin —
+   * `plot.topLeft` offsets are applied later by each geom).
+   *
+   * Cartesian: identity. Polar: (θ, r) → (cx + r·cosθ, cy + r·sinθ).
+   */
+  project(p: Point): Point;
+  /**
+   * Tessellate a polyline segment between two points in plot-frame pixel
+   * space. Returns the projected pixel points (including both endpoints).
+   * Cartesian returns `[project(p1), project(p2)]`; polar returns ~N points
+   * along the arc.
+   */
+  segment(p1: Point, p2: Point): Point[];
+  /**
+   * Render axes into `args.axisLayer`. Cartesian draws bottom (x) + left (y);
+   * polar draws an angular ring (spokes) + radial concentric circles.
+   */
+  renderAxes(args: CoordAxesArgs): void;
+  /**
+   * Inverse of `project`, for hit-testing / tooltips. Cartesian is the
+   * identity within the plot frame. Polar inverts (θ, r) and returns `null`
+   * when the projected point is outside `[innerRadius, outerRadius]`.
+   */
+  unproject(p: Point): Point | null;
+  /**
+   * Translate a pointer pan delta into scale-domain mutations.
+   * Cartesian forwards to `viewport.panBy(dx, dy)` — byte-identical to the
+   * pre-coord path. Polar decomposes the delta relative to the plot centre
+   * into tangential (rotate `startAngle`) and radial (translate the radius
+   * scale via `viewport.panBy(0, radial_dy)`) components.
+   */
+  handlePan(args: CoordPanArgs): void;
+  /**
+   * Translate a zoom factor + anchor into scale-domain mutations.
+   * Cartesian forwards to `viewport.zoomAt(cx, cy, factor)`. Polar scales the
+   * radius domain around the cursor's data-space radius; angle scale
+   * unchanged.
+   */
+  handleZoom(args: CoordZoomArgs): void;
+}
+/**
+ * Default coord — identity projection, current axis behavior. Plot's existing
+ * pipeline behaves exactly as it did before the `Coord` interface was added
+ * when this is in use.
+ */
+declare function coordCartesian(): Coord;
+interface CoordPolarOptions {
+  /** Angle (radians) where the angular axis starts. Default `-π/2` (top). */
+  startAngle?: number;
+  /** Angle where the angular axis ends. Default `startAngle + 2π` (full circle). */
+  endAngle?: number;
+  /**
+   * Convenience for non-full-circle layouts: the gap (in radians) between
+   * `startAngle` and `endAngle`. `openAngle: 0` ↔ full circle;
+   * `openAngle: π/4` ↔ fan with a 45° gap at the start. Ignored when
+   * `endAngle` is provided.
+   */
+  openAngle?: number;
+  /** `1` (default, CCW) or `-1` (CW). */
+  direction?: 1 | -1;
+  /** Inner radius in pixels. Default `0`. */
+  innerRadius?: number;
+  /**
+   * Outer radius in pixels. Default `min(plotFrame.width, plotFrame.height) / 2`
+   * — resolved lazily on `bindFrame`.
+   */
+  outerRadius?: number;
+  /** Which channel maps to θ. Default `'y'` (gheatmap/circular-tree convention). */
+  angleChannel?: "x" | "y";
+  /** Angular tessellation step (radians) for `segment` and circular axes. Default ~1°. */
+  quality?: number;
+}
+/**
+ * Polar projection. See {@link CoordPolarOptions}.
+ *
+ * Each call returns a fresh stateful coord so the same `coordPolar({...})`
+ * expression can be reused safely. `bindFrame` mutates the centre and the
+ * default `outerRadius`.
+ */
+declare function coordPolar(opts?: CoordPolarOptions): Coord;
+/**
+ * Convenience polar coord: full circle, root at centre. Equivalent to
+ * `coordPolar({ openAngle: 0, innerRadius: 0 })`.
+ */
+declare function coordRadial(opts?: Omit<CoordPolarOptions, "openAngle" | "innerRadius">): Coord;
+//#endregion
+//#region src/grammar/geoms/emphasis.d.ts
+/**
+ * A geom's hover-dim emphasis-key resolver, captured at compile time so the
+ * mount can map an active {@link HoveredHit} to the namespaced key it tagged
+ * its focused instance(s) with — WITHOUT recompiling. `geomKind` + `data`
+ * identity match the resolver to the hit (the same keys that route a hit to its
+ * geom, mirroring {@link GeomHoverDecorator}). `resolve` returns the focused
+ * key, or `null` when this hit focuses nothing in the geom (the mount then
+ * leaves emphasis settled). The geom computes the SAME ordinal it used to tag.
+ */
+interface EmphasisResolver {
+  readonly geomKind: GeomKind;
+  readonly data: readonly unknown[];
+  resolve(hit: HoveredHit): number | null;
+}
+//#endregion
+//#region src/grammar/aes.d.ts
+type ColumnKeys<T, V> = { [K in keyof T]-?: T[K] extends V ? K : never }[keyof T];
+type Accessor<T, V> = (datum: T, index: number) => V;
+type Aes<T, V> = ColumnKeys<T, V> | Accessor<T, V> | V;
+interface ResolvedAes<T, V> {
+  readonly kind: "column" | "accessor" | "constant";
+  readonly column?: keyof T & string;
+  readonly fn: Accessor<T, V>;
+}
+/**
+ * Best-effort guess of a channel's data type. Used to pick a default scale
+ * type when no override is supplied. Null / undefined values are skipped
+ * (see "Null / undefined policy" above).
+ */
+type ChannelDataType = "number" | "date" | "string" | "boolean" | "unknown";
+//#endregion
+//#region src/grammar/scales.d.ts
+type Channel = "x" | "y" | "color" | "size" | "shape" | "alpha" | "borderStyle" | "overlayGlyph";
+type PositionScaleType = "linear" | "log" | "sqrt" | "time" | "band";
+type ColorScaleType = "categorical" | "continuous" | "diverging";
+interface BasePositionScaleOptions {
+  range?: NumericRange;
+  nice?: boolean;
+  padding?: number;
+}
+/**
+ * `"nice"` is sugar for the existing `nice: true` flag — set as the domain
+ * shortcut so consumers don't need a second toggle when the only reason to
+ * touch `domain` was to pad it to round values. The data extent still
+ * derives the underlying numbers; `"nice"` just toggles the rounding.
+ */
+type NumericDomainShortcut = "nice";
+interface NumericPositionScaleOptions extends BasePositionScaleOptions {
+  type?: "linear" | "log" | "sqrt";
+  domain?: readonly [number, number] | NumericDomainShortcut;
+}
+interface TimePositionScaleOptions extends BasePositionScaleOptions {
+  type?: "time";
+  domain?: readonly [Date, Date];
+}
+interface BandPositionScaleOptions extends BasePositionScaleOptions {
+  type?: "band";
+  domain?: readonly string[];
+}
+type PositionScaleOptions = NumericPositionScaleOptions | TimePositionScaleOptions | BandPositionScaleOptions;
+interface CategoricalColorScaleOptions<T> {
+  type?: "categorical";
+  domain?: readonly T[];
+  palette?: CategoricalPalette;
+}
+/**
+ * Color-scale domain shortcuts.
+ *
+ * - `"nice"`: alias for the existing `nice: true` flag on continuous color
+ *   scales — pad the data extent to round values.
+ * - `"quantile"`: bucket the data into N quantile bins (default 5). The
+ *   returned scale's `type` becomes `"categorical"` with bucket-label
+ *   domain entries (`"Q1".."QN"`), and the palette is sampled at N evenly
+ *   spaced stops along the chart's continuous palette so the color
+ *   gradient reads as ordinal magnitude rather than nominal category.
+ */
+type ColorDomainShortcut = "nice" | "quantile";
+interface ContinuousColorScaleOptions {
+  type: "continuous" | "diverging";
+  domain?: readonly [number, number] | ColorDomainShortcut;
+  palette?: ContinuousPalette;
+  /**
+   * Extend the inferred domain outward to "nice" round values (e.g. data
+   * extent `[-2.8, 1.9]` → `[-3, 2]`). Same algorithm position scales use
+   * via `nice: true`. Ignored when `domain` is set explicitly to a tuple.
+   * Equivalent to `domain: "nice"` — keep one form per chart for clarity.
+   */
+  nice?: boolean;
+  /**
+   * Number of quantile buckets to use when `domain: "quantile"`. Default 5
+   * (quintiles). Ignored otherwise.
+   */
+  quantiles?: number;
+  /**
+   * Override the color space used to interpolate the palette stops.
+   * Falls back to `theme.paletteBlendSpace` (default `"oklch"`).
+   */
+  blendSpace?: _$insomni.BlendSpace;
+}
+type ColorScaleOptions<T> = CategoricalColorScaleOptions<T> | ContinuousColorScaleOptions;
+interface SizeScaleOptions {
+  type?: "linear" | "sqrt";
+  domain?: readonly [number, number];
+  range?: readonly [number, number];
+}
+interface AlphaScaleOptions {
+  domain?: readonly [number, number];
+  range?: readonly [number, number];
+}
+interface ShapeScaleOptions {
+  /** Explicit category order (default: order of first appearance). */
+  domain?: readonly unknown[];
+  /** Override the shape palette. Default: `POINT_SHAPE_PALETTE` from `marks`. */
+  palette?: readonly PointShapeKind[];
+}
+interface BorderStyleScaleOptions {
+  /** Explicit category order (default: order of first appearance). */
+  domain?: readonly unknown[];
+  /** Override the border-style palette. Default: `DEFAULT_BORDER_STYLE_PALETTE`. */
+  palette?: readonly PointBorderStyle[];
+}
+interface OverlayGlyphScaleOptions {
+  /** Explicit category order (default: order of first appearance). */
+  domain?: readonly unknown[];
+  /**
+   * Override the overlay palette. Default: a small subset of
+   * `POINT_SHAPE_PALETTE` excluding `circle` so the overlay is visually
+   * distinct from the typical base shape. Use `null` entries to suppress an
+   * overlay for that domain value.
+   */
+  palette?: readonly (PointShapeKind | null)[];
+}
+/** A scale callable: any value → number (or color, for color channels). */
+type ScaleFn<In, Out> = (value: In) => Out;
+interface PositionScale {
+  readonly kind: "position";
+  readonly type: PositionScaleType;
+  readonly dataType: ChannelDataType;
+  /** Pixel-space transform within the plot frame. */
+  readonly fn: ScaleFn<unknown, number>;
+  /** Underlying scale for axis builders. */
+  readonly axisScale: ContinuousScale | TimeScale | BandScale<string>;
+}
+interface ColorScale {
+  readonly kind: "color";
+  readonly dataType: ChannelDataType;
+  readonly type: ColorScaleType;
+  readonly fn: ScaleFn<unknown, Color>;
+  readonly domain: readonly unknown[];
+  /** Original palette — present for continuous/diverging scales (used by the color-bar legend). */
+  readonly palette?: ContinuousPalette | CategoricalPalette;
+}
+interface SizeScale {
+  readonly kind: "size";
+  readonly fn: ScaleFn<unknown, number>;
+  readonly domain: readonly [number, number];
+  readonly range: readonly [number, number];
+}
+interface AlphaScale {
+  readonly kind: "alpha";
+  readonly fn: ScaleFn<unknown, number>;
+  readonly domain: readonly [number, number];
+  readonly range: readonly [number, number];
+}
+interface ShapeScale {
+  readonly kind: "shape";
+  readonly fn: ScaleFn<unknown, PointShapeKind>;
+  readonly domain: readonly unknown[];
+  readonly palette: readonly PointShapeKind[];
+}
+interface BorderStyleScale {
+  readonly kind: "borderStyle";
+  readonly fn: ScaleFn<unknown, PointBorderStyle>;
+  readonly domain: readonly unknown[];
+  readonly palette: readonly PointBorderStyle[];
+}
+interface OverlayGlyphScale {
+  readonly kind: "overlayGlyph";
+  readonly fn: ScaleFn<unknown, PointShapeKind | null>;
+  readonly domain: readonly unknown[];
+  readonly palette: readonly (PointShapeKind | null)[];
+}
+declare const DEFAULT_BORDER_STYLE_PALETTE: readonly PointBorderStyle[];
+/**
+ * Default overlay palette. First slot is `null` so the most-common category
+ * gets no overlay — overlays are typically a minority styling for flagged /
+ * exceptional rows. The remaining slots are visually distinct glyphs.
+ */
+declare const DEFAULT_OVERLAY_GLYPH_PALETTE: readonly (PointShapeKind | null)[];
+//#endregion
+//#region src/grammar/geoms/types.d.ts
+type GeomKind = "point" | "line" | "area" | "bar" | "text" | "rule" | "band" | "boxplot" | "violin" | "histogram" | "ridgeline" | "rug" | "smooth" | "rolling" | "tile" | "interval";
+/**
+ * Channel mappings as declared by the user. Stored at this width on `Geom<T>`
+ * so the chart can iterate channels generically. Geom factories accept their
+ * narrower per-geom channel types (PointChannels, LineChannels, ...) as the
+ * public surface and cast into this for storage.
+ */
+interface ChannelSpec<_T> {
+  x?: unknown;
+  y?: unknown;
+  color?: unknown;
+  size?: unknown;
+  shape?: unknown;
+  alpha?: unknown;
+  borderStyle?: unknown;
+  overlayGlyph?: unknown;
+}
+/**
+ * Per-geom hints for position-scale construction. Geoms that have a
+ * conventional baseline (bar, area) request that their value axis include 0
+ * — or, for `position: 'fill'`, set an explicit `[0, 1]` domain. Hints are
+ * only applied to numeric (linear/log/sqrt) scales; band/time scales ignore
+ * them. An explicit `.scale(channel, { domain })` override always wins.
+ */
+interface PositionScaleHint {
+  /** Force this exact domain (overrides include flags). */
+  domain?: readonly [number, number];
+  /** Extend inferred domain to include 0. */
+  includeZero?: boolean;
+  /** Extend inferred domain to include 1. */
+  includeOne?: boolean;
+  /**
+   * Extend the inferred domain to include this range. Unlike `domain`, this
+   * is unioned with the data-derived extent (and with other layers' extends)
+   * rather than replacing it. Use for geoms whose visual footprint extends
+   * past the raw data — e.g. a KDE-based violin whose smoothed tails reach
+   * outside `[dataMin, dataMax]`.
+   */
+  extend?: readonly [number, number];
+}
+interface ScaleHints {
+  x?: PositionScaleHint;
+  y?: PositionScaleHint;
+}
+/**
+ * Pixel reservations on the plot frame for a geom whose visual extent
+ * exceeds its data footprint. The chart shrinks the position-scale range
+ * by these amounts so axis ticks track the compressed layout — used by
+ * ridgeline rows that rise above their baseline. Reservations from
+ * multiple layers are merged by max (the largest demand wins).
+ */
+interface RangeHints {
+  top?: number;
+  bottom?: number;
+  left?: number;
+  right?: number;
+}
+interface PrepareRangeContext<T> {
+  data: readonly T[];
+  plot: Frame;
+  scaleOptions: {
+    x?: PositionScaleOptions;
+    y?: PositionScaleOptions;
+  };
+  theme: Theme;
+  atlas: GlyphAtlas | undefined;
+}
+interface ScaleBundle {
+  x: PositionScale;
+  y: PositionScale;
+  color?: ColorScale;
+  size?: SizeScale;
+  alpha?: AlphaScale;
+  shape?: ShapeScale;
+  borderStyle?: BorderStyleScale;
+  overlayGlyph?: OverlayGlyphScale;
+}
+/**
+ * Per-rendered-element channel snapshot used for animated transitions.
+ * For simple geoms this usually matches the source datum index; for stacked /
+ * grouped geoms it can be one entry per visible segment. NaN marks filtered /
+ * hidden entries. Each geom owns the index convention used by its compile path.
+ */
+interface GeomFrame {
+  count: number;
+  x: Float32Array;
+  y: Float32Array;
+  rgba: Float32Array;
+  a: Float32Array;
+  r?: Float32Array;
+  ids?: readonly string[];
+}
+/** Injected into CompileContext during an active data/scale transition. */
+interface ActiveTransition {
+  /** Progress 0 → 1. */
+  t: number;
+  /** From-snapshot for this geom. Indexed by datum i. */
+  from: GeomFrame;
+  /** Resolve a stable match index in `from` for the given key. */
+  matchIndex(key: string, fallbackIndex?: number): number | undefined;
+}
+interface CompileContext<T> {
+  data: readonly T[];
+  scales: ScaleBundle;
+  plot: Frame;
+  theme: Theme;
+  atlas: GlyphAtlas | undefined;
+  /**
+   * Coordinate system in effect for this chart. Geoms can call
+   * `ctx.coord.project(p)` / `ctx.coord.segment(p1, p2)` to remap plot-frame
+   * pixel space into layer-pixel space — under `coordCartesian()` (the
+   * default) both are the identity, so existing geoms are unaffected. Phase 3
+   * adds `coordPolar()` / `coordRadial()` and per-geom polar projection.
+   *
+   * Optional during Phase 1: only the pipeline supplies it today, and geoms
+   * have not been migrated to project through it yet. Treat absence as
+   * `coordCartesian()` if you read it in a geom. Will become required when
+   * Phase 3 lands and per-geom polar projection ships.
+   */
+  coord?: Coord;
+  /**
+   * Currently hovered hit, or `null` if nothing is hovered. Geoms compare
+   * `hovered.data === ctx.data && hovered.geomKind === this.kind` to detect
+   * "their" hit and can use `hovered.dataIndex` to render a highlight (halo,
+   * elevated alpha/stroke, etc.). Provided by the mount; `undefined` when
+   * compiling outside a mount context (e.g. SSR / SVG export).
+   */
+  hovered?: HoveredHit | null;
+  /**
+   * Currently selected hits (multi-select). Empty array = nothing selected;
+   * `undefined` = selection is disabled (no visual treatment). Geoms render
+   * stroke rings on matching rows and may dim non-selected rows when the
+   * array is non-empty.
+   */
+  selected?: readonly HoveredHit[];
+  /** Set of series keys currently hidden via legend toggle. */
+  hidden?: ReadonlySet<string>;
+  /** Optional stable key used to match rows across data refreshes for transitions. */
+  transitionKey?: (datum: T, index: number) => string;
+  /**
+   * Active data/scale transition context. Present only during an animated
+   * transition; geoms use it to lerp channels from the previous frame toward
+   * the current compiled values.
+   */
+  activeTransition?: ActiveTransition;
+  /**
+   * Disjoint emphasis-key band base for this geom (P5-T3). The pipeline assigns
+   * `geomEmphasisBase(geomIndex)`; dim-participating geoms tag each mark
+   * instance `emphasisKey: emphasisKeyFor(base, ordinal)` so the core's GPU dim
+   * uniform can fade non-focused instances WITHOUT a marks recompile. `undefined`
+   * outside a mount (SSR / SVG export) → geoms skip tagging (no GPU emphasis).
+   * See {@link import("./emphasis.ts")}.
+   */
+  emphasisBase?: number;
+}
+/**
+ * The active hover state surfaced to compile contexts and exposed on
+ * `MountedPlot.hovered`. Coordinates are absolute element-CSS pixels
+ * (matching `CompiledHitTest.positions`).
+ */
+interface HoveredHit {
+  geomKind: GeomKind;
+  dataIndex: number;
+  /** Optional segment key for multi-series geoms (stacked/dodged bars, stacked areas). */
+  seriesKey?: string;
+  /**
+   * Reference to the data array used to compile the originating geom — used
+   * for identity comparison (`hovered.data === ctx.data`) so multi-layer
+   * charts can route the hit to the right geom.
+   */
+  data: readonly unknown[];
+  x: number;
+  y: number;
+}
+/**
+ * Resolved aesthetics for each channel of a geom — used by interaction layers
+ * (tooltips, legends-on-hover) to read the original column name and pull the
+ * raw value back out for a given datum.
+ */
+interface ResolvedChannelMap<T> {
+  x?: ResolvedAes<T, unknown>;
+  y?: ResolvedAes<T, unknown>;
+  color?: ResolvedAes<T, unknown>;
+  size?: ResolvedAes<T, unknown>;
+  shape?: ResolvedAes<T, unknown>;
+  alpha?: ResolvedAes<T, unknown>;
+}
+/**
+ * Hit-test points emitted by a geom for hover/click. Coordinates are absolute
+ * element-CSS pixels (the chart's plot frame offset is already baked in), so
+ * the consumer can hand them to a `space: "ui"` PointCloudNode without
+ * adjustment. `dataIndex[i]` maps hit `i` back to the original `data` array
+ * (after filtering NaN/null values). `seriesKey[i]` further distinguishes
+ * segments that share a source row.
+ */
+interface CompiledHitTest<T> {
+  geomKind: GeomKind;
+  label?: string;
+  positions: Float32Array;
+  dataIndex: Int32Array;
+  seriesKey?: readonly (string | undefined)[];
+  pickRadius: number;
+  /**
+   * Optional per-hit bounding rect in absolute element-CSS pixels. When
+   * present, the hit-layer prefers rect containment over nearest-point
+   * picking (`positions` + `pickRadius`), giving "whole shape" hover for
+   * shape-based geoms (bar, histogram, ridgeline rows, tile cells, ...).
+   * Layout: `[x, y, w, h]` per `dataIndex` entry. `positions` is still
+   * required as a fallback (used to anchor tooltips, brushes, etc.).
+   */
+  rects?: Float32Array;
+  /**
+   * Distance metric for nearest-point queries. Default `"xy"` (Euclidean).
+   * `"x"` makes the picker resolve nearest-by-x only — used by `line()` /
+   * `area()` when `nearestX: true` so the user can hover anywhere along the
+   * curve and the active vertex follows the cursor's x.
+   */
+  pickAxis?: "x" | "y" | "xy";
+  channels: ResolvedChannelMap<T>;
+  data: readonly T[];
+}
+/**
+ * A geom's hover-focus decoration, captured at compile time so the mount can
+ * draw it on hover **without recompiling the pipeline**. The mount calls
+ * {@link decorate} into the live overlay layer (which composites above the baked
+ * marks), so local focus treatment — a contrast halo, bringing the hovered
+ * element to the front — costs only a cheap overlay repaint rather than a full
+ * marks recompute. The complementary *global* dim-others treatment (fading every
+ * other element) rides the core's GPU emphasis uniform (see {@link
+ * EmphasisResolver}), so a geom can provide both: the decorator draws the focus
+ * halo (left at emphasis key 0 = exempt, full-strength) while the uniform dims
+ * the rest. Geoms with no local focus shape simply omit this.
+ *
+ * `geomKind` + `data` identity let the mount match the decorator to the active
+ * `HoveredHit` (the same keys used to route a hit to its geom).
+ */
+interface GeomHoverDecorator {
+  readonly geomKind: GeomKind;
+  readonly data: readonly unknown[];
+  /** Draw the focus decoration for `hit` into `layer` (the overlay layer). */
+  decorate(hit: HoveredHit, layer: Layer): void;
+}
+interface Geom<T> {
+  readonly kind: GeomKind;
+  readonly channels: ChannelSpec<T>;
+  /** Used by the auto-legend to label the layer. Falls back to channel name. */
+  readonly label?: string;
+  /** Optional position-scale hints (e.g. anchor value axis at 0 for bars). */
+  readonly scaleHints?: ScaleHints;
+  /**
+   * When true, the geom renders into the hud layer (above marks, no clip rect)
+   * instead of the marks layer. Used by geoms whose visual extent intentionally
+   * exceeds the plot frame — e.g. phylo tip labels — and that should not be
+   * clipped at the frame edge.
+   */
+  readonly overlay?: boolean;
+  /**
+   * Optional data-derived scale hints. Called once before scales are built,
+   * so geoms whose visual extent depends on the data (e.g. KDE-smoothed
+   * violins) can extend the position-scale domain accordingly. Returned
+   * hints are merged with `scaleHints` and any hints contributed by other
+   * layers. An explicit `.scale(channel, { domain })` override always wins.
+   */
+  prepareDomain?(data: readonly T[]): ScaleHints | undefined;
+  /**
+   * Optional layout-time hook that runs after layout but before scale
+   * construction. Geoms whose visual extent exceeds their data footprint
+   * — e.g. a ridgeline ridge that rises above its baseline by `overlap ×
+   * cellSize` — use this to reserve pixel margins on the plot frame, so
+   * the position scale (and its axis ticks) shrink to fit.
+   */
+  prepareRange?(ctx: PrepareRangeContext<T>): RangeHints | undefined;
+  /**
+   * Optional override for the auto-legend's per-series swatch. Geoms that
+   * draw filled regions (bar/area/tile) or strokes (line) supply their own;
+   * the pipeline falls back to a point swatch when omitted.
+   */
+  legendSwatch?(color: Color, theme: Theme): SwatchSpec;
+  compile(ctx: CompileContext<T>): readonly MarkBuilder[];
+  /**
+   * Optional hit-test contribution for interactions. Implemented per geom that
+   * wants to support hover/click selection (`point` in v1; bar/line/area in
+   * later phases). Return `null` to opt out for a particular compile pass
+   * (e.g. when the geom has no points after filtering).
+   */
+  compileHitTest?(ctx: CompileContext<T>): CompiledHitTest<T> | null;
+  /**
+   * Optional hover-focus decorator. Implemented by geoms whose focus treatment
+   * is *local* (point: contrast halo + bring-to-front) so it can ride the
+   * mount's cheap overlay path instead of a marks recompute. Called once per
+   * full compile with the same `ctx`; returns `null` to opt out (e.g. empty
+   * data). See {@link GeomHoverDecorator}.
+   */
+  hoverDecoration?(ctx: CompileContext<T>): GeomHoverDecorator | null;
+  /**
+   * Emphasis-key resolver for geoms whose hover treatment is *global* (dim the
+   * others via the core's GPU emphasis uniform: bar/line/violin/...). Captured
+   * once per full compile with the same `ctx` (so it sees the same `emphasisBase`
+   * + scales the tagging used); the mount maps an active {@link HoveredHit} to the
+   * namespaced key the geom tagged its focused instance(s) with — without
+   * recompiling. Returns `null` to opt out (e.g. empty data, or `emphasisBase`
+   * absent). Mutually complementary with {@link hoverDecoration} (local focus).
+   * See {@link import("./emphasis.ts").EmphasisResolver}.
+   */
+  emphasisResolution?(ctx: CompileContext<T>): EmphasisResolver | null;
+  /**
+   * Capture a per-datum channel snapshot for use as a transition "from" frame.
+   * Called after `compile` on each stable (non-animating) frame. Returns `null`
+   * if the geom has no meaningful frame to capture (e.g. empty data).
+   */
+  captureFrame?(ctx: CompileContext<T>): GeomFrame | null;
+}
+//#endregion
+//#region src/grammar/interactions/series-readout.d.ts
+interface SeriesReadoutRow {
+  /** Series name (color-channel value) or layer label. */
+  label: string;
+  /** Formatted display value (raw y at the snapped x). */
+  value: string;
+  /** Series swatch color, when the layer has a color channel. */
+  color?: Color;
+  /** True for the row whose snapped position is closest to the cursor. */
+  active: boolean;
+}
+interface SeriesReadoutSnapshot {
+  /** Formatted snapped x (from the closest layer). */
+  x: string;
+  /** Raw snapped x value (column-typed). Useful for custom formatting. */
+  xValue: unknown;
+  /** One row per series across all layers, in original layer + series order. */
+  rows: readonly SeriesReadoutRow[];
+}
+type SeriesReadoutFormat = {
+  /** Format the snapped x for the panel title. Default: `defaultFormat`. */x?: (value: unknown) => string; /** Format each per-series y value. Default: `defaultFormat`. */
+  y?: (value: unknown) => string;
+};
+type SeriesReadoutPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+interface SeriesReadoutUi {
+  /** Element to append the panel into (typically the chart's stage). */
+  mount: HTMLElement;
+  /** Corner inside `mount`. Default `"top-right"`. */
+  position?: SeriesReadoutPosition;
+  /** Inset (px) from the chosen corner. Default `12`. */
+  inset?: number;
+}
+interface AttachSeriesReadoutOptions {
+  /** DOM mount info. Omit to run headless and observe via `subscribe`. */
+  ui?: SeriesReadoutUi;
+  /**
+   * How to pick a hit per series.
+   * - `"nearest-x"` (default): the hit with smallest |x − cursorX|. Best for
+   *   time-series readouts; one row per series at the cursor's x.
+   * - `"hover"`: only show rows while the cursor is over a real hit (the
+   *   tooltip-style behavior, but extended to every series in the chart).
+   */
+  snap?: "nearest-x" | "hover";
+  /** Per-channel formatters. */
+  format?: SeriesReadoutFormat;
+  /** Hide when the cursor leaves the plot frame. Default `true`. */
+  hideOnLeave?: boolean;
+  /** Notified whenever the snapshot changes (incl. with `ui` attached). */
+  onChange?(snapshot: SeriesReadoutSnapshot | null): void;
+}
+interface AttachedSeriesReadout {
+  peek(): SeriesReadoutSnapshot | null;
+  subscribe(fn: (snapshot: SeriesReadoutSnapshot | null) => void): () => void;
+  dispose(): void;
+}
+//#endregion
+//#region src/grammar/interactions/brush.d.ts
+interface GrammarBrushConfig {
+  /** Which axes the brush spans. Default `"xy"`. */
+  axis?: BrushAxis;
+  /** Translucent fill color. 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 on the committed rect. Default `true`.
+   * Disable to lock a brush rect to its initial drag.
+   */
+  handles?: boolean;
+  /** Hit-test extent of each handle in CSS px. Default 8. */
+  handleSize?: number;
+  /**
+   * Enable drag-to-move on the committed rect interior. Default `true`. The
+   * rect's size is held constant during the move; off-axis movement is locked
+   * for `axis: "x"` / `"y"` brushes. Disable to lock a brush rect in place.
+   */
+  translate?: boolean;
+  /**
+   * Snap brush rect edges to the nearest hit-test position along the chosen
+   * axis. `true` snaps on the brush's active `axis`; pass `"x"` / `"y"` /
+   * `"xy"` to override. Default `false`. Useful for axis-locked range brushes
+   * over discrete x-ticks. The snap is computed against the live hit-test
+   * positions (refreshed on every `sync()`), so it follows the data.
+   */
+  snap?: boolean | BrushAxis;
+}
+interface GrammarBrush {
+  /** Replace the active hit-test set after each pipeline run. */
+  sync<T>(hits: readonly CompiledHitTest<T>[]): void;
+  /** Read-only snapshot of the current brushed hits. */
+  current(): HoveredHit[];
+  /** Current brush rect, or null when idle. */
+  rect(): BrushRect | null;
+  /** Imperatively clear the brush. */
+  clear(): void;
+  /** Draw the brush overlay into the hud layer. */
+  draw(): void;
+  dispose(): void;
+}
+//#endregion
+//#region src/grammar/attach-brush.d.ts
+interface AttachBrushOptions extends GrammarBrushConfig {
+  /**
+   * Fires whenever the brushed set changes — including the empty `[]` after
+   * `clear()` / background tap. Receives one `HoveredHit` per data row whose
+   * hit-test position falls within the brush rect.
+   */
+  onSelect?(hits: readonly HoveredHit[]): void;
+}
+interface AttachedBrush {
+  /** Read-only snapshot of the current brushed hits. */
+  peek(): readonly HoveredHit[];
+  /** Current brush rect in element-local CSS px, or `null` while idle. */
+  rect(): BrushRect | null;
+  /** Subscribe to changes. Fires immediately with the current set. */
+  subscribe(fn: (hits: readonly HoveredHit[]) => void): () => void;
+  /** Imperatively clear the brush. */
+  clear(): void;
+  /** Tear down the brush + interaction nodes. */
+  dispose(): void;
+}
+interface AttachBrushDeps {
+  manager: InteractionManager;
+  /** Plot-frame bounds in element-local CSS px. */
+  bounds: () => Frame;
+  hudLayer: () => Layer;
+  theme: () => Theme;
+  invalidator: Invalidator;
+}
+/**
+ * Internal handle exposed to the mount so it can drive `sync` + `draw` from
+ * its rAF loop and dispose alongside teardown. Public consumers receive the
+ * narrower `AttachedBrush` view returned by `MountedPlot.attachBrush`.
+ */
+interface AttachedBrushInternal extends AttachedBrush {
+  syncHits<T>(hits: readonly CompiledHitTest<T>[]): void;
+  draw(): void;
+  /** Underlying grammar brush — exposed for tests; not part of the public API. */
+  readonly brush: GrammarBrush;
+}
+declare function createAttachedBrush(deps: AttachBrushDeps, opts: AttachBrushOptions): AttachedBrushInternal;
+//#endregion
+//#region src/grammar/annotations.d.ts
+type FrameAnchorX = "left" | "center" | "right";
+type FrameAnchorY = "top" | "middle" | "bottom";
+/** Coordinate value accepted by annotation factories — data value or frame anchor. */
+type AnnotationX = FrameAnchorX | number | Date | string;
+type AnnotationY = FrameAnchorY | number | Date | string;
+interface TextAnnotationSpec {
+  kind?: "text";
+  text: string;
+  /**
+   * Horizontal position. A `FrameAnchorX` resolves to the plot frame edges;
+   * a number/Date is run through the active x scale.
+   */
+  x: AnnotationX;
+  /** Vertical position. See `x` — but resolves against the y scale. */
+  y: AnnotationY;
+  /** Pixel offset added after position resolution. */
+  offsetX?: number;
+  offsetY?: number;
+  align?: ValueLabelAlign;
+  color?: Color;
+  fontSize?: number;
+  fontStyle?: string;
+  box?: LabelBoxStyle;
+}
+interface ArrowAnnotationSpec {
+  kind: "arrow";
+  /** Tail of the arrow — `[x, y]` in data or frame-anchor coordinates. */
+  from: readonly [AnnotationX, AnnotationY];
+  /** Head of the arrow. Direction is `from → to`. */
+  to: readonly [AnnotationX, AnnotationY];
+  /** Optional label rendered near the arrowhead. */
+  label?: string;
+  /**
+   * Pixel offset for the label relative to the arrowhead. Default
+   * `[6, -6]` — to-the-right-and-above the head.
+   */
+  labelOffset?: readonly [number, number];
+  labelAlign?: ValueLabelAlign;
+  labelBox?: LabelBoxStyle;
+  /** Stroke color for the shaft and head fill. Defaults to `theme.text.color`. */
+  color?: Color;
+  /** Shaft thickness in CSS pixels. Default `1.5`. */
+  strokeWidth?: number;
+  /**
+   * Arrowhead size in CSS pixels — total length from base to tip. Default
+   * `9`; the head is `headSize × 0.5` wide at the base.
+   */
+  headSize?: number;
+  fontSize?: number;
+  fontStyle?: string;
+}
+interface CalloutAnnotationSpec {
+  kind: "callout";
+  /** Data point the callout is anchored to. */
+  at: readonly [AnnotationX, AnnotationY];
+  /** Label text rendered at the offset position. */
+  label: string;
+  /**
+   * Pixel offset from the anchor to the label position. The leader line
+   * runs between them. Default `[40, -20]`.
+   */
+  offset?: readonly [number, number];
+  /** Leader stroke color. Defaults to `theme.text.color` (faded by `leaderAlpha`). */
+  color?: Color;
+  /** Multiplier on the leader's stroke alpha. Default `0.6`. */
+  leaderAlpha?: number;
+  /** Leader thickness in CSS pixels. Default `1`. */
+  strokeWidth?: number;
+  /** Label text color. Defaults to `theme.text.color`. */
+  labelColor?: Color;
+  align?: ValueLabelAlign;
+  box?: LabelBoxStyle;
+  fontSize?: number;
+  fontStyle?: string;
+}
+type AnnotationSpec = TextAnnotationSpec | ArrowAnnotationSpec | CalloutAnnotationSpec;
+declare const annotate: {
+  readonly arrow: (spec: Omit<ArrowAnnotationSpec, "kind">) => ArrowAnnotationSpec;
+  readonly callout: (spec: Omit<CalloutAnnotationSpec, "kind">) => CalloutAnnotationSpec;
+  readonly text: (spec: Omit<TextAnnotationSpec, "kind">) => TextAnnotationSpec;
+};
+//#endregion
+//#region src/grammar/facet.d.ts
+type FacetScales = "fixed" | "free";
+interface FacetStripStyle {
+  height?: number;
+  fontSize?: number;
+  color?: Color;
+  background?: Color;
+}
+interface FacetSpec<T> {
+  /** Accessor / column name producing the facet key per datum. */
+  by: Aes<T, unknown>;
+  /** Number of columns. Default: ceil(sqrt(n)). */
+  ncol?: number;
+  /** Number of rows. Default: ceil(n / ncol). */
+  nrow?: number;
+  /**
+   * Scale handling across panels.
+   * - `"fixed"` (default) — every panel shares the same x/y/color/… scales.
+   * - `"free"` — each panel computes its own scales from its data.
+   */
+  scales?: FacetScales;
+  /** Spacing between panels in pixels. Default `12`. */
+  gap?: number;
+  /** Strip header style. */
+  strip?: FacetStripStyle;
+  /** Optional formatter for the strip label. */
+  format?: (key: unknown) => string;
+}
+//#endregion
+//#region src/grammar/geoms/point.d.ts
+interface PointChannels<T> {
+  x: Aes<T, number | Date>;
+  y: Aes<T, number | Date>;
+  color?: Aes<T, unknown>;
+  size?: Aes<T, number>;
+  /**
+   * Categorical shape mapping. Values are looked up in the active shape scale
+   * — by default a built-in palette (`POINT_SHAPE_PALETTE`). Pass a literal
+   * `PointShapeKind` accessor and `.scale("shape", { palette: [...] })` to
+   * customize. When the value is already a `PointShapeKind`, it's used as-is.
+   */
+  shape?: Aes<T, unknown>;
+  alpha?: Aes<T, number>;
+  /**
+   * Per-datum border treatment. The accessor may return either a resolved
+   * {@link PointBorderStyle} (used as-is) or any other categorical value that
+   * gets routed through the active `borderStyle` scale (default palette:
+   * `solid`, `open`, `dashed`, `dotted`). Configure a custom mapping with
+   * `.scale("borderStyle", { palette: [...] })`.
+   */
+  borderStyle?: Aes<T, unknown>;
+  /**
+   * Optional secondary glyph overlaid on the base shape at the same anchor.
+   * Accepts either a resolved {@link PointShapeKind}/`null`, or a categorical
+   * value routed through the `overlayGlyph` scale (default palette starts
+   * with `null` so the most-common category gets no overlay). Configure with
+   * `.scale("overlayGlyph", { palette: [...] })`.
+   */
+  overlayGlyph?: Aes<T, unknown>;
+  /** Overlay radius as a fraction of base radius. Default `0.6`. */
+  overlayScale?: Aes<T, number>;
+}
+interface PointOptions {
+  /** Constant fill if color channel is absent. */
+  fill?: Color;
+  /** Constant point radius if size channel is absent. */
+  radius?: number;
+  /** Override theme stroke. */
+  stroke?: Color | null;
+  /** Override theme stroke width. */
+  strokeWidth?: number;
+  /** Constant shape if shape channel is absent. */
+  shape?: PointShapeKind;
+  /** Constant border style if border-style channel is absent. */
+  borderStyle?: PointBorderStyle;
+  /** Constant overlay glyph if overlay-glyph channel is absent. */
+  overlayGlyph?: PointShapeKind | null;
+  /** Constant overlay scale if overlay-scale channel is absent. */
+  overlayScale?: number;
+  /** Display label for legend (defaults to color column name). */
+  label?: string;
+}
+declare function point<T>(channels: PointChannels<T>, options?: PointOptions): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/line.d.ts
+interface LineChannels<T> {
+  x: Aes<T, number | Date>;
+  y: Aes<T, number | Date>;
+  /** Categorical color channel splits the line into one stroke per category. */
+  color?: Aes<T, unknown>;
+  /**
+   * Optional ordering aesthetic. When present, rows are connected in ascending
+   * order (globally, or within each color-grouped series).
+   */
+  order?: Aes<T, number | Date>;
+}
+interface LineOptions {
+  stroke?: Color;
+  strokeWidth?: number;
+  curve?: LineCurve;
+  curveSamples?: number;
+  dashPattern?: readonly number[];
+  /**
+   * Categorical dash treatment. `dashPattern` takes precedence when both
+   * are supplied. See {@link LineDashStyle}.
+   */
+  dashStyle?: LineDashStyle;
+  label?: string;
+  /**
+   * When true, hover hit-tests resolve to the nearest vertex *by x* — the
+   * cursor's vertical position doesn't influence which datum is picked, so
+   * the user can hover anywhere along the line. Default `false` (per-vertex
+   * Euclidean pick within `pickRadius`). For multi-line charts this means
+   * the cursor's x picks one vertex per series; the topmost series wins
+   * via PointCloud zIndex order.
+   */
+  nearestX?: boolean;
+}
+declare function line<T>(channels: LineChannels<T>, options?: LineOptions): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/connected-scatter.d.ts
+interface ConnectedScatterChannels<T> {
+  x: Aes<T, number | Date>;
+  y: Aes<T, number | Date>;
+  color?: Aes<T, unknown>;
+  order: Aes<T, number | Date>;
+  size?: Aes<T, number>;
+  shape?: Aes<T, unknown>;
+  alpha?: Aes<T, number>;
+}
+interface ConnectedScatterOptions {
+  /** Line-layer options. */
+  line?: LineOptions;
+  /** Point-layer options. Pass `false` to render only the connecting path. */
+  point?: PointOptions | false;
+}
+/**
+ * Grammar helper for the common "connected scatterplot" recipe:
+ * a path ordered by a third variable, optionally topped with points.
+ *
+ * Returns plain geoms so callers still compose with `.layer(text(...))`,
+ * `.annotate(...)`, facets, transitions, and the normal interaction stack.
+ */
+declare function connectedScatter<T>(channels: ConnectedScatterChannels<T>, options?: ConnectedScatterOptions): readonly Geom<T>[];
+//#endregion
+//#region src/grammar/geoms/area.d.ts
+type AreaPosition = "identity" | "stack" | "fill";
+interface AreaChannels<T> {
+  x: Aes<T, number | Date>;
+  /**
+   * Single column → simple area from y=0 to y. Array of column keys → stacked
+   * area, with the implicit `__series` color channel keyed by column name.
+   */
+  y: Aes<T, number | Date> | readonly (keyof T & string)[];
+  color?: Aes<T, unknown>;
+}
+interface AreaOptions {
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** "identity" (default), "stack" (offset zero), or "fill" (offset expand). */
+  position?: AreaPosition;
+  /** Stack ordering — only meaningful with stacked positions. */
+  order?: StackOrder;
+  label?: string;
+  /**
+   * When true, hover hit-tests resolve to the nearest vertex *by x* — the
+   * cursor's vertical position doesn't influence which datum (or stacked
+   * segment) is picked, so the user can hover anywhere along the area.
+   * Default `false` (per-vertex Euclidean pick within `pickRadius`).
+   */
+  nearestX?: boolean;
+}
+declare function area<T>(channels: AreaChannels<T>, options?: AreaOptions): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/bar.d.ts
+type BarPosition = "identity" | "stack" | "dodge" | "fill";
+interface BarChannels<T> {
+  x: Aes<T, string | number | Date>;
+  /**
+   * Single column → simple bars (one per category). Array of column keys →
+   * multi-series bars (stacked / dodged / 100% stacked).
+   *
+   * For horizontal layouts (`orientation: "x"`) the single-column form carries
+   * the band category, so a string is accepted; the value axis then lives on
+   * `x`.
+   */
+  y: Aes<T, string | number | Date> | readonly (keyof T & string)[];
+  color?: Aes<T, unknown>;
+}
+interface BarOptions<T = unknown> {
+  orientation?: BarOrientation;
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  cornerRadius?: number;
+  /**
+   * Border treatment shared across every bar (or segment, for stacked/dodged
+   * layouts). See {@link BarBorderStyle}.
+   */
+  borderStyle?: BarBorderStyle;
+  /**
+   * Multi-series layout. Only meaningful when `y` (or `x`) is an array of keys.
+   * - `"stack"` (default for arrays) — segments stacked from 0
+   * - `"dodge"` — bars side-by-side within each category
+   * - `"fill"` — stacked, normalized to [0, 1]
+   * - `"identity"` — each datum drawn at its raw value
+   */
+  position?: BarPosition;
+  order?: StackOrder;
+  label?: string;
+  /** Inner-band padding for `position: 'dodge'`. Default 0.05. */
+  groupPadding?: number;
+  /** If set, render a label above each bar with the per-category total. */
+  showTotals?: (total: number, datum: T, datumIndex: number) => string;
+  /**
+   * If set, render a label per-bar (or per-segment for stacked / fill) with
+   * the segment's value. For `fill`, the supplied `value` is normalized
+   * `[0, 1]`; for other positions it's the raw segment value. `key` is the
+   * column name for multi-series bars, `undefined` for simple bars.
+   */
+  showValues?: (value: number, datum: T, datumIndex: number, key?: string) => string;
+  /** Override label color. */
+  labelColor?: Color;
+  /** Override label font size. */
+  labelFontSize?: number;
+}
+declare function bar<T>(channels: BarChannels<T>, options?: BarOptions<T>): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/histogram.d.ts
+type HistogramPosition = "identity" | "stack" | "dodge" | "fill";
+interface HistogramChannels<T> {
+  /** Numeric variable to bin. Provide one of `x` (vertical bars) or `y`. */
+  x?: Aes<T, number>;
+  /** Numeric variable to bin. Provide one of `x` (vertical bars) or `y`. */
+  y?: Aes<T, number>;
+  /** Optional categorical group key — splits the sample into per-group bins. */
+  color?: Aes<T, unknown>;
+}
+interface HistogramOptions {
+  /** Explicit bin count. Loses to `binwidth` and `breaks`. */
+  bins?: number;
+  /** Explicit bin width in data units. Beats `bins` and `rule`. */
+  binwidth?: number;
+  /** Fully explicit edge array. Beats every other bin selector. */
+  breaks?: readonly number[];
+  /**
+   * Auto-bin rule when none of `bins`, `binwidth`, `breaks` is set.
+   *
+   * - `"sturges"` (default) — R / ggplot default; works for ~normal data.
+   * - `"rice"` — slightly more bins.
+   * - `"scott"` — uses σ; good for normal-ish data.
+   * - `"fd"` — Freedman–Diaconis; robust to outliers.
+   */
+  rule?: BinRule;
+  /** Clip / extend the value-axis range used when computing edges. */
+  domain?: readonly [number, number];
+  /** Round outer edges + step to nice numbers. Default `true`. */
+  nice?: boolean;
+  /** Edge convention. Default `"left"` (`[x0, x1)` plus closed last bin). */
+  closed?: BinClosed;
+  /**
+   * Y measure. Default `"count"`.
+   *
+   * - `"count"` / `"frequency"` — raw bin count.
+   * - `"density"` — `count / (n · width)`. Integrates to 1 across bins.
+   * - `"proportion"` — `count / n`. Sums to 1 across bins (per group).
+   */
+  y?: HistogramMeasure;
+  /**
+   * Multi-group layout. Default `"stack"` when `color` channel is present,
+   * else `"identity"`.
+   *
+   * - `"identity"` — bars share a baseline of 0; useful with reduced
+   *   `fillAlpha` for an overlay effect.
+   * - `"stack"` — per-bin counts stacked.
+   * - `"dodge"` — sub-divide bin width across groups, side by side.
+   * - `"fill"` — stack normalized to `[0, 1]` per bin.
+   */
+  position?: HistogramPosition;
+  /** Render bars below the baseline (negate the count axis). Default `false`. */
+  mirror?: boolean;
+  /** Override theme `fillAlpha`. Lower this for `position: "identity"` overlays. */
+  fillAlpha?: number;
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  cornerRadius?: number;
+  /** Pixel gap between adjacent bars. Default `0` (continuous wall). */
+  gap?: number;
+  /** Inner-band padding for `position: "dodge"` (fraction of bin width). Default `0.05`. */
+  groupPadding?: number;
+  /** Optional per-bar label (uses bin midpoint + value). */
+  showCounts?: (value: number, bin: BinResult, key?: string) => string;
+  labelColor?: Color;
+  labelFontSize?: number;
+  /** Used by the auto-legend. */
+  label?: string;
+}
+declare function histogram<T>(channels: HistogramChannels<T>, options?: HistogramOptions): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/rug.d.ts
+interface RugChannels<T> {
+  x?: Aes<T, number | Date>;
+  y?: Aes<T, number | Date>;
+  /** Categorical color split for the ticks. */
+  color?: Aes<T, unknown>;
+}
+type RugSide = "x" | "y" | "both";
+interface RugOptions {
+  /**
+   * Which edges receive ticks. Defaults to whichever channels are wired —
+   * with both `x` and `y`, both edges; otherwise just the matching edge.
+   * Use `"both"` to force both edges (mirrors x onto bottom, y onto left).
+   */
+  side?: RugSide;
+  /** Tick length in pixels. Default `6`. */
+  length?: number;
+  /** Tick stroke width. Default `1`. */
+  strokeWidth?: number;
+  /** Override stroke color (defaults to theme.axis.color). */
+  stroke?: Color;
+  /** Multiplier on the resolved stroke alpha. Default `0.6`. */
+  opacity?: number;
+  label?: string;
+}
+declare function rug<T>(channels: RugChannels<T>, options?: RugOptions): Geom<T>;
+//#endregion
+//#region src/grammar/color-utils.d.ts
+/**
+ * Accent-key shorthand used by chart-level marks (`band`, `rule`, `interval`,
+ * `ribbon`). Literal {@link Color} values bypass theme resolution; accent
+ * keys resolve through `theme.accents`.
+ */
+type ColorOrAccent = Color | ThemeAccentKey;
+//#endregion
+//#region src/grammar/geoms/rule.d.ts
+interface RuleChannels<T> {
+  x?: Aes<T, number | Date>;
+  y?: Aes<T, number | Date>;
+}
+interface RuleOptions {
+  /**
+   * Stroke color. Accepts a literal {@link Color} or a theme accent key
+   * (`"positive" | "negative" | "warn" | "info"`); accent keys resolve through
+   * `theme.accents`.
+   */
+  stroke?: ColorOrAccent;
+  strokeWidth?: number;
+  dashPattern?: readonly number[];
+  /** Optional inline rule label (only meaningful for non-data rules). */
+  label?: string;
+  labelColor?: Color;
+  labelInset?: number;
+}
+declare function rule<T>(channels: RuleChannels<T>, options?: RuleOptions): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/smooth.d.ts
+type SmoothMethod = "lm" | "poly" | "loess";
+interface SmoothChannels<T> {
+  x: Aes<T, number | Date>;
+  y: Aes<T, number>;
+  /** Categorical color channel — fits one curve per group. */
+  color?: Aes<T, unknown>;
+}
+interface SmoothLabelOptions {
+  /** Pixel offset from the right end of the fit. */
+  offsetX?: number;
+  offsetY?: number;
+  /** Custom label color. Defaults to the curve color. */
+  color?: Color;
+  fontSize?: number;
+  /** Optional rounded-rect background. */
+  box?: LabelBoxStyle;
+}
+interface SmoothOptions {
+  /** Fit method. Default `"lm"`. */
+  method?: SmoothMethod;
+  /** Degree for `"poly"` (default `2`) or `"loess"` local polynomial (default `1`). */
+  degree?: number;
+  /** Span for `"loess"` (fraction of data per neighborhood). Default `0.5`. */
+  span?: number;
+  /**
+   * Confidence ribbon. `true` (default) → 95%, `false` → no ribbon, `number`
+   * → that confidence level (e.g. `0.99`).
+   */
+  ci?: boolean | number;
+  /** Number of x samples for the curve & ribbon. Default `64`. */
+  samples?: number;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Override the ribbon fill. Defaults to the stroke color at low alpha. */
+  ribbonFill?: Color;
+  ribbonOpacity?: number;
+  /**
+   * Per-group inline label at the right end of each fitted curve. Only emitted
+   * when the `color` channel is present. `true` uses the group key as the
+   * label string.
+   */
+  label?: boolean | SmoothLabelOptions;
+  /**
+   * When true, hit-tests resolve to the nearest sample by x. Hover anywhere
+   * along the curve and the closest source row in the matching group is
+   * picked. Default `false` (Euclidean within `pickRadius`).
+   */
+  nearestX?: boolean;
+}
+declare function smooth<T>(channels: SmoothChannels<T>, options?: SmoothOptions): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/rolling.d.ts
+interface StatRollingChannels<T> {
+  x: Aes<T, number | Date>;
+  y: Aes<T, number>;
+  /** Categorical color channel — runs one rolling fit per group. */
+  color?: Aes<T, unknown>;
+}
+interface StatRollingOptions<T> {
+  /** Sliding window. See `RollingWindow` — bare number = count, object for explicit unit. */
+  window: RollingWindow;
+  /** Default `"mean"`. */
+  statistic?: RollingStatistic<T>;
+  /** Default `"x"`. */
+  axis?: RollingAxis;
+  /** Rows failing the filter are dropped from every window and the output series. */
+  filter?: (datum: T, index: number) => boolean;
+  /** Line curve. Default `"linear"` — pre-smoothed data rarely needs another smoother. */
+  curve?: LineCurve;
+  /** Override the per-group stroke color. When `color` is set, defaults to the color scale. */
+  stroke?: Color;
+  strokeWidth?: number;
+  dashStyle?: LineDashStyle;
+  /**
+   * When true (default), hovering anywhere along the curve resolves to the
+   * nearest rolling point by x — the cursor reads off "the smoothed value
+   * here." Set false for Euclidean nearest within a small pickRadius.
+   *
+   * Hits always carry the synthetic {@link RollingPoint} (`{ x, y, count,
+   * sourceIndex }`) as `info.datum`, not the underlying source row — so a
+   * tooltip resolver can describe the *line's* value at the cursor (e.g.
+   * "14-day mean: 88.4 kg") rather than misattributing a source row's tooltip
+   * to a position on the smoothed curve. Branch on `info.mark === label` to
+   * format the rolling tooltip distinctly from sibling point/line layers.
+   */
+  nearestX?: boolean;
+  /** Used by the auto-legend and tooltip discrimination. Default `"rolling"`. */
+  label?: string;
+}
+declare function statRolling<T>(channels: StatRollingChannels<T>, options: StatRollingOptions<T>): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/ribbon.d.ts
+interface RibbonChannels<T> {
+  x: Aes<T, number | Date>;
+  y0: Aes<T, number | Date>;
+  y1: Aes<T, number | Date>;
+}
+interface RibbonOptions {
+  /**
+   * Fill color. Accepts a literal {@link Color} or a theme accent key
+   * (`"positive" | "negative" | "warn" | "info"`); accent keys resolve through
+   * `theme.accents`.
+   */
+  fill?: ColorOrAccent;
+  stroke?: ColorOrAccent;
+  strokeWidth?: number;
+  fillAlpha?: number;
+  label?: string;
+}
+declare function ribbon<T>(channels: RibbonChannels<T>, options?: RibbonOptions): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/interval.d.ts
+interface IntervalChannels<T> {
+  /** Anchor for vertical intervals (required when `yMin`/`yMax` are bound). */
+  x?: Aes<T, number | Date>;
+  /** Anchor for horizontal intervals (required when `xMin`/`xMax` are bound). */
+  y?: Aes<T, number | Date>;
+  yMin?: Aes<T, number | Date>;
+  yMax?: Aes<T, number | Date>;
+  xMin?: Aes<T, number | Date>;
+  xMax?: Aes<T, number | Date>;
+  /** Optional categorical color channel — routed through the chart's color scale. */
+  color?: Aes<T, unknown>;
+}
+interface IntervalOptions {
+  /**
+   * Stroke color. Accepts a literal {@link Color} or a theme accent key
+   * (`"positive" | "negative" | "warn" | "info"`); accent keys resolve through
+   * `theme.accents`.
+   */
+  stroke?: ColorOrAccent;
+  strokeWidth?: number;
+  /** Render perpendicular caps at each end. Default `true`. */
+  caps?: boolean;
+  /** Cap length in pixels (total, across both sides of the spine). Default `6`. */
+  capWidth?: number;
+  /** Display label for legend. */
+  label?: string;
+}
+declare function interval<T>(channels: IntervalChannels<T>, options?: IntervalOptions): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/band.d.ts
+interface BandChannels {
+  x?: readonly [number | Date, number | Date];
+  y?: readonly [number | Date, number | Date];
+}
+interface BandOptions {
+  /**
+   * Fill color. Accepts a literal {@link Color} or a theme accent key
+   * (`"positive" | "negative" | "warn" | "info"`); accent keys resolve through
+   * `theme.accents` and have `theme.marks.bandFillAlpha` applied unless
+   * {@link BandOptions.alpha} is set.
+   */
+  fill?: ColorOrAccent;
+  stroke?: ColorOrAccent;
+  strokeWidth?: number;
+  /**
+   * Override the fill alpha. Defaults to `theme.marks.bandFillAlpha` when
+   * `fill` is omitted or is an accent key; defaults to no override (use the
+   * color's own alpha) when `fill` is a literal {@link Color}.
+   */
+  alpha?: number;
+  label?: string;
+  labelColor?: Color;
+}
+declare function band<T>(channels: BandChannels, options?: BandOptions): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/text.d.ts
+type TextCollisionMode = "none" | "hide" | "stagger";
+interface TextChannels<T> {
+  x: Aes<T, number | Date | string>;
+  y: Aes<T, number | Date | string>;
+  text: Aes<T, string>;
+}
+interface TextOptions {
+  fontSize?: number;
+  color?: Color;
+  align?: ValueLabelAlign;
+  offsetX?: number;
+  offsetY?: number;
+  /** Optional rounded-rect background. Requires the chart's glyph atlas. */
+  box?: LabelBoxStyle;
+  label?: string;
+  /**
+   * Post-layout collision handling. Default `"none"`. `"hide"` drops
+   * overlapping labels via a greedy first-fit pass; `"stagger"` adds an
+   * alternating y offset so adjacent labels sit on two rows.
+   */
+  collisionMode?: TextCollisionMode;
+  /** Pixel padding around each label's measured rect when checking overlap. Default `2`. */
+  collisionPadding?: number;
+}
+declare function text<T>(channels: TextChannels<T>, options?: TextOptions): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/boxplot.d.ts
+type PointsMode = "auto" | "always" | "none";
+interface BoxplotChannels<T> {
+  /** Categorical band axis. */
+  x: Aes<T, string | number | Date>;
+  /**
+   * Numeric value axis (the distribution to summarize) when vertical. For
+   * horizontal layouts (`orientation: "x"`) this carries the band category, so
+   * a string is accepted; the value axis then lives on `x`.
+   */
+  y: Aes<T, string | number | Date>;
+  /**
+   * Optional grouping key. When supplied (and distinct from `x`) the layer
+   * dodges side-by-side by this channel within each band.
+   */
+  color?: Aes<T, unknown>;
+}
+/**
+ * Mean-overlay configuration. `true` → default red dot; `false` (default) →
+ * no overlay; object → fully customised.
+ */
+interface MeanMarkerOptions {
+  shape?: PointShapeKind;
+  /** Radius in pixels. Default `3.5`. */
+  radius?: number;
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+}
+interface BoxplotOptions {
+  /** Auto-detected from scale types when omitted (band axis = category axis). */
+  orientation?: "x" | "y";
+  /**
+   * Box width as a fraction of the bandwidth (or grouped inner bandwidth, when
+   * dodging). Default `0.6`.
+   */
+  width?: number;
+  /**
+   * Scale box widths by `√(n / nMax)` so groups with more samples render
+   * wider — matches ggplot's `varwidth = TRUE`. Default `false`.
+   */
+  varwidth?: boolean;
+  /** Whisker rule. Default `1.5` (Tukey). Pass `"minmax"` for no outliers. */
+  whisker?: WhiskerRule;
+  /** Quantile interpolation method. Default `"type-7"` (R default). */
+  quantile?: QuantileMethod;
+  /**
+   * Render notches around the median at `± 1.58 · IQR / √n` (McGill 1978's
+   * 95% CI). Useful as an informal significance test: non-overlapping
+   * notches between groups suggest medians differ. Default `false`.
+   */
+  notched?: boolean;
+  /**
+   * Notch indent as a fraction of the box width (how far the sides pull in
+   * at the median). Default `0.5`.
+   */
+  notchWidth?: number;
+  /**
+   * When to overlay raw jittered points.
+   *
+   * - `"auto"` (default) — only when `n < pointsThreshold` for the group.
+   *   Rationale: small samples are easy to mislead with a box; show the dots.
+   * - `"always"` — always overlay.
+   * - `"none"` — never overlay (still draws outliers unless `outliers: false`).
+   */
+  points?: PointsMode;
+  /** Threshold for `points: "auto"`. Default `10`. */
+  pointsThreshold?: number;
+  /** Jitter spread, fraction of the per-box width. Default `0.5`. */
+  pointJitter?: number;
+  /** Radius of overlay & outlier points. Default `2.5`. */
+  pointRadius?: number;
+  /** Override fill for jittered overlay points. Default `alphaize(stroke, 0.5)`. */
+  pointFill?: Color;
+  /** Override fill for outlier points. Default = stroke. */
+  outlierFill?: Color;
+  /** Outlier point radius. Default = `pointRadius`. */
+  outlierRadius?: number;
+  /** Seed for deterministic jitter. Default `1`. */
+  jitterSeed?: number;
+  /** Render outlier dots beyond the whiskers. Default `true`. */
+  outliers?: boolean;
+  /** Constant fill when no `color` channel. Default theme palette[0]. */
+  fill?: Color;
+  /**
+   * Override the theme's fill alpha (use `0` for outline-only boxes, e.g.
+   * to match ggplot's bottom-middle "no-fill" look). When unset the layer
+   * uses `theme.marks.fillAlpha`.
+   */
+  fillAlpha?: number;
+  /** Box stroke color. Default theme text color (light line on dark fill). */
+  stroke?: Color;
+  /** Box stroke width. Default `1`. */
+  strokeWidth?: number;
+  /** Median line color. Defaults to `stroke`. */
+  medianStroke?: Color;
+  /** Median line stroke width. Default `2`. */
+  medianStrokeWidth?: number;
+  /** Whisker line stroke width. Default = `strokeWidth`. */
+  whiskerStrokeWidth?: number;
+  /** Whisker cap width as a fraction of box width. Default `0.5`. */
+  capWidth?: number;
+  /**
+   * Mean overlay. `true` for the default red dot; `false` (default) to omit;
+   * pass an object to customize shape, radius, fill, stroke. The mean is
+   * **not** part of the box geometry — it's an annotation on top.
+   */
+  mean?: boolean | MeanMarkerOptions;
+  /** Inner-band padding for grouped (color-split) layout. Default `0.05`. */
+  groupPadding?: number;
+  /**
+   * Render an `n=<count>` label per band-axis category, just outside the
+   * plot frame. Counts are summed across dodge groups. Default `false`.
+   */
+  showCounts?: boolean;
+  /** Pixel offset of count labels from plot frame. Default `28` (vertical) / `32` (horizontal). */
+  countsOffset?: number;
+  countsFontSize?: number;
+  countsColor?: Color;
+  /** Display label for legend. */
+  label?: string;
+}
+declare function boxplot<T>(channels: BoxplotChannels<T>, options?: BoxplotOptions): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/_distribution.d.ts
+/** How per-row width relates to density across groups. */
+type DensityScale = "width" | "area" | "count";
+//#endregion
+//#region src/grammar/geoms/violin.d.ts
+interface ViolinChannels<T> {
+  x: Aes<T, string | number | Date>;
+  /**
+   * Numeric value axis when vertical. For horizontal layouts
+   * (`orientation: "x"`) this carries the band category, so a string is
+   * accepted; the value axis then lives on `x`.
+   */
+  y: Aes<T, string | number | Date>;
+  color?: Aes<T, unknown>;
+}
+type ViolinScale = DensityScale;
+type ViolinInner = "box" | "quartile" | "stick" | "none";
+interface ViolinOptions {
+  orientation?: "x" | "y";
+  /** Violin width as a fraction of the bandwidth (or grouped inner bandwidth). Default `0.9`. */
+  width?: number;
+  /** KDE bandwidth — number, `"silverman"` (default), or `"scott"`. */
+  bandwidth?: KdeBandwidth;
+  /** KDE evaluation grid size. Default `64`. */
+  gridSize?: number;
+  /** KDE kernel. Default `"gaussian"`. */
+  kernel?: KdeKernel;
+  /** Clip KDE to data range (true, default) or pad outward by ~3 bandwidths. */
+  trim?: boolean;
+  /**
+   * Width-normalization mode.
+   *
+   * - `"width"` (default) — each violin uses its full allotted width; shapes
+   *   are easy to compare but **areas are misleading**.
+   * - `"area"` — density scaled relative to the global max so areas are
+   *   comparable across groups (groups with low n look skinny).
+   * - `"count"` — area scales with sample size (bigger n → wider violin).
+   */
+  scale?: ViolinScale;
+  /**
+   * Inner annotation drawn on top of the violin.
+   *
+   * - `"none"` (default) — bare KDE polygon, like ggplot's `geom_violin`.
+   * - `"box"` — slim box plot with median, IQR, whiskers.
+   * - `"quartile"` — three horizontal/vertical lines at Q1, median, Q3.
+   * - `"stick"` — single line at the median only.
+   */
+  inner?: ViolinInner;
+  /** When to overlay raw jittered points. See `BoxplotOptions["points"]`. */
+  points?: PointsMode;
+  pointsThreshold?: number;
+  pointJitter?: number;
+  pointRadius?: number;
+  jitterSeed?: number;
+  /** Box stats: whisker rule when `inner: "box"`. Default `1.5`. */
+  whisker?: WhiskerRule;
+  /** Box stats: quantile method. Default `"type-7"`. */
+  quantile?: QuantileMethod;
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Color of inner annotation marks. Defaults to `stroke` (or theme text). */
+  innerStroke?: Color;
+  /** Stroke width for the embedded mini-box body. Default `1`. */
+  innerStrokeWidth?: number;
+  /** Inner-band padding for grouped (color-split) layout. Default `0.05`. */
+  groupPadding?: number;
+  /**
+   * Render an `n=<count>` label per group, aligned with the band axis just
+   * outside the plot frame. Useful when the categorical labels alone hide
+   * sample-size differences.
+   */
+  showCounts?: boolean;
+  /**
+   * Pixel offset of the count labels from the plot frame edge along the
+   * band-axis perpendicular. Increase to clear longer tick labels. Default
+   * `28` (vertical) / `32` (horizontal).
+   */
+  countsOffset?: number;
+  countsFontSize?: number;
+  countsColor?: Color;
+  label?: string;
+}
+declare function violin<T>(channels: ViolinChannels<T>, options?: ViolinOptions): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/ridgeline.d.ts
+type RidgelineGeom = "kde" | "histogram";
+type RidgelineScale = DensityScale;
+type RidgelineInner = "none" | "median" | "quartile" | "mean";
+type RidgelineFillMode = "solid" | "gradient";
+interface RidgelineChannels<T> {
+  /** Numeric value being distributed. Provide one of x or y; the other is the row category. */
+  x: Aes<T, string | number>;
+  y: Aes<T, string | number>;
+  /** Optional categorical group key. Drives palette fill (chart color scale). */
+  color?: Aes<T, unknown>;
+}
+interface RidgelineOptions {
+  /** Auto-detected from scale types when omitted. The default reproduces the common "rows on y, values on x" layout. */
+  orientation?: "x" | "y";
+  /** Density estimator. Default `"kde"`. */
+  geom?: RidgelineGeom;
+  /**
+   * How tall a ridge can be relative to its band-cell spacing. `1` = no
+   * overlap (each ridge stays inside its row); `>1` allows overlap into
+   * neighbours. Default `2.5`.
+   */
+  overlap?: number;
+  /**
+   * Across-group height normalization (same semantics as `violin`'s `scale`).
+   *
+   * - `"width"` (default) — each row uses its full allotted height.
+   * - `"area"` — heights normalized by the global max density.
+   * - `"count"` — heights scaled by sample size on top of `"area"`.
+   */
+  scale?: RidgelineScale;
+  bandwidth?: KdeBandwidth;
+  gridSize?: number;
+  kernel?: KdeKernel;
+  trim?: boolean;
+  bins?: number;
+  binwidth?: number;
+  breaks?: readonly number[];
+  rule?: BinRule;
+  measure?: HistogramMeasure;
+  closed?: BinClosed;
+  /**
+   * Solid fill (default) uses the chart color scale per category, or the
+   * theme's categorical palette if no `color` channel is mapped. Gradient
+   * fill ignores the category and applies a value-axis-mapped color ramp,
+   * reproducing the "Lincoln NE temperatures" look.
+   */
+  fillMode?: RidgelineFillMode;
+  /**
+   * Color ramp for `fillMode: "gradient"`. Receives `t ∈ [0, 1]` mapped from
+   * the value-axis range. Default = `theme.palettes.continuous`.
+   */
+  gradient?: (t01: number) => Color;
+  /** Per-row inner annotation. Default `"none"`. */
+  inner?: RidgelineInner;
+  innerStroke?: Color;
+  innerStrokeWidth?: number;
+  /** Radius of the median/mean dot when `inner` includes a point. Default `3`. */
+  innerDotRadius?: number;
+  /** Draw a thin rule along each row's baseline. Default `true`. */
+  baseline?: boolean;
+  baselineStroke?: Color;
+  baselineWidth?: number;
+  /** `n=<count>` per row, anchored inline at the row baseline by default. */
+  showCounts?: boolean;
+  countsAnchor?: "outside" | "inline";
+  /** Pixel offset for the counts label. Default 4 (inline) / 28 (outside, vertical) / 32 (outside, horizontal). */
+  countsOffset?: number;
+  countsFontSize?: number;
+  countsColor?: Color;
+  /** Solid fill for the silhouette. Default theme palette[0] (overridden by chart color scale when `color` is set). */
+  fill?: Color;
+  fillAlpha?: number;
+  /** Silhouette outline. Default theme text color. */
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Inner-band padding when dodging via `color`. Default `0.05`. */
+  groupPadding?: number;
+  whisker?: WhiskerRule;
+  quantile?: QuantileMethod;
+  label?: string;
+}
+declare function ridgeline<T>(channels: RidgelineChannels<T>, options?: RidgelineOptions): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/tile.d.ts
+interface TileChannels<T> {
+  x: Aes<T, string | number | Date>;
+  y: Aes<T, string | number | Date>;
+  /**
+   * Continuous fill — typically a numeric column. Drives the chart's color
+   * scale (legend renders as a continuous color bar). For a per-cell constant
+   * color, pass `options.fill` instead and omit this channel.
+   */
+  fill?: Aes<T, unknown>;
+}
+interface TileNAOptions {
+  /** Fill for missing/non-finite values. When unset, NA cells are skipped. */
+  fill?: Color;
+}
+interface TileOptions<T = unknown> {
+  /**
+   * Constant cell color when no `fill` channel is mapped. Ignored when
+   * `channels.fill` is present (in which case the color scale supplies the
+   * fill).
+   */
+  fill?: Color;
+  /** Horizontal/vertical inset between cells. Default `0`. */
+  padding?: number;
+  /** Per-axis padding override (multi-key form). Wins over `padding`. */
+  paddingX?: number;
+  paddingY?: number;
+  /** Optional border outline per cell. */
+  stroke?: Color;
+  strokeWidth?: number;
+  cornerRadius?: number;
+  /**
+   * Per-cell text label. Receives the (numeric) fill value when the `fill`
+   * channel is mapped; receives `NaN` otherwise (in which case you'll
+   * typically derive the label from the datum directly).
+   */
+  showValues?: (value: number, datum: T, index: number) => string;
+  labelColor?: Color;
+  labelFontSize?: number;
+  /**
+   * Skip per-cell labels when the projected cell is below this pixel size on
+   * either axis. Labels at small cell sizes are unreadable smudges and the
+   * shaping cost dominates frame time at high cell counts. Default: unset
+   * (every cell labeled). A value around `1.5 * labelFontSize` is a sensible
+   * floor for legibility.
+   */
+  minLabelCellPx?: number;
+  /**
+   * For numeric/time x or y axes only — the implicit cell width/height in
+   * domain units. When omitted, the cell extent is inferred from the
+   * smallest gap between sorted unique values in the data.
+   */
+  cellWidth?: number;
+  cellHeight?: number;
+  /** Missing-value handling. */
+  na?: TileNAOptions;
+  label?: string;
+}
+declare function tile<T>(channels: TileChannels<T>, options?: TileOptions<T>): Geom<T>;
+//#endregion
+//#region src/grammar/geoms/aggregate.d.ts
+type AggregateBinBy = "x" | "y";
+type AggregateBinSize = number | "auto" | ((info: AutoBinSizeInfo) => number);
+interface AutoBinSizeInfo {
+  /** Pixel span of the binned axis (positive). */
+  pixelSpan: number;
+  /** Domain span of the binned axis in axis units (positive). For time scales, ms. */
+  domainSpan: number;
+  /** `pixelSpan / domainSpan` — pixels per domain unit on the binned axis. */
+  pixelsPerUnit: number;
+}
+type AggregateSummaryKind = "mean" | "median" | "count" | "sum" | "first" | "last";
+interface AggregateBinView<T> {
+  /** Values from the *non-binned* axis, in input order within this bin. */
+  values: readonly number[];
+  /** Source items inside this bin, in input order. */
+  items: readonly T[];
+  /** Count after filter. */
+  count: number;
+  /** Bin's lower edge on the binned axis (inclusive). */
+  lo: number;
+  /** Bin's upper edge on the binned axis (exclusive, except the final bin). */
+  hi: number;
+}
+type AggregateSummary<T> = AggregateSummaryKind | ((bin: AggregateBinView<T>) => number);
+/** Result of a bundle summary — one center + a [lo, hi] range per bin. */
+interface AggregateBundleResult {
+  center: number;
+  lo: number;
+  hi: number;
+}
+type AggregateBundleSummaryKind = "mean+ci" | "median+iqr";
+/**
+ * Bundle summaries emit `{ center, lo, hi }` per bin and pair with the
+ * `interval` or `ribbon` inner geom. Built-in kinds plus a quantile triple
+ * `{ quantiles: [loQ, centerQ, hiQ] }` (e.g. `[0.1, 0.5, 0.9]` for an 80%
+ * range) or a custom function returning the bundle directly.
+ */
+type AggregateBundleSummary<T> = AggregateBundleSummaryKind | {
+  quantiles: readonly [number, number, number];
+} | ((bin: AggregateBinView<T>) => AggregateBundleResult);
+interface AggregateChannels<T> {
+  x: Aes<T, number | Date>;
+  y: Aes<T, number | Date>;
+}
+type AggregateInnerGeom = "point" | "line" | "bar" | "interval" | "ribbon";
+interface AggregateOptions<T> {
+  /** Axis to slide along. Default `"x"`. */
+  binBy?: AggregateBinBy;
+  /** Bin width in domain units; `"auto"` targets `~autoTargetPx` px. Default `"auto"`. */
+  binSize?: AggregateBinSize;
+  /**
+   * Reduction applied per bin. Scalar kinds (`"mean"`, `"median"`, …) pair
+   * with `geom: "point" | "line" | "bar"`. Bundle kinds (`"mean+ci"`,
+   * `"median+iqr"`, `{ quantiles }`, function-returning-`{center, lo, hi}`)
+   * pair with `geom: "interval" | "ribbon"`. Default `"mean"`.
+   */
+  summary?: AggregateSummary<T> | AggregateBundleSummary<T>;
+  /** Row predicate. Rejected rows are excluded from both binning and the
+   *  raw-fallback path. */
+  filter?: (datum: T, index: number) => boolean;
+  /** When `avg-points-per-bin < dissolveAt`, render raw geom instead.
+   *  Default `1.2`. */
+  dissolveAt?: number;
+  /** Inner mark kind. Default `"point"`. */
+  geom?: AggregateInnerGeom;
+  /** Fill / stroke applied to every emitted mark. */
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Point-specific. */
+  radius?: number;
+  shape?: PointShapeKind;
+  /** Line-specific. */
+  curve?: LineCurve;
+  /** Target pixels per bin for `"auto"` sizing. Default `7`. */
+  autoTargetPx?: number;
+  /** Display label for legend / hit-test (forwarded to inner mark). */
+  label?: string;
+  /**
+   * Confidence level for the `"mean+ci"` bundle summary. Default `0.95`.
+   * Ignored for other summaries.
+   */
+  ciLevel?: number;
+  /** Interval-specific: render perpendicular caps. Default `true`. */
+  caps?: boolean;
+  /** Interval-specific: cap length in pixels. Default `6`. */
+  capWidth?: number;
+  /** Ribbon-specific: fill alpha override (otherwise theme.marks.ribbonFillAlpha). */
+  fillAlpha?: number;
+}
+declare function aggregate<T>(channels: AggregateChannels<T>, options?: AggregateOptions<T>): Geom<T>;
+//#endregion
+//#region src/grammar/chart.d.ts
+type Row = Record<string, unknown>;
+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;
+}
+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";
+}
+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.
+ */
+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)`.
+ */
+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";
+  };
+}
+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).
+ */
+type LegendMergeChannel = "color" | "shape" | "size" | "borderStyle" | "overlayGlyph";
+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?: _$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[];
+}
+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;
+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. */
+interface TransitionsHandle {
+  /** Trigger a transition on the next draw (e.g. after a scale domain change). */
+  requestTransition(): void;
+}
+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"`.
+ */
+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.
+ */
+type ChartPanBounds = ChartPanBoundsOptions | false;
+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;
+  };
+}
+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;
+  };
+}
+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;
+}
+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?: _$insomni.MenuPlacement;
+  /** Style overrides for the rendered menu. */
+  style?: _$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;
+}
+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;
+}
+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: _$insomni.Mods;
+  originalEvent: Event | null;
+}
+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.
+ */
+type TooltipAccent = "positive" | "negative" | "neutral" | Color;
+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.
+ */
+interface TooltipContentShorthand {
+  title?: string;
+  rows: readonly TooltipShorthandRow[];
+}
+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.
+ */
+type TooltipContentResolver<T = unknown> = (info: TooltipContentInfo<T>) => TooltipContentResult | null | undefined;
+type TooltipContentResult = TooltipContentShorthand | string;
+/** One auto-built series row in axis-mode tooltips (mirrors SeriesReadoutRow). */
+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. */
+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.
+ */
+type AxisTooltipContentResolver = (info: AxisTooltipInfo) => TooltipContentShorthand | null | undefined;
+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;
+}
+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;
+}
+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.
+ */
+interface BrushedSignal {
+  get(): readonly HoveredHit[];
+  peek(): readonly HoveredHit[];
+  subscribe(fn: (v: readonly HoveredHit[]) => void): () => void;
+  /** Imperatively clear the active brush. */
+  clear(): void;
+}
+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).
+ */
+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.
+ */
+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.
+ */
+interface HoveredSignal {
+  get(): HoveredHit | null;
+  peek(): HoveredHit | null;
+  subscribe(fn: (v: HoveredHit | null) => void): () => void;
+}
+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: 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: AttachRangePresetsOptions): 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: AttachSeriesReadoutOptions): 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: AttachBrushOptions): 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>`. */
+type MountedChart<T = Row> = MountedPlot<T>;
+interface RenderTarget {
+  axisLayer: Layer;
+  marksLayer: Layer;
+  hudLayer: Layer;
+  width?: number;
+  height?: number;
+}
+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;
+}
+declare function plot<T>(spec: PlotSpec<T>): Chart<T>;
+//#endregion
+//#region src/grammar/data/pivot.d.ts
+interface FromMatrixOptions {
+  /** Y labels (rows). Top to bottom. Length must equal `values.length`. */
+  rows: readonly string[];
+  /** X labels (cols). Left to right. Length must equal `values[0].length`. */
+  cols: readonly string[];
+  /** Output key for the row label. Default `"row"`. */
+  rowKey?: string;
+  /** Output key for the col label. Default `"col"`. */
+  colKey?: string;
+  /** Output key for the cell value. Default `"value"`. */
+  valueKey?: string;
+}
+/**
+ * Convert a 2D `values[row][col]` matrix into long-format rows that the
+ * `tile()` geom consumes directly. Cells with `NaN` / `null` / `undefined`
+ * are kept (so consumers can opt into NA cell rendering); cells whose
+ * coordinates are out of range are skipped.
+ *
+ * Example:
+ * ```ts
+ * const long = fromMatrix(temperatures, {
+ *   rows: ["00:00", "06:00", "12:00", "18:00"],
+ *   cols: ["Mon", "Tue", "Wed", "Thu", "Fri"],
+ * });
+ * tile({ x: "col", y: "row", fill: "value" })
+ * ```
+ */
+declare function fromMatrix(values: readonly (readonly number[])[], opts: FromMatrixOptions): {
+  row: string;
+  col: string;
+  value: number;
+}[];
+interface PivotLongerOptions<T> {
+  /** Output column name for the original key. Default `"name"`. */
+  nameKey?: string;
+  /** Output column name for the value. Default `"value"`. */
+  valueKey?: string;
+  /** Optional id columns kept verbatim alongside the long pair. */
+  idColumns?: readonly (keyof T & string)[];
+}
+/**
+ * Pivot a wide row to a sequence of long rows — one per `keys` entry.
+ * `idColumns` are copied through to every output row so a per-row identifier
+ * (e.g. car name in the mtcars example) is preserved.
+ *
+ * Example:
+ * ```ts
+ * const long = pivotLonger(mtcars, ["mpg", "cyl", "disp", "hp"], {
+ *   idColumns: ["model"],
+ * });
+ * // → [{ model, name: "mpg", value }, { model, name: "cyl", value }, ...]
+ * ```
+ */
+declare function pivotLonger<T extends Record<string, unknown>>(rows: readonly T[], keys: readonly (keyof T & string)[], options?: PivotLongerOptions<T>): Record<string, unknown>[];
+//#endregion
+//#region src/grammar/palettes.d.ts
+/** Built-in categorical palette identifiers supported by `distinguishable`. */
+type DistinguishableScheme = "category10" | "tableau10" | "set1" | "set2" | "set3" | "dark2" | "paired" | "pastel";
+interface DistinguishableOptions {
+  /** Per-channel cardinality. Each count must be ≥ 1. */
+  for: {
+    color: number;
+    shape: number;
+  };
+  /**
+   * Categorical palette to source the color palette from. Default
+   * `"category10"`. Pass a `CategoricalPalette` directly for a custom set.
+   */
+  scheme?: DistinguishableScheme | CategoricalPalette;
+  /**
+   * Override the shape pool. Default: `POINT_SHAPE_PALETTE` from `marks`,
+   * which is already ordered for silhouette distinctness.
+   */
+  shapes?: readonly PointShapeKind[];
+}
+interface DistinguishablePalettes {
+  /**
+   * A categorical palette sliced to exactly `for.color` colors from the
+   * requested scheme. Plug into `scale("color", { palette })`.
+   */
+  color: CategoricalPalette;
+  /**
+   * Shape palette sliced to exactly `for.shape` entries. Plug into
+   * `scale("shape", { palette })`.
+   */
+  shape: readonly PointShapeKind[];
+}
+/**
+ * Build a matched `{ color, shape }` pair sized for the two channels'
+ * cardinalities. Sugar over manual `palette.colors.slice(0, N)` +
+ * `POINT_SHAPE_PALETTE.slice(0, M)` — the goal is one declaration site for
+ * the visual contract of a multi-encoding chart.
+ *
+ * Counts that exceed the source pool wrap modulo length, matching the
+ * default `CategoricalPalette` / scale wrap semantics so the helper never
+ * silently drops categories. (The visual distinction degrades past the pool
+ * size — that's an authoring problem, not a library one — but the runtime
+ * stays consistent with the rest of the scale system.)
+ */
+declare function distinguishable(options: DistinguishableOptions): DistinguishablePalettes;
+/**
+ * `palettes` namespace — currently the home of `distinguishable`. Future
+ * combinators (legend-paired schemes, perceptual-uniform slicing, …) live
+ * here so the surface stays small and predictable.
+ */
+declare const palettes: {
+  readonly distinguishable: typeof distinguishable;
+};
+//#endregion
+//#region src/grammar/profiling.d.ts
+interface RecorderHook {
+  recordCpu(name: string, durationMs: number): void;
+  recordGpu(name: string, startNs: number, endNs: number): void;
+}
+/** Inject a recorder (e.g. devtools' `recordCpu`/`recordGpu`). Pass `null` to reset to no-op. */
+declare function setRecorderHook(rec: RecorderHook | null): void;
+//#endregion
+//#region src/grammar/phylo.d.ts
+/**
+ * Subset of `@phylon/renderer`'s `TipAxis` consumed by the bridge. Any object
+ * with this shape (typically the `tipAxis` field on a `RectLayout`) works.
+ */
+interface TipAxisLike {
+  /** Number of tips. */
+  count: number;
+  /** Tip node ids in display order (top→bottom for rectilinear). */
+  order: ArrayLike<number>;
+  /** Tip node id → label, or `null` if the tip is unnamed. */
+  name(tipId: number): string | null;
+}
+interface TipScaleOptions {
+  /**
+   * Band padding in [0, 1). Default `0` — heatmaps and tile-style geoms want
+   * tight rows. Bump to e.g. `0.1` for visible gaps between bars.
+   */
+  padding?: number;
+  /**
+   * Replacement label for unnamed tips. Receives the tip's node id and its
+   * row index. Default: `(id) => "tip_" + id`.
+   */
+  unnamed?: (tipId: number, row: number) => string;
+}
+/**
+ * Build a y-channel `PositionScaleOptions` from a phylo `TipAxis`. The
+ * resulting scale is a band scale whose domain is the tip names in tree
+ * display order (top→bottom). Geoms whose `y` aesthetic resolves to a tip
+ * name will land on the matching tree row.
+ *
+ * Tip labels in the data must match `axis.name(tipId)`. Use `joinByTip`
+ * (phylo) to align metadata rows to tip names ahead of time.
+ */
+declare function tipScale(axis: TipAxisLike, opts?: TipScaleOptions): BandPositionScaleOptions;
+/**
+ * Structural shape of a phylo `CladeStrip` — neutral data describing a clade
+ * range plus a label. Mirrors `@phylon/renderer`'s exported `CladeStrip` so the
+ * plot package doesn't have to depend on phylo to consume them.
+ */
+interface CladeStripLike {
+  label: string;
+  tipCenter: string;
+  color?: Color;
+  offsetX?: number;
+}
+interface CladeStripAnnotationOptions {
+  /**
+   * Pixel offset added to every strip's annotation. Default `8` — pushes the
+   * label clear of the chart's right edge / tip labels. Per-strip
+   * `offsetX` is added on top of this.
+   */
+  offsetX?: number;
+  fontSize?: number;
+  fontStyle?: string;
+}
+/**
+ * Convert phylo `CladeStrip[]` into plot `AnnotationSpec[]`. Labels anchor at
+ * the chart's right frame edge, vertically aligned to the clade's y-center
+ * (resolved by the y-channel's `tipScale`). v1 emits text-only annotations;
+ * brackets are a follow-up that needs a non-text annotation kind.
+ */
+declare function cladeStripsToAnnotations(strips: readonly CladeStripLike[], opts?: CladeStripAnnotationOptions): TextAnnotationSpec[];
+//#endregion
+export { type Accessibility, type AccessibilityMode, type Accessor, type Aes, type AggregateBinBy, type AggregateBinSize, type AggregateBinView, type AggregateBundleResult, type AggregateBundleSummary, type AggregateBundleSummaryKind, type AggregateChannels, type AggregateInnerGeom, type AggregateOptions, type AggregateSummary, type AggregateSummaryKind, type AlphaScaleOptions, type AnnotationSpec, type AnnotationX, type AnnotationY, type AreaChannels, type AreaOptions, type AreaPosition, type ArrowAnnotationSpec, type AttachBrushOptions, type AttachRangePresetsOptions, type AttachRangePresetsPosition, type AttachRangePresetsUi, type AttachSeriesReadoutOptions, type AttachedBrush, type AttachedBrushInternal, type AttachedRangePresets, type AttachedSeriesReadout, type AutoBinSizeInfo, type AxesSpec, type AxisSpec, type AxisTickFormatter, type AxisTooltipContentResolver, type AxisTooltipInfo, type AxisTooltipRow, type BandChannels, type BandOptions, type BarChannels, type BarOptions, type BarPosition, type BlendSpace, type BorderStyleScaleOptions, type BoxplotChannels, type BoxplotOptions, type CalloutAnnotationSpec, type Channel, type ChannelSpec, type Chart, type ChartPanBounds, type ChartPanBoundsOptions, type CladeStripAnnotationOptions, type CladeStripLike, type ColorOrAccent, type ColorScaleOptions, type ColorScaleType, type CompileContext, type CompiledHitTest, type ConnectedScatterChannels, type ConnectedScatterOptions, type ContrastMetric, type Coord, type CoordAxesArgs, type CoordPanArgs, type CoordPolarOptions, type CoordViewportHandle, type CoordZoomArgs, DEFAULT_ACCESSIBILITY, DEFAULT_BORDER_STYLE_PALETTE, DEFAULT_OVERLAY_GLYPH_PALETTE, type DistinguishableOptions, type DistinguishablePalettes, type DistinguishableScheme, type FacetScales, type FacetSpec, type FacetStripStyle, type FrameAnchorX, type FrameAnchorY, type FromMatrixOptions, type Geom, type GeomKind, type HistogramChannels, type HistogramMeasure, type HistogramOptions, type HistogramPosition, type HoveredHit, type IntervalChannels, type IntervalOptions, type LegendMergeChannel, type LegendSpec, type LineChannels, type LineOptions, type MountPlotOptions, type MountedChart, type MountedPlot, type OverlayGlyphScaleOptions, type PanZoomAxes, type PanZoomConfig, type PivotLongerOptions, type PlotSpec, type Point, type PointChannels, type PointOptions, type PointsMode, type PositionScaleOptions, type PositionScaleType, type RecorderHook, type RenderTarget, type ResolveTextColorOptions, type ResolvedChannelMap, type RibbonChannels, type RibbonOptions, type RidgelineChannels, type RidgelineFillMode, type RidgelineGeom, type RidgelineInner, type RidgelineOptions, type RidgelineScale, type Row, type RugChannels, type RugOptions, type RugSide, type RuleChannels, type RuleOptions, type ScaleBundle, type ScaleOptionsByChannel, type SeriesReadoutFormat, type SeriesReadoutPosition, type SeriesReadoutRow, type SeriesReadoutSnapshot, type SeriesReadoutUi, type ShapeScaleOptions, type SizeScaleOptions, type SmoothChannels, type SmoothLabelOptions, type SmoothMethod, type SmoothOptions, type StatRollingChannels, type StatRollingOptions, type TextAnnotationSpec, type TextChannels, type TextEffects, type TextOptions, type Theme, type ThemeAccentKey, type ThemeAccents, type ThemeAxis, type ThemeInteractions, type ThemeLegend, type ThemeMarks, type ThemePalettes, type ThemeSubtitle, type ThemeText, type ThemeTitle, type ThemeTooltipAccents, type TickIntervalSpec, type TickSpec, type TileChannels, type TileNAOptions, type TileOptions, type TimeIntervalUnit, type TipAxisLike, type TipScaleOptions, type TitleSpec, type ViolinChannels, type ViolinInner, type ViolinOptions, type ViolinScale, aggregate, annotate, area, attachRangePresets, band, bar, boxplot, cladeStripsToAnnotations, connectedScatter, coordCartesian, coordPolar, coordRadial, createAttachedBrush, distinguishable, fromMatrix, histogram, interval, line, palettes, pivotLonger, plot, point, resolveTextColor, ribbon, ridgeline, rug, rule, setRecorderHook, smooth, statRolling, text, theme, themeDefault, themeMinimalGrid, tile, tipScale, violin };