@graphysdk/viz-engine 0.0.1-plugins.0 → 0.0.1-plugins.10

package/dist/index.d.ts

@@ -1,24 +1,44 @@
 import { internal } from 'arquero';
 
+/**
+ * The aesthetic mapping: data columns (or constants) bound to visual channels. Seeded globally by
+ * `createSpec({...})` and overridable per layer via `geom.x({ aes })`. Every field is optional; a channel
+ * left unset is simply not driven by data. Each channel binds to the like-named scale (e.g. `color` →
+ * `scale.color.*`, `size` → `scale.size.*`); position channels additionally require `scale.x()`/`scale.y()`
+ * to be declared (they are NOT auto-inferred).
+ */
 export declare interface AesMapping {
+    /** Horizontal position. Binds to `scale.x`. Categorical/temporal x needs `scale.x.discrete()`. */
     x?: AestheticValue;
+    /** Vertical position. Binds to `scale.y` (or `scale.ySecondary` when the layer sets `yScaleType: 'secondary'`). */
     y?: AestheticValue;
+    /** Text drawn on the observation (data labels, slice labels). Binds to no scale; rendered as-is. */
     label?: AestheticValue;
+    /** Series/category color. Binds to `scale.color.*`; mapping a column splits the geom into series and shows a legend. */
     color?: AestheticValue;
+    /** Mark size — point radius / bubble area. Binds to `scale.size.continuous({ range })`. */
     size?: AestheticValue;
+    /** Per-observation opacity in `[0,1]` after scaling. Binds to `scale.alpha.*`. */
     alpha?: AestheticValue;
+    /**
+     * Explicit grouping key for which observations form one connected mark (one line/area). Defaults to the
+     * `color` column when unset; set it to split lines/areas without colouring them differently.
+     */
     group?: AestheticValue;
+    /** Stroke thickness as a data-driven channel. Binds to `scale.strokeWidth.*`; for a fixed width use line `params.lineWidth`. */
     strokeWidth?: AestheticValue;
+    /** Dash style (`'solid'`/`'dashed'`/`'dotted'`). Binds to `scale.lineType.discrete({ domain, range })`; great for actual-vs-forecast lines. */
     lineType?: AestheticValue;
 }
 
+/** The set of built-in aesthetic channel names — the keys of {@link AesMapping}. */
 export declare type AestheticKey = keyof AesMapping;
 
 /**
- * Aesthetic value can be:
- * - string (shorthand for { variable: string })
- * - { variable: string } (explicit variable mapping)
- * - { value: DataValue } (constant value applied to every observation)
+ * How a single aesthetic channel is fed. One of three forms:
+ * - a bare string (`'revenue'`) — shorthand for `{ variable: 'revenue' }`, the common case;
+ * - `{ variable: 'revenue' }` — the same column binding, written explicitly;
+ * - `{ value: 2500 }` — a constant {@link ValueMapping} applied to every observation.
  */
 declare type AestheticValue = string | VariableMapping | ValueMapping;
 
@@ -27,22 +47,28 @@ declare function aggregate(options: AggregateOptions): AggregateTransformInput;
 /***************************************************************
  * Aggregate Transform
  ***************************************************************/
+/** A single group-wise reduction applied by `transform.aggregate`. */
 declare interface AggregateOperation {
-    /** The aggregation function to apply. */
+    /** Reduction to apply: `'count'` | `'sum'` | `'mean'` | `'median'` | `'mode'` | `'min'` | `'max'`. */
     op: AggregationFunction;
-    /** The variable to aggregate. */
+    /** The variable to reduce within each group. */
     variableName: VariableName;
-    /** The name of the output variable. */
+    /** Name of the output variable holding the reduced value. */
     as: VariableName;
 }
 
+/**
+ * Options for `transform.aggregate` — groups observations by `groupby`, then reduces each group
+ * to one observation via `operations`. The idiom for pre-summarizing data (e.g. sum revenue per region).
+ */
 declare interface AggregateOptions {
-    /** Variables to group by before aggregating. */
+    /** Variables to group by; one output observation is produced per distinct combination. */
     groupby: VariableName[];
-    /** Aggregation operations to apply per group. */
+    /** One or more reductions to compute per group. */
     operations: AggregateOperation[];
 }
 
+/** Group-and-reduce transform produced by `transform.aggregate`. */
 declare interface AggregateTransformInput {
     type: 'transform';
     transformType: 'aggregate';
@@ -82,11 +108,63 @@ declare interface AnchorSegment {
     direction: 'positive' | 'negative';
 }
 
+/**
+ * The angular span of an arc/wedge in a polar coord, in **radians** (0 = straight up, increasing
+ * clockwise — the d3-arc convention). Either endpoint is `null` when the observation declares no x
+ * interval. Returned by {@link getAngleExtent}.
+ */
 export declare interface AngleExtent {
     startAngle: NumericDataValue;
     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.
+ *
+ * Anchoring differs per kind: only {@link annotation.differenceArrow} snaps to DATA (two observations);
+ * `shape`, `text`, and `freeformArrow` position in panel fractions (`[0,1]`, top-left origin). `sticker`,
+ * `pinnedNumber`, and `comment` compile but have NO painter in `@graphysdk/react-renderer` (editor-only) —
+ * avoid them when authoring for the React renderer. For a data-anchored callout/band beyond a difference
+ * arrow, register a custom kind via `createGraphyBuilder({ annotations })`; its `annotation` builder adds
+ * one method per registered kind alongside these built-ins.
+ *
+ * @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({ 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 — the only built-in kind that snaps to data. */
+    differenceArrow(input: DifferenceArrowInput): AnnotationItem;
+    /** A shaded box positioned in panel fractions (`[0,1]`); does not snap to a data value. */
+    shape(input: ShapeInput): AnnotationItem;
+    /** A free-standing arrow with endpoints in panel fractions (`[0,1]`); does not snap to a data value. */
+    freeformArrow(input: FreeformArrowInput): AnnotationItem;
+    /** A free-standing rich-text label positioned in panel fractions (`[0,1]`); does not snap to a data value. */
+    text(input: TextAnnotationInput): 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;
+};
+
 /**
  * The compile-half definition of a custom annotation kind (ADR-035).
  *
@@ -95,9 +173,11 @@ export declare interface AngleExtent {
  * params })` from `TParams`, merge `defaultParams`, and enforce the optional coordinate arity. The
  * render-half `draw` lives in the renderer and binds to this definition by import (`defineAnnotationRenderer`).
  */
-/** Optional coordinate-count guardrail enforced by the builder; unbounded when omitted. */
-declare interface AnnotationArity {
+/** Allowed coordinate count for an annotation kind; each bound is inclusive, unbounded when omitted. */
+export declare interface AnnotationArity {
+    /** Minimum coordinates required. */
     min?: number;
+    /** Maximum coordinates allowed. */
     max?: number;
 }
 
@@ -142,18 +222,59 @@ declare interface AnnotationDataPoint {
     rowValue?: DataValue;
 }
 
-declare interface AnnotationDef<TParams extends object = object, TType extends string = string> {
+/**
+ * The compile-half definition produced by {@link defineAnnotation}. Pass an array of these to
+ * `createGraphyBuilder({ annotations })` to get a typed `annotation.<type>(...)` spec method; the
+ * render-half `draw` binds to it by import in `@graphysdk/react-renderer`.
+ */
+export declare interface AnnotationDef<TParams extends object = object, TType extends string = string> {
+    /** The registered kind name; keys the `annotation.<type>(...)` builder method and the render-side `draw`. */
     type: TType;
     /** Carrier that lets the builder recover `TParams` and merge defaults before a param reaches `draw`. */
     defaultParams: TParams;
+    /** Coordinate-count guardrail enforced by the builder; unbounded when omitted. */
     coordinates?: AnnotationArity;
 }
 
-/** Pipeable spec item produced by the registration-typed `annotation.<kind>(...)` builder. */
-declare interface AnnotationItem {
+/**
+ * Pipeable spec item produced by an `annotation.*` builder. `kind` routes the carried input to the
+ * matching {@link AnnotationsInput} field when the item is folded onto a spec by `createSpec`/`pipe`:
+ * each built-in kind targets its like-named field, and `'custom'` carries a registered
+ * {@link CustomAnnotationInput} onto `annotations.custom`.
+ */
+export declare type AnnotationItem = {
+    type: 'annotation';
+    kind: 'differenceArrow';
+    annotation: DifferenceArrowInput;
+} | {
+    type: 'annotation';
+    kind: 'shape';
+    annotation: ShapeInput;
+} | {
+    type: 'annotation';
+    kind: 'freeformArrow';
+    annotation: FreeformArrowInput;
+} | {
+    type: 'annotation';
+    kind: 'text';
+    annotation: TextAnnotationInput;
+} | {
+    type: 'annotation';
+    kind: 'sticker';
+    annotation: StickerAnnotationInput;
+} | {
+    type: 'annotation';
+    kind: 'pinnedNumber';
+    annotation: PinnedNumberAnnotationInput;
+} | {
+    type: 'annotation';
+    kind: 'comment';
+    annotation: CommentAnnotationInput;
+} | {
     type: 'annotation';
+    kind: 'custom';
     annotation: CustomAnnotationInput;
-}
+};
 
 /** Recovers an annotation definition's params type — carried structurally by its `defaultParams`. */
 declare type AnnotationParamsOf<Definition> = Definition extends AnnotationDef<infer TParams> ? TParams : never;
@@ -182,17 +303,38 @@ declare interface AnnotationsCompilerInput {
     scales: CompiledScales;
 }
 
+/**
+ * Non-data marks layered onto the panel, set as the `annotations` field on a spec. Each field holds a
+ * different built-in kind.
+ *
+ * Anchoring differs per field and is the deciding detail: only `differenceArrows` snap to DATA (two
+ * observations). `shapes`, `textAnnotations` and `freeformArrows` position in panel fractions (`[0,1]`,
+ * top-left origin) — they re-flow on resize but do NOT snap to a data value. For a data-anchored callout,
+ * band, or marker beyond a difference arrow, author a `custom` annotation.
+ *
+ * `stickers`, `pinnedNumbers` and `comments` COMPILE but have no painter in `@graphysdk/react-renderer`
+ * (they draw only in the editor's legacy engine) — don't use them when authoring for the React renderer.
+ */
 export declare interface AnnotationsInput {
+    /** Labelled deltas between two data observations. The only built-in kind that anchors to data. */
     differenceArrows?: DifferenceArrowInput[];
+    /** Shaded boxes positioned in panel fractions (`[0,1]`), not data values. */
     shapes?: ShapeInput[];
+    /** Free-standing arrows positioned in panel fractions (`[0,1]`), not data values. */
     freeformArrows?: FreeformArrowInput[];
+    /** Free-standing rich-text labels positioned in panel fractions (`[0,1]`), not data values. */
     textAnnotations?: TextAnnotationInput[];
+    /** Compiles but has NO painter in `@graphysdk/react-renderer` (editor-only). Avoid here. */
     stickers?: StickerAnnotationInput[];
+    /** Compiles but has NO painter in `@graphysdk/react-renderer` (editor-only). Avoid here. */
     pinnedNumbers?: PinnedNumberAnnotationInput[];
+    /** Compiles but has NO painter in `@graphysdk/react-renderer` (editor-only). Avoid here. */
     comments?: CommentAnnotationInput[];
+    /** Registered custom-annotation instances; the data-anchorable escape hatch when no built-in fits. */
     custom?: CustomAnnotationInput[];
 }
 
+/** Resolved form of {@link AnnotationsInput} — every field present, each entry defaulted. */
 export declare interface AnnotationsSpec {
     differenceArrows: DifferenceArrowSpec[];
     shapes: ShapeSpec[];
@@ -266,11 +408,20 @@ export declare interface AppearanceSpec {
      */
     cornerRadius: number;
     /**
+     * How non-matched observations are de-emphasised when a highlight is active.
+     * See {@link HighlightStyle}: `'dim'` lowers opacity, `'desaturate'` greys them out.
      * @default 'dim'
      */
     highlightStyle: HighlightStyle;
 }
 
+/**
+ * Area marks — a line with the region below it filled. Same render knobs as line ({@link AreaGeomParams}).
+ * Use `position: 'stack'` for a stacked area chart or `'fill'` for a 100%-stacked one.
+ *
+ * @example
+ * pipe(createSpec({ x: 'month', y: 'sales', color: 'region' }), geom.area({ position: 'stack' }), scale.x(), scale.y(), scale.color.palette());
+ */
 declare function area(options?: GeomOptions<'area'>): LayerInputOf<'area'>;
 
 /**
@@ -291,21 +442,37 @@ declare class AreaGeom extends Geom {
 }
 
 /**
- * Area-specific parameters (same rendering knobs as line, but fills under the curve)
+ * Render parameters for `geom.area` — same knobs as {@link LineGeomParams}, but the region below the curve
+ * is filled. Passed under `params`.
  */
 export declare interface AreaGeomParams {
+    /**
+     * Outline stroke width in pixels, or `'auto'` to let the theme pick a width.
+     * @default 'auto'
+     */
     lineWidth: number | 'auto';
+    /**
+     * Interpolation method between points: `'linear'` for straight segments, `'catmull-rom'` for a smooth spline.
+     * @default 'linear'
+     */
     interpolate: InterpolateType;
+    /**
+     * How to handle missing (`null`) y-values: `'zero'` drops to zero, `'gap'` breaks the area, `'connect'`
+     * bridges across the gap.
+     * @default 'zero'
+     */
     missingValues: MissingValuesType;
 }
 
+/** An arrow endpoint as a panel fraction (`[0,1]`, top-left origin). */
 export declare interface ArrowEndpoint {
-    /** 0..1 of plot width. */
+    /** `[0,1]` of panel width (0 = left). */
     x: number;
-    /** 0..1 of plot height. */
+    /** `[0,1]` of panel height (0 = top). */
     y: number;
 }
 
+/** Arrowhead at an endpoint: `'none'` (bare line) or `'line-arrow'` (drawn head). */
 export declare type ArrowheadStyle = 'none' | 'line-arrow';
 
 export declare type ArrowLineStyle = 'solid' | 'dashed';
@@ -338,8 +505,11 @@ declare interface Axes {
  * Groups all axis-related settings per axis.
  */
 declare interface AxesConfig {
+    /** Configuration for the horizontal (x) axis. */
     x: XAxisConfig;
+    /** Configuration for the primary vertical (y) axis. */
     y: YAxisConfig;
+    /** Configuration for the secondary y axis, present only on dual-axis charts. */
     ySecondary?: YAxisConfig;
 }
 
@@ -415,7 +585,9 @@ export declare interface AxisTickCandidate {
  * Configuration for a single axis's ticks
  */
 declare interface AxisTicksConfig {
+    /** Whether tick marks and their labels are drawn for this axis. */
     isVisible: boolean;
+    /** Which ticks to label — see {@link AxisLabelMode} (`'auto'` = all, `'edges'` = first/last only). */
     mode: AxisLabelMode;
 }
 
@@ -446,6 +618,14 @@ export declare type BackgroundSpec = {
     color?: string;
 };
 
+/**
+ * Bar/column marks. Drives most categorical charts: plain, stacked (`position: 'stack'`), grouped
+ * (`'dodge'`), 100%-stacked (`'fill'`), horizontal (add `coord.flip()`), and pie/donut (`position: 'fill'`
+ * inside `coord.polar({ theta: 'y' })`). No render `params`.
+ *
+ * @example
+ * pipe(createSpec({ x: 'quarter', y: 'sales', color: 'region' }), geom.bar({ position: 'stack' }), scale.x(), scale.y(), scale.color.palette());
+ */
 declare function bar(options?: GeomOptions<'bar'>): LayerInputOf<'bar'>;
 
 /**
@@ -496,27 +676,68 @@ declare interface BarOptions {
 }
 
 /**
- * Base params shared by all coordinate systems
+ * Params shared by every coordinate system. Axis limits clamp the displayed range
+ * after scaling.
  */
 declare interface BaseCoordParams {
     /**
-     * Limits for x-axis [min, max]
+     * Fixed x-axis range as `[min, max]` in data units, or `null` to auto-fit from data.
+     * @default null
      */
     xLimits: [number, number] | null;
     /**
-     * Limits for y-axis [min, max]
+     * Fixed y-axis range as `[min, max]` in data units, or `null` to auto-fit from data.
+     * @default null
      */
     yLimits: [number, number] | null;
 }
 
+/**
+ * Options accepted by every `geom.*` builder. All fields are optional; each builder fills defaults during
+ * resolution. The generic `T` is the per-geom `params` shape so `geom.line` accepts {@link LineGeomParams}
+ * while `geom.bar` accepts none.
+ */
 declare interface BaseGeomOptions<T extends GeomParams> {
+    /**
+     * Layer-level aesthetic overrides, shallow-merged OVER the spec-level mapping for this layer only.
+     * The place to retarget a channel per layer in a combo (`geom.line({ aes: { y: 'margin' } })`) or to pin a
+     * constant (`aes: { y: { value: 2500 } }` for a reference line).
+     */
     aes?: AesMapping;
-    stat?: StatName | StatInput;
+    /**
+     * Statistical transform applied to this layer's data before positioning. `'identity'` (default) plots rows
+     * as-is; `'count'` tallies observations per x; `stat.mean()` collapses to a single mean-of-`y` observation
+     * (average line); `stat.smooth({ method })` fits a regression curve (trendline).
+     * @default 'identity'
+     */
+    stat?: StatLayerInput | StatLayerInput[];
+    /**
+     * How sibling marks sharing an x position are arranged. `'identity'` overlaps them; `'stack'` stacks by
+     * `color`; `'dodge'` places them side by side; `'fill'` stacks then normalises each column to 100% (also
+     * the basis of pie/donut under `coord.polar`). Default is per-geom: `area` → `'stack'`, `bar` → `'dodge'`,
+     * `point`/`line`/`rule` → `'identity'`.
+     */
     position?: PositionType;
+    /**
+     * Which Y axis this layer binds to. `'secondary'` puts it on the right-hand axis for dual-axis combos
+     * (pair with `scale.ySecondary()`); the layer still maps to the `y` channel.
+     * @default 'primary'
+     */
     yScaleType?: YScaleType;
+    /** Geom-specific render knobs — static styling only (widths, colors, interpolation), never data channels. */
     params?: Partial<T>;
+    /**
+     * Ordered transforms applied to this layer's view of the data, on top of the spec-level transforms. Use
+     * when this geom needs a different data shape than its siblings.
+     */
     transforms?: TransformInput[];
+    /**
+     * When `false`, the layer is excluded from hover hit-detection — set it on non-data overlays like
+     * average and trend lines so they don't steal the tooltip. Defaults to `true` for all geoms except `rule`,
+     * which defaults to `false`.
+     */
     interactive?: boolean;
+    /** Per-observation value labels drawn on the marks. Off by default; see {@link DataLabelsInput}. */
     dataLabels?: DataLabelsInput;
 }
 
@@ -708,6 +929,12 @@ declare type BuiltinParams<G extends string> = G extends GeomName ? Extract<Buil
     geom: G;
 }>['params'] : Record<string, unknown>;
 
+/***************************************************************
+ * Transform Input
+ ***************************************************************/
+/** The built-in transforms; their `transformType` literals form the closed {@link TransformType}. */
+declare type BuiltinTransformInput = ReshapeTransformInput | FilterTransformInput | SortTransformInput | AggregateTransformInput | ConstantTransformInput;
+
 /**
  * Caching decorator for any TextMeasurer implementation.
  *
@@ -851,6 +1078,17 @@ export declare interface CommandApplyResult {
     readonly revert: Command;
 }
 
+/**
+ * Descriptor that knows how to deserialize a specific command type.
+ * Each concrete command co-locates its descriptor alongside the command class.
+ *
+ * Serialization is handled uniformly by the registry via `Command.params`.
+ */
+declare interface CommandDescriptor<TParams extends Record<string, unknown> = Record<string, unknown>> {
+    readonly type: string;
+    deserialize: (params: TParams, metadata: CommandMetadata) => Command;
+}
+
 /**
  * Unique identifier for commands.
  */
@@ -870,6 +1108,33 @@ export declare interface CommandMetadata {
     readonly author: string;
 }
 
+/**
+ * Central registry mapping command types to their serialization descriptors.
+ */
+export declare class CommandRegistry {
+    private readonly descriptors;
+    /**
+     * Register a command descriptor. Throws if the type is already registered.
+     */
+    register<TParams extends Record<string, unknown>>(descriptor: CommandDescriptor<TParams>): void;
+    /**
+     * Serialize a command to its wire format.
+     */
+    serialize(command: Command): SerializedCommand;
+    /**
+     * Deserialize a command from its wire format.
+     */
+    deserialize(data: SerializedCommand): Command;
+    /**
+     * Get all registered command type names.
+     */
+    getRegisteredTypes(): string[];
+    private getDescriptor;
+}
+
+/** Default singleton registry instance. */
+export declare const commandRegistry: CommandRegistry;
+
 /**
  * Event types emitted by CommandStackManager.
  */
@@ -989,6 +1254,9 @@ export declare interface CommandStackSnapshot {
  * Comment annotation: a marker dot pinned to a single observation, carrying
  * rich-text content. The renderer's mini view shows a truncated comment; hover
  * reveals the full text.
+ *
+ * NO PAINTER in `@graphysdk/react-renderer` — this compiles but never draws there (it renders only in
+ * the editor's legacy engine). Don't reach for it when authoring for the React renderer.
  */
 declare interface CommentAnnotationInput {
     id?: string;
@@ -996,6 +1264,7 @@ declare interface CommentAnnotationInput {
     content: RichTextContent;
 }
 
+/** Resolved form of {@link CommentAnnotationInput} — defaults applied, anchor normalised. */
 declare interface CommentAnnotationSpec {
     id: string;
     anchor: ObservationAnchor;
@@ -1028,6 +1297,12 @@ export declare interface CompiledAxisGuide {
     aesthetic: AestheticKey;
     /** Axis placement */
     position: AxisPosition;
+    /**
+     * Axis geometry: `'linear'` for cartesian (straight edge axis), `'circular'` for the angular axis
+     * of a polar chart (ticks around the rim — the radar spokes/labels), `'radial'` for the radial axis
+     * (concentric ring gridlines). Renderers branch on this before `position`.
+     */
+    geometry: GuideGeometry;
     /** Title text, null means no title */
     label: string | null;
     /** Whether the axis (line + ticks + labels) is visible */
@@ -1108,10 +1383,25 @@ export declare interface CompiledFreeformArrow {
     hasStickerStyle: boolean;
 }
 
-declare interface CompiledGeom {
-    /** The reparameterized dataset (may have new computed variables) */
+/**
+ * What {@link Geom.compile} returns — the reparameterised data plus any mapping the geom injects.
+ * Everything here must be JSON-serialisable (it rides in the compiled spec): emit data columns and
+ * plain mapping values only — no closures, no class instances.
+ */
+export declare interface CompiledGeom {
+    /**
+     * The reparameterised dataset: the input dataset with the position columns the mark owns added. Write
+     * each through `variableFor(axis, role | name)` — never a literal column string like `'yMin'` — so the
+     * value readers and the coord projection find them. A geom writes only the columns it owns; the mapper
+     * scales any `scalar` channel that declares an `aes` source in place from the author's mapping.
+     */
     data: Dataset;
-    /** Any mapping overrides produced by the geom */
+    /**
+     * Mapping overrides the geom injects, merged over the layer's mapping. The common case is attaching a
+     * scale a mark needs but the author never mapped — e.g. injecting `{ y: { variable } }` so a price
+     * scale forms for an OHLC mark whose extent comes from a y-interval. Return `{}` to inject nothing;
+     * never echo the author's own aesthetics back here.
+     */
     mapping: AesMapping;
     /**
      * Extra single-observation tooltip rows this geom contributes (e.g. OHLC). The compiler derives
@@ -1334,7 +1624,7 @@ export declare interface CompiledSpec {
     annotations: CompiledAnnotations;
 }
 
-declare interface CompiledStat {
+export declare interface CompiledStat {
     /** The transformed dataset. */
     data: Dataset;
     /** Any mapping overrides produced by the stat (e.g., `y` → `'count'` for `CountStat`). */
@@ -1549,7 +1839,37 @@ declare interface ComputeFreeformArrowParams {
 }
 
 /**
- * Create a custom  configuration
+ * Pipeable spec item carrying chart-level configuration. Every group is
+ * optional; only the keys you set override the resolved defaults. Accepts:
+ *
+ * - `content`: titles and attribution — `title` / `subtitle` / `caption`
+ *   (each a {@link TextContent}) plus `source` ({@link SourceContent}), each
+ *   paired with an `isXVisible` toggle.
+ * - `legend`: `{ position }` — see {@link LegendPosition}.
+ * - `axes`: per-axis `{ x, y, ySecondary }` overrides, e.g. `{ label }`.
+ * - `numberFormat`: chart-wide number formatting — see {@link NumberFormatConfig}.
+ * - `headline`: big-number summary figure — `show` / `compareWith` / `size` /
+ *   `position` (see {@link HeadlineShow}, highlights-headlines.md).
+ * - `appearance`: render-only styling — `textScale`, `highlightStyle`,
+ *   `background`, `border`, `cornerRadius` (see {@link AppearanceSpec}).
+ *
+ * @example
+ *   import { pipe, createSpec, geom, scale, config } from '@graphysdk/viz-engine';
+ *
+ *   pipe(
+ *     createSpec({ x: 'quarter', y: 'revenue', color: 'region' }),
+ *     geom.bar({ position: 'stack' }),
+ *     scale.x(),
+ *     scale.y(),
+ *     config({
+ *       content: { title: 'Quarterly revenue by region', source: { label: 'Finance', url: 'https://…' } },
+ *       legend: { position: 'top' },
+ *       axes: { y: { label: 'Revenue ($)' } },
+ *       numberFormat: { decimals: 0, abbreviation: 'auto', prefix: '$' },
+ *       headline: { show: 'total' },
+ *       appearance: { highlightStyle: 'dim' },
+ *     })
+ *   );
  */
 export declare function config(options: ConfigInput): ConfigItem;
 
@@ -1566,8 +1886,20 @@ declare interface ConfigCompilerInput {
     scales: CompiledScales;
 }
 
+/**
+ * Author-facing argument to `config(...)`: a deep-partial of {@link ConfigSpec}.
+ * Any omitted group or field falls back to its resolved default.
+ */
 declare type ConfigInput = Omit<DeepPartial<ConfigSpec>, 'legend' | 'content'> & {
+    /**
+     * Legend overrides. Overridden from the deep-partial default so it accepts the
+     * flat {@link LegendConfigInput} (`{ position, display }`) rather than a nested partial.
+     */
     legend?: LegendConfigInput;
+    /**
+     * Content overrides. Overridden from the deep-partial default so titles/source
+     * accept the author-friendly {@link ContentInput} shape (strings or rich objects).
+     */
     content?: ContentInput;
 };
 
@@ -1575,22 +1907,38 @@ declare type ConfigInput = Omit<DeepPartial<ConfigSpec>, 'legend' | 'content'> &
  * Config specification with type tag
  */
 declare interface ConfigItem {
+    /** Discriminant marking this as a config item in a pipeable spec. */
     type: 'config';
+    /** The author-supplied partial configuration to merge over the defaults. */
     config: ConfigInput;
 }
 
 /**
- * Feature configuration with resolved defaults.
- * All fields are required and always populated after resolution.
+ * Fully-resolved chart configuration: every group present with defaults
+ * applied. This is the shape carried on a compiled spec; authors pass the
+ * partial {@link ConfigInput} to `config(...)` instead.
  */
 export declare interface ConfigSpec {
+    /**
+     * Locale used to interpret raw string values into numbers/dates (e.g. which
+     * thousands/decimal separators to expect). Acts as the fallback for output
+     * formatting when no separate `formattingLocale` is supplied.
+     * @default 'en-US'
+     */
     parsingLocale: Locale;
+    /** Legend placement and display mode. */
     legend: LegendConfig;
+    /** Per-axis settings for the x, y, and optional secondary y axes. */
     axes: AxesConfig;
+    /** Plot panel framing (the box drawn around the data area). */
     panel: PanelConfig;
+    /** Big-number summary figure shown above or inside the chart. */
     headline: HeadlineConfig;
+    /** Chart-wide number formatting applied by the renderer to every numeric value. */
     numberFormat: NumberFormatConfig;
+    /** Titles, subtitle, caption, and source attribution. */
     content: ContentConfig;
+    /** Render-only styling: text scale, background, border, corner radius, highlight style. */
     appearance: AppearanceSpec;
 }
 
@@ -1618,15 +1966,20 @@ declare interface ConstantMappingCompilerOutput {
 /***************************************************************
  * Constant Transform
  ***************************************************************/
+/**
+ * Options for `transform.constant` — adds a new variable with the same value on every observation.
+ * Useful to synthesize a constant axis or a single-category grouping variable.
+ */
 declare interface ConstantOptions {
-    /** The name of the new variable. */
+    /** Name of the new variable to add. */
     variableName: VariableName;
-    /** The type of the new variable. */
+    /** Data type of the new variable. */
     type: DataType;
-    /** The constant value to assign to every observation. */
+    /** The constant value assigned to every observation. */
     value: DataValue;
 }
 
+/** Add-a-constant-column transform produced by `transform.constant`. */
 declare interface ConstantTransformInput {
     type: 'transform';
     transformType: 'constant';
@@ -1656,17 +2009,29 @@ declare interface Content {
  * hide cycles without losing the text the user typed.
  */
 export declare interface ContentConfig {
+    /** Main chart title. `null` = unset. */
     title: TextContent | null;
+    /** @default true */
     isTitleVisible: boolean;
+    /** Secondary line shown under the title. `null` = unset. */
     subtitle: TextContent | null;
+    /** @default true */
     isSubtitleVisible: boolean;
+    /** Explanatory note shown below the plot. `null` = unset. */
     caption: TextContent | null;
+    /** @default false */
     isCaptionVisible: boolean;
+    /** Data-source attribution shown under the caption. `null` = unset. */
     source: SourceContent | null;
+    /** @default false */
     isSourceVisible: boolean;
 }
 
-/** Content input — all fields optional. */
+/**
+ * Author-facing `content` argument to `config(...)`: all fields optional.
+ * Setting a text slot does not show it unless the matching `isXVisible` flag is
+ * also true (title and subtitle default visible; caption and source default hidden).
+ */
 declare type ContentInput = Partial<ContentConfig>;
 
 declare type ContinuousScaleInput = {
@@ -1752,27 +2117,60 @@ declare type ContinuousScaleSpec = Required<ContinuousScaleInput>;
  */
 export declare function convertSpecToInput(spec: Spec): SpecInput;
 
+/**
+ * Coordinate-system builder. A coord is a geom-agnostic projection applied AFTER scaling
+ * that remaps the already-scaled `[0,1]` positions of any geom; it changes neither the data,
+ * the scales, nor the chart's tier. Pipe at most one onto a spec — cartesian is assumed when
+ * none is given.
+ *
+ * - `cartesian` — standard x→horizontal, y→vertical (the default).
+ * - `flip` — swaps the x and y axes; the idiom for horizontal bars and long category labels.
+ * - `polar` — wraps x/y around a centre; `theta` selects the angle aesthetic and the other
+ *   becomes the radius. The basis for pie, donut, and radar charts.
+ *
+ * @example
+ *   import { pipe, createSpec, geom, scale, coord } from '@graphysdk/viz-engine';
+ *
+ *   // Donut: stacked value → angle, innerRadius > 0 carves the hole
+ *   pipe(
+ *     createSpec({ x: '', y: 'spend', color: 'department' }),
+ *     geom.bar({ position: 'fill' }),
+ *     coord.polar({ theta: 'y', innerRadius: 0.55 }),
+ *     scale.x(),
+ *     scale.y(),
+ *     scale.color.palette()
+ *   );
+ */
 export declare const coord: {
     /**
-     * Standard cartesian (x-y) coordinate system. This is the default if no coord is specified.
+     * Standard cartesian (x→horizontal, y→vertical) coordinate system. This is the default
+     * when no coord is piped onto the spec; declare it explicitly only to set axis limits.
      *
      * @example coord.cartesian() // auto-scaled axes
-     * @example coord.cartesian({ yLimits: [0, 100] }) // fixed y-axis
+     * @example coord.cartesian({ yLimits: [0, 100] }) // fixed y-axis range
      */
     cartesian: (params?: Partial<CartesianCoordParams>) => CartesianCoordInput;
     /**
-     * Flipped cartesian coordinates — swaps x and y axes.
-     * Useful for horizontal bar charts or when category labels are long.
+     * Flipped cartesian coordinates — swaps the x and y axes so the x aesthetic runs
+     * vertically and y runs horizontally. The idiom for horizontal bar charts and for
+     * long category labels. The mapping stays the same; only the on-screen orientation flips.
      *
-     * @example coord.flip() // horizontal bars
+     * @example coord.flip() // horizontal bars from a vertical-bar spec
      */
     flip: (params?: Partial<FlipCoordParams>) => FlipCoordInput;
     /**
-     * Polar coordinate system — maps data to angle (theta) and radius.
-     * Used for pie charts, donut charts, and radar/radial visualizations.
+     * Polar coordinate system — wraps the scaled positions around a centre, mapping one
+     * aesthetic to the angle (theta) and the other to the radius (scaled into
+     * `[innerRadius, 1]`). `theta` defaults to `'x'`.
+     *
+     * - Pie / donut: `geom.bar({ position: 'fill' })` with `theta: 'y'` (stacked value → angle);
+     *   set `innerRadius > 0` for a donut.
+     * - Radar / spider: `geom.line` or `geom.point` with `theta: 'x'` over a discrete x axis
+     *   (one evenly-spaced spoke per category).
      *
-     * @example coord.polar() // pie chart
-     * @example coord.polar({ innerRadius: 0.5 }) // donut chart
+     * @example coord.polar({ theta: 'y' }) // pie: stacked value → angle
+     * @example coord.polar({ theta: 'y', innerRadius: 0.5, startAngle: 90 }) // donut rotated 90°
+     * @example coord.polar({ theta: 'x' }) // radar: category → spoke angle
      */
     polar: (params?: Partial<PolarCoordParams>) => PolarCoordInput;
 };
@@ -1791,7 +2189,10 @@ declare class CoordCompiler {
 }
 
 /**
- * Discriminated union of all coordinate input specs (user-provided, optional params).
+ * A coordinate system produced by the `coord` builder, before resolution.
+ * A coord is a geom-agnostic projection applied AFTER scaling: it remaps the already-scaled
+ * `[0,1]` positions of any geom without touching the data, the scales, or the chart's tier.
+ * One coord per spec; defaults to cartesian when none is piped on.
  */
 declare type CoordInput = CartesianCoordInput | FlipCoordInput | PolarCoordInput;
 
@@ -1815,7 +2216,7 @@ declare type CoordSetupResult = {
 };
 
 /**
- * Discriminated union of all resolved coordinate specs (params fully defaulted).
+ * A fully resolved coordinate system (params defaulted) as it appears on the compiled spec.
  */
 declare type CoordSpec = CartesianCoordSpec | FlipCoordSpec | PolarCoordSpec;
 
@@ -1858,7 +2259,7 @@ declare interface CoordTransformInput {
  * - `'polar'` — Polar coordinates for pie, radar, and radial charts
  * - `'flip'` — Cartesian with x and y axes swapped
  */
-declare type CoordType = 'cartesian' | 'polar' | 'flip';
+export declare type CoordType = 'cartesian' | 'polar' | 'flip';
 
 declare function count(): CountStatSpec;
 
@@ -1874,12 +2275,27 @@ export declare const createAlphaValueReader: (data: Dataset, mapping: AesMapping
 export declare const createColorValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
 
 /**
- * Builds a compiler instance. Pass `geoms` to register custom (or override built-in) geom
- * definitions per-instance — there is no global registry to mutate, so injected geoms never bleed
- * across instances. An injected geom whose `type` matches a built-in overrides it (last write wins).
+ * Create command metadata with defaults.
+ */
+export declare function createCommandMetadata(options: CreateCommandMetadataOptions): CommandMetadata;
+
+declare interface CreateCommandMetadataOptions {
+    id?: string;
+    timestamp?: number;
+    description: string;
+    author?: string;
+}
+
+/**
+ * Builds a compiler instance. Pass `geoms` / `stats` / `transforms` to register custom (or override
+ * built-in) definitions per-instance — there is no global registry to mutate, so injected definitions
+ * never bleed across instances. An injected definition whose `type` matches a built-in overrides it
+ * (last write wins).
  */
 export declare const createCompiler: (opts?: {
     geoms?: readonly Geom[];
+    stats?: readonly Stat[];
+    transforms?: readonly TransformStrategy[];
 }) => Compiler;
 
 /**
@@ -1889,20 +2305,27 @@ export declare const createCompiler: (opts?: {
 export declare function createEmptyHighlight(strategy: HighlightStrategy | null): CompiledLayerHighlight | null;
 
 /**
- * Builds a Graphy authoring surface for a set of custom geoms and/or annotations: a `geom` builder that
- * merges the built-in methods with one method per registered custom geom, an `annotation` builder with
- * one method per registered annotation kind, plus the standard `createSpec`. The 90% case stays the
- * plain `import { geom, createSpec }`; reach for this only when authoring custom geoms (decision 8) or
- * custom annotations (ADR-035). Registration is per-instance — geoms are injected to
- * `createCompiler({ geoms })`; annotations need no compile-side registry (coordinate resolution is
- * generic), only the render plugin via `<GraphProvider annotationPlugins={[...]}>`.
+ * Builds a Graphy authoring surface for a set of custom geoms, stats, transforms, and/or annotations: a
+ * `geom` builder merging the built-in methods with one per registered custom geom, a `stat` builder
+ * merging the built-in stats with one per registered custom stat, a `transform` builder merging the
+ * built-in transforms with one per registered custom transform, an `annotation` builder merging the
+ * built-in kinds with one per registered annotation kind, plus the standard `createSpec`. The 90% case
+ * stays the plain `import { geom, stat, transform, annotation, createSpec }`; reach for this only when
+ * authoring custom geoms (ADR-033), stats/transforms (ADR-039), or annotations (ADR-035). Registration is
+ * per-instance — geoms, stats, and transforms are injected to `createCompiler({ geoms, stats, transforms })`;
+ * annotations need no compile-side registry (coordinate resolution is generic), only the render plugin via
+ * `<GraphProvider annotationPlugins={[...]}>`.
  */
-export declare function createGraphyBuilder<const Geoms extends readonly Geom[] = readonly [], const Annotations extends readonly AnnotationDef[] = readonly []>(options: {
+export declare function createGraphyBuilder<const Geoms extends readonly Geom[] = readonly [], const Stats extends readonly StatDef[] = readonly [], const Transforms extends readonly TransformDef[] = readonly [], const Annotations extends readonly AnnotationDef[] = readonly []>(options: {
     geoms?: Geoms;
+    stats?: Stats;
+    transforms?: Transforms;
     annotations?: Annotations;
 }): {
     geom: typeof geom & CustomGeomBuilders<Geoms>;
-    annotation: CustomAnnotationBuilders<Annotations>;
+    stat: typeof stat & CustomStatBuilders<Stats>;
+    transform: typeof transform & CustomTransformBuilders<Transforms>;
+    annotation: typeof annotation & CustomAnnotationBuilders<Annotations>;
     createSpec: typeof createSpec;
 };
 
@@ -1910,6 +2333,9 @@ export declare const createGroupValueReader: (data: Dataset, mapping: AesMapping
 
 export declare const createLabelValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
 
+/** Opens a {@link MarkTable} builder for a heterogeneous, kind-tagged geom-layout dataset. */
+export declare function createMarkTable(): MarkTable;
+
 /**
  * Builds a per-observation reader for an `AestheticValue`:
  * - `{ value: X }` → returns `X` for every observation.
@@ -1926,20 +2352,32 @@ export declare function createSegmentYReader(layer: CompiledLayer): (observation
 export declare const createSizeValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
 
 /**
- * Create a new spec, optionally piping spec items in one call. Data is passed separately
- * to {@link compile}.
+ * 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. Data is supplied
+ * separately to `compile` / `<GraphProvider data>`.
+ *
+ * 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 channel — they are NOT auto-inferred and yield NaN positions if omitted.
  *
  * @example
- * When the first arg is a mapping:
- *   createSpec({ x: 'date', y: 'value' })
+ * import { createSpec, pipe, geom, scale } from '@graphysdk/viz-engine';
  *
- * 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(),
- *   )
+ * // Most common: mapping first, then pipe the rest.
+ * const spec = pipe(createSpec({ x: 'category', y: 'revenue' }), geom.bar(), scale.x(), scale.y());
+ *
+ * @example
+ * import { createSpec, transform, mapping, geom, scale } from '@graphysdk/viz-engine';
+ *
+ * // 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(),
+ * );
  */
 export declare function createSpec(...items: Array<AesMapping | SpecItem>): SpecInput;
 
@@ -1993,6 +2431,7 @@ declare interface CustomAnnotationOptions<TParams extends object> {
     id?: string;
 }
 
+/** Resolved form of {@link CustomAnnotationInput} — params defaulted to `{}`, coordinates resolved. */
 export declare interface CustomAnnotationSpec {
     id: string;
     type: string;
@@ -2018,7 +2457,7 @@ declare type CustomGeomBuilders<Geoms extends readonly Geom[]> = {
  */
 declare interface CustomGeomOptions<TParams extends object, TAes extends string> {
     aes?: Partial<Record<TAes, AestheticValue>>;
-    stat?: StatName | StatInput;
+    stat?: StatLayerInput | StatLayerInput[];
     position?: PositionType;
     yScaleType?: YScaleType;
     params?: Partial<TParams>;
@@ -2056,12 +2495,53 @@ declare type CustomPaletteInput = {
 export declare type CustomPalettesInput = Record<string, string[]>;
 
 /**
- * Data to visualize. Structured as a table.
+ * One builder method per registered custom stat, keyed by its `type` and typed from its definition — so
+ * `stat.shareOfTotal(...)` exists because `shareOfTotal` was registered, with options checked against the
+ * stat's resolved spec. The options argument is required only when the stat declares a required option;
+ * a stat with no options or only optional ones is callable with none.
+ */
+declare type CustomStatBuilders<Stats extends readonly StatDef[]> = {
+    [Definition in Stats[number] as Definition['type']]: Partial<StatOptionsOf<Definition>> extends StatOptionsOf<Definition> ? (options?: StatOptionsOf<Definition>) => CustomStatInput : (options: StatOptionsOf<Definition>) => CustomStatInput;
+};
+
+/**
+ * A custom stat's serialised input — its registered `type` plus arbitrary plain-data options. Produced
+ * by the `stat.<type>(...)` method of `createGraphyBuilder({ stats })`; carried on a layer's `stat`
+ * field and passed through resolution unchanged (it is already a resolved spec).
+ */
+export declare interface CustomStatInput extends StatSpecBase {
+    [option: string]: unknown;
+}
+
+/**
+ * One builder method per registered custom transform, keyed by its `transformType` and typed from its
+ * definition — so `transform.topN(...)` exists because `topN` was registered, with options checked
+ * against the transform's options. The options argument is required only when the transform declares a
+ * required option; a transform with no options or only optional ones is callable with none.
+ */
+declare type CustomTransformBuilders<Transforms extends readonly TransformDef[]> = {
+    [Definition in Transforms[number] as Definition['transformType']]: Partial<TransformOptionsOf<Definition>> extends TransformOptionsOf<Definition> ? (options?: TransformOptionsOf<Definition>) => CustomTransformInput : (options: TransformOptionsOf<Definition>) => CustomTransformInput;
+};
+
+/**
+ * A custom transform's serialised input — its registered `transformType` plus plain-data options.
+ * Produced by the `transform.<type>(...)` method of `createGraphyBuilder({ transforms })`; carried on a
+ * spec or layer `transforms` array and dispatched by `transformType` like any built-in.
+ */
+export declare interface CustomTransformInput {
+    type: 'transform';
+    transformType: string;
+    options?: Record<string, unknown>;
+}
+
+/**
+ * The raw input dataset to visualize, structured as a table of `columns` + `rows`. This is what you
+ * hand to the compiler and to `<GraphProvider data>` — the untransformed, pre-compile shape, distinct
+ * from the per-observation {@link Observation} records a geom reads after compilation.
  *
- * The public-API contract. Row values must be {@link DataValue} (string, number,
- * Date, or null). Internal entry points (e.g. the dataset parser) accept a
- * looser row type — see {@link RawData} — because they must defensively handle
- * malformed input.
+ * The public-API contract: row values must be {@link DataValue} (string, number, Date, or null).
+ * Internal entry points (e.g. the dataset parser) accept a looser row type — see {@link RawData} —
+ * because they must defensively handle malformed input.
  */
 export declare interface Data {
     /**
@@ -2149,6 +2629,11 @@ export declare interface DataLabelsContent {
     labels: PlacedDataLabel[];
 }
 
+/**
+ * User-facing data-labels options for a layer (`geom.x({ dataLabels })`). A partial of {@link DataLabelsConfig}
+ * minus `labelSource` (the label source is derived from the geom, not set here); unset fields fall back to the
+ * config defaults. Set `{ showDataLabels: true }` to turn labels on.
+ */
 export declare type DataLabelsInput = DeepPartial<Omit<DataLabelsConfig, 'labelSource'>>;
 
 /**
@@ -2172,6 +2657,10 @@ export declare type DataLabelTextMeasurer = (kind: DataLabelKind, text: string)
  *
  * All transformation methods (filter, orderBy, addVariable etc.) return a new instance.
  *
+ * In a geom, this is what a `compile()` half reparameterises (e.g. `addVariable` to write computed
+ * columns) and what a render half receives as `layer.data` — iterate it (or `groupBy` it) to walk the
+ * compiled {@link Observation}s and read each mark's positions with the value readers.
+ *
  * @example
  * const data = new Dataset({
  *   age: { type: 'numeric', values: [25, 30, 35, null] },
@@ -2439,9 +2928,13 @@ declare type DatetimeTickIntervalUnit = 'hour' | 'day' | 'week' | 'month' | 'qua
 /**
  * Recursively makes every property of `T` optional.
  * Unlike the built-in `Partial`, this applies to nested objects as well.
+ *
+ * An `unknown`/`any` property is treated as a leaf (kept as-is) rather than recursed into — recursing an
+ * open value bag like `Record<string, unknown>` would otherwise rewrite each `unknown` value to `{}`,
+ * making the original value un-assignable to its own `DeepPartial`.
  */
 declare type DeepPartial<T> = {
-    [K in keyof T]?: T[K] extends Array<infer U> ? Array<DeepPartial<U>> : NonNullable<T[K]> extends object ? DeepPartial<NonNullable<T[K]>> : T[K];
+    [K in keyof T]?: unknown extends T[K] ? T[K] : T[K] extends Array<infer U> ? Array<DeepPartial<U>> : NonNullable<T[K]> extends object ? DeepPartial<NonNullable<T[K]>> : T[K];
 };
 
 export declare const DEFAULT_COLOR_PALETTE: string[];
@@ -2462,6 +2955,62 @@ declare type DefaultPaletteConfig = {
     type: 'default';
 };
 
+/**
+ * Declares the compile-half of a custom annotation kind: its `type` name, `defaultParams`, and optional
+ * coordinate `arity`. There is no compile logic here — coordinate resolution is generic — so this only
+ * exists to type and register the kind.
+ *
+ * `TType` is a `const` type parameter so the literal kind name (`'calloutBox'`) survives to the type
+ * level — the registration-typed builder keys `annotation.<kind>(...)` off it, the same way
+ * `createGraphyBuilder` captures a geom's name. `TParams` is recovered from `defaultParams`; annotate or
+ * cast it (`defaultParams: {...} as CalloutBoxParams`) when a param's literal union would otherwise widen.
+ */
+export declare function defineAnnotation<const TType extends string, TParams extends object = object>(def: {
+    type: TType;
+    defaultParams?: TParams;
+    coordinates?: AnnotationArity;
+}): AnnotationDef<TParams, TType>;
+
+/**
+ * Declares a custom stat — the grammar-correct home for a per-group derived value (share-of-total,
+ * running total, rank, z-score). The `compute` receives the layer dataset, the effective mapping, the
+ * resolved spec, and a `column` namespacing helper; it returns the transformed dataset plus any mapping
+ * rebinding (`{ y: column('share') }`), exactly as the built-in `count`/`smooth` stats do.
+ *
+ * `TSpec` is the resolved spec interface (its `type` literal plus options). Declare it so the builder
+ * method `stat.<type>(options)` is typed; the compute reads `input.spec` narrowed to it.
+ *
+ * @example
+ *   interface ShareStatSpec { type: 'shareOfTotal'; field: string }
+ *   export const shareOfTotal = defineStat<ShareStatSpec>({
+ *     type: 'shareOfTotal',
+ *     computedColumns: ['share'],
+ *     computedVariables: ['y'],
+ *     compute: ({ data, spec, column }) => {
+ *       const total = data.getValues(spec.field, { type: 'numeric', skipNulls: true }).reduce((a, b) => a + b, 0);
+ *       const share = column('share');
+ *       const values = data.getValues(spec.field, { type: 'numeric' }).map((v) => (v ?? 0) / total);
+ *       return { data: data.addVariable(share, 'numeric', values), mapping: { y: share } };
+ *     },
+ *   });
+ */
+export declare function defineStat<const TSpec extends StatSpecBase = StatSpecBase>(manifest: StatDefinitionManifest<TSpec>): StatDef<TSpec>;
+
+/**
+ * Declares a custom transform — mapping-blind, whole-table reshaping (top-N-with-"Other", an exotic
+ * fold/pivot) the five built-ins don't cover. Prefer a stat (`defineStat`) for any per-group derived
+ * value; reach for a transform only to reshape the table itself. The `apply` receives the dataset and
+ * the transform's options and returns a new dataset.
+ *
+ * @example
+ *   interface TopNOptions { valueName: string; n: number }
+ *   export const topN = defineTransform<'topN', TopNOptions>({
+ *     transformType: 'topN',
+ *     apply: (data, { valueName }) => data.orderBy(valueName, 'desc'), // …keep first n, fold rest into "Other"…
+ *   });
+ */
+export declare function defineTransform<const TType extends string, TOptions extends object = object>(manifest: TransformDefinitionManifest<TType, TOptions>): TransformDef<TType, TOptions>;
+
 declare interface DifferenceArrowDimensions {
     /** Gap between the arrow start point and its anchored observation. */
     arrowStartGap: number;
@@ -2488,25 +3037,34 @@ declare interface DifferenceArrowDimensions {
 }
 
 /**
- * User-facing difference-arrow input. `size`, `color` and `labelCrossPosition`
- * are defaulted by the resolver.
+ * A labelled delta drawn between two data observations — the only built-in annotation that anchors to
+ * DATA. Both endpoints are observation anchors (main-axis value + series), so the arrow snaps to the
+ * dataset and survives resize. Only drawn under a cartesian coordinate system. `size`, `color` and
+ * `labelCrossPosition` are defaulted by the resolver.
  */
 export declare interface DifferenceArrowInput {
     id?: string;
+    /** Observation the arrow starts from. */
     start: ObservationAnchorInput;
+    /** Observation the arrow points to. */
     end: ObservationAnchorInput;
+    /** Which delta the label reports. */
     label: DifferenceArrowLabelKind;
+    /** Arrow colour; `null`/omitted falls back to the theme default. @default null */
     color?: string | null;
+    /** @default 'small' */
     size?: DifferenceArrowSize;
+    /** Where the label sits along the arrow's cross-axis, as a `[0,1]` fraction. @default 0.5 */
     labelCrossPosition?: number;
 }
 
+/** What the arrow's label reports about the `start → end` delta. */
 export declare type DifferenceArrowLabelKind = 'absolute-difference' | 'relative-difference' | 'proportion';
 
 export declare type DifferenceArrowSize = 'small' | 'medium' | 'large';
 
 /**
- * Resolved difference-arrow spec with all optional fields defaulted.
+ * Resolved form of {@link DifferenceArrowInput} — defaults applied, anchors normalised.
  */
 export declare interface DifferenceArrowSpec {
     id: string;
@@ -2578,23 +3136,39 @@ export declare interface ExternalMeasurements {
     footerSize: BoxSize;
 }
 
+/**
+ * Extracts the constant value from a `{ value }` mapping. Returns undefined for variable mappings.
+ */
+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;
 
 /***************************************************************
  * Filter Transform
  ***************************************************************/
+/**
+ * Options for `transform.filter` — keeps only observations where `variableName <operator> value`.
+ */
 declare interface FilterOptions {
     /** The variable to filter on. */
     variableName: VariableName;
-    /** The comparison operator. */
+    /** Comparison operator: `'eq'` | `'neq'` | `'gt'` | `'gte'` | `'lt'` | `'lte'`. */
     operator: ComparisonOperator;
-    /** The value to compare against. */
+    /** The value to compare each observation's `variableName` against. */
     value: DataValue;
 }
 
+/** Row-filtering transform produced by `transform.filter`. */
 declare interface FilterTransformInput {
     type: 'transform';
     transformType: 'filter';
@@ -2617,6 +3191,24 @@ export declare function findAxisGuide(guides: CompiledGuides, scaleAestheticKey:
  */
 export declare function findLegendForAesthetic(guides: CompiledGuides, aesthetic: AestheticKey): CompiledLegendGuide | null;
 
+/**
+ * A gate fixture: a chart authored as plain data — its spec, the custom geom(s) it uses, and the rows —
+ * with no React. The codegen harness's compile and semantic gates load one (authored beside the geom as
+ * `src/<name>.fixture.ts`, exporting a `fixture`) to check that the geom compiles to finite, serialisable
+ * positions and that a synthetic cursor placed on each probed observation resolves hover and a localised
+ * tooltip. It is the rendered chart minus the renderer, so the gates run headlessly.
+ */
+export declare interface Fixture {
+    /** The custom geom instance(s) to register with the compiler — the same instances the spec uses. */
+    geoms: readonly Geom[];
+    /** The spec rendered in `App.tsx`, built with `createGraphyBuilder` + `pipe`. */
+    spec: SpecInput;
+    /** Rows matching the spec's channels (OHLC for a candlestick, a node/link graph for a sankey, …). */
+    data: Data;
+    /** Observation indices the semantic gate fires a cursor at. Defaults to `[0]` when omitted. */
+    probes?: number[];
+}
+
 declare interface FlipCoordInput {
     type: 'coord';
     coordType: 'flip';
@@ -2733,23 +3325,31 @@ export declare interface FormattedPerGroupHeadline {
 }
 
 /**
- * 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.
+ * A free-standing arrow pointing at something on the panel. Both endpoints sit in panel fractions
+ * (`[0,1]`, top-left origin), so they re-flow with panel size but do NOT snap to a data point. Distinct
+ * from {@link DifferenceArrowInput}, which anchors to dataset observations.
  */
 export declare interface FreeformArrowInput {
     id?: string;
+    /** Tail endpoint. */
     start: ArrowEndpoint;
+    /** Head endpoint (the end pointed at). */
     end: ArrowEndpoint;
-    /** null falls back to the theme `defaultAnnotationArrowStroke`. */
+    /** `null` falls back to the theme `defaultAnnotationArrowStroke`. @default null */
     color?: string | null;
+    /** @default 'medium' */
     thickness?: ArrowThickness;
+    /** Arrowhead at the `start` (tail) endpoint. @default 'none' */
     startArrowheadStyle?: ArrowheadStyle;
+    /** Arrowhead at the `end` (head) endpoint. @default 'line-arrow' */
     endArrowheadStyle?: ArrowheadStyle;
+    /** @default 'solid' */
     lineStyle?: ArrowLineStyle;
+    /** Apply the editor's hand-drawn "sticker" styling. @default false */
     hasStickerStyle?: boolean;
 }
 
+/** Resolved form of {@link FreeformArrowInput} — defaults applied. */
 export declare interface FreeformArrowSpec {
     id: string;
     start: ArrowEndpoint;
@@ -2786,7 +3386,7 @@ declare type GenerateTicksOptions = {
  * empty default and keep their typed params through the spec builder's static surface; a custom geom
  * names its params type and declares matching {@link defaultParams}.
  */
-declare abstract class Geom<TParams extends object = object> {
+export declare abstract class Geom<TParams extends object = object> {
     /**
      * The aesthetics an author must map for this geom. Built-ins list closed aesthetic keys
      * (`['x','y']`); a custom geom may also list open channel names (a box plot's `min`/`q1`/…) that it
@@ -2878,6 +3478,13 @@ declare abstract class Geom<TParams extends object = object> {
      * renderer how to place the annotation.
      */
     resolveAnchorPosition(_observation: Observation, _coordSystem: CoordSystem): AnchorPosition | null;
+    /**
+     * Reparameterizes the stat-transformed data into the shape this geom's geometry needs, the central
+     * hook a custom geom implements. Receives the transformed dataset, effective mapping and geom params;
+     * returns the dataset with any computed position variables added (e.g. a bar's `xMin`/`xMax`/`yMin`
+     * interval), the mapping overrides the geom injects, and any extra tooltip rows it contributes. The
+     * compile pipeline runs this per layer before the position and visual mappers read the result.
+     */
     abstract compile(input: GeomCompilerInput): CompiledGeom;
     /**
      * Validates the layer's mapping against invariants specific to this geom (e.g. a rule needs exactly
@@ -2887,6 +3494,25 @@ declare abstract class Geom<TParams extends object = object> {
     validateMapping?(input: GeomMappingValidationInput): ValidationIssue[];
 }
 
+/**
+ * The built-in geom builders. Each is called with one {@link BaseGeomOptions} object and returns a pipeable
+ * layer that `pipe`/`createSpec` folds onto the spec. Compose several to layer marks (e.g. bars + a trend
+ * line). The five marks: `point` (scatter/bubble), `line`, `area`, `bar` (also pie/donut in polar), and
+ * `rule` (a constant or data-driven reference line).
+ *
+ * @example
+ * import { createSpec, pipe, geom, scale, config } from '@graphysdk/viz-engine';
+ *
+ * // Multi-series line; mapping `color` to a column splits series and adds a legend.
+ * const spec = pipe(
+ *   createSpec({ x: 'month', y: 'sales', color: 'region' }),
+ *   geom.line(),
+ *   scale.x(),
+ *   scale.y(),
+ *   scale.color.palette(),
+ *   config({ legend: { position: 'top' } }),
+ * );
+ */
 export declare const geom: {
     point: typeof point;
     line: typeof line;
@@ -2946,12 +3572,31 @@ declare class GeomCompiler {
     resolveAnchorPosition(geomName: GeomIdentity, observation: Observation, coordSystem: CoordSystem): AnchorPosition | null;
 }
 
-declare interface GeomCompilerInput {
-    /** The dataset after stat transformation */
+/**
+ * What {@link Geom.compile} receives. The geom reads these to compute its mark geometry and returns a
+ * {@link CompiledGeom}. The pipeline has already run the layer's stat and resolved its aesthetics, so
+ * `compile` sees finished input and only reparameterises it.
+ */
+export declare interface GeomCompilerInput {
+    /**
+     * The dataset after stat transformation — one row per observation, columnar. Read a mapped channel's
+     * column with `extractVariableName(mapping[channel])`, then `data.getValues(column, { type })`; write
+     * computed columns with `data.addVariable` / `data.addConstantVariable` (each returns a new dataset —
+     * the Dataset is immutable).
+     */
     data: Dataset;
-    /** The effective mapping for the layer */
+    /**
+     * The effective mapping for the layer: which data column (or constant) backs each aesthetic the author
+     * declared. The source of every channel column the geom reads — including the custom `aes` channels in
+     * {@link Geom.requiredAesthetics} (an OHLC `open`, a box plot `q1`). Read a custom channel with
+     * `readAesthetic(mapping, channel)`.
+     */
     mapping: AesMapping;
-    /** Geom-specific params */
+    /**
+     * The geom's static params, already merged over {@link Geom.defaultParams} by the builder. Render
+     * configuration only (widths, radii, colours) — never data columns that bind to a scale, which belong
+     * in `aes`. Typed as the geom's `TParams` at the call site.
+     */
     params: LayerSpec['params'];
 }
 
@@ -2980,8 +3625,10 @@ declare interface GeomMappingValidationInput {
 /** A built-in geom's name — the default vocabulary the spec builder offers out of the box. */
 export declare type GeomName = (typeof GEOM_NAMES)[number];
 
+/** {@link BaseGeomOptions} specialised to geom `G`, so its `params` is typed to that geom's param shape. */
 declare type GeomOptions<G extends GeomName> = BaseGeomOptions<GeomParamsMap[G]>;
 
+/** Union of every built-in geom's params type; the upper bound for {@link BaseGeomOptions}'s generic. */
 declare type GeomParams = GeomParamsMap[keyof GeomParamsMap];
 
 /**
@@ -3014,19 +3661,34 @@ declare class GeomRegistry extends Registry<string, Geom> {
  * data: the `label` is static text and the `variable` names a column, so the rows ride in the
  * serialisable compiled spec.
  */
-declare interface GeomTooltipRow {
+export declare interface GeomTooltipRow {
     /** The row's label (e.g. "Open"). Static text the geom supplies. */
     label: string;
     /** The data column whose per-observation value the row displays. */
     variable: VariableName;
 }
 
-/** Reads the resolved alpha (opacity) value from an observation. */
+/**
+ * Reads the observation's resolved opacity in `[0,1]` (0 = transparent, 1 = opaque) — pass straight to
+ * `fillOpacity`/`opacity`. The `alpha` aesthetic mapped through its scale. `null` when no `alpha`
+ * aesthetic is mapped.
+ */
 export declare function getAlpha(observation: Observation): NumericDataValue;
 
+/**
+ * Reads a polar observation's angular extent — the x interval projected to angles. Use it to draw the
+ * wedge of a pie/donut slice or polar bar; pair with {@link getRadiusExtent} for the radial span.
+ * `startAngle`/`endAngle` are in **radians** (0 = straight up, increasing clockwise). The compiler has
+ * already projected the x interval under `coord.polar()`, so no manual angle math is needed.
+ */
 export declare function getAngleExtent(observation: Observation): AngleExtent;
 
-/** Reads the resolved color string from an observation. */
+/**
+ * Reads the observation's resolved fill/stroke colour as a paint-ready CSS colour string. The visual
+ * mapper has already run the `color` aesthetic through the colour scale, so this is the final string to
+ * hand to `fill`/`stroke` — no further lookup needed. `undefined` when the layer maps no `color`
+ * aesthetic; supply your own series colour (e.g. via `useCategoricalColor`) in that case.
+ */
 export declare function getColor(observation: Observation): string | undefined;
 
 /** Reads the coordinate lying on the cross axis of the coord system. */
@@ -3040,6 +3702,13 @@ export declare function getCrossAxisCoordinate(mainAxis: MainAxis, point: XYPoin
  */
 export declare const getDifferenceArrowDimensions: (size: DifferenceArrowSize, textScale: number) => DifferenceArrowDimensions;
 
+/**
+ * Reads the observation's resolved series identity: the category the `group`/`color` aesthetic placed
+ * it in, as a plain string. Use it to split a layer's observations into series (one polygon, line, or
+ * colour per group) when painting. `null` when the layer maps no grouping aesthetic — a single,
+ * ungrouped series. Reads the compiler-emitted `group` column, so the value survives any renaming of
+ * the user's grouping mapping.
+ */
 export declare const getGroup: (observation: Observation) => CategoricalDataValue;
 
 /**
@@ -3050,20 +3719,33 @@ export declare const getGroup: (observation: Observation) => CategoricalDataValu
 export declare const getIdentityKey: (observation: Observation) => string;
 
 /**
- * Reads the resolved line type (stroke style) from an observation.
- * Falls back to `'solid'` when no `lineType` variable was derived.
+ * Reads the observation's resolved line style (`'solid'`, `'dashed'`, …) for use as a stroke pattern.
+ * The `lineType` aesthetic mapped through its scale, falling back to `'solid'` when no `lineType`
+ * aesthetic is mapped — so this reader, unlike the others, never returns `null`.
  */
 export declare function getLineType(observation: Observation): LineStyleType;
 
 /** Reads the coordinate lying on the main (independent) axis of the coord system. */
 export declare function getMainAxisCoordinate(mainAxis: MainAxis, point: XYPoint): number;
 
+/**
+ * Reads a polar observation's radial extent — the y interval projected to radii. Use it with
+ * {@link getAngleExtent} to draw a donut/polar-bar segment. `innerRadius`/`outerRadius` are in `[0,1]`
+ * (0 = centre, 1 = outer ring); `outerRadius` falls back to the `point` y radius when the observation
+ * carries no upper y endpoint (a pie slice, which has no inner cutout to oppose).
+ */
 export declare function getRadiusExtent(observation: Observation): RadiusExtent;
 
-/** Reads the resolved size value from an observation. */
+/**
+ * Reads the observation's resolved size in **pixels** (e.g. a point's diameter or a mark's nominal
+ * extent), already mapped through the `size` scale. `null` when no `size` aesthetic is mapped.
+ */
 export declare function getSize(observation: Observation): NumericDataValue;
 
-/** Reads the resolved stroke width value from an observation. */
+/**
+ * Reads the observation's resolved stroke width in **pixels** — pass straight to `strokeWidth`. The
+ * `strokeWidth` aesthetic mapped through its scale. `null` when no `strokeWidth` aesthetic is mapped.
+ */
 export declare function getStrokeWidth(observation: Observation): NumericDataValue;
 
 declare interface GetValuesOptions {
@@ -3075,29 +3757,61 @@ declare interface GetValuesOptions {
     distinct?: boolean;
 }
 
-/** Reads the normalized x position from an observation. */
+/**
+ * Reads the observation's scaled x position: the value of the `point` x channel, already mapped
+ * through the x scale to `[0,1]` of the panel width (0 = left edge, 1 = right edge). `null` when the
+ * observation has no x position. Under `coord.polar({ theta: 'x' })` this returns the vertex **angle
+ * in radians** instead (0 = straight up, increasing clockwise). The everyday position reader — pair
+ * it with {@link getY} to place a point-anchored mark.
+ */
 export declare function getX(observation: Observation): NumericDataValue;
 
-/** Reads the normalized xMax (right band edge) from an observation. */
+/**
+ * Reads the upper x endpoint of the observation's x interval, scaled to `[0,1]` of the panel width
+ * (1 = right edge). The right edge of a band/bar or the end of a horizontal range bar. Pairs with
+ * {@link getXMin}. `null` when the observation declares no x interval.
+ */
 export declare function getXMax(observation: Observation): NumericDataValue;
 
-/** Reads the normalized xMin (left band edge) from an observation. */
+/**
+ * Reads the lower x endpoint of the observation's x interval, scaled to `[0,1]` of the panel width
+ * (0 = left edge). The left edge of a band/bar, the start of a horizontal range bar, or a body's left
+ * side. Pairs with {@link getXMax}; `getXMin`/`getXMax` preserve the values `compile()` wrote and are
+ * never re-sorted, so `getXMin` can exceed `getXMax`. `null` when the observation declares no x interval.
+ */
 export declare function getXMin(observation: Observation): NumericDataValue;
 
-/** Reads the normalized y position from an observation. */
+/**
+ * Reads the observation's scaled y position: the value of the `point` y channel, already mapped
+ * through the y scale to `[0,1]` of the panel height with a **bottom origin** (0 = bottom, 1 = top).
+ * SVG y grows downward, so paint with `1 - getY(...)`. `null` when the observation has no y position.
+ * Under polar coords this returns the **radius in `[0,1]`** (0 = centre, 1 = outer ring). See
+ * {@link getYRaw} to recover the pre-stack segment magnitude.
+ */
 export declare function getY(observation: Observation): NumericDataValue;
 
-/** Reads the normalized yMax (upper extent) from an observation. */
+/**
+ * Reads the upper y endpoint of the observation's y interval, scaled to `[0,1]` of the panel height
+ * with a **bottom origin** (1 = top; paint with `1 - getYMax(...)`). The bar top, the top of a
+ * candlestick wick, or the end of a vertical range/gantt span. Pairs with {@link getYMin}.
+ * `null` when the observation declares no y interval.
+ */
 export declare function getYMax(observation: Observation): NumericDataValue;
 
-/** Reads the normalized yMin (lower extent) from an observation. */
+/**
+ * Reads the lower y endpoint of the observation's y interval, scaled to `[0,1]` of the panel height
+ * with a **bottom origin** (0 = bottom; paint with `1 - getYMin(...)`). The bar baseline, the bottom of
+ * a candlestick wick, or the start of a vertical range/gantt span. Pairs with {@link getYMax}; the pair
+ * preserves the values `compile()` wrote and is never re-sorted, so `getYMin` can exceed `getYMax`.
+ * `null` when the observation declares no y interval.
+ */
 export declare function getYMin(observation: Observation): NumericDataValue;
 
 /**
- * Reads the segment value written by stacking position adjusters.
- *
- * Survives theposition-mapper untouched, so renderers can recover original-unit values
- * for stacked segments after `mapping.y` has been rewritten to the cumulative band top.
+ * Reads the observation's pre-stack segment magnitude in **original data units** (not `[0,1]`).
+ * Stacking position adjusters rewrite the mapped `y` to the cumulative band top and stash the segment's
+ * own value here, so a renderer or data label can recover what the segment contributed before stacking.
+ * `null` when the layer was not stacked (the column is written only when stacking along y).
  */
 export declare function getYRaw(observation: Observation): NumericDataValue;
 
@@ -3238,7 +3952,7 @@ declare type GraphyPaletteVariant = 'default' | 'waterfall';
  * for instance. A geom declares these so the axis guide resolves grid policy from the definition
  * instead of a geom-keyed lookup. Every field absent means the geom imposes no policy.
  */
-declare interface GridPolicy {
+export declare interface GridPolicy {
     hideGridX?: boolean;
     hideGridY?: boolean;
     hideBorder?: boolean;
@@ -3484,15 +4198,29 @@ export declare class HeuristicTextMeasurer implements TextMeasurer {
 }
 
 /**
- * Create a pipeable highlight spec item.
+ * Pipeable spec item that emphasises the observations matching `predicate` and
+ * de-emphasises (dims or desaturates) everything else. Multiple `highlight(...)`
+ * calls accumulate — their matches union. The de-emphasis style is chosen
+ * separately via `config({ appearance: { highlightStyle: 'dim' | 'desaturate' } })`.
+ *
+ * @param predicate - which observations to emphasise (see {@link Predicate}).
+ * @param options - `scope` ({@link HighlightScope}, default `'data-point'`),
+ *   `layerIndex` (target a single layer; omit to apply to all layers), and an
+ *   optional explicit `id`.
  *
  * @example
+ *   import { pipe, createSpec, geom, scale, highlight } from '@graphysdk/viz-engine';
+ *
  *   pipe(
- *     createSpec(data, { x: 'month', y: 'revenue', color: 'region' }),
+ *     createSpec({ x: 'month', y: 'revenue', color: 'region' }),
  *     geom.bar(),
- *     highlight({ field: 'region', eq: 'EU' }),
- *     highlight({ field: 'region', eq: 'US' }, { scope: 'series' }),
- *   )
+ *     scale.x(),
+ *     scale.y(),
+ *     // emphasise one whole series; leave other layers untouched
+ *     highlight({ variable: 'region', eq: 'EU' }, { scope: 'series' }),
+ *     // and every observation at or above a threshold
+ *     highlight({ variable: 'revenue', gte: 2000 })
+ *   );
  */
 export declare function highlight(predicate: Predicate, options?: HighlightBuilderOptions): HighlightInput;
 
@@ -3642,10 +4370,10 @@ export declare class HoverEngine {
      */
     private nonInteractiveLayerIds;
     /**
-     * Render-side hit-testers registered per layer for `render-hit-test` (Tier-C) layers, keyed by
+     * Render-side hit-testers registered per layer for `render-hit-test` (geom-layout) layers, keyed by
      * `CompiledLayer.id`. The renderer owns this map and injects it via {@link setHitTesters}; the
      * engine holds the live reference so a plugin mounting or updating its tester is visible at the
-     * next `query()` without a re-index. Empty for charts with no Tier-C geom.
+     * next `query()` without a re-index. Empty for charts with no geom-layout geom.
      */
     private hitTesters;
     constructor({ layers, coordSystem }: HoverEngineInput);
@@ -3786,6 +4514,17 @@ declare interface InferredScaleInput {
 
 declare type InferredScaleOptions = ContinuousScaleOptions | DiscreteScaleOptions | DatetimeScaleOptions;
 
+/**
+ * Recovers where a raw sub-value sits inside an already-scaled interval. Given a raw `[rawLo, rawHi]`
+ * pair that the compiler mapped to the scaled `[scaledLo, scaledHi]` endpoints, returns the scaled
+ * position of `raw` by affine interpolation. The geom-scaled trick a candlestick uses to place its open/close
+ * inside the scaled `[low, high]` wick without re-running the y-scale.
+ *
+ * Exact only when the scale between raw and scaled space is **linear** — both endpoints pin a straight
+ * line every interior value reads off. A degenerate interval (`rawLo === rawHi`) returns `scaledLo`.
+ */
+export declare function interpolateInScaledInterval(raw: number, rawLo: number, rawHi: number, scaledLo: number, scaledHi: number): number;
+
 /**
  * Curve interpolation method for lines and areas.
  *
@@ -3869,13 +4608,27 @@ declare interface LayerCompilerInput {
  */
 declare type LayerInput = BuiltinLayerInput | CustomLayerInput;
 
+/**
+ * Geom-agnostic fields shared by every layer input, before resolution. Builders produce this shape (with
+ * `geom` and `params` added per geom); all fields are optional and filled with defaults during resolution.
+ */
 declare interface LayerInputBase {
+    /** Discriminant marking this spec item as a layer. */
     type: 'layer';
+    /** Optional stable identifier for the layer; auto-assigned during resolution when omitted. */
     id?: string;
+    /**
+     * Layer-level aesthetic mapping (the builder's `aes`), shallow-merged OVER the spec-level mapping for this
+     * layer only. Retargets a channel per layer or pins a constant via `{ y: { value } }`.
+     */
     mapping?: AesMapping;
-    stat?: StatName | StatInput;
+    /** Statistical transform(s) applied before positioning — a single stat or a pipeline. @default 'identity' */
+    stat?: StatLayerInput | StatLayerInput[];
+    /** How sibling marks sharing an x position are arranged (`'stack'`, `'dodge'`, `'fill'`, `'identity'`). Default is per-geom. */
     position?: PositionType;
+    /** Which Y axis the layer binds to — `'secondary'` targets the right-hand axis in a dual-axis combo. @default 'primary' */
     yScaleType?: YScaleType;
+    /** Per-observation value labels drawn on the marks. @default off */
     dataLabels?: DataLabelsInput;
     /**
      * Ordered transforms applied to this layer's view of the data, on top of any
@@ -3890,6 +4643,7 @@ declare interface LayerInputBase {
     interactive?: boolean;
 }
 
+/** A built-in layer input narrowed to geom `G`: the shared base plus that geom's tag and partial `params`. */
 declare type LayerInputOf<G extends GeomName> = LayerInputBase & {
     geom: G;
     params?: Partial<GeomParamsMap[G]>;
@@ -3900,18 +4654,32 @@ declare type LayerInputOf<G extends GeomName> = LayerInputBase & {
  */
 declare type LayerSpec = BuiltinLayerSpec | CustomLayerSpec;
 
+/**
+ * Geom-agnostic fields shared by every resolved layer spec. Mirrors {@link LayerInputBase} with all fields
+ * required and defaults applied (`stat` resolved to {@link ResolvedStatSpec}[], `dataLabels` fully expanded).
+ */
 declare interface LayerSpecBase {
+    /** Discriminant marking this spec item as a layer. */
     type: 'layer';
+    /** Resolved stable identifier for the layer (always present after resolution). */
     id: string;
+    /** Resolved aesthetic mapping for this layer, merged from spec-level and layer-level inputs. */
     mapping: AesMapping;
-    stat: StatSpec;
+    /** Resolved statistical-transform pipeline (empty array means identity). */
+    stat: ResolvedStatSpec[];
+    /** Resolved arrangement of sibling marks at the same x position. */
     position: PositionType;
+    /** Resolved Y-axis binding (`'primary'` or `'secondary'`). */
     yScaleType: YScaleType;
+    /** Resolved ordered transforms applied to this layer's view of the data. */
     transforms: TransformInput[];
+    /** Whether the layer participates in hover hit-detection. */
     interactive: boolean;
+    /** Resolved per-observation data-labels configuration. */
     dataLabels: DataLabelsConfig;
 }
 
+/** A resolved built-in layer spec narrowed to geom `G`: the shared base plus that geom's tag and full `params`. */
 declare type LayerSpecOf<G extends GeomName> = LayerSpecBase & {
     geom: G;
     params: GeomParamsMap[G];
@@ -3947,7 +4715,7 @@ declare interface LayerValidationCheckInput {
 declare interface LayerValidationInput {
     layerId: string;
     geom: GeomIdentity;
-    stat: StatSpec;
+    stat: ResolvedStatSpec[];
     /** `spec.mapping` merged with `layer.mapping` */
     effectiveMapping: AesMapping;
     /** Layer's dataset after its own transforms have been applied */
@@ -3986,6 +4754,9 @@ declare class LayerValidator {
      * without a `validateMapping` hook impose none.
      */
     private validateGeomMapping;
+    /** Unions the `computedVariables` of every stat in the layer's pipeline — any aesthetic computed by
+     *  any stage is waived from the pre-stat existence/required checks. */
+    private collectComputedVariables;
     /**
      * Rejects a layer whose coord is absent from the geom's declared `supportedCoordTypes` (e.g. a rule
      * has no meaning under polar pie/donut coords). The supported set lives on the geom definition, so
@@ -4004,14 +4775,16 @@ export declare const LAYOUT_PADDING = 24;
  * settled after the first resolve.
  *
  * Here's the pipeline:
- *   1. **Seed**: stamp each axis with a placeholder label so the grid has something to measure.
- *   2. **Resolve v1**: first grid pass; `panel.height` is now final.
- *   3. **Finalize vertical**: pick the densest candidate that fits `panel.height` for left/right
+ *   1. **Polar prep**: split cartesian from polar axes, format the polar axes whole, and derive the
+ *      symmetric `polarMargin` their rim labels reserve (both empty/zero for a cartesian chart).
+ *   2. **Seed**: stamp each cartesian axis with a placeholder label so the grid has something to measure.
+ *   3. **Resolve v1**: first grid pass; `panel.height` is now final.
+ *   4. **Finalize vertical**: pick the densest candidate that fits `panel.height` for left/right
  *      axes; horizontal axes keep their seed.
- *   4. **Resolve v2**: vertical edge widths now reflect final labels, so `panel.width` is final.
- *   5. **Finalize horizontal**: pick the densest candidate that fits `panel.width` for top/bottom
- *      axes. Vertical axes carry over from step 3.
- *   6. **Resolve v3**: final grid pass with all axes finalized.
+ *   5. **Resolve v2**: vertical edge widths now reflect final labels, so `panel.width` is final.
+ *   6. **Finalize horizontal**: pick the densest candidate that fits `panel.width` for top/bottom
+ *      axes. Vertical axes carry over from step 4.
+ *   7. **Resolve v3**: final grid pass with all axes finalized.
  */
 export declare class LayoutCompiler {
     private readonly measurer;
@@ -4047,6 +4820,13 @@ export declare class LayoutCompiler {
 export declare interface LayoutCompileResult {
     layout: GraphLayout;
     formattedAxes: FormattedAxis[];
+    /**
+     * Polar axes (circular angular + radial), formatted with every tick (no fit-based selection or
+     * truncation — a radar shows one spoke per category and rings at the radial ticks). Empty for cartesian
+     * charts. The polar guide renderer consumes these together with the panel/plot rects; they are kept apart
+     * from {@link formattedAxes} because they project around a circle, not onto the four cartesian edges.
+     */
+    formattedPolarAxes: FormattedAxis[];
 }
 
 /** Input for the layout compiler. */
@@ -4091,8 +4871,9 @@ declare interface Legend {
  */
 declare interface LegendConfig {
     /**
-     * Position of the legend
-     * @default 'top'
+     * Where the legend sits relative to the plot. See {@link LegendPosition} for the values;
+     * `'auto'` lets the renderer pick based on chart type and series count.
+     * @default 'auto'
      */
     position: LegendPosition;
     /**
@@ -4152,8 +4933,23 @@ declare interface LegendItemVisual {
     lineType?: LineStyleType;
 }
 
+/**
+ * Where the legend sits relative to the plot, set via
+ * `config({ legend: { position: … } })`.
+ * - 'auto': let the compiler choose based on chart type (default).
+ * - 'right' | 'left' | 'top' | 'bottom': pin to that edge.
+ * - 'none': hide the legend entirely.
+ */
 declare type LegendPosition = 'auto' | 'right' | 'left' | 'top' | 'bottom' | 'none';
 
+/**
+ * Line marks — connected series. One line per `group` (defaults to the `color` column). Tune the stroke via
+ * {@link LineGeomParams}. Pair with `stat.smooth()` for a trendline. Observations are connected in data
+ * order, so sort by x first.
+ *
+ * @example
+ * pipe(createSpec({ x: 'month', y: 'sales', color: 'region' }), geom.line(), scale.x(), scale.y(), scale.color.palette());
+ */
 declare function line(options?: GeomOptions<'line'>): LayerInputOf<'line'>;
 
 /**
@@ -4176,17 +4972,22 @@ declare class LineGeom extends Geom {
 }
 
 /**
- * Line-specific parameters
+ * Render parameters for `geom.line`. Passed under `params`.
  */
 export declare interface LineGeomParams {
+    /**
+     * Stroke width in pixels, or `'auto'` to let the theme pick a width.
+     * @default 'auto'
+     */
     lineWidth: number | 'auto';
     /**
-     * Interpolation method to use for the line.
+     * Interpolation method between points: `'linear'` for straight segments, `'catmull-rom'` for a smooth spline.
      * @default 'linear'
      */
     interpolate: InterpolateType;
     /**
-     * How to handle missing (NULL/undefined) values.
+     * How to handle missing (`null`) y-values: `'gap'` breaks the line, `'zero'` drops to zero, `'connect'`
+     * bridges across the gap.
      * @default 'gap'
      */
     missingValues: MissingValuesType;
@@ -4213,7 +5014,12 @@ export declare type Locale = (typeof LOCALES)[number];
 /** A BCP-47 string representing a supported locale. */
 declare const LOCALES: readonly ["en-GB", "en-US", "ar", "pt-PT"];
 
-/** Logical composition of any predicate. */
+/**
+ * Boolean composition of nested predicates:
+ * - `and`: every sub-predicate matches.
+ * - `or`: at least one matches.
+ * - `not`: the sub-predicate does not match.
+ */
 export declare type LogicalPredicate = {
     and: Predicate[];
 } | {
@@ -4248,7 +5054,9 @@ export declare type MainAxis = 'x' | 'y';
 declare type MappableAes<Definition extends Geom> = Definition['requiredAesthetics'][number] | Definition['visualAesthetics'][number] | 'group';
 
 /**
- * Create a pipeable mapping spec item.
+ * Create a pipeable mapping spec item. Use this form (rather than passing the mapping as the first
+ * `createSpec` arg) when a transform must run before the mapping is read — e.g. reshaping wide columns
+ * to long so a freshly-created column can be bound to a channel.
  *
  * @example
  * createSpec(
@@ -4261,13 +5069,38 @@ declare type MappableAes<Definition extends Geom> = Definition['requiredAestheti
 export declare function mapping(aes: AesMapping): MappingItem;
 
 /**
- * A pipeable spec item that sets/merges the global aesthetic mapping.
+ * A pipeable spec item that sets/merges the global {@link AesMapping}. Produced by {@link mapping} and
+ * folded into the spec by `pipe`/`createSpec`; later mapping items shallow-merge over earlier channels.
  */
 declare interface MappingItem {
     type: 'mapping';
     mapping: AesMapping;
 }
 
+/** Declares one mark kind's own columns and the data type of each. */
+export declare type MarkColumnSchema = Record<string, DataType>;
+
+/**
+ * Builds one columnar {@link Dataset} from heterogeneous marks discriminated by a `kind` column — *the*
+ * geom-layout dataset shape (node+link, group+leaf, node+edge). Each kind declares its own columns; the union
+ * across kinds forms the dataset's columns, and a row's off-kind columns are filled with `null` **by
+ * construction**, so the null-padding invariant a hand-built builder maintains by hand (and breaks when a
+ * column is omitted from one kind's push) can no longer drift.
+ */
+declare class MarkTable {
+    /** Column name → declared type, accumulated as the union across every declared kind. */
+    private readonly columnTypes;
+    /** Kind name → the column names that kind owns. */
+    private readonly kindColumns;
+    private readonly rows;
+    /** Declares a mark kind and the columns it carries. Throws if the kind repeats or a column's type conflicts. */
+    kind(name: string, columns: MarkColumnSchema): this;
+    /** Appends one row for a declared kind. Throws if the kind is unknown, or a value misses/overshoots the kind's columns. */
+    push(kind: string, values: Record<string, DataValue>): this;
+    /** Materialises the rows into a {@link Dataset}, null-padding every off-kind column. */
+    toDataset(options: ToDatasetOptions): Dataset;
+}
+
 declare function mean(): MeanStatSpec;
 
 /**
@@ -4353,14 +5186,16 @@ declare type NeonPaletteConfig = {
 declare type NeonPaletteVariant = 'default' | 'waterfall';
 
 /**
- * Configuration for formatting a single number.
- * Defines how numeric values should be displayed in the chart.
+ * Chart-wide number formatting, applied by the renderer to every numeric value
+ * (axis ticks, tooltips, data labels, headline figures). Set via
+ * `config({ numberFormat: { … } })`.
  */
 export declare interface NumberFormatConfig {
     /**
      * Number of decimal places to display.
      * - number: Fixed decimal places (e.g., 2 → "1234.56")
-     * - 'auto': Automatic based on value magnitude (default)
+     * - 'auto': Automatic based on value magnitude
+     * @default 'auto'
      */
     decimals: number | 'auto';
     /**
@@ -4370,6 +5205,7 @@ export declare interface NumberFormatConfig {
      * - 'k': Force thousands (1234567 → "1,234.6K")
      * - 'm': Force millions (1234567 → "1.2M")
      * - 'b': Force billions (1234567890 → "1.2B")
+     * @default 'auto'
      */
     abbreviation: 'auto' | 'k' | 'm' | 'b' | 'none';
     /**
@@ -4398,7 +5234,13 @@ declare interface NumericValueFormat {
     type: 'decimal' | 'integer' | 'percentage' | 'duration';
 }
 
-/** A single row of data, mapping every variable name to the value in that row. */
+/**
+ * One compiled per-observation record — the unit a geom's render half iterates and reads to paint a
+ * single mark. Maps every variable name (the author's data columns plus the compiler's internal
+ * position/visual/group columns) to that observation's value. Read positions and encodings off it with
+ * the value readers ({@link getX}, {@link getYMin}, {@link getColor}, …) rather than indexing internal
+ * keys by hand; read your own named columns with `readNumber`/`readString`.
+ */
 export declare type Observation = Record<VariableName, DataValue>;
 
 /**
@@ -4417,13 +5259,16 @@ export declare interface ObservationAnchor {
     groupValue: DataValue;
 }
 
-/** Points at a single observation by its anchor value and series. */
+/**
+ * Snaps to a single data observation by its main-axis value and series. The annotation tracks that
+ * observation across resize and re-layout (unlike panel-fractional positioning).
+ */
 export declare interface ObservationAnchorInput {
-    /** Pick a specific layer when multiple share the same `(anchorValue, groupValue)` pair. */
+    /** Pick a specific layer when multiple share the same `(anchorValue, groupValue)` pair. Index into the spec's layers. */
     layerIndex?: number;
-    /** Value on the main axis (x in cartesian, y in flipped). */
+    /** Value on the main axis (x in cartesian, y in flipped) that selects the observation. */
     anchorValue: DataValue;
-    /** Series identity (the `group` aesthetic value). */
+    /** Series identity — the `color`/`group` aesthetic value that disambiguates within the axis value. */
     groupValue: DataValue;
 }
 
@@ -4455,13 +5300,15 @@ declare interface PaletteScaleSpec {
  * Panel configuration
  */
 declare interface PanelConfig {
+    /** Border drawn around the plot panel (the data area). */
     border: {
+        /** Whether the panel border is rendered. */
         isVisible: boolean;
     };
 }
 
 /**
- * A render-side hit-test a Tier-C geom registers for a `render-hit-test` layer. The engine calls it
+ * A render-side hit-test a geom-layout geom registers for a `render-hit-test` layer. The engine calls it
  * with the cursor in panel `[0, 1]` space using a **top-left origin (y-down)** — the same frame the
  * geom paints in (unit-space SVG / `toPercent`), so the geom can test against its own rendered
  * geometry without re-flipping. It returns the declared identity `key` of the observation under the
@@ -4518,19 +5365,29 @@ declare interface PieOptions {
  * Pinned-number annotation: a marker dot pinned to a single observation. The
  * renderer's mini view shows the observation's measurement value; hover reveals
  * the full tooltip (x + y + trend).
+ *
+ * NO PAINTER in `@graphysdk/react-renderer` — this compiles but never draws there (it renders only in
+ * the editor's legacy engine). Don't reach for it when authoring for the React renderer.
  */
 declare interface PinnedNumberAnnotationInput {
     id?: string;
     anchor: ObservationAnchorInput;
 }
 
+/** Resolved form of {@link PinnedNumberAnnotationInput} — defaults applied, anchor normalised. */
 declare interface PinnedNumberAnnotationSpec {
     id: string;
     anchor: ObservationAnchor;
 }
 
 /**
- * Pipe a spec through a series of spec items (left-to-right).
+ * 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());
  */
 export declare function pipe(spec: SpecInput, ...items: SpecItem[]): SpecInput;
 
@@ -4560,6 +5417,20 @@ export declare interface PlacedDataLabel {
     position: DataLabelPosition;
 }
 
+/**
+ * Point marks — scatter plots and bubble charts. Map `size` to a column for a bubble chart and `color` for
+ * categorical series. Sizing is controlled via {@link PointGeomParams} `size` or `scale.size.continuous`.
+ *
+ * @example
+ * pipe(
+ *   createSpec({ x: 'gdp', y: 'lifeExp', size: 'population', color: 'continent' }),
+ *   geom.point(),
+ *   scale.x(),
+ *   scale.y(),
+ *   scale.size.continuous({ range: [4, 40] }),
+ *   scale.color.palette(),
+ * );
+ */
 declare function point(options?: GeomOptions<'point'>): LayerInputOf<'point'>;
 
 /**
@@ -4578,9 +5449,14 @@ declare class PointGeom extends Geom {
 }
 
 /**
- * Point-specific parameters
+ * Render parameters for `geom.point`. Passed under `params`.
  */
 declare interface PointGeomParams {
+    /**
+     * Mark diameter in pixels, used when `size` is not a data channel. To size by data instead, map the `size`
+     * aesthetic and declare `scale.size.continuous({ range })`.
+     * @default 8
+     */
     size: number;
 }
 
@@ -4596,19 +5472,28 @@ declare interface PolarCoordInput {
 }
 
 /**
- * Params for polar coordinate system
+ * Resolved params for the polar coordinate system (defaults applied).
+ * Drives pie, donut, and radar/radial layouts by mapping one scaled aesthetic to the
+ * angle and the other to the radius.
  */
 declare interface PolarCoordParams extends BaseCoordParams {
     /**
-     * Which aesthetic maps to theta (angle): 'x' or 'y'
+     * Which aesthetic becomes the angle (theta); the other aesthetic becomes the radius,
+     * scaled into `[innerRadius, 1]`. Use `'y'` for pie/donut (stacked value → angle),
+     * `'x'` for radar (one spoke per category).
+     * @default 'x'
      */
     theta: 'x' | 'y';
     /**
-     * Starting angle in degrees
+     * Rotation offset of the whole layout, in degrees. Shifts where the first datum begins;
+     * the full sweep is 360°.
+     * @default 0
      */
     startAngle: number;
     /**
-     * Inner radius as fraction 0-1 (for donut charts)
+     * Hole radius as a fraction of the outer radius, `0`–`1`. `0` is a full pie;
+     * any value `> 0` produces a donut (e.g. `0.55`).
+     * @default 0
      */
     innerRadius: number;
 }
@@ -4631,6 +5516,13 @@ export declare interface PolarCoordSystem {
     axisMapping: AxisMapping;
     /** Donut hole radius as a fraction of the outer radius (0-1). 0 for a full pie. */
     innerRadius: number;
+    /**
+     * Angular offset, in radians, applied to every angular position — the spec's `startAngle` (degrees)
+     * converted once at setup. The polar guide renderer recovers a tick's angle as `position * 2π +
+     * startAngle`, matching the angular transform the coord applies to the data, so spokes/labels align
+     * with the painted marks.
+     */
+    startAngle: number;
 }
 
 export declare const POSITION_VARIABLES: {
@@ -4723,7 +5615,7 @@ declare interface PositionalScaleMethods {
  * derives from. A geom's channels are the manifest the position mapper and coord projection iterate
  * instead of hardcoding the column set.
  */
-declare type PositionChannel = RolePositionChannel | ScalarPositionChannel;
+export declare type PositionChannel = RolePositionChannel | ScalarPositionChannel;
 
 declare interface PositionChannelBase {
     axis: ChannelAxis;
@@ -4771,6 +5663,10 @@ export declare type PositionType = 'stack' | 'dodge' | 'identity' | 'fill';
  */
 declare type PositionValueKind = 'value' | 'bandOffset';
 
+/**
+ * Selects which observations a highlight emphasises: either a single-column
+ * {@link VariablePredicate} or a {@link LogicalPredicate} combining several.
+ */
 export declare type Predicate = VariablePredicate | LogicalPredicate;
 
 export declare const prefixInternalVariable: (name: string) => string;
@@ -4793,11 +5689,51 @@ declare interface QuantitativeScaleMethods {
     identity: (options?: IdentityScaleOptions) => IdentityScaleInput;
 }
 
+/**
+ * The radial span of an arc/wedge in a polar coord, in `[0,1]` (0 = centre, 1 = outer ring).
+ * `innerRadius` is `null` when the observation declares no y interval; `outerRadius` falls back to the
+ * `point` radius when no upper endpoint exists. Returned by {@link getRadiusExtent}.
+ */
 export declare interface RadiusExtent {
     innerRadius: NumericDataValue;
     outerRadius: NumericDataValue;
 }
 
+/**
+ * Reads an aesthetic value by an open channel name — built-in (`x`, `color`, …) or custom. A custom
+ * geom maps extra channels (a box plot's `q1`/`median`/`q3`, an error bar's bounds) under names outside
+ * the closed {@link AestheticKey} set; those keys ride in the mapping at runtime and are read here
+ * through the one sanctioned widening, so a channel's value is sourced from `aes` rather than `params`.
+ */
+export declare function readAesthetic(aesMapping: AesMapping, name: string): AestheticValue | undefined;
+
+/**
+ * Reads a value by **column name** from an observation, as a number. Use this for the columns a custom
+ * geom named itself (via `variableFor(axis, name)` for scalar channels, or `addVariable` in `compile()`)
+ * — the position readers (`getX`, `getYMin`, …) and visual readers (`getColor`, …) cover the built-in
+ * channels by their fixed internal keys, but there is no typed accessor for an author-named column, and
+ * this fills that gap. The returned number is **whatever was written to that column** (a scalar channel
+ * is already scaled to `[0,1]`; a plain `addVariable` value is in its original units — it carries no
+ * scaling on its own).
+ *
+ * Shares the readers' null-discipline: a missing or wrong-typed value is `null`, never silently coerced
+ * to `0`. Pass `fallback` to opt into a default for genuinely-missing values; the overload then narrows
+ * the return to `number`, so a geom that wants `0`-on-missing says so explicitly.
+ */
+export declare function readNumber(observation: Observation, key: string): number | null;
+
+export declare function readNumber(observation: Observation, key: string, fallback: number): number;
+
+/**
+ * Reads a value by **column name** from an observation, as a string — the string counterpart to
+ * {@link readNumber}, for author-named categorical/label columns a custom geom wrote in `compile()`.
+ * A missing or wrong-typed value is `null` unless a `fallback` is given (the overload then narrows the
+ * return to `string`).
+ */
+export declare function readString(observation: Observation, key: string): string | null;
+
+export declare function readString(observation: Observation, key: string, fallback: string): string;
+
 /** A rectangle in pixel coordinates, origin at top-left. */
 export declare interface Rect {
     x: number;
@@ -4857,6 +5793,11 @@ declare function reshape(options?: ReshapeOptions): ReshapeTransformInput;
 /***************************************************************
  * Reshape Transform
  ***************************************************************/
+/**
+ * Options for `transform.reshape` — pivots a wide table to long ("tidy") form by collapsing
+ * several numeric columns into two: a key column (the original column name) and a value column.
+ * The idiom for turning a multi-metric table into a single series mappable by `color`.
+ */
 declare interface ReshapeOptions {
     /**
      * Numeric variables to collapse into rows.
@@ -4880,6 +5821,7 @@ declare interface ReshapeOptions {
     valueName?: VariableName;
 }
 
+/** Pivot-to-long transform produced by `transform.reshape`. */
 declare interface ReshapeTransformInput {
     type: 'transform';
     transformType: 'reshape';
@@ -4918,6 +5860,12 @@ export declare interface ResolvedObservationAnchor extends AnchorPosition {
     color: string | undefined;
 }
 
+/**
+ * A fully-resolved stat spec: a built-in {@link StatSpec} or a custom stat's `{ type, ...options }`.
+ * What the {@link StatCompiler} dispatches on and a stat's `compute` receives.
+ */
+export declare type ResolvedStatSpec = StatSpec | CustomStatInput;
+
 /**
  * A custom annotation's coordinate resolved to normalized panel space, in **top-left [0,1]** — the
  * space the draw function paints in. `observation` is attached only for a snap-to-observation
@@ -4963,15 +5911,35 @@ export declare function resolveYScaleAesthetic(yScaleType: YScaleType): ScaledAe
  */
 export declare const RESTING_HOVER_STATE: HoverState;
 
-/** TipTap-compatible rich text node (no tiptap dependency). */
+/**
+ * A node in a ProseMirror/TipTap-style rich-text document tree (no tiptap
+ * dependency). NOT a plain string — it is a recursive node where `content`
+ * holds child nodes and a leaf text node carries `text`. Used both for chart
+ * titles/captions and for text annotation bodies.
+ *
+ * The root is a `{ type: 'doc' }` node; block children are `'paragraph'` or
+ * `'heading'` (with `attrs.level`); inline runs are `'text'` nodes whose
+ * `marks` apply styling (e.g. `{ type: 'bold' }`, `{ type: 'italic' }`,
+ * `{ type: 'link', attrs: { href } }`). Plain prose is one paragraph of one
+ * text node:
+ *
+ * ```ts
+ * { type: 'doc', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Quarterly sales' }] }] }
+ * ```
+ */
 export declare interface RichTextContent {
+    /** Node kind: `'doc'` (root), `'paragraph'`, `'heading'`, `'text'`, etc. */
     type?: string;
+    /** Child nodes. Present on container nodes; absent on `'text'` leaves. */
     content?: RichTextContent[];
+    /** The literal string carried by a `'text'` leaf node. */
     text?: string;
+    /** Inline formatting applied to a `'text'` node (bold, italic, link, …). */
     marks?: Array<{
         type: string;
         attrs?: Record<string, unknown>;
     }>;
+    /** Node attributes, e.g. `{ level: 2 }` on a heading or `{ href }` on a link mark target. */
     attrs?: Record<string, unknown>;
 }
 
@@ -4986,6 +5954,18 @@ declare interface RolePositionChannel extends PositionChannelBase {
     name?: string;
 }
 
+/**
+ * Rule marks — a single horizontal or vertical reference line, the built-in for goal/threshold/average
+ * lines (no custom geom needed). Pin a constant with `aes: { y: { value } }` (horizontal) or
+ * `aes: { x: { value } }` (vertical, numeric x), or compute a data-driven line with `stat.mean()`. Style and
+ * label it via {@link RuleGeomParams}; set `interactive: false` so it doesn't take hover.
+ *
+ * @example
+ * // Constant goal line at y = 2500
+ * geom.rule({ aes: { y: { value: 2500 } }, params: { label: 'Target', lineType: 'dashed', labelPosition: 'start' } });
+ * // Data-driven average line
+ * geom.rule({ aes: { y: 'revenue' }, stat: stat.mean(), params: { label: 'Average' }, interactive: false });
+ */
 declare function rule(options?: GeomOptions<'rule'>): LayerInputOf<'rule'>;
 
 /**
@@ -5008,20 +5988,34 @@ declare class RuleGeom extends Geom {
 }
 
 /**
- * Rule-specific parameters.
+ * Render parameters for `geom.rule`. Passed under `params`. The line's value comes from `aes`
+ * (`{ y: { value } }` or `stat.mean()`), not from here — these are styling and labelling only.
  */
 export declare interface RuleGeomParams {
-    /** Stroke color; falls back to a theme token. */
+    /** Stroke color (any CSS color). Falls back to a theme token when omitted. */
     color?: string;
+    /**
+     * Stroke width in pixels.
+     * @default 1
+     */
     strokeWidth: number;
+    /**
+     * Dash style of the line.
+     * @default 'dashed'
+     */
     lineType: LineStyleType;
-    /** Optional inline text label rendered alongside the line. */
+    /** Optional inline text label rendered alongside the line (e.g. `'Target'`, `'Average'`). */
     label?: string;
+    /**
+     * Which end of the line the `label` is anchored to.
+     * @default 'start'
+     */
     labelPosition: RuleLabelPosition;
 }
 
 /**
- * Where the optional inline label is anchored along a reference line.
+ * Where the optional inline label sits along a reference line: `'start'` (left/top end) or `'end'`
+ * (right/bottom end).
  */
 export declare type RuleLabelPosition = 'start' | 'end';
 
@@ -5053,6 +6047,31 @@ declare abstract class Scale {
     abstract compile(spec: ScaleSpec, values: DataValue[]): CompiledScale;
 }
 
+/**
+ * Scale builder — declares how each mapped variable is turned into a visual value
+ * (axis position, color, size, …). Pipe the result onto a spec.
+ *
+ * Position scales must be declared EXPLICITLY: the builder never auto-infers `x`/`y`,
+ * so omitting `scale.x()` / `scale.y()` yields NaN positions. `scale.x`/`.y`/`.ySecondary`
+ * are callable for an inferred scale (type auto-detected from the data) or expose explicit
+ * sub-methods: `.continuous` / `.discrete` / `.datetime` / `.log` / `.sqrt`. Use
+ * `scale.x.discrete()` for categorical or temporal-string axes.
+ *
+ * Non-position aesthetics auto-infer from the mapping, so their scale entry is optional —
+ * add one only to override the default (e.g. `scale.color.palette()`, `scale.size.continuous({ range })`).
+ *
+ * @example
+ *   import { pipe, createSpec, geom, scale } from '@graphysdk/viz-engine';
+ *
+ *   pipe(
+ *     createSpec({ x: 'gdp', y: 'lifeExp', size: 'population', color: 'continent' }),
+ *     geom.point(),
+ *     scale.x.log({ domainMin: 1 }),
+ *     scale.y.continuous({ zero: false, nice: true }),
+ *     scale.size.continuous({ range: [4, 40] }),
+ *     scale.color.palette()
+ *   );
+ */
 export declare const scale: ScaleAPI;
 
 declare interface ScaleAPI {
@@ -5159,10 +6178,13 @@ export declare type ScaledAestheticKey = ScaledPositionAestheticKey | ScaledVisu
 
 declare type ScaledPositionAestheticKey = 'x' | 'y' | 'ySecondary';
 
-declare type ScaledVisualAestheticKey = 'color' | 'size' | 'alpha' | 'strokeWidth' | 'lineType';
+export declare type ScaledVisualAestheticKey = 'color' | 'size' | 'alpha' | 'strokeWidth' | 'lineType';
 
 /**
- * Union type for all possible scale specifications (including inferred, pre-resolution).
+ * Any value the `scale` builder produces, before resolution. Each pipe item carries the
+ * target aesthetic plus its scale type and options; an `inferred` entry has its concrete
+ * type chosen from the data during compilation. This is the type accepted by the spec
+ * pipeline — author scales with the `scale` builder rather than constructing it by hand.
  */
 declare type ScaleInput = ContinuousScaleInput | DiscreteScaleInput | PaletteScaleInput | DatetimeScaleInput | IdentityScaleInput | InferredScaleInput;
 
@@ -5171,8 +6193,9 @@ declare class ScaleRegistry extends Registry<ScaleType, Scale> {
 }
 
 /**
- * Union of scale specs that can appear after resolution (all fields required).
- * InferredScaleInput is resolved to a concrete type during spec resolution.
+ * A fully resolved scale (every option defaulted) as it appears on the compiled spec.
+ * The `inferred` variant has already been collapsed to one of these concrete types
+ * during resolution, so this union has no `inferred` member.
  */
 declare type ScaleSpec = ContinuousScaleSpec | DiscreteScaleSpec | DatetimeScaleSpec | IdentityScaleSpec | PaletteScaleSpec;
 
@@ -5386,27 +6409,37 @@ declare type SetScaleDomainParams = {
 };
 
 /**
- * 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.
+ * A shaded box layered onto the panel. Position and size are panel fractions (`[0,1]`, top-left
+ * origin) — NOT data values — so the shape re-flows on resize but does not snap to a data point. Use a
+ * difference arrow or a custom annotation when you need data anchoring.
  */
 export declare interface ShapeInput {
     id?: string;
+    /** @default 'rectangle' */
     kind?: ShapeKind;
+    /** @default 'foreground' */
     zOrder?: ShapeZOrder;
+    /** Left edge as a `[0,1]` fraction of panel width (0 = left). */
     x: number;
+    /** Top edge as a `[0,1]` fraction of panel height (0 = top). */
     y: number;
+    /** Width as a `[0,1]` fraction of panel width. */
     width: number;
+    /** Height as a `[0,1]` fraction of panel height. */
     height: number;
+    /** @default 'transparent' */
     fillColor?: string;
+    /** Fill alpha, `[0,1]`. @default 1 */
     fillOpacity?: number;
+    /** Stroke width in pixels. @default 1 */
     strokeWidth?: number;
-    /** null falls back to the theme `defaultAnnotationShapeStroke`. */
+    /** `null` falls back to the theme `defaultAnnotationShapeStroke`. @default null */
     strokeColor?: string | null;
 }
 
 export declare type ShapeKind = 'rectangle';
 
+/** Resolved form of {@link ShapeInput} — defaults applied. */
 export declare interface ShapeSpec {
     id: string;
     kind: ShapeKind;
@@ -5427,7 +6460,9 @@ export declare interface ShapeSpec {
 export declare type ShapeZOrder = 'background' | 'foreground';
 
 /**
- * Builder for the smooth stat.
+ * Builder for the smooth stat — fits a regression trendline through the observations.
+ * Pair with `geom.line` for a drawn trendline. `order` applies only to `'polynomial'`,
+ * `bandwidth` only to `'loess'`; both are ignored by the other methods.
  *
  * @example
  *   geom.line({ stat: stat.smooth({ method: 'linear' }) })
@@ -5441,7 +6476,14 @@ declare function smooth(options: {
 }): SmoothStatInput;
 
 /**
- * Regression methods supported by the `smooth` stat.
+ * Regression/trendline method fitted by the `smooth` stat through the observations:
+ * - `'linear'` — straight line of best fit (`y = a + b·x`). The default.
+ * - `'loess'` — locally weighted smoothing; follows local structure. Tune with `bandwidth`.
+ * - `'exponential'` — `y = a·e^(b·x)`; constant-rate growth/decay.
+ * - `'logarithmic'` — `y = a + b·ln(x)`; fast early then flattening.
+ * - `'quadratic'` — parabola (`y = a + b·x + c·x²`); a single bend.
+ * - `'power'` — `y = a·x^b`; scale-free relationships.
+ * - `'polynomial'` — degree-`order` polynomial; multiple bends. Tune with `order`.
  */
 export declare type SmoothMethod = 'linear' | 'loess' | 'exponential' | 'logarithmic' | 'quadratic' | 'power' | 'polynomial';
 
@@ -5451,7 +6493,9 @@ export declare type SmoothMethod = 'linear' | 'loess' | 'exponential' | 'logarit
 declare interface SmoothStatInput {
     type: 'smooth';
     method: SmoothMethod;
+    /** Polynomial degree. Only used when `method: 'polynomial'`. @default 3 */
     order?: number;
+    /** LOESS smoothing window as a fraction (0–1) of the data. Only used when `method: 'loess'`. @default 0.3 */
     bandwidth?: number;
 }
 
@@ -5469,9 +6513,18 @@ declare interface SmoothStatSpec {
 
 declare function sort(options: SortOptions): SortTransformInput;
 
+/**
+ * Sorts the data by the x variable if it is numeric or temporal.
+ */
+export declare const sortByXIfContinuous: (data: Dataset, mapping: AesMapping) => Dataset;
+
 /***************************************************************
  * Sort Transform
  ***************************************************************/
+/**
+ * Options for `transform.sort` — reorders observations by one variable. Affects draw order
+ * and the order categories are first seen (and thus discrete-scale domain order).
+ */
 declare interface SortOptions {
     /** The variable to sort by. */
     variableName: VariableName;
@@ -5479,15 +6532,18 @@ declare interface SortOptions {
     direction?: 'asc' | 'desc';
 }
 
+/** Observation-ordering transform produced by `transform.sort`. */
 declare interface SortTransformInput {
     type: 'transform';
     transformType: 'sort';
     options: SortOptions;
 }
 
-/** Data-source attribution shown under the caption. */
+/** Data-source attribution shown under the caption: a `label` and optional `url`. */
 export declare interface SourceContent {
+    /** Displayed attribution text, e.g. `'Internal pipeline'`. */
     label?: string;
+    /** Optional link the label points to. */
     url?: string;
 }
 
@@ -5496,19 +6552,26 @@ export declare interface SourceContent {
  * runtime's index builders, so the descriptor lets the engine dispatch on declared data instead
  * of branching on the geom name.
  *
- * `render-hit-test` is the Tier-C escape hatch: the geom's geometry comes from a layout algorithm,
+ * `render-hit-test` is the geom-layout escape hatch: the geom's geometry comes from a layout algorithm,
  * not from scales, so the compiler cannot build a spatial index from position columns. The geom
  * instead provides a render-side hit-test function (injected per-instance through the renderer),
  * and the engine resolves the observation it returns against the declared identity key. Only the
  * kind rides in the compiled spec — the closure never crosses the serialisable boundary.
+ *
+ * `polar-points` is the polar refinement of `points` (a radar's vertices read in polar). The cursor
+ * and the vertices live in incompatible spaces for the cartesian nearest query — vertices are
+ * `(angle, radius)`, the cursor is plot-local `[0,1]` — so the polar query converts each at query
+ * time (no stored cartesian, no Delaunay), staying correct across resizes. Geoms never declare it; a
+ * polar coord refines a `points`-natural mark to it during the coord transform.
  */
-declare type SpatialIndexKind = 'buckets' | 'rects' | 'points' | 'arcs' | 'noop' | 'render-hit-test';
+export declare type SpatialIndexKind = 'buckets' | 'rects' | 'points' | 'arcs' | 'noop' | 'render-hit-test' | 'polar-points';
 
 /**
  * A layer's geometry-agnostic hit-test declaration. Pure serialisable data riding in the compiled
  * spec: it names the spatial structure the marks present so the runtime can build the matching
  * index without knowing which geom produced it. A geom declares its cartesian-natural kind on its
- * definition; a polar coord refines it to `arcs` during the coord transform.
+ * definition; a polar coord refines it to `arcs` (filled wedges) or `polar-points` (radar vertices)
+ * during the coord transform.
  */
 declare interface SpatialMapDescriptor {
     kind: SpatialIndexKind;
@@ -5554,17 +6617,30 @@ export declare interface Spec {
 }
 
 /**
- * The canonical spec type — plain JSON, serializable. Data is provided separately
- * (as a `Data` value to {@link compile}, or as a prop to `<GraphProvider>`).
+ * The canonical spec type — plain JSON, serializable. Built by `createSpec`/`pipe`; data is provided
+ * separately (as a `Data` value to {@link compile}, or as a prop to `<GraphProvider>`). Hand-construct it
+ * only when you cannot use the builders; otherwise prefer `pipe(createSpec({...}), geom.x(), scale.x(), ...)`.
  */
 export declare interface SpecInput {
+    /** Global aesthetic mapping (data columns → channels); layer `aes` overrides merge over this. */
     mapping: AesMapping;
+    /** Geometry layers to render, in draw order. One entry per `geom.*` call. */
     layers: LayerInput[];
+    /**
+     * Scale declarations, one per aesthetic. Position scales (`scale.x`/`scale.y`/`scale.ySecondary`) are NOT
+     * auto-inferred — declare them explicitly or position channels resolve to NaN. Visual scales
+     * (`color`/`size`/...) are inferred from the data when omitted.
+     */
     scales: ScaleInput[];
+    /** Spec-level data transforms applied before any layer is compiled (reshape, filter, ...). */
     transforms: TransformInput[];
+    /** Predicate-driven emphasis rules that dim or accentuate matching observations. */
     highlights: HighlightInput[];
+    /** Annotation overlays — difference arrows, shapes, text, freeform arrows. Optional. */
     annotations?: AnnotationsInput;
+    /** Coordinate system: cartesian (default), `coord.flip()`, or `coord.polar(...)`. Optional. */
     coords?: CoordInput;
+    /** Chart configuration: titles/captions, legend, axes, number format, headline, appearance. */
     config: ConfigInput;
 }
 
@@ -5581,6 +6657,18 @@ export declare class SpecResolver {
     }): Spec;
 }
 
+/**
+ * Render a {@link SpecInput} as fluent builder source — `pipe(createSpec({…}), geom.x(…), scale.x(…),
+ * config({…}))` — emitting only values that differ from their defaults. Returns `null` when the spec
+ * contains something the builder form cannot faithfully represent (a custom geom, a transform, a polar
+ * coord, …), so the caller can fall back to a literal object and never lose data.
+ *
+ * The defaults are static (data-independent), so this needs no dataset. Position scales are emitted in
+ * the inferred `scale.x(opts)` form on purpose: the resolver only applies context defaults (e.g. a bar
+ * chart's `zero: true`) to inferred scales, so converting them to an explicit type would change the chart.
+ */
+export declare function specToBuilderSource(input: SpecInput): string | null;
+
 export declare interface StackTotalEntry {
     /** Serialised x value for stable join keys across observations. */
     xKey: string;
@@ -5623,9 +6711,11 @@ declare abstract class Stage<Input, Output> {
 
 /**
  * Base class for statistical transformations applied to layer data (e.g. binning, counting, smoothing).
+ * Built-ins use a literal {@link StatName}; custom stats authored with `defineStat` carry any registered
+ * `type` string ({@link StatIdentity}).
  */
-declare abstract class Stat {
-    abstract readonly type: StatName;
+export declare abstract class Stat {
+    abstract readonly type: StatIdentity;
     /**
      * Aesthetics this stat will compute (e.g. count computes 'y'). Used by validation to skip existence checks.
      */
@@ -5634,6 +6724,23 @@ declare abstract class Stat {
     protected abstract computeStat(input: StatCompilerInput): CompiledStat;
 }
 
+/**
+ * Statistical-transform builder — sets a geom's `stat`, replacing each layer's raw observations
+ * with a derived summary before positions are computed. Defaults to `identity` (raw data).
+ *
+ * - `identity()` — pass observations through unchanged (the default).
+ * - `count()` — number of observations per x value, written to `y`; do NOT also map `y`.
+ * - `mean()` — reduce the mapped `y` to its average (a single value); the idiom for an
+ *   average line (`geom.rule({ stat: stat.mean() })`).
+ * - `smooth({ method })` — fit a regression trendline; the idiom for a trendline
+ *   (`geom.line({ stat: stat.smooth({ method: 'linear' }) })`).
+ *
+ * @example
+ *   import { geom, stat } from '@graphysdk/viz-engine';
+ *
+ *   geom.rule({ aes: { y: 'revenue' }, stat: stat.mean(), params: { label: 'Average' } });
+ *   geom.line({ stat: stat.smooth({ method: 'linear' }), interactive: false });
+ */
 export declare const stat: {
     identity: typeof identity;
     count: typeof count;
@@ -5642,25 +6749,28 @@ export declare const stat: {
 };
 
 /**
- * Resolves a stat by name and delegates computation.
+ * Resolves stats by name and delegates computation. A layer's `stat` is an ordered pipeline (Decision 8):
+ * each step sees the dataset and effective mapping produced by the previous step, so a later stat can read
+ * an earlier stat's emitted column. Returns the net mapping overrides (last-writer-wins) for the caller to
+ * merge over the layer's effective mapping.
  */
 declare class StatCompiler {
     private readonly registry;
     constructor(registry: StatRegistry);
-    compute(spec: StatSpec, input: {
+    compute(specs: ResolvedStatSpec[], input: {
         data: Dataset;
         mapping: AesMapping;
         xScaleIsDiscrete: boolean;
     }): CompiledStat;
 }
 
-declare interface StatCompilerInput {
+export declare interface StatCompilerInput {
     /** The input dataset. */
     data: Dataset;
     /** The effective mapping for the layer. */
     mapping: AesMapping;
-    /** The resolved stat spec. Narrow by `spec.type` to access stat-specific params. */
-    spec: StatSpec;
+    /** The resolved stat spec (built-in or custom). Narrow by `spec.type` to access stat-specific params. */
+    spec: ResolvedStatSpec;
     /**
      * Whether the x aesthetic resolves to a discrete (band) scale. The `smooth` stat emits one fitted
      * point per observed x when set.
@@ -5669,9 +6779,70 @@ declare interface StatCompilerInput {
 }
 
 /**
- * User-facing stat input — either a {@link StatName} string shorthand or an object spec.
+ * A registered custom stat: a {@link Stat} the compiler consumes, carrying the resolved-spec type so
+ * `createGraphyBuilder({ stats })` can type its `stat.<type>(options)` builder method.
+ */
+export declare interface StatDef<TSpec extends StatSpecBase = StatSpecBase> extends Stat {
+    readonly type: TSpec['type'] & string;
+    /**
+     * Phantom — carries the resolved-spec type to the type level so the registration-typed builder can
+     * recover the stat's options. Never set at runtime.
+     */
+    readonly __spec?: TSpec;
+}
+
+/**
+ * The compute input an authored stat receives: the standard {@link StatCompilerInput}, but with `spec`
+ * narrowed to the stat's own resolved spec `TSpec`, plus a `column` helper that namespaces a declared
+ * computed column to a collision-safe internal name (Decision 9).
+ */
+export declare interface StatDefinitionInput<TSpec extends StatSpecBase = StatSpecBase> extends Omit<StatCompilerInput, 'spec'> {
+    /** The resolved spec for this stat — its `type` plus the options the builder passed. */
+    spec: TSpec;
+    /**
+     * Namespaces a column declared in `computedColumns` to `\0graphy\0_<type>_<local>` — globally unique,
+     * so a stat's output can never collide with a user column or another stat. Throws on an undeclared name.
+     * Write the returned name into `addVariable`/`addConstantVariable` and into any `mapping` rebinding.
+     */
+    column: (localName: string) => string;
+}
+
+/**
+ * The manifest passed to {@link defineStat}. Declares the stat's `type`, the columns it emits
+ * (`computedColumns`, namespaced per-type), the aesthetics it rebinds (`computedVariables`, which waive
+ * the validator's pre-stat existence/required checks), and the `compute` itself.
+ */
+export declare interface StatDefinitionManifest<TSpec extends StatSpecBase = StatSpecBase> {
+    /** The registered stat name; keys both the registry and the `stat.<type>(...)` builder method. */
+    type: TSpec['type'] & string;
+    /** Local names of the columns `compute` emits via `column(...)`. Namespaced per-type for collision-safety. */
+    computedColumns?: readonly string[];
+    /** Aesthetics `compute` rebinds (e.g. `'y'`). Waives the validator's pre-stat existence/required checks. */
+    computedVariables?: readonly AestheticKey[];
+    /** Derives the layer's summary from its dataset. Not called on an empty dataset (the base short-circuits). */
+    compute: (input: StatDefinitionInput<TSpec>) => CompiledStat;
+}
+
+/**
+ * The open identity of a stat: a built-in {@link StatName} or any custom stat's `type` string
+ * registered via `createCompiler({ stats })`. The `& {}` keeps the built-in names as autocomplete
+ * candidates without collapsing the union to bare `string` (mirrors `GeomIdentity`).
+ */
+export declare type StatIdentity = StatName | (string & {});
+
+/**
+ * Any value the `stat` builder produces — passed as the `stat` option of a geom.
+ * The string-shorthand variants (`stat.identity()`, `stat.count()`, `stat.mean()`) carry only
+ * a `type`; `smooth` additionally carries the regression parameters.
+ */
+export declare type StatInput = IdentityStatSpec | CountStatSpec | SmoothStatInput | MeanStatSpec;
+
+/**
+ * A single stat a layer's `stat` option accepts — a built-in name, a built-in {@link StatInput}, or a
+ * custom stat input. A layer's `stat` is one of these or an ordered list of them (Decision 8): each step
+ * sees the previous step's emitted columns, e.g. `[stat.percentOfTotal(...), stat.window({ op: 'rank' })]`.
  */
-declare type StatInput = IdentityStatSpec | CountStatSpec | SmoothStatInput | MeanStatSpec;
+declare type StatLayerInput = StatName | StatInput | CustomStatInput;
 
 /**
  * Statistical transformation applied to data before rendering.
@@ -5681,22 +6852,43 @@ 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`
  */
-declare type StatName = 'identity' | 'count' | 'smooth' | 'mean';
+export declare type StatName = 'identity' | 'count' | 'smooth' | 'mean';
 
 /**
- * Built-in stat implementations keyed by {@link StatName}.
+ * The options a registered custom stat's builder method accepts — its resolved spec minus the `type`
+ * discriminant (the builder fills `type`). Recovered structurally from the definition's phantom spec.
  */
-declare class StatRegistry extends Registry<StatName, Stat> {
-    constructor();
+declare type StatOptionsOf<Definition> = Definition extends StatDef<infer TSpec> ? Omit<TSpec, 'type'> : never;
+
+/**
+ * Stat implementations keyed by `type`. Built-ins are registered first; any custom stats injected via
+ * `createCompiler({ stats })` register afterwards (a custom `type` matching a built-in overrides it,
+ * last write wins) — mirroring `GeomRegistry`.
+ */
+declare class StatRegistry extends Registry<string, Stat> {
+    constructor(opts?: {
+        stats?: readonly Stat[];
+    });
 }
 
 /**
- * Discriminated union of all resolved stat specs (post-resolution).
+ * Discriminated union of all built-in resolved stat specs (post-resolution).
  */
-declare type StatSpec = IdentityStatSpec | CountStatSpec | SmoothStatSpec | MeanStatSpec;
+export declare type StatSpec = IdentityStatSpec | CountStatSpec | SmoothStatSpec | MeanStatSpec;
+
+/**
+ * The minimal shape every stat spec shares: its `type` discriminant. A custom stat's resolved spec
+ * extends this with arbitrary plain-data options; `defineStat<TSpec>` narrows `TSpec` from it.
+ */
+export declare interface StatSpecBase {
+    type: StatIdentity;
+}
 
 /**
  * Sticker annotation: a built-in emoji-like image pinned to a single observation.
+ *
+ * NO PAINTER in `@graphysdk/react-renderer` — this compiles but never draws there (it renders only in
+ * the editor's legacy engine). Don't reach for it when authoring for the React renderer.
  */
 declare interface StickerAnnotationInput {
     id?: string;
@@ -5704,6 +6896,7 @@ declare interface StickerAnnotationInput {
     sticker: StickerId;
 }
 
+/** Resolved form of {@link StickerAnnotationInput} — defaults applied, anchor normalised. */
 declare interface StickerAnnotationSpec {
     id: string;
     anchor: ObservationAnchor;
@@ -5754,26 +6947,33 @@ declare interface TemporalValueFormat {
     dateFormat?: string;
 }
 
+/** How `backgroundColor` is applied: `'fade'` (soft gradient) or `'opaque'` (flat fill). */
 export declare type TextAnnotationBackgroundColorStyle = 'fade' | 'opaque';
 
 /**
- * Freeform rich-text annotation. Position and width are fractions of the plot
- * rect (0..1). Height is intrinsic to the rendered content.
+ * A free-standing text label on the panel. Positioned in panel fractions (`[0,1]`, top-left origin) —
+ * NOT data values — so it re-flows on resize but does not snap to a data point. There is no `height`
+ * field: height is intrinsic to the rendered content. `content` is a structured {@link RichTextContent}
+ * node tree (ProseMirror/TipTap-style), NOT a plain string — wrap a string as
+ * `{ type: 'doc', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Label' }] }] }`.
  */
 export declare interface TextAnnotationInput {
     id?: string;
+    /** Rich-text node tree to render (not a plain string). */
     content: RichTextContent;
-    /** 0..1 of plot width — top-left corner. */
+    /** Left edge as a `[0,1]` fraction of panel width (0 = left, top-left corner). */
     x: number;
-    /** 0..1 of plot height — top-left corner. */
+    /** Top edge as a `[0,1]` fraction of panel height (0 = top, top-left corner). */
     y: number;
-    /** 0..1 of plot width. */
+    /** Box width as a `[0,1]` fraction of panel width; text wraps within it (height is intrinsic). */
     width: number;
-    /** null falls back to a transparent background. */
+    /** `null` falls back to a transparent background. @default null */
     backgroundColor?: string | null;
+    /** @default 'opaque' */
     backgroundColorStyle?: TextAnnotationBackgroundColorStyle;
 }
 
+/** Resolved form of {@link TextAnnotationInput} — defaults applied. */
 export declare interface TextAnnotationSpec {
     id: string;
     content: RichTextContent;
@@ -5784,13 +6984,22 @@ export declare interface TextAnnotationSpec {
     backgroundColorStyle: TextAnnotationBackgroundColorStyle;
 }
 
-/** A text value — plain string or structured rich text. */
+/**
+ * A text value for a title, subtitle, or caption: either a plain `string`
+ * (rendered as-is) or a structured {@link RichTextContent} document tree for
+ * multi-style / multi-line text.
+ */
 export declare type TextContent = string | RichTextContent;
 
 export declare interface TextMeasurer {
     measureText: (text: string, font: FontSpec) => MeasuredText;
 }
 
+declare interface ToDatasetOptions {
+    /** Name of the categorical column that discriminates each row's kind. Must not collide with a declared column. */
+    kindColumn: string;
+}
+
 /** A chart's semantic content for the hovered observations, in reading order. */
 export declare interface TooltipContent {
     /** Localized main-axis value of the primary's observation. `null` for polar. */
@@ -5823,6 +7032,29 @@ export declare interface TooltipRow {
     key: string;
 }
 
+/**
+ * Data-transform builder — reshapes the dataset BEFORE any geom maps over it. Pipe one or more
+ * onto a spec; they apply in order, ahead of stats and scaling, and affect every layer.
+ *
+ * - `reshape(opts?)` — pivot wide numeric columns to long form (key/value); the move for plotting
+ *   several metrics as one color-split series.
+ * - `filter(opts)` — keep observations matching `variableName <operator> value`.
+ * - `sort(opts)` — order observations by a variable (`'asc'` | `'desc'`).
+ * - `aggregate(opts)` — group by variables and reduce each group (sum/mean/count/…).
+ * - `constant(opts)` — add a column with a fixed value on every observation.
+ *
+ * @example
+ *   import { pipe, createSpec, geom, scale, transform } from '@graphysdk/viz-engine';
+ *
+ *   pipe(
+ *     createSpec({ x: 'region', y: 'total', color: 'region' }),
+ *     transform.filter({ variableName: 'year', operator: 'eq', value: 2024 }),
+ *     transform.aggregate({ groupby: ['region'], operations: [{ op: 'sum', variableName: 'revenue', as: 'total' }] }),
+ *     geom.bar(),
+ *     scale.x(),
+ *     scale.y()
+ *   );
+ */
 export declare const transform: {
     reshape: typeof reshape;
     filter: typeof filter;
@@ -5848,27 +7080,71 @@ declare interface TransformCompilerInput {
     transforms: TransformInput[];
 }
 
-/***************************************************************
- * Transform Input
- ***************************************************************/
-declare type TransformInput = ReshapeTransformInput | FilterTransformInput | SortTransformInput | AggregateTransformInput | ConstantTransformInput;
+/**
+ * A registered custom transform: a {@link TransformStrategy} the compiler consumes, carrying the option
+ * type so `createGraphyBuilder({ transforms })` can type its `transform.<type>(options)` builder method.
+ */
+export declare interface TransformDef<TType extends string = string, TOptions extends object = object> extends TransformStrategy {
+    readonly transformType: TType;
+    /**
+     * Phantom — carries the options type to the type level so the registration-typed builder can recover
+     * the transform's options. Never set at runtime.
+     */
+    readonly __options?: TOptions;
+}
 
 /**
- * Built-in transform implementations keyed by transform type.
+ * The manifest passed to {@link defineTransform}. Declares the `transformType` and an `apply` that
+ * reshapes the dataset given the transform's plain-data options.
  */
-declare class TransformRegistry extends Registry<TransformType, TransformStrategy> {
-    constructor();
+export declare interface TransformDefinitionManifest<TType extends string = string, TOptions extends object = object> {
+    /** The registered transform name; keys both the registry and the `transform.<type>(...)` builder method. */
+    transformType: TType;
+    /** Reshapes the dataset given the transform's options. Mapping-blind, whole-table surgery. */
+    apply: (data: Dataset, options: TOptions) => Dataset;
 }
 
 /**
- * Strategy interface for compiling a specific transform type.
+ * The open identity of a transform: a built-in {@link TransformType} or any custom transform's
+ * `transformType` string registered via `createCompiler({ transforms })` (mirrors `GeomIdentity`).
+ */
+export declare type TransformIdentity = TransformType | (string & {});
+
+/**
+ * Any value the `transform` builder produces. Transforms run before stats and scaling, in the
+ * order they appear, reshaping the dataset that every layer then maps over.
+ */
+export declare type TransformInput = BuiltinTransformInput | CustomTransformInput;
+
+/**
+ * The options a registered custom transform's builder method accepts — recovered structurally from the
+ * definition's phantom options type.
  */
-declare interface TransformStrategy {
-    readonly transformType: TransformType;
+declare type TransformOptionsOf<Definition> = Definition extends TransformDef<string, infer TOptions> ? TOptions : never;
+
+/**
+ * Transform strategies keyed by `transformType`. Built-ins register first; any custom transforms
+ * injected via `createCompiler({ transforms })` register afterwards (a custom `transformType` matching
+ * a built-in overrides it, last write wins) — mirroring `GeomRegistry` / `StatRegistry`.
+ */
+declare class TransformRegistry extends Registry<string, TransformStrategy> {
+    constructor(opts?: {
+        transforms?: readonly TransformStrategy[];
+    });
+}
+
+/**
+ * Strategy interface for compiling a specific transform type. Built-ins use a literal
+ * {@link TransformType}; custom transforms authored with `defineTransform` carry any registered
+ * `transformType` string ({@link TransformIdentity}).
+ */
+export declare interface TransformStrategy {
+    readonly transformType: TransformIdentity;
     apply: (data: Dataset, transform: TransformInput) => Dataset;
 }
 
-declare type TransformType = TransformInput['transformType'];
+/** Discriminant tag of a built-in {@link TransformInput}. */
+export declare type TransformType = BuiltinTransformInput['transformType'];
 
 declare type TrendlineType = 'linear' | 'loess' | 'exponential' | 'logarithmic' | 'quadratic' | 'power' | 'polynomial';
 
@@ -5914,27 +7190,39 @@ export declare interface ValueFormatterFactoryParams<T = ValueFormat> {
 }
 
 /**
- * Constant mapping - a literal value applied to every observation.
- * Analogous to Vega-Lite's `{datum: X}` / ggplot2's `aes(color = "literal")`.
+ * Pins a channel to a single literal value applied to every observation, instead of reading a column.
+ * Use it for reference-line constants (`geom.rule({ aes: { y: { value: 2500 } } })`) or to force a fixed
+ * style (`aes: { lineType: { value: 'dashed' } }`). Analogous to Vega-Lite's `{datum: X}`.
  */
 declare interface ValueMapping {
+    /** The constant — a number, string, Date, or null — shared by all observations. */
     value: DataValue;
 }
 
 /** A column of a variable in the dataset. When `valueFormat` is omitted, the Dataset assigns a type-based default (`numeric → decimal`, `categorical → text`, `temporal → date`). */
-declare type Variable = {
+export declare type Variable = {
     type: DataType;
     values: DataValue[];
     valueFormat?: ValueFormat;
 };
 
+/**
+ * The internal dataset variable a channel reads and writes, derived from its axis and open name. The
+ * built-in names (`point`/`lower`/`upper`) resolve to the canonical position columns (`x`, `xMin`, …),
+ * so value readers and renderer recipes stay untouched; any other name resolves to a namespaced column,
+ * so a custom scaled channel never collides with a built-in or another geom's channel.
+ */
+export declare function variableFor(axis: ChannelAxis, name: string): string;
+
 /** A map of variable names to their type and values. */
-declare type VariableMap = Record<VariableName, Variable>;
+export declare type VariableMap = Record<VariableName, Variable>;
 
 /**
- * Variable mapping - references a column in the data
+ * Binds a channel to a data column by name. `{ variable: 'revenue' }` reads the `revenue` column
+ * per observation. Equivalent to the bare-string shorthand `'revenue'` in an {@link AesMapping}.
  */
 declare interface VariableMapping {
+    /** Column key in the data, matching a `columns[i].key`. */
     variable: string;
 }
 
@@ -5943,15 +7231,20 @@ declare type VariableMetadata = Record<VariableName, {
     valueFormat: ValueFormat;
 }>;
 
-/** A type alias for variable names. */
+/** A variable (column) name. Names with the internal prefix address compiler-emitted columns; address those through the value readers (`getX`, …) or `variableFor`, never by literal. */
 export declare type VariableName = string;
 
 /**
- * Field-based predicates against post-transform user columns.
+ * A value test against one post-transform user column. The selected operator
+ * decides which observations a highlight emphasises:
+ * - `eq`: column equals the value.
+ * - `oneOf`: column is one of the listed values.
+ * - `lt` / `lte` / `gt` / `gte`: ordering comparison (numeric / datetime only).
+ * - `range`: inclusive `[min, max]` interval.
  *
- * `lt`, `lte`, `gt`, `gte`, and `range` accept `DataValue`s and are coerced at
- * evaluation time by the referenced column's `DataType`. Ordering operators
- * against a categorical field are a resolve-time validation error.
+ * Comparison values are `DataValue`s coerced at evaluation time by the
+ * referenced column's `DataType`. Ordering operators against a categorical
+ * field are a resolve-time validation error.
  */
 export declare type VariablePredicate = {
     variable: VariableName;
@@ -6021,7 +7314,7 @@ declare interface XAxisConfig {
      */
     label: string | null;
     /**
-     * Position of the y axis.
+     * Position of the x axis.
      * @default 'bottom'
      */
     position: AxisPosition;