@graphysdk/viz-engine 0.0.1-experimental.7 → 0.0.1-plugins.0

package/dist/index.d.ts

@@ -1,44 +1,17 @@
-/**
- * `@graphysdk/viz-engine` — a grammar-of-graphics engine that compiles a declarative spec into a
- * render-ready `CompiledSpec`. Framework-agnostic: no DOM, no React.
- *
- * Rebuilding a renderer — read these first, in order:
- * 1. {@link Compiler} / {@link createCompiler} — the compile lifecycle and the apply→recompile loop.
- * 2. {@link CompiledSpec} — the render-ready projection you paint (and the compile/render contract).
- * 3. {@link LayoutCompiler} — pixel layout (panel/axes/header rects) plus final axis-tick selection.
- * 4. {@link Command} — serializable spec mutations for interactive edits.
- *
- * The contract in one breath: position scales emit normalized `[0,1]` (x 0=left…1=right, y 0=bottom…1=top,
- * so SVG renderers invert y as `1 - y`); visual scales emit final values (color strings, px sizes); the
- * engine emits format *descriptors* ({@link ValueFormat}) the renderer turns into locale strings; the
- * renderer owns pixel layout, theme, and formatting. Resolve layers and scales by id, never by index.
- *
- * @packageDocumentation
- */
-
-import { Area } from 'd3-shape';
-import { CurveFactory } from 'd3-shape';
 import { internal } from 'arquero';
-import { Line } from 'd3-shape';
-import { Translator } from '@graphysdk/i18n';
 
-/** Maps each visual channel (x, y, color, size, ...) to a data column or constant value. */
 export declare interface AesMapping {
     x?: AestheticValue;
     y?: AestheticValue;
     label?: AestheticValue;
     color?: AestheticValue;
     size?: AestheticValue;
-    /** Opacity channel (0–1). */
     alpha?: AestheticValue;
-    /** Splits marks into series (separate lines/areas) without assigning a visual encoding. */
     group?: AestheticValue;
     strokeWidth?: AestheticValue;
-    /** Dash-pattern channel (solid, dashed, dotted, ...). */
     lineType?: AestheticValue;
 }
 
-/** Name of a single visual channel that can be mapped, such as `'x'` or `'color'`. */
 export declare type AestheticKey = keyof AesMapping;
 
 /**
@@ -85,6 +58,18 @@ declare type AggregationInput = Record<VariableName, {
     aggregation: AggregationFunction;
 }>;
 
+/**
+ * Where an annotation anchored to an observation sits, in normalised panel space `[0, 1]²`, plus the
+ * render discriminant the annotation renderer dispatches on. A geom computes this from an observation
+ * under a coord system (`Geom.resolveAnchorPosition`); the annotations compiler resolves anchors through
+ * the definition rather than branching on geom name.
+ */
+declare interface AnchorPosition {
+    x: number;
+    y: number;
+    geom: 'bar' | 'line' | 'polar-bar';
+}
+
 /**
  * Bounds of the segment a stack total anchors to, in normalised `[0,1]` panel space (origin
  * bottom-left, y grows up). `direction` records which side of the stack the anchor came from.
@@ -97,41 +82,81 @@ declare interface AnchorSegment {
     direction: 'positive' | 'negative';
 }
 
-/** Angular sweep of a polar arc, in radians clockwise from 12 o'clock. */
 export declare interface AngleExtent {
     startAngle: NumericDataValue;
     endAngle: NumericDataValue;
 }
 
-/** Anchors an annotation to a data point by row position, column, and/or category value. */
+/**
+ * The compile-half definition of a custom annotation kind (ADR-035).
+ *
+ * It carries **no compile logic** — coordinate resolution is generic for every kind — and exists only
+ * so the registration-typed builder (`createGraphyBuilder({ annotations })`) can type `annotation.<kind>({
+ * params })` from `TParams`, merge `defaultParams`, and enforce the optional coordinate arity. The
+ * render-half `draw` lives in the renderer and binds to this definition by import (`defineAnnotationRenderer`).
+ */
+/** Optional coordinate-count guardrail enforced by the builder; unbounded when omitted. */
+declare interface AnnotationArity {
+    min?: number;
+    max?: number;
+}
+
+/**
+ * A single coordinate for a custom annotation (ADR-035). One of three whole-coordinate modes — a
+ * data-domain value scaled through the chart's scales, a raw [0,1] unit fraction of the panel, or a
+ * snap to an existing observation. Per-axis mixing (x in one mode, y in another) is a deliberate
+ * non-goal until a consumer needs it.
+ */
+export declare type AnnotationCoordinateInput = {
+    data: {
+        x: DataValue;
+        y: DataValue;
+    };
+} | {
+    unit: {
+        x: number;
+        y: number;
+    };
+} | {
+    observation: ObservationAnchorInput;
+};
+
+/** A resolved coordinate — the observation anchor's `layerIndex` normalised to a `layerId`. */
+declare type AnnotationCoordinateSpec = {
+    data: {
+        x: DataValue;
+        y: DataValue;
+    };
+} | {
+    unit: {
+        x: number;
+        y: number;
+    };
+} | {
+    observation: ObservationAnchor;
+};
+
 declare interface AnnotationDataPoint {
     rowIndex?: number;
     columnKey?: string;
     rowValue?: DataValue;
 }
 
-/**
- * Attach annotations to a spec. Multiple `annotations(...)` items append within
- * each group (like `geom` layers and `highlight`s), they don't replace.
- *
- * @example
- * pipe(
- *   createSpec({ x: 'quarter', y: 'revenue' }),
- *   geom.bar(),
- *   scale.x(),
- *   scale.y(),
- *   annotations({
- *     differenceArrows: [
- *       {
- *         start: { anchorValue: 'Q1', groupValue: null },
- *         end: { anchorValue: 'Q3', groupValue: null },
- *         label: 'relative-difference',
- *       },
- *     ],
- *   }),
- * );
- */
-export declare const annotations: (input: AnnotationsInput) => AnnotationsItem;
+declare interface AnnotationDef<TParams extends object = object, TType extends string = string> {
+    type: TType;
+    /** Carrier that lets the builder recover `TParams` and merge defaults before a param reaches `draw`. */
+    defaultParams: TParams;
+    coordinates?: AnnotationArity;
+}
+
+/** Pipeable spec item produced by the registration-typed `annotation.<kind>(...)` builder. */
+declare interface AnnotationItem {
+    type: 'annotation';
+    annotation: CustomAnnotationInput;
+}
+
+/** Recovers an annotation definition's params type — carried structurally by its `defaultParams`. */
+declare type AnnotationParamsOf<Definition> = Definition extends AnnotationDef<infer TParams> ? TParams : never;
 
 /**
  * Compiles annotations into a render-ready format.
@@ -144,18 +169,19 @@ export declare const annotations: (input: AnnotationsInput) => AnnotationsItem;
  *   stage passes them through into dedicated `Compiled<Kind>` types.
  */
 declare class AnnotationsCompiler extends Stage<AnnotationsCompilerInput, CompiledAnnotations> {
+    private readonly geomCompiler;
+    constructor(geomCompiler: GeomCompiler);
     protected dependencies(input: AnnotationsCompilerInput): readonly unknown[];
     protected run(input: AnnotationsCompilerInput): CompiledAnnotations;
 }
 
-/** Inputs the annotations compiler needs: the spec plus the already-compiled layers and coord system it projects against. */
 declare interface AnnotationsCompilerInput {
     annotations: AnnotationsSpec;
     layers: readonly CompiledLayer[];
     coordSystem: CoordSystem;
+    scales: CompiledScales;
 }
 
-/** All annotations attached to a chart, as user-facing input. Every group is optional. */
 export declare interface AnnotationsInput {
     differenceArrows?: DifferenceArrowInput[];
     shapes?: ShapeInput[];
@@ -164,15 +190,9 @@ export declare interface AnnotationsInput {
     stickers?: StickerAnnotationInput[];
     pinnedNumbers?: PinnedNumberAnnotationInput[];
     comments?: CommentAnnotationInput[];
+    custom?: CustomAnnotationInput[];
 }
 
-/** Annotations as a pipeable spec item. Produced by {@link annotations}. */
-export declare interface AnnotationsItem {
-    type: 'annotations';
-    annotations: AnnotationsInput;
-}
-
-/** Resolved annotations for a chart, with every group present and all fields defaulted. */
 export declare interface AnnotationsSpec {
     differenceArrows: DifferenceArrowSpec[];
     shapes: ShapeSpec[];
@@ -181,16 +201,16 @@ export declare interface AnnotationsSpec {
     stickers: StickerAnnotationSpec[];
     pinnedNumbers: PinnedNumberAnnotationSpec[];
     comments: CommentAnnotationSpec[];
+    custom: CustomAnnotationSpec[];
 }
 
+/** Whether a custom annotation paints behind the geoms (background) or on top (foreground). */
+export declare type AnnotationZOrder = 'background' | 'foreground';
+
 declare interface Appearance {
-    /** Id of the color palette to apply to all series. */
     paletteId?: string;
-    /** Per-series style overrides, keyed by series id. */
     seriesStyles?: Record<string, SeriesStyle>;
-    /** Colors all bars the same instead of giving each category its own palette color. */
     useSingleColorForBars?: boolean;
-    /** Tints the chart background with the palette instead of leaving it plain. */
     backgroundModifier?: 'none' | 'tint';
     border?: Partial<{
         style: 'none' | 'custom' | 'tinted' | 'gradient' | 'preset' | 'grey';
@@ -202,27 +222,17 @@ declare interface Appearance {
         heading: GraphTextStyle;
         body: GraphTextStyle;
     }>;
-    /** One of the {@link CHART_TEXT_SCALES} multipliers applied to all text sizes. */
     textScale?: number;
-    /** How non-highlighted series are de-emphasized when one series is highlighted. */
     highlightStyle?: 'grey' | 'fade-color';
     isLogoHidden?: boolean;
     numberFormat?: Partial<{
-        /** Fixed number of decimal places, or 'auto' to choose per value. */
         decimalPlaces: 'auto' | number;
-        /** Large-number suffix: none, automatic, or a forced thousands/millions/billions unit. */
         abbreviation: 'none' | 'auto' | 'k' | 'm' | 'b';
     }>;
     showTooltips?: boolean;
     animateTransitions?: boolean;
 }
 
-/**
- * Resolved appearance config the renderer reads for chrome. `background` and `border` are narrowed to
- * their compiled variants — see {@link BackgroundConfig} and {@link BorderConfig} for how the renderer
- * materializes each `'tinted'`/`'gradient'`/`'preset'` case. The inherited `textScale` must be applied
- * at both measurement and CSS render time.
- */
 export declare type AppearanceConfig = Omit<AppearanceSpec, 'background' | 'border'> & {
     background: BackgroundConfig;
     border: BorderConfig;
@@ -236,10 +246,6 @@ export declare interface AppearanceSpec {
     /**
      * Multiplier applied to every text element. The renderer sets a CSS
      * variable; em-based theme tokens scale automatically.
-     *
-     * Renderer contract: apply this at BOTH text measurement and CSS render time.
-     * The engine assumes the measured sizes it receives already include the
-     * multiplier, so layout will be wrong if it is applied to only one of the two.
      * @default 1
      */
     textScale: number;
@@ -260,7 +266,6 @@ export declare interface AppearanceSpec {
      */
     cornerRadius: number;
     /**
-     * How non-matched observations are de-emphasised when a highlight is active.
      * @default 'dim'
      */
     highlightStyle: HighlightStyle;
@@ -268,36 +273,32 @@ export declare interface AppearanceSpec {
 
 declare function area(options?: GeomOptions<'area'>): LayerInputOf<'area'>;
 
+/**
+ * Represents a series of observations as a filled area. Multiple areas will be stacked on top of each other.
+ *
+ * Like the line geom, if the x variable is numeric or temporal, the data will be sorted by x.
+ */
+declare class AreaGeom extends Geom {
+    readonly type: "area";
+    readonly requiredAesthetics: AestheticKey[];
+    readonly positionChannels: readonly PositionChannel[];
+    readonly swatchShape: SwatchShape;
+    readonly highlightStrategy = "overlay-anchor";
+    readonly spatialKind = "buckets";
+    readonly directLabelPositions: readonly ["identity", "stack", "dodge", "fill"];
+    readonly supportsPerGroupHeadline: boolean;
+    compile({ data, mapping }: GeomCompilerInput): CompiledGeom;
+}
+
 /**
  * Area-specific parameters (same rendering knobs as line, but fills under the curve)
  */
 export declare interface AreaGeomParams {
-    /**
-     * Outline stroke width in pixels. `'auto'` reads the per-observation
-     * `strokeWidth` channel (`getStrokeWidth`), falling back to the geom default.
-     */
     lineWidth: number | 'auto';
-    /**
-     * Interpolation method between points — a d3-shape curve family (`'linear'` ⇒
-     * `curveLinear`, `'catmull-rom'` ⇒ `curveCatmullRom`).
-     * @default 'linear'
-     */
     interpolate: InterpolateType;
-    /**
-     * How to handle missing (NULL/undefined) values, as for line: `'zero'`
-     * pre-substituted by the compiler, `'gap'` breaks the path at a null, and
-     * `'connect'` drops null rows before pathing.
-     * @default 'gap'
-     */
     missingValues: MissingValuesType;
 }
 
-export declare interface AreaPathGenerators {
-    lineGenerator: Line<Observation>;
-    areaGenerator: Area<Observation>;
-}
-
-/** One end of a freeform arrow, positioned as a fraction of the plot rect (0..1) so it re-flows on resize. */
 export declare interface ArrowEndpoint {
     /** 0..1 of plot width. */
     x: number;
@@ -305,17 +306,13 @@ export declare interface ArrowEndpoint {
     y: number;
 }
 
-/** Whether an arrow end carries an arrowhead. */
 export declare type ArrowheadStyle = 'none' | 'line-arrow';
 
-/** Whether an arrow's line is drawn solid or dashed. */
 export declare type ArrowLineStyle = 'solid' | 'dashed';
 
-/** Preset stroke weight for an arrow annotation. */
 export declare type ArrowThickness = 'thin' | 'medium' | 'thick';
 
 declare interface AverageLine {
-    /** Column whose mean value the average line is drawn at. */
     columnKey: string;
 }
 
@@ -331,9 +328,7 @@ export declare interface AverageLineSymbol {
 declare interface Axes {
     x?: AxisOptions;
     y?: AxisOptions;
-    /** Secondary (right-hand) y-axis; only its label is configurable. */
     y2?: Pick<AxisOptions, 'label'>;
-    /** Splits series across a primary and secondary y-axis. */
     hasDualYAxis?: boolean;
     showGridLines?: boolean;
 }
@@ -387,14 +382,10 @@ declare interface AxisMapping {
 declare interface AxisOptions {
     label?: string;
     isHidden?: boolean;
-    /** Flips the axis direction so values run from high to low. */
     isReversed?: boolean;
     scaleType?: 'linear' | 'logarithmic';
-    /** Forces the lower bound of the axis domain instead of deriving it from the data. */
     min?: number;
-    /** Forces the upper bound of the axis domain instead of deriving it from the data. */
     max?: number;
-    /** Whether to show ticks at every step ('auto') or only at the domain edges ('edges'). */
     tickDisplayMode?: 'auto' | 'edges';
 }
 
@@ -407,13 +398,7 @@ declare type AxisPosition = 'left' | 'right' | 'top' | 'bottom';
 export declare interface AxisTick {
     /** Raw value in data space (number, Date, or string) */
     value: DataValue;
-    /**
-     * Tick position in the same normalized space the geoms use. Normalized to [0,1]: x is 0=left…1=right,
-     * y is 0=bottom…1=top (data-up). SVG / top-origin renderers invert y as `1 - y`.
-     *
-     * For discrete scales this is the band CENTER; the band spans `position ± bandwidth/2`
-     * (see {@link CompiledAxisGuide.bandwidth}).
-     */
+    /** Normalized position in [0,1] space — used for placement */
     position: number;
 }
 
@@ -434,16 +419,6 @@ declare interface AxisTicksConfig {
     mode: AxisLabelMode;
 }
 
-/**
- * Resolved background fill (compiled from `BackgroundSpec`). The variant is decided, but
- * `'theme'` carries no `color` — the renderer narrows (`'color' in background`) before reading it.
- *
- * Renderer materialization by variant:
- * - `'theme'`: paint the active theme's graph-background token (no `color` on this variant).
- * - `'solid'`: paint `color` as-is (a CSS color string, possibly a theme token; `'transparent'` = none).
- * - `'tinted'`: `color` is the resolved anchor; mix it with the theme background, lightening or
- *   darkening per the active {@link GraphTheme}.
- */
 export declare type BackgroundConfig = {
     type: 'theme';
 } | {
@@ -474,19 +449,45 @@ export declare type BackgroundSpec = {
 declare function bar(options?: GeomOptions<'bar'>): LayerInputOf<'bar'>;
 
 /**
- * Which side of the value scale's domain a bar's baseline (its zero origin) falls beyond.
+ * Represents each observation as a rectangular bar.
  *
- * - `'min'`: the baseline sits below the domain, so bars grow from the clipped lower edge
- *   (the usual case — a positive `domainMin`).
- * - `'max'`: the baseline sits above the domain.
- * - `null`: the baseline is in view, so bars start at their true origin.
- */
-export declare type BarBaselineClip = 'min' | 'max' | null;
+ * Neither `x` nor `y` are required because:
+ * - `x` is not needed if a polar coordinate system is used
+ * - `y` may be computed by a stat (e.g. `count`)
+ */
+declare class BarGeom extends Geom {
+    readonly type: "bar";
+    readonly positionChannels: readonly PositionChannel[];
+    readonly swatchShape: SwatchShape;
+    readonly highlightStrategy = "observation-rerender";
+    readonly spatialKind = "rects";
+    readonly directLabelPositions: readonly ["stack", "fill"];
+    readonly gridPolicies: {
+        cartesian: {
+            hideGridX: boolean;
+        };
+        flip: {
+            hideGridX: boolean;
+        };
+        polar: {
+            hideGridX: boolean;
+            hideGridY: boolean;
+        };
+    };
+    readonly emitsGrandTotal: boolean;
+    readonly emitsStackTotals: boolean;
+    readonly supportsPerGroupHeadline: boolean;
+    compile({ data, mapping }: GeomCompilerInput): CompiledGeom;
+    /**
+     * Cartesian: the top-edge midpoint of the bar (the right-edge midpoint when flipped). Polar (pie
+     * slice): the slice midpoint projected from `(angle, radius)` into the panel's `[0, 1]²` frame —
+     * `xMin`/`xMax` are start/end angles (radians) and `yMin`/`yMax` are inner/outer radii.
+     */
+    resolveAnchorPosition(observation: Observation, coordSystem: CoordSystem): AnchorPosition | null;
+}
 
 /**
- * Bar/Column-specific parameters — intentionally empty. A bar's geometry comes
- * entirely from the position columns (band edges plus bar length); corner radius
- * and column grouping are renderer-owned styling, not spec params.
+ * Bar/Column-specific parameters
  */
 declare type BarGeomParams = Record<string, never>;
 
@@ -509,7 +510,6 @@ declare interface BaseCoordParams {
 }
 
 declare interface BaseGeomOptions<T extends GeomParams> {
-    /** Layer-local aesthetic mapping, merged over the spec-level mapping. */
     aes?: AesMapping;
     stat?: StatName | StatInput;
     position?: PositionType;
@@ -532,17 +532,6 @@ export declare const BORDER_PRESET_GRADIENTS: Record<BorderPreset, string>;
 /** Named gradient presets available to `border.type === 'preset'`. */
 export declare const BORDER_PRESETS: readonly ["lilac", "neon_pink", "blackberry", "sun", "iceland", "sunset", "ultraviolet", "purple", "ice_cream", "mint", "cool", "fresh"];
 
-/**
- * Resolved border ring (compiled from `BorderSpec`), painted inside the chart bounds. `'none'` carries
- * no `color`/`width`; narrow on `type` before reading either.
- *
- * Renderer materialization by variant:
- * - `'solid'`: fill the ring with `color` as-is.
- * - `'tinted'`: fill with `color` lightened/darkened for the active {@link GraphTheme}.
- * - `'gradient'`: fill with a 90° linear gradient from `color` to a theme-adjusted stop.
- * - `'preset'`: fill with `BORDER_PRESET_GRADIENTS[preset]` used verbatim as the CSS background (the
- *   preset already encodes its own colors and angle, theme-independent).
- */
 export declare type BorderConfig = {
     type: 'none';
 } | {
@@ -563,7 +552,6 @@ export declare type BorderConfig = {
     width: number;
 };
 
-/** Name of a built-in gradient available to `border.type === 'preset'`. */
 export declare type BorderPreset = (typeof BORDER_PRESETS)[number];
 
 /**
@@ -602,7 +590,6 @@ export declare type BorderSpec = {
     width: number;
 };
 
-/** A width/height pair in pixels, for elements whose position is tracked separately or not yet known. */
 export declare type BoxSize = {
     width: number;
     height: number;
@@ -612,11 +599,9 @@ export declare type BoxSize = {
  * For each average-line rule in a graph with a categorical color grouping, returns the swatch
  * shape + color the renderer should paint inside the rule's label pill.
  *
- * Pass the SOURCE `spec.layers` (not the compiled layers) so each layer's original `stat`,
- * `transforms` and `mapping` are available without needing extra fields on `CompiledLayer`, and the
- * compiled `color` scale (`scales.color`). The returned map is keyed by RULE-layer id (the id is
- * preserved through compilation): look up a rule by its own id; a missing entry means draw no
- * symbol (e.g. no categorical color grouping, or the rule's series didn't resolve to a color).
+ * Reads the rule-matching fields (`stat`, `transforms`, `mapping`) from the source `layers` specs,
+ * and the source layer's swatch shape from its `CompiledLayer` (matched by id, which is preserved
+ * through compilation). The returned map is keyed by layer id.
  *
  * Two shapes of rule layer are handled:
  * - **Filtered**: the rule carries an `eq`-filter. The color-scale lookup value is the filter's
@@ -624,7 +609,7 @@ export declare type BoxSize = {
  * - **Unfiltered**: no filter; the rule's `mapping.y` IS the lookup value. The source layer is
  *   the one whose `y` aesthetic is bound to the same variable.
  */
-export declare function buildAverageLineSymbols(layers: readonly LayerSpec[], colorScale: CompiledScale | undefined, coordSystem: CoordSystem): ReadonlyMap<string, AverageLineSymbol>;
+export declare function buildAverageLineSymbols(layers: readonly LayerSpec[], compiledLayers: readonly CompiledLayer[], colorScale: CompiledScale | undefined, coordSystem: CoordSystem): ReadonlyMap<string, AverageLineSymbol>;
 
 /**
  * Pure projection of `(layers, coordSystem, axes, formatter context, panelRect, measureDataLabel)`
@@ -653,11 +638,8 @@ export declare interface BuildDataLabelsContentInput {
 }
 
 /**
- * Builds a CSS font shorthand string from a FontSpec, in the order `"<style> <weight> <size>px
- * <family>"` (e.g. `"normal 500 12px 'Inter'"`). A single family is quoted so names with spaces stay
- * one token; a family already containing a comma is treated as a ready fallback list and passed
- * through unquoted. A named weight (e.g. `'bold'`) is emitted as-is — the browser canvas resolves it —
- * rather than being mapped to a number; omitted weight/style fall back to the defaults.
+ * Builds a CSS font shorthand string from a FontSpec.
+ * Always quotes the family name to safely handle names with spaces.
  *
  * Renderer-agnostic: usable by browser (OffscreenCanvas) and backend
  * (@napi-rs/canvas) measurers to set `ctx.font` before `ctx.measureText()`.
@@ -676,17 +658,10 @@ declare interface BuildLayerYValueFormatterInput {
 }
 
 /**
- * Builds the SVG arc path for a polar bar (pie / donut slice).
- *
- * Returns `null` for an empty slice (no angular span or no radius) that d3 cannot render.
- */
-export declare const buildPolarBarArcPath: (input: PolarBarArcInput) => string | null;
-
-/**
- * Pure projection of `(compiled, hover)` into the tooltip's `{ header, rows }`. Pure (no I/O, no
- * mutation) — safe to memoize on its input.
- *
- * Returns `null` when there is no primary hit; use that as the tooltip show/hide signal.
+ * Renders `(compiled, hover)` into a chart's semantic content — the single source every surface
+ * (tooltip, screen reader, accessible table) reads, so content never forks per surface. Each
+ * observation's value flows through the layer's semantic map: the raw reading projected on demand
+ * from the declared y encoding, localized here at display time via the encoding's format.
  *
  * Row order is layer-declaration order across layers, color-scale domain order within a layer
  * (= the legend's display order). The primary hit is emphasized in place — never reordered to
@@ -694,30 +669,45 @@ export declare const buildPolarBarArcPath: (input: PolarBarArcInput) => string |
  */
 export declare const buildTooltipContent: ({ layers, coordSystem, scales, guides, numberFormat, parsingLocale, hover, formattingLocale, }: BuildTooltipContentInput) => TooltipContent | null;
 
-/**
- * Everything `buildTooltipContent` needs to turn the current hover into tooltip rows. Feed the
- * same compiled-spec slices used to build the `HoverEngine` (`layers`, `coordSystem`) so labels and
- * hits stay aligned, plus the spec's `scales`, `guides`, and config formatting fields.
- */
 export declare interface BuildTooltipContentInput {
-    /** Compiled layers — the same array passed to the `HoverEngine`. Source of per-series swatch/label data. */
     layers: readonly CompiledLayer[];
-    /** Compiled coord system — the same one passed to the `HoverEngine` (drives swatch shape; gates the header). */
     coordSystem: CoordSystem;
-    /** `CompiledSpec.scales`. The `color` scale's domain fixes legend (display) row order within a layer. */
     scales: CompiledScales;
-    /** `CompiledSpec.guides`. Supplies axis titles, color-group labels, and the `ValueFormat` descriptors. */
     guides: CompiledGuides;
-    /** From `config.numberFormat`. Number-formatting options threaded into every value formatter. */
     numberFormat: NumberFormatConfig;
-    /** From `config.parsingLocale`. Interprets raw values and is the display-locale fallback. */
     parsingLocale: Locale;
-    /** The `HoverState` returned by `HoverEngine.query()` for the current pointer. */
     hover: HoverState;
-    /** Overrides `parsingLocale` for display only (`locale = formattingLocale ?? parsingLocale`). */
     formattingLocale?: Locale;
 }
 
+/** The built-in names as a runtime set, so the resolver can route a custom name to the generic path. */
+export declare const BUILTIN_GEOM_NAMES: ReadonlySet<GeomName>;
+
+/**
+ * Discriminated union of the built-in layer inputs, keyed on `geom`. The per-geom `params` typing is
+ * derived from this via `Extract`, so it stays a closed union the open identity never pollutes.
+ */
+declare type BuiltinLayerInput = {
+    [G in GeomName]: LayerInputOf<G>;
+}[GeomName];
+
+/**
+ * Discriminated union of the built-in resolved layer specs, keyed on `geom`. All properties are fully
+ * resolved — no optionals. The `Extract`-based per-geom params views read from this closed union.
+ */
+declare type BuiltinLayerSpec = {
+    [G in GeomName]: LayerSpecOf<G>;
+}[GeomName];
+
+/**
+ * The resolved `params` type for a geom identity: a built-in's typed params (read from the closed
+ * `BuiltinLayerSpec`, which the open identity never pollutes) or opaque params for a custom geom whose
+ * concrete type a render plugin supplies via the `TParams` slot of {@link CompiledLayerFor}.
+ */
+declare type BuiltinParams<G extends string> = G extends GeomName ? Extract<BuiltinLayerSpec, {
+    geom: G;
+}>['params'] : Record<string, unknown>;
+
 /**
  * Caching decorator for any TextMeasurer implementation.
  *
@@ -760,8 +750,6 @@ export declare interface CartesianCoordSystem {
      * rise, X ticks on the horizontal axis); `'y'` for `coord.flip()` (bars extend, Y ticks on the
      * horizontal axis). Consumers that need to branch on flip read this; the runtime `coord/axes`
      * helpers turn it into main/cross accessors so the branch lives in one place.
-     * When `'y'`, the x-columns carry the measure / cross-axis extent and the y-columns carry the
-     * main-axis band, so geoms swap which reader feeds which pixel axis. See {@link MainAxis}.
      */
     mainAxis: MainAxis;
     /** Axis orientation metadata for the guide compiler */
@@ -787,6 +775,12 @@ declare interface CategoricalValueFormat {
     type: 'text';
 }
 
+/**
+ * The spatial axis a position channel binds to. Selects the scale (`x` → the x scale, `y` → the
+ * primary or secondary y scale) and is the axis flip swaps and polar projects.
+ */
+declare type ChannelAxis = 'x' | 'y';
+
 /**
  * One discrete colour group: its domain value, mapped colour, per-value swatch shape, and the
  * index of the first layer that contributed the value (its "owning" layer in legend/headline
@@ -823,7 +817,6 @@ declare interface ColorScaleMethods {
 }
 
 declare interface ComboOptions {
-    /** Geometry used for the bar-like series alongside line series in a combo chart. */
     comboType?: 'grouped-bars' | 'stacked-bars' | 'lines';
 }
 
@@ -842,14 +835,7 @@ export declare interface Command<TParams extends Record<string, unknown> = Recor
     readonly params: TParams;
     /**
      * Execute the command against a spec.
-     * Returns the new spec and a revert command that can undo this change, or `null` when the
-     * command is a no-op (e.g. the target is missing or the value is unchanged).
-     *
-     * Dispatch loop a renderer runs to reflect a command in the view: apply it to the live
-     * `CompiledSpec.spec`, and on a non-`null` result recompile the returned spec —
-     * `const result = command.apply(compiled.spec); if (!result) return; recompile({ spec: result.spec })`.
-     * A `null` result skips the recompile (and any notify). Always apply against `CompiledSpec.spec`,
-     * the canonical live spec.
+     * Returns the new spec and a revert command that can undo this change.
      */
     apply: (spec: Spec) => CommandApplyResult | null;
 }
@@ -865,17 +851,6 @@ export declare interface CommandApplyResult {
     readonly revert: Command;
 }
 
-/**
- * Descriptor that knows how to deserialize a specific command type.
- * Each concrete command co-locates its descriptor alongside the command class.
- *
- * Serialization is handled uniformly by the registry via `Command.params`.
- */
-declare interface CommandDescriptor<TParams extends Record<string, unknown> = Record<string, unknown>> {
-    readonly type: string;
-    deserialize: (params: TParams, metadata: CommandMetadata) => Command;
-}
-
 /**
  * Unique identifier for commands.
  */
@@ -895,33 +870,6 @@ export declare interface CommandMetadata {
     readonly author: string;
 }
 
-/**
- * Central registry mapping command types to their serialization descriptors.
- */
-export declare class CommandRegistry {
-    private readonly descriptors;
-    /**
-     * Register a command descriptor. Throws if the type is already registered.
-     */
-    register<TParams extends Record<string, unknown>>(descriptor: CommandDescriptor<TParams>): void;
-    /**
-     * Serialize a command to its wire format.
-     */
-    serialize(command: Command): SerializedCommand;
-    /**
-     * Deserialize a command from its wire format.
-     */
-    deserialize(data: SerializedCommand): Command;
-    /**
-     * Get all registered command type names.
-     */
-    getRegisteredTypes(): string[];
-    private getDescriptor;
-}
-
-/** Default singleton registry instance. */
-export declare const commandRegistry: CommandRegistry;
-
 /**
  * Event types emitted by CommandStackManager.
  */
@@ -1033,9 +981,7 @@ declare interface CommandStackOptions {
 export declare interface CommandStackSnapshot {
     readonly canUndo: boolean;
     readonly canRedo: boolean;
-    /** Description of the command that an undo would reverse, for labeling UI; null when nothing to undo. */
     readonly undoDescription: string | null;
-    /** Description of the command that a redo would re-apply; null when nothing to redo. */
     readonly redoDescription: string | null;
 }
 
@@ -1059,14 +1005,6 @@ declare interface CommentAnnotationSpec {
 /** Comparison operators for declarative filtering. */
 declare type ComparisonOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte';
 
-/**
- * All annotations of a chart after compilation, grouped by kind and ready for the renderer.
- *
- * Paint order (back to front): background shapes → geoms → data-labels → difference-arrows →
- * foreground shapes → freeform-arrows → text-annotations. Note that `shapes` are split by their
- * `zOrder` into two passes that bracket the geom layer (see {@link ShapeZOrder}); stickers, pinned
- * numbers and comments are marker overlays painted above text-annotations.
- */
 export declare interface CompiledAnnotations {
     differenceArrows: CompiledDifferenceArrow[];
     shapes: CompiledShape[];
@@ -1075,6 +1013,7 @@ export declare interface CompiledAnnotations {
     stickers: CompiledStickerAnnotation[];
     pinnedNumbers: CompiledPinnedNumberAnnotation[];
     comments: CompiledCommentAnnotation[];
+    custom: CompiledCustomAnnotation[];
 }
 
 /**
@@ -1087,34 +1026,21 @@ export declare interface CompiledAxisGuide {
     scaleAestheticKey: ScaledAestheticKey;
     /** The aesthetic this axis serves (always 'x' or 'y') */
     aesthetic: AestheticKey;
-    /**
-     * Axis placement. Already reflects any flip — drive placement off this, do NOT re-derive from the coord
-     * system's `mainAxis`.
-     */
+    /** Axis placement */
     position: AxisPosition;
     /** Title text, null means no title */
     label: string | null;
-    /**
-     * Gates the whole axis region (line + ticks + labels). Orthogonal to `ticksVisible` / `gridVisible` and to
-     * {@link CompiledPanel.border}.
-     */
+    /** Whether the axis (line + ticks + labels) is visible */
     isVisible: boolean;
-    /**
-     * Candidate tick sets, sorted by ascending count — these are RAW candidates, not the final selection.
-     * Final selection happens in `LayoutCompiler` (two phases: pick the densest candidate whose labels fit), and
-     * the renderer paints the resulting `FormattedAxis.ticks` verbatim — it must not re-select candidates here.
-     */
+    /** Candidate tick sets, sorted by ascending count. Runtime picks the densest one that fits. */
     tickCandidates: AxisTickCandidate[];
-    /**
-     * Resolved format descriptor shared by all ticks on this axis. Already applied during tick selection: the
-     * renderer paints `FormattedAxis.ticks[].formattedLabel` as-is and must NOT re-apply this `ValueFormat`.
-     */
+    /** Resolved format descriptor shared by all ticks on this axis */
     valueFormat: ValueFormat;
-    /** Tick mode from config. Already honored by the compiler when building candidates — don't re-filter ticks. */
+    /** Tick mode from config */
     tickMode: AxisLabelMode;
-    /** Whether tick marks are visible. Labels still show when this is false (independent of `isVisible`). */
+    /** Whether tick marks are visible */
     ticksVisible: boolean;
-    /** Whether grid lines are visible at tick positions. Grid is drawn separately from the axis region. */
+    /** Whether grid lines are visible at tick positions */
     gridVisible: boolean;
     /** Scale type — the renderer uses this to select a formatting strategy */
     scaleType: ScaleType;
@@ -1135,6 +1061,19 @@ declare type CompiledConfig = Omit<ConfigSpec, 'appearance'> & {
     appearance: AppearanceConfig;
 };
 
+/**
+ * Compile-time projection of a custom (registered) annotation. `type` resolves the render-side `draw`;
+ * `targets` are the resolved coordinates; `params` is opaque (typed at authoring time); `zOrder` is the
+ * per-instance override, or `null` to defer to the renderer's declared default.
+ */
+export declare interface CompiledCustomAnnotation {
+    id: string;
+    type: string;
+    params: Record<string, unknown>;
+    zOrder: AnnotationZOrder | null;
+    targets: ResolvedTarget[];
+}
+
 /**
  * A difference arrow with both endpoints resolved to normalized [0, 1]² coordinates.
  */
@@ -1150,9 +1089,7 @@ export declare interface CompiledDifferenceArrow {
      */
     color: string | null;
     size: DifferenceArrowSize;
-    /** Which quantity the arrow's label reports (absolute, relative, or proportion of the two endpoints). */
     label: DifferenceArrowLabelKind;
-    /** Where the label sits along the arrow, as a fraction from start (0) to end (1). */
     labelCrossPosition: number;
 }
 
@@ -1163,13 +1100,11 @@ export declare interface CompiledFreeformArrow {
     id: string;
     start: ArrowEndpoint;
     end: ArrowEndpoint;
-    /** Line color, or `null` to fall back to the theme default. */
     color: string | null;
     thickness: ArrowThickness;
     startArrowheadStyle: ArrowheadStyle;
     endArrowheadStyle: ArrowheadStyle;
     lineStyle: ArrowLineStyle;
-    /** Whether to draw the playful 'sticker' arrow styling instead of a plain line. */
     hasStickerStyle: boolean;
 }
 
@@ -1178,6 +1113,13 @@ declare interface CompiledGeom {
     data: Dataset;
     /** Any mapping overrides produced by the geom */
     mapping: AesMapping;
+    /**
+     * Extra single-observation tooltip rows this geom contributes (e.g. OHLC). The compiler derives
+     * each row's display format from its column and the renderer materialises the values for the
+     * hovered observation. Omit when the geom adds no detail rows; the standard one-row-per-series
+     * tooltip applies.
+     */
+    tooltipRows?: GeomTooltipRow[];
 }
 
 declare interface CompiledGrandTotalHeadline {
@@ -1228,20 +1170,10 @@ export declare interface CompiledIdentityScale extends CompiledScaleBase {
  * Render-ready layer with resolved mappings and transformed data.
  */
 export declare interface CompiledLayer {
-    /**
-     * Stable identity carried over from `LayerSpec.id`. Preserved across recompiles (commands keep
-     * it too), so renderers root per-mark React keys on it — marks morph instead of remounting — and
-     * join hover by matching `HoverHit.layerId === layer.id`.
-     */
+    /** Stable identity carried over from `LayerSpec.id`. Preserved across recompiles. */
     id: string;
-    /**
-     * This layer's transformed, render-ready observations, in render order. Within a series the rows
-     * are pre-ordered along the main axis, so a line / area path can be drawn as-is with no re-sort.
-     * Connected geoms (line, area, polar arc) partition these by `GROUP_VARIABLES.group`
-     * (`data.groupBy(...)`) — one mark per group; per-mark geoms (bar, point) iterate `data` directly.
-     */
     data: Dataset;
-    geom: GeomName;
+    geom: GeomIdentity;
     /** Final mapping after merging root + layer + stat + geom overrides */
     mapping: AesMapping;
     position: PositionType;
@@ -1261,27 +1193,45 @@ export declare interface CompiledLayer {
      * highlights compile stage when applicable highlights match (empty otherwise).
      */
     highlight: CompiledLayerHighlight | null;
+    /**
+     * The layer's geometry-agnostic meaning: the ordered encodings each observation carries (raw
+     * value + format descriptor). Pure data — values stay in `data` and are projected on demand.
+     */
+    semanticMap: SemanticMapDescriptor;
+    /**
+     * The layer's geometry-agnostic hit-test declaration: the spatial structure its marks present,
+     * so the runtime builds the matching index without branching on geom name. Pure data.
+     */
+    spatialMap: SpatialMapDescriptor;
+    /**
+     * The legend/tooltip mark for this layer — the geom's declared cartesian-natural swatch shape.
+     * Pure serialisable data; a polar coord refines a `square` mark to a `slice` at read time.
+     */
+    swatchShape: SwatchShape;
+    /**
+     * `true` when the layer's compile threw or produced invalid output and it was quarantined to a
+     * sentinel that carries no data. The runtime renders a failed-layer placeholder for it; sibling
+     * layers and shared scale domains are unaffected because a sentinel contributes nothing.
+     */
+    failed: boolean;
 }
 
 /**
  * `CompiledLayer` narrowed to a specific `geom`. Lets call sites that already know the geom
  * (geom renderers dispatched off `layer.geom`) take a typed `params` directly, eliminating the
- * `as ...GeomParams` cast that was needed when `params` was the full param union.
+ * `as ...GeomParams` cast that was needed when `params` was the full param union. A custom geom's
+ * render plugin passes `TParams` explicitly (its definition's params type); built-in call sites
+ * default it from the geom name.
  */
-export declare type CompiledLayerFor<G extends GeomName> = Omit<CompiledLayer, 'geom' | 'params'> & {
+export declare type CompiledLayerFor<G extends string, TParams = BuiltinParams<G>> = Omit<CompiledLayer, 'geom' | 'params'> & {
     geom: G;
-    params: Extract<LayerSpec, {
-        geom: G;
-    }>['params'];
+    params: TParams;
 };
 
 /**
  * Per-layer highlight state on `CompiledLayer.highlight`. Bundles the geom's composition
  * strategy (set at layer compile time, never changes after) with the composition output
  * (rewritten by the highlights compile stage when applicable highlights match).
- *
- * This is the **static** highlight (from the spec). A live hover transiently supersedes it: while a
- * pointer is over the chart, render the hover result (see `HoverState`) in place of this.
  */
 export declare interface CompiledLayerHighlight {
     /** How this layer composes highlight matches above its base render. */
@@ -1290,13 +1240,8 @@ export declare interface CompiledLayerHighlight {
     composition: HighlightComposition;
 }
 
-/** A render-ready legend: its resolved placement plus the items it lists, possibly merged across aesthetics. */
 export declare interface CompiledLegendGuide {
-    /**
-     * Visual SCALE keys this legend represents (may be merged): one or more of `color` / `size` / `alpha` /
-     * `strokeWidth` / `lineType` — match those exact tokens. When this includes `'size'` the legend is a BUBBLE
-     * legend: paint each item as a circle sized by {@link LegendItemVisual.size} (pixels) rather than a swatch.
-     */
+    /** Which aesthetics this legend represents (may be merged) */
     aesthetics: AestheticKey[];
     /** Title text, null means no title */
     title: string | null;
@@ -1308,12 +1253,7 @@ export declare interface CompiledLegendGuide {
     items: LegendItem[];
 }
 
-/** The plotting area's frame, telling the renderer whether to draw a border around the panel. */
 export declare interface CompiledPanel {
-    /**
-     * Panel-rect outline. Drawn alongside the grid lines and independent of axis visibility — an axis can be
-     * hidden while this border still shows (and vice versa).
-     */
     border: {
         isVisible: boolean;
     };
@@ -1346,55 +1286,30 @@ declare interface CompiledPositionAdjuster {
  */
 export declare interface CompiledPositionScale<Input = DataValue> extends CompiledScaleBase<Input> {
     kind: 'position';
-    /**
-     * Maps a data value to its normalized position.
-     * Normalized to [0,1]: x is 0=left…1=right, y is 0=bottom…1=top (data-up). SVG / top-origin
-     * renderers invert y as `1 - y`.
-     * Continuous unclamped scales extrapolate outside [0,1] for out-of-domain inputs, so [0,1] is the
-     * in-domain range, not a hard guarantee.
-     */
     map: (value: Input) => number;
-    /**
-     * Band width as a fraction of the panel's main-axis extent, for discrete position scales. This is
-     * the full category band; a per-observation xMin/xMax extent may be a narrower dodged sub-band
-     * inside it. Stays keyed to aesthetic x even when the coord is flipped. Null for continuous /
-     * datetime; null or ≤0 means derive the extent per observation instead.
-     */
+    /** Band width in [0,1] space for discrete position scales. Null for continuous/datetime. */
     bandwidth: number | null;
 }
 
 declare type CompiledPositionScaleOptions<Input = DataValue> = Omit<CompiledPositionScale<Input>, 'kind' | 'aesthetic' | 'spec'>;
 
-/** Any compiled scale, discriminated by `kind` into position, visual, or identity. */
 export declare type CompiledScale<Input = DataValue> = CompiledPositionScale<Input> | CompiledVisualScale<Input> | CompiledIdentityScale;
 
-/** Fields shared by every compiled scale, regardless of `kind`. */
 declare interface CompiledScaleBase<Input = DataValue> {
-    /** The aesthetic this scale drives (e.g. 'x', 'color'). */
     aesthetic: AestheticKey;
-    /**
-     * The scale's resolved input domain, in domain order.
-     * Iterate and `map(value)` over this to enumerate legend / palette swatches.
-     */
     domain: Input[];
-    /** The spec this scale was compiled from. */
     spec: ScaleSpec;
-    /** Produces axis/legend tick values; see {@link GenerateTicksOptions} for the supported variants. */
     generateTicks: (options?: GenerateTicksOptions) => Input[];
 }
 
-/** All compiled scales for a plot, keyed by the aesthetic each one drives. Absent keys are unmapped. */
 export declare type CompiledScales = Partial<Record<ScaledAestheticKey, CompiledScale>>;
 
 /**
- * Compile-time projection of a freeform rectangle. `x`/`y`/`width`/`height` are normalized
- * `[0, 1]` of the panel with a top-left origin (no y-flip) — unlike observation anchors, which
- * are data-space.
+ * Compile-time projection of a freeform rectangle.
  */
 export declare interface CompiledShape {
     id: string;
     kind: ShapeKind;
-    /** Whether the shape draws behind the geoms (background) or over them (foreground). */
     zOrder: ShapeZOrder;
     x: number;
     y: number;
@@ -1403,30 +1318,13 @@ export declare interface CompiledShape {
     fillColor: string;
     fillOpacity: number;
     strokeWidth: number;
-    /** Stroke color, or `null` for no border. */
     strokeColor: string | null;
 }
 
 /**
- * Fully compiled spec, ready for the renderer — the output of {@link Compiler.compile} and the input a
- * renderer paints from. Coords/scales/guides/config/annotations are resolved descriptors; geom data
- * carries its visual values in normalized `[0,1]` position space (y up). See {@link Compiler} for the
- * cross-cutting conventions and {@link LayoutCompiler} for turning this into pixel rects.
- *
- * Not serializable: scales hold live `map` closures (see {@link CompiledPositionScale}). Keep a
- * `CompiledSpec` in memory only — to persist or snapshot, store {@link CompiledSpec.spec} (or the
- * original {@link CompilerInput}) and recompile.
- *
- * Reference stability: each compile returns a fresh top-level object, but a nested slice whose inputs
- * did not change keeps its prior reference (per-stage memoization). Renderers can therefore subscribe
- * by reference identity on individual slices (`layers`, `scales`, …) to skip unchanged work.
+ * Fully compiled spec, ready for the renderer.
  */
 export declare interface CompiledSpec {
-    /**
-     * The resolved spec this output was compiled from, retained so callers can recompile or inspect the
-     * source. This is the canonical live {@link Spec} to apply {@link Command}s against — feed a
-     * command's resulting spec back through {@link Compiler.recompile}.
-     */
     spec: Spec;
     coordSystem: CoordSystem;
     layers: CompiledLayer[];
@@ -1453,11 +1351,7 @@ declare interface CompiledStickerAnnotation {
 }
 
 /**
- * Compile-time projection of a text annotation. `x`/`y`/`width` are normalized `[0, 1]` of the
- * panel with a top-left origin (no y-flip), like `CompiledShape` — panel fractions, not pixels.
- *
- * There is deliberately no height: it is content-intrinsic. The renderer lays out the text within
- * `width` and extends the box down to the panel's bottom edge.
+ * Compile-time projection of a text annotation.
  */
 export declare interface CompiledTextAnnotation {
     id: string;
@@ -1465,9 +1359,7 @@ export declare interface CompiledTextAnnotation {
     x: number;
     y: number;
     width: number;
-    /** Fill behind the text, or `null` for no background. */
     backgroundColor: string | null;
-    /** Whether the background is faded into the plot or fully opaque. */
     backgroundColorStyle: TextAnnotationBackgroundColorStyle;
 }
 
@@ -1477,45 +1369,13 @@ export declare interface CompiledTextAnnotation {
  */
 export declare interface CompiledVisualScale<Input = DataValue> extends CompiledScaleBase<Input> {
     kind: 'visual';
-    /**
-     * Maps a data value to a concrete visual output (color string, pixel size, opacity, …).
-     * Already applied per observation by the visual mapper — read the resolved value via the matching
-     * value reader. Call `map` only for out-of-band values like legend swatches, enumerating the
-     * inputs via {@link CompiledScaleBase.domain}.
-     */
     map: (value: Input) => DataValue;
 }
 
 declare type CompiledVisualScaleOptions<Input = DataValue> = Omit<CompiledVisualScale<Input>, 'kind' | 'aesthetic' | 'spec'>;
 
 /**
- * The grammar-of-graphics engine. Orchestrates the compilation of a spec into render-ready output.
- *
- * Start here. The full pipeline a renderer drives is:
- * `{@link CompilerInput} → {@link createCompiler}() → {@link CompiledSpec} → {@link Command}.apply →
- * {@link Compiler.recompile}`. {@link Compiler.compile} resolves the input and runs every stage;
- * {@link Compiler.recompile} re-runs the stages against an already-resolved {@link Spec} (the live
- * {@link CompiledSpec.spec}) — that is how a dispatched command reaches the view.
- *
- * Conventions that hold across every compiled output (so a renderer can be built against this package
- * alone):
- * - Positions are normalized to `[0,1]` with **y up**: x runs 0=left…1=right, y runs 0=bottom…1=top.
- *   A top-origin renderer (SVG, canvas) must invert y as `1 - y`. Continuous unclamped scales may
- *   extrapolate outside `[0,1]` for out-of-domain inputs.
- * - The engine emits **descriptors, not strings**: values carry a {@link ValueFormat} and the renderer
- *   formats them at paint time (locale lives renderer-side). Likewise scales are callable `map`
- *   functions, never D3 config for the renderer to rebuild.
- * - Pixel layout is a separate step the engine owns too: feed a {@link CompiledSpec} (or its slices)
- *   through {@link LayoutCompiler} to get the plot/panel/axis rects; geoms paint in `[0,1]` inside the
- *   panel rect. Renderers do not reimplement the grid.
- * - Resolve cross-references **by id**: a layer's scale comes from {@link CompiledSpec.scales} keyed by
- *   aesthetic, its axis from {@link CompiledSpec.guides}; marks key off the layer id.
- *
- * Statefulness: a `Compiler` retains the last dataset seen by {@link Compiler.compile}/{@link Compiler.recompile}
- * and reuses it to derive guide and legend labels. Call {@link Compiler.compile} (which takes data) at
- * least once before any {@link Compiler.recompile}({ spec }), otherwise label derivation has no dataset.
- * Per-stage memoization and dataset retention are instance-scoped, so create one `Compiler` per graph
- * and reuse it across recompiles rather than building a fresh one per frame.
+ * The main compiler. It orchestrates the compilation of a spec into a render-ready output.
  *
  * Each layer is processed through the pipeline. Coords and scales are compiled separately as they apply to
  * the entire plot.
@@ -1540,15 +1400,6 @@ export declare class Compiler {
     private lastData;
     private readonly stages;
     constructor(dataCompiler: DataCompiler, specCompiler: SpecResolver, transformCompiler: TransformCompiler, constantMappingCompiler: ConstantMappingCompiler, layerValidationCheck: LayerValidationCheck, layerCompiler: LayerCompiler, scaleCompiler: ScaleCompiler, coordCompiler: CoordCompiler, positionMapperCompiler: PositionMapperCompiler, visualMapperCompiler: VisualMapperCompiler, guideCompiler: GuideCompiler, summariseCompiler: SummariseCompiler, highlightsCompiler: HighlightsCompiler, configCompiler: ConfigCompiler, annotationsCompiler: AnnotationsCompiler);
-    /**
-     * Resolve `input` (a low-level spec or a high-level GraphConfig) against `data` and run the full
-     * pipeline, producing a render-ready {@link CompiledSpec}. The primary entry point for consumers.
-     *
-     * Routing: reach for `compile` whenever the input or the {@link RendererContext} changes — including
-     * a theme or palette switch, since `ctx` is consumed **only** here ({@link Compiler.recompile} takes
-     * no `ctx`). For a data-only or command-driven update prefer {@link Compiler.recompile}, which keeps
-     * layer ids stable so id-keyed renderers can transition marks instead of remounting them.
-     */
     compile({ input, data, ctx }: {
         input: CompilerInput;
         data: Data;
@@ -1557,15 +1408,6 @@ export declare class Compiler {
     /**
      * Run the rendering pipeline against an already-resolved {@link Spec}.
      *
-     * This is the second half of the command dispatch loop. To reflect a {@link Command} in the view:
-     * `const result = command.apply(compiled.spec); if (!result) return; recompile({ spec: result.spec })`.
-     * A `null` apply result is a no-op — skip the recompile. {@link CompiledSpec.spec} is the canonical
-     * live {@link Spec} to apply commands against; pass the new spec straight back here. Using a
-     * {@link CommandStackManager} is optional — the minimal path is just apply-then-recompile.
-     *
-     * Requires a prior {@link Compiler.compile} (or recompile-with-data): the retained dataset is what
-     * guide and legend labels are derived from.
-     *
      * When `data` is provided, it is parsed and spliced onto `spec` before the pipeline
      * runs — useful for swapping the dataset without re-resolving the spec, so layer ids
      * survive and id-keyed renderers can transition marks instead of unmounting them.
@@ -1610,31 +1452,22 @@ export declare type CompilerCacheStats = Record<CompilerStageName, MemoStats>;
  */
 export declare type CompilerInput = SpecInput | GraphConfig;
 
-/** Identifier of a single compile pipeline stage, used to key the per-stage cache counters. */
 declare type CompilerStageName = (typeof COMPILER_STAGE_KEYS)[number];
 
-/** A difference arrow ready to paint: SVG paths, label text and box styling, all in panel-local pixel space. */
 export declare interface ComputedDifferenceArrow {
     id: string;
     /** SVG path for the arrow body. Coordinates are in panel-local pixel space. */
     linePath: string;
     /** SVG path for the arrowhead. */
     arrowheadPath: string;
-    /**
-     * Pixel position of the label box CENTER. The engine does not size the box: measure `labelText`
-     * yourself, then box width = measured width + `2·labelPaddingX` and box height =
-     * `labelLineHeight + 2·labelPaddingY`.
-     */
+    /** Pixel position for the label box midpoint. */
     labelPosition: PointPosition;
     labelText: string;
     /** Resolved color for the arrow. `null` lets the renderer fall back to a neutral default. */
     color: string | null;
     /** Stroke width derived from the arrow size. */
     strokeWidth: number;
-    /**
-     * Label box line height in pixels. Doubles as the label's font size (paint the text at this size
-     * with `labelFontWeight`); the box height is `labelLineHeight + 2·labelPaddingY`.
-     */
+    /** Label box line height in pixels. */
     labelLineHeight: number;
     /** Label box horizontal padding (left + right). */
     labelPaddingX: number;
@@ -1646,15 +1479,6 @@ export declare interface ComputedDifferenceArrow {
     labelFontWeight: number;
 }
 
-/**
- * A freeform arrow ready to paint: SVG paths plus stroke/dash styling, all in panel-local pixel space.
- *
- * Sticker rendering (`hasStickerStyle`): paint the union of the three path strings (`linePath`,
- * `startArrowheadPath`, `endArrowheadPath`) as one shape with a light outline and a drop shadow. The
- * outline and shadow extend past the geometry, so the drop-shadow filter region must be inflated on
- * every side by `arrowheadExtent + strokeWidth + outlineWidth + blurRadius` to avoid clipping at the
- * arrowheads (the last two are renderer-owned).
- */
 export declare interface ComputedFreeformArrow {
     id: string;
     /** SVG path for the arrow body, in panel-local pixels. */
@@ -1663,7 +1487,7 @@ export declare interface ComputedFreeformArrow {
     startArrowheadPath: string;
     /** SVG path for the end arrowhead or '' when there is none. */
     endArrowheadPath: string;
-    /** Resolved color, or `null` to fall back to the theme `defaultAnnotationArrowStroke` token. */
+    /** Resolved color or `null` to fall back to theme default. */
     color: string | null;
     strokeWidth: number;
     /** SVG `stroke-dasharray` or `null` for a solid line. */
@@ -1693,14 +1517,9 @@ export declare const computeDifferenceArrow: ({ arrow, mainAxis, panelWidth, pan
 
 declare interface ComputeDifferenceArrowParams {
     arrow: CompiledDifferenceArrow;
-    /**
-     * Chart orientation — `CartesianCoordSystem.mainAxis`. When `'y'` the arrow geometry is flipped to
-     * run horizontally. Pass `'x'` for a polar coord system.
-     */
     mainAxis: 'x' | 'y';
     panelWidth: number;
     panelHeight: number;
-    /** Graph-wide text scale, applied to the label so it sizes with the rest of the chart. */
     textScale: number;
     locale: Locale;
 }
@@ -1714,9 +1533,7 @@ export declare const computeDirectLabelsLayout: <TPayload>({ items, containerHei
 
 declare interface ComputeDirectLabelsLayoutInput<TPayload> {
     items: ReadonlyArray<DirectLabelInput<TPayload>>;
-    /** Pixel height of the area labels are placed within; positions are clamped to `[0, containerHeight]`. */
     containerHeight: number;
-    /** Pixel height of a single label, used to detect and resolve vertical overlap. */
     labelHeight: number;
 }
 
@@ -1726,12 +1543,14 @@ declare interface ComputeDirectLabelsLayoutInput<TPayload> {
 export declare const computeFreeformArrow: ({ arrow, panelWidth, panelHeight, }: ComputeFreeformArrowParams) => ComputedFreeformArrow | null;
 
 declare interface ComputeFreeformArrowParams {
-    arrow: CompiledFreeformArrow;
+    arrow: FreeformArrowSpec;
     panelWidth: number;
     panelHeight: number;
 }
 
-/** Wraps partial config options into a tagged `ConfigItem` for inclusion in a spec. */
+/**
+ * Create a custom  configuration
+ */
 export declare function config(options: ConfigInput): ConfigItem;
 
 /**
@@ -1742,7 +1561,6 @@ declare class ConfigCompiler extends Stage<ConfigCompilerInput, CompiledConfig>
     protected run(input: ConfigCompilerInput): CompiledConfig;
 }
 
-/** Inputs the config compiler needs: the config spec plus the compiled scales it resolves color references against. */
 declare interface ConfigCompilerInput {
     config: ConfigSpec;
     scales: CompiledScales;
@@ -1766,13 +1584,6 @@ declare interface ConfigItem {
  * All fields are required and always populated after resolution.
  */
 export declare interface ConfigSpec {
-    /**
-     * Locale used to interpret source values AND, by default, to format display
-     * output (axis labels, tooltips, numbers). Pass `formattingLocale` to a
-     * `format*` helper to override display only — it resolves
-     * `formattingLocale ?? parsingLocale`. The `duration` format is always
-     * English regardless of locale.
-     */
     parsingLocale: Locale;
     legend: LegendConfig;
     axes: AxesConfig;
@@ -1830,7 +1641,6 @@ declare interface Content {
     isSubtitleHidden?: boolean;
     caption?: string | RichTextContent;
     isCaptionHidden?: boolean;
-    /** Attribution shown in the footer; optional label text and link target. */
     source?: Partial<{
         label: string;
         url: string;
@@ -1942,7 +1752,6 @@ declare type ContinuousScaleSpec = Required<ContinuousScaleInput>;
  */
 export declare function convertSpecToInput(spec: Spec): SpecInput;
 
-/** Builders for the chart's coordinate system. Pass the result as the spec's `coord` to choose cartesian, flipped, or polar. */
 export declare const coord: {
     /**
      * Standard cartesian (x-y) coordinate system. This is the default if no coord is specified.
@@ -1987,23 +1796,21 @@ declare class CoordCompiler {
 declare type CoordInput = CartesianCoordInput | FlipCoordInput | PolarCoordInput;
 
 /**
- * Built-in coordinate system implementations keyed by {@link CoordType}.
+ * Built-in coordinate system implementations keyed by {@link CoordType}. `flip` and `polar` read each
+ * layer geom's position-channel manifest via {@link GeomRegistry} to decide which columns to project.
  */
 declare class CoordRegistry extends Registry<CoordType, CoordStrategy> {
-    constructor();
+    constructor(geomRegistry: GeomRegistry);
 }
 
-/** What a {@link CoordStrategy} receives during the setup pass — the coord spec plus the plot's scales and compiled layers. */
 declare interface CoordSetupInput {
     coordSpec: CoordSpec;
     scales: ScaleSpec[];
     layers: CompiledLayer[];
 }
 
-/** Output of the setup pass: the resolved coordinate system plus scales the coord system may have adjusted. */
 declare type CoordSetupResult = {
     coordSystem: CoordSystem;
-    /** Scales after any coord-imposed adjustments (e.g. `flip` reversing an axis). */
     scales: ScaleSpec[];
 };
 
@@ -2036,13 +1843,9 @@ declare interface CoordStrategy {
 /**
  * Render-ready coordinate system (discriminated union).
  * Discriminates on geometric paradigm: cartesian plane vs polar projection.
- *
- * A mark's geometry is the `(geom, coordSystem.type)` pair, not the geom alone: the same geom
- * renders differently per coord — a bar is a rect in cartesian and an arc in polar.
  */
 export declare type CoordSystem = CartesianCoordSystem | PolarCoordSystem;
 
-/** What a {@link CoordStrategy} receives during the transform pass — the coord spec and position-mapped layers. */
 declare interface CoordTransformInput {
     coordSpec: CoordSpec;
     layers: CompiledLayer[];
@@ -2066,57 +1869,46 @@ declare interface CountStatSpec {
     type: 'count';
 }
 
-/** Reader for the raw value behind a layer's `alpha` mapping. */
-export declare const createAlphaValueReader: (data: Dataset, mapping: AesMapping) => RawValueReader;
-
-/**
- * Builds the d3 area + top-line generators for an area layer.
- *
- * The `mainAxis === 'y'` branch is structural: d3-area exposes two separate APIs —
- * `.x(main).y0(crossMin).y1(crossMax)` for vertical fills and `.y(main).x0(crossMin).x1(crossMax)`
- * for horizontal fills — there is no orientation-agnostic setter. After `coord.flip()` has run,
- * `POSITION_VARIABLES.x` holds the measure (fill bound) and `POSITION_VARIABLES.y` the band
- * center, so the flipped branch reads `xMin`/`xMax` as the fill bounds and `y` as the main-axis
- * position.
- */
-export declare const createAreaPathGenerators: (coordSystem: CartesianCoordSystem, params: AreaGeomParams) => AreaPathGenerators;
+export declare const createAlphaValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
 
-/** Reader for the raw value behind a layer's `color` mapping. */
-export declare const createColorValueReader: (data: Dataset, mapping: AesMapping) => RawValueReader;
+export declare const createColorValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
 
 /**
- * Builds a {@link Compiler} with all built-in stages and registries wired together. The standard
- * entry point for consumers; use this rather than constructing `Compiler` by hand.
- *
- * The returned {@link Compiler} is the head of the pipeline
- * (`{@link CompilerInput} → createCompiler() → {@link CompiledSpec} → {@link Command}.apply →
- * {@link Compiler.recompile}`) — see {@link Compiler} for the conventions a renderer relies on.
- * Because the compiler is stateful (retains the last dataset, memoizes per stage), create one
- * instance per graph and reuse it across recompiles instead of calling `createCompiler` each frame.
+ * Builds a compiler instance. Pass `geoms` to register custom (or override built-in) geom
+ * definitions per-instance — there is no global registry to mutate, so injected geoms never bleed
+ * across instances. An injected geom whose `type` matches a built-in overrides it (last write wins).
  */
-export declare const createCompiler: () => Compiler;
+export declare const createCompiler: (opts?: {
+    geoms?: readonly Geom[];
+}) => Compiler;
 
 /**
- * Fresh empty highlight state for a layer of the given geom, or `null` when the geom opts
- * out of highlighting (no entry in `HIGHLIGHT_STRATEGY_BY_GEOM`).
+ * Fresh empty highlight state for the given composition strategy, or `null` when the strategy is
+ * `null` (the geom opts out of highlighting). Callers resolve the strategy from the geom definition.
  */
-export declare function createEmptyHighlight(geom: GeomName): CompiledLayerHighlight | null;
-
-/** Reader for the raw value behind a layer's `group` mapping. */
-export declare const createGroupValueReader: (data: Dataset, mapping: AesMapping) => RawValueReader;
+export declare function createEmptyHighlight(strategy: HighlightStrategy | null): CompiledLayerHighlight | null;
 
 /**
- * The single structural model of a headline item's rows and segments. Both the measurer (which sizes
- * each segment without a DOM) and the JSX (which paints them) read this, so a layout change — a new
- * row, a reordered segment — lands in one place and the two can't drift. Styling and font pixels are
- * resolved by each consumer from the roles; this model carries only structure, text, and gaps.
+ * Builds a Graphy authoring surface for a set of custom geoms and/or annotations: a `geom` builder that
+ * merges the built-in methods with one method per registered custom geom, an `annotation` builder with
+ * one method per registered annotation kind, plus the standard `createSpec`. The 90% case stays the
+ * plain `import { geom, createSpec }`; reach for this only when authoring custom geoms (decision 8) or
+ * custom annotations (ADR-035). Registration is per-instance — geoms are injected to
+ * `createCompiler({ geoms })`; annotations need no compile-side registry (coordinate resolution is
+ * generic), only the render plugin via `<GraphProvider annotationPlugins={[...]}>`.
  */
-export declare const createHeadlineItemRows: (item: FormattedHeadlineItem) => HeadlineRow[];
+export declare function createGraphyBuilder<const Geoms extends readonly Geom[] = readonly [], const Annotations extends readonly AnnotationDef[] = readonly []>(options: {
+    geoms?: Geoms;
+    annotations?: Annotations;
+}): {
+    geom: typeof geom & CustomGeomBuilders<Geoms>;
+    annotation: CustomAnnotationBuilders<Annotations>;
+    createSpec: typeof createSpec;
+};
 
-/** Reader for the raw value behind a layer's `label` mapping. */
-export declare const createLabelValueReader: (data: Dataset, mapping: AesMapping) => RawValueReader;
+export declare const createGroupValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
 
-export declare const createLinePathGenerator: (params: LineGeomParams) => Line<Observation>;
+export declare const createLabelValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
 
 /**
  * Builds a per-observation reader for an `AestheticValue`:
@@ -2126,20 +1918,12 @@ export declare const createLinePathGenerator: (params: LineGeomParams) => Line<O
  *   so downstream code can rely on a typed `DataValue`.
  * - `undefined` / unknown variable → `null`.
  */
-export declare const createRawValueReader: (data: Dataset, aestheticValue: AestheticValue | undefined) => RawValueReader;
+export declare const createRawValueReader: (data: Dataset, aestheticValue: AestheticValue | undefined) => ((observation: Observation) => DataValue);
 
-/**
- * Per-observation reader for the segment-y value of a compiled layer, in original data units.
- *
- * When the layer is stacked, the y position columns already hold cumulative band bounds (draw
- * segments directly) — so for a label or tooltip showing the segment's own value, use this reader,
- * not {@link getY} (which is normalized to `[0, 1]`). It auto-selects `yRaw` for stacked layers and
- * the user's y mapping otherwise.
- */
+/** Per-observation reader for the segment-y value of a compiled layer. */
 export declare function createSegmentYReader(layer: CompiledLayer): (observation: Observation) => DataValue;
 
-/** Reader for the raw value behind a layer's `size` mapping. */
-export declare const createSizeValueReader: (data: Dataset, mapping: AesMapping) => RawValueReader;
+export declare const createSizeValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
 
 /**
  * Create a new spec, optionally piping spec items in one call. Data is passed separately
@@ -2159,58 +1943,117 @@ export declare const createSizeValueReader: (data: Dataset, mapping: AesMapping)
  */
 export declare function createSpec(...items: Array<AesMapping | SpecItem>): SpecInput;
 
-export declare const createStableKeyGenerator: (data: Dataset, mapping: AesMapping, layerId: string) => ((observation: Observation) => string);
-
-/** Reader for the raw value behind a layer's `strokeWidth` mapping. */
-export declare const createStrokeWidthValueReader: (data: Dataset, mapping: AesMapping) => RawValueReader;
+export declare const createStrokeWidthValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
 
 /**
- * The single descriptor → string entry point: turns a compiler-emitted {@link ValueFormat} (plus a
- * locale and number-format config) into a reusable {@link ValueFormatter}. A renderer materializing a
- * `valueFormat` it pulled off a compiled guide/legend/headline goes through here rather than
- * branching on `type` itself.
- *
- * Dispatches on `valueFormat.type` and throws on an unknown kind (so a newly added format surfaces
- * loudly instead of silently formatting wrong). A `lookup` formatter needs the per-call `Observation`
- * to pick its case — see {@link ValueFormatter}; every other kind ignores the observation.
+ * Creates a value formatter for a given value format.
  */
 export declare const createValueFormatter: (params: ValueFormatterFactoryParams) => ValueFormatter;
 
-/** Reader for the raw value behind a layer's `x` mapping. */
-export declare const createXValueReader: (data: Dataset, mapping: AesMapping) => RawValueReader;
+export declare const createXValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
 
-/** Reader for the raw value behind a layer's `y` mapping. */
-export declare const createYValueReader: (data: Dataset, mapping: AesMapping) => RawValueReader;
+export declare const createYValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
 
 /** Three letter ISO string representing the currency */
-export declare type CurrencyIso = 'aed' | 'aud' | 'bdt' | 'bhd' | 'brl' | 'cad' | 'chf' | 'clp' | 'cny' | 'cop' | 'czk' | 'dkk' | 'egp' | 'eur' | 'gbp' | 'hkd' | 'huf' | 'idr' | 'ils' | 'inr' | 'jpy' | 'krw' | 'kwd' | 'mxn' | 'myr' | 'ngn' | 'nok' | 'nzd' | 'php' | 'pkr' | 'pln' | 'qar' | 'ron' | 'rub' | 'sar' | 'sek' | 'sgd' | 'thb' | 'try' | 'twd' | 'usd' | 'vnd' | 'zar';
+declare type CurrencyIso = 'aed' | 'aud' | 'bdt' | 'bhd' | 'brl' | 'cad' | 'chf' | 'clp' | 'cny' | 'cop' | 'czk' | 'dkk' | 'egp' | 'eur' | 'gbp' | 'hkd' | 'huf' | 'idr' | 'ils' | 'inr' | 'jpy' | 'krw' | 'kwd' | 'mxn' | 'myr' | 'ngn' | 'nok' | 'nzd' | 'php' | 'pkr' | 'pln' | 'qar' | 'ron' | 'rub' | 'sar' | 'sek' | 'sgd' | 'thb' | 'try' | 'twd' | 'usd' | 'vnd' | 'zar';
 
 declare interface CurrencyValueFormat {
     type: 'currency';
     iso: CurrencyIso;
 }
 
-/** A single named color slot within a custom palette supplied by the renderer. */
-export declare type CustomPaletteColor = {
+/**
+ * One builder method per registered custom annotation, keyed by its `type` and typed from its
+ * definition — so `annotation.calloutBox(...)` exists because `calloutBox` was registered, with params
+ * checked against the definition's `TParams`. Returns a pipeable {@link AnnotationItem}.
+ */
+declare type CustomAnnotationBuilders<Annotations extends readonly AnnotationDef[]> = {
+    [Definition in Annotations[number] as Definition['type']]: (options: CustomAnnotationOptions<AnnotationParamsOf<Definition>>) => AnnotationItem;
+};
+
+/**
+ * A custom (registered) annotation instance. `type` names the registered kind (resolves the render-side
+ * `draw`); `coordinates` resolve to targets at compile time; `params` is opaque at the spec level — the
+ * registration-typed builder types it from the annotation definition. `zOrder` overrides the kind's
+ * declared default.
+ */
+export declare interface CustomAnnotationInput {
+    id?: string;
+    type: string;
+    coordinates: AnnotationCoordinateInput[];
+    params?: Record<string, unknown>;
+    zOrder?: AnnotationZOrder;
+}
+
+/** Options for authoring a custom annotation through the registration-typed builder (ADR-035). */
+declare interface CustomAnnotationOptions<TParams extends object> {
+    coordinates: AnnotationCoordinateInput[];
+    params?: Partial<TParams>;
+    zOrder?: AnnotationZOrder;
+    id?: string;
+}
+
+export declare interface CustomAnnotationSpec {
     id: string;
-    hex: string;
-    name?: string;
+    type: string;
+    coordinates: AnnotationCoordinateSpec[];
+    params: Record<string, unknown>;
+    /** `null` defers to the renderer's declared default zOrder. */
+    zOrder: AnnotationZOrder | null;
+}
+
+/**
+ * One builder method per registered custom geom, keyed by its `type` and typed from its definition —
+ * so `geom.candlestick(...)` exists because `candlestick` was registered, with params checked against
+ * the geom's `TParams` (decision 8).
+ */
+declare type CustomGeomBuilders<Geoms extends readonly Geom[]> = {
+    [Definition in Geoms[number] as Definition['type'] & string]: (options?: CustomGeomOptions<ParamsOf<Definition>, MappableAes<Definition>>) => LayerInput;
 };
 
+/**
+ * Options for authoring a custom geom's layer through the registration-typed builder. Mirrors the
+ * built-in geom options, but `params` is typed from the registered definition's `TParams` and `aes`
+ * is constrained to the geom's declared mapping keys (`TAes`) — an undeclared aesthetic is rejected.
+ */
+declare interface CustomGeomOptions<TParams extends object, TAes extends string> {
+    aes?: Partial<Record<TAes, AestheticValue>>;
+    stat?: StatName | StatInput;
+    position?: PositionType;
+    yScaleType?: YScaleType;
+    params?: Partial<TParams>;
+    transforms?: TransformInput[];
+    interactive?: boolean;
+    dataLabels?: DataLabelsInput;
+}
+
+/**
+ * A layer input for a custom-registered geom whose `type` is not a built-in name. `params` is opaque
+ * at the spec level; the registration-typed builder is where it is typed from the geom definition.
+ */
+declare interface CustomLayerInput extends LayerInputBase {
+    geom: string;
+    params?: Record<string, unknown>;
+}
+
+/** A resolved layer spec for a custom-registered geom — the generic resolver's output shape. */
+declare interface CustomLayerSpec extends LayerSpecBase {
+    geom: string;
+    params: Record<string, unknown>;
+}
+
 declare type CustomPaletteConfig = {
     type: 'custom';
     id: string;
     colors: string[];
 };
 
-/** Reference to a user-registered custom palette by id, resolved against the palette registry. */
 declare type CustomPaletteInput = {
     type: 'custom';
     id: string;
 };
 
-/** Renderer-owned custom palettes, keyed by `paletteId`, that a GraphConfig may reference by id. */
-export declare type CustomPalettesInput = Record<string, CustomPaletteColor[]>;
+export declare type CustomPalettesInput = Record<string, string[]>;
 
 /**
  * Data to visualize. Structured as a table.
@@ -2264,9 +2107,7 @@ export declare type DataLabelPosition = 'inside' | 'outside';
 
 declare interface DataLabels {
     showDataLabels?: boolean;
-    /** Whether labels show raw values or each point's share of its stack/total. */
     dataLabelFormat?: 'absolute' | 'percentage';
-    /** Shows the summed total above each stack in stacked charts. */
     showStackTotals?: boolean;
     showCategoryLabels?: boolean;
 }
@@ -2302,16 +2143,12 @@ export declare interface DataLabelsConfig {
     labelSource: AestheticValue;
 }
 
-/**
- * Fully-derived data-labels content. Renderers map straight over `labels` and paint each as given —
- * the engine resolves no overlaps between labels.
- */
+/** Fully-derived data-labels content. Renderers map straight over `labels`. */
 export declare interface DataLabelsContent {
     /** Flat list, in layer-declaration order; per-observation labels precede stack totals within a layer. */
     labels: PlacedDataLabel[];
 }
 
-/** User-facing data-labels options; any omitted field falls back to its resolved default. */
 export declare type DataLabelsInput = DeepPartial<Omit<DataLabelsConfig, 'labelSource'>>;
 
 /**
@@ -2325,10 +2162,6 @@ export declare type DataLabelTarget = 'observation' | 'aggregate';
 /**
  * Renderer-supplied measurer that knows which font to apply for each `DataLabelKind`. Lets
  * placement strategies measure text without the engine ever holding a `FontSpec`.
- *
- * Must return the FINAL plate size — text metrics plus the renderer's own padding. The engine
- * treats the returned `width`/`height` as the plate dimensions (`PlacedDataLabel.width`/`height`)
- * and does not add padding of its own.
  */
 export declare type DataLabelTextMeasurer = (kind: DataLabelKind, text: string) => MeasuredText;
 
@@ -2390,7 +2223,7 @@ export declare class Dataset {
      * Derives a new variable based on existing variables, using a table expression. If `valueFormat`
      * is omitted, a type-based default is used.
      */
-    deriveVariable(variable: VariableName, type: DataType, expression: (observation: Observation) => DataValue, valueFormat?: ValueFormat): Dataset;
+    deriveVariable(variable: VariableName, type: DataType, expression: (observation: Observation, rowIndex: number) => DataValue, valueFormat?: ValueFormat): Dataset;
     /**
      * Renames a variable.
      */
@@ -2611,21 +2444,18 @@ declare type DeepPartial<T> = {
     [K in keyof T]?: T[K] extends Array<infer U> ? Array<DeepPartial<U>> : NonNullable<T[K]> extends object ? DeepPartial<NonNullable<T[K]>> : T[K];
 };
 
+export declare const DEFAULT_COLOR_PALETTE: string[];
+
 /**
  * Default font style.
  */
 export declare const DEFAULT_FONT_STYLE = "normal";
 
 /**
- * Numeric weight used when a `FontSpec` omits `weight`. A from-scratch measurer must apply the same
- * default to produce identical metrics (and identical cache keys).
+ * Default font weight.
  */
 export declare const DEFAULT_FONT_WEIGHT = 500;
 
-/** Stroke width used when a line/area layer leaves `lineWidth` on `'auto'` and the observation carries none. */
-export declare const DEFAULT_LINE_WIDTH = 2;
-
-/** Locale used when a consumer does not specify one. */
 export declare const DEFAULT_LOCALE: Locale;
 
 declare type DefaultPaletteConfig = {
@@ -2645,7 +2475,7 @@ declare interface DifferenceArrowDimensions {
     curveRadius: number;
     /** Stroke width of the arrow. */
     strokeWidth: number;
-    /** Line height of the label in pixels. Also the label's font size; box height = `labelLineHeight + 2·labelPaddingY`. */
+    /** Line height of the label in pixels. */
     labelLineHeight: number;
     /** Horizontal label padding (left + right). */
     labelPaddingX: number;
@@ -2662,25 +2492,17 @@ declare interface DifferenceArrowDimensions {
  * are defaulted by the resolver.
  */
 export declare interface DifferenceArrowInput {
-    /** Stable id; generated by the resolver when omitted. */
     id?: string;
-    /** Observation the arrow's tail points from. */
     start: ObservationAnchorInput;
-    /** Observation the arrow's head points to. */
     end: ObservationAnchorInput;
-    /** What the arrow's label measures (raw gap, relative change, or share). */
     label: DifferenceArrowLabelKind;
-    /** null falls back to a theme default. */
     color?: string | null;
     size?: DifferenceArrowSize;
-    /** Offset of the label across the arrow, as a fraction of the arrow's length. */
     labelCrossPosition?: number;
 }
 
-/** What a difference arrow's label measures: the raw gap, the relative change, or one value as a share of the other. */
 export declare type DifferenceArrowLabelKind = 'absolute-difference' | 'relative-difference' | 'proportion';
 
-/** Preset visual scale for a difference arrow. */
 export declare type DifferenceArrowSize = 'small' | 'medium' | 'large';
 
 /**
@@ -2696,25 +2518,18 @@ export declare interface DifferenceArrowSpec {
     labelCrossPosition: number;
 }
 
-/** One label to place, given by its data anchor as a normalized Y in `[0, 1]` (1 = top). */
 export declare interface DirectLabelInput<TPayload> {
     normalizedY: number;
-    /** Renderer-defined data round-tripped onto the resulting placement. */
     payload: TPayload;
 }
 
-/** A label's resolved position after overlap resolution, plus its original anchor for drawing a connector. */
 export declare interface DirectLabelPlacement<TPayload> {
-    /** Vertical centre of the label after repulsion, in top-down pixel space. */
     y: number;
-    /** Pixel Y of the original data anchor — the start of any connector line back to the data. */
     anchorY: number;
     payload: TPayload;
 }
 
-/** Result of laying out direct labels. `hasOverlap` flags whether any labels had to be nudged apart. */
 export declare interface DirectLabelsLayout<TPayload> {
-    /** Placements in ascending Y order. Items whose final Y falls outside the rect are omitted. */
     placements: Array<DirectLabelPlacement<TPayload>>;
     hasOverlap: boolean;
 }
@@ -2755,25 +2570,15 @@ declare type DiscreteScaleOptions<RangeValue extends number | string = number |
 declare type DiscreteScaleSpec = Required<DiscreteScaleInput>;
 
 /** A value format with no inner lookups. Lookup cases and fallbacks are constrained to this so a `lookup` cannot nest another `lookup` at the type level. */
-export declare type ExplicitValueFormat = TemporalValueFormat | NumericValueFormat | CurrencyValueFormat | CategoricalValueFormat;
+declare type ExplicitValueFormat = TemporalValueFormat | NumericValueFormat | CurrencyValueFormat | CategoricalValueFormat;
 
-/**
- * Measured heights of content regions (header: title+subtitle, footer: caption). The caller measures
- * the already-rendered header/footer DOM and feeds these back; only the HEIGHTS are read (widths are
- * ignored, since those regions span the full width). Expect a zero-size first pass before the DOM has
- * mounted, then a second compile once real heights are known.
- */
+/** Measured heights of content regions (header: title+subtitle, footer: caption). */
 export declare interface ExternalMeasurements {
     headerSize: BoxSize;
     footerSize: BoxSize;
 }
 
-/**
- * Flattens a title, subtitle, or caption to plain text by concatenating every leaf `text` node with
- * no separators. Block boundaries (paragraphs, list items, line breaks) are intentionally dropped —
- * the result feeds text measurement and static fallbacks, not display, so it must not be shown as the
- * formatted heading.
- */
+/** Flattens a title, subtitle, or caption to plain text for measurement and static renderers. */
 export declare const extractPlainText: (content: TextContent) => string;
 
 declare function filter(options: FilterOptions): FilterTransformInput;
@@ -2802,10 +2607,6 @@ declare interface FilterTransformInput {
  * Lookups go through `scaleAestheticKey`, not `aesthetic`: `ySecondary` shares
  * `aesthetic === 'y'` with the primary y axis, so matching on aesthetic would return the wrong
  * axis for layers with `yScaleType: 'secondary'`.
- *
- * Pair with `resolveYScaleAesthetic` (scale.constants.ts) to find a layer's axis:
- * `findAxisGuide(guides, resolveYScaleAesthetic(layer.yScaleType))` resolves a secondary-y layer to
- * the `ySecondary` guide.
  */
 export declare function findAxisGuide(guides: CompiledGuides, scaleAestheticKey: ScaledAestheticKey): CompiledAxisGuide | null;
 
@@ -2830,50 +2631,30 @@ declare interface FlipCoordSpec {
     params: BaseCoordParams;
 }
 
-/**
- * The font a `TextMeasurer` measures against. Both `family` and `size` are required: a
- * measurer backed by canvas `measureText` (or `buildFontString`) needs a concrete family and
- * pixel size to return real metrics, so an incomplete spec silently yields wrong measurements.
- */
 export declare interface FontSpec {
-    /** CSS font family (e.g. `'Inter'`). Required — there is no fallback family. */
     family: string;
-    /**
-     * Final font size in pixels. Named `size`, not `fontSize`. The caller has already applied text-scale
-     * and any em → px conversion, so a measurer (and the renderer) must use this as-is — do not re-scale.
-     */
     size: number;
     weight?: NamedWeightKey | number;
     style?: 'normal' | 'italic' | 'oblique';
 }
 
 /**
- * Composes a compiled headline guide into final display strings: locale-formatted figures, the
- * English aggregate prefix, the series/measure name, the trend percentage, and main-axis labels.
- * Every field on the result is render-verbatim (see {@link FormattedHeadlineItem}); the renderer adds
- * only the arrow/colour implied by the trend `direction`. Returns null when there is no headline.
+ * Composes a compiled headline guide into display strings: locale-formatted figures, the English
+ * aggregate prefix, the series/measure name, the trend percentage, and main-axis labels.
  */
-export declare const formatHeadline: ({ headline, show, numberFormat, parsingLocale, formattingLocale, t, }: FormatHeadlineInput) => FormattedHeadline | null;
+export declare const formatHeadline: ({ headline, show, numberFormat, parsingLocale, formattingLocale, }: FormatHeadlineInput) => FormattedHeadline | null;
 
-/** Inputs to {@link formatHeadline}. `formattingLocale` overrides `parsingLocale` for display when the two differ. */
 export declare interface FormatHeadlineInput {
     headline: CompiledHeadlineGuide | null;
     /** Aggregate mode, read from `config.headline.show` — it isn't duplicated onto the guide. */
     show: HeadlineShow;
     numberFormat: NumberFormatConfig;
     parsingLocale: Locale;
-    /**
-     * Display-locale override: `locale = formattingLocale ?? parsingLocale`. The supported set is small
-     * ('en-GB', 'en-US', 'ar', 'pt-PT'); a `duration` figure always formats in English regardless.
-     */
     formattingLocale?: Locale;
-    t: Translator;
 }
 
 /**
- * Formats all legend guides by attaching a `formattedLabel` to each item. Item order is preserved
- * from the compiled guide — canonical scale-domain order — and consumers must keep it (tooltips and
- * swatch lists read top-to-bottom in this order).
+ * Formats all legend guides by attaching a `formattedLabel` to each item.
  */
 export declare const formatLegends: ({ legends, numberFormat, parsingLocale, formattingLocale, }: FormatLegendsInput) => FormattedLegend[];
 
@@ -2881,18 +2662,12 @@ declare interface FormatLegendsInput {
     legends: readonly CompiledLegendGuide[];
     numberFormat: NumberFormatConfig;
     parsingLocale: Locale;
-    /**
-     * Display-locale override: `locale = formattingLocale ?? parsingLocale`. The supported set is small
-     * ('en-GB', 'en-US', 'ar', 'pt-PT'); a `duration` label always formats in English regardless.
-     */
     formattingLocale?: Locale;
 }
 
 /**
- * Formats a rule layer's underlying numeric value with the same value formatter as the axis the rule
- * anchors to: y-rules use the y-axis; x-rules use x. Takes the rule's own `CompiledLayerFor<'rule'>`
- * and returns ONLY the formatted value — or null when the rule has no observation or a null value.
- * The caller composes it with the rule's label text (this helper does not).
+ * Formats a rule's underlying numeric value with the same value formatter as the axis the rule
+ * anchors to: y-rules use the y-axis; x-rules use x.
  */
 export declare const formatRuleValue: ({ guides, numberFormat, layer, locale }: FormatRuleValueInput) => string | null;
 
@@ -2903,17 +2678,7 @@ declare interface FormatRuleValueInput {
     locale: Locale;
 }
 
-/**
- * An axis guide with each tick's label composed into a display string, plus rotation and truncation
- * hints. Produced by `LayoutCompiler.compile()`, which runs the final two-phase tick selection
- * (picking the densest candidate set whose labels fit) — so by the time a renderer sees this the
- * ticks are settled. Do not re-select candidates or re-apply a `ValueFormat`.
- */
 export declare interface FormattedAxis extends Omit<CompiledAxisGuide, 'tickCandidates'> {
-    /**
-     * The chosen ticks, each carrying its composed display string in `formattedLabel`. The label is
-     * already locale-formatted — render it verbatim.
-     */
     ticks: Array<AxisTick & {
         formattedLabel: string;
     }>;
@@ -2923,10 +2688,6 @@ export declare interface FormattedAxis extends Omit<CompiledAxisGuide, 'tickCand
     labelMaxWidthPx: number | null;
 }
 
-/**
- * A headline showing a single grand-total number, used for polar charts. `value` is a bare final
- * display string — no prefix, label, or swatch accompanies it; render it verbatim.
- */
 export declare interface FormattedGrandTotalHeadline {
     kind: 'grandTotal';
     value: string;
@@ -2938,21 +2699,15 @@ export declare interface FormattedGrandTotalHeadline {
  */
 export declare type FormattedHeadline = FormattedPerGroupHeadline | FormattedGrandTotalHeadline;
 
-/** A headline's trend versus a reference observation, formatted for display. */
 export declare interface FormattedHeadlineComparison {
-    /** Movement direction — the only place the sign lives; drives the renderer's arrow and colour. */
+    /** Movement direction — drives the renderer's arrow and colour. */
     direction: HeadlineTrendDirection;
-    /** Unsigned magnitude of the variation as a locale percentage, e.g. "20%" (sign comes from `direction`). */
+    /** Absolute variation as a locale percentage, e.g. "20%". */
     percentage: string;
     /** Reference observation label, e.g. "from Feb 2025". */
     reference: string;
 }
 
-/**
- * A single headline figure: its name, formatted value, observation label and optional trend
- * comparison. Every string field is final and display-ready (English-only — the aggregate prefix,
- * name, figure, and trend are already composed); render them verbatim, do not recompose or relocalize.
- */
 export declare interface FormattedHeadlineItem {
     /** Group swatch, passed through from the compiled item (present only at ≥2 groups). */
     swatch: HeadlineGroupSwatch | null;
@@ -2966,15 +2721,12 @@ export declare interface FormattedHeadlineItem {
     comparison: FormattedHeadlineComparison | null;
 }
 
-/** A legend guide with each item's label composed into a display string. */
 export declare interface FormattedLegend extends Omit<CompiledLegendGuide, 'items'> {
-    /** Legend entries, each carrying its composed display string in `formattedLabel`. */
     items: Array<LegendItem & {
         formattedLabel: string;
     }>;
 }
 
-/** A headline showing one labelled figure per group (e.g. one per series). */
 export declare interface FormattedPerGroupHeadline {
     kind: 'perGroup';
     items: FormattedHeadlineItem[];
@@ -2987,9 +2739,7 @@ export declare interface FormattedPerGroupHeadline {
  */
 export declare interface FreeformArrowInput {
     id?: string;
-    /** Tail endpoint. */
     start: ArrowEndpoint;
-    /** Head endpoint. */
     end: ArrowEndpoint;
     /** null falls back to the theme `defaultAnnotationArrowStroke`. */
     color?: string | null;
@@ -2997,11 +2747,9 @@ export declare interface FreeformArrowInput {
     startArrowheadStyle?: ArrowheadStyle;
     endArrowheadStyle?: ArrowheadStyle;
     lineStyle?: ArrowLineStyle;
-    /** Render with a raised, outlined sticker-like appearance. */
     hasStickerStyle?: boolean;
 }
 
-/** Resolved freeform arrow with all optional fields defaulted. */
 export declare interface FreeformArrowSpec {
     id: string;
     start: ArrowEndpoint;
@@ -3032,14 +2780,113 @@ declare type GenerateTicksOptions = {
 
 /**
  * Base class for geoms that turn observations into visual marks (points, bars, lines etc).
+ *
+ * `TParams` is the geom's parameter type — the single source of truth the registration-typed builder
+ * reads to type `geom.<name>({ params })` and to default missing params. Built-ins leave it at the
+ * empty default and keep their typed params through the spec builder's static surface; a custom geom
+ * names its params type and declares matching {@link defaultParams}.
  */
-declare abstract class Geom {
-    readonly requiredAesthetics: AestheticKey[];
-    abstract readonly type: GeomName;
+declare abstract class Geom<TParams extends object = object> {
+    /**
+     * The aesthetics an author must map for this geom. Built-ins list closed aesthetic keys
+     * (`['x','y']`); a custom geom may also list open channel names (a box plot's `min`/`q1`/…) that it
+     * binds to scales through its {@link positionChannels}, so the registration-typed builder accepts and
+     * types them as `aes` keys instead of forcing the bindings into `params`.
+     */
+    readonly requiredAesthetics: readonly string[];
+    /**
+     * The params merged in by the registration-typed builder before a missing key would reach the geom.
+     * The default is empty; a custom geom overrides it with its definition's defaults, which doubles as
+     * the carrier that lets the builder recover `TParams` from the registered instance.
+     */
+    readonly defaultParams: TParams;
+    /**
+     * The position channels this geom produces. The position mapper and coord projection iterate this
+     * manifest instead of a hardcoded column set, so a geom's geometry is described by what it declares.
+     */
+    readonly positionChannels: readonly PositionChannel[];
+    /**
+     * The visual aesthetics this geom encodes (color, size, …). The visual mapper and legend iterate
+     * this declaration instead of a hardcoded set, so a geom's visual surface is described by what it
+     * declares. The default is the full vocabulary; a geom narrows it to the aesthetics it actually
+     * paints, and a custom aesthetic extends it (decision 10).
+     */
+    readonly visualAesthetics: readonly ScaledVisualAestheticKey[];
+    /**
+     * The swatch shape that evokes this geom's on-canvas mark in the legend and tooltip — its
+     * cartesian-natural shape. A polar coord refines a `square` mark to a `slice` (pie/donut wedge)
+     * at read time. Decoupled from `GeomName` so guides paint by what a geom declares, not its name.
+     */
+    readonly swatchShape: SwatchShape;
+    /**
+     * How this geom composes highlight matches above its base render, or `null` to opt out of
+     * highlighting. Read at layer compile and stamped onto `CompiledLayer.highlight.strategy`.
+     * Declared per geom so core resolves it from the definition, not a geom-keyed lookup.
+     */
+    readonly highlightStrategy: HighlightStrategy | null;
+    /**
+     * The spatial structure this geom's marks present for hit-testing — its cartesian-natural kind.
+     * Stamped onto `CompiledLayer.spatialMap`; a polar coord refines it to `arcs`. Declared per geom
+     * so the runtime builds the matching index from data, not by branching on the geom name.
+     */
+    readonly spatialKind: SpatialIndexKind;
+    /**
+     * Positions for which this geom supports direct (inline) series labels in the legend. Empty when
+     * the geom never shows them. The legend reads this from the definition, not a geom-keyed lookup.
+     */
+    readonly directLabelPositions: readonly PositionType[];
+    /**
+     * Grid/border visibility overrides this geom requests per coord type (e.g. a bar hides the
+     * categorical-axis grid). Empty when the geom imposes none. The axis guide reads these.
+     */
+    readonly gridPolicies: Partial<Record<CoordType, GridPolicy>>;
+    /**
+     * How this geom derives each observation's stable identity key: `'index'` (position by row, so
+     * marks morph smoothly on enter/exit) or `'fields'` (x value plus resolved series). The identity
+     * compiler reads this from the definition, not a geom-name check.
+     */
+    readonly identityKeyStrategy: 'index' | 'fields';
+    /**
+     * The coord types under which this geom has meaningful semantics. The layer validator rejects a
+     * layer whose coord is absent from this set (e.g. a rule has no polar interpretation). Declared per
+     * geom so the validator resolves support from the definition, not a geom-name check.
+     */
+    readonly supportedCoordTypes: readonly CoordType[];
+    /**
+     * Whether a non-stacked layer of this geom carries a layer-wide grand total (the signed sum of `y`,
+     * the pie/donut headline figure). The summarise stage runs the grand-total summariser only for geoms
+     * that declare this, so eligibility lives on the definition rather than a geom-name gate.
+     */
+    readonly emitsGrandTotal: boolean;
+    /**
+     * Whether a stacked layer of this geom carries per-x stack totals (the share-of-stack denominator).
+     * The summarise stage runs the stack-totals summariser only for geoms that declare this, so a stacked
+     * area (which writes the same interval columns) is excluded by declaration, not by a geom-name gate.
+     */
+    readonly emitsStackTotals: boolean;
+    /**
+     * Whether a layer of this geom contributes a per-group headline figure. The headline guide builds a
+     * per-group strip only when an eligible geom is present, reading this from the definition rather than
+     * a membership list of geom names (so a reference-line geom, which is an annotation, opts out).
+     */
+    readonly supportsPerGroupHeadline: boolean;
+    abstract readonly type: GeomIdentity;
+    /**
+     * Where an annotation anchored to the given observation sits, in normalised panel space, or `null`
+     * when this geom does not support anchoring (the default). The annotations compiler resolves anchors
+     * through this method rather than branching on geom name; the returned `geom` discriminant tells the
+     * renderer how to place the annotation.
+     */
+    resolveAnchorPosition(_observation: Observation, _coordSystem: CoordSystem): AnchorPosition | null;
     abstract compile(input: GeomCompilerInput): CompiledGeom;
+    /**
+     * Validates the layer's mapping against invariants specific to this geom (e.g. a rule needs exactly
+     * one numeric axis). Returns the issues found; omit the method when the geom imposes no mapping
+     * invariant. The layer validator dispatches here instead of branching on geom name.
+     */
+    validateMapping?(input: GeomMappingValidationInput): ValidationIssue[];
 }
 
-/** Factories for the geometry layers a chart can draw (point, line, area, bar, rule). */
 export declare const geom: {
     point: typeof point;
     line: typeof line;
@@ -3048,13 +2895,55 @@ export declare const geom: {
     rule: typeof rule;
 };
 
+/**
+ * The built-in geometric marks. The single source for both the {@link GeomName} type and the runtime
+ * {@link BUILTIN_GEOM_NAMES} set used to tell a built-in name from a custom registration.
+ *
+ * - `'point'` — Scatter-style dot marks
+ * - `'line'` — Connected line marks
+ * - `'area'` — Filled area marks
+ * - `'bar'` — Rectangular bar marks
+ * - `'rule'` — Horizontal or vertical reference line at a constant value
+ */
+export declare const GEOM_NAMES: readonly ["point", "line", "area", "bar", "rule"];
+
 /**
  * Resolves a geom by name and delegates compilation.
  */
 declare class GeomCompiler {
     private readonly registry;
     constructor(registry: GeomRegistry);
-    compile(geomName: GeomName, input: GeomCompilerInput): CompiledGeom;
+    compile(geomName: GeomIdentity, input: GeomCompilerInput): CompiledGeom;
+    /**
+     * The geom's declared position-channel manifest — the contract the position adjuster gate reads to
+     * decide whether an adjustment applies to this geom.
+     */
+    getPositionChannels(geomName: GeomIdentity): readonly PositionChannel[];
+    /**
+     * The geom's declared swatch shape — the legend/tooltip mark the guides paint for it. The coord
+     * refinement (a polar `square` becomes a `slice`) is applied by the reader, not here.
+     */
+    getSwatchShape(geomName: GeomIdentity): SwatchShape;
+    /** The geom's declared spatial-index kind — the hit-test structure its marks present. */
+    getSpatialKind(geomName: GeomIdentity): SpatialIndexKind;
+    /** The visual aesthetics this geom encodes — the set the visual mapper and legend iterate. */
+    getVisualAesthetics(geomName: GeomIdentity): readonly ScaledVisualAestheticKey[];
+    /** The geom's declared highlight composition strategy, or `null` when it opts out of highlighting. */
+    getHighlightStrategy(geomName: GeomIdentity): HighlightStrategy | null;
+    /** The positions for which the geom supports direct (inline) legend labels. */
+    getDirectLabelPositions(geomName: GeomIdentity): readonly PositionType[];
+    /** The grid/border visibility overrides the geom requests per coord type. */
+    getGridPolicies(geomName: GeomIdentity): Partial<Record<CoordType, GridPolicy>>;
+    /** How the geom derives its observation identity key — `'index'` or `'fields'`. */
+    getIdentityKeyStrategy(geomName: GeomIdentity): 'index' | 'fields';
+    /** Whether a non-stacked layer of this geom carries a layer-wide grand total. */
+    emitsGrandTotal(geomName: GeomIdentity): boolean;
+    /** Whether a stacked layer of this geom carries per-x stack totals. */
+    emitsStackTotals(geomName: GeomIdentity): boolean;
+    /** Whether a layer of this geom contributes a per-group headline figure. */
+    supportsPerGroupHeadline(geomName: GeomIdentity): boolean;
+    /** Where an annotation anchored to the observation sits, or `null` when the geom does not anchor. */
+    resolveAnchorPosition(geomName: GeomIdentity, observation: Observation, coordSystem: CoordSystem): AnchorPosition | null;
 }
 
 declare interface GeomCompilerInput {
@@ -3067,18 +2956,29 @@ declare interface GeomCompilerInput {
 }
 
 /**
- * The type of geometric mark used to represent data in a layer.
- *
- * - `'point'` — Scatter-style dot marks
- * - `'line'` — Connected line marks
- * - `'area'` — Filled area marks
- * - `'bar'` — Rectangular bar marks
- * - `'rule'` — Horizontal or vertical reference line at a constant value
- *
- * A mark's geometry is the `(geom, coordSystem.type)` pair, not geom alone — a `bar` is a rect in
- * cartesian and an arc in polar — so renderers dispatch on the pair.
+ * Open geom identity: the built-in vocabulary plus any custom registration's `type`. The layer types,
+ * the compiled layer, and the geom registry key on this so a registered custom geom is a first-class
+ * mark; the built-in literals stay for autocomplete. Core never *decides* on the name (the decisions
+ * live on the geom definition) — this is purely the identity a layer carries.
+ */
+export declare type GeomIdentity = GeomName | (string & {});
+
+/**
+ * Input to a geom's mapping validation. The validator resolves the stat-computed aesthetics and the
+ * effective mapping, so the geom only expresses its own invariant (e.g. a rule needs exactly one
+ * numeric axis) without reaching for a registry.
  */
-export declare type GeomName = 'point' | 'line' | 'area' | 'bar' | 'rule';
+declare interface GeomMappingValidationInput {
+    /** Layer id, for issue attribution. */
+    layerId: string;
+    /** The effective mapping: spec mapping merged with the layer's. */
+    mapping: AesMapping;
+    /** Aesthetics a stat computes at compile time, so a missing literal there is not an error. */
+    computedVariables: ReadonlySet<AestheticKey>;
+}
+
+/** A built-in geom's name — the default vocabulary the spec builder offers out of the box. */
+export declare type GeomName = (typeof GEOM_NAMES)[number];
 
 declare type GeomOptions<G extends GeomName> = BaseGeomOptions<GeomParamsMap[G]>;
 
@@ -3096,64 +2996,42 @@ declare interface GeomParamsMap {
 }
 
 /**
- * Built-in geom implementations keyed by {@link GeomName}.
+ * Geom implementations keyed by their open `type` — the built-ins by default, with any injected
+ * custom geoms overlaid last-write-wins. The key is `string`, not the closed `GeomName`, so a custom
+ * registration is a first-class entry.
  */
-declare class GeomRegistry extends Registry<GeomName, Geom> {
-    constructor();
+declare class GeomRegistry extends Registry<string, Geom> {
+    constructor(opts?: {
+        geoms?: readonly Geom[];
+    });
 }
 
 /**
- * Reads the resolved alpha (opacity) value from an observation, in `[0, 1]`.
- *
- * `null` / `undefined` ⇒ unmapped — apply the geom default. A series (line / area) shares one
- * resolved value across its rows; read it from the first observation.
+ * One extra tooltip row a geom contributes for the hovered observation — a named reading of a data
+ * column the standard one-row-per-series tooltip would not surface on its own. An OHLC candle, for
+ * instance, declares four (open/high/low/close); the compiler derives each row's display format from
+ * the column and the renderer materialises the values for the observation under the cursor. Pure
+ * data: the `label` is static text and the `variable` names a column, so the rows ride in the
+ * serialisable compiled spec.
  */
+declare interface GeomTooltipRow {
+    /** The row's label (e.g. "Open"). Static text the geom supplies. */
+    label: string;
+    /** The data column whose per-observation value the row displays. */
+    variable: VariableName;
+}
+
+/** Reads the resolved alpha (opacity) value from an observation. */
 export declare function getAlpha(observation: Observation): NumericDataValue;
 
-/**
- * Reads a polar arc's angular sweep. In polar layers the x position columns are repurposed as
- * angles: absolute radians, `startAngle` already applied, clockwise from 12 o'clock — matching the
- * polar transform, `HoverHit`'s polar convention, and d3-shape `arc()`. Pass the values through
- * unmodified. Either field `null` ⇒ skip the arc.
- */
 export declare function getAngleExtent(observation: Observation): AngleExtent;
 
-/**
- * Reports whether a bar geom's baseline falls outside the value scale's visible domain. When it
- * does, bar lengths are truncated at the panel edge and no longer encode their values to scale, so
- * renderers can fade the clipped edge to signal the truncation.
- *
- * Returns `null` for non-continuous or reversed value scales, where a single clipped edge is not
- * well defined.
- */
-export declare const getBarBaselineClip: (valueScale: CompiledScale | undefined) => BarBaselineClip;
-
-/**
- * Normalized data-space bounds for a bar observation in [0, 1]² with origin at the top-left
- * (matches SVG conventions used by overlay renderers). Negative values flip the rect upside-down
- * so callers don't need to know whether the bar grows up or down from its baseline.
- *
- * `mainAxis` selects which data axis separates bars (bar length runs along the cross axis). For
- * `'x'` bars grow vertically; for `'y'` (flipped) they grow horizontally and the cross-axis
- * extent can be negative for negative values.
- */
-export declare const getBarRectBounds: (mainAxis: MainAxis, observation: Observation) => Rect | null;
-
-/**
- * Reads the resolved color string from an observation.
- *
- * `undefined` ⇒ unmapped — the renderer supplies its geom default fill. A series (line / area)
- * shares one resolved value across its rows; read it from the first observation.
- */
+/** Reads the resolved color string from an observation. */
 export declare function getColor(observation: Observation): string | undefined;
 
 /** Reads the coordinate lying on the cross axis of the coord system. */
 export declare function getCrossAxisCoordinate(mainAxis: MainAxis, point: XYPoint): number;
 
-export declare const getCurve: (interpolate: InterpolateType) => CurveFactory;
-
-export declare const getDashArray: (lineType: LineStyleType) => string | undefined;
-
 /**
  * Returns pixel dimensions for a difference arrow at the requested size.
  *
@@ -3162,65 +3040,30 @@ export declare const getDashArray: (lineType: LineStyleType) => string | undefin
  */
 export declare const getDifferenceArrowDimensions: (size: DifferenceArrowSize, textScale: number) => DifferenceArrowDimensions;
 
-/**
- * Reads the series-grouping key written onto an observation during compilation.
- *
- * Connected geoms (line, area, polar arc) must partition observations by this key —
- * `data.groupBy(GROUP_VARIABLES.group)` — and emit one mark per group; per-mark geoms (bar, point)
- * iterate `data` directly. Visual channels are constant within a group, so read them from the
- * first observation.
- */
 export declare const getGroup: (observation: Observation) => CategoricalDataValue;
 
-export declare function getHoverGuideLineProps(coordSystem: CartesianCoordSystem, primary: XYPoint): HoverGuideLineProps;
-
-export declare function getHoverGuideRectProps(coordSystem: CartesianCoordSystem, scales: CompiledSpec['scales'], primary: HoverHit): HoverGuideRectProps | null;
+/**
+ * Reads the stable identity key the compiler emits for each observation. Surfaces that need a
+ * mark's identity (animation data-join, linked selection, reading order) read this one key rather
+ * than reconstructing their own.
+ */
+export declare const getIdentityKey: (observation: Observation) => string;
 
 /**
  * Reads the resolved line type (stroke style) from an observation.
  * Falls back to `'solid'` when no `lineType` variable was derived.
- *
- * A series (line / area) shares one resolved value across its rows; read it from the first
- * observation.
  */
 export declare function getLineType(observation: Observation): LineStyleType;
 
 /** Reads the coordinate lying on the main (independent) axis of the coord system. */
 export declare function getMainAxisCoordinate(mainAxis: MainAxis, point: XYPoint): number;
 
-/**
- * Resolves a `FontSpec` weight to its numeric CSS value, the form a text-measurement cache key needs.
- * A number passes through; a named weight maps via {@link NAMED_WEIGHTS}; an omitted weight falls back
- * to {@link DEFAULT_FONT_WEIGHT}. A from-scratch measurer must resolve weights the same way to share
- * cache keys with the engine.
- */
-export declare const getNumericWeight: (weight: NamedWeightKey | number | undefined) => number;
-
-/**
- * Reads a polar arc's radial extent. In polar layers the y position columns are repurposed as
- * radii: fractions (`[0, 1]`) of the outer radius. The renderer maps these into a unit circle and
- * lets the browser scale it to pixels (no manual multiply by a panel radius). Either field `null`
- * ⇒ skip the arc.
- */
 export declare function getRadiusExtent(observation: Observation): RadiusExtent;
 
-/**
- * Reads the resolved size value from an observation — a nominal diameter (points halve it for the
- * marker radius).
- *
- * `null` / `undefined` ⇒ unmapped — apply the geom default. A series (line / area) shares one
- * resolved value across its rows; read it from the first observation.
- */
+/** Reads the resolved size value from an observation. */
 export declare function getSize(observation: Observation): NumericDataValue;
 
-export declare const getStablePolarBarKeyGenerator: () => ((observation: Observation, index: number) => string);
-
-/**
- * Reads the resolved stroke width value from an observation, in pixels.
- *
- * `null` / `undefined` ⇒ unmapped — apply the geom default. A series (line / area) shares one
- * resolved value across its rows; read it from the first observation.
- */
+/** Reads the resolved stroke width value from an observation. */
 export declare function getStrokeWidth(observation: Observation): NumericDataValue;
 
 declare interface GetValuesOptions {
@@ -3232,71 +3075,35 @@ declare interface GetValuesOptions {
     distinct?: boolean;
 }
 
-/**
- * Reads the normalized x position (band center) from an observation.
- *
- * Normalized to [0,1]: x is 0=left…1=right, y is 0=bottom…1=top (data-up). SVG / top-origin
- * renderers invert y as `1 - y`.
- */
+/** Reads the normalized x position from an observation. */
 export declare function getX(observation: Observation): NumericDataValue;
 
-/**
- * Reads the normalized xMax (right band edge) from an observation.
- *
- * Written only for extent-bearing geoms (bars, stacked / range area); returns `null` otherwise —
- * fall back to {@link getX} (the band center). Per geom: bar = rect band edge + bar length,
- * area = cross-axis fill bound; point / line leave it unused.
- */
+/** Reads the normalized xMax (right band edge) from an observation. */
 export declare function getXMax(observation: Observation): NumericDataValue;
 
-/**
- * Reads the normalized xMin (left band edge) from an observation.
- *
- * Written only for extent-bearing geoms (bars, stacked / range area); returns `null` otherwise —
- * fall back to {@link getX} (the band center). Per geom: bar = rect band edge, area = cross-axis
- * fill bound; point / line leave it unused.
- */
+/** Reads the normalized xMin (left band edge) from an observation. */
 export declare function getXMin(observation: Observation): NumericDataValue;
 
-/**
- * Reads the normalized y position (band center) from an observation.
- *
- * Normalized to [0,1]: x is 0=left…1=right, y is 0=bottom…1=top (data-up). SVG / top-origin
- * renderers invert y as `1 - y`.
- */
+/** Reads the normalized y position from an observation. */
 export declare function getY(observation: Observation): NumericDataValue;
 
-/**
- * Reads the normalized yMax (upper extent) from an observation.
- *
- * Written only for extent-bearing geoms (bars, stacked / range area); returns `null` otherwise —
- * fall back to {@link getY} (the band center). Per geom: bar = rect band edge + bar length,
- * area = cross-axis fill bound; point / line leave it unused.
- */
+/** Reads the normalized yMax (upper extent) from an observation. */
 export declare function getYMax(observation: Observation): NumericDataValue;
 
-/**
- * Reads the normalized yMin (lower extent) from an observation.
- *
- * Written only for extent-bearing geoms (bars, stacked / range area); returns `null` otherwise —
- * fall back to {@link getY} (the band center). Per geom: bar = rect band edge, area = cross-axis
- * fill bound; point / line leave it unused.
- */
+/** Reads the normalized yMin (lower extent) from an observation. */
 export declare function getYMin(observation: Observation): NumericDataValue;
 
 /**
  * Reads the segment value written by stacking position adjusters.
  *
- * Survives the position-mapper untouched, so renderers can recover original-unit values
+ * Survives theposition-mapper untouched, so renderers can recover original-unit values
  * for stacked segments after `mapping.y` has been rewritten to the cumulative band top.
  */
 export declare function getYRaw(observation: Observation): NumericDataValue;
 
 /** Goal line with a target value. */
 declare interface GoalLine {
-    /** Value on the measure axis where the line is drawn. */
     target: number;
-    /** Category value at which to anchor an optional marker on the line. */
     marker?: DataValue;
     label?: string;
 }
@@ -3306,10 +3113,8 @@ declare type GraphAnnotation = GraphStickerAnnotation | GraphTooltipAnnotation |
 declare interface GraphArrowAnnotation {
     id: string;
     type: 'arrow';
-    /** Tail position as fractions (0-1) of the plot width and height. */
     startX: number;
     startY: number;
-    /** Head position as fractions (0-1) of the plot width and height. */
     endX: number;
     endY: number;
     color?: string;
@@ -3317,22 +3122,15 @@ declare interface GraphArrowAnnotation {
     startArrowheadStyle: 'none' | 'line-arrow';
     lineStyle: 'solid' | 'dashed';
     endArrowheadStyle: 'none' | 'line-arrow';
-    /** Adds a white outline so the arrow reads as a sticker on top of the chart. */
     hasStickerStyle: boolean;
 }
 
-/**
- * The full set of options a consumer passes to configure a chart's type, styling, axes, and content.
- * Every field is optional, so omitted settings fall back to engine defaults.
- */
 export declare interface GraphConfig {
     type?: GraphType;
-    /** Geometry-specific settings, unioned across all chart types. */
     options?: Options;
     axes?: Axes;
     legend?: Legend;
     appearance?: Appearance;
-    /** Ad-hoc overrides of individual theme tokens, plus a shortcut for the chart background. */
     themeOverrides?: {
         [key: string]: unknown;
         graphBackground?: string;
@@ -3347,33 +3145,25 @@ export declare interface GraphConfig {
 declare interface GraphDifferenceArrowAnnotation {
     id: string;
     type: 'difference-arrow';
-    /** How the gap between the two points is expressed in the label. */
     show: 'absolute-difference' | 'relative-difference' | 'proportion';
     start: AnnotationDataPoint;
     end: AnnotationDataPoint;
     color?: string;
     size: 'medium' | 'small' | 'large';
-    /** Position of the label along the arrow as a fraction (0-1) from start to end. */
     labelPosition?: number;
 }
 
 declare type GraphHighlightAnnotation = {
     id: string;
     type: 'highlight';
-    /** Scope of the emphasis: a single point, a whole series, or all points at one x value. */
     highlight: 'data-point' | 'series' | 'x-value';
 } & AnnotationDataPoint;
 
 /** Output of the layout computation. */
 export declare interface GraphLayout {
-    /** The full graphical area: panel + axes + axis labels, excluding header and footer. */
+    /** The full graphical area (axes + panel + axis labels), excluding header and footer. */
     plot: Rect;
-    /**
-     * The panel area where geom layers render i.e. the data rectangle inside the axes. Strictly nested
-     * inside {@link GraphLayout.plot}. Geoms paint here in normalized `[0,1]` data space with y inverted
-     * (data y=0 sits at the panel bottom), so map a data point to `panel.x + x * panel.width` and
-     * `panel.y + (1 - y) * panel.height`.
-     */
+    /** The panel area where geom layers render i.e. the data rectangle inside the axes. */
     panel: Rect;
     /** Rects for axis regions (ticks + tick labels), keyed by edge. */
     axes: Partial<Record<LayoutEdge, Rect>>;
@@ -3393,16 +3183,12 @@ declare interface GraphShapeAnnotation {
     id: string;
     type: 'shape';
     shape: 'rectangle';
-    /** Whether the shape is drawn behind or in front of the plotted data. */
     layer: 'belowPlot' | 'abovePlot';
-    /** Top-left position as fractions (0-1) of the plot width and height. */
     x: number;
     y: number;
-    /** Size as fractions (0-1) of the plot width and height. */
     width: number;
     height: number;
     fillColor: string;
-    /** Fill opacity from 0 (transparent) to 1 (opaque). */
     fillOpacity: number;
     strokeWidth: number;
 }
@@ -3417,35 +3203,24 @@ declare interface GraphTextAnnotation {
     id: string;
     type: 'text';
     content: RichTextContent;
-    /** Left position as a fraction (0-1) of the plot width. */
     x: number;
-    /** Top position as a fraction (0-1) of the plot height. */
     y: number;
-    /** Box width as a fraction (0-1) of the plot width; text wraps within it. */
     width: number;
     backgroundColor?: string;
-    /** Whether the background is semi-transparent ('fade') or fully opaque. */
     backgroundColorStyle?: 'fade' | 'opaque';
 }
 
 declare interface GraphTextStyle {
-    /** Id of a font registered with the engine; resolved to a concrete family at compile time. */
     fontId?: string;
     color?: string;
 }
 
-/**
- * Active light or dark mode. Selects the full theme token set used when resolving theme-dependent
- * colors, and sets the direction tints and gradients adjust in (lighten on dark, darken on light) —
- * see the `'tinted'`/`'gradient'` variants of {@link BackgroundConfig} and {@link BorderConfig}.
- */
 export declare type GraphTheme = 'light' | 'dark';
 
 declare type GraphTooltipAnnotation = {
     id: string;
     type: 'tooltip';
-    /** Tooltip body as TipTap rich-text content; omit or `null` for a pinned-number annotation (no caption). */
-    caption?: RichTextContent | null;
+    caption: unknown;
 } & AnnotationDataPoint;
 
 /** Type of graph to use for the data. */
@@ -3456,16 +3231,19 @@ declare type GraphyPaletteConfig = {
     variant?: GraphyPaletteVariant;
 };
 
-/** `waterfall` swaps in the positive/negative/total colors used by waterfall charts. */
 declare type GraphyPaletteVariant = 'default' | 'waterfall';
 
 /**
- * Internal column name holding each observation's series-grouping key.
- *
- * Connected geoms (line, area, polar arc) partition observations on `group`
- * (`data.groupBy(GROUP_VARIABLES.group)`) to emit one mark per series; per-mark geoms (bar, point)
- * iterate the dataset directly. Read via `getGroup`.
+ * Grid/border visibility a geom requests per coord type — a bar hides the categorical-axis grid,
+ * for instance. A geom declares these so the axis guide resolves grid policy from the definition
+ * instead of a geom-keyed lookup. Every field absent means the geom imposes no policy.
  */
+declare interface GridPolicy {
+    hideGridX?: boolean;
+    hideGridY?: boolean;
+    hideBorder?: boolean;
+}
+
 export declare const GROUP_VARIABLES: {
     readonly group: string;
 };
@@ -3518,6 +3296,8 @@ declare type GroupedVariableNames = {
  * influences axis placement.
  */
 declare class GuideCompiler extends Stage<GuideCompilerInput, CompiledGuides> {
+    private readonly geomCompiler;
+    constructor(geomCompiler: GeomCompiler);
     protected dependencies(input: GuideCompilerInput): readonly unknown[];
     protected run(input: GuideCompilerInput): CompiledGuides;
 }
@@ -3542,24 +3322,8 @@ declare interface GuideCompilerInput {
  */
 declare type GuideConfig = Pick<ConfigSpec, 'axes' | 'legend' | 'headline' | 'panel'>;
 
-/** Geometric shape an axis traces: a straight line, a full circle, or a spoke from the centre. */
 declare type GuideGeometry = 'linear' | 'circular' | 'radial';
 
-/** Gap between the swatch and its group label, in pixels. */
-export declare const HEADLINE_SWATCH_GAP = 4;
-
-/** Side length of the colour swatch in a headline group row, in pixels. */
-export declare const HEADLINE_SWATCH_SIZE = 12;
-
-/** Gap between trend segments (arrow, percentage, reference), in pixels. */
-export declare const HEADLINE_TREND_GAP = 4;
-
-/** Side length of the trend arrow icon, in pixels. */
-export declare const HEADLINE_TREND_ICON_SIZE = 12;
-
-/** Gap between the value figure and its observation label, in pixels. */
-export declare const HEADLINE_VALUE_LABEL_GAP = 4;
-
 /**
  * Comparison reference for trend indicator
  * - 'previous': Compare to preceding data point
@@ -3604,9 +3368,6 @@ declare interface HeadlineConfig {
     position: HeadlinePosition;
 }
 
-/** Which font token a text segment renders at: the large figure or the smaller chrome. */
-export declare type HeadlineFontRole = 'value' | 'label';
-
 declare interface HeadlineGroupSwatch {
     color: string;
     shape: SwatchShape;
@@ -3633,24 +3394,14 @@ declare interface HeadlineItem {
     comparison: HeadlineComparison | null;
 }
 
-/**
- * What the layout needs to measure, size, and place a headline. Passing this only RESERVES the headline
- * band during compile — it does not place the headline. To paint it, the renderer must call
- * {@link resolveHeadlinePlacement} with the resolved {@link GraphLayout} for the paint rect, size, and
- * visible-item count.
- */
+/** What the layout needs to measure, size, and place a headline. */
 export declare interface HeadlineLayoutInput {
-    /** The headline content to render, already resolved into a strip or grand-total shape. */
     formatted: FormattedHeadline;
     /** Configured size token; `'auto'` resolves to the largest that fits. */
     size: HeadlineSize;
     /** Configured polar placement; only consulted for a grand total. */
     position: HeadlinePosition;
-    /**
-     * Donut hole radius as a fraction of the outer radius; the caller builds it from the coord system as
-     * `polar ? coordSystem.innerRadius : 0`. A centred grand total with `innerRadius > 0` overlays the
-     * donut hole instead of reserving a strip band.
-     */
+    /** Donut hole radius as a fraction of the outer radius; `0` for non-polar. */
     innerRadius: number;
 }
 
@@ -3666,9 +3417,7 @@ export declare interface HeadlineMeasurer {
 }
 
 declare interface HeadlineNumbers {
-    /** Which aggregate to surface as the big headline figure. */
     show?: 'current' | 'average' | 'total' | 'conversion' | 'none';
-    /** Baseline the headline is compared against to compute the change indicator. */
     compareWith?: 'previous' | 'first' | 'none';
     size?: 'auto' | 'small' | 'medium' | 'large';
 }
@@ -3702,32 +3451,6 @@ export declare interface HeadlinePlacement {
  */
 export declare type HeadlinePosition = 'above' | 'center';
 
-export declare interface HeadlineRow {
-    role: HeadlineRowRole;
-    gap: number;
-    segments: HeadlineSegment[];
-    ariaLabel?: string;
-}
-
-/** Which row a segment stacks into, aligned with the renderer's CSS class names. */
-export declare type HeadlineRowRole = 'valueRow' | 'trendRow' | 'groupRow';
-
-export declare type HeadlineSegment = {
-    kind: 'text';
-    textRole: HeadlineTextRole;
-    fontRole: HeadlineFontRole;
-    text: string;
-    trendDirection?: HeadlineTrendDirection;
-} | {
-    kind: 'swatch';
-    swatch: HeadlineSwatch;
-    size: number;
-} | {
-    kind: 'trendArrow';
-    direction: HeadlineTrendDirection;
-    size: number;
-};
-
 /**
  * Display mode for headline numbers
  * - 'total': Sum of all values
@@ -3747,16 +3470,6 @@ export declare type HeadlineShow = 'total' | 'average' | 'current' | 'conversion
  */
 export declare type HeadlineSize = 'auto' | 'small' | 'medium' | 'large';
 
-declare type HeadlineSwatch = NonNullable<FormattedHeadlineItem['swatch']>;
-
-/** Which styled span a text segment maps to (drives its CSS class and colour). */
-export declare type HeadlineTextRole = 'value' | 'observation' | 'label' | 'trendPercentage' | 'trendReference';
-
-/**
- * Direction of a headline's trend, and the SOLE source of the comparison's sign — drive both the
- * arrow and the colour off it, since `percentage` is unsigned. `flat` is neutral, so render it
- * without a good/bad colour or a directional arrow.
- */
 export declare type HeadlineTrendDirection = 'up' | 'down' | 'flat';
 
 /**
@@ -3783,18 +3496,6 @@ export declare class HeuristicTextMeasurer implements TextMeasurer {
  */
 export declare function highlight(predicate: Predicate, options?: HighlightBuilderOptions): HighlightInput;
 
-/**
- * Source of truth for which composition strategy each geom uses, or `null` for geoms that
- * opt out of highlighting entirely.
- */
-declare const HIGHLIGHT_STRATEGY_BY_GEOM: {
-    readonly bar: "observation-rerender";
-    readonly rule: null;
-    readonly line: "overlay-anchor";
-    readonly area: "overlay-anchor";
-    readonly point: "overlay-anchor";
-};
-
 declare interface HighlightBuilderOptions {
     id?: string;
     scope?: HighlightScope;
@@ -3803,15 +3504,11 @@ declare interface HighlightBuilderOptions {
 
 /** Per-layer side-channel produced by the highlights compile stage. */
 export declare interface HighlightComposition {
-    /** True when the base render should be wrapped in a dim group (so matched marks stand out). */
+    /** True when the base render should be wrapped in a dim group. */
     isDimmed: boolean;
-    /**
-     * A real sub-`CompiledLayer` whose dataset is mask-filtered to just the matched observations
-     * (everything else identical to the source layer). Feed it back through the same geom renderer to
-     * draw the highlighted marks at full strength; `null` when no re-render pass applies.
-     */
+    /** Sub-layer holding only matched observations, or `null` when no matched re-render pass applies. */
     matchedLayer: CompiledLayer | null;
-    /** Observations to paint as overlay markers under `'overlay-anchor'`. Empty for other strategies. */
+    /** Observations that qualify for the overlay-marker pass. Empty when the strategy doesn't use it. */
     overlayCandidates: HighlightOverlayCandidate[];
 }
 
@@ -3828,13 +3525,9 @@ export declare interface HighlightInput {
     layerIndex?: number;
 }
 
-/** Observation that qualifies for an overlay marker (`'overlay-anchor'` dot + value label). */
+/** Observation that qualifies for an overlay marker, along with its source index. */
 export declare interface HighlightOverlayCandidate {
     observation: Observation;
-    /**
-     * Row index into the **source** layer's dataset. Use only as a stable React key for the overlay;
-     * it is not a coordinate or a handle into the (mask-filtered) `matchedLayer`.
-     */
     observationIndex: number;
 }
 
@@ -3888,21 +3581,28 @@ export declare interface HighlightSpec {
 }
 
 /**
- * How a geom composes highlight matches above its base render. Looked up per geom in
- * `HIGHLIGHT_STRATEGY_BY_GEOM` and stamped onto `CompiledLayer.highlight.strategy` by
- * the layer compiler. Tells the renderer how to consume {@link HighlightComposition}:
+ * How a geom composes highlight matches above its base render. Declared per geom on the geom
+ * definition and stamped onto `CompiledLayer.highlight.strategy` by the layer compiler.
  *
- * - `'observation-rerender'`: re-render `composition.matchedLayer` through the same geom renderer
- *   (on top of the dimmed base), no overlays. Used by per-observation surface geoms (bar, rule).
- * - `'overlay-anchor'`: series-scope matches still go through the `matchedLayer` re-render pass,
- *   but data-point / x-value matches surface instead as a dot + value label per
- *   `composition.overlayCandidates` entry, placed at the geom's own anchor for that observation.
- *   Used by line, area, point.
+ * - `'observation-rerender'`: matched observations re-render through the same plugin against a
+ *   filtered sub-dataset. Used by per-observation surface geoms (bar, rule).
+ * - `'overlay-anchor'`: series-scope matches go through the matched re-render pass;
+ *   data-point / x-value-scope matches surface as a dot + value label at the plugin's
+ *   reported anchor. Used by line, area, point.
  */
 export declare type HighlightStrategy = 'observation-rerender' | 'overlay-anchor';
 
-/** The fixed mapping from geom to highlight strategy, for code that needs to look up a geom's strategy by name. */
-export declare type HighlightStrategyByGeom = typeof HIGHLIGHT_STRATEGY_BY_GEOM;
+/**
+ * Per-geom highlight strategy as a type map, derived from the geom definitions so the renderer's
+ * plugin contract requires `getOverlayAnchor` for exactly the `'overlay-anchor'` geoms.
+ */
+export declare type HighlightStrategyByGeom = {
+    bar: BarGeom['highlightStrategy'];
+    line: LineGeom['highlightStrategy'];
+    area: AreaGeom['highlightStrategy'];
+    point: PointGeom['highlightStrategy'];
+    rule: RuleGeom['highlightStrategy'];
+};
 
 /**
  * Chart-global dimming mode for non-matched observations when at least one
@@ -3941,6 +3641,13 @@ export declare class HoverEngine {
      * detection nor group/related, so they are visual decoration only as far as hover is concerned.
      */
     private nonInteractiveLayerIds;
+    /**
+     * Render-side hit-testers registered per layer for `render-hit-test` (Tier-C) layers, keyed by
+     * `CompiledLayer.id`. The renderer owns this map and injects it via {@link setHitTesters}; the
+     * engine holds the live reference so a plugin mounting or updating its tester is visible at the
+     * next `query()` without a re-index. Empty for charts with no Tier-C geom.
+     */
+    private hitTesters;
     constructor({ layers, coordSystem }: HoverEngineInput);
     /**
      * Diff-aware re-index. Layers whose `data`, `geom`, `position` or the graph's coord-system
@@ -3956,10 +3663,6 @@ export declare class HoverEngine {
     /**
      * Renderers call this on mount and on resize. Viewport is set-once, not per-query.
      *
-     * Pass the plot **panel** rect (the geom-drawing area), the same rect the pointer is normalized
-     * against before `query` — these must agree or hit-testing skews. Only the aspect ratio is used
-     * (it corrects the scatter points-2D index); the absolute pixels are not retained.
-     *
      * On every call, viewport-dependent indexes are asked to re-prep themselves for the new
      * viewport (`reindexPoints2DForAspect` is idempotent on aspect match, so unchanged-aspect
      * calls are cheap). The renderer is expected to debounce resize events so the underlying
@@ -3967,14 +3670,25 @@ export declare class HoverEngine {
      */
     setViewport(viewport: HoverViewport): void;
     /**
-     * Synchronous query. The `cursor` is the pointer normalized to `[0, 1]` against the **same rect
-     * passed to `setViewport`** (the plot panel) — x left-to-right, y in data-space (0 bottom, 1 top),
-     * so a top-origin renderer flips Y before calling (see {@link HoverCursor}).
-     *
-     * Returns the same `HoverState` reference while the primary stays on the same `(layerId,
-     * pointIndex)`, so subscribers using identity-based equality can short-circuit intra-geom cursor
-     * moves without re-rendering. Cache invalidates on `update()`. Warm-start seeds are written after
-     * every match so the next call walks a minimum number of Delaunay edges.
+     * Registers the render-side hit-testers for `render-hit-test` layers. The renderer holds a live,
+     * mutable map (a plugin writes its tester on mount); the engine keeps the reference, so updates
+     * are seen at the next `query()` without re-indexing. Pure runtime injection — nothing here rides
+     * in the compiled spec.
+     */
+    setHitTesters(hitTesters: ReadonlyMap<string, PanelHitTester>): void;
+    /**
+     * Resolves a `HoverState` for a known observation identity on a `render-hit-test` layer — the push
+     * path for geoms that own their own pointer surface (a live-simulation layer whose interactive
+     * overlay intercepts pointer events before the central capture layer sees them). The geom already
+     * knows which mark is under the cursor and supplies its key; the engine turns it into the same
+     * unified `HoverState` the pull path produces, so the central tooltip and a11y read one source.
+     */
+    hoverByKey(layerId: string, key: string): HoverState;
+    /**
+     * Synchronous query. Returns the same `HoverState` reference while the primary stays on the
+     * same `(layerId, pointIndex)`, so subscribers using identity-based equality can short-circuit
+     * intra-geom cursor moves without re-rendering. Cache invalidates on `update()`. Warm-start
+     * seeds are written after every match so the next call walks a minimum number of Delaunay edges.
      */
     query(cursor: HoverCursor): HoverState;
     private invalidateCache;
@@ -3990,22 +3704,6 @@ export declare interface HoverEngineInput {
     coordSystem: CoordSystem;
 }
 
-/** SVG `<line>` endpoints for the continuous-composition rule. */
-declare interface HoverGuideLineProps {
-    x1: string | number;
-    x2: string | number;
-    y1: string | number;
-    y2: string | number;
-}
-
-/** SVG `<rect>` attributes for the bar-composition band rect. */
-declare interface HoverGuideRectProps {
-    x: string | number;
-    y: string | number;
-    width: string | number;
-    height: string | number;
-}
-
 /**
  * A single hit returned by the hover engine.
  *
@@ -4029,12 +3727,9 @@ export declare interface HoverHit {
     layerId: string;
     pointIndex: number;
     /**
-     * Paint coordinates for an overlay marker (e.g. a hover dot) at this hit. Normalized panel-local.
-     * Cartesian: `[0, 1]²` in data-space (y=0 at the bottom, y=1 at the top — matching the compiler's
-     * `POSITION_VARIABLES.y`); convert to panel pixels as `xPixel = x * panel.width`,
-     * `yPixel = (1 - y) * panel.height` (invert y for top-origin renderers). Polar: `(angle in radians
-     * clockwise from 12 o'clock, radius in [0, 1])` — place via the same angle/radius transform the
-     * arcs use (center = panel center, outer radius = `min(panel.w, panel.h) / 2`).
+     * Normalized panel-local position. Cartesian: `[0, 1]²` in data-space (y=0 at the bottom,
+     * y=1 at the top — matching the compiler's `POSITION_VARIABLES.y`). Polar: `(angle in radians
+     * clockwise from 12 o'clock, radius in [0, 1])`.
      */
     x: number;
     y: number;
@@ -4042,37 +3737,20 @@ export declare interface HoverHit {
     observation: Observation;
 }
 
-/**
- * Output of `HoverEngine.query()`. Hits are partitioned into three roles. To paint, recombine
- * **per layer**: the primary's own layer renders `primary + group + (related.get(layerId) ?? [])`;
- * every other layer renders only `related.get(layerId) ?? []`. Tooltips list these in legend
- * (color scale-domain) order, with the primary emphasized in place rather than hoisted to the top.
- */
+/** Output of `HoverEngine.query()`. */
 export declare interface HoverState {
-    /** The single hit directly under the cursor (nearest/contained geom), or `null` when over no geom. */
     primary: HoverHit | null;
-    /**
-     * Companion hits in the **primary's own layer** that share its main-axis position: the stacked
-     * segments of the hovered column, or the dodged-bar siblings in the same band. Empty for point
-     * and arc layers (each mark stands alone). Render alongside the primary in its layer; do not
-     * surface them in any other layer.
-     */
     group: HoverHit[];
     /**
-     * Companion hits in **other** layers at the same main-axis position (e.g. every line/area/bar
-     * crossing the hovered x), bucketed by `CompiledLayer.id` so a per-layer consumer reads its own
-     * hits in O(1) (`related.get(layer.id) ?? []`) instead of filtering a flat array on every render.
-     * Layers with no companions are absent from the map — callers fall back to an empty array on miss.
+     * Cross-layer and same-layer companion hits, bucketed by `CompiledLayer.id` so a per-layer
+     * consumer reads its own hits in O(1) (`related.get(layer.id) ?? []`) instead of filtering
+     * a flat array on every render. Layers with no companions are absent from the map — callers
+     * fall back to an empty array on miss.
      */
     related: ReadonlyMap<string, HoverHit[]>;
 }
 
-/**
- * Viewport facts the engine needs for aspect-corrected hit testing. Pass the plot **panel** rect
- * (where geoms paint), not the whole chart — `HoverEngine.query` normalizes the pointer against
- * this same rect. Only the aspect ratio (`width / height`) is consumed: it corrects the points-2D
- * (scatter) nearest-neighbour index so Euclidean distance matches on-screen pixel distance.
- */
+/** Viewport facts the engine needs for aspect-corrected hit testing. */
 export declare interface HoverViewport {
     /** Panel width in pixels. */
     width: number;
@@ -4111,27 +3789,22 @@ declare type InferredScaleOptions = ContinuousScaleOptions | DiscreteScaleOption
 /**
  * Curve interpolation method for lines and areas.
  *
- * - `'linear'` — Straight segments between points. Maps to d3-shape `curveLinear`.
- * - `'catmull-rom'` — Smooth spline through points. Maps to d3-shape `curveCatmullRom`.
+ * - `'linear'` — Straight segments between points
+ * - `'catmull-rom'` — Smooth spline through points
  */
 export declare type InterpolateType = 'linear' | 'catmull-rom';
 
+/** Whether a geom identity is one of the built-in marks (vs. a custom registration). */
+export declare function isBuiltinGeomName(name: string): name is GeomName;
+
 /** Narrows a coord system to the cartesian variant. */
 export declare function isCartesian(coordSystem: CoordSystem): coordSystem is CartesianCoordSystem;
 
-export declare const isCategoricalValueFormat: (valueFormat: ValueFormat) => valueFormat is CategoricalValueFormat;
-
 /**
  * Current state of the process-wide caching flag.
  */
 export declare const isCompilerCachingEnabled: () => boolean;
 
-export declare const isCurrencyValueFormat: (valueFormat: ValueFormat) => valueFormat is CurrencyValueFormat;
-
-export declare const isDateWithoutYearValueFormat: (valueFormat: ValueFormat) => valueFormat is TemporalValueFormat & {
-    type: "month" | "day_month" | "weekly_date_range";
-};
-
 /**
  * Type guard that checks if a value is neither null nor undefined.
  */
@@ -4139,10 +3812,6 @@ export declare function isDefined<T>(value: T | null | undefined): value is T;
 
 /**
  * True when `input` is a {@link GraphConfig} rather than a {@link SpecInput}.
- *
- * Discriminates purely on the presence of `layers`: a {@link SpecInput} always carries a `layers`
- * array and a {@link GraphConfig} never has a top-level `layers`, so its absence identifies a
- * GraphConfig.
  */
 export declare const isGraphConfig: (input: SpecInput | GraphConfig) => input is GraphConfig;
 
@@ -4152,34 +3821,10 @@ export declare const isGraphConfig: (input: SpecInput | GraphConfig) => input is
  *
  *   if (isLayerOf(layer, 'line')) renderLine(layer); // layer is CompiledLayerFor<'line'>
  */
-export declare function isLayerOf<G extends GeomName>(layer: CompiledLayer, geom: G): layer is CompiledLayerFor<G>;
+export declare function isLayerOf<G extends string>(layer: CompiledLayer, geom: G): layer is CompiledLayerFor<G>;
 
-export declare const isLookupValueFormat: (valueFormat: ValueFormat) => valueFormat is LookupValueFormat;
-
-export declare const isNumericValueFormat: (valueFormat: ValueFormat) => valueFormat is NumericValueFormat | CurrencyValueFormat;
-
-/**
- * Whether a string is safe to assign to an `href`. Allows http, https, and
- * mailto; rejects javascript:, data:, vbscript:, and any other scheme that
- * could execute code or load arbitrary content.
- *
- * Leading control characters (NUL, tab, newline, etc.) are stripped before
- * the scheme check because the browser ignores them when parsing href, so
- * `\tjavascript:alert(1)` would otherwise sneak past a naive prefix test.
- */
-export declare const isSafeUrl: (input: unknown) => input is string;
-
-/**
- * True for positions that accumulate values along an axis (`'stack'` and `'fill'`).
- *
- * When true, the y position columns already hold cumulative band bounds — the renderer draws each
- * segment directly between them. Recover a segment's own value (for labels / tooltips) via
- * `getYRaw`, or in original data units via `createSegmentYReader`.
- */
 export declare function isStackedPosition(position: PositionType): boolean;
 
-export declare const isTemporalValueFormat: (valueFormat: ValueFormat) => valueFormat is TemporalValueFormat;
-
 /**
  * Snapshot of the most recent compile/recompile call returned by {@link Compiler.getLastCompile}.
  * `stages` holds the per-stage hit/miss delta incurred *by that call* (not cumulative);
@@ -4219,24 +3864,17 @@ declare interface LayerCompilerInput {
 }
 
 /**
- * Discriminated union of all layer inputs, keyed on `geom`.
+ * Any layer input: a built-in (typed per geom) or a custom registration (open identity, opaque params).
  * This is the user-facing type — fields are optional and will be resolved with defaults.
  */
-declare type LayerInput = {
-    [G in GeomName]: LayerInputOf<G>;
-}[GeomName];
+declare type LayerInput = BuiltinLayerInput | CustomLayerInput;
 
 declare interface LayerInputBase {
     type: 'layer';
-    /** Stable identifier; auto-assigned during resolution when omitted. */
     id?: string;
-    /** Layer-local aesthetic mapping, merged over the spec-level mapping. */
     mapping?: AesMapping;
-    /** Statistical transform applied to this layer (e.g. count, mean, smooth). @default 'identity' */
     stat?: StatName | StatInput;
-    /** How overlapping marks are arranged (stack, dodge, fill, identity). */
     position?: PositionType;
-    /** Which y scale this layer binds to — the primary or secondary axis. */
     yScaleType?: YScaleType;
     dataLabels?: DataLabelsInput;
     /**
@@ -4258,12 +3896,9 @@ declare type LayerInputOf<G extends GeomName> = LayerInputBase & {
 };
 
 /**
- * Discriminated union of all resolved layer specs, keyed on `geom`.
- * All properties are fully resolved — no optionals.
+ * Any resolved layer spec: a built-in or a custom registration. All properties are fully resolved.
  */
-declare type LayerSpec = {
-    [G in GeomName]: LayerSpecOf<G>;
-}[GeomName];
+declare type LayerSpec = BuiltinLayerSpec | CustomLayerSpec;
 
 declare interface LayerSpecBase {
     type: 'layer';
@@ -4282,7 +3917,6 @@ declare type LayerSpecOf<G extends GeomName> = LayerSpecBase & {
     params: GeomParamsMap[G];
 };
 
-/** Optional per-layer aggregates the summariser emits for label rendering. Fields are present only when the layer's geometry calls for them. */
 export declare interface LayerSummary {
     /** Per-x stack totals — one entry per x. */
     stackTotals?: StackTotalEntry[];
@@ -4312,7 +3946,7 @@ declare interface LayerValidationCheckInput {
 
 declare interface LayerValidationInput {
     layerId: string;
-    geom: GeomName;
+    geom: GeomIdentity;
     stat: StatSpec;
     /** `spec.mapping` merged with `layer.mapping` */
     effectiveMapping: AesMapping;
@@ -4347,31 +3981,23 @@ declare class LayerValidator {
      */
     private validateVariableExistence;
     /**
-     * Rule layers need exactly one numeric ValueMapping on `x` or `y`, unless a stat produces the
-     * value at compile time (e.g. `stat.mean()` populates `y`).
+     * Runs the geom's own mapping invariant (a rule needs exactly one numeric axis, say). The invariant
+     * lives on the geom definition, so the validator dispatches to it rather than naming a geom; geoms
+     * without a `validateMapping` hook impose none.
      */
-    private validateRuleMapping;
+    private validateGeomMapping;
     /**
-     * In the current version, rule layers don't have meaningful semantics under polar coords (pie / donut).
+     * Rejects a layer whose coord is absent from the geom's declared `supportedCoordTypes` (e.g. a rule
+     * has no meaning under polar pie/donut coords). The supported set lives on the geom definition, so
+     * the validator resolves support from there rather than naming a geom.
      */
-    private validateRuleCoord;
+    private validateCoordSupport;
 }
 
-/**
- * Default outer padding around the whole chart, in pixels. Used when {@link buildLayoutGrid} is called
- * without an explicit `padding` (the renderer threads a resolved theme token in to override it). Once
- * resolved it is baked into every {@link GraphLayout} rect (rects start at this inset), so don't re-add
- * it when painting — the constant is exported only so callers can reconcile against the container edge.
- * The per-region gaps below are intentionally internal; trust the returned rects rather than
- * reproducing the spacing.
- */
+/** Outer padding around the whole chart, in pixels. */
 export declare const LAYOUT_PADDING = 24;
 
 /**
- * The public layout entry point — `new LayoutCompiler(measurer).compile(input)`. Renderers consume the
- * returned {@link GraphLayout} rects and {@link LayoutCompileResult.formattedAxes}; they do not
- * reimplement the grid or re-run tick selection.
- *
  * Compiles layout geometry and final axis ticks. Output rects are in container coordinates.
  *
  * Horizontal axis edge height is candidate-independent (~line-height), so `panel.height` is
@@ -4420,44 +4046,23 @@ export declare class LayoutCompiler {
  */
 export declare interface LayoutCompileResult {
     layout: GraphLayout;
-    /**
-     * The axes with their final ticks already chosen and formatted by the compiler — paint each
-     * `ticks[].formattedLabel` as-is. Tick selection runs as part of layout (it depends on the resolved
-     * panel size), so do not re-run candidate selection or re-apply a value format in the renderer.
-     */
     formattedAxes: FormattedAxis[];
 }
 
 /** Input for the layout compiler. */
 export declare interface LayoutCompilerInput {
     axes: readonly CompiledAxisGuide[];
-    /** Locale the source data was parsed with; the fallback when no formatting locale is given. */
     parsingLocale: Locale;
     numberFormat: NumberFormatConfig;
     formattedLegends: FormattedLegend[];
-    /** Total pixel area available to the whole chart. */
     containerSize: BoxSize;
     externalMeasurements: ExternalMeasurements;
     /** The headline to measure and place; absent = no headline. */
     headline?: HeadlineLayoutInput;
-    /** Locale used to format tick/label text; falls back to `parsingLocale` when absent. */
     formattingLocale?: Locale;
-    /** Annotations that may overflow the panel and need extra edge padding reserved. */
     annotations?: CompiledAnnotations;
-    /** Coord system, consulted only to decide whether annotation overflow applies (cartesian only). */
     coordSystem?: CoordSystem;
-    /**
-     * Must equal the renderer's actual text zoom. It only affects layout when difference-arrow
-     * annotations exist on a cartesian coord, where it scales their label measurements to reserve the
-     * right panel-edge padding; otherwise it is inert.
-     */
     textScale?: number;
-    /**
-     * Outer padding around the whole chart, in pixels, applied uniformly on all four sides. Defaults to
-     * {@link LAYOUT_PADDING} when omitted. Renderers thread a resolved theme token here so a consumer can
-     * tighten or loosen the frame (e.g. a borderless, recolored chart that wants less surrounding space).
-     */
-    padding?: number;
 }
 
 /** Positions where axes/labels/legends can be placed around the panel. */
@@ -4465,20 +4070,13 @@ export declare type LayoutEdge = 'top' | 'right' | 'bottom' | 'left';
 
 /** Strategy for measuring chart element sizes in pixels. */
 export declare interface LayoutMeasurer extends HeadlineMeasurer {
-    /**
-     * Returns the axis band thickness (height for top/bottom, width for left/right): the tick-label
-     * extent plus the renderer's own tick marks and offsets. Honour `labelRotation` and the
-     * `labelMaxWidthPx` truncation cap so the reserved band matches what is actually painted.
-     */
+    /** Returns the pixel size for an axis (height for top/bottom, width for left/right). */
     measureAxis: (axis: FormattedAxis) => number;
     /** Returns the pixel size for an axis title (height for top/bottom, width for left/right). */
     measureAxisLabel: (axis: FormattedAxis) => number;
     /** Returns the pixel size for a legend (height for top/bottom, width for left/right). */
     measureLegend: (legend: FormattedLegend) => number;
-    /**
-     * Returns the size of a single tick label. This drives final tick density, so measure with the exact
-     * font the ticks are painted in; selection reads only `width`/`height` from the result.
-     */
+    /** Returns the size of a single tick label. */
     measureTickLabel: (label: string) => MeasuredText;
     /** Returns the size of a difference-arrow label rendered at the given size. */
     measureDifferenceArrowLabel: (text: string, size: DifferenceArrowSize) => MeasuredText;
@@ -4521,7 +4119,6 @@ declare type LegendConfigInput = Partial<LegendConfig>;
  */
 declare type LegendDisplay = 'pill' | 'direct' | 'auto';
 
-/** One entry in a legend: a domain value paired with the visual values that represent it. */
 export declare interface LegendItem {
     /** Raw data value (e.g., "Apples") */
     value: DataValue;
@@ -4529,17 +4126,12 @@ export declare interface LegendItem {
     label: string | null;
     /** Mapped visual values per aesthetic (e.g., { color: '#ff0000' }). */
     visual: LegendItemVisual;
-    /**
-     * Normalized y position in [0,1], 1 = top (matches {@link DirectLabelInput.normalizedY}). Null when display
-     * is not 'direct' or no endpoint found.
-     */
+    /** Normalized y position in [0,1]. Null when display is not 'direct' or no endpoint found. */
     normalizedY: number | null;
     /**
      * Visual signature of the geom this item describes. Per-item because a
      * single merged legend can span layers of different geoms (e.g. a combo
-     * chart's bar series and line series share one legend). Resolved via the
-     * same {@link SwatchShape} mapping that drives the headline and rule pills,
-     * so a series paints one consistent mark everywhere.
+     * chart's bar series and line series share one legend).
      */
     swatchShape: SwatchShape;
     /**
@@ -4554,14 +4146,9 @@ export declare interface LegendItem {
  */
 declare interface LegendItemVisual {
     color?: string;
-    /**
-     * Symbol diameter in PIXELS, present on bubble legends (see {@link CompiledLegendGuide.aesthetics}). Render a
-     * sized circle rather than a swatch; skip the item when this is non-finite or ≤ 0.
-     */
     size?: DataValue;
     alpha?: DataValue;
     strokeWidth?: DataValue;
-    /** Stroke style for `line` / `area` swatches only (solid/dashed/dotted). Other `swatchShape`s ignore it. */
     lineType?: LineStyleType;
 }
 
@@ -4569,27 +4156,37 @@ declare type LegendPosition = 'auto' | 'right' | 'left' | 'top' | 'bottom' | 'no
 
 declare function line(options?: GeomOptions<'line'>): LayerInputOf<'line'>;
 
+/**
+ * Represents a series of points connected by a line.
+ *
+ * If the x variable is numeric or temporal, the data will be sorted by x (this is to ensure the line is connected in the correct order).
+ */
+declare class LineGeom extends Geom {
+    readonly type: "line";
+    readonly requiredAesthetics: AestheticKey[];
+    readonly positionChannels: readonly PositionChannel[];
+    readonly swatchShape: SwatchShape;
+    readonly highlightStrategy = "overlay-anchor";
+    readonly spatialKind = "buckets";
+    readonly directLabelPositions: readonly ["identity", "stack", "dodge", "fill"];
+    readonly supportsPerGroupHeadline: boolean;
+    compile(input: GeomCompilerInput): CompiledGeom;
+    /** The observation's exact `(x, y)`. A line has no polar anchor. */
+    resolveAnchorPosition(observation: Observation, coordSystem: CoordSystem): AnchorPosition | null;
+}
+
 /**
  * Line-specific parameters
  */
 export declare interface LineGeomParams {
-    /**
-     * Stroke width in pixels. `'auto'` reads the per-observation `strokeWidth`
-     * channel (`getStrokeWidth`) and falls back to the geom default when unmapped.
-     */
     lineWidth: number | 'auto';
     /**
-     * Interpolation method to use for the line. Names a d3-shape curve family:
-     * `'linear'` ⇒ `curveLinear`, `'catmull-rom'` ⇒ `curveCatmullRom`.
+     * Interpolation method to use for the line.
      * @default 'linear'
      */
     interpolate: InterpolateType;
     /**
-     * How to handle missing (NULL/undefined) values:
-     * - `'zero'`: nulls arrive already substituted with zero by the compiler —
-     *   render normally, no special handling.
-     * - `'gap'`: break the path wherever x or y is null (d3 `defined()`).
-     * - `'connect'`: drop null rows before pathing so the line spans the gap.
+     * How to handle missing (NULL/undefined) values.
      * @default 'gap'
      */
     missingValues: MissingValuesType;
@@ -4599,7 +4196,6 @@ declare interface LineOptions {
     isSmoothLine?: boolean;
     lineThickness?: number | 'auto';
     showPoints?: boolean;
-    /** How gaps in the data are drawn: leave a gap, connect across, or treat as zero. */
     missingValues?: 'gap' | 'connect' | 'zero';
 }
 
@@ -4612,16 +4208,9 @@ declare interface LineOptions {
  */
 export declare type LineStyleType = 'solid' | 'dashed' | 'dotted';
 
-/**
- * One of the BCP-47 locale strings the engine supports for number and date
- * formatting. Used both to parse source values and as the display fallback (see
- * `ConfigSpec.parsingLocale`); a `format*` helper's `formattingLocale` param
- * overrides display. The supported set is deliberately small (see `LOCALES`),
- * and `duration` always formats in English regardless of the locale.
- */
 export declare type Locale = (typeof LOCALES)[number];
 
-/** The full set of supported BCP-47 locale strings. */
+/** A BCP-47 string representing a supported locale. */
 declare const LOCALES: readonly ["en-GB", "en-US", "ar", "pt-PT"];
 
 /** Logical composition of any predicate. */
@@ -4637,7 +4226,7 @@ export declare type LogicalPredicate = {
  * A value format that switches on a peer variable's value. Produced by transforms whose output is
  * structurally observation-dependent (see `reshapeFromWideToLong`).
  */
-export declare interface LookupValueFormat {
+declare interface LookupValueFormat {
     type: 'lookup';
     /** Peer variable whose stringified value selects the case. */
     byVariable: VariableName;
@@ -4647,13 +4236,16 @@ export declare interface LookupValueFormat {
     fallback: ExplicitValueFormat;
 }
 
+/** The data-space axis a `CartesianCoordSystem` uses as the main (independent) axis. */
+export declare type MainAxis = 'x' | 'y';
+
 /**
- * The data-space axis a `CartesianCoordSystem` uses as the main (independent) axis.
- * When `mainAxis === 'y'` (flip), the position column roles swap: the x-columns (`getX`/`getXMin`/
- * `getXMax`) carry the measure / cross-axis extent and the y-columns carry the main-axis band
- * position. Geoms branch on this to decide which reader feeds which pixel axis.
+ * The aesthetic keys a custom geom's layer mapping may carry — recovered structurally from the
+ * definition's declared manifest (`requiredAesthetics` + `visualAesthetics`), plus `group` (series is
+ * universal). An author writing `geom.<name>({ aes })` is autocompleted to these and an undeclared key
+ * is rejected, the mapping analog of how `ParamsOf` types `params`.
  */
-export declare type MainAxis = 'x' | 'y';
+declare type MappableAes<Definition extends Geom> = Definition['requiredAesthetics'][number] | Definition['visualAesthetics'][number] | 'group';
 
 /**
  * Create a pipeable mapping spec item.
@@ -4685,13 +4277,6 @@ declare interface MeanStatSpec {
     type: 'mean';
 }
 
-/**
- * Pixel dimensions of a measured string, in CSS pixels. `height === ascent + descent`, where ascent
- * and descent come from the font box (canvas `fontBoundingBoxAscent`/`fontBoundingBoxDescent`), not
- * the glyph box — so the height reflects the font's line metrics and is stable across strings rather
- * than tracking the actual glyphs drawn. `width` is the advance width (the pen advance), not the
- * tight ink bounding box.
- */
 export declare interface MeasuredText {
     width: number;
     height: number;
@@ -4710,19 +4295,14 @@ export declare interface MemoStats {
 /**
  * Strategy for handling null/undefined values in lines and areas.
  *
- * - `'zero'` — Replace missing values with zero. Pre-substituted by the compiler, so the renderer
- *   sees no nulls and paths normally.
- * - `'gap'` — Leave a visible gap where values are missing. The renderer breaks the path at any
- *   null x / y (e.g. d3's `defined()`).
- * - `'connect'` — Skip missing values and connect adjacent valid points. The renderer drops null
- *   rows before pathing.
+ * - `'zero'` — Replace missing values with zero
+ * - `'gap'` — Leave a visible gap where values are missing
+ * - `'connect'` — Skip missing values and connect adjacent valid points
  */
 export declare type MissingValuesType = 'zero' | 'gap' | 'connect';
 
-/** The hues available as a base for monochrome palettes, in pick order. */
 export declare const MONO_BASES: readonly ["grey", "red", "orange", "yellow", "green", "cyan", "blue", "purple", "pink"];
 
-/** One of the base hues a monochrome palette can be built from. */
 export declare type MonoPaletteBase = (typeof MONO_BASES)[number];
 
 declare type MonoPaletteConfig = {
@@ -4731,17 +4311,14 @@ declare type MonoPaletteConfig = {
     variant?: MonoPaletteVariant;
 };
 
-/** Tints the single-hue ramp for use on light vs dark backgrounds. */
 declare type MonoPaletteVariant = 'light' | 'dark';
 
 /**
- * Named font weights mapped to their numeric values — the canonical table `getNumericWeight` resolves
- * a named `FontSpec.weight` against. A from-scratch measurer must reproduce these exact mappings to
- * match the engine's text-measurement cache keys.
+ * Named font weights mapped to their numeric values.
  *
  * See: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-weight#common_weight_name_mapping
  */
-export declare const NAMED_WEIGHTS: {
+declare const NAMED_WEIGHTS: {
     readonly thin: 100;
     readonly hairline: 100;
     readonly extraLight: 200;
@@ -4761,12 +4338,10 @@ export declare const NAMED_WEIGHTS: {
     readonly ultraBlack: 950;
 };
 
-export declare type NamedWeightKey = keyof typeof NAMED_WEIGHTS;
+declare type NamedWeightKey = keyof typeof NAMED_WEIGHTS;
 
-/** The hues available as a base for neon palettes, in pick order. */
 export declare const NEON_BASES: readonly ["cyan", "pink", "purple", "red", "orange", "yellow", "green", "blue"];
 
-/** One of the base hues a neon palette can be built from. */
 export declare type NeonPaletteBase = (typeof NEON_BASES)[number];
 
 declare type NeonPaletteConfig = {
@@ -4775,7 +4350,6 @@ declare type NeonPaletteConfig = {
     variant?: NeonPaletteVariant;
 };
 
-/** `waterfall` swaps in the positive/negative/total colors used by waterfall charts. */
 declare type NeonPaletteVariant = 'default' | 'waterfall';
 
 /**
@@ -4809,15 +4383,11 @@ export declare interface NumberFormatConfig {
      */
     decimalSeparator?: string;
     /**
-     * Prefix to prepend (e.g., '$', '€'). No value formatter reads this — it is
-     * renderer-applied (currently inert in this package); a rebuild must prepend
-     * it to the formatted string itself.
+     * Prefix to prepend (e.g., '$', '€').
      */
     prefix?: string;
     /**
-     * Suffix to append (e.g., '%', ' units'). No value formatter reads this — it
-     * is renderer-applied (currently inert in this package); a rebuild must append
-     * it to the formatted string itself.
+     * Suffix to append (e.g., '%', ' units').
      */
     suffix?: string;
 }
@@ -4859,55 +4429,26 @@ export declare interface ObservationAnchorInput {
 
 declare type Options = Partial<LineOptions & BarOptions & ScatterOptions & ComboOptions & PieOptions & TableOptions>;
 
-/** Resolved palette selector; a custom palette carries its looked-up `colors`. */
 declare type PaletteConfig = DefaultPaletteConfig | GraphyPaletteConfig | PastelPaletteConfig | NeonPaletteConfig | MonoPaletteConfig | CustomPaletteConfig;
 
-/** Palette selector accepted from users; a custom palette is referenced by `id` only. */
 declare type PaletteConfigInput = DefaultPaletteConfig | GraphyPaletteConfig | PastelPaletteConfig | NeonPaletteConfig | MonoPaletteConfig | CustomPaletteInput;
 
-/** Resolved palette overrides: group number (1-indexed) to a concrete hex color. */
-export declare type PaletteOverrides = Record<number, string>;
-
-/**
- * Sparse override map.  Keys are group numbers (1-indexed), values are either a raw
- * hex value, or a color id to look up in the active custom palette.
- *
- * Indexes that are not specified fallback to the palette default.
- *
- * If both are set, `hex` wins.  If `id` is set but not found in the active custom palette,
- * the override is ignored.
- */
-export declare type PaletteOverridesInput = Record<number, {
-    hex?: string;
-    id?: string;
-}>;
-
-/** User-facing palette color scale; defaults to the active theme palette when `palette` is omitted. */
 declare interface PaletteScaleInput {
     type: 'scale';
-    /** Which channel this scale drives — only color channels accept palettes. */
     scaledAesthetic: ScaledAestheticKey;
     scaleType: 'palette';
-    /** Named or custom palette to draw group colors from. */
     palette?: PaletteConfigInput;
-    /** Per-group color overrides on top of the chosen palette. */
-    overrides?: PaletteOverridesInput;
 }
 
 declare interface PaletteScaleOptions {
-    /** Named or custom palette to draw group colors from. */
     palette?: PaletteConfigInput;
-    /** Per-group color overrides on top of the chosen palette. */
-    overrides?: PaletteOverridesInput;
 }
 
-/** Resolved palette color scale with a concrete palette config. */
 declare interface PaletteScaleSpec {
     type: 'scale';
     scaledAesthetic: ScaledAestheticKey;
     scaleType: 'palette';
     palette: PaletteConfig;
-    overrides?: PaletteOverrides;
 }
 
 /**
@@ -4919,12 +4460,31 @@ declare interface PanelConfig {
     };
 }
 
+/**
+ * A render-side hit-test a Tier-C geom registers for a `render-hit-test` layer. The engine calls it
+ * with the cursor in panel `[0, 1]` space using a **top-left origin (y-down)** — the same frame the
+ * geom paints in (unit-space SVG / `toPercent`), so the geom can test against its own rendered
+ * geometry without re-flipping. It returns the declared identity `key` of the observation under the
+ * cursor, or `null` for a miss; the engine resolves that key to a `HoverHit` and `HoverState`.
+ *
+ * The closure is injected per-instance through the renderer and never rides in the compiled spec —
+ * only the `render-hit-test` kind does (the serialisable boundary, ADR-005 / ADR-033 decision 4).
+ */
+export declare type PanelHitTester = (cursor: {
+    x: number;
+    y: number;
+}) => {
+    key: string;
+} | null;
+
+/** Recovers a geom definition's params type — carried structurally by its `defaultParams`. */
+declare type ParamsOf<Definition> = Definition extends Geom<infer TParams> ? TParams : never;
+
 declare type PastelPaletteConfig = {
     type: 'pastel';
     variant?: PastelPaletteVariant;
 };
 
-/** `waterfall` swaps in the positive/negative/total colors used by waterfall charts. */
 declare type PastelPaletteVariant = 'default' | 'waterfall';
 
 /**
@@ -4951,7 +4511,6 @@ declare abstract class PerLayerStage<Input extends {
 }
 
 declare interface PieOptions {
-    /** Where the aggregate total is shown: inside the ring (donut) or outside the chart. */
     pieTotalPosition?: 'center' | 'outside';
 }
 
@@ -4978,12 +4537,8 @@ export declare function pipe(spec: SpecInput, ...items: SpecItem[]): SpecInput;
 /**
  * One placed label, ready for a renderer to paint. Coordinates are in panel-pixel space
  * with origin at the panel's top-left — renderers translate into their own frame.
- *
- * Labels are placed independently, with NO cross-label overlap resolution — paint each as given.
- * (Contrast `computeDirectLabelsLayout`, which de-collides line-end labels against each other.)
  */
 export declare interface PlacedDataLabel {
-    /** Id of the layer this label belongs to, so the renderer can group/style by source layer. */
     layerId: string;
     /**
      * Stable key — derived from data identity (X value + group), not array position. Per-observation
@@ -4994,7 +4549,7 @@ export declare interface PlacedDataLabel {
     x: number;
     y: number;
     text: string;
-    /** Box width/height in pixels — the plate size returned by `measureDataLabel` (text + renderer padding). (x, y) is the box centre. */
+    /** Box width/height in pixels — measured text plus the engine's padding. (x, y) is the box centre. */
     width: number;
     height: number;
     /** When true, paint the label rotated -90° around `(x, y)`. */
@@ -5007,11 +4562,25 @@ export declare interface PlacedDataLabel {
 
 declare function point(options?: GeomOptions<'point'>): LayerInputOf<'point'>;
 
+/**
+ * Represents each observation as a point (e.g. for scatter plots).
+ */
+declare class PointGeom extends Geom {
+    readonly type: "point";
+    readonly requiredAesthetics: AestheticKey[];
+    readonly positionChannels: readonly PositionChannel[];
+    readonly swatchShape: SwatchShape;
+    readonly highlightStrategy = "overlay-anchor";
+    readonly spatialKind = "points";
+    readonly identityKeyStrategy = "index";
+    readonly supportsPerGroupHeadline: boolean;
+    compile({ data }: GeomCompilerInput): CompiledGeom;
+}
+
 /**
  * Point-specific parameters
  */
 declare interface PointGeomParams {
-    /** Marker diameter in pixels. */
     size: number;
 }
 
@@ -5020,13 +4589,6 @@ declare interface PointPosition {
     y: number;
 }
 
-export declare interface PolarBarArcInput {
-    startAngle: number;
-    endAngle: number;
-    innerRadius: number;
-    outerRadius: number;
-}
-
 declare interface PolarCoordInput {
     type: 'coord';
     coordType: 'polar';
@@ -5062,25 +4624,15 @@ declare interface PolarCoordSpec {
  * Angular params (theta, startAngle) are consumed by the compiler during coordTransform.
  * `innerRadius` is also exposed here so the renderer can recover the donut hole geometry
  * (e.g. to place a centred headline) without reaching into per-observation radii.
- *
- * Polar layers repurpose the position columns: x-columns carry angles, y-columns carry radii.
- * Angles are absolute radians (`startAngle` already applied, clockwise — matches d3-shape `arc()`),
- * passed through unmodified. Radii are [0,1] fractions of the outer radius, mapped into a unit
- * circle whose center is the panel center and whose radius is `min(panel.w, panel.h) / 2`.
  */
 export declare interface PolarCoordSystem {
     type: 'polar';
     /** Axis orientation metadata for the guide compiler */
     axisMapping: AxisMapping;
-    /**
-     * Donut hole radius as a fraction of the outer radius (0-1). 0 for a full pie.
-     * This is the same fraction the radial transform uses as the per-arc RadiusExtent.innerRadius
-     * floor, so it is recoverable from any arc.
-     */
+    /** Donut hole radius as a fraction of the outer radius (0-1). 0 for a full pie. */
     innerRadius: number;
 }
 
-/** Internal column names holding each observation's compiled positions (normalized to `[0, 1]`). */
 export declare const POSITION_VARIABLES: {
     readonly x: string;
     readonly y: string;
@@ -5096,16 +4648,26 @@ export declare const POSITION_VARIABLES: {
  */
 declare abstract class PositionAdjuster {
     abstract readonly type: PositionType;
+    /**
+     * The single position channel this adjuster reads to compute the adjustment, expressed in the
+     * geom-agnostic channel vocabulary. A geom is adjuster-compatible only when its manifest declares
+     * this channel; otherwise the adjustment is meaningless and the compiler no-ops it. Returns `null`
+     * for a topology-free adjuster (identity), which applies to any geom.
+     */
+    getConsumedChannel(_axis: ChannelAxis): PositionChannel | null;
     abstract adjust(input: PositionAdjusterCompilerInput): CompiledPositionAdjuster;
 }
 
 /**
- * Resolves a position adjustment by name and delegates to the appropriate implementation.
+ * Resolves a position adjustment by name and delegates to the appropriate implementation, gating on
+ * the consuming geom's position-channel manifest: an adjuster applies only when the geom declares the
+ * channel it consumes. An incompatible pairing (e.g. stacking a geom with no value point) no-ops —
+ * the adjustment is meaningless for that geom, not an error.
  */
 declare class PositionAdjusterCompiler {
     private readonly registry;
     constructor(registry: PositionAdjusterRegistry);
-    adjust(positionName: PositionType, input: PositionAdjusterCompilerInput): CompiledPositionAdjuster;
+    adjust(positionName: PositionType, geomChannels: readonly PositionChannel[], input: PositionAdjusterCompilerInput): CompiledPositionAdjuster;
 }
 
 declare interface PositionAdjusterCompilerInput {
@@ -5113,6 +4675,11 @@ declare interface PositionAdjusterCompilerInput {
     data: Dataset;
     /** The effective mapping for the layer */
     mapping: AesMapping;
+    /**
+     * The axis stack/fill accumulate along (the value axis). Defaults to `y`. dodge ignores it — it
+     * always splits the band axis.
+     */
+    axis?: ChannelAxis;
 }
 
 /**
@@ -5151,23 +4718,26 @@ declare interface PositionalScaleMethods {
 }
 
 /**
- * A position variable mapper that applies position scaling for a single concern
- * (e.g. primary x, band extents, y baseline extents).
- *
- * Returns the dataset with any new positional variables added,
- * or the same dataset unchanged if this mapper does not apply.
+ * One position channel a geom declares: where it sits ({@link ChannelAxis}, {@link PositionChannelRole}),
+ * how its raw column maps to a position ({@link PositionValueKind}), and an open identity its column
+ * derives from. A geom's channels are the manifest the position mapper and coord projection iterate
+ * instead of hardcoding the column set.
  */
-declare interface PositionMapper {
-    map: (input: PositionMapperInput) => Dataset;
+declare type PositionChannel = RolePositionChannel | ScalarPositionChannel;
+
+declare interface PositionChannelBase {
+    axis: ChannelAxis;
+    valueKind: PositionValueKind;
 }
 
 /**
- * Applies position scales to raw data values, producing scale-normalized `x` and `y` variables
- * ([0,1]) on each layer's dataset.
+ * Applies position scales to raw data values, producing scale-normalized position variables ([0,1])
+ * on each layer's dataset. The variables produced are whatever the layer's geom declares in its
+ * channel manifest, mapped by {@link mapPositionChannels}.
  */
 declare class PositionMapperCompiler extends PerLayerStage<PositionMapperCompilerInput> {
-    private readonly mappers;
-    constructor(mappers?: PositionMapper[]);
+    private readonly geomRegistry;
+    constructor(geomRegistry: GeomRegistry);
     protected dependencies(input: PositionMapperCompilerInput): readonly unknown[];
     protected compileLayer(layer: CompiledLayer, input: PositionMapperCompilerInput): CompiledLayer;
 }
@@ -5177,15 +4747,6 @@ declare interface PositionMapperCompilerInput {
     scales: PositionScalesSlice;
 }
 
-/**
- * Context passed to each column mapper during position mapping.
- */
-declare interface PositionMapperInput {
-    data: Dataset;
-    layer: CompiledLayer;
-    getPositionScale: (scaleAestheticKey: ScaledAestheticKey) => CompiledPositionScale | null;
-}
-
 /**
  * Subset of {@link CompiledScales} the position mapper reads. Narrowed so visual-scale changes
  * don't enter this stage's cache dependency surface.
@@ -5202,18 +4763,17 @@ declare type PositionScalesSlice = Pick<CompiledScales, 'x' | 'y' | 'ySecondary'
  */
 export declare type PositionType = 'stack' | 'dodge' | 'identity' | 'fill';
 
-/** Any highlight match condition: a field test or a logical combination of them. */
-export declare type Predicate = VariablePredicate | LogicalPredicate;
-
 /**
- * Namespaces a variable name so the compiler's own columns can't collide with user data columns.
- * The prefix uses control characters that real datasets won't contain.
+ * How a channel's raw column becomes a scaled position.
+ * - `value` — the column holds data-domain values mapped directly through the scale.
+ * - `bandOffset` — the column holds fractional offsets around the scaled axis point, sized by the
+ *   scale's bandwidth (a bar's left/right edges relative to its band centre).
  */
-export declare const prefixInternalVariable: (name: string) => string;
+declare type PositionValueKind = 'value' | 'bandOffset';
 
-export declare const prepareAreaObservations: (observations: Observation[], missingValues: AreaGeomParams["missingValues"]) => Observation[];
+export declare type Predicate = VariablePredicate | LogicalPredicate;
 
-export declare const prepareLineObservations: (observations: Observation[], missingValues: LineGeomParams["missingValues"]) => Observation[];
+export declare const prefixInternalVariable: (name: string) => string;
 
 declare interface QuantitativeScaleMethods {
     /**
@@ -5233,24 +4793,12 @@ declare interface QuantitativeScaleMethods {
     identity: (options?: IdentityScaleOptions) => IdentityScaleInput;
 }
 
-/** Radial extent of a polar arc, as a fraction (`[0, 1]`) of the outer radius. */
 export declare interface RadiusExtent {
     innerRadius: NumericDataValue;
     outerRadius: NumericDataValue;
 }
 
-/** Resolves one observation's raw, type-filtered value for an aesthetic. */
-declare type RawValueReader = (observation: Observation) => DataValue;
-
-export declare function readXExtent(primary: HoverHit): number | null;
-
-export declare function readYExtent(primary: HoverHit): number | null;
-
-/**
- * A rectangle in pixel coordinates, origin at top-left. Every rect on a {@link GraphLayout} is measured
- * from the chart CONTAINER top-left (with {@link LAYOUT_PADDING} already included), never panel- or
- * plot-local — paint against these absolute coordinates without re-offsetting.
- */
+/** A rectangle in pixel coordinates, origin at top-left. */
 export declare interface Rect {
     x: number;
     y: number;
@@ -5293,12 +4841,9 @@ declare class Registry<K extends string, T> {
 }
 
 /**
- * Render-time context used for GraphConfig conversion. Consumed only by {@link Compiler.compile}; a
- * theme or palette change therefore requires a fresh `compile` (it cannot be applied via
- * {@link Compiler.recompile}, which takes no `ctx`).
+ * Render-time context used for GraphConfig conversion.
  */
 export declare interface RendererContext {
-    /** Theme used to resolve theme-dependent colors; defaults to light when omitted. */
     theme?: GraphTheme;
     /** Renderer-owned palette catalog, keyed by `paletteId`. */
     customPalettes?: CustomPalettesInput;
@@ -5362,25 +4907,29 @@ export declare type ResolvedLegendDisplay = Exclude<LegendDisplay, 'auto'>;
 export declare type ResolvedLegendPosition = Exclude<LegendPosition, 'auto' | 'none'>;
 
 /**
- * An observation's anchor projected into normalized panel space `[0, 1]²`. Data-space origin
- * (y=0 at the bottom, matching `POSITION_VARIABLES.y`), so a top-origin renderer flips `y`
- * before painting — unlike `CompiledShape`/`CompiledTextAnnotation`, which are top-left.
+ * An observation's anchor projected into normalized panel space `[0, 1]²`, with the raw measure and
+ * resolved color the renderer needs. The `{ x, y, geom }` triple is the {@link AnchorPosition} the
+ * owning geom computes; this adds the per-observation facts the annotation chrome reads.
  */
-export declare interface ResolvedObservationAnchor {
-    x: number;
-    y: number;
-    /**
-     * The geom kind the anchored observation belongs to. Advisory: lets the renderer offset a
-     * marker-style annotation (sticker, pinned number, comment) to sit on that mark's shape. NOT used
-     * by `computeDifferenceArrow` — its endpoint gaps come from `getDifferenceArrowDimensions`.
-     */
-    geom: 'bar' | 'line' | 'polar-bar';
+export declare interface ResolvedObservationAnchor extends AnchorPosition {
     /** Raw value of the y-aesthetic (or x-aesthetic when flipped), used by label formatting. */
     measurementValue: number;
     /** Resolved color for this observation, if any. */
     color: string | undefined;
 }
 
+/**
+ * A custom annotation's coordinate resolved to normalized panel space, in **top-left [0,1]** — the
+ * space the draw function paints in. `observation` is attached only for a snap-to-observation
+ * coordinate (so the draw can read the bound row's columns); unit/data targets are synthetic points.
+ */
+export declare interface ResolvedTarget {
+    x: number;
+    y: number;
+    mode: 'data' | 'unit' | 'observation';
+    observation?: Observation;
+}
+
 /**
  * Decides where, at what size, and how much of a headline paints, once the layout is resolved. A strip
  * headline takes the reserved band at its container-fit size, then drops trailing items that overflow
@@ -5391,32 +4940,20 @@ export declare interface ResolvedObservationAnchor {
  */
 export declare const resolveHeadlinePlacement: ({ headline, layout, containerSize, measurer, itemGap, }: ResolveHeadlinePlacementInput) => HeadlinePlacement | null;
 
-/** What {@link resolveHeadlinePlacement} needs: the headline, the resolved layout it places into, and the renderer's measurer. */
 export declare interface ResolveHeadlinePlacementInput {
     headline: HeadlineLayoutInput;
     layout: GraphLayout;
     containerSize: BoxSize;
-    /** Measures the headline as the renderer actually paints it; a mismatch miscounts the visible items. */
     measurer: HeadlineMeasurer;
-    /**
-     * Gap the renderer lays out between adjacent strip items; governs how many fit the band. Keep it
-     * consistent with the real paint gap, alongside `measurer`, or the visible-item count drifts.
-     */
+    /** Gap the renderer lays out between adjacent strip items; governs how many fit the band. */
     itemGap: number;
 }
 
 /** Source of a layer's segment y value: `yRaw` when stacked, user's y mapping otherwise. */
 export declare function resolveSegmentYSource(position: PositionType, mapping: AesMapping): AestheticValue;
 
-export declare const resolveStrokeWidth: (observation: Observation, params: AreaGeomParams | LineGeomParams) => number;
-
 /**
  * Resolves the Y scale aesthetic based on the layer's `yScaleType` axis assignment.
- *
- * `CompiledScales` is keyed by scale aesthetic (`ySecondary` is a key, not an aesthetic), so to get
- * a layer's y scale read `scales[resolveYScaleAesthetic(layer.yScaleType)]`. For its axis, pass the
- * same resolved key to `findAxisGuide` (find-guide.ts): the two compose for secondary-axis lookup,
- * so a `secondary` layer resolves to the `ySecondary` guide, not `y`.
  */
 export declare function resolveYScaleAesthetic(yScaleType: YScaleType): ScaledAestheticKey;
 
@@ -5426,20 +4963,7 @@ export declare function resolveYScaleAesthetic(yScaleType: YScaleType): ScaledAe
  */
 export declare const RESTING_HOVER_STATE: HoverState;
 
-/**
- * TipTap-compatible rich text node (no tiptap dependency).
- *
- * Renderer contract — the vocabulary a text renderer must handle. Anything not
- * listed falls through to a `<span>` carrying the node's own marks/attrs.
- *
- * Block `type`s (snake_case and camelCase accepted): `doc`, `paragraph`,
- * `heading`, `blockquote`, `bulletList`/`bullet_list`, `orderedList`/
- * `ordered_list`, `listItem`/`list_item`, `hardBreak`/`hard_break`, `text`.
- *
- * Mark `type`s (some carry synonyms): `bold`/`strong`, `italic`/`em`,
- * `underline`, `strike`, `code`, `link`, `textStyle`. The `link` mark reads
- * `attrs.href` and the renderer URL-safety-checks it before emitting an anchor.
- */
+/** TipTap-compatible rich text node (no tiptap dependency). */
 export declare interface RichTextContent {
     type?: string;
     content?: RichTextContent[];
@@ -5448,31 +4972,48 @@ export declare interface RichTextContent {
         type: string;
         attrs?: Record<string, unknown>;
     }>;
-    /**
-     * Per-node attributes the renderer recognizes: `heading.level` (1–3),
-     * `paragraph.textAlign`, and on the `textStyle` mark `color`, `font` (a font
-     * id), and `fontSize` — a number read as `n/10` em. Unrecognized keys are
-     * ignored.
-     */
     attrs?: Record<string, unknown>;
 }
 
+/**
+ * A structural channel — the per-axis anchor (`point`) or one end of an interval (`lower`/`upper`).
+ * Its {@link PositionChannel.name | name} defaults to the role, so the canonical position columns
+ * (`x`, `xMin`, `yMax`, …) are preserved and a geom declares `{ axis, role, valueKind }` with no name.
+ */
+declare interface RolePositionChannel extends PositionChannelBase {
+    role: 'point' | 'lower' | 'upper';
+    /** Open identity override; defaults to {@link role}. Built-ins omit it to keep canonical columns. */
+    name?: string;
+}
+
 declare function rule(options?: GeomOptions<'rule'>): LayerInputOf<'rule'>;
 
 /**
- * Rule-specific parameters.
+ * Reference line at a numeric value, supplied as a constant mapping or read from a stat-output
+ * variable (e.g. `stat.mean()`). Emits a 1-observation dataset on a synthetic variable.
  *
- * A rule is a single reference line. The renderer reads one observation —
- * `data.getFirst()` — via `getX`/`getY`. Orientation: horizontal when the layer
- * maps `y` (a constant-y line spanning the panel width), vertical otherwise;
- * under a flipped coord system the orientation inverts with the axes.
+ * The other axis is cleared so inherited mappings don't reach the position mapper.
+ */
+declare class RuleGeom extends Geom {
+    readonly type: "rule";
+    readonly positionChannels: readonly PositionChannel[];
+    readonly highlightStrategy: null;
+    readonly supportedCoordTypes: readonly CoordType[];
+    compile({ data: inputData, mapping }: GeomCompilerInput): CompiledGeom;
+    /**
+     * A rule needs exactly one numeric value on `x` or `y` (or a stat that computes one at compile
+     * time, e.g. `stat.mean()` on `y`) — it draws a single reference line on one axis.
+     */
+    validateMapping({ layerId, mapping, computedVariables }: GeomMappingValidationInput): ValidationIssue[];
+}
+
+/**
+ * Rule-specific parameters.
  */
 export declare interface RuleGeomParams {
     /** Stroke color; falls back to a theme token. */
     color?: string;
-    /** Stroke width in pixels. */
     strokeWidth: number;
-    /** Dash pattern of the line (solid, dashed, dotted, ...). */
     lineType: LineStyleType;
     /** Optional inline text label rendered alongside the line. */
     label?: string;
@@ -5484,6 +5025,26 @@ export declare interface RuleGeomParams {
  */
 export declare type RuleLabelPosition = 'start' | 'end';
 
+/**
+ * A standalone scaled value on an axis, identified by an open {@link ScalarPositionChannel.name | name}.
+ * Always `value`-kind — a lone value has no band to offset against. Its column is namespaced from the
+ * name, so two geoms' scalars never collide and neither freezes an internal column (the decision-9
+ * litmus): a box plot declares `q1`/`median`/`q3`, an error bar its CI bounds, and the position mapper
+ * scales each through the axis scale exactly as it scales an interval bound.
+ */
+declare interface ScalarPositionChannel extends PositionChannelBase {
+    role: 'scalar';
+    valueKind: 'value';
+    name: string;
+    /**
+     * The mapping key this channel sources its raw values from. When set, the position mapper reads
+     * `mapping[aes]`'s column and scales it in place — so the value is authored as `aes` (a box plot's
+     * `q1`), not hand-copied from `params`. When omitted, the channel reads the column the geom wrote
+     * under {@link variableFor}`(axis, name)` (a geom that computes the value itself).
+     */
+    aes?: string;
+}
+
 declare abstract class Scale {
     /** Data types this scale accepts. */
     abstract readonly compatibleDataTypes: readonly DataType[];
@@ -5596,10 +5157,8 @@ declare interface ScaleCompilerInput {
  */
 export declare type ScaledAestheticKey = ScaledPositionAestheticKey | ScaledVisualAestheticKey;
 
-/** Scale keys whose output is a spatial coordinate. `ySecondary` is the optional second y axis. */
 declare type ScaledPositionAestheticKey = 'x' | 'y' | 'ySecondary';
 
-/** Scale keys whose output is a visual channel rather than a position. */
 declare type ScaledVisualAestheticKey = 'color' | 'size' | 'alpha' | 'strokeWidth' | 'lineType';
 
 /**
@@ -5633,7 +5192,6 @@ declare type ScaleTransformType = 'linear' | 'log' | 'sqrt';
  * - `'discrete'` — Discrete categorical values
  * - `'datetime'` — Date/time range
  * - `'identity'` — Pass-through, values used as-is
- * - `'palette'` — Discrete values mapped through a named color palette
  */
 declare type ScaleType = 'continuous' | 'discrete' | 'datetime' | 'identity' | 'palette';
 
@@ -5641,13 +5199,47 @@ declare interface ScatterOptions {
     pointSize?: number | 'auto';
 }
 
+/**
+ * One geom-declared detail row: a label, the column its value is read from, and the format to display
+ * that value with (derived from the column, never formatted at compile time). Resolved once per layer
+ * from the geom's {@link GeomTooltipRow} declaration; values stay in `data` and are read on demand.
+ */
+declare interface SemanticDetailRowDescriptor {
+    label: string;
+    variable: VariableName;
+    valueFormat: ValueFormat;
+}
+
+/**
+ * One encoding in a layer's semantic map: an aesthetic, the variable its value is read from, and
+ * the format to display that value with. The format is usually the value variable's own, but the
+ * two can differ — a stacked y reads its segment magnitude from a column that defaults to decimal
+ * while displaying it with the y variable's preserved format. Resolved once per layer — the
+ * descriptor is O(aesthetics), pure data, and never holds per-observation values, so it rides in
+ * the compiled spec without duplicating columns.
+ */
+declare interface SemanticEncodingDescriptor {
+    aesthetic: AestheticKey;
+    variable: VariableName;
+    valueFormat: ValueFormat;
+}
+
+/** A layer's geometry-agnostic meaning, declared as the ordered set of encodings its marks carry. */
+declare interface SemanticMapDescriptor {
+    encodings: SemanticEncodingDescriptor[];
+    /**
+     * Extra single-observation rows a geom contributes to the tooltip (e.g. OHLC), in declaration
+     * order. Empty for geoms that add none, in which case the standard one-row-per-series content
+     * applies.
+     */
+    detailRows: SemanticDetailRowDescriptor[];
+}
+
 /**
  * Serialized representation of a command for wire transport and persistence.
  * Only forward commands are serialized — inverses are recomputed at execution time.
- * Round-trip a command with {@link commandRegistry}'s `serialize`/`deserialize`.
  */
 export declare interface SerializedCommand {
-    /** Command type discriminator used to pick the right descriptor when deserializing. */
     readonly type: string;
     readonly params: Record<string, unknown>;
     readonly metadata: CommandMetadata;
@@ -5655,9 +5247,7 @@ export declare interface SerializedCommand {
 
 /** Config for styling a specific series. */
 declare interface SeriesStyle {
-    /** Id of a slot in the active palette; takes precedence over the palette's default assignment. */
     paletteColorId?: string;
-    /** Explicit color that overrides any palette slot for this series. */
     customColor?: string;
     fillStyle?: 'solid' | 'hatched';
     lineStyle?: 'solid' | 'dashed' | 'dotted';
@@ -5702,7 +5292,6 @@ export declare class SetContentCaptionCommand implements Command<SetContentCapti
 }
 
 declare type SetContentCaptionParams = {
-    /** New caption, or `null` to clear it. */
     caption: TextContent | null;
 };
 
@@ -5721,7 +5310,6 @@ export declare class SetContentSubtitleCommand implements Command<SetContentSubt
 }
 
 declare type SetContentSubtitleParams = {
-    /** New subtitle, or `null` to clear it. */
     subtitle: TextContent | null;
 };
 
@@ -5741,7 +5329,6 @@ export declare class SetContentTitleCommand implements Command<SetContentTitlePa
 }
 
 declare type SetContentTitleParams = {
-    /** New title, or `null` to clear it. */
     title: TextContent | null;
 };
 
@@ -5775,7 +5362,6 @@ export declare class SetLineWidthCommand implements Command<SetLineWidthParams>
 }
 
 declare type SetLineWidthParams = {
-    /** Layer to target; when omitted, the first line/area layer is used. */
     layerId?: string;
     lineWidth: LineGeomParams['lineWidth'];
 };
@@ -5794,11 +5380,8 @@ export declare class SetScaleDomainCommand implements Command<SetScaleDomainPara
 }
 
 declare type SetScaleDomainParams = {
-    /** Which scale to change, identified by the aesthetic it drives (e.g. x, y). */
     scaledAesthetic: ScaledAestheticKey;
-    /** New lower bound; omit to leave the existing minimum unchanged. */
     domainMin?: ContinuousScaleSpec['domainMin'];
-    /** New upper bound; omit to leave the existing maximum unchanged. */
     domainMax?: ContinuousScaleSpec['domainMax'];
 };
 
@@ -5810,28 +5393,20 @@ declare type SetScaleDomainParams = {
 export declare interface ShapeInput {
     id?: string;
     kind?: ShapeKind;
-    /** Draw beneath the geoms (background) or on top (foreground). */
     zOrder?: ShapeZOrder;
-    /** Left edge, as a fraction of plot width (0..1). */
     x: number;
-    /** Top edge, as a fraction of plot height (0..1). */
     y: number;
-    /** Width, as a fraction of plot width (0..1). */
     width: number;
-    /** Height, as a fraction of plot height (0..1). */
     height: number;
     fillColor?: string;
-    /** Fill alpha, 0 (transparent) to 1 (opaque). */
     fillOpacity?: number;
     strokeWidth?: number;
     /** null falls back to the theme `defaultAnnotationShapeStroke`. */
     strokeColor?: string | null;
 }
 
-/** The geometry a shape annotation draws. */
 export declare type ShapeKind = 'rectangle';
 
-/** Resolved shape annotation with all optional fields defaulted. */
 export declare interface ShapeSpec {
     id: string;
     kind: ShapeKind;
@@ -5847,9 +5422,7 @@ export declare interface ShapeSpec {
 }
 
 /**
- * Whether the shape renders beneath the geoms (background) or on top (foreground). This is not a
- * sort key within a single pass: the renderer paints `background` shapes, then the geom layer, then
- * `foreground` shapes — two separate passes bracketing the geoms (see `CompiledAnnotations`).
+ * Whether the shape renders beneath the geoms (background) or on top (foreground).
  */
 export declare type ShapeZOrder = 'background' | 'foreground';
 
@@ -5878,9 +5451,7 @@ export declare type SmoothMethod = 'linear' | 'loess' | 'exponential' | 'logarit
 declare interface SmoothStatInput {
     type: 'smooth';
     method: SmoothMethod;
-    /** Polynomial order — only meaningful when `method: 'polynomial'`. */
     order?: number;
-    /** LOESS bandwidth — only meaningful when `method: 'loess'`. */
     bandwidth?: number;
 }
 
@@ -5920,6 +5491,29 @@ export declare interface SourceContent {
     url?: string;
 }
 
+/**
+ * The kind of spatial structure a geom presents for hit-testing. Each value selects one of the
+ * runtime's index builders, so the descriptor lets the engine dispatch on declared data instead
+ * of branching on the geom name.
+ *
+ * `render-hit-test` is the Tier-C escape hatch: the geom's geometry comes from a layout algorithm,
+ * not from scales, so the compiler cannot build a spatial index from position columns. The geom
+ * instead provides a render-side hit-test function (injected per-instance through the renderer),
+ * and the engine resolves the observation it returns against the declared identity key. Only the
+ * kind rides in the compiled spec — the closure never crosses the serialisable boundary.
+ */
+declare type SpatialIndexKind = 'buckets' | 'rects' | 'points' | 'arcs' | 'noop' | 'render-hit-test';
+
+/**
+ * A layer's geometry-agnostic hit-test declaration. Pure serialisable data riding in the compiled
+ * spec: it names the spatial structure the marks present so the runtime can build the matching
+ * index without knowing which geom produced it. A geom declares its cartesian-natural kind on its
+ * definition; a polar coord refines it to `arcs` during the coord transform.
+ */
+declare interface SpatialMapDescriptor {
+    kind: SpatialIndexKind;
+}
+
 /**
  * Fully resolved spec — all fields populated, defaults applied, inferred types resolved.
  * This is what the compilation pipeline consumes.
@@ -5974,16 +5568,12 @@ export declare interface SpecInput {
     config: ConfigInput;
 }
 
-declare type SpecItem = LayerInput | ScaleInput | CoordInput | ConfigItem | TransformInput | MappingItem | HighlightInput | AnnotationsItem;
+declare type SpecItem = LayerInput | ScaleInput | CoordInput | ConfigItem | TransformInput | MappingItem | HighlightInput | AnnotationItem;
 
 /**
  * Compiles a raw compiler input or graph config into a resolved Spec.
  */
 export declare class SpecResolver {
-    /**
-     * Resolve user input into a fully defaulted {@link Spec}. Accepts either a viz-engine
-     * `SpecInput` or a legacy `GraphConfig`, converting the latter before resolution.
-     */
     compile({ input, dataset, ctx }: {
         input: CompilerInput;
         dataset: Dataset;
@@ -5991,7 +5581,6 @@ export declare class SpecResolver {
     }): Spec;
 }
 
-/** A stack's total at one x position, with where its label should be anchored. Drives stack-total labels. */
 export declare interface StackTotalEntry {
     /** Serialised x value for stable join keys across observations. */
     xKey: string;
@@ -6045,7 +5634,6 @@ declare abstract class Stat {
     protected abstract computeStat(input: StatCompilerInput): CompiledStat;
 }
 
-/** Factories for the statistical transforms a layer can apply (identity, count, smooth, mean). */
 export declare const stat: {
     identity: typeof identity;
     count: typeof count;
@@ -6126,8 +5714,14 @@ declare type StickerId = 'rocket' | 'clapping-hands' | 'thumbs-up' | 'thumbs-dow
 
 /**
  * Computes per-layer aggregates (stack totals, grand totals) consumed directly by the renderer.
+ *
+ * Which geoms carry each aggregate is declared on the geom definition and resolved through the
+ * injected {@link GeomCompiler}, so the stage dispatches by declaration rather than naming a geom;
+ * the summariser strategies stay geom-agnostic computations.
  */
 declare class SummariseCompiler extends PerLayerStage<SummariseCompilerInput> {
+    private readonly geomCompiler;
+    constructor(geomCompiler: GeomCompiler);
     protected dependencies(): readonly unknown[];
     protected compileLayer(layer: CompiledLayer): CompiledLayer;
 }
@@ -6137,38 +5731,29 @@ declare interface SummariseCompilerInput {
 }
 
 /**
- * Visual signature of a geom, decoupled from `GeomName` because legends and tooltips don't care
- * about the geom's spec-level identity — only what shape best evokes its on-canvas mark.
+ * Visual signature of a geom's mark, decoupled from `GeomName` because legends and tooltips care
+ * only about the shape that best evokes the on-canvas mark, not the geom's spec-level identity.
  *
- * - `bar` + cartesian → `square`
- * - `bar` + polar → `slice` (pie / donut wedge)
- * - `line` → `line` (a horizontal stroke)
- * - `area` → `area` (filled region with a stroke accent)
- * - `point` → `circle`
- *
- * One resolver feeds the legend, the headline strip, and rule pills, so a given series shows the same mark in
- * every surface. A combo legend still carries mixed shapes — the value is resolved per series, not per chart.
+ * - `square` → a filled rect (bar)
+ * - `line` → a horizontal stroke
+ * - `area` → a filled region with a stroke accent
+ * - `circle` → a point
+ * - `slice` → a pie / donut wedge (a `square` mark refined under polar coords)
  */
 export declare type SwatchShape = 'square' | 'line' | 'circle' | 'area' | 'slice';
 
 declare type Table = internal.ColumnTable;
 
 declare interface TableOptions {
-    /** Relative widths per column, keyed by column key; values are normalized into fractions. */
     tableColumnRatios?: Record<string, number>;
 }
 
 declare interface TemporalValueFormat {
     type: 'datetime' | 'time' | 'date' | 'year' | 'quarter' | 'month_year' | 'month' | 'weekly_date_range_with_year' | 'weekly_date_range' | 'day_month';
-    /**
-     * Source-parsing metadata: the template the values were originally parsed from (e.g. 'dd-mm-yyyy').
-     * It is NOT a formatting instruction and is not consumed when materializing output — the renderer
-     * picks the display shape from `type` alone, not from this field.
-     */
+    /** Template string representing how values of this type have been formatted. ie. dd-mm-yyyy  */
     dateFormat?: string;
 }
 
-/** How a text annotation's background fill is applied: faded into the plot or fully opaque. */
 export declare type TextAnnotationBackgroundColorStyle = 'fade' | 'opaque';
 
 /**
@@ -6177,7 +5762,6 @@ export declare type TextAnnotationBackgroundColorStyle = 'fade' | 'opaque';
  */
 export declare interface TextAnnotationInput {
     id?: string;
-    /** Rich-text body to render. */
     content: RichTextContent;
     /** 0..1 of plot width — top-left corner. */
     x: number;
@@ -6187,11 +5771,9 @@ export declare interface TextAnnotationInput {
     width: number;
     /** null falls back to a transparent background. */
     backgroundColor?: string | null;
-    /** Whether the background fill fades into the plot or is fully opaque. */
     backgroundColorStyle?: TextAnnotationBackgroundColorStyle;
 }
 
-/** Resolved text annotation with all optional fields defaulted. */
 export declare interface TextAnnotationSpec {
     id: string;
     content: RichTextContent;
@@ -6205,34 +5787,26 @@ export declare interface TextAnnotationSpec {
 /** A text value — plain string or structured rich text. */
 export declare type TextContent = string | RichTextContent;
 
-/**
- * Measures rendered text dimensions so the layout engine can size labels without a real DOM.
- * Swap implementations (canvas-backed, heuristic) to fit the runtime environment.
- *
- * Contract: `measureText` must be deterministic for a given `(text, FontSpec)` — the engine caches
- * results keyed on that pair and assumes repeat calls agree. It must measure against fonts that are
- * already loaded; measuring before the family is ready would cache fallback-font metrics and skew
- * every subsequent layout for that key.
- */
 export declare interface TextMeasurer {
     measureText: (text: string, font: FontSpec) => MeasuredText;
 }
 
-/** Fully-derived tooltip content. The popover renders directly from this. */
+/** A chart's semantic content for the hovered observations, in reading order. */
 export declare interface TooltipContent {
-    /** Formatted main-axis value of the primary's observation. `null` for polar. */
+    /** Localized main-axis value of the primary's observation. `null` for polar. */
     header: string | null;
     rows: TooltipRow[];
 }
 
 /**
- * One row in the chart tooltip popover. Pure projection of a `HoverHit` against the layer's
- * compiled scales.
+ * One row of a chart's semantic content: a single observation's meaning, resolved and localized for
+ * display. Surface-agnostic — the tooltip renders it directly, and the accessible surfaces (screen
+ * reader, data table) derive from the same rows so content never forks per surface.
  */
 export declare interface TooltipRow {
     /**
      * Resolved color string applied as the row's swatch fill/stroke. `null` only when the chart
-     * has no color scale at all — the popover suppresses the swatch cell in that edge case.
+     * has no color scale at all — surfaces suppress the swatch cell in that edge case.
      */
     swatchColor: string | null;
     /** Visual signature of the row's source geom. Drives the swatch shape. */
@@ -6241,7 +5815,7 @@ export declare interface TooltipRow {
     swatchLineType: LineStyleType;
     /** Row label — color value (multi-series) or layer's Y-axis title (single-series). */
     label: string;
-    /** Formatted Y reading for this hit. */
+    /** Localized Y reading for this observation. */
     value: string;
     /** Styling hint: the row whose hit `=== primary`. Never re-orders. */
     isPrimary: boolean;
@@ -6249,23 +5823,6 @@ export declare interface TooltipRow {
     key: string;
 }
 
-/** Formats a normalized [0,1] value as a CSS percentage string for SVG positioning. */
-export declare const toPercent: (value: number) => string;
-
-/**
- * Converts a normalized [0,1] x-coordinate to viewBox coordinate (identity transform).
- * Used inside nested SVGs with viewBox="0 0 1 1".
- */
-export declare function toViewBoxX(normalized: number): number;
-
-/**
- * Converts a normalized [0,1] y-coordinate to viewBox coordinate (Y-inverted).
- * SVG y=0 is at the top, but data y=0 is at the bottom, so we invert.
- * Used inside nested SVGs with viewBox="0 0 1 1".
- */
-export declare function toViewBoxY(normalized: number): number;
-
-/** Factories for data transforms applied before charting (reshape, filter, sort, aggregate, constant). */
 export declare const transform: {
     reshape: typeof reshape;
     filter: typeof filter;
@@ -6331,7 +5888,7 @@ declare interface UndoRedoResult {
  * Each validation stage (e.g. {@link LayerValidator}, the pre-pass in {@link ScaleCompiler}) collects
  * {@link ValidationIssue}s and throws a single {@link SpecValidationError} at the end of its stage.
  */
-declare type ValidationCode = 'UNKNOWN_VARIABLE' | 'INCOMPATIBLE_TYPE' | 'MISSING_AESTHETIC' | 'INVALID_RULE_MAPPING' | 'INVALID_RULE_COORD';
+declare type ValidationCode = 'UNKNOWN_VARIABLE' | 'INCOMPATIBLE_TYPE' | 'MISSING_AESTHETIC' | 'INVALID_RULE_MAPPING' | 'UNSUPPORTED_COORD';
 
 declare interface ValidationIssue {
     code: ValidationCode;
@@ -6340,37 +5897,7 @@ declare interface ValidationIssue {
     aesthetic?: string;
 }
 
-/**
- * The compiler-emitted descriptor of how a raw data value should be turned into a display string.
- * The engine never formats values itself; it tags each guide/legend/headline figure with a
- * `ValueFormat`, and the renderer materializes it via `createValueFormatter` (a descriptor is inert
- * until paired with a locale and number-format config). It surfaces on compiled guides
- * (`CompiledAxisGuide.valueFormat`, legend/headline items), so a renderer holds these values and must
- * be able to name and switch on them.
- *
- * The `type` discriminant selects the formatter. Rendered examples (en-US, default number config):
- * - `currency` — '$1,234.50' (narrow currency symbol from `iso`, 2 decimals).
- * - `decimal` — '1,234.5' (locale grouping; decimals/abbreviation from number-format config).
- * - `integer` — '1,235' (no fraction digits).
- * - `percentage` — '12%' (value is a fraction: 0.12 → '12%').
- * - `duration` — '1h 5m' (value is milliseconds; always English, never localized).
- * - `text` — 'North' (categorical value passed through unchanged).
- * - `date` — 'Jan 5, 2025'.
- * - `datetime` — 'Jan 5, 2025 • 14:30:00' (comma between date and time replaced by a middot).
- * - `time` — '14:30'.
- * - `year` — '2025'.
- * - `quarter` — 'Q1 2025'.
- * - `month` — 'January' (no year).
- * - `month_year` — 'Jan 2025'.
- * - `day_month` — 'January 5' (no year).
- * - `weekly_date_range` — 'January 5 – 11' (value + 6 days, no year).
- * - `weekly_date_range_with_year` — 'Jan 5 – 11, 2025'.
- * - `lookup` — resolved per observation; see {@link LookupValueFormat}.
- *
- * The `isXValueFormat` guards (e.g. {@link isLookupValueFormat}, {@link isTemporalValueFormat}) narrow
- * a held descriptor to a family without listing every member kind by hand.
- */
-export declare type ValueFormat = ExplicitValueFormat | LookupValueFormat;
+declare type ValueFormat = ExplicitValueFormat | LookupValueFormat;
 
 /**
  * Formats one value. When the underlying `ValueFormat` is a `lookup`, the second `observation` argument
@@ -6379,16 +5906,10 @@ export declare type ValueFormat = ExplicitValueFormat | LookupValueFormat;
  */
 export declare type ValueFormatter = (value: DataValue, observation?: Observation) => string;
 
-/** Inputs to build a {@link ValueFormatter}: the format to apply, the locale, and number-formatting config. */
 export declare interface ValueFormatterFactoryParams<T = ValueFormat> {
     valueFormat: T;
     locale: Locale;
     numberFormat: NumberFormatConfig;
-    /**
-     * Advanced override merged onto the formatter's default Intl options, used by axis/tick label
-     * compaction (e.g. dropping the year on dense date axes). Standard value formatting omits it and
-     * lets each kind's defaults stand.
-     */
     intlOptions?: Intl.NumberFormatOptions | Intl.DateTimeFormatOptions;
 }
 
@@ -6455,7 +5976,6 @@ export declare type VariablePredicate = {
     range: [DataValue, DataValue];
 };
 
-/** Internal column names holding each observation's resolved visual channels (color, size, etc.). */
 export declare const VISUAL_VARIABLES: {
     readonly color: string;
     readonly size: string;
@@ -6469,6 +5989,8 @@ export declare const VISUAL_VARIABLES: {
  * `alpha`, `strokeWidth`) on each layer's dataset.
  */
 declare class VisualMapperCompiler extends PerLayerStage<VisualMapperCompilerInput> {
+    private readonly geomCompiler;
+    constructor(geomCompiler: GeomCompiler);
     protected dependencies(input: VisualMapperCompilerInput): readonly unknown[];
     protected compileLayer(layer: CompiledLayer, input: VisualMapperCompilerInput): CompiledLayer;
 }