insomni-plot 0.1.0-alpha.0

package/dist/range-presets-CzECsu3V.d.mts

@@ -0,0 +1,1523 @@
+import { BlendSpace, Color, Frame, FrameRect, GlyphAtlas, Group, Layer, LineCap, LineJoin, ResolvedCameraState, Vec2 } from "insomni";
+import { CameraViewport, ViewportLike } from "insomni/viewport";
+
+//#region src/scales.d.ts
+type NumericRange = readonly [number, number];
+type NumericDomain = readonly [number, number];
+type DateDomain = readonly [Date, Date];
+type TickFormatter<T> = (value: T) => string;
+interface ContinuousScale {
+  (value: number): number;
+  readonly domain: NumericDomain;
+  readonly range: NumericRange;
+  invert(value: number): number;
+  ticks(count?: number): readonly number[];
+  tickFormat(count?: number): TickFormatter<number>;
+}
+interface TimeScale {
+  (value: Date): number;
+  readonly domain: DateDomain;
+  readonly range: NumericRange;
+  invert(value: number): Date;
+  ticks(count?: number): readonly Date[];
+  tickFormat(count?: number): TickFormatter<Date>;
+}
+interface BandScale<Domain> {
+  (value: Domain): number;
+  readonly domain: readonly Domain[];
+  readonly range: NumericRange;
+  bandwidth(): number;
+  step(): number;
+  ticks(): readonly Domain[];
+  tickFormat(): TickFormatter<Domain>;
+}
+type AxisScale<Value> = ContinuousScale | TimeScale | BandScale<Value>;
+interface BandScaleOptions {
+  padding?: number;
+  paddingInner?: number;
+  paddingOuter?: number;
+  align?: number;
+}
+/**
+ * Time interval units accepted by {@link timeTicks} / {@link timeTickFormat}
+ * and by axis `ticks: { interval, step }` specs. `quarter` is sugar for
+ * `month` with step `3 × step`.
+ */
+type TimeIntervalUnit = "millisecond" | "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+declare function linearScale(domain: NumericDomain, range: NumericRange): ContinuousScale;
+declare function sqrtScale(domain: NumericDomain, range: NumericRange): ContinuousScale;
+declare function logScale(domain: NumericDomain, range: NumericRange): ContinuousScale;
+declare function timeScale(domain: DateDomain, range: NumericRange): TimeScale;
+/**
+ * Generate UTC tick dates at an explicit interval (e.g. every month, every
+ * 3 weeks, every quarter). Use this when the default `timeScale.ticks(count)`
+ * heuristic picks the wrong granularity for a known cadence. `step` defaults
+ * to `1`. `quarter` is sugar for `month, step: 3`.
+ */
+declare function timeTicks(domain: DateDomain, unit: TimeIntervalUnit, step?: number): readonly Date[];
+/**
+ * Tick formatter paired with {@link timeTicks}. The label shape is picked
+ * from the unit: years render `"2026"`, months `"Mar 2026"`, days `"Mar 14"`,
+ * etc. — matching the formatter used by {@link timeScale}.
+ */
+declare function timeTickFormat(unit: TimeIntervalUnit, step?: number): TickFormatter<Date>;
+declare function bandScale<Domain>(domain: readonly Domain[], range: NumericRange, options?: BandScaleOptions): BandScale<Domain>;
+interface GroupedBandScale<Outer, Inner> {
+  /** Position (start) of the inner band within `outer`. */
+  (outer: Outer, inner: Inner): number;
+  /** Inner bandwidth — the rendered width of one inner bar. */
+  bandwidth(): number;
+  /** Inner step — distance between adjacent inner band starts. */
+  step(): number;
+  /** Outer band scale this is nested inside. */
+  readonly outer: BandScale<Outer>;
+  /** Ordered keys of the inner band scale. */
+  readonly innerKeys: readonly Inner[];
+}
+interface GroupedBandScaleOptions {
+  padding?: number;
+  paddingInner?: number;
+  paddingOuter?: number;
+  align?: number;
+}
+/**
+ * Build a nested band scale: each band of the `outer` scale is subdivided
+ * into one inner band per key. Returns a function `(outerKey, innerKey) →
+ * position` plus inner `bandwidth()` and `step()`.
+ *
+ * Use this for grouped bars / dot plots where each category has multiple
+ * series side by side. Outer scale handles category placement and
+ * spacing; inner band controls intra-group layout.
+ */
+declare function groupedBandScale<Outer, Inner>(outer: BandScale<Outer>, innerKeys: readonly Inner[], options?: GroupedBandScaleOptions): GroupedBandScale<Outer, Inner>;
+//#endregion
+//#region src/axis.d.ts
+/**
+ * Explicit time interval for axis ticks: render one tick per `step × unit`
+ * regardless of how many fit. `quarter` is sugar for `month, step: 3`. Pairs
+ * with {@link AxisOptions.ticks} on time scales — ignored on numeric / band
+ * scales (those fall back to a default tick count).
+ */
+interface TickIntervalSpec {
+  interval: TimeIntervalUnit;
+  step?: number;
+}
+/**
+ * Tick generation strategy on continuous scales:
+ * - `number` — target count (current default behavior).
+ * - `"auto"` — derive count from the axis's pixel span (~80px/tick horizontal,
+ *   ~50px/tick vertical). Cheap proxy for "as many ticks as comfortably fit."
+ * - `TickIntervalSpec` — explicit time interval (time scales only).
+ *
+ * `undefined` keeps the previous default of {@link DEFAULT_TICKS}.
+ */
+type TickSpec = number | "auto" | TickIntervalSpec;
+/**
+ * Loose tick formatter signature consumed by the grammar's `AxisSpec.format`.
+ * The runtime calls it with the active scale's tick value — `number` for
+ * linear/log/sqrt, `Date` for time, `string` for band scales. Typed loose so
+ * consumers can write `(v: number) => ...` or `(v: Date) => ...` directly
+ * without a wrapping cast; narrow inside the function to the type your scale
+ * produces.
+ */
+type AxisTickFormatter = (value: any) => string;
+interface AxisOrigin {
+  x?: number;
+  y?: number;
+}
+/**
+ * Configuration for axis tick labels. Currently only carries `maxWidth` —
+ * existing `labelFontSize` / `labelColor` / etc. live as flat keys on
+ * `AxisOptions` for back-compat. New per-label knobs go here.
+ */
+interface AxisLabelConfig {
+  /**
+   * Maximum width in pixels for any tick label. Labels exceeding this width
+   * are truncated to the longest prefix that fits with a trailing ellipsis
+   * (`…`). Requires `atlas` to measure text. When unset, labels render at
+   * their natural width.
+   */
+  maxWidth?: number;
+}
+/**
+ * Axis title — accepts either a plain string or a config object. The object
+ * form lets callers cap the title's rendered width with an ellipsis.
+ */
+type AxisTitle = string | {
+  text: string;
+  maxWidth?: number;
+};
+interface AxisOptions<Value> {
+  ticks?: TickSpec;
+  tickValues?: readonly Value[];
+  /**
+   * Render shorter, unlabeled minor tick marks between the major ticks.
+   * - Number `N`: subdivide each major interval into `N` parts (so `N=2`
+   *   places one minor halfway between every adjacent major pair).
+   * - Array: explicit minor tick values, used as-is.
+   *
+   * Minor ticks never render labels and don't affect axis measurement.
+   */
+  minorTicks?: number | readonly Value[];
+  /** Length of minor tick marks. Default `tickSize / 2`. */
+  minorTickSize?: number;
+  /**
+   * Render a tick label only every `N`th major tick. Default `1` (every
+   * major). Use `2` to label every other tick, etc. The hidden ticks still
+   * draw their tick mark and grid line. The first tick is always labeled.
+   */
+  labelStep?: number;
+  /**
+   * Automatic label collision avoidance. `"auto"` measures the
+   * formatted tick labels and inflates `labelStep` until no two visible
+   * labels overlap (with a small padding). Off by default — opt in when
+   * the axis density is data-driven (dense band axes, time axes whose
+   * domain rescales on zoom). Falls back to `labelStep` when no atlas
+   * is available.
+   */
+  labelCollision?: "auto";
+  format?: TickFormatter<Value>;
+  atlas?: GlyphAtlas;
+  labels?: boolean;
+  tickSize?: number;
+  tickWidth?: number;
+  tickColor?: Color;
+  axisLine?: boolean;
+  axisLineWidth?: number;
+  axisLineColor?: Color;
+  /**
+   * Override the axis-line extent in pixels along the axis direction. Defaults
+   * to the scale's range. Pass `[0, plotFrame.width]` (or `.height`) to draw
+   * the spine across the full plot frame even when the data range is inset
+   * (framePadding / `prepareRange` reservations).
+   */
+  axisLineExtent?: readonly [number, number];
+  labelPadding?: number;
+  labelColor?: Color;
+  labelFontSize?: number;
+  labelFontFamily?: string;
+  labelFontWeight?: string;
+  labelFontStyle?: string;
+  /** Per-label configuration (currently `maxWidth` for ellipsis truncation). */
+  label?: AxisLabelConfig;
+  gridLines?: boolean;
+  gridLength?: number;
+  gridWidth?: number;
+  gridColor?: Color;
+  /**
+   * Axis title. Rendered upright alongside the axis — outside the tick
+   * labels for horizontal axes, above the axis line for vertical axes.
+   * Requires `atlas`. Skipped when undefined / empty. Pass an object form
+   * `{ text, maxWidth }` to cap the title width with ellipsis.
+   */
+  title?: AxisTitle;
+  titlePadding?: number;
+  titleFontSize?: number;
+  titleFontFamily?: string;
+  titleFontWeight?: string;
+  titleFontStyle?: string;
+  titleColor?: Color;
+}
+interface TruncateFontOptions {
+  fontSize: number;
+  fontFamily?: string;
+  fontWeight?: string;
+  fontStyle?: string;
+}
+/**
+ * Truncate `text` so its rendered width fits within `maxWidth`, appending an
+ * ellipsis when the original text is too wide. Returns the original text if
+ * it already fits or if measurement is impossible. Uses binary search over
+ * prefix lengths for O(log n) `measureText` calls.
+ */
+declare function truncateToWidth(atlas: GlyphAtlas | undefined, text: string, maxWidth: number | undefined, font: TruncateFontOptions): string;
+interface AxisMeasurement {
+  /**
+   * Total perpendicular space the axis needs. For horizontal axes this is
+   * tick size + label height + (title padding + title height when present),
+   * since the title sits below/above the labels. For vertical axes this is
+   * tick size + label width only — the title for vertical axes is rendered
+   * above the axis (parallel to the value range) and reported separately
+   * via `axialTitleOverhead` so callers can reserve vertical space for it.
+   */
+  readonly thickness: number;
+  /** Maximum measured width across all formatted tick labels. */
+  readonly maxLabelWidth: number;
+  /** Tick label height (font size). */
+  readonly labelHeight: number;
+  /** Whether a title is present and was measured. */
+  readonly hasTitle: boolean;
+  /** Measured title font size (0 if no title). */
+  readonly titleHeight: number;
+  /**
+   * Pixels the axis title needs *along* the value-range axis, on top of the
+   * axis itself. Non-zero only for vertical axes with a title (which is
+   * rendered above the axis line). Horizontal axes return 0 — their title's
+   * footprint is already included in `thickness`.
+   */
+  readonly axialTitleOverhead: number;
+}
+interface AxisBuilder<Value> {
+  addTo(layer: Layer, origin?: AxisOrigin): Layer;
+  /**
+   * Measure how much room the axis will occupy on its perpendicular axis.
+   * Use the result as `AXIS_MARGIN.bottom/left/...` so callers don't have to
+   * hand-tune padding for long tick labels or axis titles.
+   *
+   * Requires an atlas — pass either `options.atlas` at construction or one
+   * via the `atlas` argument here.
+   */
+  measure(atlas?: GlyphAtlas): AxisMeasurement;
+  readonly tickValues: readonly Value[];
+}
+declare function bottomAxis<Value>(scale: AxisScale<Value>, options?: AxisOptions<Value>): AxisBuilder<Value>;
+declare function leftAxis<Value>(scale: AxisScale<Value>, options?: AxisOptions<Value>): AxisBuilder<Value>;
+declare function topAxis<Value>(scale: AxisScale<Value>, options?: AxisOptions<Value>): AxisBuilder<Value>;
+declare function rightAxis<Value>(scale: AxisScale<Value>, options?: AxisOptions<Value>): AxisBuilder<Value>;
+//#endregion
+//#region src/marks/curve.d.ts
+/**
+ * Built-in interpolation modes between successive points:
+ * - `"linear"` — straight line (default).
+ * - `"step"` — horizontal then vertical at midpoint.
+ * - `"step-before"` — vertical then horizontal (value changes immediately).
+ * - `"step-after"` — horizontal then vertical (value held until next x).
+ * - `"monotone-x"` — Fritsch–Carlson monotone cubic. Smooth, no overshoot.
+ *   Safe default for noisy series.
+ * - `"basis"` — uniform B-spline. Very smooth; clipped at endpoints.
+ * - `"catmull-rom"` — Catmull–Rom spline with tension 0.5 — passes through every point.
+ * - `"cardinal"` — Cardinal spline with tension 0.5 — looser, rounder curves.
+ *
+ * You can also pass a `CustomCurve` function for full control. See `defineCurve`.
+ */
+type LineCurvePreset = "linear" | "step" | "step-before" | "step-after" | "monotone-x" | "basis" | "catmull-rom" | "cardinal";
+/**
+ * Custom resampler. Receives the raw points and a sample-density hint
+ * (passed via `lineMark({ curveSamples })`), returns the polyline to draw.
+ * Endpoints should generally pass through `points[0]` and `points.at(-1)`.
+ */
+type CustomCurve = (points: Vec2[], samples: number) => Vec2[];
+type LineCurve = LineCurvePreset | CustomCurve;
+/**
+ * Wrap a resampler function so it has a stable identity for use as a curve
+ * preset. The returned value is callable like a `CustomCurve` and may be
+ * passed wherever `LineCurve` is expected.
+ *
+ * ```ts
+ * const wobble = defineCurve((points, samples) => {
+ *   // …emit your own polyline…
+ * });
+ * lineMark(data, { curve: wobble });
+ * ```
+ */
+declare function defineCurve(resample: CustomCurve): CustomCurve;
+/**
+ * Build a Catmull–Rom-family curve at a given tension.
+ * `tension = 0.5` is classic Catmull–Rom; `0` is a tighter spline; `1` is
+ * very loose. Useful for hand-drawn looking line charts.
+ */
+declare function cardinalCurve(tension?: number): CustomCurve;
+declare function resamplePoints(points: Vec2[], curve: LineCurve, samples: number): Vec2[];
+//#endregion
+//#region src/marks/stack.d.ts
+interface StackSegment<T, K extends string = string> {
+  /** Original datum the segment came from. */
+  readonly datum: T;
+  /** Key of this segment within the datum (matches `keys[subIndex]`). */
+  readonly key: K;
+  /** Numeric value of this segment. */
+  readonly value: number;
+  /** Cumulative offset — where this segment starts (0 for the first key). */
+  readonly base: number;
+  /** `base + value` — where this segment ends. */
+  readonly top: number;
+  /** Index of this segment within its datum (0-based, same order as `keys`). */
+  readonly subIndex: number;
+  /** Index of the source datum in the input array. */
+  readonly datumIndex: number;
+}
+type StackOffset = "zero" | "expand" | "silhouette" | "wiggle";
+type StackOrder = "input" | "ascending" | "descending" | "inside-out" | "appearance";
+interface StackOptions<T, K extends string = string> {
+  /**
+   * Extract the numeric value for `key` from `datum`. Default: `datum[key]` —
+   * works when the data is a plain object keyed by string.
+   */
+  value?: (datum: T, key: K, datumIndex: number) => number;
+  /**
+   * Baseline offset:
+   * - `"zero"` (default) — bases at 0 going up.
+   * - `"expand"` — normalize each datum to `[0, 1]` (100% stacked).
+   * - `"silhouette"` — center the stack on 0 (`-rowSum/2 .. +rowSum/2`).
+   * - `"wiggle"` — minimize layer wiggle (Byron–Wattenberg streamgraph).
+   */
+  offset?: StackOffset;
+  /**
+   * Series ordering. Reorders the stack from inner-out:
+   * - `"input"` (default) — preserve `keys` order.
+   * - `"ascending"` — smallest total first.
+   * - `"descending"` — largest total first.
+   * - `"inside-out"` — largest in the middle (good for streamgraphs).
+   * - `"appearance"` — by index of each series' max value.
+   */
+  order?: StackOrder;
+}
+/**
+ * Flatten `data` into a list of `StackSegment`s — one per (datum, key) pair —
+ * with cumulative `base` / `top` offsets computed per datum. Supports
+ * `offset` (zero / expand / silhouette / wiggle) and `order` (input /
+ * ascending / descending / inside-out / appearance).
+ *
+ * Output order is `data[0].keys[0], data[0].keys[1], ..., data[1].keys[0],
+ * ...` — convenient for `barMark` / `areaMark`. `subIndex` reflects the
+ * post-`order` stacking position (0 = inner-most).
+ */
+declare function stack<T, K extends string = string>(data: readonly T[], keys: readonly K[], options?: StackOptions<T, K>): StackSegment<T, K>[];
+//#endregion
+//#region src/marks.d.ts
+interface MarkOrigin {
+  x?: number;
+  y?: number;
+}
+interface MarkBuilder {
+  addTo(layer: Layer, origin?: MarkOrigin): Layer;
+  readonly length: number;
+}
+type Accessor<T, V> = (datum: T, index: number) => V;
+type ValueOrAccessor<T, V> = V | Accessor<T, V>;
+/**
+ * Discrete marker glyphs for `pointMark`. The first four are filled solids;
+ * the `-open` variants render the same outline with no fill (caller must
+ * supply a stroke). `cross`, `plus`, and `star` are filled glyphs whose
+ * "arm" thickness scales with `radius`.
+ */
+type PointShapeKind = "circle" | "square" | "triangle" | "diamond" | "circle-open" | "square-open" | "triangle-open" | "diamond-open" | "cross" | "plus" | "star";
+/**
+ * Border treatment applied orthogonally to a point's shape kind.
+ *
+ * - `"solid"` (default): existing behavior — fill + optional solid stroke.
+ * - `"open"`: fill is suppressed; stroke uses `stroke ?? fill` as the color
+ *   (equivalent to the `-open` shape variants, but composable with any kind).
+ * - `"dashed"` / `"dotted"`: fill is kept; the stroke is rendered as a polyline
+ *   ring with a dash pattern. Required because SDF strokes don't support
+ *   per-shape dashes; this routes the border through `tessellatePolyline`.
+ */
+type PointBorderStyle = "solid" | "dashed" | "dotted" | "open";
+/** Line-stroke dash treatment. Maps to polyline `dashPattern`. */
+type LineDashStyle = "solid" | "dashed" | "dotted";
+/** Default dash pattern emitted for `"dashed"` border/line styles. */
+declare const DASHED_PATTERN: readonly number[];
+/** Default dash pattern emitted for `"dotted"` border/line styles. */
+declare const DOTTED_PATTERN: readonly number[];
+interface PointMarkOptions<T> {
+  x: Accessor<T, number>;
+  y: Accessor<T, number>;
+  radius?: ValueOrAccessor<T, number>;
+  fill?: ValueOrAccessor<T, Color>;
+  stroke?: ValueOrAccessor<T, Color>;
+  strokeWidth?: ValueOrAccessor<T, number>;
+  shape?: ValueOrAccessor<T, PointShapeKind>;
+  /**
+   * Per-datum border treatment (`"solid"` | `"dashed"` | `"dotted"` | `"open"`).
+   * Composes with any shape kind; e.g. `shape: "circle", borderStyle: "open"`
+   * is equivalent to `shape: "circle-open"`. Dashed/dotted borders bypass the
+   * SDF shader (which has no dash support) and route through a polyline ring.
+   */
+  borderStyle?: ValueOrAccessor<T, PointBorderStyle>;
+  /**
+   * Optional secondary glyph drawn on top of the base shape at the same anchor.
+   * Pass `null` to skip overlay for a specific datum. The overlay's radius is
+   * `radius * overlayScale`; its color falls back to the base stroke (or fill
+   * if no stroke) so badges contrast against the base shape.
+   */
+  overlayGlyph?: ValueOrAccessor<T, PointShapeKind | null>;
+  /** Overlay radius as a fraction of the base radius. Default `0.6`. */
+  overlayScale?: ValueOrAccessor<T, number>;
+  /**
+   * Per-datum GPU emphasis key (P5-T3) applied to every primitive a point emits
+   * (base shape + overlay glyph). Used by boxplot/violin point overlays + mean
+   * markers to tag a whole entity's dots with the entity's key. `undefined` →
+   * untagged (no dim).
+   */
+  emphasisKey?: Accessor<T, number | undefined>;
+  group?: Group;
+}
+declare function pointMark<T>(data: readonly T[], options: PointMarkOptions<T>): MarkBuilder;
+interface LineMarkOptions<T> {
+  x: Accessor<T, number>;
+  y: Accessor<T, number>;
+  stroke?: Color;
+  strokeWidth?: number;
+  curve?: LineCurve;
+  /** Resample density for smooth curves (`monotone-x`, `basis`). Default `16`. */
+  curveSamples?: number;
+  cap?: LineCap;
+  join?: LineJoin;
+  dashPattern?: readonly number[];
+  dashOffset?: number;
+  /**
+   * Categorical dash treatment. `"solid"` (default) leaves the stroke as a
+   * continuous line; `"dashed"` and `"dotted"` map to default dash patterns.
+   * `dashPattern` takes precedence when both are supplied.
+   */
+  dashStyle?: LineDashStyle;
+  defined?: Accessor<T, boolean>;
+  /**
+   * GPU emphasis key (P5-T3) applied to every polyline segment of this line.
+   * A whole line/series shares one key so it dims/un-dims together. `undefined`
+   * → untagged (no dim).
+   */
+  emphasisKey?: number;
+  group?: Group;
+}
+declare function lineMark<T>(data: readonly T[], options: LineMarkOptions<T>): MarkBuilder;
+interface AreaMarkOptions<T> {
+  x: Accessor<T, number>;
+  y0: Accessor<T, number>;
+  y1: Accessor<T, number>;
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  defined?: Accessor<T, boolean>;
+  group?: Group;
+}
+declare function areaMark<T>(data: readonly T[], options: AreaMarkOptions<T>): MarkBuilder;
+/**
+ * Bar border treatment — shared between `barMark`, `categoricalBarMark`,
+ * `stackedBarMark`, and `groupedBarMark`. Same routing as point borders:
+ * `"open"` suppresses fill; `"dashed"` / `"dotted"` emit a polyline ring
+ * around the rect because SDF rect strokes have no native dash support.
+ */
+type BarBorderStyle = "solid" | "dashed" | "dotted" | "open";
+interface BarMarkOptions<T> {
+  x: Accessor<T, number>;
+  y: Accessor<T, number>;
+  width: ValueOrAccessor<T, number>;
+  height: ValueOrAccessor<T, number>;
+  fill?: ValueOrAccessor<T, Color>;
+  stroke?: ValueOrAccessor<T, Color>;
+  strokeWidth?: ValueOrAccessor<T, number>;
+  cornerRadius?: ValueOrAccessor<T, number>;
+  rotation?: ValueOrAccessor<T, number>;
+  /** Per-datum border treatment. See {@link BarBorderStyle}. */
+  borderStyle?: ValueOrAccessor<T, BarBorderStyle>;
+  group?: Group;
+}
+declare function barMark<T>(data: readonly T[], options: BarMarkOptions<T>): MarkBuilder;
+type BarOrientation = "y" | "x";
+interface CategoricalBarMarkOptions<T, C> {
+  /**
+   * `"y"` (default) → vertical bars, value mapped to height.
+   * `"x"` → horizontal bars, value mapped to width.
+   */
+  orientation?: BarOrientation;
+  category: Accessor<T, C>;
+  value: Accessor<T, number>;
+  /** Band scale resolving categories to one of the layer's axes. */
+  categoryScale: BandScale<C>;
+  /** Continuous scale resolving values to the perpendicular axis. */
+  valueScale: ContinuousScale;
+  /** Baseline value (in domain units). Default `0`. */
+  baseline?: number;
+  fill?: ValueOrAccessor<T, Color>;
+  stroke?: ValueOrAccessor<T, Color>;
+  strokeWidth?: ValueOrAccessor<T, number>;
+  cornerRadius?: ValueOrAccessor<T, number>;
+  /** Per-datum border treatment. See {@link BarBorderStyle}. */
+  borderStyle?: ValueOrAccessor<T, BarBorderStyle>;
+  /** Per-datum GPU emphasis key (P5-T3). `undefined` → untagged (no dim). */
+  emphasisKey?: Accessor<T, number | undefined>;
+  group?: Group;
+}
+declare function categoricalBarMark<T, C>(data: readonly T[], options: CategoricalBarMarkOptions<T, C>): MarkBuilder;
+interface StackedBarMarkOptions<T, C, K extends string> {
+  orientation?: BarOrientation;
+  category: Accessor<T, C>;
+  categoryScale: BandScale<C>;
+  valueScale: ContinuousScale;
+  /** Per-segment fill — typically `colorScale(palette, keys)` (a function of `K`). */
+  color: (key: K, segment: StackSegment<T, K>) => Color;
+  offset?: StackOffset;
+  order?: StackOrder;
+  value?: (datum: T, key: K, datumIndex: number) => number;
+  cornerRadius?: number;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Border treatment shared across every segment. See {@link BarBorderStyle}. */
+  borderStyle?: BarBorderStyle;
+  /** Per-segment GPU emphasis key (P5-T3). `undefined` → untagged (no dim). */
+  emphasisKey?: (key: K, segment: StackSegment<T, K>) => number | undefined;
+  group?: Group;
+}
+interface StackedMarkBuilder<T, K extends string> extends MarkBuilder {
+  /** Per-(datum, key) layout segments — useful for `valueLabelMark` over totals. */
+  readonly segments: readonly StackSegment<T, K>[];
+}
+declare function stackedBarMark<T, C, K extends string>(data: readonly T[], keys: readonly K[], options: StackedBarMarkOptions<T, C, K>): StackedMarkBuilder<T, K>;
+interface GroupedBarMarkOptions<T, C, K extends string> {
+  orientation?: BarOrientation;
+  category: Accessor<T, C>;
+  groupedScale: GroupedBandScale<C, K>;
+  valueScale: ContinuousScale;
+  /** Per-key fill — typically `colorScale(palette, keys)`. */
+  color: (key: K) => Color;
+  /** Per-(datum, key) value resolver. Default `datum[key]`. */
+  value?: (datum: T, key: K, datumIndex: number) => number;
+  /** Domain-space baseline. Default `0`. */
+  baseline?: number;
+  cornerRadius?: number;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Border treatment shared across every bar in the grouped layout. */
+  borderStyle?: BarBorderStyle;
+  /** Per-(datum, key) GPU emphasis key (P5-T3). `undefined` → untagged. */
+  emphasisKey?: (datum: T, key: K, datumIndex: number) => number | undefined;
+  group?: Group;
+}
+declare function groupedBarMark<T, C, K extends string>(data: readonly T[], options: GroupedBarMarkOptions<T, C, K>): MarkBuilder;
+interface StackedAreaMarkOptions<T, K extends string> {
+  /** Continuous x position resolver — already in layer-space pixels. */
+  x: Accessor<T, number>;
+  /** Continuous scale that maps stack base/top values to layer-space pixels. */
+  valueScale: ContinuousScale;
+  /** Per-series fill. */
+  color: (key: K) => Color;
+  offset?: StackOffset;
+  order?: StackOrder;
+  value?: (datum: T, key: K, datumIndex: number) => number;
+  defined?: Accessor<T, boolean>;
+  stroke?: Color;
+  strokeWidth?: number;
+  group?: Group;
+}
+declare function stackedAreaMark<T, K extends string>(data: readonly T[], keys: readonly K[], options: StackedAreaMarkOptions<T, K>): StackedMarkBuilder<T, K>;
+//#endregion
+//#region src/annotations.d.ts
+type RuleAnchor = "start" | "middle" | "end";
+interface RuleStyle {
+  stroke?: Color;
+  strokeWidth?: number;
+  dashPattern?: readonly number[];
+  dashOffset?: number;
+}
+interface RuleLabel {
+  label?: string;
+  /** Where the label sits along the rule. Default `"end"`. */
+  labelAnchor?: RuleAnchor;
+  /** Perpendicular offset from the rule (positive = away from the data). Default `6`. */
+  labelOffset?: number;
+  /** Tangential offset from the chosen anchor (positive = inwards). Default `6`. */
+  labelInset?: number;
+  labelColor?: Color;
+  fontSize?: number;
+  fontStyle?: string;
+}
+interface HorizontalRuleOptions extends RuleStyle, RuleLabel {
+  /** Value (in layer-space pixels, post-scale) of the horizontal rule. */
+  y: number;
+  x?: never;
+  /** Range of x covered. Required — typically `[0, plot.width]`. */
+  extent: readonly [number, number];
+  group?: Group;
+}
+interface VerticalRuleOptions extends RuleStyle, RuleLabel {
+  /** Value (in layer-space pixels, post-scale) of the vertical rule. */
+  x: number;
+  y?: never;
+  /** Range of y covered. Required — typically `[0, plot.height]`. */
+  extent: readonly [number, number];
+  group?: Group;
+}
+type RuleMarkOptions = HorizontalRuleOptions | VerticalRuleOptions;
+declare function ruleMark(options: RuleMarkOptions): MarkBuilder;
+interface BandStyle {
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Draw the two perpendicular edge lines (uses `stroke`). Default `true` when `stroke` set. */
+  edges?: boolean;
+}
+interface BandLabel {
+  label?: string;
+  /** Where the label sits along the band. Default `"middle"`. */
+  labelAnchor?: RuleAnchor;
+  /** Perpendicular offset into the perpendicular extent (positive = inwards). Default `4`. */
+  labelOffset?: number;
+  labelColor?: Color;
+  fontSize?: number;
+  fontStyle?: string;
+}
+interface VerticalBandOptions extends BandStyle, BandLabel {
+  /** Range along the x axis (vertical band — fills between x0 and x1). */
+  x: readonly [number, number];
+  y?: never;
+  /** Required perpendicular extent (typically `[0, plot.height]`). */
+  extent: readonly [number, number];
+  group?: Group;
+}
+interface HorizontalBandOptions extends BandStyle, BandLabel {
+  /** Range along the y axis (horizontal band). */
+  y: readonly [number, number];
+  x?: never;
+  /** Required perpendicular extent (typically `[0, plot.width]`). */
+  extent: readonly [number, number];
+  group?: Group;
+}
+type BandMarkOptions = VerticalBandOptions | HorizontalBandOptions;
+declare function bandMark(options: BandMarkOptions): MarkBuilder;
+type ValueLabelAlign = "left" | "center" | "right";
+/**
+ * Optional rounded-rectangle background drawn behind label text. When set
+ * (and an `atlas` is available for measurement), `valueLabelMark` measures
+ * each label and emits a `pushRect` underneath sized to the text bounds plus
+ * `padding`. The rect's anchor matches the label's `align` so the text stays
+ * visually centered on `(x, y) + offset`.
+ */
+interface LabelBoxStyle {
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Pixels added on each side. Number = uniform; object = per-edge. Default `4`. */
+  padding?: number | {
+    x?: number;
+    y?: number;
+  };
+  cornerRadius?: number;
+}
+interface ValueLabelMarkOptions<T> {
+  x: Accessor<T, number>;
+  y: Accessor<T, number>;
+  text: Accessor<T, string>;
+  /** Horizontal anchor of the text relative to (`x`,`y`). Default `"center"`. */
+  align?: ValueLabelAlign;
+  /** Pixel offset from (`x`,`y`). Default `{ x: 0, y: -4 }` (above). */
+  offset?: {
+    x?: number;
+    y?: number;
+  };
+  color?: ValueOrAccessor<T, Color>;
+  fontSize?: number;
+  fontStyle?: string;
+  /** Skip labels for which this returns false. */
+  filter?: Accessor<T, boolean>;
+  /** Optional rounded-rect background. */
+  box?: LabelBoxStyle;
+  /**
+   * Glyph atlas used to measure each label's true rendered width and height
+   * for `box` sizing. When omitted the box falls back to a coarse character-
+   * width estimate that visibly mismatches the glyphs at small font sizes.
+   */
+  atlas?: GlyphAtlas;
+  group?: Group;
+}
+declare function valueLabelMark<T>(data: readonly T[], options: ValueLabelMarkOptions<T>): MarkBuilder;
+//#endregion
+//#region src/layout/box.d.ts
+interface MeasuredBox {
+  width: number;
+  height: number;
+}
+interface BoxOrigin {
+  x: number;
+  y: number;
+}
+/**
+ * A measure-then-place rectangle. Implementations must return a stable
+ * `measure()` (called by parents to size themselves) and an `addTo` that
+ * draws into a layer at the given top-left.
+ */
+interface Placeable {
+  measure(): MeasuredBox;
+  addTo(layer: Layer, origin: BoxOrigin): void;
+}
+//#endregion
+//#region src/legend.d.ts
+interface PointSwatchSpec {
+  kind: "point";
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  shape?: PointShapeKind;
+  /** Default `5`. */
+  radius?: number;
+  /** Per-shape border treatment — matches the mark side. Default `"solid"`. */
+  borderStyle?: PointBorderStyle;
+  /** Optional secondary glyph drawn on the same anchor. `null`/undefined = none. */
+  overlayGlyph?: PointShapeKind | null;
+  /** Overlay radius as a fraction of `radius`. Default `0.6`. */
+  overlayScale?: number;
+}
+interface LineSwatchSpec {
+  kind: "line";
+  stroke: Color;
+  strokeWidth?: number;
+  dashPattern?: readonly number[];
+  /** Default `18`. */
+  width?: number;
+}
+interface BarSwatchSpec {
+  kind: "bar";
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  cornerRadius?: number;
+  /** Default `12`. */
+  size?: number;
+}
+interface AreaSwatchSpec {
+  kind: "area";
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Default `14` (slight rectangle, not a square). */
+  width?: number;
+  /** Default `8`. */
+  height?: number;
+}
+type SwatchSpec = PointSwatchSpec | LineSwatchSpec | BarSwatchSpec | AreaSwatchSpec;
+declare function pointSwatch(opts: Omit<PointSwatchSpec, "kind">): PointSwatchSpec;
+declare function lineSwatch(opts: Omit<LineSwatchSpec, "kind">): LineSwatchSpec;
+declare function barSwatch(opts: Omit<BarSwatchSpec, "kind">): BarSwatchSpec;
+declare function areaSwatch(opts: Omit<AreaSwatchSpec, "kind">): AreaSwatchSpec;
+interface LegendEntry {
+  label: string;
+  swatch: SwatchSpec;
+  /** Optional hint for interactivity layers to render the entry as "off". */
+  hidden?: boolean;
+}
+type LegendOrientation = "horizontal" | "vertical";
+type LegendAlign = "start" | "end";
+interface LegendOptions {
+  atlas: GlyphAtlas;
+  orientation?: LegendOrientation;
+  /** Anchor inside the layout box. Default `"start"` (left/top edge of box). */
+  align?: LegendAlign;
+  fontSize?: number;
+  fontStyle?: string;
+  labelColor?: Color;
+  /** Pixel gap between swatch and label. Default `6`. */
+  swatchGap?: number;
+  /** Pixel gap between entries. Default `14` (horizontal) or `4` (vertical). */
+  entryGap?: number;
+  /** Optional title rendered above the entries (left-aligned, bold). */
+  title?: string;
+  titleFontSize?: number;
+  titleColor?: Color;
+  /** Pixel gap between title and entries. Default `4`. */
+  titleGap?: number;
+  /** Alpha for hidden entries. Default `0.2`. */
+  dimAlpha?: number;
+  group?: Group;
+}
+interface LegendBuilder extends Placeable {
+  /** Number of entries (or, for color bars, palette samples). */
+  readonly length: number;
+  /** Total laid-out width and height in layer-space pixels. */
+  measure(): {
+    width: number;
+    height: number;
+  };
+  /** Bounding boxes of each entry, relative to the legend's top-left. */
+  getEntryBboxes(): (FrameRect & {
+    label: string;
+  })[];
+}
+/**
+ * Lay out a row (or column) of swatch + label pairs. Each mark contributes
+ * its own swatch shape via the `*Swatch(...)` helpers, so a dashed line shows
+ * a dashed swatch, a triangle point shows a triangle, etc.
+ *
+ * The legend is positioned by `origin` when added: `origin` is the *top-left*
+ * of the layout box. To right-align, measure first then offset:
+ *
+ * ```ts
+ * const lg = legend(entries, { atlas: a });
+ * const { width } = lg.measure();
+ * lg.addTo(layer, { x: outer.x + outer.width - width, y: outer.y });
+ * ```
+ */
+declare function legend(entries: readonly LegendEntry[], options: LegendOptions): LegendBuilder;
+//#endregion
+//#region src/colors.d.ts
+interface ContinuousPalette {
+  (t: number): Color;
+  readonly kind: "continuous";
+  readonly stops: readonly Color[];
+  /** Color space used to interpolate between adjacent stops. */
+  readonly blendSpace: BlendSpace;
+  /**
+   * Return a new palette with the same stops but interpolating in the given
+   * space. The original is unchanged. Cheap — palettes are stateless.
+   */
+  withBlendSpace(space: BlendSpace): ContinuousPalette;
+}
+interface CategoricalPalette {
+  (index: number): Color;
+  readonly kind: "categorical";
+  readonly colors: readonly Color[];
+}
+declare function colorScale(palette: ContinuousPalette, domain: readonly [number, number]): (value: number) => Color;
+declare function colorScale<Domain>(palette: CategoricalPalette, domain: readonly Domain[]): (value: Domain) => Color;
+declare const viridis: ContinuousPalette;
+declare const plasma: ContinuousPalette;
+declare const inferno: ContinuousPalette;
+declare const magma: ContinuousPalette;
+declare const cividis: ContinuousPalette;
+declare const coolwarm: ContinuousPalette;
+declare const rdbu: ContinuousPalette;
+declare const spectral: ContinuousPalette;
+declare const tableau10: CategoricalPalette;
+declare const category10: CategoricalPalette;
+declare const pastel: CategoricalPalette;
+declare const set1: CategoricalPalette;
+declare const set2: CategoricalPalette;
+declare const set3: CategoricalPalette;
+declare const dark2: CategoricalPalette;
+declare const accent: CategoricalPalette;
+declare const paired: CategoricalPalette;
+declare const blues: ContinuousPalette;
+declare const greens: ContinuousPalette;
+declare const oranges: ContinuousPalette;
+declare const reds: ContinuousPalette;
+declare const purples: ContinuousPalette;
+declare const greys: ContinuousPalette;
+declare const brbg: ContinuousPalette;
+declare const prgn: ContinuousPalette;
+declare const piyg: ContinuousPalette;
+declare const puor: ContinuousPalette;
+/**
+ * Build a continuous palette from an arbitrary list of CSS hex stops.
+ * Stops are evenly spaced; sample with `palette(t)` where `t ∈ [0, 1]`.
+ */
+declare function continuousPalette(hexStops: readonly string[]): ContinuousPalette;
+/**
+ * Build a categorical palette from an arbitrary list of CSS hex colors.
+ * Indices wrap modulo length, so `palette(N)` always returns a valid color.
+ */
+declare function categoricalPalette(hexColors: readonly string[]): CategoricalPalette;
+//#endregion
+//#region src/viewport/axis-state.d.ts
+interface ContinuousAxisConfig {
+  type: "linear" | "log" | "sqrt";
+  domain: NumericDomain;
+}
+interface TimeAxisConfig {
+  type: "time";
+  domain: DateDomain;
+}
+interface BandAxisConfig<T = unknown> extends BandScaleOptions {
+  type: "band";
+  domain: readonly T[];
+}
+type ViewportAxisConfig<T = unknown> = ContinuousAxisConfig | TimeAxisConfig | BandAxisConfig<T>;
+type VisibleDomainInput = readonly [number, number] | readonly [Date, Date];
+interface Transform {
+  to: (v: number) => number;
+  from: (v: number) => number;
+}
+interface ContinuousAxisState {
+  kind: "continuous";
+  type: "linear" | "log" | "sqrt" | "time";
+  transform: Transform;
+  t0: number;
+  t1: number;
+  baseT0: number;
+  baseT1: number;
+  r0: number;
+  r1: number;
+  /**
+   * Memoized scale instance for the current (t0, t1, r0, r1, type, transform)
+   * tuple. Null after construction and after any mutation; populated lazily by
+   * `buildScale` / `applyAxis`. Pan/zoom/setVisibleDomain/clampAxisToBase/
+   * resetAxis/setAxisRange/copyContinuous all clear it via `invalidateScale`.
+   */
+  scaleCache: ContinuousScale | TimeScale | null;
+}
+interface BandAxisState<T> {
+  kind: "band";
+  domain: readonly T[];
+  options: BandScaleOptions;
+  r0: number;
+  r1: number;
+  /** See `ContinuousAxisState.scaleCache`. */
+  scaleCache: BandScale<T> | null;
+}
+type AxisState<T> = ContinuousAxisState | BandAxisState<T>;
+//#endregion
+//#region src/viewport.d.ts
+/**
+ * Per-axis margin spec. A bare number applies to both axes. Values are
+ * fractions of the *visible* span and apply symmetrically to both edges.
+ */
+type PanBoundsMargin = number | {
+  x?: number;
+  y?: number;
+};
+interface PanBoundsMargins {
+  /** Pan-past-content allowance when content is larger than the viewport. */
+  overshoot?: PanBoundsMargin;
+  /** Content drift allowance when content fits inside the viewport. */
+  drift?: PanBoundsMargin;
+}
+interface DataPanBoundsOptions extends PanBoundsMargins {}
+interface DataViewportOptions<X = unknown, Y = unknown> {
+  /** Frame in pixel space (relative to parent if `parent` is supplied). */
+  frame: Frame;
+  /** Optional parent viewport — `frame` is interpreted in the parent's space. */
+  parent?: ViewportLike;
+  x: ViewportAxisConfig<X>;
+  y: ViewportAxisConfig<Y>;
+  /** Minimum domain-span multiplier (relative to base). Default: 0.001 */
+  minZoom?: number;
+  /** Maximum domain-span multiplier (relative to base). Default: 1000 */
+  maxZoom?: number;
+  /**
+   * Pan-bound the visible domain to the axis base domain (the initial domain
+   * passed in `x` / `y`). When zoomed in, panning stops at content edges
+   * (plus margin); when zoomed out far enough that content fits in view,
+   * the viewport cannot pan content off-screen. Zoom itself remains
+   * unrestricted past content — this only governs pan position.
+   */
+  panBounds?: DataPanBoundsOptions;
+}
+type ZoomFactor = number | {
+  x?: number;
+  y?: number;
+};
+interface LinearProjector {
+  /** sx = worldX * txSlope + txConst */
+  readonly txSlope: number;
+  readonly txConst: number;
+  /** sy = worldY * tySlope + tyConst */
+  readonly tySlope: number;
+  readonly tyConst: number;
+}
+interface DataViewport<X = unknown, Y = unknown> {
+  readonly mode: "data";
+  /** Frame relative to `parent` (or absolute if no parent). */
+  readonly frame: Frame;
+  /** Frame in root / canvas space — walks the parent chain on each read. */
+  readonly absoluteFrame: Frame;
+  /** Parent viewport, if this is a nested viewport. */
+  readonly parent: ViewportLike | null;
+  /** Mutable rect equal to `absoluteFrame`, refreshed in place on each access. */
+  readonly clipRect: FrameRect;
+  /** Identity camera (data-mode pan/zoom flows through axis scales). */
+  readonly camera: ResolvedCameraState;
+  readonly x: AxisScale<X>;
+  readonly y: AxisScale<Y>;
+  readonly visibleXDomain: NumericDomain | DateDomain | readonly X[];
+  readonly visibleYDomain: NumericDomain | DateDomain | readonly Y[];
+  /** Pan by pixel deltas in this viewport's frame space. */
+  panBy(dxPx: number, dyPx: number): void;
+  /** Zoom around a screen-pixel anchor in the viewport's absolute frame space. */
+  zoomAt(anchorSx: number, anchorSy: number, factor: ZoomFactor): void;
+  /** Reset to initial domain. */
+  reset(): void;
+  /**
+   * Replace the frame (in the same space as the original frame).
+   *
+   * `reserve` (CSS-px insets) shrinks the axis pixel range without changing
+   * the visible frame extent or `clipRect`. This is how the chart pipeline
+   * tells the viewport about position-scale range reservations
+   * (`framePadding` + per-geom `prepareRange`) so `dataToScreen` matches
+   * where marks actually render. Defaults to zero insets — callers that
+   * don't reserve any space (test viewports, manual mounts) can omit it.
+   */
+  setFrame(frame: Frame, reserve?: AxisRangeReserve): void;
+  /** Convert a screen pixel to data coords. Returns null if outside the absolute frame. */
+  screenToData(sx: number, sy: number): {
+    x: X;
+    y: Y;
+  } | null;
+  /** Convert data coords to screen pixels (absolute). */
+  dataToScreen(dx: X, dy: Y): Vec2;
+  /**
+   * If both axes are linear continuous (not log, not time, not band), return a
+   * pre-computed slope+intercept projector for use in hot loops. Returns null
+   * for mixed or non-linear axis configurations. Recompute once per project
+   * call; do not call per-entry.
+   */
+  getLinearProjector(): LinearProjector | null;
+  /** Set the visible domain absolutely on one or both continuous axes. */
+  setVisibleDomain(domains: {
+    x?: VisibleDomainInput;
+    y?: VisibleDomainInput;
+  }): void;
+  /** Replace the pan-bound config (or clear it with `null`). */
+  setPanBounds(options: DataPanBoundsOptions | null): void;
+  /** Subscribe to any view-state change. */
+  onChange(cb: () => void): () => void;
+  /** @internal */
+  _state: DataInternal;
+}
+/** Anything that can be linked together — `linkViewports` ignores camera viewports. */
+type Viewport<X = unknown, Y = unknown> = DataViewport<X, Y> | CameraViewport;
+interface MutableFrameRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+interface ResolvedAxisMargin {
+  x: number;
+  y: number;
+}
+interface ResolvedMargins {
+  overshoot: ResolvedAxisMargin;
+  drift: ResolvedAxisMargin;
+}
+interface DataInternal {
+  mode: "data";
+  frame: Frame;
+  parent: ViewportLike | null;
+  listeners: Set<() => void>;
+  notifying: boolean;
+  clipRect: MutableFrameRect;
+  xAxis: AxisState<unknown>;
+  yAxis: AxisState<unknown>;
+  minZoom: number;
+  maxZoom: number;
+  panBoundsMargins: ResolvedMargins | null;
+  rangeReserve: AxisRangeReserve;
+}
+/**
+ * CSS-px insets that shrink the axis pixel range without changing the frame
+ * extent. Mirrors the chart pipeline's `framePadding` + per-geom
+ * `prepareRange` reservations so `dataToScreen` lines up with where marks
+ * actually render.
+ */
+interface AxisRangeReserve {
+  readonly left: number;
+  readonly right: number;
+  readonly top: number;
+  readonly bottom: number;
+}
+declare function createDataViewport<X = unknown, Y = unknown>(options: DataViewportOptions<X, Y>): DataViewport<X, Y>;
+interface LinkViewportsOptions {
+  /** Sync X axis state. Default: true. */
+  x?: boolean;
+  /** Sync Y axis state. Default: false. */
+  y?: boolean;
+}
+/**
+ * Keep multiple data viewports in sync on selected axes. Camera viewports in
+ * the array are skipped (link only makes sense between like-typed data axes).
+ *
+ * Any pan/zoom/reset on one data viewport propagates the current transformed-
+ * domain endpoints to the others on the linked axes. Requires linked axes to
+ * have matching `type` (e.g. both `linear`, or both `time`).
+ */
+declare function linkViewports(viewports: readonly Viewport<any, any>[], options?: LinkViewportsOptions): () => void;
+//#endregion
+//#region src/stats/regression.d.ts
+/**
+ * A fitted regression. `predict(x)` returns the mean-response estimate;
+ * `seMean(x)` returns the standard error of that estimate (for confidence
+ * bands). `summary` carries whatever fit-specific scalars are interesting
+ * (slope, intercept, coefs, r²) — exposed for callers that want to render
+ * an equation or stat label.
+ */
+interface RegressionFit {
+  readonly n: number;
+  predict(x: number): number;
+  /** Standard error of the mean response at `x`. Returns 0 when undefined. */
+  seMean(x: number): number;
+  readonly residualStdError: number;
+  readonly summary: Readonly<Record<string, number | readonly number[]>>;
+}
+declare function linearFit(xs: readonly number[], ys: readonly number[]): RegressionFit | null;
+declare function polyFit(xs: readonly number[], ys: readonly number[], degree: number): RegressionFit | null;
+interface LoessOptions {
+  /** Fraction of the sample used in each local fit. Default `0.5`. */
+  span?: number;
+  /** Degree of local polynomial: `1` (default) or `2`. */
+  degree?: 1 | 2;
+}
+declare function loessFit(xs: readonly number[], ys: readonly number[], options?: LoessOptions): RegressionFit | null;
+interface ConfidenceBandPoint {
+  x: number;
+  yhat: number;
+  lo: number;
+  hi: number;
+}
+interface ConfidenceBandOptions {
+  samples?: number;
+  /** Confidence level. Default `0.95`. */
+  level?: number;
+  /** Override `[xmin, xmax]`. Defaults to data range. */
+  domain?: readonly [number, number];
+}
+declare function confidenceBand(fit: RegressionFit, xs: readonly number[], options?: ConfidenceBandOptions): ConfidenceBandPoint[];
+//#endregion
+//#region src/stats/rolling-window.d.ts
+type RollingStatisticKind = "mean" | "median" | "min" | "max" | "sum" | "stddev";
+/**
+ * Statistic to compute over each window. Strings cover the common cases;
+ * `{ kind: 'quantile', p }` picks an arbitrary quantile (0..1); a function
+ * receives the windowed `(values, items)` and returns any scalar — use it for
+ * custom stats (mode, trimmed mean, sign of slope, …).
+ */
+type RollingStatistic<T> = RollingStatisticKind | {
+  kind: "quantile";
+  p: number;
+} | ((values: readonly number[], items: readonly T[]) => number);
+/**
+ * Window size.
+ *
+ * - A bare number is interpreted as `unit: 'count'` (k nearest items by axis
+ *   value, including self). Most predictable across axis types.
+ * - `{ value, unit: 'domain' }` — sliding window of `value` data-axis units,
+ *   centered on the current item. For a time axis pass milliseconds (e.g.
+ *   `7 * 24 * 3_600_000` for a 7-day window). For a numeric axis the value is
+ *   in the axis's own units.
+ * - `{ value, unit: 'count' }` — explicit count-window form.
+ */
+type RollingWindow = number | {
+  value: number;
+  unit: "domain" | "count";
+};
+type RollingAxis = "x" | "y";
+interface RollingWindowOptions<T> {
+  x: (datum: T, index: number) => number | Date;
+  y: (datum: T, index: number) => number;
+  window: RollingWindow;
+  /** Default `"mean"`. */
+  statistic?: RollingStatistic<T>;
+  /**
+   * Points failing the filter are excluded from every window *and* not
+   * emitted on the output series — they vanish from both the aggregation
+   * and the line that connects the results.
+   */
+  filter?: (datum: T, index: number) => boolean;
+  /**
+   * Axis the window slides along. Default `"x"` (slide on x, aggregate y);
+   * `"y"` flips (slide on y, aggregate x). Output is sorted by the slide
+   * axis so a `lineMark` connecting the points draws monotonically.
+   */
+  axis?: RollingAxis;
+}
+interface RollingPoint {
+  x: number;
+  y: number;
+  /** Index into the original input `data` array. */
+  sourceIndex: number;
+  /** Number of points (after filter) that fell in this window. */
+  count: number;
+}
+declare function rollingWindow<T>(data: readonly T[], options: RollingWindowOptions<T>): RollingPoint[];
+//#endregion
+//#region src/stats/index.d.ts
+type QuantileMethod = "type-7" | "type-1";
+/**
+ * Quantile of an already-sorted ascending numeric array.
+ *
+ * - `"type-7"` (default): R's default — linear interpolation between order
+ *   stats with `h = (n - 1) * p`. The quantile method most users expect.
+ * - `"type-1"`: inverse-of-empirical-CDF (step function). No interpolation.
+ *
+ * Returns `NaN` for empty input. Clamps `p` to `[0, 1]`.
+ */
+declare function quantile(sorted: readonly number[], p: number, method?: QuantileMethod): number;
+type WhiskerRule = number | "minmax";
+interface BoxStats {
+  /** Sample size (after filtering non-finite). */
+  n: number;
+  /** Smallest value in the sample. */
+  min: number;
+  /** Lower whisker endpoint (clamped to data range). */
+  lowerWhisker: number;
+  q1: number;
+  median: number;
+  q3: number;
+  /** Upper whisker endpoint (clamped to data range). */
+  upperWhisker: number;
+  /** Largest value in the sample. */
+  max: number;
+  /** Q3 − Q1. */
+  iqr: number;
+  /** Values strictly outside the whiskers. Order preserves input order. */
+  outliers: number[];
+  /** Mean of the sample. Useful as an annotation; not used for box geometry. */
+  mean: number;
+}
+interface BoxStatsOptions {
+  /**
+   * Whisker rule.
+   *
+   * - A number `k` (default `1.5`) — Tukey-style: whiskers extend to the most
+   *   extreme value within `k * IQR` of Q1/Q3. Anything beyond is an outlier.
+   * - `"minmax"` — whiskers extend to the data min/max; no outliers.
+   */
+  whisker?: WhiskerRule;
+  quantile?: QuantileMethod;
+}
+/**
+ * Compute Tukey-style box statistics. Filters non-finite inputs.
+ *
+ * Returns `null` for empty input — caller decides how to render `n=0`.
+ * For `n=1`, every quartile equals the single value and `outliers` is empty.
+ */
+declare function boxStats(values: readonly number[], options?: BoxStatsOptions): BoxStats | null;
+type KdeKernel = "gaussian" | "epanechnikov";
+type KdeBandwidth = number | "silverman" | "scott";
+interface KdeOptions {
+  /** Number of evaluation points. Default `64`, capped to `512`. */
+  gridSize?: number;
+  /**
+   * Either a positive number (fixed bandwidth in data units) or a rule:
+   * - `"silverman"` (default) — `1.06 · scale · n^(-1/5)` with the robust
+   *   scale `min(σ, IQR/1.34)`. Less sensitive to heavy tails / skew.
+   * - `"scott"` — `1.06 · σ · n^(-1/5)` using the plain standard deviation
+   *   (no IQR robustification). Wider on skewed/heavy-tailed samples.
+   */
+  bandwidth?: KdeBandwidth;
+  kernel?: KdeKernel;
+  /**
+   * Evaluate over `[min, max]` of the sample (`true`, default) or pad outward
+   * by ~3 bandwidths so density tails reach near-zero (`false`).
+   */
+  trim?: boolean;
+  /** Override the evaluation domain. Bypasses `trim`. */
+  domain?: readonly [number, number];
+}
+interface KdeResult {
+  /** Evaluation grid (length `gridSize`). */
+  x: number[];
+  /** Density at each grid point (length `gridSize`). */
+  y: number[];
+  /** Resolved bandwidth in data units. */
+  bandwidth: number;
+}
+/**
+ * Kernel density estimate.
+ *
+ * Returns `null` for empty input. For all-equal samples falls back to a tiny
+ * bandwidth so callers don't divide by zero — the result is a narrow spike.
+ */
+declare function kde(values: readonly number[], options?: KdeOptions): KdeResult | null;
+/**
+ * Group an iterable into a `Map` keyed by `key(item)`. Insertion order
+ * preserved per key; the map's key order is the order of first occurrence.
+ */
+declare function groupBy<T, K>(items: Iterable<T>, key: (item: T, index: number) => K): Map<K, T[]>;
+type BinRule = "sturges" | "scott" | "fd" | "rice";
+type BinClosed = "left" | "right";
+interface BinBreaksOptions {
+  /** Explicit bin count. Ignored if `binwidth` or `breaks` is set. */
+  bins?: number;
+  /** Explicit bin width in data units. Beats `bins` and `rule`. */
+  binwidth?: number;
+  /** Fully explicit edge array — bypasses rules entirely. */
+  breaks?: readonly number[];
+  /**
+   * Rule used to pick a bin count when neither `bins`, `binwidth`, nor
+   * `breaks` is provided.
+   *
+   * - `"sturges"` (default) — `⌈log₂ n⌉ + 1`. R / ggplot default.
+   * - `"rice"` — `⌈2 · n^(1/3)⌉`. Slightly higher resolution.
+   * - `"scott"` — `3.49 σ n^(-1/3)` width. Good for roughly normal data.
+   * - `"fd"` — Freedman-Diaconis `2 · IQR · n^(-1/3)` width. Robust on skew.
+   */
+  rule?: BinRule;
+  /** Clip edges to this. Default = `[min, max]` of data. */
+  domain?: readonly [number, number];
+  /** Round outer edges + step to nice numbers. Default `true`. */
+  nice?: boolean;
+}
+interface BinResult {
+  /** Inclusive lower edge for `closed: "left"` (the default). */
+  x0: number;
+  /** Exclusive upper edge for `closed: "left"`, except the final bin. */
+  x1: number;
+  /** Number of input values that fell in this bin. */
+  count: number;
+  /** `count / (n · width)`. Sums to 1 across all bins (∑ density · width). */
+  density: number;
+}
+/**
+ * How a histogram bin's `count` is converted into a y-axis value:
+ * - `"count"` / `"frequency"`: raw `count`
+ * - `"density"`: `count / (n · width)` — area sums to 1
+ * - `"proportion"`: `count / n` — values sum to 1
+ */
+type HistogramMeasure = "count" | "density" | "proportion" | "frequency";
+/**
+ * Convert a `BinResult` to its measured value under `measure`. `n` is the
+ * total sample count for the histogram (or per-group total for stacked /
+ * faceted cases) — used to normalise `density` and `proportion`.
+ */
+declare function histogramMeasureValue(bin: BinResult, n: number, measure: HistogramMeasure): number;
+interface BinOptions extends BinBreaksOptions {
+  /**
+   * Edge-closure convention. With `"left"` (default) bins are `[x0, x1)` and
+   * the final bin includes the max as `[x_{k-1}, x_k]`. With `"right"` the
+   * first bin is `[x_0, x_1]` and the rest are `(x_i, x_{i+1}]`.
+   */
+  closed?: BinClosed;
+}
+/**
+ * Compute bin edges for the given data. Returns an array of length
+ * `binCount + 1` describing the boundaries of each bin from left to right.
+ *
+ * Resolution order (highest precedence first): explicit `breaks` → `binwidth`
+ * → `bins` → `rule` (default `"sturges"`).
+ *
+ * Returns `[]` for empty / all-non-finite input.
+ */
+declare function binBreaks(values: readonly number[], options?: BinBreaksOptions): number[];
+/**
+ * Bin a numeric sample into a sorted array of `BinResult`. Filters non-finite.
+ *
+ * Bins are half-open `[x0, x1)` by default (`closed: "left"`); the last bin
+ * is closed on both ends so the maximum value is counted. With
+ * `closed: "right"` the first bin is closed on both ends and the rest are
+ * `(x0, x1]`.
+ *
+ * Values strictly outside the resolved domain are dropped.
+ */
+declare function bin(values: readonly number[], options?: BinOptions): BinResult[];
+/**
+ * Assign already-resolved values into known bin edges. Useful when the caller
+ * has computed `breaks` once across multiple groups (so per-group histograms
+ * align horizontally).
+ */
+declare function binWithBreaks(values: readonly number[], breaks: readonly number[], closed?: BinClosed): BinResult[];
+interface BinByOptions extends BinOptions {
+  /**
+   * Use one shared edge array for every group (default `true`) so per-group
+   * histograms align horizontally for stack/dodge/overlay. With `false`, each
+   * group computes its own breaks against its own data.
+   */
+  sharedBreaks?: boolean;
+}
+interface BinByResult<K> {
+  breaks: number[];
+  groups: Map<K, BinResult[]>;
+}
+/**
+ * Bin a flat numeric array partitioned by key. Group iteration order matches
+ * first-occurrence order in the input.
+ */
+declare function binBy<K>(values: readonly number[], keys: readonly K[], options?: BinByOptions): BinByResult<K>;
+/**
+ * Deterministic uniform jitter offsets in `[-width/2, +width/2]`. Same
+ * `(seed, count)` pair always produces the same sequence — important so that
+ * jittered overlay points don't dance between renders.
+ */
+declare function jitter(seed: number, count: number, width: number): number[];
+//#endregion
+//#region src/range-presets.d.ts
+/** Axis the controller drives. */
+type RangePresetAxis = "x" | "y";
+/**
+ * Resolved domain a preset applies to the viewport. Numeric pair for linear /
+ * log / score axes; Date pair for time axes.
+ */
+type RangePresetDomain = NumericDomain | DateDomain;
+/** Optional getter form for the data-extent fallback. */
+type RangePresetDataDomain = RangePresetDomain | (() => RangePresetDomain);
+/**
+ * Context passed to a preset's `resolve` function. `dataDomain` is the full
+ * extent of the underlying data (either provided by the consumer at
+ * construction time or, if omitted, the viewport's current visible domain
+ * sampled at construction). `now` is the current time (epoch ms) — relevant
+ * for time presets; helpers like `linearPreset` ignore it.
+ */
+interface RangePresetContext {
+  dataDomain: RangePresetDomain;
+  now: number;
+}
+/**
+ * A single preset entry. `resolve` returns the domain the viewport should be
+ * set to when the user activates this key. Return `null` to express "this
+ * preset has no valid domain given the current data" — the controller will
+ * leave the viewport untouched and not mark itself active.
+ */
+interface RangePreset {
+  key: string;
+  label: string;
+  resolve: (ctx: RangePresetContext) => RangePresetDomain | null;
+}
+interface RangePresetsOptions {
+  /**
+   * Any `DataViewport` regardless of axis-value type — accepts the
+   * `DataViewport<number, number>` returned by `MountedPlot.viewport` as
+   * well as the unparameterized form. The controller only reads visible
+   * domains and applies new ones through the viewport's continuous-axis
+   * API, so X/Y value types are not constrained at this layer.
+   */
+  viewport: DataViewport<any, any>;
+  axis: RangePresetAxis;
+  presets: readonly RangePreset[];
+  /**
+   * Full data extent. Either a fixed `[min, max]` (numbers or Dates) or a
+   * getter that re-reads on each preset evaluation. If omitted, the
+   * controller snapshots the viewport's current visible domain at
+   * construction time and reuses it as the data domain.
+   */
+  dataDomain?: RangePresetDataDomain;
+  /** Defaults to `Date.now`. Re-evaluated on every `setActive`. */
+  now?: () => number;
+  /**
+   * Relative tolerance for the diff-against-snapshot custom check. A change
+   * smaller than `epsilon * max(|a|, |b|, 1)` on either endpoint is ignored.
+   * Defaults to `1e-6` — tight enough to detect a one-pixel pan, loose
+   * enough to absorb float round-trips through the axis scale.
+   */
+  epsilon?: number;
+}
+/** Subscriber receives the new active key, or `null` for "custom". */
+type RangePresetsSubscriber = (active: string | null) => void;
+interface RangePresetsController {
+  readonly presets: readonly RangePreset[];
+  /**
+   * Activate a preset by key. Re-resolves the preset, applies the resulting
+   * domain to the viewport, and remembers the resolved snapshot so future
+   * `onChange` events can detect manual changes. Passing `null` clears the
+   * active state without touching the viewport.
+   */
+  setActive(key: string | null): void;
+  /** Currently active preset key, or `null` if user has panned/zoomed manually. */
+  getActive(): string | null;
+  /** Subscribe to active-state changes. Returns an unsubscribe fn. */
+  subscribe(fn: RangePresetsSubscriber): () => void;
+  dispose(): void;
+}
+declare function createRangePresets(opts: RangePresetsOptions): RangePresetsController;
+/**
+ * Recognized time-preset keys. Each maps to a window relative to `now`
+ * (except `MAX`, which uses the full data extent, and `YTD` which goes
+ * from January 1 of the current year to `now`).
+ */
+type TimePresetKey = "24H" | "7D" | "1M" | "3M" | "6M" | "1Y" | "YTD" | "MAX";
+/**
+ * Time-axis preset. Resolves to a `DateDomain` ending at `now` (or the data
+ * domain's end, for `MAX`). Built-in months use calendar-approximate
+ * constants (30/90/182/365 days) — close enough for chart UI.
+ */
+declare function timePreset(key: TimePresetKey, label?: string): RangePreset;
+/**
+ * Linear / numeric preset showing the last `span` units of `dataDomain` —
+ * i.e. `[max - span, max]`. Useful for "last 100m", "last 50 errors", etc.
+ * `MAX`-style behavior comes from passing `Infinity` (will clamp to the
+ * full data domain).
+ */
+declare function linearPreset(opts: {
+  key: string;
+  label: string;
+  span: number;
+}): RangePreset;
+/**
+ * Log-axis preset showing the last `decades` decades of the data — i.e.
+ * `[max / 10^decades, max]`, clamped to the data domain's lower bound.
+ * The viewport itself stays linear-or-log depending on its scale config;
+ * this helper just picks the domain endpoints.
+ */
+declare function logPreset(opts: {
+  key: string;
+  label: string;
+  decades: number;
+}): RangePreset;
+//#endregion
+export { polyFit as $, LineCurvePreset as $n, SwatchSpec as $t, binBreaks as A, MarkOrigin as An, groupedBandScale as Ar, pastel as At, RollingPoint as B, categoricalBarMark as Bn, set3 as Bt, KdeBandwidth as C, CategoricalBarMarkOptions as Cn, GroupedBandScaleOptions as Cr, dark2 as Ct, QuantileMethod as D, LineDashStyle as Dn, TimeIntervalUnit as Dr, magma as Dt, KdeResult as E, GroupedBarMarkOptions as En, TickFormatter as Er, inferno as Et, histogramMeasureValue as F, StackedBarMarkOptions as Fn, timeTickFormat as Fr, purples as Ft, rollingWindow as G, stackedBarMark as Gn, BarSwatchSpec as Gt, RollingStatisticKind as H, lineMark as Hn, tableau10 as Ht, jitter as I, StackedMarkBuilder as In, timeTicks as Ir, rdbu as It, LoessOptions as J, StackOrder as Jn, LegendEntry as Jt, ConfidenceBandOptions as K, StackOffset as Kn, LegendAlign as Kt, kde as L, ValueOrAccessor as Ln, reds as Lt, binWithBreaks as M, PointMarkOptions as Mn, logScale as Mr, plasma as Mt, boxStats as N, PointShapeKind as Nn, sqrtScale as Nr, prgn as Nt, WhiskerRule as O, LineMarkOptions as On, TimeScale as Or, oranges as Ot, groupBy as P, StackedAreaMarkOptions as Pn, timeScale as Pr, puor as Pt, loessFit as Q, LineCurve as Qn, PointSwatchSpec as Qt, quantile as R, areaMark as Rn, set1 as Rt, HistogramMeasure as S, BarOrientation as Sn, GroupedBandScale as Sr, coolwarm as St, KdeOptions as T, DOTTED_PATTERN as Tn, NumericRange as Tr, greys as Tt, RollingWindow as U, pointMark as Un, viridis as Ut, RollingStatistic as V, groupedBarMark as Vn, spectral as Vt, RollingWindowOptions as W, stackedAreaMark as Wn, AreaSwatchSpec as Wt, confidenceBand as X, stack as Xn, LegendOrientation as Xt, RegressionFit as Y, StackSegment as Yn, LegendOptions as Yt, linearFit as Z, CustomCurve as Zn, LineSwatchSpec as Zt, BinOptions as _, valueLabelMark as _n, AxisScale as _r, categoricalPalette as _t, RangePresetDomain as a, BandMarkOptions as an, AxisMeasurement as ar, createDataViewport as at, BoxStats as b, BarBorderStyle as bn, ContinuousScale as br, colorScale as bt, RangePresetsSubscriber as c, LabelBoxStyle as cn, AxisTickFormatter as cr, ContinuousAxisConfig as ct, linearPreset as d, ValueLabelAlign as dn, TickSpec as dr, VisibleDomainInput as dt, areaSwatch as en, cardinalCurve as er, DataPanBoundsOptions as et, logPreset as f, ValueLabelMarkOptions as fn, bottomAxis as fr, CategoricalPalette as ft, BinClosed as g, ruleMark as gn, truncateToWidth as gr, brbg as gt, BinByResult as h, bandMark as hn, topAxis as hr, blues as ht, RangePresetDataDomain as i, pointSwatch as in, AxisLabelConfig as ir, Viewport as it, binBy as j, PointBorderStyle as jn, linearScale as jr, piyg as jt, bin as k, MarkBuilder as kn, bandScale as kr, paired as kt, TimePresetKey as l, RuleAnchor as ln, AxisTitle as lr, TimeAxisConfig as lt, BinByOptions as m, VerticalRuleOptions as mn, rightAxis as mr, accent as mt, RangePresetAxis as n, legend as nn, resamplePoints as nr, DataViewportOptions as nt, RangePresetsController as o, HorizontalBandOptions as on, AxisOptions as or, linkViewports as ot, timePreset as p, VerticalBandOptions as pn, leftAxis as pr, ContinuousPalette as pt, ConfidenceBandPoint as q, StackOptions as qn, LegendBuilder as qt, RangePresetContext as r, lineSwatch as rn, AxisBuilder as rr, LinkViewportsOptions as rt, RangePresetsOptions as s, HorizontalRuleOptions as sn, AxisOrigin as sr, BandAxisConfig as st, RangePreset as t, barSwatch as tn, defineCurve as tr, DataViewport as tt, createRangePresets as u, RuleMarkOptions as un, TickIntervalSpec as ur, ViewportAxisConfig as ut, BinResult as v, Accessor as vn, BandScale as vr, category10 as vt, KdeKernel as w, DASHED_PATTERN as wn, NumericDomain as wr, greens as wt, BoxStatsOptions as x, BarMarkOptions as xn, DateDomain as xr, continuousPalette as xt, BinRule as y, AreaMarkOptions as yn, BandScaleOptions as yr, cividis as yt, RollingAxis as z, barMark as zn, set2 as zt };