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

package/dist/index.d.ts

@@ -1,44 +1,24 @@
 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;
 
 /**
- * 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.
+ * Aesthetic value can be:
+ * - string (shorthand for { variable: string })
+ * - { variable: string } (explicit variable mapping)
+ * - { value: DataValue } (constant value applied to every observation)
  */
 declare type AestheticValue = string | VariableMapping | ValueMapping;
 
@@ -47,28 +27,22 @@ declare function aggregate(options: AggregateOptions): AggregateTransformInput;
 /***************************************************************
  * Aggregate Transform
  ***************************************************************/
-/** A single group-wise reduction applied by `transform.aggregate`. */
 declare interface AggregateOperation {
-    /** Reduction to apply: `'count'` | `'sum'` | `'mean'` | `'median'` | `'mode'` | `'min'` | `'max'`. */
+    /** The aggregation function to apply. */
     op: AggregationFunction;
-    /** The variable to reduce within each group. */
+    /** The variable to aggregate. */
     variableName: VariableName;
-    /** Name of the output variable holding the reduced value. */
+    /** The name of the output variable. */
     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; one output observation is produced per distinct combination. */
+    /** Variables to group by before aggregating. */
     groupby: VariableName[];
-    /** One or more reductions to compute per group. */
+    /** Aggregation operations to apply per group. */
     operations: AggregateOperation[];
 }
 
-/** Group-and-reduce transform produced by `transform.aggregate`. */
 declare interface AggregateTransformInput {
     type: 'transform';
     transformType: 'aggregate';
@@ -108,63 +82,11 @@ 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).
  *
@@ -173,11 +95,9 @@ export declare const annotation: {
  * 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`).
  */
-/** Allowed coordinate count for an annotation kind; each bound is inclusive, unbounded when omitted. */
-export declare interface AnnotationArity {
-    /** Minimum coordinates required. */
+/** Optional coordinate-count guardrail enforced by the builder; unbounded when omitted. */
+declare interface AnnotationArity {
     min?: number;
-    /** Maximum coordinates allowed. */
     max?: number;
 }
 
@@ -222,59 +142,18 @@ declare interface AnnotationDataPoint {
     rowValue?: DataValue;
 }
 
-/**
- * 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`. */
+declare interface AnnotationDef<TParams extends object = object, TType extends string = string> {
     type: TType;
     /** Carrier that lets the builder recover `TParams` and merge defaults before a param reaches `draw`. */
     defaultParams: TParams;
-    /** Coordinate-count guardrail enforced by the builder; unbounded when omitted. */
     coordinates?: AnnotationArity;
 }
 
-/**
- * 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 = {
+/** Pipeable spec item produced by the registration-typed `annotation.<kind>(...)` builder. */
+declare interface 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;
@@ -303,38 +182,17 @@ 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[];
@@ -408,20 +266,11 @@ 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'>;
 
 /**
@@ -442,37 +291,21 @@ declare class AreaGeom extends Geom {
 }
 
 /**
- * Render parameters for `geom.area` — same knobs as {@link LineGeomParams}, but the region below the curve
- * is filled. Passed under `params`.
+ * Area-specific parameters (same rendering knobs as line, but fills under the curve)
  */
 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 panel width (0 = left). */
+    /** 0..1 of plot width. */
     x: number;
-    /** `[0,1]` of panel height (0 = top). */
+    /** 0..1 of plot height. */
     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';
@@ -505,11 +338,8 @@ 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;
 }
 
@@ -585,9 +415,7 @@ 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;
 }
 
@@ -618,14 +446,6 @@ 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'>;
 
 /**
@@ -676,68 +496,27 @@ declare interface BarOptions {
 }
 
 /**
- * Params shared by every coordinate system. Axis limits clamp the displayed range
- * after scaling.
+ * Base params shared by all coordinate systems
  */
 declare interface BaseCoordParams {
     /**
-     * Fixed x-axis range as `[min, max]` in data units, or `null` to auto-fit from data.
-     * @default null
+     * Limits for x-axis [min, max]
      */
     xLimits: [number, number] | null;
     /**
-     * Fixed y-axis range as `[min, max]` in data units, or `null` to auto-fit from data.
-     * @default null
+     * Limits for y-axis [min, max]
      */
     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;
-    /**
-     * 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'`.
-     */
+    stat?: StatName | StatInput;
     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;
 }
 
@@ -929,12 +708,6 @@ 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.
  *
@@ -1078,17 +851,6 @@ export declare interface CommandApplyResult {
     readonly revert: Command;
 }
 
-/**
- * Descriptor that knows how to deserialize a specific command type.
- * Each concrete command co-locates its descriptor alongside the command class.
- *
- * Serialization is handled uniformly by the registry via `Command.params`.
- */
-declare interface CommandDescriptor<TParams extends Record<string, unknown> = Record<string, unknown>> {
-    readonly type: string;
-    deserialize: (params: TParams, metadata: CommandMetadata) => Command;
-}
-
 /**
  * Unique identifier for commands.
  */
@@ -1108,33 +870,6 @@ export declare interface CommandMetadata {
     readonly author: string;
 }
 
-/**
- * Central registry mapping command types to their serialization descriptors.
- */
-export declare class CommandRegistry {
-    private readonly descriptors;
-    /**
-     * Register a command descriptor. Throws if the type is already registered.
-     */
-    register<TParams extends Record<string, unknown>>(descriptor: CommandDescriptor<TParams>): void;
-    /**
-     * Serialize a command to its wire format.
-     */
-    serialize(command: Command): SerializedCommand;
-    /**
-     * Deserialize a command from its wire format.
-     */
-    deserialize(data: SerializedCommand): Command;
-    /**
-     * Get all registered command type names.
-     */
-    getRegisteredTypes(): string[];
-    private getDescriptor;
-}
-
-/** Default singleton registry instance. */
-export declare const commandRegistry: CommandRegistry;
-
 /**
  * Event types emitted by CommandStackManager.
  */
@@ -1254,9 +989,6 @@ 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;
@@ -1264,7 +996,6 @@ declare interface CommentAnnotationInput {
     content: RichTextContent;
 }
 
-/** Resolved form of {@link CommentAnnotationInput} — defaults applied, anchor normalised. */
 declare interface CommentAnnotationSpec {
     id: string;
     anchor: ObservationAnchor;
@@ -1383,25 +1114,10 @@ export declare interface CompiledFreeformArrow {
     hasStickerStyle: boolean;
 }
 
-/**
- * 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.
-     */
+declare interface CompiledGeom {
+    /** The reparameterized dataset (may have new computed variables) */
     data: Dataset;
-    /**
-     * 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.
-     */
+    /** Any mapping overrides produced by the geom */
     mapping: AesMapping;
     /**
      * Extra single-observation tooltip rows this geom contributes (e.g. OHLC). The compiler derives
@@ -1624,7 +1340,7 @@ export declare interface CompiledSpec {
     annotations: CompiledAnnotations;
 }
 
-export declare interface CompiledStat {
+declare interface CompiledStat {
     /** The transformed dataset. */
     data: Dataset;
     /** Any mapping overrides produced by the stat (e.g., `y` → `'count'` for `CountStat`). */
@@ -1839,37 +1555,7 @@ declare interface ComputeFreeformArrowParams {
 }
 
 /**
- * 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' },
- *     })
- *   );
+ * Create a custom  configuration
  */
 export declare function config(options: ConfigInput): ConfigItem;
 
@@ -1886,20 +1572,8 @@ 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;
 };
 
@@ -1907,38 +1581,22 @@ 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;
 }
 
 /**
- * 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.
+ * Feature configuration with resolved defaults.
+ * All fields are required and always populated after resolution.
  */
 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;
 }
 
@@ -1966,20 +1624,15 @@ 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 {
-    /** Name of the new variable to add. */
+    /** The name of the new variable. */
     variableName: VariableName;
-    /** Data type of the new variable. */
+    /** The type of the new variable. */
     type: DataType;
-    /** The constant value assigned to every observation. */
+    /** The constant value to assign to every observation. */
     value: DataValue;
 }
 
-/** Add-a-constant-column transform produced by `transform.constant`. */
 declare interface ConstantTransformInput {
     type: 'transform';
     transformType: 'constant';
@@ -2009,29 +1662,17 @@ 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;
 }
 
-/**
- * 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).
- */
+/** Content input — all fields optional. */
 declare type ContentInput = Partial<ContentConfig>;
 
 declare type ContinuousScaleInput = {
@@ -2117,60 +1758,27 @@ 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→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.
+     * Standard cartesian (x-y) coordinate system. This is the default if no coord is specified.
      *
      * @example coord.cartesian() // auto-scaled axes
-     * @example coord.cartesian({ yLimits: [0, 100] }) // fixed y-axis range
+     * @example coord.cartesian({ yLimits: [0, 100] }) // fixed y-axis
      */
     cartesian: (params?: Partial<CartesianCoordParams>) => CartesianCoordInput;
     /**
-     * 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.
+     * Flipped cartesian coordinates — swaps x and y axes.
+     * Useful for horizontal bar charts or when category labels are long.
      *
-     * @example coord.flip() // horizontal bars from a vertical-bar spec
+     * @example coord.flip() // horizontal bars
      */
     flip: (params?: Partial<FlipCoordParams>) => FlipCoordInput;
     /**
-     * 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).
+     * Polar coordinate system — maps data to angle (theta) and radius.
+     * Used for pie charts, donut charts, and radar/radial visualizations.
      *
-     * @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
+     * @example coord.polar() // pie chart
+     * @example coord.polar({ innerRadius: 0.5 }) // donut chart
      */
     polar: (params?: Partial<PolarCoordParams>) => PolarCoordInput;
 };
@@ -2189,10 +1797,7 @@ declare class CoordCompiler {
 }
 
 /**
- * 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.
+ * Discriminated union of all coordinate input specs (user-provided, optional params).
  */
 declare type CoordInput = CartesianCoordInput | FlipCoordInput | PolarCoordInput;
 
@@ -2216,7 +1821,7 @@ declare type CoordSetupResult = {
 };
 
 /**
- * A fully resolved coordinate system (params defaulted) as it appears on the compiled spec.
+ * Discriminated union of all resolved coordinate specs (params fully defaulted).
  */
 declare type CoordSpec = CartesianCoordSpec | FlipCoordSpec | PolarCoordSpec;
 
@@ -2259,7 +1864,7 @@ declare interface CoordTransformInput {
  * - `'polar'` — Polar coordinates for pie, radar, and radial charts
  * - `'flip'` — Cartesian with x and y axes swapped
  */
-export declare type CoordType = 'cartesian' | 'polar' | 'flip';
+declare type CoordType = 'cartesian' | 'polar' | 'flip';
 
 declare function count(): CountStatSpec;
 
@@ -2275,27 +1880,12 @@ export declare const createAlphaValueReader: (data: Dataset, mapping: AesMapping
 export declare const createColorValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
 
 /**
- * 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).
+ * Builds a compiler instance. Pass `geoms` to register custom (or override built-in) geom
+ * definitions per-instance — there is no global registry to mutate, so injected geoms never bleed
+ * across instances. An injected geom whose `type` matches a built-in overrides it (last write wins).
  */
 export declare const createCompiler: (opts?: {
     geoms?: readonly Geom[];
-    stats?: readonly Stat[];
-    transforms?: readonly TransformStrategy[];
 }) => Compiler;
 
 /**
@@ -2305,27 +1895,20 @@ 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, 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={[...]}>`.
+ * Builds a Graphy authoring surface for a set of custom geoms and/or annotations: a `geom` builder that
+ * merges the built-in methods with one method per registered custom geom, an `annotation` builder with
+ * one method per registered annotation kind, plus the standard `createSpec`. The 90% case stays the
+ * plain `import { geom, createSpec }`; reach for this only when authoring custom geoms (decision 8) or
+ * custom annotations (ADR-035). Registration is per-instance — geoms are injected to
+ * `createCompiler({ geoms })`; annotations need no compile-side registry (coordinate resolution is
+ * generic), only the render plugin via `<GraphProvider annotationPlugins={[...]}>`.
  */
-export declare 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: {
+export declare function createGraphyBuilder<const Geoms extends readonly Geom[] = readonly [], const Annotations extends readonly AnnotationDef[] = readonly []>(options: {
     geoms?: Geoms;
-    stats?: Stats;
-    transforms?: Transforms;
     annotations?: Annotations;
 }): {
     geom: typeof geom & CustomGeomBuilders<Geoms>;
-    stat: typeof stat & CustomStatBuilders<Stats>;
-    transform: typeof transform & CustomTransformBuilders<Transforms>;
-    annotation: typeof annotation & CustomAnnotationBuilders<Annotations>;
+    annotation: CustomAnnotationBuilders<Annotations>;
     createSpec: typeof createSpec;
 };
 
@@ -2333,9 +1916,6 @@ 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.
@@ -2352,32 +1932,20 @@ export declare function createSegmentYReader(layer: CompiledLayer): (observation
 export declare const createSizeValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
 
 /**
- * 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
- * import { createSpec, pipe, geom, scale } from '@graphysdk/viz-engine';
- *
- * // Most common: mapping first, then pipe the rest.
- * const spec = pipe(createSpec({ x: 'category', y: 'revenue' }), geom.bar(), scale.x(), scale.y());
+ * Create a new spec, optionally piping spec items in one call. Data is passed separately
+ * to {@link compile}.
  *
  * @example
- * import { createSpec, transform, mapping, geom, scale } from '@graphysdk/viz-engine';
+ * When the first arg is a mapping:
+ *   createSpec({ x: 'date', y: 'value' })
  *
- * // All-in-one form, clearer when a transform must run before the mapping is read.
- * const spec = createSpec(
- *   transform.reshape({ reshape: ['revenue'], keyName: 'metric', valueName: 'amount' }),
- *   mapping({ x: 'month', y: 'amount', color: 'metric' }),
- *   geom.bar(),
- *   scale.x(),
- *   scale.y(),
- * );
+ * When piping spec items (more readable when chaining transforms):
+ *   createSpec(
+ *     transform.reshape({ reshape: ['revenue'], keyName: 'metric', valueName: 'amount' }),
+ *     mapping({ x: 'month', y: 'amount', color: 'metric' }),
+ *     geom.bar(),
+ *     scale.x(),
+ *   )
  */
 export declare function createSpec(...items: Array<AesMapping | SpecItem>): SpecInput;
 
@@ -2431,7 +1999,6 @@ 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;
@@ -2457,7 +2024,7 @@ declare type CustomGeomBuilders<Geoms extends readonly Geom[]> = {
  */
 declare interface CustomGeomOptions<TParams extends object, TAes extends string> {
     aes?: Partial<Record<TAes, AestheticValue>>;
-    stat?: StatLayerInput | StatLayerInput[];
+    stat?: StatName | StatInput;
     position?: PositionType;
     yScaleType?: YScaleType;
     params?: Partial<TParams>;
@@ -2495,53 +2062,12 @@ declare type CustomPaletteInput = {
 export declare type CustomPalettesInput = Record<string, string[]>;
 
 /**
- * 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.
+ * Data to visualize. Structured as a table.
  *
- * 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 {
     /**
@@ -2629,11 +2155,6 @@ 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'>>;
 
 /**
@@ -2657,10 +2178,6 @@ 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] },
@@ -2928,13 +2445,9 @@ 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]?: 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];
+    [K in keyof T]?: T[K] extends Array<infer U> ? Array<DeepPartial<U>> : NonNullable<T[K]> extends object ? DeepPartial<NonNullable<T[K]>> : T[K];
 };
 
 export declare const DEFAULT_COLOR_PALETTE: string[];
@@ -2955,62 +2468,6 @@ 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;
@@ -3037,34 +2494,25 @@ declare interface DifferenceArrowDimensions {
 }
 
 /**
- * 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.
+ * User-facing difference-arrow input. `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 form of {@link DifferenceArrowInput} — defaults applied, anchors normalised.
+ * Resolved difference-arrow spec with all optional fields defaulted.
  */
 export declare interface DifferenceArrowSpec {
     id: string;
@@ -3136,39 +2584,23 @@ 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;
-    /** Comparison operator: `'eq'` | `'neq'` | `'gt'` | `'gte'` | `'lt'` | `'lte'`. */
+    /** The comparison operator. */
     operator: ComparisonOperator;
-    /** The value to compare each observation's `variableName` against. */
+    /** The value to compare against. */
     value: DataValue;
 }
 
-/** Row-filtering transform produced by `transform.filter`. */
 declare interface FilterTransformInput {
     type: 'transform';
     transformType: 'filter';
@@ -3191,24 +2623,6 @@ 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';
@@ -3325,31 +2739,23 @@ export declare interface FormattedPerGroupHeadline {
 }
 
 /**
- * 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.
+ * Freeform arrow annotation. Endpoints sit in plot-fractional coordinates
+ * (0..1), so they re-flow with panel size. Distinct from
+ * {@link DifferenceArrowInput}, which anchors to dataset observations.
  */
 export declare interface FreeformArrowInput {
     id?: string;
-    /** Tail endpoint. */
     start: ArrowEndpoint;
-    /** Head endpoint (the end pointed at). */
     end: ArrowEndpoint;
-    /** `null` falls back to the theme `defaultAnnotationArrowStroke`. @default null */
+    /** null falls back to the theme `defaultAnnotationArrowStroke`. */
     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;
@@ -3386,7 +2792,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}.
  */
-export declare abstract class Geom<TParams extends object = object> {
+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
@@ -3478,13 +2884,6 @@ export 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
@@ -3494,25 +2893,6 @@ export 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;
@@ -3572,31 +2952,12 @@ declare class GeomCompiler {
     resolveAnchorPosition(geomName: GeomIdentity, observation: Observation, coordSystem: CoordSystem): AnchorPosition | null;
 }
 
-/**
- * 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).
-     */
+declare interface GeomCompilerInput {
+    /** The dataset after stat transformation */
     data: Dataset;
-    /**
-     * 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)`.
-     */
+    /** The effective mapping for the layer */
     mapping: AesMapping;
-    /**
-     * 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.
-     */
+    /** Geom-specific params */
     params: LayerSpec['params'];
 }
 
@@ -3625,10 +2986,8 @@ 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];
 
 /**
@@ -3661,34 +3020,19 @@ 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.
  */
-export declare interface GeomTooltipRow {
+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 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.
- */
+/** Reads the resolved alpha (opacity) value from an observation. */
 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 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.
- */
+/** Reads the resolved color string from an observation. */
 export declare function getColor(observation: Observation): string | undefined;
 
 /** Reads the coordinate lying on the cross axis of the coord system. */
@@ -3702,13 +3046,6 @@ 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;
 
 /**
@@ -3719,33 +3056,20 @@ export declare const getGroup: (observation: Observation) => CategoricalDataValu
 export declare const getIdentityKey: (observation: Observation) => string;
 
 /**
- * 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`.
+ * Reads the resolved line type (stroke style) from an observation.
+ * Falls back to `'solid'` when no `lineType` variable was derived.
  */
 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 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.
- */
+/** Reads the resolved size value from an observation. */
 export declare function getSize(observation: Observation): NumericDataValue;
 
-/**
- * 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.
- */
+/** Reads the resolved stroke width value from an observation. */
 export declare function getStrokeWidth(observation: Observation): NumericDataValue;
 
 declare interface GetValuesOptions {
@@ -3757,61 +3081,29 @@ declare interface GetValuesOptions {
     distinct?: boolean;
 }
 
-/**
- * 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.
- */
+/** Reads the normalized x position from an observation. */
 export declare function getX(observation: Observation): NumericDataValue;
 
-/**
- * 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.
- */
+/** Reads the normalized xMax (right band edge) from an observation. */
 export declare function getXMax(observation: Observation): NumericDataValue;
 
-/**
- * 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.
- */
+/** Reads the normalized xMin (left band edge) from an observation. */
 export declare function getXMin(observation: Observation): NumericDataValue;
 
-/**
- * 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.
- */
+/** Reads the normalized y position from an observation. */
 export declare function getY(observation: Observation): NumericDataValue;
 
-/**
- * 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.
- */
+/** Reads the normalized yMax (upper extent) from an observation. */
 export declare function getYMax(observation: Observation): NumericDataValue;
 
-/**
- * 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.
- */
+/** Reads the normalized yMin (lower extent) from an observation. */
 export declare function getYMin(observation: Observation): NumericDataValue;
 
 /**
- * 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).
+ * 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.
  */
 export declare function getYRaw(observation: Observation): NumericDataValue;
 
@@ -3952,7 +3244,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.
  */
-export declare interface GridPolicy {
+declare interface GridPolicy {
     hideGridX?: boolean;
     hideGridY?: boolean;
     hideBorder?: boolean;
@@ -4198,29 +3490,15 @@ export declare class HeuristicTextMeasurer implements TextMeasurer {
 }
 
 /**
- * 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`.
+ * Create a pipeable highlight spec item.
  *
  * @example
- *   import { pipe, createSpec, geom, scale, highlight } from '@graphysdk/viz-engine';
- *
  *   pipe(
- *     createSpec({ x: 'month', y: 'revenue', color: 'region' }),
+ *     createSpec(data, { x: 'month', y: 'revenue', color: 'region' }),
  *     geom.bar(),
- *     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 })
- *   );
+ *     highlight({ field: 'region', eq: 'EU' }),
+ *     highlight({ field: 'region', eq: 'US' }, { scope: 'series' }),
+ *   )
  */
 export declare function highlight(predicate: Predicate, options?: HighlightBuilderOptions): HighlightInput;
 
@@ -4370,10 +3648,10 @@ export declare class HoverEngine {
      */
     private nonInteractiveLayerIds;
     /**
-     * Render-side hit-testers registered per layer for `render-hit-test` (geom-layout) layers, keyed by
+     * Render-side hit-testers registered per layer for `render-hit-test` (Tier-C) layers, keyed by
      * `CompiledLayer.id`. The renderer owns this map and injects it via {@link setHitTesters}; the
      * engine holds the live reference so a plugin mounting or updating its tester is visible at the
-     * next `query()` without a re-index. Empty for charts with no geom-layout geom.
+     * next `query()` without a re-index. Empty for charts with no Tier-C geom.
      */
     private hitTesters;
     constructor({ layers, coordSystem }: HoverEngineInput);
@@ -4514,17 +3792,6 @@ 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.
  *
@@ -4608,27 +3875,13 @@ 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;
-    /** 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. */
+    stat?: StatName | StatInput;
     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
@@ -4643,7 +3896,6 @@ 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]>;
@@ -4654,32 +3906,18 @@ 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;
-    /** Resolved statistical-transform pipeline (empty array means identity). */
-    stat: ResolvedStatSpec[];
-    /** Resolved arrangement of sibling marks at the same x position. */
+    stat: StatSpec;
     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];
@@ -4715,7 +3953,7 @@ declare interface LayerValidationCheckInput {
 declare interface LayerValidationInput {
     layerId: string;
     geom: GeomIdentity;
-    stat: ResolvedStatSpec[];
+    stat: StatSpec;
     /** `spec.mapping` merged with `layer.mapping` */
     effectiveMapping: AesMapping;
     /** Layer's dataset after its own transforms have been applied */
@@ -4754,9 +3992,6 @@ 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
@@ -4775,16 +4010,14 @@ export declare const LAYOUT_PADDING = 24;
  * settled after the first resolve.
  *
  * Here's the pipeline:
- *   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
+ *   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
  *      axes; horizontal axes keep their seed.
- *   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.
+ *   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.
  */
 export declare class LayoutCompiler {
     private readonly measurer;
@@ -4871,9 +4104,8 @@ declare interface Legend {
  */
 declare interface LegendConfig {
     /**
-     * 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 of the legend
+     * @default 'top'
      */
     position: LegendPosition;
     /**
@@ -4933,23 +4165,8 @@ 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'>;
 
 /**
@@ -4972,22 +4189,17 @@ declare class LineGeom extends Geom {
 }
 
 /**
- * Render parameters for `geom.line`. Passed under `params`.
+ * Line-specific parameters
  */
 export declare interface LineGeomParams {
-    /**
-     * 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.
+     * Interpolation method to use for the line.
      * @default 'linear'
      */
     interpolate: InterpolateType;
     /**
-     * How to handle missing (`null`) y-values: `'gap'` breaks the line, `'zero'` drops to zero, `'connect'`
-     * bridges across the gap.
+     * How to handle missing (NULL/undefined) values.
      * @default 'gap'
      */
     missingValues: MissingValuesType;
@@ -5014,12 +4226,7 @@ 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"];
 
-/**
- * Boolean composition of nested predicates:
- * - `and`: every sub-predicate matches.
- * - `or`: at least one matches.
- * - `not`: the sub-predicate does not match.
- */
+/** Logical composition of any predicate. */
 export declare type LogicalPredicate = {
     and: Predicate[];
 } | {
@@ -5054,9 +4261,7 @@ 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. 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.
+ * Create a pipeable mapping spec item.
  *
  * @example
  * createSpec(
@@ -5069,38 +4274,13 @@ declare type MappableAes<Definition extends Geom> = Definition['requiredAestheti
 export declare function mapping(aes: AesMapping): MappingItem;
 
 /**
- * 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.
+ * A pipeable spec item that sets/merges the global aesthetic mapping.
  */
 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;
 
 /**
@@ -5186,16 +4366,14 @@ declare type NeonPaletteConfig = {
 declare type NeonPaletteVariant = 'default' | 'waterfall';
 
 /**
- * Chart-wide number formatting, applied by the renderer to every numeric value
- * (axis ticks, tooltips, data labels, headline figures). Set via
- * `config({ numberFormat: { … } })`.
+ * Configuration for formatting a single number.
+ * Defines how numeric values should be displayed in the chart.
  */
 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'
+     * - 'auto': Automatic based on value magnitude (default)
      */
     decimals: number | 'auto';
     /**
@@ -5205,7 +4383,6 @@ 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';
     /**
@@ -5234,13 +4411,7 @@ declare interface NumericValueFormat {
     type: 'decimal' | 'integer' | 'percentage' | 'duration';
 }
 
-/**
- * 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`.
- */
+/** A single row of data, mapping every variable name to the value in that row. */
 export declare type Observation = Record<VariableName, DataValue>;
 
 /**
@@ -5259,16 +4430,13 @@ export declare interface ObservationAnchor {
     groupValue: DataValue;
 }
 
-/**
- * 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).
- */
+/** Points at a single observation by its anchor value and series. */
 export declare interface ObservationAnchorInput {
-    /** Pick a specific layer when multiple share the same `(anchorValue, groupValue)` pair. Index into the spec's layers. */
+    /** Pick a specific layer when multiple share the same `(anchorValue, groupValue)` pair. */
     layerIndex?: number;
-    /** Value on the main axis (x in cartesian, y in flipped) that selects the observation. */
+    /** Value on the main axis (x in cartesian, y in flipped). */
     anchorValue: DataValue;
-    /** Series identity — the `color`/`group` aesthetic value that disambiguates within the axis value. */
+    /** Series identity (the `group` aesthetic value). */
     groupValue: DataValue;
 }
 
@@ -5300,15 +4468,13 @@ 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 geom-layout geom registers for a `render-hit-test` layer. The engine calls it
+ * A render-side hit-test a Tier-C geom registers for a `render-hit-test` layer. The engine calls it
  * with the cursor in panel `[0, 1]` space using a **top-left origin (y-down)** — the same frame the
  * geom paints in (unit-space SVG / `toPercent`), so the geom can test against its own rendered
  * geometry without re-flipping. It returns the declared identity `key` of the observation under the
@@ -5365,29 +4531,19 @@ 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;
 }
 
 /**
- * Fold a sequence of pipeable spec items onto an existing spec, left to right, returning a new spec.
- * Each item is appended by kind: layers accumulate (call `geom.*` once per mark), scales accumulate,
- * `config` deep-merges, `coord`/`mapping` overwrite/merge. The usual shape is
- * `pipe(createSpec({...}), geom.x(), scale.x(), scale.y(), ...)`.
- *
- * @example
- * pipe(createSpec({ x: 'month', y: 'sales', color: 'region' }), geom.line(), scale.x(), scale.y(), scale.color.palette());
+ * Pipe a spec through a series of spec items (left-to-right).
  */
 export declare function pipe(spec: SpecInput, ...items: SpecItem[]): SpecInput;
 
@@ -5417,20 +4573,6 @@ 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'>;
 
 /**
@@ -5449,14 +4591,9 @@ declare class PointGeom extends Geom {
 }
 
 /**
- * Render parameters for `geom.point`. Passed under `params`.
+ * Point-specific parameters
  */
 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;
 }
 
@@ -5472,28 +4609,19 @@ declare interface PolarCoordInput {
 }
 
 /**
- * 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.
+ * Params for polar coordinate system
  */
 declare interface PolarCoordParams extends BaseCoordParams {
     /**
-     * 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'
+     * Which aesthetic maps to theta (angle): 'x' or 'y'
      */
     theta: 'x' | 'y';
     /**
-     * Rotation offset of the whole layout, in degrees. Shifts where the first datum begins;
-     * the full sweep is 360°.
-     * @default 0
+     * Starting angle in degrees
      */
     startAngle: number;
     /**
-     * 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
+     * Inner radius as fraction 0-1 (for donut charts)
      */
     innerRadius: number;
 }
@@ -5615,7 +4743,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.
  */
-export declare type PositionChannel = RolePositionChannel | ScalarPositionChannel;
+declare type PositionChannel = RolePositionChannel | ScalarPositionChannel;
 
 declare interface PositionChannelBase {
     axis: ChannelAxis;
@@ -5663,10 +4791,6 @@ 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;
@@ -5689,51 +4813,11 @@ 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;
@@ -5793,11 +4877,6 @@ 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.
@@ -5821,7 +4900,6 @@ declare interface ReshapeOptions {
     valueName?: VariableName;
 }
 
-/** Pivot-to-long transform produced by `transform.reshape`. */
 declare interface ReshapeTransformInput {
     type: 'transform';
     transformType: 'reshape';
@@ -5860,12 +4938,6 @@ 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
@@ -5911,35 +4983,15 @@ export declare function resolveYScaleAesthetic(yScaleType: YScaleType): ScaledAe
  */
 export declare const RESTING_HOVER_STATE: HoverState;
 
-/**
- * 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' }] }] }
- * ```
- */
+/** TipTap-compatible rich text node (no tiptap dependency). */
 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>;
 }
 
@@ -5954,18 +5006,6 @@ 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'>;
 
 /**
@@ -5988,34 +5028,20 @@ declare class RuleGeom extends Geom {
 }
 
 /**
- * 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.
+ * Rule-specific parameters.
  */
 export declare interface RuleGeomParams {
-    /** Stroke color (any CSS color). Falls back to a theme token when omitted. */
+    /** Stroke color; falls back to a theme token. */
     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 (e.g. `'Target'`, `'Average'`). */
+    /** Optional inline text label rendered alongside the line. */
     label?: string;
-    /**
-     * Which end of the line the `label` is anchored to.
-     * @default 'start'
-     */
     labelPosition: RuleLabelPosition;
 }
 
 /**
- * Where the optional inline label sits along a reference line: `'start'` (left/top end) or `'end'`
- * (right/bottom end).
+ * Where the optional inline label is anchored along a reference line.
  */
 export declare type RuleLabelPosition = 'start' | 'end';
 
@@ -6047,31 +5073,6 @@ 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 {
@@ -6178,13 +5179,10 @@ export declare type ScaledAestheticKey = ScaledPositionAestheticKey | ScaledVisu
 
 declare type ScaledPositionAestheticKey = 'x' | 'y' | 'ySecondary';
 
-export declare type ScaledVisualAestheticKey = 'color' | 'size' | 'alpha' | 'strokeWidth' | 'lineType';
+declare type ScaledVisualAestheticKey = 'color' | 'size' | 'alpha' | 'strokeWidth' | 'lineType';
 
 /**
- * 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.
+ * Union type for all possible scale specifications (including inferred, pre-resolution).
  */
 declare type ScaleInput = ContinuousScaleInput | DiscreteScaleInput | PaletteScaleInput | DatetimeScaleInput | IdentityScaleInput | InferredScaleInput;
 
@@ -6193,9 +5191,8 @@ declare class ScaleRegistry extends Registry<ScaleType, Scale> {
 }
 
 /**
- * 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.
+ * Union of scale specs that can appear after resolution (all fields required).
+ * InferredScaleInput is resolved to a concrete type during spec resolution.
  */
 declare type ScaleSpec = ContinuousScaleSpec | DiscreteScaleSpec | DatetimeScaleSpec | IdentityScaleSpec | PaletteScaleSpec;
 
@@ -6409,37 +5406,27 @@ declare type SetScaleDomainParams = {
 };
 
 /**
- * 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.
+ * Freeform rectangle annotation. Position and size are expressed as
+ * fractions of the plot rect (0..1) so the annotation re-flows when the
+ * panel resizes.
  */
 export declare interface ShapeInput {
     id?: string;
-    /** @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`. @default null */
+    /** null falls back to the theme `defaultAnnotationShapeStroke`. */
     strokeColor?: string | null;
 }
 
 export declare type ShapeKind = 'rectangle';
 
-/** Resolved form of {@link ShapeInput} — defaults applied. */
 export declare interface ShapeSpec {
     id: string;
     kind: ShapeKind;
@@ -6460,9 +5447,7 @@ export declare interface ShapeSpec {
 export declare type ShapeZOrder = 'background' | 'foreground';
 
 /**
- * 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.
+ * Builder for the smooth stat.
  *
  * @example
  *   geom.line({ stat: stat.smooth({ method: 'linear' }) })
@@ -6476,14 +5461,7 @@ declare function smooth(options: {
 }): SmoothStatInput;
 
 /**
- * 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`.
+ * Regression methods supported by the `smooth` stat.
  */
 export declare type SmoothMethod = 'linear' | 'loess' | 'exponential' | 'logarithmic' | 'quadratic' | 'power' | 'polynomial';
 
@@ -6493,9 +5471,7 @@ 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;
 }
 
@@ -6513,18 +5489,9 @@ 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;
@@ -6532,18 +5499,15 @@ 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: a `label` and optional `url`. */
+/** Data-source attribution shown under the caption. */
 export declare interface SourceContent {
-    /** Displayed attribution text, e.g. `'Internal pipeline'`. */
     label?: string;
-    /** Optional link the label points to. */
     url?: string;
 }
 
@@ -6552,7 +5516,7 @@ 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 geom-layout escape hatch: the geom's geometry comes from a layout algorithm,
+ * `render-hit-test` is the Tier-C escape hatch: the geom's geometry comes from a layout algorithm,
  * not from scales, so the compiler cannot build a spatial index from position columns. The geom
  * instead provides a render-side hit-test function (injected per-instance through the renderer),
  * and the engine resolves the observation it returns against the declared identity key. Only the
@@ -6564,7 +5528,7 @@ export declare interface SourceContent {
  * 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.
  */
-export declare type SpatialIndexKind = 'buckets' | 'rects' | 'points' | 'arcs' | 'noop' | 'render-hit-test' | 'polar-points';
+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
@@ -6617,30 +5581,17 @@ export declare interface Spec {
 }
 
 /**
- * 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(), ...)`.
+ * The canonical spec type — plain JSON, serializable. Data is provided separately
+ * (as a `Data` value to {@link compile}, or as a prop to `<GraphProvider>`).
  */
 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;
 }
 
@@ -6657,18 +5608,6 @@ 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;
@@ -6711,11 +5650,9 @@ 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}).
  */
-export declare abstract class Stat {
-    abstract readonly type: StatIdentity;
+declare abstract class Stat {
+    abstract readonly type: StatName;
     /**
      * Aesthetics this stat will compute (e.g. count computes 'y'). Used by validation to skip existence checks.
      */
@@ -6724,23 +5661,6 @@ export 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;
@@ -6749,28 +5669,25 @@ export declare const stat: {
 };
 
 /**
- * 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.
+ * Resolves a stat by name and delegates computation.
  */
 declare class StatCompiler {
     private readonly registry;
     constructor(registry: StatRegistry);
-    compute(specs: ResolvedStatSpec[], input: {
+    compute(spec: StatSpec, input: {
         data: Dataset;
         mapping: AesMapping;
         xScaleIsDiscrete: boolean;
     }): CompiledStat;
 }
 
-export declare interface StatCompilerInput {
+declare interface StatCompilerInput {
     /** The input dataset. */
     data: Dataset;
     /** The effective mapping for the layer. */
     mapping: AesMapping;
-    /** The resolved stat spec (built-in or custom). Narrow by `spec.type` to access stat-specific params. */
-    spec: ResolvedStatSpec;
+    /** The resolved stat spec. Narrow by `spec.type` to access stat-specific params. */
+    spec: StatSpec;
     /**
      * Whether the x aesthetic resolves to a discrete (band) scale. The `smooth` stat emits one fitted
      * point per observed x when set.
@@ -6779,70 +5696,9 @@ export declare interface StatCompilerInput {
 }
 
 /**
- * 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' })]`.
+ * User-facing stat input — either a {@link StatName} string shorthand or an object spec.
  */
-declare type StatLayerInput = StatName | StatInput | CustomStatInput;
+declare type StatInput = IdentityStatSpec | CountStatSpec | SmoothStatInput | MeanStatSpec;
 
 /**
  * Statistical transformation applied to data before rendering.
@@ -6852,43 +5708,22 @@ declare type StatLayerInput = StatName | StatInput | CustomStatInput;
  * - `'smooth'` — Fit a regression curve through `(x, y)` and emit the fitted points
  * - `'mean'` — Reduce the dataset to a single observation holding the mean of `y`
  */
-export declare type StatName = 'identity' | 'count' | 'smooth' | 'mean';
-
-/**
- * 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 type StatOptionsOf<Definition> = Definition extends StatDef<infer TSpec> ? Omit<TSpec, 'type'> : never;
+declare type StatName = 'identity' | 'count' | 'smooth' | 'mean';
 
 /**
- * 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`.
+ * Built-in stat implementations keyed by {@link StatName}.
  */
-declare class StatRegistry extends Registry<string, Stat> {
-    constructor(opts?: {
-        stats?: readonly Stat[];
-    });
+declare class StatRegistry extends Registry<StatName, Stat> {
+    constructor();
 }
 
 /**
- * Discriminated union of all built-in resolved stat specs (post-resolution).
+ * Discriminated union of all resolved stat specs (post-resolution).
  */
-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;
-}
+declare type StatSpec = IdentityStatSpec | CountStatSpec | SmoothStatSpec | MeanStatSpec;
 
 /**
  * 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;
@@ -6896,7 +5731,6 @@ declare interface StickerAnnotationInput {
     sticker: StickerId;
 }
 
-/** Resolved form of {@link StickerAnnotationInput} — defaults applied, anchor normalised. */
 declare interface StickerAnnotationSpec {
     id: string;
     anchor: ObservationAnchor;
@@ -6947,33 +5781,26 @@ declare interface TemporalValueFormat {
     dateFormat?: string;
 }
 
-/** How `backgroundColor` is applied: `'fade'` (soft gradient) or `'opaque'` (flat fill). */
 export declare type TextAnnotationBackgroundColorStyle = 'fade' | 'opaque';
 
 /**
- * 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' }] }] }`.
+ * Freeform rich-text annotation. Position and width are fractions of the plot
+ * rect (0..1). Height is intrinsic to the rendered content.
  */
 export declare interface TextAnnotationInput {
     id?: string;
-    /** Rich-text node tree to render (not a plain string). */
     content: RichTextContent;
-    /** Left edge as a `[0,1]` fraction of panel width (0 = left, top-left corner). */
+    /** 0..1 of plot width — top-left corner. */
     x: number;
-    /** Top edge as a `[0,1]` fraction of panel height (0 = top, top-left corner). */
+    /** 0..1 of plot height — top-left corner. */
     y: number;
-    /** Box width as a `[0,1]` fraction of panel width; text wraps within it (height is intrinsic). */
+    /** 0..1 of plot width. */
     width: number;
-    /** `null` falls back to a transparent background. @default null */
+    /** null falls back to a transparent background. */
     backgroundColor?: string | null;
-    /** @default 'opaque' */
     backgroundColorStyle?: TextAnnotationBackgroundColorStyle;
 }
 
-/** Resolved form of {@link TextAnnotationInput} — defaults applied. */
 export declare interface TextAnnotationSpec {
     id: string;
     content: RichTextContent;
@@ -6984,22 +5811,13 @@ export declare interface TextAnnotationSpec {
     backgroundColorStyle: TextAnnotationBackgroundColorStyle;
 }
 
-/**
- * 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.
- */
+/** A text value — plain string or structured rich 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. */
@@ -7032,29 +5850,6 @@ 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;
@@ -7080,71 +5875,27 @@ declare interface TransformCompilerInput {
     transforms: TransformInput[];
 }
 
-/**
- * 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;
-}
-
-/**
- * The manifest passed to {@link defineTransform}. Declares the `transformType` and an `apply` that
- * reshapes the dataset given the transform's plain-data options.
- */
-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;
-}
-
-/**
- * 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 type TransformOptionsOf<Definition> = Definition extends TransformDef<string, infer TOptions> ? TOptions : never;
+/***************************************************************
+ * Transform Input
+ ***************************************************************/
+declare type TransformInput = ReshapeTransformInput | FilterTransformInput | SortTransformInput | AggregateTransformInput | ConstantTransformInput;
 
 /**
- * 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`.
+ * Built-in transform implementations keyed by transform type.
  */
-declare class TransformRegistry extends Registry<string, TransformStrategy> {
-    constructor(opts?: {
-        transforms?: readonly TransformStrategy[];
-    });
+declare class TransformRegistry extends Registry<TransformType, TransformStrategy> {
+    constructor();
 }
 
 /**
- * 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}).
+ * Strategy interface for compiling a specific transform type.
  */
-export declare interface TransformStrategy {
-    readonly transformType: TransformIdentity;
+declare interface TransformStrategy {
+    readonly transformType: TransformType;
     apply: (data: Dataset, transform: TransformInput) => Dataset;
 }
 
-/** Discriminant tag of a built-in {@link TransformInput}. */
-export declare type TransformType = BuiltinTransformInput['transformType'];
+declare type TransformType = TransformInput['transformType'];
 
 declare type TrendlineType = 'linear' | 'loess' | 'exponential' | 'logarithmic' | 'quadratic' | 'power' | 'polynomial';
 
@@ -7190,39 +5941,27 @@ export declare interface ValueFormatterFactoryParams<T = ValueFormat> {
 }
 
 /**
- * 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}`.
+ * Constant mapping - a literal value applied to every observation.
+ * Analogous to Vega-Lite's `{datum: X}` / ggplot2's `aes(color = "literal")`.
  */
 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`). */
-export declare type Variable = {
+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. */
-export declare type VariableMap = Record<VariableName, Variable>;
+declare type VariableMap = Record<VariableName, Variable>;
 
 /**
- * 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}.
+ * Variable mapping - references a column in the data
  */
 declare interface VariableMapping {
-    /** Column key in the data, matching a `columns[i].key`. */
     variable: string;
 }
 
@@ -7231,20 +5970,15 @@ declare type VariableMetadata = Record<VariableName, {
     valueFormat: ValueFormat;
 }>;
 
-/** 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. */
+/** A type alias for variable names. */
 export declare type VariableName = string;
 
 /**
- * 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.
+ * Field-based predicates against post-transform user columns.
  *
- * 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.
+ * `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.
  */
 export declare type VariablePredicate = {
     variable: VariableName;
@@ -7314,7 +6048,7 @@ declare interface XAxisConfig {
      */
     label: string | null;
     /**
-     * Position of the x axis.
+     * Position of the y axis.
      * @default 'bottom'
      */
     position: AxisPosition;