@graphysdk/viz-engine 0.0.1-alpha.6 → 0.0.1-experimental.1

package/dist/index.d.ts

@@ -1,49 +1,45 @@
+/**
+ * `@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';
 
-/** The exact-aes object a geom def's builder accepts — every admitted key optional. */
-declare type AesFromDef<Def extends Geom<unknown>> = {
-    [Key in AesKeysOf<Def>]?: AestheticValue;
-};
-
-/**
- * The aes key one position role contributes: a `point` role its axis; a `min`/`max`/`scalar` role its
- * declared `aes` — a plain `string`, so a custom positional aesthetic (`'open'`) is recovered too (a
- * role with no `aes` contributes nothing). Mirrors `deriveDeclaredAesthetics` at the type level.
- */
-declare type AesFromRole<Role extends PositionRole> = Role['role'] extends 'point' ? Role['axis'] : Role['role'] extends 'min' | 'max' | 'scalar' ? Role extends {
-    aes: infer A extends string;
-} ? A : never : never;
-
-/**
- * Distributes {@link AesFromRole} over a geom's position-role union. {@link AesFromRole} keys on
- * `Role['role']` rather than a naked `Role`, so it does *not* distribute on its own — applied to the
- * union directly it collapses to `never`. The `Roles extends Roles` hop forces per-member evaluation.
- */
-declare type AesFromRoles<Roles extends PositionRole> = Roles extends Roles ? AesFromRole<Roles> : never;
-
-/**
- * The aes keys a geom def admits: its position keys ∪ its declared `aesthetics` keys. A widened
- * `positionRoles` relaxes the position half to {@link AestheticKey}, which absorbs the union — so
- * authoring still compiles with the exact-aes check dropped.
- */
-declare type AesKeysOf<Def extends Geom<unknown>> = PositionAesKeys<Def> | DeclaredAesKeys<Def>;
-
-/**
- * Maps each aesthetic to a variable or constant value. The built-in channels (x, y, color, …) keep
- * exact types and autocomplete; the index signature also admits a geom's **custom positional
- * aesthetics** — an OHLC candlestick's `open`/`high`/`low`/`close` — which the geom declares on its
- * position contract and the engine then trains and scales like a built-in channel.
- */
-export declare interface AesMapping extends KnownAesthetics {
-    [aesthetic: string]: AestheticValue | undefined;
+/** 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 built-in aesthetic that can be mapped, such as `'x'` or `'color'`. */
-export declare type AestheticKey = keyof KnownAesthetics;
+/** Name of a single visual channel that can be mapped, such as `'x'` or `'color'`. */
+export declare type AestheticKey = keyof AesMapping;
 
 /**
  * Aesthetic value can be:
@@ -51,7 +47,7 @@ export declare type AestheticKey = keyof KnownAesthetics;
  * - { variable: string } (explicit variable mapping)
  * - { value: DataValue } (constant value applied to every observation)
  */
-export declare type AestheticValue = string | VariableMapping | ValueMapping;
+declare type AestheticValue = string | VariableMapping | ValueMapping;
 
 declare function aggregate(options: AggregateOptions): AggregateTransformInput;
 
@@ -89,59 +85,6 @@ declare type AggregationInput = Record<VariableName, {
     aggregation: AggregationFunction;
 }>;
 
-/**
- * Which point of a target's box an anchor resolves to. Compass directions name the
- * eight edge/corner points; `center` is the box centre. Omitted means the geom-natural
- * point (e.g. a bar's top-edge midpoint).
- */
-export declare type AnchorAlign = 'center' | 'top' | 'right' | 'bottom' | 'left' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-
-/**
- * A hit with a scale-derived panel anchor — every index kind except `'render-hit-test'`. The compiler's
- * position scales give it a real `(x, y)`, so an overlay marker (hover dot, guide line) can be placed at it.
- */
-export declare interface AnchoredHoverHit extends HoverHitBase {
-    /** Discriminant: this hit has a real anchor, so `x`/`y` are safe to read. */
-    anchored: true;
-    /**
-     * 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
-     * polar cells use (center = panel center, outer radius = `min(panel.w, panel.h) / 2`).
-     */
-    x: number;
-    y: number;
-}
-
-/**
- * A render-owned hit (`'render-hit-test'`: sankey, treemap, voronoi): the geometry lives render-side, so
- * the engine has no scale-derived anchor for it — there is deliberately no `x`/`y`. A render-owned geom's
- * `renderHover` derives its overlay from `observation`, and the tooltip follows the live cursor.
- */
-export declare interface AnchorlessHoverHit extends HoverHitBase {
-    /** Discriminant: no anchor. Narrow on this before reading `x`/`y`, which this variant does not carry. */
-    anchored: false;
-}
-
-/**
- * A nudge applied after a target resolves. `unit` selects the frame: `'panel'` is a
- * fraction of the plot rect, `'px'` is device pixels (resolved at runtime).
- */
-export declare interface AnchorOffset {
-    x?: number;
-    y?: number;
-    /** Defaults to `'panel'`. */
-    unit?: 'panel' | 'px';
-}
-
-/** A per-observation anchor position in normalised panel `[0, 1]` space (annotation anchoring). */
-export declare interface AnchorPosition {
-    x: number;
-    y: number;
-}
-
 /**
  * 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.
@@ -160,55 +103,6 @@ export declare interface AngleExtent {
     endAngle: NumericDataValue;
 }
 
-/**
- * Builder for the built-in annotation kinds — the pipeable counterpart to setting the `annotations`
- * field by hand. Each method returns an {@link AnnotationItem}; piped into `createSpec`/`pipe` it appends
- * to the matching {@link AnnotationsInput} field, so annotations compose left-to-right like every other
- * spec feature (geoms, scales, highlights). Multiple calls of the same kind accumulate.
- *
- * @example
- *   import { pipe, createSpec, geom, scale, annotation } from '@graphysdk/viz-engine';
- *
- *   pipe(
- *     createSpec({ x: 'month', y: 'revenue', color: 'region' }),
- *     geom.line(),
- *     scale.x.discrete(),
- *     scale.y(),
- *     scale.color.palette(),
- *     annotation.differenceArrow({
- *       start: { anchorValue: 'Jan', groupValue: 'North' },
- *       end: { anchorValue: 'Jun', groupValue: 'North' },
- *       label: 'relative-difference',
- *     }),
- *     annotation.shape({
- *       region: { anchorType: 'panel', x: 0, y: 0.7, width: 1, height: 0.3 },
- *       fillColor: '#e15759',
- *       fillOpacity: 0.12,
- *     }),
- *   );
- */
-export declare const annotation: {
-    /** A labelled delta between two data observations — reads the measured gap between them. */
-    differenceArrow(input: DifferenceArrowInput): AnnotationItem;
-    /** A shaded box whose area is positioned by a region anchor (panel fractions or a data selection). */
-    shape(input: ShapeInput): AnnotationItem;
-    /** A free-standing arrow whose endpoints are point anchors (panel fractions or observations). */
-    arrow(input: ArrowInput): AnnotationItem;
-    /** A free-standing rich-text label positioned by a point anchor. */
-    text(input: TextAnnotationInput): AnnotationItem;
-    /** An image whose area is positioned by a region anchor (panel fractions or a data selection). */
-    image(input: ImageAnnotationInput): AnnotationItem;
-    /** Editor-only: compiles but has NO painter in `@graphysdk/react-renderer`. */
-    sticker(input: StickerAnnotationInput): AnnotationItem;
-    /** Editor-only: compiles but has NO painter in `@graphysdk/react-renderer`. */
-    pinnedNumber(input: PinnedNumberAnnotationInput): AnnotationItem;
-    /** Editor-only: compiles but has NO painter in `@graphysdk/react-renderer`. */
-    comment(input: CommentAnnotationInput): AnnotationItem;
-};
-
-/** Pixel gap between an anchor and the near edge of its mini bubble. */
-export declare const ANNOTATION_TOOLTIP_MARKER_GAP = 9;
-
 /** Anchors an annotation to a data point by row position, column, and/or category value. */
 declare interface AnnotationDataPoint {
     rowIndex?: number;
@@ -217,57 +111,16 @@ declare interface AnnotationDataPoint {
 }
 
 /**
- * The value returned by an {@link annotation} builder. Treat it as an opaque token — pipe
- * it into a spec, don't construct it by hand.
- */
-export declare type AnnotationItem = {
-    type: 'annotation';
-    kind: 'differenceArrow';
-    annotation: DifferenceArrowInput;
-} | {
-    type: 'annotation';
-    kind: 'shape';
-    annotation: ShapeInput;
-} | {
-    type: 'annotation';
-    kind: 'arrow';
-    annotation: ArrowInput;
-} | {
-    type: 'annotation';
-    kind: 'text';
-    annotation: TextAnnotationInput;
-} | {
-    type: 'annotation';
-    kind: 'image';
-    annotation: ImageAnnotationInput;
-} | {
-    type: 'annotation';
-    kind: 'sticker';
-    annotation: StickerAnnotationInput;
-} | {
-    type: 'annotation';
-    kind: 'pinnedNumber';
-    annotation: PinnedNumberAnnotationInput;
-} | {
-    type: 'annotation';
-    kind: 'comment';
-    annotation: CommentAnnotationInput;
-};
-
-/**
- * Compiles annotations into a render-ready format. Every anchor is projected into normalized panel
- * space `[0, 1]²` with one convention: data-up (y=0 at the bottom). The renderer flips `y` once at
- * paint time.
+ * Compiles annotations into a render-ready format.
  *
- * - Difference arrows: each `(anchor, group)` endpoint is projected. Cartesian only.
- * - Pinned numbers / comments: observation-anchored, projected the same way (cartesian + polar).
- * - Shapes / images / arrows / text / stickers: their point and region anchors are projected here,
- *   so a `panel` anchor is flipped from top-left to data-up and an `observation` anchor tracks the
- *   observation it points at.
+ * - Difference arrows: each `(anchor, group)` endpoint is projected into normalized panel
+ *   space `[0, 1]²`. Cartesian only.
+ * - Stickers, pinned numbers and comments: the single anchor is projected the same way.
+ *   Supported in both cartesian and polar coord systems (pies pin annotations to slice midpoints).
+ * - Shapes / freeform arrows / text annotations: coordinates are already in `[0, 1]`, so the
+ *   stage passes them through into dedicated `Compiled<Kind>` types.
  */
 declare class AnnotationsCompiler extends Stage<AnnotationsCompilerInput, CompiledAnnotations> {
-    private readonly container;
-    constructor(container: CommonContainer);
     protected dependencies(input: AnnotationsCompilerInput): readonly unknown[];
     protected run(input: AnnotationsCompilerInput): CompiledAnnotations;
 }
@@ -277,52 +130,30 @@ declare interface AnnotationsCompilerInput {
     annotations: AnnotationsSpec;
     layers: readonly CompiledLayer[];
     coordSystem: CoordSystem;
-    config: AnnotationsConfig;
 }
 
-/**
- * Subset of {@link ConfigSpec} the annotations stage reads. Narrowed so unrelated config changes
- * don't enter the cache dependency surface.
- */
-declare type AnnotationsConfig = Pick<ConfigSpec, 'parsingLocale'>;
-
-/** All annotations attached to a graph, as user-facing input. */
+/** All annotations attached to a chart, as user-facing input. Every group is optional. */
 export declare interface AnnotationsInput {
     differenceArrows?: DifferenceArrowInput[];
     shapes?: ShapeInput[];
-    freeformArrows?: ArrowInput[];
+    freeformArrows?: FreeformArrowInput[];
     textAnnotations?: TextAnnotationInput[];
-    images?: ImageAnnotationInput[];
     stickers?: StickerAnnotationInput[];
     pinnedNumbers?: PinnedNumberAnnotationInput[];
     comments?: CommentAnnotationInput[];
 }
 
-/** Resolved annotations for a graph, with all fields defaulted. */
+/** Resolved annotations for a chart, with every group present and all fields defaulted. */
 export declare interface AnnotationsSpec {
     differenceArrows: DifferenceArrowSpec[];
     shapes: ShapeSpec[];
-    freeformArrows: ArrowSpec[];
+    freeformArrows: FreeformArrowSpec[];
     textAnnotations: TextAnnotationSpec[];
-    images: ImageAnnotationSpec[];
     stickers: StickerAnnotationSpec[];
     pinnedNumbers: PinnedNumberAnnotationSpec[];
     comments: CommentAnnotationSpec[];
 }
 
-/**
- * Whether an annotation renders beneath the geoms (background) or on top (foreground).
- */
-export declare type AnnotationZOrder = 'background' | 'foreground';
-
-/**
- * A transform input that may be built-in or custom. Used at the spec-construction boundary
- * (`pipe`/`createSpec` items, `SpecInput.transforms`) and the transform compile stage, so a custom
- * transform pipes in and applies through the registry — while {@link TransformInput} stays the clean
- * built-in union everywhere a `transformType` is narrowed.
- */
-export declare type AnyTransformInput = TransformInput | CustomTransformInput<string>;
-
 declare interface Appearance {
     /** Id of the color palette to apply to all series. */
     paletteId?: string;
@@ -330,7 +161,7 @@ declare interface Appearance {
     seriesStyles?: Record<string, SeriesStyle>;
     /** Colors all bars the same instead of giving each category its own palette color. */
     useSingleColorForBars?: boolean;
-    /** Tints the graph background with the palette instead of leaving it plain. */
+    /** Tints the chart background with the palette instead of leaving it plain. */
     backgroundModifier?: 'none' | 'tint';
     border?: Partial<{
         style: 'none' | 'custom' | 'tinted' | 'gradient' | 'preset' | 'grey';
@@ -338,7 +169,10 @@ declare interface Appearance {
         width: number;
     }>;
     hasRoundedCorners?: boolean;
-    textStyle?: AppearanceTextStyle;
+    textStyle?: Partial<{
+        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. */
@@ -374,7 +208,7 @@ 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.
+     * 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
@@ -403,11 +237,6 @@ export declare interface AppearanceSpec {
     highlightStyle: HighlightStyle;
 }
 
-export declare type AppearanceTextStyle = Partial<{
-    heading: GraphTextStyle;
-    body: GraphTextStyle;
-}>;
-
 declare function area(options?: GeomOptions<'area'>): LayerInputOf<'area'>;
 
 /**
@@ -416,7 +245,7 @@ declare function area(options?: GeomOptions<'area'>): LayerInputOf<'area'>;
 export declare interface AreaGeomParams {
     /**
      * Outline stroke width in pixels. `'auto'` reads the per-observation
-     * `strokeWidth` value (`getStrokeWidth`), falling back to the geom default.
+     * `strokeWidth` channel (`getStrokeWidth`), falling back to the geom default.
      */
     lineWidth: number | 'auto';
     /**
@@ -426,12 +255,11 @@ export declare interface AreaGeomParams {
      */
     interpolate: InterpolateType;
     /**
-     * How to handle missing (null/undefined) values. As for line:
-     * - `'zero'`: nulls arrive already substituted with zero by the compiler.
-     * - `'gap'`: break the path at a null.
-     * - `'connect'`: drop nulls before pathing so the line spans the gap.
+     * 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;
 }
 
@@ -440,46 +268,20 @@ export declare interface AreaPathGenerators {
     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;
+    /** 0..1 of plot height. */
+    y: number;
+}
+
 /** Whether an arrow end carries an arrowhead. */
 export declare type ArrowheadStyle = 'none' | 'line-arrow';
 
-/**
- * Arrow annotation. Each endpoint is a {@link PointAnchorInput}, so it can float in
- * panel fractions or pin to an observation. Distinct from {@link DifferenceArrowInput},
- * which reads the measured gap between two observations.
- */
-export declare interface ArrowInput {
-    id?: string;
-    /** Tail endpoint. */
-    start: PointAnchorInput;
-    /** Head endpoint. */
-    end: PointAnchorInput;
-    /** null falls back to the theme `defaultAnnotationArrowStroke`. */
-    color?: string | null;
-    thickness?: ArrowThickness;
-    startArrowheadStyle?: ArrowheadStyle;
-    endArrowheadStyle?: ArrowheadStyle;
-    lineStyle?: ArrowLineStyle;
-    /** Render with a raised, outlined sticker-like appearance. */
-    hasStickerStyle?: boolean;
-}
-
 /** Whether an arrow's line is drawn solid or dashed. */
 export declare type ArrowLineStyle = 'solid' | 'dashed';
 
-/** Resolved arrow with all optional fields defaulted. */
-export declare interface ArrowSpec {
-    id: string;
-    start: PointAnchor;
-    end: PointAnchor;
-    color: string | null;
-    thickness: ArrowThickness;
-    startArrowheadStyle: ArrowheadStyle;
-    endArrowheadStyle: ArrowheadStyle;
-    lineStyle: ArrowLineStyle;
-    hasStickerStyle: boolean;
-}
-
 /** Preset stroke weight for an arrow annotation. */
 export declare type ArrowThickness = 'thin' | 'medium' | 'thick';
 
@@ -492,8 +294,7 @@ declare interface AverageLine {
  * Visual descriptor for the swatch rendered inside an average-line label pill.
  */
 export declare interface AverageLineSymbol {
-    /** The source layer's geom — the renderer reads its swatch shape off the geom's render contract. */
-    geom: string;
+    shape: SwatchShape;
     color: string;
 }
 
@@ -526,27 +327,24 @@ declare interface AxisGridConfig {
      * Whether grid lines are visible.
      * - true/false: explicit visibility
      * - null: let the compiler decide based on geom/coord policies
-     *   (visible unless a geom policy hides it, e.g. bar charts hide the x grid)
+     *   (defaults to false for x-axis, true for y-axis)
      */
     isVisible: boolean | null;
-    /**
-     * Line style of this axis's grid lines.
-     * @default 'dashed'
-     */
-    lineStyle: LineStyleType;
-    /**
-     * Stroke width of this axis's grid lines in px. null inherits the theme's grid line width.
-     * @default null
-     */
-    lineWidth: number | null;
 }
 
+/**
+ * Label display mode for axis ticks
+ * - 'auto': Show all ticks (default behavior)
+ * - 'edges': Show only the first and last tick
+ */
+declare type AxisLabelMode = 'auto' | 'edges';
+
 /**
  * Maps each positional aesthetic to its axis orientation.
  * The guide compiler uses this to determine where axes are placed
  * and what geometry they use (e.g., linear vs circular grid lines).
  */
-export declare interface AxisMapping {
+declare interface AxisMapping {
     x: {
         position: AxisPosition;
         geometry: GuideGeometry;
@@ -584,7 +382,7 @@ export declare interface AxisTick {
      * 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`
+     * For discrete scales this is the band CENTER; the band spans `position ± bandwidth/2`
      * (see {@link CompiledAxisGuide.bandwidth}).
      */
     position: number;
@@ -599,24 +397,17 @@ export declare interface AxisTickCandidate {
     valueFormat?: ValueFormat;
 }
 
-/**
- * Display mode for axis ticks
- * - 'auto': Show all ticks (default behavior)
- * - 'edges': Show only the first and last tick
- */
-declare type AxisTickMode = 'auto' | 'edges';
-
 /**
  * Configuration for a single axis's ticks
  */
 declare interface AxisTicksConfig {
     isVisible: boolean;
-    mode: AxisTickMode;
+    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.
+ * `'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).
@@ -655,8 +446,8 @@ declare function bar(options?: GeomOptions<'bar'>): LayerInputOf<'bar'>;
 
 /**
  * Bar/Column-specific parameters — intentionally empty. A bar's geometry comes
- * entirely from the position variables (band edges plus bar length); corner radius
- * and grouping are renderer-owned styling, not spec params.
+ * entirely from the position columns (band edges plus bar length); corner radius
+ * and column grouping are renderer-owned styling, not spec params.
  */
 declare type BarGeomParams = Record<string, never>;
 
@@ -681,7 +472,7 @@ declare interface BaseCoordParams {
 declare interface BaseGeomOptions<T extends GeomParams> {
     /** Layer-local aesthetic mapping, merged over the spec-level mapping. */
     aes?: AesMapping;
-    stat?: StatName | StatInput | CustomStatInput<string>;
+    stat?: StatName | StatInput;
     position?: PositionType;
     yScaleType?: YScaleType;
     params?: Partial<T>;
@@ -703,8 +494,8 @@ export declare const BORDER_PRESET_GRADIENTS: Record<BorderPreset, string>;
 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 graph bounds. `'none'` carries no `color`/`width`.
- * Narrow on `type` before reading either.
+ * 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.
@@ -779,15 +570,14 @@ export declare type BoxSize = {
 };
 
 /**
- * For each average-line rule in a graph with a categorical color grouping, returns the source geom
- * + color the renderer paints inside the rule's label pill (mapping the geom to a swatch shape via
- * its `(geom, coord)` registry).
+ * 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`,
+ * 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
+ * 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 group didn't resolve to a color).
+ * symbol (e.g. no categorical color grouping, or the rule's series didn't resolve to a color).
  *
  * Two shapes of rule layer are handled:
  * - **Filtered**: the rule carries an `eq`-filter. The color-scale lookup value is the filter's
@@ -795,14 +585,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): ReadonlyMap<string, AverageLineSymbol>;
-
-/**
- * Turns placed callouts into the hit regions the pointer tracker tests. Only in-view callouts get
- * a region. The anchor goes through `toPanelCursor` — the same mapping the tracker applies to the
- * live cursor — so the hover engine resolves the same observation the marker pixel would.
- */
-export declare const buildCalloutHitRegions: (placed: readonly PlacedCallout[], panelRect: Rect) => CalloutHitRegion[];
+export declare function buildAverageLineSymbols(layers: readonly LayerSpec[], colorScale: CompiledScale | undefined, coordSystem: CoordSystem): ReadonlyMap<string, AverageLineSymbol>;
 
 /**
  * Pure projection of `(layers, coordSystem, axes, formatter context, panelRect, measureDataLabel)`
@@ -831,16 +614,11 @@ export declare interface BuildDataLabelsContentInput {
 }
 
 /**
- * Normalise **any** thrown value into a serialisable {@link VizDiagnostic}. A {@link VizError}
- * maps field-for-field (`severity: 'error'`); anything else — a plain `Error`, a string, an
- * unexpected throw — becomes `kind: 'internal'`, `code: 'INTERNAL_INVARIANT'`, so even surprises
- * emit structured output for telemetry and codegen rather than an opaque message.
- */
-export declare function buildDiagnostic(error: unknown): VizDiagnostic;
-
-/**
- * Builds a CSS font shorthand string from a FontSpec.
- * Always quotes the family name to safely handle names with spaces.
+ * 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.
  *
  * Renderer-agnostic: usable by browser (OffscreenCanvas) and backend
  * (@napi-rs/canvas) measurers to set `ctx.font` before `ctx.measureText()`.
@@ -858,16 +636,6 @@ declare interface BuildLayerYValueFormatterInput {
     locale: Locale;
 }
 
-/**
- * Formats a pinned number's value using the value format resolved onto its anchor at compile time.
- */
-export declare function buildPinnedNumberValueFormatter({ numberFormat, locale, }: BuildPinnedNumberValueFormatterInput): (anchor: ResolvedObservationPoint) => string;
-
-declare interface BuildPinnedNumberValueFormatterInput {
-    numberFormat: NumberFormatConfig;
-    locale: Locale;
-}
-
 /**
  * Builds the SVG arc path for a polar bar (pie / donut slice).
  *
@@ -876,7 +644,10 @@ declare interface BuildPinnedNumberValueFormatterInput {
 export declare const buildPolarBarArcPath: (input: PolarBarArcInput) => string | null;
 
 /**
- * Pure projection of `(compiled, hover)` into the tooltip's `{ header, rows }`. Returns `null` when there is no primary hit; use that as the tooltip show/hide signal.
+ * 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.
  *
  * 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
@@ -890,9 +661,9 @@ export declare const buildTooltipContent: ({ layers, coordSystem, scales, guides
  * 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-group swatch/label data. */
+    /** 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` (gates the header). */
+    /** 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;
@@ -925,31 +696,6 @@ export declare class CachedTextMeasurer implements TextMeasurer {
     private getCacheKey;
 }
 
-/**
- * A pinned-callout hit region the pointer tracker tests in memory.
- */
-export declare interface CalloutHitRegion {
-    /** Hit rectangle in panel-local pixels — the same space as `(clientX, clientY) - captureRect`. */
-    rect: Rect;
-    /** Normalized, y-flipped cursor used to resolve this callout's observation from the hover engine. */
-    cursor: HoverCursor;
-    /** The data anchor (marker) in panel-local pixels; the tooltip anchors here to cover the mini. */
-    markerPx: {
-        x: number;
-        y: number;
-    };
-    /** Direction the mini sits from the marker, so the tooltip can expand over it the same way. */
-    placement: CalloutPlacement;
-}
-
-/** Which kind of annotation a callout renders. */
-export declare type CalloutKind = 'pinned-number' | 'comment';
-
-export declare type CalloutMeasurer = (kind: CalloutKind, text: string) => BoxSize;
-
-/** Direction the mini bubble sits relative to its anchor. */
-export declare type CalloutPlacement = 'top' | 'right' | 'bottom' | 'left';
-
 declare interface CartesianCoordInput {
     type: 'coord';
     coordType: 'cartesian';
@@ -975,9 +721,8 @@ 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-variables carry the measure / cross-axis extent and the y-variables carry the
-     * main-axis band — but that swap is already applied to the position variables by the coord transform,
-     * so geoms read `getX`/`getY` without branching. See {@link MainAxis}.
+     * 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 */
@@ -1012,8 +757,7 @@ declare interface CategoricalValueFormat {
 declare interface ColorGroup {
     value: DataValue;
     color: string;
-    /** The owning layer's geom — the renderer reads its swatch shape off the geom's render contract. */
-    geom: string;
+    shape: SwatchShape;
     layerIndex: number;
     /** Format for the group's `value`, resolved from the owning layer's color column. */
     valueFormat: ValueFormat;
@@ -1040,7 +784,7 @@ declare interface ColorScaleMethods {
 }
 
 declare interface ComboOptions {
-    /** Geometry used for the bar-like series alongside line series in a combo graph. */
+    /** Geometry used for the bar-like series alongside line series in a combo chart. */
     comboType?: 'grouped-bars' | 'stacked-bars' | 'lines';
 }
 
@@ -1065,6 +809,8 @@ export declare interface Command<TParams extends Record<string, unknown> = Recor
      * 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.
      */
     apply: (spec: Spec) => CommandApplyResult | null;
 }
@@ -1261,42 +1007,32 @@ export declare interface CommandStackSnapshot {
  */
 declare interface CommentAnnotationInput {
     id?: string;
-    at: ObservationAnchorInput;
+    anchor: ObservationAnchorInput;
     content: RichTextContent;
 }
 
 declare interface CommentAnnotationSpec {
     id: string;
-    at: ObservationAnchor;
+    anchor: ObservationAnchor;
     content: RichTextContent;
 }
 
-/**
- * Cross-cutting services shared across a single compile, created once per {@link Compiler} and
- * passed as the first argument to every collaborator that needs them.
- */
-declare interface CommonContainer {
-    diagnostics: DiagnosticsCollector;
-    /** The geom registry, so resolvers can read declared capabilities (e.g. scale constraints). */
-    geomRegistry: GeomRegistry;
-}
-
 /** Comparison operators for declarative filtering. */
 declare type ComparisonOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte';
 
 /**
- * All annotations of a graph after compilation, grouped by kind and ready for the renderer.
+ * All annotations of a chart after compilation, grouped by kind and ready for the renderer.
  *
- * The engine does not impose paint order across kinds; the renderer decides it. The one ordering
- * signal carried here is {@link CompiledShape.zOrder}, which marks a shape as drawing behind
- * (`background`) or over (`foreground`) the geoms.
+ * 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[];
     freeformArrows: CompiledFreeformArrow[];
     textAnnotations: CompiledTextAnnotation[];
-    images: CompiledImageAnnotation[];
     stickers: CompiledStickerAnnotation[];
     pinnedNumbers: CompiledPinnedNumberAnnotation[];
     comments: CompiledCommentAnnotation[];
@@ -1313,45 +1049,34 @@ export declare interface CompiledAxisGuide {
     /** The aesthetic this axis serves (always 'x' or 'y') */
     aesthetic: AestheticKey;
     /**
-     * Axis placement. Already reflects any flip, do not re-derive from the coord system's `mainAxis`.
+     * Axis placement. Already reflects any flip — drive placement off this, do NOT re-derive from the coord
+     * system's `mainAxis`.
      */
     position: AxisPosition;
-    /**
-     * Geometric shape the axis traces.
-     * - `'linear'` for a straight cartesian edge (drawn by the cartesian grid/axis renderers),
-     * - `'circular'` for a radar's angular spoke axis
-     * - `'radial'` for its ring axis.
-     *
-     * Mirrors the coord system's `axisMapping[aesthetic].geometry`.
-     */
-    geometry: GuideGeometry;
     /** Title text, null means no title */
     label: string | null;
     /**
-     * Gates the whole axis region (line + ticks + labels).
+     * Gates the whole axis region (line + ticks + labels). Orthogonal to `ticksVisible` / `gridVisible` and to
+     * {@link CompiledPanel.border}.
      */
     isVisible: boolean;
     /**
-     * Candidate tick sets, sorted by ascending count. These are raw candidates, not the final selection.
-     * Final selection happens in `LayoutCompiler`. The renderer
-     * paints the resulting `FormattedAxis.ticks` verbatim; it must not re-select candidates here.
+     * 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.
      */
     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`.
+     * renderer paints `FormattedAxis.ticks[].formattedLabel` as-is and must NOT re-apply this `ValueFormat`.
      */
     valueFormat: ValueFormat;
     /** Tick mode from config. Already honored by the compiler when building candidates — don't re-filter ticks. */
-    tickMode: AxisTickMode;
+    tickMode: AxisLabelMode;
     /** Whether tick marks are visible. Labels still show when this is false (independent of `isVisible`). */
     ticksVisible: boolean;
     /** Whether grid lines are visible at tick positions. Grid is drawn separately from the axis region. */
     gridVisible: boolean;
-    /** Line style of this axis's grid lines. */
-    gridLineStyle: LineStyleType;
-    /** Stroke width of this axis's grid lines in px. null inherits the theme's grid line width. */
-    gridLineWidth: number | null;
     /** Scale type — the renderer uses this to select a formatting strategy */
     scaleType: ScaleType;
     /** Band width in [0, 1] space for discrete position scales. Undefined otherwise. */
@@ -1361,9 +1086,9 @@ export declare interface CompiledAxisGuide {
 /**
  * Compile-time projection of a comment annotation.
  */
-export declare interface CompiledCommentAnnotation {
+declare interface CompiledCommentAnnotation {
     id: string;
-    at: ResolvedObservationPoint;
+    anchor: ResolvedObservationAnchor;
     content: RichTextContent;
 }
 
@@ -1376,8 +1101,8 @@ declare type CompiledConfig = Omit<ConfigSpec, 'appearance'> & {
  */
 export declare interface CompiledDifferenceArrow {
     id: string;
-    start: ResolvedObservationPoint;
-    end: ResolvedObservationPoint;
+    start: ResolvedObservationAnchor;
+    end: ResolvedObservationAnchor;
     /**
      * Resolved color. Precedence:
      * 1. user-specified `arrow.color`
@@ -1388,23 +1113,17 @@ export declare interface CompiledDifferenceArrow {
     size: DifferenceArrowSize;
     /** Which quantity the arrow's label reports (absolute, relative, or proportion of the two endpoints). */
     label: DifferenceArrowLabelKind;
-    /**
-     * Label position along the arrow as a fraction of its length, anchored to the geometric edge (not
-     * the endpoints): 0 = left, 1 = right (top/bottom when flipped). Defaults to 0.5.
-     */
+    /** Where the label sits along the arrow, as a fraction from start (0) to end (1). */
     labelCrossPosition: number;
 }
 
-/** The three compile-side definition shapes a plugin can contribute. */
-export declare type CompileDefinition = Geom<unknown> | StatDefinition | TransformDefinition;
-
 /**
- * Compile-time projection of an arrow annotation.
+ * Compile-time projection of a freeform arrow.
  */
 export declare interface CompiledFreeformArrow {
     id: string;
-    start: ResolvedPoint;
-    end: ResolvedPoint;
+    start: ArrowEndpoint;
+    end: ArrowEndpoint;
     /** Line color, or `null` to fall back to the theme default. */
     color: string | null;
     thickness: ArrowThickness;
@@ -1415,7 +1134,7 @@ export declare interface CompiledFreeformArrow {
     hasStickerStyle: boolean;
 }
 
-export declare interface CompiledGeom {
+declare interface CompiledGeom {
     /** The reparameterized dataset (may have new computed variables) */
     data: Dataset;
     /** Any mapping overrides produced by the geom */
@@ -1447,11 +1166,6 @@ export declare interface CompiledGuides {
      * source legends, headline, and tooltip all read so they agree on how each series reads.
      */
     colorGroups: ColorGroup[];
-    /**
-     * Friendly display labels keyed by variable name. Runtime consumers (e.g. tooltips) resolve a
-     * series' label from this rather than borrowing a guide's title.
-     */
-    variableLabels: VariableLabels;
 }
 
 /**
@@ -1471,65 +1185,25 @@ export declare interface CompiledIdentityScale extends CompiledScaleBase {
     map: (value: DataValue) => DataValue;
 }
 
-/**
- * Compile-time projection of an image annotation.
- */
-export declare interface CompiledImageAnnotation {
-    id: string;
-    /** Image URL or data URI. */
-    src: string;
-    /** Whether the image draws behind the geoms (background) or over them (foreground). */
-    zOrder: AnnotationZOrder;
-    region: ResolvedRegion;
-    /** How the image scales inside its box. */
-    fit: ImageAnnotationFit;
-    opacity: number;
-}
-
 /**
  * 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-geom React keys on it — geoms morph instead of remounting — and
+     * 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`.
      */
     id: string;
     /**
-     * This layer's transformed, render-ready dataset. Within a group, the observations
+     * 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 observation per group; per-observation geoms (bar, point) iterate `data` directly.
+     * (`data.groupBy(...)`) — one mark per group; per-mark geoms (bar, point) iterate `data` directly.
      */
     data: Dataset;
-    /**
-     * The geom this layer paints. A plain `string` (not {@link GeomName}): the compiled spec is
-     * serialisable and reaches a renderer with no knowledge of the registered plugins, so a custom
-     * geom's identity survives as its name and downstream resolution is a registry lookup. Narrow back
-     * to a built-in flavour with {@link isLayerOf} / {@link CompiledLayerFor}.
-     */
-    geom: string;
-    /**
-     * The coord-agnostic hit-test shape this layer's geom declares, baked from the geom def at compile
-     * time. The runtime hover indexer (`build-layer-index`) reads this plus the chart's coord system to
-     * build the projected index, so a custom geom is indexed by what it declares rather than by name, and
-     * the polar projection (a pie's `cells`, a radar's angle-snap) is a runtime fact of the coord.
-     */
-    spatialKind: SpatialKind;
-    /**
-     * What counts as "the same observation" for this layer, baked from the geom def. The runtime
-     * resolves a `'render-hit-test'` tester's returned key against this, and morphs/hover-stability
-     * use it across recompiles.
-     */
-    identityKey: IdentityKey;
-    /**
-     * The geom's tooltip contract, baked from the geom def. When non-empty the tooltip shows one row
-     * per field (the field's `key` label, the raw value of its `aes` from the hovered observation),
-     * replacing the default y-value row. Empty for geoms that use the default tooltip.
-     */
-    tooltip: TooltipContract;
-    /** Final mapping after merging root + layer + stat + geom overrides (may carry custom positional aesthetics). */
+    geom: GeomName;
+    /** Final mapping after merging root + layer + stat + geom overrides */
     mapping: AesMapping;
     position: PositionType;
     yScaleType: YScaleType;
@@ -1567,8 +1241,8 @@ export declare type CompiledLayerFor<G extends GeomName> = Omit<CompiledLayer, '
  * 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 graph, render the hover result (see `HoverState`) in place of this.
+ * 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. */
@@ -1580,9 +1254,9 @@ export declare interface CompiledLayerHighlight {
 /** 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`. When this includes `'size'` the legend is a bubble
-     * legend.
+     * 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.
      */
     aesthetics: AestheticKey[];
     /** Title text, null means no title */
@@ -1595,21 +1269,15 @@ export declare interface CompiledLegendGuide {
     items: LegendItem[];
 }
 
-/** The plotting area's frame, telling the renderer which panel border edges to draw and how. */
+/** The plotting area's frame, telling the renderer whether to draw a border around the panel. */
 export declare interface CompiledPanel {
     /**
-     * Panel-rect outline, per edge. Drawn alongside the grid lines and independent of axis
-     * visibility. A corner is rounded only when both edges meeting at it are visible.
+     * 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: Record<PanelBorderEdge, CompiledPanelBorderEdge>;
-}
-
-/** One resolved edge of the panel border. */
-export declare interface CompiledPanelBorderEdge {
-    isVisible: boolean;
-    lineStyle: LineStyleType;
-    /** Stroke width in px. null inherits the theme's grid line width. */
-    lineWidth: number | null;
+    border: {
+        isVisible: boolean;
+    };
 }
 
 declare interface CompiledPerGroupHeadline {
@@ -1621,9 +1289,9 @@ declare interface CompiledPerGroupHeadline {
 /**
  * Compile-time projection of a pinned-number annotation.
  */
-export declare interface CompiledPinnedNumberAnnotation {
+declare interface CompiledPinnedNumberAnnotation {
     id: string;
-    at: ResolvedObservationPoint;
+    anchor: ResolvedObservationAnchor;
 }
 
 declare interface CompiledPositionAdjuster {
@@ -1661,7 +1329,7 @@ declare type CompiledPositionScaleOptions<Input = DataValue> = Omit<CompiledPosi
 /** Any compiled scale, discriminated by `kind` into position, visual, or identity. */
 export declare type CompiledScale<Input = DataValue> = CompiledPositionScale<Input> | CompiledVisualScale<Input> | CompiledIdentityScale;
 
-/** Shared interface for all compiled scales, regardless of `kind`. */
+/** 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;
@@ -1672,22 +1340,27 @@ declare interface CompiledScaleBase<Input = DataValue> {
     domain: Input[];
     /** The spec this scale was compiled from. */
     spec: ScaleSpec;
-    /** Produces axis/legend tick values. See {@link GenerateTicksOptions} for the supported variants. */
+    /** Produces axis/legend tick values; see {@link GenerateTicksOptions} for the supported variants. */
     generateTicks: (options?: GenerateTicksOptions) => Input[];
 }
 
-/** All compiled scales for a graph, keyed by the aesthetic each one drives. Absent keys are unmapped. */
+/** 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 rectangle annotation.
+ * 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.
  */
 export declare interface CompiledShape {
     id: string;
     kind: ShapeKind;
     /** Whether the shape draws behind the geoms (background) or over them (foreground). */
-    zOrder: AnnotationZOrder;
-    region: ResolvedRegion;
+    zOrder: ShapeZOrder;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
     fillColor: string;
     fillOpacity: number;
     strokeWidth: number;
@@ -1700,11 +1373,20 @@ export declare interface CompiledShape {
  * 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.
  */
 export declare interface CompiledSpec {
     /**
      * The resolved spec this output was compiled from, retained so callers can recompile or inspect the
-     * source.
+     * 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;
@@ -1715,7 +1397,7 @@ export declare interface CompiledSpec {
     annotations: CompiledAnnotations;
 }
 
-export declare interface CompiledStat {
+declare interface CompiledStat {
     /** The transformed dataset. */
     data: Dataset;
     /** Any mapping overrides produced by the stat (e.g., `y` → `'count'` for `CountStat`). */
@@ -1723,24 +1405,26 @@ export declare interface CompiledStat {
 }
 
 /**
- * Compile-time projection of a sticker annotation.
+ * Compile-time projection of a sticker annotation, anchored to one observation.
  */
-export declare interface CompiledStickerAnnotation {
+declare interface CompiledStickerAnnotation {
     id: string;
-    at: ResolvedPoint;
+    anchor: ResolvedObservationAnchor;
     sticker: StickerId;
 }
 
 /**
- * Compile-time projection of a text annotation.
+ * 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's height to fit the content.
+ * `width` and extends the box down to the panel's bottom edge.
  */
 export declare interface CompiledTextAnnotation {
     id: string;
     content: RichTextContent;
-    at: ResolvedPoint;
+    x: number;
+    y: number;
     width: number;
     /** Fill behind the text, or `null` for no background. */
     backgroundColor: string | null;
@@ -1755,8 +1439,8 @@ 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 etc).
-     * Already applied per observation by the visual mapper: read the resolved value via the matching
+     * 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}.
      */
@@ -1768,38 +1452,42 @@ declare type CompiledVisualScaleOptions<Input = DataValue> = Omit<CompiledVisual
 /**
  * The grammar-of-graphics engine. Orchestrates the compilation of a spec into render-ready output.
  *
- * The full pipeline is:
+ * 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}), which is how a dispatched command reaches the view.
- *
- * Conventions that hold across every compiled output:
- * - Positions are normalized to `[0,1]` with y up: x runs 0=left…1=right, y runs 0=bottom…1=top.
- *   A top-origin coordinate space inverts y as `1 - y`. Continuous unclamped scales may extrapolate
- *   outside `[0,1]` for out-of-domain inputs.
- * - Output is made of descriptors, not strings: values carry a {@link ValueFormat} and are formatted
- *   downstream at paint time (locale stays on the rendering side). Scales are callable `map` functions
- *   rather than reconstructable configuration; use value readers to access the raw values.
- * - Pixel layout is a separate step the engine owns: a {@link CompiledSpec} (or its slices) passes
- *   through {@link LayoutCompiler} to produce the panel/axis rects; geoms paint in `[0,1]` inside
- *   the panel rect.
+ * {@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 guides (legends, axes etc).
- * Per-stage memoization and dataset retention are instance-scoped: one `Compiler` is meant to live per
- * graph and be reused across recompiles.
+ * 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.
  *
- * Each layer is processed through the pipeline. Coords and scales are compiled separately as they apply
- * to the entire graph.
+ * Each layer is processed through the pipeline. Coords and scales are compiled separately as they apply to
+ * the entire plot.
  */
 export declare class Compiler {
-    private readonly container;
     private readonly dataCompiler;
     private readonly specCompiler;
     private readonly transformCompiler;
     private readonly constantMappingCompiler;
-    private readonly layerPhasedCompiler;
+    private readonly layerValidationCheck;
+    private readonly layerCompiler;
     private readonly scaleCompiler;
     private readonly coordCompiler;
     private readonly positionMapperCompiler;
@@ -1810,24 +1498,23 @@ export declare class Compiler {
     private readonly configCompiler;
     private readonly annotationsCompiler;
     private lastCompile;
-    private lastDiagnostics;
     private lastData;
     private readonly stages;
-    constructor(container: CommonContainer, dataCompiler: DataCompiler, specCompiler: SpecResolver, transformCompiler: TransformCompiler, constantMappingCompiler: ConstantMappingCompiler, layerPhasedCompiler: LayerPhasedCompiler, scaleCompiler: ScaleCompiler, coordCompiler: CoordCompiler, positionMapperCompiler: PositionMapperCompiler, visualMapperCompiler: VisualMapperCompiler, guideCompiler: GuideCompiler, summariseCompiler: SummariseCompiler, highlightsCompiler: HighlightsCompiler, configCompiler: ConfigCompiler, annotationsCompiler: AnnotationsCompiler);
+    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
+     * 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 geoms instead of remounting them.
+     * layer ids stable so id-keyed renderers can transition marks instead of remounting them.
      */
-    compile(args: {
+    compile({ input, data, ctx }: {
         input: CompilerInput;
         data: Data;
         ctx?: RendererContext;
-    }): CompileResult;
+    }): CompiledSpec;
     /**
      * Run the rendering pipeline against an already-resolved {@link Spec}.
      *
@@ -1838,16 +1525,16 @@ export declare class Compiler {
      * {@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
-     * guides (legends, axes etc) are derived from.
+     * 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.
      */
-    recompile(args: {
+    recompile({ spec, data }: {
         spec: Spec;
         data?: Data;
-    }): CompileResult;
+    }): CompiledSpec;
     /**
      * Per-stage cache hit/miss counters. Only populated in non-production builds — production builds
      * always report `{ hits: 0, misses: 0 }` because the counter increments tree-shake out.
@@ -1863,18 +1550,6 @@ export declare class Compiler {
      * production builds.
      */
     getLastCompile(): LastCompileSnapshot | null;
-    /**
-     * Diagnostics (errors and warnings) from the most recent compile/recompile, split by severity.
-     */
-    getDiagnostics(): DrainedDiagnostics | null;
-    /**
-     * Owns the diagnostics lifecycle for one compile: reset the collector on entry, run the pipeline,
-     * then drain into `lastDiagnostics` on the success tail. A throw escapes before the drain, leaving
-     * the collector populated for {@link toErrorResult} — the single failure-drain site.
-     */
-    private runCompile;
-    private toOkResult;
-    private toErrorResult;
     private trackCompile;
     private runPipeline;
 }
@@ -1890,27 +1565,13 @@ export declare const COMPILER_STAGE_KEYS: readonly ["data", "transform", "consta
  */
 export declare type CompilerCacheStats = Record<CompilerStageName, MemoStats>;
 
-/**
- * Result of {@link Compiler.compile} / {@link Compiler.recompile}. A success carries the compiled
- * spec; a failure carries `errors` (always a list — length 1 for a fail-fast stage, length N for
- * batched validation). Both carry any `warnings` the compile produced.
- */
-export declare type CompileResult = {
-    ok: true;
-    compiled: CompiledSpec;
-    warnings: VizDiagnostic[];
-} | {
-    ok: false;
-    errors: VizDiagnostic[];
-    warnings: VizDiagnostic[];
-};
-
 /**
  * Any value accepted by {@link Compiler.compile}: a low-level {@link SpecInput} or a
  * high-level {@link GraphConfig}. Data is passed as a separate argument.
  */
 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. */
@@ -1921,7 +1582,7 @@ export declare interface ComputedDifferenceArrow {
     /** SVG path for the arrowhead. */
     arrowheadPath: string;
     /**
-     * Pixel position of the label box center. The engine does not size the box: measure `labelText`
+     * 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`.
      */
@@ -1950,7 +1611,10 @@ export declare interface ComputedDifferenceArrow {
  * 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.
+ * `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;
@@ -1960,7 +1624,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 the theme `defaultAnnotationArrowStroke` token. */
     color: string | null;
     strokeWidth: number;
     /** SVG `stroke-dasharray` or `null` for a solid line. */
@@ -1990,11 +1654,14 @@ export declare const computeDifferenceArrow: ({ arrow, mainAxis, panelWidth, pan
 
 declare interface ComputeDifferenceArrowParams {
     arrow: CompiledDifferenceArrow;
-    /** Graph orientation. When `y` the arrow geometry is flipped to run horizontally. */
+    /**
+     * 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. */
+    /** Graph-wide text scale, applied to the label so it sizes with the rest of the chart. */
     textScale: number;
     locale: Locale;
 }
@@ -2025,15 +1692,6 @@ declare interface ComputeFreeformArrowParams {
     panelHeight: number;
 }
 
-/**
- * Computes the strokes for a panel border with per-edge visibility, line style and width.
- * A corner is rounded only when both of its edges are visible; edges sharing a style and width
- * join through the full corner arc, while differing ones split the arc at its midpoint. Returns
- * one path per contiguous same-styled run of visible edges — a single closed path when all four
- * match, empty when every edge is hidden.
- */
-export declare const computePanelBorderPaths: (border: CompiledPanel["border"], rect: Rect, cornerRadius: number) => PanelBorderPath[];
-
 /** Wraps partial config options into a tagged `ConfigItem` for inclusion in a spec. */
 export declare function config(options: ConfigInput): ConfigItem;
 
@@ -2041,8 +1699,6 @@ export declare function config(options: ConfigInput): ConfigItem;
  * Compiles config input into a render-ready CompliledConfig object.
  */
 declare class ConfigCompiler extends Stage<ConfigCompilerInput, CompiledConfig> {
-    private readonly container;
-    constructor(container: CommonContainer);
     protected dependencies(input: ConfigCompilerInput): readonly unknown[];
     protected run(input: ConfigCompilerInput): CompiledConfig;
 }
@@ -2072,9 +1728,9 @@ declare interface ConfigItem {
  */
 export declare interface ConfigSpec {
     /**
-     * Locale used to interpret source values and, by default, to format display
+     * 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 to
+     * `format*` helper to override display only — it resolves
      * `formattingLocale ?? parsingLocale`. The `duration` format is always
      * English regardless of locale.
      */
@@ -2247,7 +1903,7 @@ declare type ContinuousScaleSpec = Required<ContinuousScaleInput>;
  */
 export declare function convertSpecToInput(spec: Spec): SpecInput;
 
-/** Builders for the graph's coordinate system. Pass the result as the spec's `coord` to choose cartesian, flipped, or polar. */
+/** 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.
@@ -2342,15 +1998,14 @@ declare interface CoordStrategy {
  * Render-ready coordinate system (discriminated union).
  * Discriminates on geometric paradigm: cartesian plane vs polar projection.
  *
- * The same geom renders differently per coord: a bar is a rect in cartesian and an arc in polar.
+ * 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, resolved coord system, and position-mapped layers. */
+/** What a {@link CoordStrategy} receives during the transform pass — the coord spec and position-mapped layers. */
 declare interface CoordTransformInput {
     coordSpec: CoordSpec;
-    /** The coord system resolved by {@link CoordStrategy.setup}, so the transform reuses its resolved angles (e.g. polar `startAngle`/`spokeRotation`) rather than re-deriving them. */
-    coordSystem: CoordSystem;
     layers: CompiledLayer[];
 }
 
@@ -2361,7 +2016,7 @@ declare interface CoordTransformInput {
  * - `'polar'` — Polar coordinates for pie, radar, and radial charts
  * - `'flip'` — Cartesian with x and y axes swapped
  */
-export declare type CoordType = 'cartesian' | 'polar' | 'flip';
+declare type CoordType = 'cartesian' | 'polar' | 'flip';
 
 declare function count(): CountStatSpec;
 
@@ -2392,7 +2047,7 @@ export declare const createColorValueReader: (data: Dataset, mapping: AesMapping
 
 /**
  * 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.
+ * 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 →
@@ -2400,52 +2055,13 @@ export declare const createColorValueReader: (data: Dataset, mapping: AesMapping
  * 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.
  */
-export declare const createCompiler: ({ plugins }?: CreateCompilerOptions) => Compiler;
-
-/** Options for {@link createCompiler}. */
-export declare interface CreateCompilerOptions {
-    /**
-     * Custom geoms, stats, and transforms to register alongside the built-ins. A render half
-     * (react-renderer's `GeomRendererDefinition`) is accepted too — its compile definition is read
-     * structurally from `.definition`, so the engine never imports a React type. A by-name render-only
-     * override carries no compile definition and is skipped here, leaving the built-in compile half
-     * intact. Built-ins seed first, then these in array order (last-in-array wins).
-     */
-    plugins?: readonly Plugin_2[];
-}
-
-/**
- * Builds the recurring layout-geom dataset shape — several observation kinds (node+flow, group+leaf,
- * node+edge) in one columnar dataset, discriminated by a `kind` column — from per-kind observation groups.
- * Owns the null-padding-by-construction invariant a hand-built version is easy to get wrong: every column
- * any group declares exists on every observation, null where a kind doesn't carry it.
- *
- * Column order is the kind column first, then columns in first-seen order. Each column's `DataType`
- * is inferred from its first non-null value (numeric/temporal/categorical), defaulting to categorical
- * for an all-null column.
- */
-export declare function createDatasetFromKindPartitions(groups: readonly KindPartition[], kindColumn?: VariableName): Dataset;
+export declare const createCompiler: () => Compiler;
 
 /**
- * Fresh empty highlight state for a layer of the given geom, or `null` when the geom opts out of
- * highlighting. A custom geom (a name outside the built-in strategy table) opts out for now — the
- * built-in highlight strategies don't yet read the declared `Geom.highlightStrategy`.
+ * 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`).
  */
-export declare function createEmptyHighlight(geom: string): CompiledLayerHighlight | null;
-
-/**
- * Build the authoring surface from a `plugins` array — the headless/advanced primitive that
- * `createGraphyKit` (react-renderer) wraps. Pass the same array to `createCompiler` so the writable
- * surface and the compilable surface cannot diverge. The `const` type parameter captures the tuple
- * literally, so each def's `type`/`aes`/`params` flow into its generated builder method.
- */
-export declare function createGraphyBuilder<const P extends readonly Plugin_2[] = []>(options?: CreateGraphyBuilderOptions<P>): GraphyBuilder<P>;
-
-/** Options for {@link createGraphyBuilder}. */
-export declare interface CreateGraphyBuilderOptions<P extends readonly Plugin_2[] = readonly Plugin_2[]> {
-    /** Custom geoms/stats/transforms (and render halves, read via `.definition`) the authored spec may use. */
-    plugins?: P;
-}
+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;
@@ -2461,8 +2077,6 @@ export declare const createHeadlineItemRows: (item: FormattedHeadlineItem) => He
 /** Reader for the raw value behind a layer's `label` mapping. */
 export declare const createLabelValueReader: (data: Dataset, mapping: AesMapping) => RawValueReader;
 
-export declare const createLineFillAreaGenerator: (params: LineGeomParams) => Area<Observation>;
-
 export declare const createLinePathGenerator: (params: LineGeomParams) => Line<Observation>;
 
 /**
@@ -2478,7 +2092,7 @@ export declare const createRawValueReader: (data: Dataset, aestheticValue: Aesth
 /**
  * Per-observation reader for the segment-y value of a compiled layer, in original data units.
  *
- * When the layer is stacked, the y position variables already hold cumulative band bounds (draw
+ * 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.
@@ -2489,31 +2103,20 @@ export declare function createSegmentYReader(layer: CompiledLayer): (observation
 export declare const createSizeValueReader: (data: Dataset, mapping: AesMapping) => RawValueReader;
 
 /**
- * Seed a spec — the entry point for every chart. The first argument may be a bare {@link AesMapping}
- * (`{ x, y, color, ... }`), which becomes the spec's global aesthetic mapping; any further arguments are
- * pipeable spec items (geoms, scales, coords, transforms, config, ...) folded on in order.
- *
- * This is the builder pattern: `createSpec` seeds the mapping, then `pipe` (or extra args here) folds each
- * item onto an immutable spec, accumulating layers/scales/etc. Always declare `scale.x()` / `scale.y()` for
- * any position mapping — they are NOT auto-inferred and yield NaN positions if omitted.
- *
- * @example
- * import { createSpec, pipe, geom, scale } from '@graphysdk/viz-engine';
- *
- * // Most common: mapping first, then pipe the rest.
- * const spec = pipe(createSpec({ x: 'category', y: 'revenue' }), geom.bar(), scale.x(), scale.y());
+ * Create a new spec, optionally piping spec items in one call. Data is passed separately
+ * to {@link compile}.
  *
  * @example
- * import { createSpec, transform, mapping, geom, scale } from '@graphysdk/viz-engine';
+ * When the first arg is a mapping:
+ *   createSpec({ x: 'date', y: 'value' })
  *
- * // All-in-one form, clearer when a transform must run before the mapping is read.
- * const spec = createSpec(
- *   transform.reshape({ reshape: ['revenue'], keyName: 'metric', valueName: 'amount' }),
- *   mapping({ x: 'month', y: 'amount', color: 'metric' }),
- *   geom.bar(),
- *   scale.x(),
- *   scale.y(),
- * );
+ * When piping spec items (more readable when chaining transforms):
+ *   createSpec(
+ *     transform.reshape({ reshape: ['revenue'], keyName: 'metric', valueName: 'amount' }),
+ *     mapping({ x: 'month', y: 'amount', color: 'metric' }),
+ *     geom.bar(),
+ *     scale.x(),
+ *   )
  */
 export declare function createSpec(...items: Array<AesMapping | SpecItem>): SpecInput;
 
@@ -2527,6 +2130,10 @@ export declare const createStrokeWidthValueReader: (data: Dataset, mapping: AesM
  * 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.
  */
 export declare const createValueFormatter: (params: ValueFormatterFactoryParams) => ValueFormatter;
 
@@ -2544,45 +2151,6 @@ declare interface CurrencyValueFormat {
     iso: CurrencyIso;
 }
 
-/**
- * Scales a plot-local cursor `(x, y)` in data-space `[0, 1]²` into the pie-local unit disk (centre
- * `(0, 0)`, outer radius `1`), undoing the aspect ratio so the disk is inscribed in the shorter panel
- * dimension and centred. In the returned frame `y` is up, so a vertex at `(angle, radius)` sits at
- * {@link polarToUnit}`(angle, radius)`. Every polar query shares this one correction.
- */
-export declare const cursorToPiePlane: (cursor: HoverCursor, aspectRatio: number) => XYPoint;
-
-/** Converts a plot-local cursor into polar `(angle, radius)` in the inscribed-disk frame. */
-export declare const cursorToPolar: (cursor: HoverCursor, aspectRatio: number) => {
-    angle: number;
-    radius: number;
-};
-
-/**
- * A builder method per custom geom def, keyed on its `type`. `& string` keeps the remap key legal; if
- * the def's `type` widened to `string` (no `as const`), the method lands under an index signature
- * instead of a named key — still usable, just unkeyed (C3).
- */
-declare type CustomGeomBuilders<P extends readonly Plugin_2[]> = {
-    [Def in GeomDefsOf<P> as Def['type'] & string]: (options?: GeomBuilderOptions<Def>) => CustomGeomLayerInput;
-};
-
-/**
- * A layer for a custom (plugin-contributed) geom. Its `geom` is a name outside {@link GeomName},
- * resolved downstream through the geom registry; `params` are validated at the typed builder call
- * site, so the node itself carries them as an open record.
- */
-export declare interface CustomGeomLayerInput extends LayerInputBase {
-    geom: string;
-    params?: Record<string, unknown>;
-}
-
-/** A resolved layer spec for a custom geom — the {@link CustomGeomLayerInput} counterpart. */
-export declare interface CustomGeomLayerSpec extends LayerSpecBase {
-    geom: string;
-    params: Record<string, unknown>;
-}
-
 /** A single named color slot within a custom palette supplied by the renderer. */
 export declare type CustomPaletteColor = {
     id: string;
@@ -2605,33 +2173,6 @@ declare type CustomPaletteInput = {
 /** Renderer-owned custom palettes, keyed by `paletteId`, that a GraphConfig may reference by id. */
 export declare type CustomPalettesInput = Record<string, CustomPaletteColor[]>;
 
-declare type CustomStatBuilders<P extends readonly Plugin_2[]> = {
-    [Def in StatDefsOf<P> as Def['type'] & string]: () => CustomStatInput<Def['type'] & string>;
-};
-
-/**
- * The input node a custom (plugin-contributed) stat builder produces.
- */
-export declare interface CustomStatInput<Name extends string = string> {
-    type: Name;
-}
-
-declare type CustomTransformBuilders<P extends readonly Plugin_2[]> = {
-    [Def in TransformDefsOf<P> as Def['transformType'] & string]: (options?: TransformBuilderOptions) => CustomTransformInput<Def['transformType'] & string>;
-};
-
-/***************************************************************
- * Transform Input
- ***************************************************************/
-/**
- * The input node a custom (plugin-contributed) transform builder produces.
- */
-export declare interface CustomTransformInput<Name extends string = string> {
-    type: 'transform';
-    transformType: Name;
-    options?: Record<string, unknown>;
-}
-
 /**
  * Data to visualize. Structured as a table.
  *
@@ -2658,14 +2199,6 @@ export declare interface Data {
     /* Excluded from this release type: _metadata */
 }
 
-/**
- * Padding folded into `measureDataLabel`'s `(width, height)` so the engine sees the rendered
- * box dimensions, not raw text metrics. Stack totals carry a tighter pill than per-observation labels.
- */
-export declare const DATA_LABEL_PADDING_X_PX = 6;
-
-export declare const DATA_LABEL_PADDING_Y_PX = 2;
-
 /**
  * Parses raw `Data` into a typed {@link Dataset}. Swapping the `Data` reference triggers
  * a re-parse; repeated compiles against the same reference short-circuit. The orchestrator decides
@@ -2676,25 +2209,6 @@ declare class DataCompiler extends Stage<Data, Dataset> {
     protected run(input: Data): Dataset;
 }
 
-/**
- * Anchor along one axis of the geom's box, CSS-flexbox style. `justify` runs along the value
- * axis — `'end'` is the value tip whatever the orientation or sign (e.g. the bottom of a negative
- * column). `align` runs across it: bandwidth for bars, angular for pie wedges, x for
- * point/line/area.
- */
-export declare type DataLabelAnchor = 'start' | 'center' | 'end';
-
-export declare interface DataLabelDimensions {
-    /** Font size in pixels. Box height = text height + `2·paddingY`. */
-    fontSize: number;
-    /** Font weight for the label text (CSS numeric weight). */
-    fontWeight: number;
-    /** Horizontal label padding (each of left + right). */
-    paddingX: number;
-    /** Vertical label padding (each of top + bottom). */
-    paddingY: number;
-}
-
 /**
  * Discriminator for which on-canvas typography a strategy is measuring against. The renderer
  * owns the actual `FontSpec` for each kind — the engine only names the kind so the renderer's
@@ -2702,23 +2216,6 @@ export declare interface DataLabelDimensions {
  */
 export declare type DataLabelKind = 'dataLabel' | 'stackTotal';
 
-/**
- * Where data labels sit relative to the geom they decorate.
- * - `'auto'` — the engine chooses: fit inside, flip outside, drop or rotate as needed.
- *   `justify`/`align` are ignored.
- * - `'inside'` — within the geom's box, hugging the `(justify, align)` anchor. Never dropped,
- *   flipped or rotated. On line/point geoms the label centres on the data point/marker.
- * - `'outside'` — just past the value-axis edge selected by `justify`; `align` stays within the
- *   geom's width (line/point labels sit beside the geom). Never dropped. Stacked/filled cartesian
- *   bar segments coerce to `'inside'` — every segment edge borders a neighbour; use
- *   `showStackTotals` for stack-end totals. (Pie wedges keep `'outside'`.)
- *
- * Styling follows the label's effective position: over the geom → inside styling (white text,
- * no plate); off it — by placement, offset, or not fitting — outside styling (dark text on a
- * plate). Area labels always use the plated styling: the translucent fill can't back white text.
- */
-export declare type DataLabelPlacement = 'auto' | 'inside' | 'outside';
-
 /**
  * Where a label sits relative to the geom or stack it decorates. Independent of `target`.
  * - `inside` — over the geom; renderer paints white text without a plate.
@@ -2730,7 +2227,7 @@ 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 graphs. */
+    /** Shows the summed total above each stack in stacked charts. */
     showStackTotals?: boolean;
     showCategoryLabels?: boolean;
 }
@@ -2764,27 +2261,6 @@ export declare interface DataLabelsConfig {
      * @default { variable: POSITION_VARIABLES.yRaw }
      */
     labelSource: AestheticValue;
-    /**
-     * Where labels sit relative to the geom. Explicit values render exactly as asked; dropping,
-     * flipping and rotation happen only under `'auto'`.
-     * @default 'auto'
-     */
-    position: DataLabelPlacement;
-    /**
-     * Anchor along the geom's value/growth axis. Only consulted when `position` is explicit.
-     * @default 'end' ('center' for stacked/filled bars)
-     */
-    justify: DataLabelAnchor;
-    /**
-     * Anchor across the geom's secondary axis. Only consulted when `position` is explicit.
-     * @default 'center'
-     */
-    align: DataLabelAnchor;
-    /**
-     * Gap in pixels between the geom's edge and the label box. Stack totals ignore it.
-     * @default 4 for bars and polar wedges, 12 for point/line/area
-     */
-    offset: number;
 }
 
 /**
@@ -2811,7 +2287,7 @@ 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
+ * 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.
  */
@@ -2871,14 +2347,6 @@ export declare class Dataset {
      * Adds a new constant variable to the dataset. Format resolution follows {@link addVariable}.
      */
     addConstantVariable(variable: VariableName, type: DataType, value: DataValue, valueFormat?: ValueFormat): Dataset;
-    /**
-     * Returns the source literal a variable was materialised from via {@link addConstantVariable},
-     * or undefined if it isn't a recorded constant. The returned wrapper distinguishes a constant
-     * whose value is `null` (wrapper present) from a non-constant variable (undefined).
-     */
-    getConstant(variable: VariableName): {
-        value: DataValue;
-    } | undefined;
     /**
      * Derives a new variable based on existing variables, using a table expression. If `valueFormat`
      * is omitted, a type-based default is used.
@@ -3096,24 +2564,14 @@ declare interface DatetimeTickInterval {
 
 declare type DatetimeTickIntervalUnit = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
 
-/**
- * The aes keys a geom's declared `aesthetics` contributes — its visual + data channel names, only when
- * declared `as const`. The widened base type (`readonly GeomAesthetic[]`) contributes nothing, so a
- * position-only geom isn't silently opened to every aesthetic.
- */
-declare type DeclaredAesKeys<Def extends Geom<unknown>> = IsWidenedTuple<Def['aesthetics']> extends true ? never : Def['aesthetics'][number]['name'];
-
 /**
  * Recursively makes every property of `T` optional.
  * Unlike the built-in `Partial`, this applies to nested objects as well.
  */
 declare type DeepPartial<T> = {
-    [K in keyof T]?: T[K] extends Array<infer U> ? Array<DeepPartial<U>> : unknown extends T[K] ? T[K] : NonNullable<T[K]> extends object ? DeepPartial<NonNullable<T[K]>> : T[K];
+    [K in keyof T]?: T[K] extends Array<infer U> ? Array<DeepPartial<U>> : NonNullable<T[K]> extends object ? DeepPartial<NonNullable<T[K]>> : T[K];
 };
 
-/** Series colors used when a chart specifies no palette. Cycled in order as series count grows. */
-export declare const DEFAULT_COLOR_PALETTE: string[];
-
 /**
  * Default font style.
  */
@@ -3135,93 +2593,6 @@ declare type DefaultPaletteConfig = {
     type: 'default';
 };
 
-/**
- * Recover the compile definition from a plugin. A render half (react-renderer's
- * `GeomRendererDefinition`) carries its compile definition at `.definition`; a bare definition is its
- * own. The engine reads this structurally so it never imports a React type.
- */
-export declare type DefinitionOf<T> = T extends {
-    definition: infer D;
-} ? D : T;
-
-/**
- * Every compile definition contributed by the `plugins` tuple. A render half carries its definition
- * at `.definition` (recovered by {@link DefinitionOf}); a render-only override carries none and is
- * dropped here, because `Extract<…, CompileDefinition>` excludes its `{ geom; render }` shape — so it
- * contributes no builder method.
- */
-declare type DefsOf<P extends readonly Plugin_2[]> = Extract<DefinitionOf<P[number]>, CompileDefinition>;
-
-/**
- * Conventional `context` keys. A diagnostic's `context` is free-form `Record<string, JsonValue>`,
- * but emitters draw from this vocabulary so consumers can rely on consistent keys per code rather
- * than parsing prose:
- *
- * - `layerIndex` — index of the offending layer
- * - `aesthetic` — the aesthetic channel (`x`, `y`, `color`, …)
- * - `variableName` — the offending data variable
- * - `scaleType` — the scale type involved
- * - `variableType` — the data type of the offending variable
- * - `expected` / `actual` — the required vs. supplied value
- * - `requested` / `available` — an unknown/duplicate registered type and the registered alternatives
- * - `kind` — the registry or resolver label for a registration diagnostic (`UNKNOWN_REGISTERED_TYPE`,
- *   `DUPLICATE_REGISTERED_TYPE`, `MISSING_GEOM_RENDERER`)
- */
-declare const DIAGNOSTIC_CONTEXT_KEYS: readonly ["layerIndex", "aesthetic", "variableName", "scaleType", "variableType", "expected", "actual", "requested", "available", "kind"];
-
-/**
- * Structured location + repair atoms carried by an error or diagnostic. Keys are constrained to the
- * {@link DIAGNOSTIC_CONTEXT_KEYS} vocabulary, so the contract codegen binds to is compiler-checked
- * at every emit site — a typo or an ad-hoc key is a type error here, not a silent drift that breaks
- * a downstream consumer. Values are {@link JsonValue} so a diagnostic stays serialisable end-to-end.
- */
-export declare type DiagnosticContext = Partial<Record<DiagnosticContextKey, JsonValue>>;
-
-/** A key from the documented {@link DIAGNOSTIC_CONTEXT_KEYS} vocabulary. */
-export declare type DiagnosticContextKey = (typeof DIAGNOSTIC_CONTEXT_KEYS)[number];
-
-/**
- * The human- and machine-readable core every error and diagnostic shares: a `message`, optional
- * structured `context` atoms, and an optional repair `suggestion`. The `severity`/`kind`/`code` axes
- * are layered on by {@link VizDiagnostic}, and `cause` by {@link VizErrorOptions} — so the producer
- * surface has one core shape rather than three overlapping ones.
- */
-export declare interface DiagnosticDetails {
-    /** Human-readable description of what went wrong. */
-    message: string;
-    /** Serialisable location + repair atoms, drawn from the documented key vocabulary. */
-    context?: DiagnosticContext;
-    /** Repair hint for a human or an LLM. Advisory prose, not part of the stable contract. */
-    suggestion?: string;
-}
-
-/**
- * Chart-scoped sink for diagnostics produced during one compile.
- *
- * Holds warnings *and* the validator's batched errors; `drain` splits them by severity.
- */
-declare class DiagnosticsCollector {
-    private diagnostics;
-    private persistent;
-    /**
-     * Record an advisory user-input diagnostic — a fixable problem that degraded gracefully.
-     *
-     * A `persistent` warning survives {@link reset} and resurfaces in every {@link drain} — a
-     * chart-level condition true for the collector's whole life (e.g. a plugin registration collision),
-     * so it is surfaced on every compile without being re-emitted. A normal warning is cleared each
-     * compile.
-     */
-    addWarning(issue: UserInputIssue, options?: {
-        persistent?: boolean;
-    }): void;
-    /** Record a fatal user-input diagnostic — used by validators that collect every problem before throwing. */
-    addError(issue: UserInputIssue): void;
-    /** Clear the per-compile diagnostics. Called at the start of each compile; persistent ones survive. */
-    reset(): void;
-    /** Return the accumulated diagnostics (persistent + this compile's) split by severity, deduped. */
-    drain(): DrainedDiagnostics;
-}
-
 declare interface DifferenceArrowDimensions {
     /** Gap between the arrow start point and its anchored observation. */
     arrowStartGap: number;
@@ -3263,7 +2634,7 @@ export declare interface DifferenceArrowInput {
     /** null falls back to a theme default. */
     color?: string | null;
     size?: DifferenceArrowSize;
-    /** AnchorOffset of the label along the arrow, as a fraction of the arrow's length. */
+    /** Offset of the label across the arrow, as a fraction of the arrow's length. */
     labelCrossPosition?: number;
 }
 
@@ -3344,21 +2715,12 @@ declare type DiscreteScaleOptions<RangeValue extends number | string = number |
 
 declare type DiscreteScaleSpec = Required<DiscreteScaleInput>;
 
-/** Diagnostics split by severity, as returned by {@link DiagnosticsCollector.drain}. */
-declare interface DrainedDiagnostics {
-    errors: VizDiagnostic[];
-    warnings: VizDiagnostic[];
-}
-
-/** Measured sizes (in pixels) for each edge of the layout. */
-export declare type EdgeSizes = Record<LayoutEdge, number>;
-
 /** 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;
 
 /**
  * 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
+ * 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.
  */
@@ -3368,20 +2730,13 @@ export declare interface ExternalMeasurements {
 }
 
 /**
- * Extracts the constant value from a `{ value }` mapping. Returns undefined for variable mappings.
+ * 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.
  */
-export declare function extractConstantValue(aestheticValue: AestheticValue | undefined): DataValue | undefined;
-
-/** Flattens a title, subtitle, or caption to plain text for measurement and static renderers. */
 export declare const extractPlainText: (content: TextContent) => string;
 
-/**
- * Extracts the variable name from an AestheticValue.
- * Returns the variable name for string shorthands and { variable } mappings.
- * Returns null for constant { value } mappings or undefined values.
- */
-export declare function extractVariableName(aestheticValue: AestheticValue | undefined): VariableName | null;
-
 declare function filter(options: FilterOptions): FilterTransformInput;
 
 /***************************************************************
@@ -3415,12 +2770,6 @@ declare interface FilterTransformInput {
  */
 export declare function findAxisGuide(guides: CompiledGuides, scaleAestheticKey: ScaledAestheticKey): CompiledAxisGuide | null;
 
-/** Returns the first region whose rect contains the panel-local point, or null. */
-export declare const findCalloutHit: (point: {
-    x: number;
-    y: number;
-}, regions: readonly CalloutHitRegion[]) => CalloutHitRegion | null;
-
 /**
  * Returns the legend that covers the given visual aesthetic, or null if no legend is configured
  * for it. Legends may be merged across aesthetics (one legend covering color + size on a point
@@ -3475,7 +2824,8 @@ export declare interface FormatHeadlineInput {
     numberFormat: NumberFormatConfig;
     parsingLocale: Locale;
     /**
-     * Display-locale override: `locale = formattingLocale ?? parsingLocale`.
+     * 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;
@@ -3493,7 +2843,8 @@ declare interface FormatLegendsInput {
     numberFormat: NumberFormatConfig;
     parsingLocale: Locale;
     /**
-     * Display-locale override: `locale = formattingLocale ?? parsingLocale`.
+     * 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;
 }
@@ -3501,7 +2852,8 @@ declare interface FormatLegendsInput {
 /**
  * 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.
+ * 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).
  */
 export declare const formatRuleValue: ({ guides, numberFormat, layer, locale }: FormatRuleValueInput) => string | null;
 
@@ -3533,8 +2885,8 @@ export declare interface FormattedAxis extends Omit<CompiledAxisGuide, 'tickCand
 }
 
 /**
- * A headline showing a single grand-total number, used for polar graphs. `value` is a bare final
- * display string: no prefix, label or swatch accompanies it. Render it verbatim.
+ * 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';
@@ -3577,18 +2929,52 @@ export declare interface FormattedHeadlineItem {
 
 /** A legend guide with each item's label composed into a display string. */
 export declare interface FormattedLegend extends Omit<CompiledLegendGuide, 'items'> {
-    /** Legend items, each carrying its composed display string in `formattedLabel`. */
+    /** 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 group). */
+/** A headline showing one labelled figure per group (e.g. one per series). */
 export declare interface FormattedPerGroupHeadline {
     kind: 'perGroup';
     items: FormattedHeadlineItem[];
 }
 
+/**
+ * Freeform arrow annotation. Endpoints sit in plot-fractional coordinates
+ * (0..1), so they re-flow with panel size. Distinct from
+ * {@link DifferenceArrowInput}, which anchors to dataset observations.
+ */
+export declare interface FreeformArrowInput {
+    id?: string;
+    /** Tail endpoint. */
+    start: ArrowEndpoint;
+    /** Head endpoint. */
+    end: ArrowEndpoint;
+    /** null falls back to the theme `defaultAnnotationArrowStroke`. */
+    color?: string | null;
+    thickness?: ArrowThickness;
+    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;
+    end: ArrowEndpoint;
+    color: string | null;
+    thickness: ArrowThickness;
+    startArrowheadStyle: ArrowheadStyle;
+    endArrowheadStyle: ArrowheadStyle;
+    lineStyle: ArrowLineStyle;
+    hasStickerStyle: boolean;
+}
+
 /**
  * Options for `generateTicks`:
  * - `{ count }` — approximate tick count (continuous, datetime).
@@ -3607,99 +2993,14 @@ declare type GenerateTicksOptions = {
 
 /**
  * Base class for geoms that turn observations into visual marks (points, bars, lines etc).
- *
- * A geom declares its capabilities as fields and hooks with sensible base-class defaults; a subclass
- * overrides only what differs. The compile and runtime pipeline reads these declarations to decide
- * behaviour rather than branching on `type`, so a custom geom is a first-class participant.
- *
- * What earns a place on the def: a field belongs here only if it answers a question a name-agnostic
- * pipeline stage must ask of *every* geom (e.g. "which coord systems do you support?", "what spatial
- * index do you paint into?"). A single geom's one-off behaviour is an optional hook that geom alone
- * implements — never a shared flag the base class asserts for all geoms. Fields are grouped below by
- * the concern that consumes them.
- */
-export declare abstract class Geom<TParams = Record<string, never>> {
-    /** Position columns the compile half injects and the render half reads — the cross-half contract. */
-    readonly positionRoles: PositionRoles;
-    /** What makes "the same observation" across recompiles. */
-    readonly identityKey: IdentityKey;
-    /** How overlapping marks of this geom arrange when the layer omits a position (bar → dodge, area → stack). */
-    readonly defaultPosition: PositionType;
-    /** Whether layers of this geom take part in hover hit-testing by default (rule opts out). */
-    readonly defaultInteractive: boolean;
-    /**
-     * The aesthetics this geom honours, each tagged by {@link GeomAesthetic} `kind`: a `'visual'` scaled
-     * channel (`color`, `size`) or a `'data'` relational/layout input read straight from its mapped column
-     * without a scale (a sankey's `source`/`target`/`value`). Declaring a name registers it so the mapping
-     * is recognised and, when `required`, enforces its presence.
-     */
-    readonly aesthetics: GeomAesthetics;
-    /**
-     * Variable names this geom computes in its own output that an author may map an aesthetic to.
-     * They don't exist in the input data, so they're exempt from the unknown-variable check.
-     */
-    readonly derivedVariables: readonly string[];
-    /** How this geom composes highlight matches above its base render; `null` opts out of highlighting. */
-    readonly highlightStrategy: HighlightStrategy | null;
-    /** Scale-domain constraints this geom imposes (discrete band axis, zero-anchored y); unset = none. */
-    readonly scaleConstraints?: ScaleConstraints;
-    /** Coordinate systems this geom can be rendered under. */
-    readonly supportedCoordTypes: readonly CoordType[];
-    /**
-     * The hit-test shape this geom declares, coord-agnostic (see {@link SpatialKind}). Baked onto the
-     * compiled layer verbatim; the runtime hover indexer (`build-layer-index`) projects it for the chart's
-     * coord.
-     */
-    readonly spatialKind: SpatialKind;
-    /** Per-coord grid/border visibility this geom requests from the axes guide. */
-    readonly grid: Partial<Record<CoordType, GridPolicy>>;
-    /** How this geom relates to the colour legend (single-item suppression, auto-placement, direct labels). */
-    readonly legend: LegendPolicy;
-    /** Per-coord data-label defaults merged over the base config (e.g. bar+polar → percentage). */
-    readonly dataLabels?: Partial<Record<CoordType, Partial<DataLabelsConfig>>>;
-    /** Coord types the built-in placement pipeline can place this geom's data labels under. */
-    readonly dataLabelCoordTypes: readonly CoordType[];
-    /** The tooltip contract this geom declares. */
-    readonly tooltip: TooltipContract;
-    /** Per-layer aggregate summaries this geom opts into (grand total, stack totals, per-group headline). */
-    readonly summaries: GeomSummaries;
-    /** Optional bespoke mapping requirement not expressible as a position role's `aes` source. */
-    validateMapping?: (input: GeomMappingValidationInput) => readonly UserInputIssue[];
-    /**
-     * Optional: resolve a per-observation annotation anchor in normalised panel `[0, 1]` space. A geom
-     * that supports anchoring (bar, line) implements this; the annotation stage skips geoms that don't.
-     */
-    resolveAnchorPosition?: (observation: Observation, coordSystem: CoordSystem) => AnchorPosition | null;
-    /**
-     * Optional: the geom's bespoke default data-label source when none is mapped (point → the bound
-     * `size` variable). Returns `null` to defer to the shared segment-y default.
-     */
-    resolveDefaultLabelSource?: (mapping: AesMapping) => AestheticValue | null;
-    /**
-     * Optional: data-label defaults that depend on the layer's position adjuster (e.g. bar defaults `justify` to
-     * `'center'` on stacked/filled segments). Applied over the base defaults; both the per-coord defaults and
-     * the user's config override it.
-     */
-    resolveDataLabelDefaults?: (position: PositionType) => Partial<DataLabelsConfig>;
-    /**
-     * The geom's name. The built-in subclasses narrow this to a `GeomName` literal; the base accepts
-     * any `string` so a custom geom carries a name outside the built-in union (runtime identity is a
-     * plain string, resolved through the registry).
-     */
-    abstract readonly type: string;
-    /** Default values for this geom's params; also carries the params type (`TParams`). */
-    abstract readonly defaultParams: TParams;
-    /**
-     * Resolve this geom's params from the (optional) user-supplied params, merged over
-     * {@link defaultParams}. Read by the layer resolver. Override to apply a geom-specific invariant the
-     * merge can't express — area normalises `missingValues: 'gap'` to `'zero'`, which it can't render
-     * mid-stack. Params are validated at the typed builder call site, so this works on an open record.
-     */
-    resolveParams(params: Record<string, unknown> | undefined): Record<string, unknown>;
+ */
+declare abstract class Geom {
+    readonly requiredAesthetics: AestheticKey[];
+    abstract readonly type: GeomName;
     abstract compile(input: GeomCompilerInput): CompiledGeom;
 }
 
-/** Factories for the geom layers a graph can draw (point, line, area, bar, rule). */
+/** Factories for the geometry layers a chart can draw (point, line, area, bar, rule). */
 export declare const geom: {
     point: typeof point;
     line: typeof line;
@@ -3709,82 +3010,34 @@ export declare const geom: {
 };
 
 /**
- * An aesthetic a geom reads from its layer's mapping, tagged by how the engine treats it:
- *
- * - `'visual'` — a scaled visual channel (`color`, `size`), trained through a scale. Constrained to the
- *   built-in {@link AestheticKey} vocabulary.
- * - `'data'` — a relational/layout input read straight from the mapped column without any scale (a
- *   sankey's `source`/`target`/`value`). Free-form name, outside the built-in vocabulary.
- *
- * Declaring an aesthetic registers its name so the mapping is recognised (no `UNDECLARED_AESTHETIC`
- * warning) and, when `required`, enforced by the missing-aesthetic check.
- */
-export declare type GeomAesthetic = {
-    readonly kind: 'visual';
-    readonly name: AestheticKey;
-    readonly required?: boolean;
-} | {
-    readonly kind: 'data';
-    readonly name: string;
-    readonly required?: boolean;
-};
-
-/** A geom's declared aesthetics. */
-export declare type GeomAesthetics = readonly GeomAesthetic[];
-
-/**
- * Options for a custom geom builder method. Mirrors the built-in geom option envelope, but with
- * `params` typed from the def's `defaultParams` and `aes` constrained to the def's declared
- * aesthetics ({@link AesFromDef}).
- */
-declare interface GeomBuilderOptions<Def extends Geom<unknown>> {
-    aes?: AesFromDef<Def>;
-    stat?: StatName | StatInput | CustomStatInput<string>;
-    position?: PositionType;
-    yScaleType?: YScaleType;
-    params?: Partial<Def['defaultParams']>;
-    transforms?: TransformInput[];
-    interactive?: boolean;
-    dataLabels?: DataLabelsInput;
-}
-
-/**
- * Resolves a geom by name, delegates compilation, then fills any `aes`-sourced interval roles the
- * geom declares (e.g. a bar's `yMax` from its `y` aesthetic) so the geom compile half doesn't.
+ * Resolves a geom by name and delegates compilation.
  */
 declare class GeomCompiler {
-    private readonly container;
-    constructor(container: CommonContainer);
-    compile(geomName: string, input: GeomCompilerInput): CompiledGeom;
+    private readonly registry;
+    constructor(registry: GeomRegistry);
+    compile(geomName: GeomName, input: GeomCompilerInput): CompiledGeom;
 }
 
-export declare interface GeomCompilerInput {
+declare interface GeomCompilerInput {
     /** The dataset after stat transformation */
     data: Dataset;
-    /** The effective mapping for the layer (may carry the geom's custom positional aesthetics). */
+    /** The effective mapping for the layer */
     mapping: AesMapping;
     /** Geom-specific params */
     params: LayerSpec['params'];
 }
 
-declare type GeomDefsOf<P extends readonly Plugin_2[]> = Extract<DefsOf<P>, Geom<unknown>>;
-
-/** Context a geom's `validateMapping` hook receives to assert a bespoke mapping requirement. */
-export declare interface GeomMappingValidationInput {
-    /** The layer's effective mapping (root + layer merged). */
-    mapping: AesMapping;
-    /** Aesthetics the layer's stat computes at compile time, which count as "provided". */
-    computedVariables: ReadonlySet<AestheticKey>;
-}
-
 /**
  * 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 (cartesian) or pie wedge (polar)
+ * - `'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.
  */
 export declare type GeomName = 'point' | 'line' | 'area' | 'bar' | 'rule';
 
@@ -3804,37 +3057,22 @@ declare interface GeomParamsMap {
 }
 
 /**
- * Geom implementations keyed by name. Built-ins are registered in the constructor; custom geoms are
- * appended via `createRegistries`, so the key is a plain `string` rather than the built-in `GeomName`.
+ * Built-in geom implementations keyed by {@link GeomName}.
  */
-declare class GeomRegistry extends Registry<string, Geom<unknown>> {
+declare class GeomRegistry extends Registry<GeomName, Geom> {
     constructor();
 }
 
-/**
- * Per-layer aggregate summaries a geom opts into. Read by the summarise stage (which gates the
- * grand-total / stack-total summarisers) and the headline guide (per-group eligibility), so the
- * behaviour follows what a geom declares rather than its name.
- */
-export declare interface GeomSummaries {
-    /** Emit a layer-wide grand total over `y` (the figure a polar headline shows). */
-    grandTotal?: boolean;
-    /** Emit per-x stack totals for a stacked layer. */
-    stackTotals?: boolean;
-    /** Eligible to carry a per-group headline strip. */
-    perGroupHeadline?: boolean;
-}
-
 /**
  * Reads the resolved alpha (opacity) value from an observation, in `[0, 1]`.
  *
- * `null` / `undefined` ⇒ unmapped — apply the geom default. A group (line / area) shares one
+ * `null` / `undefined` ⇒ unmapped — apply the geom default. A series (line / area) shares one
  * resolved value across its rows; read it from the first observation.
  */
 export declare function getAlpha(observation: Observation): NumericDataValue;
 
 /**
- * Reads a polar arc's angular sweep. In polar layers the x position variables are repurposed as
+ * 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.
@@ -3855,8 +3093,8 @@ export declare const getBarRectBounds: (mainAxis: MainAxis, observation: Observa
 /**
  * Reads the resolved color string from an observation.
  *
- * `undefined` ⇒ unmapped — the renderer supplies its geom default fill. A group (line / area)
- * shares one resolved value across its observations; read it from the first 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.
  */
 export declare function getColor(observation: Observation): string | undefined;
 
@@ -3867,15 +3105,6 @@ export declare const getCurve: (interpolate: InterpolateType) => CurveFactory;
 
 export declare const getDashArray: (lineType: LineStyleType) => string | undefined;
 
-/**
- * Returns pixel dimensions for a data label of the given kind. The renderer owns the
- * font family; everything that must agree between renderers (size, weight, padding) lives here.
- *
- * `textScale` lets callers track the graph-wide text scale so labels size to the rest of the
- * graph. Pass `1` to keep the base pixel sizes.
- */
-export declare const getDataLabelDimensions: (kind: DataLabelKind, textScale: number) => DataLabelDimensions;
-
 /**
  * Returns pixel dimensions for a difference arrow at the requested size.
  *
@@ -3885,12 +3114,12 @@ export declare const getDataLabelDimensions: (kind: DataLabelKind, textScale: nu
 export declare const getDifferenceArrowDimensions: (size: DifferenceArrowSize, textScale: number) => DifferenceArrowDimensions;
 
 /**
- * Reads the group value written onto an observation during compilation.
+ * Reads the series-grouping key written onto an observation during compilation.
  *
- * Connected geoms (line, area) must partition observations by this key —
- * `data.groupBy(GROUP_VARIABLES.group)` — and emit one compound geom per group; other geoms
- * (bar, point, polar) iterate `data` directly. Visual values are constant within a group, so
- * read them from the first observation.
+ * 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;
 
@@ -3902,7 +3131,7 @@ export declare function getHoverGuideRectProps(coordSystem: CartesianCoordSystem
  * Reads the resolved line type (stroke style) from an observation.
  * Falls back to `'solid'` when no `lineType` variable was derived.
  *
- * A group (line / area) shares one resolved value across its observations; read it from the first
+ * A series (line / area) shares one resolved value across its rows; read it from the first
  * observation.
  */
 export declare function getLineType(observation: Observation): LineStyleType;
@@ -3919,33 +3148,18 @@ export declare function getMainAxisCoordinate(mainAxis: MainAxis, point: XYPoint
 export declare const getNumericWeight: (weight: NamedWeightKey | number | undefined) => number;
 
 /**
- * Arc extents for a banded polar bar's hover guide: the primary's category band on the band axis,
- * swept across the full value axis — the polar analog of the cartesian band rect (band width × full
- * cross extent). A `theta: 'x'` rose bands the angular spoke and sweeps the full radius; a `theta: 'y'`
- * radial bar bands the radial track and sweeps the full angle.
- */
-export declare function getPolarHoverGuideArcProps(coordSystem: PolarCoordSystem, primary: HoverHit): HoverGuideArcProps | null;
-
-/**
- * Reads a polar arc's radial extent. In polar layers the y position variables are repurposed as
+ * 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 scaled `[0, 1]` position of a custom **scalar** aesthetic (a candlestick's `open`/`close`),
- * written by the position mapper into a derived column. The aesthetic's raw value stays in the user's
- * mapped column (for tooltips/labels); this returns the finished position the render half paints with.
- */
-export declare function getScaledAesthetic(observation: Observation, aesthetic: string): NumericDataValue;
-
 /**
  * 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 group (line / area) shares one
+ * `null` / `undefined` ⇒ unmapped — apply the geom default. A series (line / area) shares one
  * resolved value across its rows; read it from the first observation.
  */
 export declare function getSize(observation: Observation): NumericDataValue;
@@ -3955,7 +3169,7 @@ export declare const getStablePolarBarKeyGenerator: () => ((observation: Observa
 /**
  * Reads the resolved stroke width value from an observation, in pixels.
  *
- * `null` / `undefined` ⇒ unmapped — apply the geom default. A group (line / area) shares one
+ * `null` / `undefined` ⇒ unmapped — apply the geom default. A series (line / area) shares one
  * resolved value across its rows; read it from the first observation.
  */
 export declare function getStrokeWidth(observation: Observation): NumericDataValue;
@@ -3971,6 +3185,9 @@ declare interface GetValuesOptions {
 
 /**
  * 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`.
  */
 export declare function getX(observation: Observation): NumericDataValue;
 
@@ -3994,6 +3211,9 @@ 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`.
  */
 export declare function getY(observation: Observation): NumericDataValue;
 
@@ -4032,7 +3252,7 @@ declare interface GoalLine {
     label?: string;
 }
 
-declare type GraphAnnotation = GraphStickerAnnotation | GraphTooltipAnnotation | GraphHighlightAnnotation | GraphTextAnnotation | GraphArrowAnnotation | GraphDifferenceArrowAnnotation | GraphShapeAnnotation | GraphImageAnnotation;
+declare type GraphAnnotation = GraphStickerAnnotation | GraphTooltipAnnotation | GraphHighlightAnnotation | GraphTextAnnotation | GraphArrowAnnotation | GraphDifferenceArrowAnnotation | GraphShapeAnnotation;
 
 declare interface GraphArrowAnnotation {
     id: string;
@@ -4058,12 +3278,12 @@ declare interface GraphArrowAnnotation {
  */
 export declare interface GraphConfig {
     type?: GraphType;
-    /** Geometry-specific settings, unioned across all graph types. */
+    /** 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 graph background. */
+    /** Ad-hoc overrides of individual theme tokens, plus a shortcut for the chart background. */
     themeOverrides?: {
         [key: string]: unknown;
         graphBackground?: string;
@@ -4095,37 +3315,15 @@ declare type GraphHighlightAnnotation = {
     highlight: 'data-point' | 'series' | 'x-value';
 } & AnnotationDataPoint;
 
-declare interface GraphImageAnnotation {
-    id: string;
-    type: 'image';
-    /** Image URL or data URI. */
-    src: string;
-    /** Whether the image 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;
-    /** How the image scales inside its box: stretch, letterbox, or crop-to-fill. */
-    fit?: 'fill' | 'contain' | 'cover';
-    /** Opacity from 0 (transparent) to 1 (opaque). */
-    opacity?: number;
-}
-
 /** Output of the layout computation. */
 export declare interface GraphLayout {
     /** The full graphical area: panel + axes + axis labels, excluding header and footer. */
     plot: Rect;
-    /** The bordered container that surrounds the panel. */
-    panelFrame: Rect;
     /**
      * The panel area where geom layers render i.e. the data rectangle inside the axes. Strictly nested
-     * inside `plot`. Geoms paint here in normalized `[0,1]` data space with y inverted
+     * 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`. Equal to {@link panelFrame} unless the layout reserves extra space
-     * for content that overflows the panel.
+     * `panel.y + (1 - y) * panel.height`.
      */
     panel: Rect;
     /** Rects for axis regions (ticks + tick labels), keyed by edge. */
@@ -4187,7 +3385,11 @@ declare interface GraphTextStyle {
     color?: string;
 }
 
-/** Light or dark theme used when resolving theme-dependent colors during GraphConfig conversion. */
+/**
+ * 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 = {
@@ -4200,46 +3402,20 @@ declare type GraphTooltipAnnotation = {
 /** Type of graph to use for the data. */
 export declare type GraphType = 'line' | 'areaStacked' | 'bar' | 'barStacked' | 'barStackedFill' | 'column' | 'columnStacked' | 'columnStackedFill' | 'combo' | 'pie' | 'donut' | 'funnel' | 'heatmap' | 'scatter' | 'bubble' | 'waterfall' | 'mekko' | 'table';
 
-/**
- * The authoring surface: the `geom`/`stat`/`transform`/`scale`/`coord` factories plus
- * `createSpec`/`pipe`. The built-in factories are augmented with a typed method per custom def in
- * `plugins` — `geom.<name>` / `stat.<name>` / `transform.<name>`, each with `params` typed from the
- * def's `defaultParams` and `aes` from its declared aesthetics. `plugins` is re-exposed so a wrapping
- * factory can seed the compiler from the same array — what can be written and what can compile derive
- * from one list. A render-only override contributes no method (it has no compile-half def).
- */
-export declare interface GraphyBuilder<P extends readonly Plugin_2[] = readonly Plugin_2[]> {
-    geom: typeof geom & CustomGeomBuilders<P>;
-    stat: typeof stat & CustomStatBuilders<P>;
-    transform: typeof transform & CustomTransformBuilders<P>;
-    scale: typeof scale;
-    coord: typeof coord;
-    createSpec: typeof createSpec;
-    pipe: typeof pipe;
-    readonly plugins: P;
-}
-
 declare type GraphyPaletteConfig = {
     type: 'graphy';
     variant?: GraphyPaletteVariant;
 };
 
-/** `waterfall` swaps in the positive/negative/total colors used by waterfall graphs. */
+/** `waterfall` swaps in the positive/negative/total colors used by waterfall charts. */
 declare type GraphyPaletteVariant = 'default' | 'waterfall';
 
-/** A geom's per-coord grid/border visibility overrides, applied by the axes guide. */
-export declare interface GridPolicy {
-    hideGridX?: boolean;
-    hideGridY?: boolean;
-    hideBorder?: boolean;
-}
-
 /**
- * Internal variable holding each observation's group value.
+ * Internal column name holding each observation's series-grouping key.
  *
- * Connected geoms (line, area) must partition observations by this key —
- * `data.groupBy(GROUP_VARIABLES.group)` — and emit one compound geom per group; other geoms
- * (bar, point, polar) iterate `data` directly. Read via `getGroup`.
+ * 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`.
  */
 export declare const GROUP_VARIABLES: {
     readonly group: string;
@@ -4293,8 +3469,6 @@ declare type GroupedVariableNames = {
  * influences axis placement.
  */
 declare class GuideCompiler extends Stage<GuideCompilerInput, CompiledGuides> {
-    private readonly container;
-    constructor(container: CommonContainer);
     protected dependencies(input: GuideCompilerInput): readonly unknown[];
     protected run(input: GuideCompilerInput): CompiledGuides;
 }
@@ -4319,8 +3493,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. */
-export declare type GuideGeometry = 'linear' | 'circular' | 'radial';
+/** 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;
@@ -4386,8 +3560,7 @@ export declare type HeadlineFontRole = 'value' | 'label';
 
 declare interface HeadlineGroupSwatch {
     color: string;
-    /** The owning layer's geom — the renderer reads its swatch shape off the geom's render contract. */
-    geom: string;
+    shape: SwatchShape;
 }
 
 declare interface HeadlineItem {
@@ -4412,8 +3585,8 @@ declare interface HeadlineItem {
 }
 
 /**
- * What the layout needs to measure, size, and place a headline. Passing this only reserves the headline
- * band during compile. To paint it, the renderer must call
+ * 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.
  */
@@ -4531,7 +3704,7 @@ declare type HeadlineSwatch = NonNullable<FormattedHeadlineItem['swatch']>;
 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
+ * 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.
  */
@@ -4581,12 +3754,12 @@ 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 observations stand out). */
+    /** True when the base render should be wrapped in a dim group (so matched marks stand out). */
     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 geoms at full strength; `null` when no re-render pass applies.
+     * draw the highlighted marks at full strength; `null` when no re-render pass applies.
      */
     matchedLayer: CompiledLayer | null;
     /** Observations to paint as overlay markers under `'overlay-anchor'`. Empty for other strategies. */
@@ -4610,7 +3783,8 @@ export declare interface HighlightInput {
 export declare interface HighlightOverlayCandidate {
     observation: Observation;
     /**
-     * Observation index into the source layer's dataset.
+     * 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;
 }
@@ -4621,8 +3795,6 @@ export declare interface HighlightOverlayCandidate {
  * `CompiledLayer.highlight.composition`. The renderer reads the composition directly.
  */
 declare class HighlightsCompiler extends PerLayerStage<HighlightsCompilerInput> {
-    private readonly container;
-    constructor(container: CommonContainer);
     protected dependencies(input: HighlightsCompilerInput): readonly unknown[];
     protected compileLayer(layer: CompiledLayer, input: HighlightsCompilerInput): CompiledLayer;
 }
@@ -4720,20 +3892,6 @@ export declare class HoverEngine {
      * detection nor group/related, so they are visual decoration only as far as hover is concerned.
      */
     private nonInteractiveLayerIds;
-    /**
-     * Per-layer render-side spatial queries for `'render-hit-test'` layers, keyed by `layerId`. The
-     * renderer registers these (the closures live render-side and never serialise); `query` consults
-     * them for render-owned layers. Held on the instance, so they survive `update()`.
-     */
-    private hitTesters;
-    /**
-     * Push-path cache for {@link resolveHoverByKey}, mirroring the `cachedKey`/`cachedState` pair
-     * `query()` keeps: the same `(layerId, key)` resolves to the same `HoverState` reference, so a
-     * live geom pushing the same key on every pointermove/frame does not defeat the store's
-     * reference-equality dedup. Invalidated alongside the query cache on `update()`.
-     */
-    private cachedByKeyId;
-    private cachedByKeyState;
     constructor({ layers, coordSystem }: HoverEngineInput);
     /**
      * Diff-aware re-index. Layers whose `data`, `geom`, `position` or the graph's coord-system
@@ -4749,7 +3907,7 @@ 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
+     * 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.
      *
@@ -4760,8 +3918,8 @@ 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),
+     * 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,
@@ -4770,31 +3928,6 @@ export declare class HoverEngine {
      * every match so the next call walks a minimum number of Delaunay edges.
      */
     query(cursor: HoverCursor): HoverState;
-    /**
-     * Registers a render-side spatial query for a `'render-hit-test'` layer. The renderer owns the
-     * closure (it changes every render as the geom recomputes its geometry); the engine only consults
-     * it during {@link query}. Idempotent per `layerId` — re-registering replaces the previous tester.
-     */
-    registerHitTester(layerId: string, tester: RenderHitTester): void;
-    unregisterHitTester(layerId: string): void;
-    /**
-     * Resolves a render-owned layer's hit from an observation key the geom already knows — the push
-     * path, for a geom whose geometry keeps changing after it's drawn and which owns its own pointer
-     * surface. Skips the spatial test {@link query} performs and resolves the key directly against the
-     * layer's `byKey` lookup. Returns the resting state when the layer is missing, isn't render-owned,
-     * non-interactive, or the key is unknown. The hit carries no anchor coordinates — the caller
-     * positions the tooltip.
-     *
-     * Honors `CompiledLayer.interactive` the same way {@link query} does (which filters the layer out
-     * before hit-testing), so a non-interactive render-owned layer participates in no hover on either
-     * path.
-     *
-     * Returns the same `HoverState` reference while `(layerId, key)` is unchanged, so a live geom
-     * pushing the same key on every pointermove/frame short-circuits the store's reference-equality
-     * dedup instead of re-rendering every hover subscriber per move (the tooltip still follows the
-     * cursor — that anchor is the caller's, not part of this state).
-     */
-    resolveHoverByKey(layerId: string, key: string): HoverState;
     private invalidateCache;
 }
 
@@ -4808,14 +3941,6 @@ export declare interface HoverEngineInput {
     coordSystem: CoordSystem;
 }
 
-/** Arc extents for the banded-polar-bar guide wedge (the polar analog of the band rect). */
-export declare interface HoverGuideArcProps {
-    startAngle: number;
-    endAngle: number;
-    innerRadius: number;
-    outerRadius: number;
-}
-
 /** SVG `<line>` endpoints for the continuous-composition rule. */
 declare interface HoverGuideLineProps {
     x1: string | number;
@@ -4832,41 +3957,45 @@ declare interface HoverGuideRectProps {
     height: string | number;
 }
 
-/**
- * A single hit returned by the hover engine. Discriminated on {@link AnchoredHoverHit.anchored}: an
- * anchored hit carries `(x, y)`; a render-owned hit carries none, so reading `x`/`y` without first
- * narrowing on `anchored` is a compile error rather than a silent placeholder.
- */
-export declare type HoverHit = AnchoredHoverHit | AnchorlessHoverHit;
-
 /**
  * A single hit returned by the hover engine.
+ *
+ * `layerId` is the stable `CompiledLayer.id` — *not* an array position. The engine preserves it
+ * across `update()` calls regardless of layer reordering or insertion, so callers must resolve a
+ * layer by matching `layer.id === hit.layerId`, never by `layers[layerId]`.
+ *
+ * `pointIndex` is an opaque per-layer stable handle for the hit geom, used by the engine as a
+ * warm-start seed for subsequent queries. The encoding is per index kind:
+ * - `buckets` / `rects` / `arcs`: the dataset row inside the layer's observations.
+ * - `points`: the entry's position inside the layer's `points[]` (i.e. the Delaunay's array
+ *   index). Diverges from the dataset row when the dataset has null x/y gaps, so callers must
+ *   read `observation` rather than indexing `data` by `pointIndex`.
+ *
+ * In every case the handle is stable across `update()` calls for layers whose `data`/`geom`/
+ * `position` references were not replaced (the warm-start identity promised by the ADR), and
+ * callers that need the observation row should read `observation` — never index into the dataset
+ * by `pointIndex`.
  */
-declare interface HoverHitBase {
-    /**
-     * Stable `CompiledLayer.id`. The engine preserves it across `update()` calls regardless of layer
-     * reordering or insertion, so callers must resolve a layer by matching `layer.id === hit.layerId`,
-     * never by `layers[layerId]`.
-     */
+export declare interface HoverHit {
     layerId: string;
-    /**
-     * An opaque per-layer stable handle for the hit geom, used by the engine as a warm-start seed for
-     * subsequent queries. The encoding is per index kind:
-     * - `buckets` / `rects` / `cells`: the dataset row inside the layer's observations.
-     * - `points`: the entry's position inside the layer's `points[]` (i.e. the Delaunay's array
-     *   index). Diverges from the dataset row when the dataset has null x/y gaps, so callers must
-     *   read `observation` rather than indexing `data` by `pointIndex`.
-     */
     pointIndex: number;
     /**
-     * The observation being hovered over. Renderers read values from here; the engine does not format.
+     * 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`).
      */
+    x: number;
+    y: number;
+    /** The observation being hovered over. Renderers read values from here; the engine does not format. */
     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) ?? [])`;
+ * **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.
  */
@@ -4874,14 +4003,14 @@ 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
+     * 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 cell layers (each mark stands alone). Render alongside the primary in its layer; do not
+     * 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
+     * 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.
@@ -4890,7 +4019,7 @@ export declare interface HoverState {
 }
 
 /**
- * Viewport facts the engine needs for aspect-corrected hit testing. Pass the plot panel rect
+ * 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.
@@ -4904,22 +4033,6 @@ export declare interface HoverViewport {
 
 declare function identity(): IdentityStatSpec;
 
-/**
- * What makes "the same observation" across recompiles, for morphs and hover stability.
- *
- * Two kinds. `'index'` and `'x-group'` are *derived*: the pipeline resolves them from the layer's
- * position/mapping, so the geom names a role, not a column.
- * - `'index'`: positional index into the dataset — the fallback when no field is stable.
- * - `'x-group'`: the columns backing the layer's x + group aesthetics, resolved per chart from the
- *   mapping. The default for standard cartesian geoms, which can't name those columns themselves.
- *
- * `{ variable }` is *explicit*: identity is one data column the geom owns and names directly, for a
- * geom keyed by its own id (sankey nodes, voronoi sites) where the x+series roles don't apply.
- */
-export declare type IdentityKey = 'index' | 'x-group' | {
-    readonly variable: string;
-};
-
 declare interface IdentityScaleInput {
     type: 'scale';
     scaledAesthetic: ScaledAestheticKey;
@@ -4937,37 +4050,6 @@ declare interface IdentityStatSpec {
     type: 'identity';
 }
 
-/** How an image annotation scales inside its box: stretch, letterbox, or crop-to-fill. */
-export declare type ImageAnnotationFit = 'fill' | 'contain' | 'cover';
-
-/**
- * Image annotation. Its area is positioned by a {@link RegionAnchorInput} so it
- * re-resolves each compile (re-flows on resize, tracks data when bound).
- */
-export declare interface ImageAnnotationInput {
-    id?: string;
-    /** Image URL or data URI. */
-    src: string;
-    /** Draw beneath the geoms (background) or on top (foreground). */
-    zOrder?: AnnotationZOrder;
-    /** The area the image fills. */
-    region: RegionAnchorInput;
-    /** How the image scales inside its box. */
-    fit?: ImageAnnotationFit;
-    /** Opacity, 0 (transparent) to 1 (opaque). */
-    opacity?: number;
-}
-
-/** Resolved image annotation with all optional fields defaulted. */
-export declare interface ImageAnnotationSpec {
-    id: string;
-    src: string;
-    zOrder: AnnotationZOrder;
-    region: RegionAnchor;
-    fit: ImageAnnotationFit;
-    opacity: number;
-}
-
 declare interface InferredScaleInput {
     type: 'scale';
     scaledAesthetic: ScaledAestheticKey;
@@ -4977,24 +4059,6 @@ declare interface InferredScaleInput {
 
 declare type InferredScaleOptions = ContinuousScaleOptions | DiscreteScaleOptions | DatetimeScaleOptions;
 
-/**
- * An engine invariant was violated — our bug.
- *
- * Codegen tools must report and stop, never retry-loop. `code` defaults to the
- * sole `INTERNAL_INVARIANT`, so most call sites pass just a `message`.
- */
-export declare class InternalError extends VizError {
-    readonly kind = "internal";
-    constructor(options: Omit<VizErrorOptions<InternalErrorCode>, 'code'> & {
-        code?: InternalErrorCode;
-    });
-}
-
-/**
- * Stable code for a violated engine invariant.
- */
-export declare type InternalErrorCode = 'INTERNAL_INVARIANT';
-
 /**
  * Curve interpolation method for lines and areas.
  *
@@ -5026,6 +4090,10 @@ 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;
 
@@ -5055,7 +4123,7 @@ 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 variables already hold cumulative band bounds — the renderer draws each
+ * 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`.
  */
@@ -5063,43 +4131,6 @@ export declare function isStackedPosition(position: PositionType): boolean;
 
 export declare const isTemporalValueFormat: (valueFormat: ValueFormat) => valueFormat is TemporalValueFormat;
 
-/**
- * True when a declared tuple field widened to a general array (the author omitted `as const`), detected
- * via a non-literal `length`. Drives the graceful fallback to a loose aes set.
- */
-declare type IsWidenedTuple<Tuple> = Tuple extends readonly unknown[] ? (number extends Tuple['length'] ? true : false) : true;
-
-/**
- * Any value that survives a `JSON.stringify` / `JSON.parse` round-trip unchanged.
- */
-declare type JsonValue = string | number | boolean | null | JsonValue[] | {
-    [key: string]: JsonValue;
-};
-
-/** One kind's observations for {@link createDatasetFromKindPartitions} — e.g. a sankey's nodes, or its flows. */
-export declare interface KindPartition {
-    /** Discriminator written to the kind column for every observation in this group (`'node'`, `'flow'`). */
-    kind: string;
-    /** Column-keyed observations for this kind. Columns absent here are null-padded across the union. */
-    observations: ReadonlyArray<Readonly<Observation>>;
-}
-
-/** The aesthetic channels with first-class engine support — the source of {@link AestheticKey}. */
-declare interface KnownAesthetics {
-    x?: AestheticValue;
-    y?: AestheticValue;
-    label?: AestheticValue;
-    color?: AestheticValue;
-    size?: AestheticValue;
-    /** Opacity (0–1). */
-    alpha?: AestheticValue;
-    /** Splits geoms into groups (separate lines/areas) without assigning a visual aesthetic. */
-    group?: AestheticValue;
-    strokeWidth?: AestheticValue;
-    /** Dash-pattern aesthetic (solid, dashed, dotted, ...). */
-    lineType?: AestheticValue;
-}
-
 /**
  * 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);
@@ -5111,17 +4142,15 @@ export declare interface LastCompileSnapshot {
 }
 
 /**
- * Compiles each layer through the transforms → stat → group → chronological-date → geom →
- * position adjusters pipeline.
+ * Compiles each layer through the transforms → stat → group → geom → position adjusters pipeline.
  */
 declare class LayerCompiler extends PerLayerStage<LayerCompilerInput, LayerSpec, CompiledLayer> {
-    private readonly container;
     private readonly transformCompiler;
     private readonly statCompiler;
     private readonly groupCompiler;
     private readonly geomCompiler;
     private readonly positionAdjusterCompiler;
-    constructor(container: CommonContainer, transformCompiler: TransformCompiler, statCompiler: StatCompiler, groupCompiler: GroupCompiler, geomCompiler: GeomCompiler, positionAdjusterCompiler: PositionAdjusterCompiler);
+    constructor(transformCompiler: TransformCompiler, statCompiler: StatCompiler, groupCompiler: GroupCompiler, geomCompiler: GeomCompiler, positionAdjusterCompiler: PositionAdjusterCompiler);
     protected dependencies(input: LayerCompilerInput): readonly unknown[];
     protected compileLayer(layer: LayerSpec, input: LayerCompilerInput): CompiledLayer;
     private runLayerPipeline;
@@ -5141,26 +4170,22 @@ declare interface LayerCompilerInput {
 }
 
 /**
- * Discriminated union of all layer inputs, keyed on `geom`. The built-in arms stay exactly typed;
- * the {@link CustomGeomLayerInput} arm admits a plugin geom carrying a name outside {@link GeomName}.
+ * Discriminated union of all layer inputs, keyed on `geom`.
  * This is the user-facing type — fields are optional and will be resolved with defaults.
  */
-export declare type LayerInput = {
+declare type LayerInput = {
     [G in GeomName]: LayerInputOf<G>;
-}[GeomName] | CustomGeomLayerInput;
+}[GeomName];
 
-export declare interface LayerInputBase {
+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), or a custom plugin stat.
-     * @default 'identity'
-     */
-    stat?: StatName | StatInput | CustomStatInput<string>;
-    /** How overlapping geoms are arranged (stack, dodge, fill, identity). */
+    /** 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;
@@ -5183,93 +4208,13 @@ declare type LayerInputOf<G extends GeomName> = LayerInputBase & {
     params?: Partial<GeomParamsMap[G]>;
 };
 
-/**
- * The layer step of the compile pipeline: it brackets {@link LayerCompiler} with checks so the main
- * {@link Compiler} sees a single call. One {@link compile} runs three phases:
- *
- * 1. {@link checkPreCompile} — per-layer invariant checks collected across all layers, then the first
- *    thrown as a representative `UserInputError`, so the compile cache never holds output for a
- *    rejected layer.
- * 2. {@link LayerCompiler.compile} — the actual per-layer compilation (memoized).
- * 3. {@link checkPostCompile} — advisory checks over the compiled output (currently: nothing-to-plot),
- *    emitted as non-fatal warnings.
- */
-declare class LayerPhasedCompiler {
-    private readonly container;
-    private readonly transformCompiler;
-    private readonly statRegistry;
-    private readonly layerCompiler;
-    constructor(container: CommonContainer, transformCompiler: TransformCompiler, statRegistry: StatRegistry, layerCompiler: LayerCompiler);
-    /** Cache telemetry for the wrapped layer compile, surfaced to the main compiler's per-stage stats. */
-    get stats(): MemoStats;
-    /** Validate inputs, compile each layer, then inspect the compiled output. */
-    compile(input: LayerCompilerInput): CompiledLayer[];
-    /** Pre-compile: validate each layer's spec, aborting the pipeline if any layer is invalid. */
-    checkPreCompile(input: LayerCompilerInput): void;
-    /**
-     * Post-compile: a chart whose every layer resolved to zero observations compiles cleanly but
-     * renders blank. Surface that as a warning so an empty dataset — or transforms that filtered every
-     * row away — is non-silent for both the end user and codegen, rather than a confusingly empty plot.
-     */
-    checkPostCompile(layers: CompiledLayer[]): void;
-    /**
-     * Run every per-layer check and collect their issues. Each check reads what the geom *declares*
-     * (its position contract, its `validateMapping` hook, its supported coords) rather than which geom
-     * it is, so a custom geom is validated by the same path as a built-in.
-     *
-     * 1. Required aesthetics are present (accounting for stat-computed variables).
-     * 2. Every mapped variable exists in the layer's dataset.
-     * 3. Each custom positional aesthetic maps to a numeric column.
-     * 4. The geom's own bespoke mapping requirement, if it declares one.
-     * 5. The geom supports the active coord system.
-     */
-    validateLayer(input: LayerValidationInput): UserInputIssue[];
-    /**
-     * Checks that all aesthetics required by the geom are present (accounting for stat-computed variables).
-     */
-    private validateRequiredAesthetics;
-    /**
-     * Checks that every mapped variable in the effective mapping exists in the layer's dataset (after
-     * transforms). Skips aesthetics that will be computed by stats (e.g. `y` when `stat='count'`).
-     */
-    private validateVariableExistence;
-    /**
-     * Checks that each **custom** positional aesthetic an interval (`min`/`max`) or `scalar` role binds
-     * maps to a numeric column. The position mapper reads these columns as numbers to scale them, so a
-     * categorical or temporal column would throw deep in the pipeline (a misclassified internal error);
-     * flagging it here names the offending aesthetic in a user-facing error instead.
-     *
-     * Only custom aesthetics (those whose name differs from the role's axis) are checked — a built-in `x`/`y`
-     * is already covered by the scale-compatibility pass and the geom's own `validateMapping` — and a role
-     * sourced from a constant or a stat-computed variable is left to the existing checks.
-     */
-    private validatePositionalAestheticTypes;
-    /**
-     * Runs the geom's own bespoke mapping requirement, if it declares one (e.g. a rule's "exactly one
-     * of x or y"). The geom returns geom-scoped issues; the validator stamps the layer context on.
-     */
-    private validateGeomMapping;
-    /**
-     * Rejects a layer under a coord system its geom doesn't declare support for (e.g. a rule under
-     * polar). Reads `supportedCoordTypes` so a custom geom is gated by what it declares, not by name.
-     */
-    private validateCoordSupport;
-    /**
-     * Flags a mapping that names an aesthetic the geom never declared — neither in its position
-     * contract (the position aesthetics) nor its declared `aesthetics`, and not one of the
-     * {@link UNIVERSAL_AESTHETICS} or a stat-computed channel. The extra mapping is silently ignored
-     * downstream, so this is a warning (a likely typo, e.g. `size` on a bar) rather than a hard error.
-     */
-    private collectUndeclaredAesthetics;
-}
-
 /**
  * Discriminated union of all resolved layer specs, keyed on `geom`.
  * All properties are fully resolved — no optionals.
  */
-export declare type LayerSpec = {
+declare type LayerSpec = {
     [G in GeomName]: LayerSpecOf<G>;
-}[GeomName] | CustomGeomLayerSpec;
+}[GeomName];
 
 declare interface LayerSpecBase {
     type: 'layer';
@@ -5288,7 +4233,7 @@ 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 geom calls for them. */
+/** 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[];
@@ -5298,12 +4243,27 @@ export declare interface LayerSummary {
     absoluteGrandTotal?: number;
 }
 
-/** A single layer's resolved inputs, as fed to {@link LayerPhasedCompiler.validateLayer}. */
+/**
+ * Per-layer invariant checks. Runs before {@link LayerCompiler} so the compile cache never holds
+ * output for rejected layers.
+ */
+declare class LayerValidationCheck {
+    private readonly transformCompiler;
+    private readonly validator;
+    constructor(transformCompiler: TransformCompiler, validator: LayerValidator);
+    check(input: LayerValidationCheckInput): void;
+}
+
+declare interface LayerValidationCheckInput {
+    data: Dataset;
+    layers: LayerSpec[];
+    mapping: AesMapping;
+    coords: CoordSpec;
+}
+
 declare interface LayerValidationInput {
     layerId: string;
-    /** Position of the layer in `spec.layers`, carried into diagnostic `context`. */
-    layerIndex: number;
-    geom: string;
+    geom: GeomName;
     stat: StatSpec;
     /** `spec.mapping` merged with `layer.mapping` */
     effectiveMapping: AesMapping;
@@ -5314,8 +4274,45 @@ declare interface LayerValidationInput {
 }
 
 /**
- * Default outer padding around the graph, in pixels, used when {@link buildLayoutGrid} gets no explicit
- * `padding` (the renderer overrides it with a resolved theme token).
+ * Validates a single layer against a set of invariants.
+ *
+ * Checks:
+ * 1. All required aesthetics are present (accounting for stat-computed variables).
+ * 2. All mapped variables exist in the layer's dataset (after transforms).
+ *
+ * Returns issues rather than throwing. The caller (LayerCompiler) batches issues across all layers and throws
+ * a single SpecValidationError at the end.
+ */
+declare class LayerValidator {
+    private readonly geomRegistry;
+    private readonly statRegistry;
+    constructor(geomRegistry: GeomRegistry, statRegistry: StatRegistry);
+    validate(input: LayerValidationInput): ValidationIssue[];
+    /**
+     * Checks that all aesthetics required by the geom are present (accounting for stat-computed variables).
+     */
+    private validateRequiredAesthetics;
+    /**
+     * Checks that every mapped variable in the effective mapping exists in the layer's dataset (after
+     * transforms). Skips aesthetics that will be computed by stats (e.g. `y` when `stat='count'`).
+     */
+    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`).
+     */
+    private validateRuleMapping;
+    /**
+     * In the current version, rule layers don't have meaningful semantics under polar coords (pie / donut).
+     */
+    private validateRuleCoord;
+}
+
+/**
+ * Outer padding around the whole chart, in pixels. Already baked into every {@link GraphLayout} rect
+ * (rects start at this inset), so don't re-add it when painting — it 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.
  */
 export declare const LAYOUT_PADDING = 24;
 
@@ -5344,28 +4341,9 @@ export declare class LayoutCompiler {
     constructor(measurer: LayoutMeasurer);
     compile(input: LayoutCompilerInput): LayoutCompileResult;
     /**
-     * Computes space that needs to be added inside and outside of the panel frame to
-     * accomodate content that may overflow its boundary.
-     */
-    private measurePanelOverflow;
-    /**
-     * Reserves space for overflowing content by re-measuring against the reserved panel until the reserve settles.
-     * Data-anchored content moves as the panel shrinks, so this handles the case where a single pass may under-reserve
-     * if an element is particularly close to the boundary.
-     */
-    private settlePanelOverflow;
-    /**
-     * Shapes the polar panel into a centred 1:1 square so the drawing frame has a single, aspect-free
-     * scale: geoms position marks as a percentage of a square viewport (fixed pixel radius, no resize
-     * re-render) and the inscribed circle is identical for guides, marks, hover and highlight. For a
-     * radar (circular axis) the panel is first inset on all four sides by the widest rim label — circular
-     * and radial axes claim no edge track (see measureGuides), so without this the outer ring would touch
-     * the shorter panel edge and rim labels would overflow — then squared. A pie/donut (no circular axis)
-     * is squared without a rim inset.
+     * Computes the panel pad needed so annotation labels stay inside the graph and don't overlap the panel edges.
      */
-    private applyPolarPanelInset;
-    /** Rim-label inset for a radar's circular axis (widest label + gap per side); zero for a pie/donut. */
-    private measurePolarRimInset;
+    private measureAnnotationOverflow;
     /**
      * Stamps each axis with a single hardcoded-label placeholder tick. This gives the grid something to measure in
      * the first pass. The finalize pass replaces it with the real candidate selected for the resolved panel size.
@@ -5392,9 +4370,9 @@ 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
+     * 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 the renderer does not re-run candidate selection or re-apply a value format.
+     * panel size), so do not re-run candidate selection or re-apply a value format in the renderer.
      */
     formattedAxes: FormattedAxis[];
 }
@@ -5406,7 +4384,7 @@ export declare interface LayoutCompilerInput {
     parsingLocale: Locale;
     numberFormat: NumberFormatConfig;
     formattedLegends: FormattedLegend[];
-    /** Total pixel area available to the whole graph. */
+    /** Total pixel area available to the whole chart. */
     containerSize: BoxSize;
     externalMeasurements: ExternalMeasurements;
     /** The headline to measure and place; absent = no headline. */
@@ -5415,20 +4393,14 @@ export declare interface LayoutCompilerInput {
     formattingLocale?: Locale;
     /** Annotations that may overflow the panel and need extra edge padding reserved. */
     annotations?: CompiledAnnotations;
-    /** Coord system, consulted only to decide whether panel overflow applies (cartesian only). */
+    /** Coord system, consulted only to decide whether annotation overflow applies (cartesian only). */
     coordSystem?: CoordSystem;
-    /** Font size multiplier applied to all text drawn by the renderer. */
-    textScale?: number;
-    /** Compiled layers, used to reserve panel padding for data labels that would otherwise overflow the cross axis. */
-    layers?: readonly CompiledLayer[];
-    /** Strategy to apply when content overflows the panel (configured per content type) */
-    overflowStrategy?: OverflowStrategyInput;
     /**
-     * * 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).
+     * 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.
      */
-    padding?: number;
+    textScale?: number;
 }
 
 /** Positions where axes/labels/legends can be placed around the panel. */
@@ -5453,8 +4425,6 @@ export declare interface LayoutMeasurer extends HeadlineMeasurer {
     measureTickLabel: (label: string) => MeasuredText;
     /** Returns the size of a difference-arrow label rendered at the given size. */
     measureDifferenceArrowLabel: (text: string, size: DifferenceArrowSize) => MeasuredText;
-    /** Returns the size of a data label of the given kind. */
-    measureDataLabel: DataLabelTextMeasurer;
 }
 
 declare interface Legend {
@@ -5494,7 +4464,7 @@ declare type LegendConfigInput = Partial<LegendConfig>;
  */
 declare type LegendDisplay = 'pill' | 'direct' | 'auto';
 
-/** One item in a legend: a domain value paired with the visual values that represent it. */
+/** 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;
@@ -5508,12 +4478,13 @@ export declare interface LegendItem {
      */
     normalizedY: number | null;
     /**
-     * The geom whose swatch 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).
-     * The renderer maps it to a swatch shape via its `(geom, coord)` registry — the same geom that
-     * drives the headline and rule pills.
+     * 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.
      */
-    geom: string;
+    swatchShape: SwatchShape;
     /**
      * Format descriptor for this item's `value`. Per-item because a combo legend can span layers
      * whose aesthetic variables have different inferred formats.
@@ -5527,41 +4498,18 @@ export declare interface LegendItem {
 declare interface LegendItemVisual {
     color?: string;
     /**
-     * Symbol diameter in pixels, present on bubble legends (see {@link CompiledLegendGuide.aesthetics}). Render a
+     * 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 swatch shapes ignore it. */
+    /** Stroke style for `line` / `area` swatches only (solid/dashed/dotted). Other `swatchShape`s ignore it. */
     lineType?: LineStyleType;
 }
 
-/**
- * How a geom relates to the colour legend. Read by the legends guide to decide whether a redundant
- * single-item legend is dropped, where an `'auto'` legend lands, and whether direct (inline) labels
- * can stand in for it.
- */
-export declare interface LegendPolicy {
-    /** When a single item renders, the legend is redundant (the graph shows it directly), so suppress it. */
-    suppressWhenSingleItem?: boolean;
-    /** When this geom's legend prefers the side (right) over the top; defaults to `'never'`. */
-    sidePlacement?: LegendSidePlacement;
-    /** Positions for which this geom shows direct (inline) series labels instead of a pill legend. */
-    directLabelSupport?: Partial<Record<PositionType, boolean>>;
-}
-
 declare type LegendPosition = 'auto' | 'right' | 'left' | 'top' | 'bottom' | 'none';
 
-/**
- * When a geom's colour legend prefers the side (right) over the top, used to resolve an `'auto'`
- * legend position once the rendered item count is known:
- * - `'never'`: always top-placed (the default — point, rule, and any geom that doesn't opt in).
- * - `'whenCrowded'`: moves to the side once there are many items (line/area).
- * - `'whenStackedVertical'`: moves to the side only for vertically-stacked layers (bar).
- */
-export declare type LegendSidePlacement = 'never' | 'whenCrowded' | 'whenStackedVertical';
-
 declare function line(options?: GeomOptions<'line'>): LayerInputOf<'line'>;
 
 /**
@@ -5570,7 +4518,7 @@ declare function line(options?: GeomOptions<'line'>): LayerInputOf<'line'>;
 export declare interface LineGeomParams {
     /**
      * Stroke width in pixels. `'auto'` reads the per-observation `strokeWidth`
-     * value (`getStrokeWidth`) and falls back to the geom default when unmapped.
+     * channel (`getStrokeWidth`) and falls back to the geom default when unmapped.
      */
     lineWidth: number | 'auto';
     /**
@@ -5588,12 +4536,6 @@ export declare interface LineGeomParams {
      * @default 'gap'
      */
     missingValues: MissingValuesType;
-    /**
-     * Draws a gradient fill beneath the line (series color fading from the line down to
-     * transparent at the panel baseline).
-     * @default true
-     */
-    showFill: boolean;
 }
 
 declare interface LineOptions {
@@ -5602,8 +4544,6 @@ declare interface LineOptions {
     showPoints?: boolean;
     /** How gaps in the data are drawn: leave a gap, connect across, or treat as zero. */
     missingValues?: 'gap' | 'connect' | 'zero';
-    /** Draws a gradient fill beneath the line (single series only) */
-    showFill?: boolean;
 }
 
 /**
@@ -5615,7 +4555,13 @@ 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. */
+/**
+ * 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. */
@@ -5646,12 +4592,9 @@ export declare interface LookupValueFormat {
 
 /**
  * The data-space axis a `CartesianCoordSystem` uses as the main (independent) axis.
- * When `mainAxis === 'y'` (flip), the position variable roles swap: the x-variables (`getX`/`getXMin`/
- * `getXMax`) carry the measure / cross-axis extent and the y-variables carry the main-axis band
- * position. The swap is baked into the position variables at compile time (the coord transform renames
- * them), so `getX`/`getY` map straight to their pixel axes regardless of flip. This flag is for
- * consumers that must reason about which data axis is independent — guide placement, hover bucketing,
- * label and arrow growth direction — via the `coord/axes` main/cross helpers.
+ * 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.
  */
 export declare type MainAxis = 'x' | 'y';
 
@@ -5685,7 +4628,13 @@ declare interface MeanStatSpec {
     type: 'mean';
 }
 
-/** Pixel dimensions of a measured string, including the baseline split into ascent and descent. */
+/**
+ * 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;
@@ -5708,7 +4657,8 @@ export declare interface MemoStats {
  *   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 nulls before pathing.
+ * - `'connect'` — Skip missing values and connect adjacent valid points. The renderer drops null
+ *   rows before pathing.
  */
 export declare type MissingValuesType = 'zero' | 'gap' | 'connect';
 
@@ -5768,12 +4718,9 @@ declare type NeonPaletteConfig = {
     variant?: NeonPaletteVariant;
 };
 
-/** `waterfall` swaps in the positive/negative/total colors used by waterfall graphs. */
+/** `waterfall` swaps in the positive/negative/total colors used by waterfall charts. */
 declare type NeonPaletteVariant = 'default' | 'waterfall';
 
-/** Wrap an angle into `[0, 2π)`. */
-export declare const normalizeAngle: (angle: number) => number;
-
 /**
  * Configuration for formatting a single number.
  * Defines how numeric values should be displayed in the chart.
@@ -5805,11 +4752,15 @@ export declare interface NumberFormatConfig {
      */
     decimalSeparator?: string;
     /**
-     * Prefix to prepend (e.g., '$', '€').
+     * 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?: string;
     /**
-     * Suffix to append (e.g., '%', ' units').
+     * 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?: string;
 }
@@ -5835,8 +4786,8 @@ export declare interface ObservationAnchor {
     layerId?: string;
     /** Value on the main axis (x in cartesian, y in flipped). */
     anchorValue: DataValue;
-    /** The group value to match if any, otherwise match any group. */
-    groupValue?: DataValue;
+    /** Series identity (the `group` aesthetic value). */
+    groupValue: DataValue;
 }
 
 /** Points at a single observation by its anchor value and series. */
@@ -5845,31 +4796,12 @@ export declare interface ObservationAnchorInput {
     layerIndex?: number;
     /** Value on the main axis (x in cartesian, y in flipped). */
     anchorValue: DataValue;
-    /** The group value to match if any, otherwise match any group. */
-    groupValue?: DataValue;
+    /** Series identity (the `group` aesthetic value). */
+    groupValue: DataValue;
 }
 
 declare type Options = Partial<LineOptions & BarOptions & ScatterOptions & ComboOptions & PieOptions & TableOptions>;
 
-/** How far an anchor may sit outside the panel before a callout is considered out of view. */
-export declare const OUT_OF_VIEW_MARGIN_PX = 8;
-
-/**
- * Configure a different overflow strategy per direction.
- */
-export declare interface OverflowStrategyConfig {
-    x: PanelOverflowStrategy;
-    y: PanelOverflowStrategy;
-}
-
-/**
- * Overflow strategy to user per content type
- */
-export declare interface OverflowStrategyInput {
-    dataLabels?: OverflowStrategyConfig;
-    differenceArrows?: OverflowStrategyConfig;
-}
-
 /** Resolved palette selector; a custom palette carries its looked-up `colors`. */
 declare type PaletteConfig = DefaultPaletteConfig | GraphyPaletteConfig | PastelPaletteConfig | NeonPaletteConfig | MonoPaletteConfig | CustomPaletteConfig;
 
@@ -5896,7 +4828,7 @@ export declare type PaletteOverridesInput = Record<number, {
 /** User-facing palette color scale; defaults to the active theme palette when `palette` is omitted. */
 declare interface PaletteScaleInput {
     type: 'scale';
-    /** Which aesthetic this scale drives — only color aesthetics accept palettes. */
+    /** Which channel this scale drives — only color channels accept palettes. */
     scaledAesthetic: ScaledAestheticKey;
     scaleType: 'palette';
     /** Named or custom palette to draw group colors from. */
@@ -5921,91 +4853,21 @@ declare interface PaletteScaleSpec {
     overrides?: PaletteOverrides;
 }
 
-/** One side of the panel border. */
-export declare type PanelBorderEdge = 'top' | 'right' | 'bottom' | 'left';
-
-/**
- * Configuration for one edge of the panel border.
- */
-export declare interface PanelBorderEdgeConfig {
-    /**
-     * Whether this edge is drawn.
-     * @default true
-     */
-    isVisible: boolean;
-    /**
-     * Line style of this edge.
-     * @default 'dashed'
-     */
-    lineStyle: LineStyleType;
-    /**
-     * Stroke width of this edge in px. null inherits the theme's grid line width.
-     * @default null
-     */
-    lineWidth: number | null;
-}
-
-/** One stroke of the panel border: every segment in it shares a single line style and width. */
-export declare interface PanelBorderPath {
-    lineStyle: LineStyleType;
-    /** Stroke width in px. null inherits the theme's grid line width. */
-    lineWidth: number | null;
-    segments: PanelBorderSegment[];
-}
-
-/**
- * A drawing primitive for the panel border, in the input rect's pixel space. Arcs follow the
- * canvas 2D convention (radians, clockwise, y down) and start at the current point, so segments
- * replay directly via `moveTo`/`lineTo`/`arc` or convert to an SVG path (`A` with sweep flag 1).
- */
-export declare type PanelBorderSegment = {
-    type: 'move';
-    x: number;
-    y: number;
-} | {
-    type: 'line';
-    x: number;
-    y: number;
-} | {
-    type: 'arc';
-    cx: number;
-    cy: number;
-    radius: number;
-    startAngle: number;
-    endAngle: number;
-} | {
-    type: 'close';
-};
-
 /**
- * Panel configuration. The border is configured per edge; a corner is rounded
- * only when both edges meeting at it are visible.
+ * Panel configuration
  */
 declare interface PanelConfig {
-    border: Record<PanelBorderEdge, PanelBorderEdgeConfig>;
-    /** Per-source, per-axis strategy to use for content that overflows the panel edge. */
-    overflow: {
-        dataLabels: OverflowStrategyConfig;
-        differenceArrows: OverflowStrategyConfig;
+    border: {
+        isVisible: boolean;
     };
 }
 
-/**
- * How the panel adapts to content that would otherwise overflow its edge.
- * - `outside`: the overflowing element lands outside the panel frame and the frame shrinks to
- *    accomodate it.
- * - `inside`: the overflowing element stays inside the panel frame and the content inside the
- *   frame shrinks to accomodate it.
- * - `none`: no accomodation, content may overflow and overlap with other elements
- */
-export declare type PanelOverflowStrategy = 'outside' | 'inside' | 'none';
-
 declare type PastelPaletteConfig = {
     type: 'pastel';
     variant?: PastelPaletteVariant;
 };
 
-/** `waterfall` swaps in the positive/negative/total colors used by waterfall graphs. */
+/** `waterfall` swaps in the positive/negative/total colors used by waterfall charts. */
 declare type PastelPaletteVariant = 'default' | 'waterfall';
 
 /**
@@ -6032,7 +4894,7 @@ declare abstract class PerLayerStage<Input extends {
 }
 
 declare interface PieOptions {
-    /** Where the aggregate total is shown: inside the ring (donut) or outside the graph. */
+    /** Where the aggregate total is shown: inside the ring (donut) or outside the chart. */
     pieTotalPosition?: 'center' | 'outside';
 }
 
@@ -6041,68 +4903,37 @@ declare interface PieOptions {
  * renderer's mini view shows the observation's measurement value; hover reveals
  * the full tooltip (x + y + trend).
  */
-export declare interface PinnedNumberAnnotationInput {
+declare interface PinnedNumberAnnotationInput {
     id?: string;
-    at: ObservationAnchorInput;
+    anchor: ObservationAnchorInput;
 }
 
-export declare interface PinnedNumberAnnotationSpec {
+declare interface PinnedNumberAnnotationSpec {
     id: string;
-    at: ObservationAnchor;
+    anchor: ObservationAnchor;
 }
 
 /**
- * Fold a sequence of pipeable spec items onto an existing spec, left to right, returning a new spec.
- * Each item is appended by kind: layers accumulate (call `geom.*` once per mark), scales accumulate,
- * `config` deep-merges, `coord`/`mapping` overwrite/merge. The usual shape is
- * `pipe(createSpec({...}), geom.x(), scale.x(), scale.y(), ...)`.
- *
- * @example
- * pipe(createSpec({ x: 'month', y: 'sales', color: 'region' }), geom.line(), scale.x(), scale.y(), scale.color.palette());
+ * Pipe a spec through a series of spec items (left-to-right).
  */
 export declare function pipe(spec: SpecInput, ...items: SpecItem[]): SpecInput;
 
-/**
- * Turns compiled pinned-number and comment annotations into render-ready `PlacedCallout` rects.
- */
-export declare function placeCallouts(input: PlaceCalloutsInput): PlacedCallout[];
-
-export declare interface PlaceCalloutsInput {
-    pinnedNumbers: readonly CompiledPinnedNumberAnnotation[];
-    comments: readonly CompiledCommentAnnotation[];
-    panelRect: Rect;
-    coordSystem: CoordSystem;
-    measurer: CalloutMeasurer;
-    formatPinnedNumber: (annotation: CompiledPinnedNumberAnnotation) => string;
-}
-
-/**
- * One placed callout, ready for a renderer to paint. Coordinates are in panel-pixel space
- * with origin at the panel's top-left.
- */
-export declare interface PlacedCallout {
-    id: string;
-    kind: CalloutKind;
-    /** Anchor position in panel-local SVG pixels (cartesian y already flipped to top-origin). */
-    anchorPx: {
-        x: number;
-        y: number;
-    };
-    placement: CalloutPlacement;
-    miniRect: Rect;
-    inView: boolean;
-}
-
 /**
  * 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.
+ * 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
+     * labels use `${layerId}:${stableKey([xValue, groupValue])}`; stack totals use
+     * `${layerId}:stack:${xKey}`. Survives appends, removals, and reorders of `layer.data`.
+     */
+    key: string;
     x: number;
     y: number;
     text: string;
@@ -6117,55 +4948,8 @@ export declare interface PlacedDataLabel {
     position: DataLabelPosition;
 }
 
-/**
- * One entry in the unified `plugins` array. Either a bare compile definition, a render half that carries
- * its definition at `.definition`, or a render-only override that carries none. The first two contribute
- * a compile definition (matched structurally over the field that already exists, never by naming
- * react-renderer's `GeomRendererDefinition` type); the last seeds only the render registry.
- */
-declare type Plugin_2 = CompileDefinition | {
-    readonly definition: CompileDefinition;
-} | RenderOnlyPlugin;
-export { Plugin_2 as Plugin }
-
 declare function point(options?: GeomOptions<'point'>): LayerInputOf<'point'>;
 
-/** Resolved point anchor: `layerIndex` replaced with the stable `layerId`. */
-export declare type PointAnchor = {
-    anchorType: 'panel';
-    x: number;
-    y: number;
-    offset?: AnchorOffset;
-} | {
-    anchorType: 'observation';
-    layerId?: string;
-    anchorValue: DataValue;
-    groupValue?: DataValue;
-    align?: AnchorAlign;
-    offset?: AnchorOffset;
-};
-
-/**
- * A single position, expressed as a relationship to the graph that re-resolves each compile.
- *
- * - `panel`: a fraction of the plot rect (`[0,1]`), top-left origin. Does not snap to data.
- * - `observation`: pinned to one observation by its `(anchorValue, groupValue)` pair.
- */
-export declare type PointAnchorInput = {
-    anchorType: 'panel';
-    x: number;
-    y: number;
-    offset?: AnchorOffset;
-} | {
-    anchorType: 'observation';
-    /** Pick a specific layer when multiple share the same `(anchorValue, groupValue)` pair. */
-    layerIndex?: number;
-    anchorValue: DataValue;
-    groupValue?: DataValue;
-    align?: AnchorAlign;
-    offset?: AnchorOffset;
-};
-
 /**
  * Point-specific parameters
  */
@@ -6179,13 +4963,6 @@ declare interface PointPosition {
     y: number;
 }
 
-/**
- * Pixels between a radar's outer ring and its rim category labels. Shared across the compile/render
- * seam so the layout reserves exactly the margin the guide renderer paints into (the layout compiler's
- * rim inset and the polar guide renderers derive from this one value rather than hand-synced copies).
- */
-export declare const POLAR_RIM_LABEL_GAP_PX = 8;
-
 export declare interface PolarBarArcInput {
     startAngle: number;
     endAngle: number;
@@ -6229,8 +5006,8 @@ declare interface PolarCoordSpec {
  * `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 variables: x-variables carry angles, y-variables carry radii.
- * Angles are absolute radians (`startAngle` already applied, clockwise),
+ * 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`.
  */
@@ -6244,39 +5021,9 @@ export declare interface PolarCoordSystem {
      * floor, so it is recoverable from any arc.
      */
     innerRadius: number;
-    /**
-     * Angular offset of the first position, in radians (the spec's `startAngle` converted from degrees).
-     * The angular transform bakes it into the `x` column and the guide renderer reuses it, so painted
-     * marks, spokes and rim labels share one origin.
-     */
-    startAngle: number;
-    /**
-     * Extra frame rotation, in radians, that lands the first categorical spoke on `startAngle`
-     * (first-axis-up). The band scale places category 0 at `1/(2N)`, so this is `−(1/(2N))·2π` for a
-     * categorical circular axis and `0` for a continuous one (pie/donut). Added alongside `startAngle`
-     * in the angular transform and recovered identically by the guide renderer.
-     */
-    spokeRotation: number;
-    /**
-     * Which position axis carries the chart's categorical band, or `null` when there is none: `'x'` for a
-     * radar/rose (categories spoke the angular axis), `'y'` for a radial bar (categories are concentric
-     * radial tracks — the post-swap radius column), `null` for a pie/donut (the angle is a continuous value
-     * sweep, so no position axis is categorical). Resolved once in `setup` so the guide compiler (does this
-     * polar chart draw axes?), the hover indexer (pie enclosure vs banded-bar snap, and which axis groups
-     * the bands), and the polar hover guide (wedge orientation) each read one fact rather than re-deriving
-     * it from mapping, axis geometry, or scale type.
-     */
-    bandAxis: 'x' | 'y' | null;
 }
 
-/**
- * Projects a polar coordinate (angle in radians clockwise from 12 o'clock, radius as a `[0, 1]`
- * fraction) to an offset in a y-**up** unit disk centred at the origin: `(r·sinθ, r·cosθ)`. Callers
- * that paint in a top-origin pixel frame negate `y` and scale by the pixel radius.
- */
-export declare const polarToUnit: (angle: number, radius: number) => XYPoint;
-
-/** Internal variables holding each observation's compiled positions (normalized to `[0, 1]`). */
+/** Internal column names holding each observation's compiled positions (normalized to `[0, 1]`). */
 export declare const POSITION_VARIABLES: {
     readonly x: string;
     readonly y: string;
@@ -6318,13 +5065,6 @@ declare class PositionAdjusterRegistry extends Registry<PositionType, PositionAd
     constructor();
 }
 
-/**
- * The aes keys a geom's position roles contribute: the open per-role keys ({@link AesFromRoles},
- * including custom positional aesthetics). When `positionRoles` widened (no `as const`) the role set is
- * untyped, so this relaxes to the full {@link AestheticKey} set and the exact-aes check is dropped.
- */
-declare type PositionAesKeys<Def extends Geom<unknown>> = IsWidenedTuple<Def['positionRoles']> extends true ? AestheticKey : Def['positionRoles'] extends readonly PositionRole[] ? AesFromRoles<Def['positionRoles'][number]> : never;
-
 declare interface PositionalScaleMethods {
     /**
      * Continuous (numeric) scale. Supports `transform`, `reverse`, `nice`, `zero`, `domainMin`, `domainMax`.
@@ -6353,9 +5093,6 @@ declare interface PositionalScaleMethods {
     sqrt: (options?: ContinuousScaleOptions) => ContinuousScaleInput;
 }
 
-/** The axis a position role binds to. */
-export declare type PositionAxis = 'x' | 'y';
-
 /**
  * A position variable mapper that applies position scaling for a single concern
  * (e.g. primary x, band extents, y baseline extents).
@@ -6372,9 +5109,8 @@ declare interface PositionMapper {
  * ([0,1]) on each layer's dataset.
  */
 declare class PositionMapperCompiler extends PerLayerStage<PositionMapperCompilerInput> {
-    private readonly container;
     private readonly mappers;
-    constructor(container: CommonContainer, mappers?: PositionMapper[]);
+    constructor(mappers?: PositionMapper[]);
     protected dependencies(input: PositionMapperCompilerInput): readonly unknown[];
     protected compileLayer(layer: CompiledLayer, input: PositionMapperCompilerInput): CompiledLayer;
 }
@@ -6388,54 +5124,17 @@ declare interface PositionMapperCompilerInput {
  * Context passed to each column mapper during position mapping.
  */
 declare interface PositionMapperInput {
-    geomRegistry: GeomRegistry;
     data: Dataset;
     layer: CompiledLayer;
     getPositionScale: (scaleAestheticKey: ScaledAestheticKey) => CompiledPositionScale | null;
 }
 
-/**
- * One position column the geom's compile half injects and its render half reads (`yMin`/`yMax`/…).
- * Declaring it makes the cross-half column contract explicit, so a single-half override can be
- * checked rather than silently mispainting.
- *
- * `aes` names the aesthetic the mapper sources the role from — a plain `string`, so a geom may bind
- * a **custom positional aesthetic** (`'open'`, `'low'`) the engine then trains and scales like a
- * built-in channel. A `min`/`max` role without `aes` is compile-written (e.g. a bar's
- * `yMin = 0`); a `scalar` role scales its `aes` column in place into the aesthetic-named column.
- */
-export declare interface PositionRole {
-    readonly axis: PositionAxis;
-    readonly role: PositionRoleKind;
-    readonly valueKind: 'value';
-    readonly aes?: string;
-}
-
-/**
- * The role a position column plays on its axis (named column semantics):
- * - `point`: a single per-observation position; sources its axis aesthetic implicitly.
- * - `scalar`: a single value scaled in place on the axis (e.g. a reference line).
- * - `min` / `max`: the two ends of a per-observation interval (e.g. a bar's `[0, value]`).
- */
-export declare type PositionRoleKind = 'point' | 'scalar' | 'min' | 'max';
-
-/** A geom's position roles. */
-declare type PositionRoles = readonly PositionRole[];
-
 /**
  * Subset of {@link CompiledScales} the position mapper reads. Narrowed so visual-scale changes
  * don't enter this stage's cache dependency surface.
  */
 declare type PositionScalesSlice = Pick<CompiledScales, 'x' | 'y' | 'ySecondary'>;
 
-/**
- * Maps a normalized `[0, 1]` axis position to its absolute angle in radians, applying the coord's
- * `startAngle` origin and the first-axis-up `spokeRotation`. The single owner of the position→angle
- * convention: the compiler's angular transform bakes it into the `x` column and the guide renderer
- * recovers it with the identical call, so marks, spokes and rim labels stay aligned.
- */
-export declare const positionToAngle: (position: number, startAngle: number, spokeRotation: number) => number;
-
 /**
  * Position adjustment for overlapping geometries.
  *
@@ -6486,26 +5185,14 @@ export declare interface RadiusExtent {
 /** Resolves one observation's raw, type-filtered value for an aesthetic. */
 declare type RawValueReader = (observation: Observation) => DataValue;
 
-/**
- * Reads a numeric value from a layout geom's own author-named column. Returns `fallback`
- * (default `0`) when the column is absent or non-finite, so a missing or `NaN`/`Infinity` value
- * degrades to the fallback instead of corrupting geometry coordinates.
- */
-export declare function readAuthoredNumber(observation: Observation, key: VariableName, fallback?: number): number;
-
-/**
- * Reads a string value from an observation's own author-named column. The string sibling of
- * {@link readAuthoredNumber}: returns `fallback` (default `''`) when the column is absent or not a string.
- */
-export declare function readAuthoredString(observation: Observation, key: VariableName, fallback?: string): string;
-
 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 graph container top-left (with {@link LAYOUT_PADDING} already included), never panel-local coordinates.
+ * 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.
  */
 export declare interface Rect {
     x: number;
@@ -6520,28 +5207,6 @@ declare interface ReferenceLines {
     averageLine?: AverageLine;
 }
 
-/** Resolved region anchor. */
-export declare type RegionAnchor = {
-    anchorType: 'panel';
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-};
-
-/**
- * An area, expressed as a relationship to the graph.
- *
- * - `panel`: a rectangle in panel-rect fractions (`[0,1]`), top-left origin.
- */
-export declare type RegionAnchorInput = {
-    anchorType: 'panel';
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-};
-
 /**
  * A typed key-value store for looking up registered implementations by name.
  *
@@ -6571,7 +5236,9 @@ declare class Registry<K extends string, T> {
 }
 
 /**
- * Render-time context used for GraphConfig conversion.
+ * 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`).
  */
 export declare interface RendererContext {
     /** Theme used to resolve theme-dependent colors; defaults to light when omitted. */
@@ -6580,35 +5247,6 @@ export declare interface RendererContext {
     customPalettes?: CustomPalettesInput;
 }
 
-/**
- * A render-side spatial query a layout geom registers for its layer. The cursor arrives in
- * panel-local `[0, 1]` with a top-left origin — the frame the geom paints in — so it tests against
- * the geometry it drew without re-projecting. Returns the identity key under the cursor, or `null`.
- *
- * The returned `key` must equal `getStableKey(identityValue)`, the value {@link RenderHitTestIndex.byKey}
- * stored. `getStableKey` is identity for strings but normalizes other types (e.g. `Date → toISOString()`),
- * so a geom keying on a numeric/temporal column must return the normalized value or the lookup
- * silently misses.
- */
-export declare type RenderHitTester = (cursor: {
-    x: number;
-    y: number;
-}) => {
-    key: string;
-} | null;
-
-/**
- * A render-only plugin: a geom render half keyed by an existing geom name that contributes no compile
- * definition (the by-name `defineGeomRenderer('bar', …)` override). The engine recognises it
- * structurally — a render half with `geom`/`render` and no `.definition` — and skips it when seeding the
- * compile registries, so the built-in compile half keeps running; only the renderer consumes it.
- * React-free here: `render` is opaque to the engine, never called by it.
- */
-export declare interface RenderOnlyPlugin {
-    readonly geom: string;
-    readonly render: object;
-}
-
 /***************************************************************
  * Builders
  ***************************************************************/
@@ -6646,14 +5284,6 @@ declare interface ReshapeTransformInput {
     options: ReshapeOptions;
 }
 
-/**
- * Recover a plugin's compile definition: a render half carries it at `.definition`; a bare definition is
- * its own. A render-only override (a render half with no `.definition`) contributes no compile half, so it
- * resolves to `undefined`. Read structurally so the engine never imports a React type — and exported so
- * react-renderer's render-half reader reuses this one read across the package boundary.
- */
-export declare function resolveDefinition(entry: Plugin_2): CompileDefinition | undefined;
-
 /** A headline size with `'auto'` resolved away — what the renderer paints at. */
 export declare type ResolvedHeadlineSize = Exclude<HeadlineSize, 'auto'>;
 
@@ -6675,45 +5305,23 @@ export declare type ResolvedLegendDisplay = Exclude<LegendDisplay, 'auto'>;
 export declare type ResolvedLegendPosition = Exclude<LegendPosition, 'auto' | 'none'>;
 
 /**
- * A point resolved from an observation.
+ * 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.
  */
-export declare interface ResolvedObservationPoint extends ResolvedPoint {
-    geom: string;
-    measurementValue: number;
-    valueFormat: ValueFormat;
-    color: string | undefined;
-}
-
-/**
- * A point anchor projected into normalized panel space `[0, 1]²`. One convention across all
- * annotation kinds: data-space origin (y=0 at the bottom, matching `POSITION_VARIABLES.y`), so a
- * top-origin renderer flips `y` before painting.
- *
- * The measurement fields (`geom`/`measurementValue`/`valueFormat`/`color`) are present only for
- * points resolved from an observation; a panel-anchored point leaves them undefined. Kinds that read
- * them carry the narrower {@link ResolvedObservationPoint}.
- */
-export declare interface ResolvedPoint {
+export declare interface ResolvedObservationAnchor {
     x: number;
     y: number;
-    /** The geom name the anchored observation belongs to, so the renderer can offset the anchor to fit that geom's shape. */
-    geom?: string;
+    /**
+     * 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';
     /** Raw value of the y-aesthetic (or x-aesthetic when flipped), used by label formatting. */
-    measurementValue?: number;
-    /** Value format for `measurementValue`, read from the source layer — coord-system independent. */
-    valueFormat?: ValueFormat;
+    measurementValue: number;
     /** Resolved color for this observation, if any. */
-    color?: string;
-}
-
-/**
- * A region anchor projected into normalized panel space `[0, 1]²`.
- */
-export declare interface ResolvedRegion {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
+    color: string | undefined;
 }
 
 /**
@@ -6763,6 +5371,17 @@ 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.
  */
 export declare interface RichTextContent {
     type?: string;
@@ -6879,9 +5498,8 @@ declare interface ScaleAPI {
  * Compiles scale specs into render-ready CompiledScale objects.
  */
 declare class ScaleCompiler extends Stage<ScaleCompilerInput, CompiledScales> {
-    private readonly container;
     private readonly registry;
-    constructor(container: CommonContainer, registry: ScaleRegistry);
+    constructor(registry: ScaleRegistry);
     protected dependencies(input: ScaleCompilerInput): readonly unknown[];
     protected run(input: ScaleCompilerInput): CompiledScales;
     /**
@@ -6899,14 +5517,6 @@ declare class ScaleCompiler extends Stage<ScaleCompilerInput, CompiledScales> {
      * position-adjusted range (e.g. [0, 1] after fill).
      */
     private collectValues;
-    /**
-     * Maps each custom positional aesthetic a layer's geom declares to the scale its axis feeds. Only
-     * `scalar` roles need this: they bind a *new* channel the collector trains by name. An interval
-     * (`min`/`max`) role's values already reach the domain through its `yMin`/`yMax` column (via the
-     * `y` mapping below), so routing it here too would double-count. A role binding a visual channel is
-     * a misdeclaration and is ignored rather than rerouted into a position scale.
-     */
-    private resolveCustomPositionalAxes;
     /**
      * Determines which dataset variables to collect for a given aesthetic.
      *
@@ -6923,14 +5533,6 @@ declare interface ScaleCompilerInput {
     scales: ScaleSpec[];
 }
 
-/** Scale-domain constraints a geom imposes on the inferred position scales. */
-export declare interface ScaleConstraints {
-    /** Force this geom's band (x) scale to be discrete (e.g. a bar's categorical axis). */
-    discreteMainAxis?: boolean;
-    /** Anchor this geom's y scale at a zero baseline — its marks rise from 0. */
-    zeroBaseline?: boolean;
-}
-
 /**
  * Identifiers for scales. Superset of AestheticKey — includes `ySecondary`
  * which is a scale aesthetic key but NOT an aesthetic (layers still map to `y`).
@@ -6949,7 +5551,7 @@ declare type ScaledVisualAestheticKey = 'color' | 'size' | 'alpha' | 'strokeWidt
 declare type ScaleInput = ContinuousScaleInput | DiscreteScaleInput | PaletteScaleInput | DatetimeScaleInput | IdentityScaleInput | InferredScaleInput;
 
 declare class ScaleRegistry extends Registry<ScaleType, Scale> {
-    constructor(container: CommonContainer);
+    constructor();
 }
 
 /**
@@ -7144,16 +5746,23 @@ declare type SetScaleDomainParams = {
 };
 
 /**
- * Rectangle annotation. Its area is positioned by a {@link RegionAnchorInput} so it
- * re-resolves each compile (re-flows on resize, tracks data when bound).
+ * Freeform rectangle annotation. Position and size are expressed as
+ * fractions of the plot rect (0..1) so the annotation re-flows when the
+ * panel resizes.
  */
 export declare interface ShapeInput {
     id?: string;
     kind?: ShapeKind;
     /** Draw beneath the geoms (background) or on top (foreground). */
-    zOrder?: AnnotationZOrder;
-    /** The area this shape fills. */
-    region: RegionAnchorInput;
+    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;
@@ -7169,16 +5778,23 @@ export declare type ShapeKind = 'rectangle';
 export declare interface ShapeSpec {
     id: string;
     kind: ShapeKind;
-    zOrder: AnnotationZOrder;
-    region: RegionAnchor;
+    zOrder: ShapeZOrder;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
     fillColor: string;
     fillOpacity: number;
     strokeWidth: number;
     strokeColor: string | null;
 }
 
-/** Overlap tolerance, in pixels, before two sibling mini bubbles count as colliding. */
-export declare const SIBLING_OVERLAP_THRESHOLD_PX = 2;
+/**
+ * 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`).
+ */
+export declare type ShapeZOrder = 'background' | 'foreground';
 
 /**
  * Builder for the smooth stat.
@@ -7247,24 +5863,6 @@ export declare interface SourceContent {
     url?: string;
 }
 
-/**
- * The coord-agnostic hit-test shape a geom declares — how its marks are shaped, never how that shape
- * projects under a coord. The runtime pairs this shape with the chart's coord system to build a matching
- * hover index; that projection lives in one place (`build-layer-index`), so a geom never names a
- * coord-specific variant and can't mis-declare one.
- *
- * - `'buckets'` — marks bucket along an axis for nearest-position snapping (line/area crosshair).
- * - `'rects'` — marks are rectangles (bars).
- * - `'points'` — marks are discrete vertices (scatter).
- * - `'noop'` — nothing hit-testable.
- * - `'render-hit-test'` — geometry comes from a render-side layout algorithm rather than position
- *   scales, so only the renderer can hit-test it.
- *
- * Every shape but `'render-hit-test'` is derived from position scales at compile time, so the runtime
- * builds its index from the compiled data alone.
- */
-export declare type SpatialKind = 'buckets' | 'rects' | 'points' | 'noop' | 'render-hit-test';
-
 /**
  * Fully resolved spec — all fields populated, defaults applied, inferred types resolved.
  * This is what the compilation pipeline consumes.
@@ -7293,7 +5891,7 @@ export declare interface Spec {
     /** Resolved scale specs — one per aesthetic, all defaults filled, no 'inferred' types remaining. */
     scales: ScaleSpec[];
     /** Data transforms applied to `data` before layer compilation. */
-    transforms: AnyTransformInput[];
+    transforms: TransformInput[];
     /** Predicate-driven highlights with `layerIndex` normalised to `layerId` and ids assigned. */
     highlights: HighlightSpec[];
     /** Annotation overlays (difference arrows, etc.) with optional fields defaulted. */
@@ -7312,24 +5910,22 @@ export declare interface SpecInput {
     mapping: AesMapping;
     layers: LayerInput[];
     scales: ScaleInput[];
-    transforms: AnyTransformInput[];
+    transforms: TransformInput[];
     highlights: HighlightInput[];
     annotations?: AnnotationsInput;
     coords?: CoordInput;
     config: ConfigInput;
 }
 
-declare type SpecItem = LayerInput | ScaleInput | CoordInput | ConfigItem | AnyTransformInput | MappingItem | HighlightInput | AnnotationItem;
+declare type SpecItem = LayerInput | ScaleInput | CoordInput | ConfigItem | TransformInput | MappingItem | HighlightInput;
 
 /**
  * Compiles a raw compiler input or graph config into a resolved Spec.
  */
 export declare class SpecResolver {
-    private readonly container;
-    constructor(container: CommonContainer);
     /**
-     * Resolve user input into a fully defaulted {@link Spec}.
-     * Accepts either a `SpecInput` or `GraphConfig`, converting the latter before resolution.
+     * 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;
@@ -7382,12 +5978,8 @@ declare abstract class Stage<Input, Output> {
 /**
  * Base class for statistical transformations applied to layer data (e.g. binning, counting, smoothing).
  */
-export declare abstract class Stat {
-    /**
-     * The stat's name. Built-in subclasses narrow this to a `StatName` literal; the base accepts any
-     * `string` so a custom stat carries a name outside the built-in union, resolved through the registry.
-     */
-    abstract readonly type: string;
+declare abstract class Stat {
+    abstract readonly type: StatName;
     /**
      * Aesthetics this stat will compute (e.g. count computes 'y'). Used by validation to skip existence checks.
      */
@@ -7396,7 +5988,7 @@ export declare abstract class Stat {
     protected abstract computeStat(input: StatCompilerInput): CompiledStat;
 }
 
-/** Factories for the stats a layer can apply (identity, count, smooth, mean). */
+/** Factories for the statistical transforms a layer can apply (identity, count, smooth, mean). */
 export declare const stat: {
     identity: typeof identity;
     count: typeof count;
@@ -7417,7 +6009,7 @@ declare class StatCompiler {
     }): CompiledStat;
 }
 
-export declare interface StatCompilerInput {
+declare interface StatCompilerInput {
     /** The input dataset. */
     data: Dataset;
     /** The effective mapping for the layer. */
@@ -7431,11 +6023,6 @@ export declare interface StatCompilerInput {
     xScaleIsDiscrete: boolean;
 }
 
-/** A custom stat is a {@link Stat} subclass instance. Named alias for its role as a plugin. */
-export declare type StatDefinition = Stat;
-
-declare type StatDefsOf<P extends readonly Plugin_2[]> = Extract<DefsOf<P>, Stat>;
-
 /**
  * User-facing stat input — either a {@link StatName} string shorthand or an object spec.
  */
@@ -7449,13 +6036,12 @@ declare type StatInput = IdentityStatSpec | CountStatSpec | SmoothStatInput | Me
  * - `'smooth'` — Fit a regression curve through `(x, y)` and emit the fitted points
  * - `'mean'` — Reduce the dataset to a single observation holding the mean of `y`
  */
-export declare type StatName = 'identity' | 'count' | 'smooth' | 'mean';
+declare type StatName = 'identity' | 'count' | 'smooth' | 'mean';
 
 /**
- * Stat implementations keyed by name. Built-ins are registered in the constructor; custom stats are
- * appended via `createRegistries`, so the key is a plain `string` rather than the built-in `StatName`.
+ * Built-in stat implementations keyed by {@link StatName}.
  */
-declare class StatRegistry extends Registry<string, Stat> {
+declare class StatRegistry extends Registry<StatName, Stat> {
     constructor();
 }
 
@@ -7465,29 +6051,26 @@ declare class StatRegistry extends Registry<string, Stat> {
 declare type StatSpec = IdentityStatSpec | CountStatSpec | SmoothStatSpec | MeanStatSpec;
 
 /**
- * Sticker annotation: a built-in emoji-like image positioned by a {@link PointAnchorInput}.
+ * Sticker annotation: a built-in emoji-like image pinned to a single observation.
  */
-export declare interface StickerAnnotationInput {
+declare interface StickerAnnotationInput {
     id?: string;
-    at: PointAnchorInput;
+    anchor: ObservationAnchorInput;
     sticker: StickerId;
 }
 
-export declare interface StickerAnnotationSpec {
+declare interface StickerAnnotationSpec {
     id: string;
-    at: PointAnchor;
+    anchor: ObservationAnchor;
     sticker: StickerId;
 }
 
-export declare type StickerId = string;
+declare type StickerId = 'rocket' | 'clapping-hands' | 'thumbs-up' | 'thumbs-down' | 'grinning-face';
 
 /**
  * Computes per-layer aggregates (stack totals, grand totals) consumed directly by the renderer.
- * Which summaries a layer carries is gated by the geom def's declared `summaries`, not its name.
  */
 declare class SummariseCompiler extends PerLayerStage<SummariseCompilerInput> {
-    private readonly container;
-    constructor(container: CommonContainer);
     protected dependencies(): readonly unknown[];
     protected compileLayer(layer: CompiledLayer): CompiledLayer;
 }
@@ -7496,6 +6079,21 @@ declare interface SummariseCompilerInput {
     layers: CompiledLayer[];
 }
 
+/**
+ * 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.
+ *
+ * - `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.
+ */
+export declare type SwatchShape = 'square' | 'line' | 'circle' | 'area' | 'slice';
+
 declare type Table = internal.ColumnTable;
 
 declare interface TableOptions {
@@ -7503,14 +6101,11 @@ declare interface TableOptions {
     tableColumnRatios?: Record<string, number>;
 }
 
-/** A full turn in radians. */
-export declare const TAU: 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
+     * 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.
      */
     dateFormat?: string;
@@ -7520,15 +6115,17 @@ declare interface TemporalValueFormat {
 export declare type TextAnnotationBackgroundColorStyle = 'fade' | 'opaque';
 
 /**
- * Rich-text annotation. Its top-left corner is positioned by a {@link PointAnchorInput};
- * `width` is a fraction of the plot rect. Height is intrinsic to the rendered content.
+ * Freeform rich-text annotation. Position and width are fractions of the plot
+ * rect (0..1). Height is intrinsic to the rendered content.
  */
 export declare interface TextAnnotationInput {
     id?: string;
     /** Rich-text body to render. */
     content: RichTextContent;
-    /** The annotation's top-left corner. */
-    at: PointAnchorInput;
+    /** 0..1 of plot width — top-left corner. */
+    x: number;
+    /** 0..1 of plot height — top-left corner. */
+    y: number;
     /** 0..1 of plot width. */
     width: number;
     /** null falls back to a transparent background. */
@@ -7541,7 +6138,8 @@ export declare interface TextAnnotationInput {
 export declare interface TextAnnotationSpec {
     id: string;
     content: RichTextContent;
-    at: PointAnchor;
+    x: number;
+    y: number;
     width: number;
     backgroundColor: string | null;
     backgroundColorStyle: TextAnnotationBackgroundColorStyle;
@@ -7570,11 +6168,6 @@ export declare interface TooltipContent {
     rows: TooltipRow[];
 }
 
-declare type TooltipContract = ReadonlyArray<{
-    readonly key: string;
-    readonly aes: string;
-}>;
-
 /**
  * One row in the chart tooltip popover. Pure projection of a `HoverHit` against the layer's
  * compiled scales.
@@ -7585,8 +6178,8 @@ export declare interface TooltipRow {
      * has no color scale at all — the popover suppresses the swatch cell in that edge case.
      */
     swatchColor: string | null;
-    /** The row's source geom — the renderer reads its swatch shape off the geom's render contract. */
-    geom: string;
+    /** Visual signature of the row's source geom. Drives the swatch shape. */
+    swatchShape: SwatchShape;
     /** Resolved stroke style for line/area swatches. Falls back to `'solid'` when not derived. */
     swatchLineType: LineStyleType;
     /** Row label — color value (multi-series) or layer's Y-axis title (single-series). */
@@ -7599,23 +6192,6 @@ export declare interface TooltipRow {
     key: string;
 }
 
-/**
- * Maps a panel-local pixel point to the data-space cursor the hover engine queries with: x
- * normalized to the panel width, y normalized and flipped to bottom-origin (matching
- * `POSITION_VARIABLES.y`). Polar queries take the same full-panel cursor — the engine applies the
- * inscribed-square and aspect-ratio correction internally.
- *
- * Both the pointer tracker (normalizing the live cursor) and callout hit regions (normalizing a
- * marker pixel) go through this, so a hit region resolves to the same observation the cursor would.
- */
-export declare const toPanelCursor: (point: {
-    x: number;
-    y: number;
-}, panelSize: {
-    width: number;
-    height: number;
-}) => HoverCursor;
-
 /** Formats a normalized [0,1] value as a CSS percentage string for SVG positioning. */
 export declare const toPercent: (value: number) => string;
 
@@ -7641,11 +6217,6 @@ export declare const transform: {
     constant: typeof constant;
 };
 
-/** Options for a custom transform builder method (transforms carry no declared params surface yet). */
-declare interface TransformBuilderOptions {
-    options?: Record<string, unknown>;
-}
-
 /**
  * Applies transforms to a dataset via registered strategies. Cache partitioned by dataset
  * reference so the spec-level and per-layer call sites don't thrash each other.
@@ -7660,51 +6231,30 @@ declare class TransformCompiler extends Stage<TransformCompilerInput, Dataset> {
 
 declare interface TransformCompilerInput {
     data: Dataset;
-    transforms: AnyTransformInput[];
+    transforms: TransformInput[];
 }
 
-/** A custom transform is a {@link TransformStrategy}. Named alias for its role as a plugin. */
-export declare type TransformDefinition = TransformStrategy;
-
-declare type TransformDefsOf<P extends readonly Plugin_2[]> = Extract<DefsOf<P>, {
-    readonly transformType: string;
-}>;
-
-export declare type TransformInput = ReshapeTransformInput | FilterTransformInput | SortTransformInput | AggregateTransformInput | ConstantTransformInput;
+/***************************************************************
+ * Transform Input
+ ***************************************************************/
+declare type TransformInput = ReshapeTransformInput | FilterTransformInput | SortTransformInput | AggregateTransformInput | ConstantTransformInput;
 
 /**
- * Transform implementations keyed by name. Built-ins are registered in the constructor; custom
- * transforms are appended via `createRegistries`, so the key is a plain `string` rather than the
- * built-in `TransformType`.
+ * Built-in transform implementations keyed by transform type.
  */
-declare class TransformRegistry extends Registry<string, TransformStrategy> {
+declare class TransformRegistry extends Registry<TransformType, TransformStrategy> {
     constructor();
 }
 
 /**
  * Strategy interface for compiling a specific transform type.
  */
-export declare interface TransformStrategy {
-    /**
-     * The transform's name. Built-in transforms narrow this to a `TransformType` literal; the type
-     * accepts any `string` so a custom transform carries a name outside the built-in union, resolved
-     * through the registry.
-     */
-    readonly transformType: string;
-    apply: (data: Dataset, transform: AnyTransformInput) => Dataset;
-    /**
-     * Variable names this transform adds to the dataset (e.g. a reshape's key column or a constant's
-     * variable). Declared so consumers can discover introduced columns without branching on the type.
-     */
-    getIntroducedVariables?: (transform: AnyTransformInput) => VariableName[];
+declare interface TransformStrategy {
+    readonly transformType: TransformType;
+    apply: (data: Dataset, transform: TransformInput) => Dataset;
 }
 
-/**
- * The built-in transform names. Hand-written (not derived from {@link TransformInput}) and
- * cross-checked against the registry's built-in tuple via `satisfies` in `transform.registry.ts`, so
- * it stays the closed built-in union.
- */
-export declare type TransformType = 'reshape' | 'filter' | 'sort' | 'aggregate' | 'constant';
+declare type TransformType = TransformInput['transformType'];
 
 declare type TrendlineType = 'linear' | 'loess' | 'exponential' | 'logarithmic' | 'quadratic' | 'power' | 'polynomial';
 
@@ -7719,39 +6269,29 @@ declare interface UndoRedoResult {
 }
 
 /**
- * Inverse of {@link polarToUnit}: recovers `(angle, radius)` from a point in the same y-up unit disk.
- * `atan2(x, y)` yields a clockwise-from-12 angle with no sign flip because `y` is up; `hypot` recovers
- * the radius.
- */
-export declare const unitToPolar: (x: number, y: number) => {
-    angle: number;
-    radius: number;
-};
-
-/**
- * Stable code for a failure the caller can fix by editing their {@link Spec} or {@link Data}.
+ * Shared validation types used across compiler stages.
+ *
+ * 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.
  */
-export declare type UserInputErrorCode = 'UNKNOWN_VARIABLE' | 'INCOMPATIBLE_TYPE' | 'INCOMPATIBLE_SCALE_DOMAIN' | 'MISSING_AESTHETIC' | 'UNDECLARED_AESTHETIC' | 'INVALID_RULE_MAPPING' | 'UNSUPPORTED_COORD' | 'MISSING_STAT_VARIABLE' | 'CONFLICTING_STAT_MAPPING' | 'UNKNOWN_REGISTERED_TYPE' | 'DUPLICATE_REGISTERED_TYPE' | 'MISSING_GEOM_RENDERER' | 'RENDER_HIT_TEST_IDENTITY' | 'MISSING_RENDER_HIT_TEST' | 'CONFLICTING_RENDER_HIT_TEST' | 'OVERLAY_REQUIRES_RENDER_HIT_TEST' | 'PALETTE_NOT_FOUND' | 'LAYER_INDEX_OUT_OF_RANGE' | 'INVALID_HIGHLIGHT_OPERATOR' | 'UNRESOLVABLE_COLOR' | 'UNSUPPORTED_GRAPH_TYPE' | 'INVALID_DATA_SHAPE' | 'EMPTY_DATASET' | 'DATA_LABEL_PLACEMENT_COERCED' | 'DATA_LABELS_UNSUPPORTED' | 'DATA_LABEL_SETTING_IGNORED';
+declare type ValidationCode = 'UNKNOWN_VARIABLE' | 'INCOMPATIBLE_TYPE' | 'MISSING_AESTHETIC' | 'INVALID_RULE_MAPPING' | 'INVALID_RULE_COORD';
 
-/**
- * One user-input problem authored once and used three ways: pushed onto the collector as a warning
- * ({@link DiagnosticsCollector.addWarning}) or a batched error
- * ({@link DiagnosticsCollector.addError}), or thrown as a {@link UserInputError}. `kind` is
- * never restated — it is implied by the partitioned `code`, so it cannot drift from it.
- */
-export declare interface UserInputIssue extends DiagnosticDetails {
-    code: UserInputErrorCode;
+declare interface ValidationIssue {
+    code: ValidationCode;
+    message: string;
+    layerId?: string;
+    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 engine never formats values itself: it tags each guide/legend/headline figure with a
- * `ValueFormat` (e.g. `CompiledAxisGuide.valueFormat`), and the renderer materializes it via
- * `createValueFormatter`. A descriptor is inert until paired with a locale and number-format config,
- * so renderers hold these and switch on the `type` discriminant.
- *
- * `type` selects the formatter. Rendered examples (en-US, default number config):
+ * 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).
@@ -7771,7 +6311,7 @@ export declare interface UserInputIssue extends DiagnosticDetails {
  * - `lookup` — resolved per observation; see {@link LookupValueFormat}.
  *
  * The `isXValueFormat` guards (e.g. {@link isLookupValueFormat}, {@link isTemporalValueFormat}) narrow
- * a descriptor to a family without naming every member kind.
+ * a held descriptor to a family without listing every member kind by hand.
  */
 export declare type ValueFormat = ExplicitValueFormat | LookupValueFormat;
 
@@ -7787,7 +6327,11 @@ export declare interface ValueFormatterFactoryParams<T = ValueFormat> {
     valueFormat: T;
     locale: Locale;
     numberFormat: NumberFormatConfig;
-    /** Per-call overrides merged onto the formatter's default Intl options (e.g. compact axis dates). */
+    /**
+     * 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;
 }
 
@@ -7806,14 +6350,6 @@ declare type Variable = {
     valueFormat?: ValueFormat;
 };
 
-/**
- * Friendly display labels for variables, keyed by variable name. Sourced from
- * `Data.columns[i].label` for raw columns; consumers may extend this map to
- * provide labels for transform-produced columns. Only present entries are
- * stored — absent variables fall back to the raw variable name at the guide.
- */
-declare type VariableLabels = Record<string, string>;
-
 /** A map of variable names to their type and values. */
 declare type VariableMap = Record<VariableName, Variable>;
 
@@ -7827,9 +6363,6 @@ declare interface VariableMapping {
 declare type VariableMetadata = Record<VariableName, {
     type: DataType;
     valueFormat: ValueFormat;
-    constant?: {
-        value: DataValue;
-    };
 }>;
 
 /** A type alias for variable names. */
@@ -7865,7 +6398,7 @@ export declare type VariablePredicate = {
     range: [DataValue, DataValue];
 };
 
-/** Internal variables holding each observation's resolved visual values (color, size, etc.). */
+/** Internal column names holding each observation's resolved visual channels (color, size, etc.). */
 export declare const VISUAL_VARIABLES: {
     readonly color: string;
     readonly size: string;
@@ -7894,54 +6427,6 @@ declare interface VisualMapperCompilerInput {
  */
 declare type VisualScalesSlice = Pick<CompiledScales, ScaledVisualAestheticKey>;
 
-/**
- * The serialisable, normalised form of any error or warning. Every failure the engine surfaces —
- * fatal errors, batched validation problems, and advisory warnings — is a `VizDiagnostic`; there is
- * no second shape. Attachable to a bug report wholesale, and the unit codegen reads.
- */
-export declare interface VizDiagnostic extends DiagnosticDetails {
-    severity: VizErrorSeverity;
-    kind: VizErrorKind;
-    code: VizErrorCode;
-}
-
-/**
- * Platform-independent base for every error the engine throws.
- */
-declare abstract class VizError extends Error {
-    readonly code: VizErrorCode;
-    readonly context?: DiagnosticContext;
-    readonly suggestion?: string;
-    /** Whose fault the failure is. Fixed by the concrete subclass. */
-    abstract readonly kind: VizErrorKind;
-    constructor(options: VizErrorOptions);
-}
-
-/**
- * Every error code, partitioned by fault. A {@link UserInputError} only accepts a
- * {@link UserInputErrorCode}; an {@link InternalError} only accepts an {@link InternalErrorCode}.
- */
-export declare type VizErrorCode = UserInputErrorCode | InternalErrorCode;
-
-/** Whose fault a failure is, and whether the caller can fix it. */
-export declare type VizErrorKind = 'user-input' | 'internal';
-
-/**
- * Construction options shared by every {@link VizError}: the {@link DiagnosticDetails} core (message,
- * context, suggestion) plus a partitioned `code` and an optional `cause`. `Code` is partitioned per
- * subclass, so the compiler rejects a code from the wrong fault partition (e.g. an `InternalErrorCode`
- * on a {@link UserInputError}).
- */
-declare interface VizErrorOptions<Code extends VizErrorCode = VizErrorCode> extends DiagnosticDetails {
-    /** Stable, machine-readable code. The primary contract for programmatic consumers. */
-    code: Code;
-    /** The underlying error, if this wraps one. */
-    cause?: unknown;
-}
-
-/** Whether a diagnostic is fatal (`error`) or advisory (`warning`). */
-export declare type VizErrorSeverity = 'error' | 'warning';
-
 /**
  * X-axis configuration (after defaults applied)
  */