insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/types.d.ts

@@ -0,0 +1,319 @@
+import type { Color, Frame, GlyphAtlas, Layer } from "insomni";
+import type { MarkBuilder } from "../../marks.ts";
+import type { SwatchSpec } from "../../legend.ts";
+import type { Aes, ResolvedAes } from "../aes.ts";
+import type { AlphaScale, BorderStyleScale, ColorScale, OverlayGlyphScale, PositionScale, PositionScaleOptions, ShapeScale, SizeScale } from "../scales.ts";
+import type { Theme } from "../theme.ts";
+export 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.
+ */
+export 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.
+ */
+export 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];
+}
+export 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).
+ */
+export interface RangeHints {
+    top?: number;
+    bottom?: number;
+    left?: number;
+    right?: number;
+}
+export interface PrepareRangeContext<T> {
+    data: readonly T[];
+    plot: Frame;
+    scaleOptions: {
+        x?: PositionScaleOptions;
+        y?: PositionScaleOptions;
+    };
+    theme: Theme;
+    atlas: GlyphAtlas | undefined;
+}
+export type AnyAes<T> = Aes<T, unknown>;
+export 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.
+ */
+export 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. */
+export 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;
+}
+export 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?: import("../coord.ts").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`).
+ */
+export 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.
+ */
+export 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.
+ */
+export 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).
+ */
+export 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;
+}
+export 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>): import("./emphasis.ts").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;
+}

package/src/grammar/geoms/types.ts

@@ -0,0 +1,362 @@
+// ---------------------------------------------------------------------------
+// Geom contract
+// ---------------------------------------------------------------------------
+
+import type { Color, Frame, GlyphAtlas, Layer } from "insomni";
+import type { MarkBuilder } from "../../marks.ts";
+import type { SwatchSpec } from "../../legend.ts";
+import type { Aes, ResolvedAes } from "../aes.ts";
+import type {
+  AlphaScale,
+  BorderStyleScale,
+  ColorScale,
+  OverlayGlyphScale,
+  PositionScale,
+  PositionScaleOptions,
+  ShapeScale,
+  SizeScale,
+} from "../scales.ts";
+import type { Theme } from "../theme.ts";
+
+export 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.
+ */
+export 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.
+ */
+export 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];
+}
+
+export 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).
+ */
+export interface RangeHints {
+  top?: number;
+  bottom?: number;
+  left?: number;
+  right?: number;
+}
+
+export interface PrepareRangeContext<T> {
+  data: readonly T[];
+  plot: Frame;
+  scaleOptions: { x?: PositionScaleOptions; y?: PositionScaleOptions };
+  theme: Theme;
+  atlas: GlyphAtlas | undefined;
+}
+
+// Used inside the chart pipeline once channels are read off a geom.
+export type AnyAes<T> = Aes<T, unknown>;
+
+export 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.
+ */
+export interface GeomFrame {
+  count: number; // data.length this frame
+  x: Float32Array; // plot-relative pixel x
+  y: Float32Array; // plot-relative pixel y
+  rgba: Float32Array; // 4 floats per datum: [r,g,b,a, r,g,b,a, ...]
+  a: Float32Array; // per-datum alpha [0,1]
+  r?: Float32Array; // point: radius; area: y0 (baseline px); bar: raw domain value
+  ids?: readonly string[];
+}
+
+/** Injected into CompileContext during an active data/scale transition. */
+export 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;
+}
+
+export 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?: import("../coord.ts").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`).
+ */
+export 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.
+ */
+export 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.
+ */
+export 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).
+ */
+export 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;
+}
+
+export 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>): import("./emphasis.ts").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;
+}