@graphysdk/viz-engine 0.0.1-plugins.5 → 0.0.1-plugins.6

package/dist/index.d.ts

@@ -1,24 +1,44 @@
 import { internal } from 'arquero';
 
+/**
+ * The aesthetic mapping: data columns (or constants) bound to visual channels. Seeded globally by
+ * `createSpec({...})` and overridable per layer via `geom.x({ aes })`. Every field is optional; a channel
+ * left unset is simply not driven by data. Each channel binds to the like-named scale (e.g. `color` →
+ * `scale.color.*`, `size` → `scale.size.*`); position channels additionally require `scale.x()`/`scale.y()`
+ * to be declared (they are NOT auto-inferred).
+ */
 export declare interface AesMapping {
+    /** Horizontal position. Binds to `scale.x`. Categorical/temporal x needs `scale.x.discrete()`. */
     x?: AestheticValue;
+    /** Vertical position. Binds to `scale.y` (or `scale.ySecondary` when the layer sets `yScaleType: 'secondary'`). */
     y?: AestheticValue;
+    /** Text drawn on the observation (data labels, slice labels). Binds to no scale; rendered as-is. */
     label?: AestheticValue;
+    /** Series/category color. Binds to `scale.color.*`; mapping a column splits the geom into series and shows a legend. */
     color?: AestheticValue;
+    /** Mark size — point radius / bubble area. Binds to `scale.size.continuous({ range })`. */
     size?: AestheticValue;
+    /** Per-observation opacity in `[0,1]` after scaling. Binds to `scale.alpha.*`. */
     alpha?: AestheticValue;
+    /**
+     * Explicit grouping key for which observations form one connected mark (one line/area). Defaults to the
+     * `color` column when unset; set it to split lines/areas without colouring them differently.
+     */
     group?: AestheticValue;
+    /** Stroke thickness as a data-driven channel. Binds to `scale.strokeWidth.*`; for a fixed width use line `params.lineWidth`. */
     strokeWidth?: AestheticValue;
+    /** Dash style (`'solid'`/`'dashed'`/`'dotted'`). Binds to `scale.lineType.discrete({ domain, range })`; great for actual-vs-forecast lines. */
     lineType?: AestheticValue;
 }
 
+/** The set of built-in aesthetic channel names — the keys of {@link AesMapping}. */
 export declare type AestheticKey = keyof AesMapping;
 
 /**
- * Aesthetic value can be:
- * - string (shorthand for { variable: string })
- * - { variable: string } (explicit variable mapping)
- * - { value: DataValue } (constant value applied to every observation)
+ * How a single aesthetic channel is fed. One of three forms:
+ * - a bare string (`'revenue'`) — shorthand for `{ variable: 'revenue' }`, the common case;
+ * - `{ variable: 'revenue' }` — the same column binding, written explicitly;
+ * - `{ value: 2500 }` — a constant {@link ValueMapping} applied to every observation.
  */
 declare type AestheticValue = string | VariableMapping | ValueMapping;
 
@@ -27,22 +47,28 @@ declare function aggregate(options: AggregateOptions): AggregateTransformInput;
 /***************************************************************
  * Aggregate Transform
  ***************************************************************/
+/** A single group-wise reduction applied by `transform.aggregate`. */
 declare interface AggregateOperation {
-    /** The aggregation function to apply. */
+    /** Reduction to apply: `'count'` | `'sum'` | `'mean'` | `'median'` | `'mode'` | `'min'` | `'max'`. */
     op: AggregationFunction;
-    /** The variable to aggregate. */
+    /** The variable to reduce within each group. */
     variableName: VariableName;
-    /** The name of the output variable. */
+    /** Name of the output variable holding the reduced value. */
     as: VariableName;
 }
 
+/**
+ * Options for `transform.aggregate` — groups observations by `groupby`, then reduces each group
+ * to one observation via `operations`. The idiom for pre-summarizing data (e.g. sum revenue per region).
+ */
 declare interface AggregateOptions {
-    /** Variables to group by before aggregating. */
+    /** Variables to group by; one output observation is produced per distinct combination. */
     groupby: VariableName[];
-    /** Aggregation operations to apply per group. */
+    /** One or more reductions to compute per group. */
     operations: AggregateOperation[];
 }
 
+/** Group-and-reduce transform produced by `transform.aggregate`. */
 declare interface AggregateTransformInput {
     type: 'transform';
     transformType: 'aggregate';
@@ -82,11 +108,63 @@ declare interface AnchorSegment {
     direction: 'positive' | 'negative';
 }
 
+/**
+ * The angular span of an arc/wedge in a polar coord, in **radians** (0 = straight up, increasing
+ * clockwise — the d3-arc convention). Either endpoint is `null` when the observation declares no x
+ * interval. Returned by {@link getAngleExtent}.
+ */
 export declare interface AngleExtent {
     startAngle: NumericDataValue;
     endAngle: NumericDataValue;
 }
 
+/**
+ * Builder for the built-in annotation kinds — the pipeable counterpart to setting the `annotations`
+ * field by hand. Each method returns an {@link AnnotationItem}; piped into `createSpec`/`pipe` it appends
+ * to the matching {@link AnnotationsInput} field, so annotations compose left-to-right like every other
+ * spec feature (geoms, scales, highlights). Multiple calls of the same kind accumulate.
+ *
+ * Anchoring differs per kind: only {@link annotation.differenceArrow} snaps to DATA (two observations);
+ * `shape`, `text`, and `freeformArrow` position in panel fractions (`[0,1]`, top-left origin). `sticker`,
+ * `pinnedNumber`, and `comment` compile but have NO painter in `@graphysdk/react-renderer` (editor-only) —
+ * avoid them when authoring for the React renderer. For a data-anchored callout/band beyond a difference
+ * arrow, register a custom kind via `createGraphyBuilder({ annotations })`; its `annotation` builder adds
+ * one method per registered kind alongside these built-ins.
+ *
+ * @example
+ *   import { pipe, createSpec, geom, scale, annotation } from '@graphysdk/viz-engine';
+ *
+ *   pipe(
+ *     createSpec({ x: 'month', y: 'revenue', color: 'region' }),
+ *     geom.line(),
+ *     scale.x.discrete(),
+ *     scale.y(),
+ *     scale.color.palette(),
+ *     annotation.differenceArrow({
+ *       start: { anchorValue: 'Jan', groupValue: 'North' },
+ *       end: { anchorValue: 'Jun', groupValue: 'North' },
+ *       label: 'relative-difference',
+ *     }),
+ *     annotation.shape({ x: 0, y: 0.7, width: 1, height: 0.3, fillColor: '#e15759', fillOpacity: 0.12 }),
+ *   );
+ */
+export declare const annotation: {
+    /** A labelled delta between two data observations — the only built-in kind that snaps to data. */
+    differenceArrow(input: DifferenceArrowInput): AnnotationItem;
+    /** A shaded box positioned in panel fractions (`[0,1]`); does not snap to a data value. */
+    shape(input: ShapeInput): AnnotationItem;
+    /** A free-standing arrow with endpoints in panel fractions (`[0,1]`); does not snap to a data value. */
+    freeformArrow(input: FreeformArrowInput): AnnotationItem;
+    /** A free-standing rich-text label positioned in panel fractions (`[0,1]`); does not snap to a data value. */
+    text(input: TextAnnotationInput): AnnotationItem;
+    /** Editor-only: compiles but has NO painter in `@graphysdk/react-renderer`. */
+    sticker(input: StickerAnnotationInput): AnnotationItem;
+    /** Editor-only: compiles but has NO painter in `@graphysdk/react-renderer`. */
+    pinnedNumber(input: PinnedNumberAnnotationInput): AnnotationItem;
+    /** Editor-only: compiles but has NO painter in `@graphysdk/react-renderer`. */
+    comment(input: CommentAnnotationInput): AnnotationItem;
+};
+
 /**
  * The compile-half definition of a custom annotation kind (ADR-035).
  *
@@ -95,9 +173,11 @@ export declare interface AngleExtent {
  * params })` from `TParams`, merge `defaultParams`, and enforce the optional coordinate arity. The
  * render-half `draw` lives in the renderer and binds to this definition by import (`defineAnnotationRenderer`).
  */
-/** Optional coordinate-count guardrail enforced by the builder; unbounded when omitted. */
+/** Allowed coordinate count for an annotation kind; each bound is inclusive, unbounded when omitted. */
 export declare interface AnnotationArity {
+    /** Minimum coordinates required. */
     min?: number;
+    /** Maximum coordinates allowed. */
     max?: number;
 }
 
@@ -142,18 +222,59 @@ declare interface AnnotationDataPoint {
     rowValue?: DataValue;
 }
 
+/**
+ * The compile-half definition produced by {@link defineAnnotation}. Pass an array of these to
+ * `createGraphyBuilder({ annotations })` to get a typed `annotation.<type>(...)` spec method; the
+ * render-half `draw` binds to it by import in `@graphysdk/react-renderer`.
+ */
 export declare interface AnnotationDef<TParams extends object = object, TType extends string = string> {
+    /** The registered kind name; keys the `annotation.<type>(...)` builder method and the render-side `draw`. */
     type: TType;
     /** Carrier that lets the builder recover `TParams` and merge defaults before a param reaches `draw`. */
     defaultParams: TParams;
+    /** Coordinate-count guardrail enforced by the builder; unbounded when omitted. */
     coordinates?: AnnotationArity;
 }
 
-/** Pipeable spec item produced by the registration-typed `annotation.<kind>(...)` builder. */
-declare interface AnnotationItem {
+/**
+ * Pipeable spec item produced by an `annotation.*` builder. `kind` routes the carried input to the
+ * matching {@link AnnotationsInput} field when the item is folded onto a spec by `createSpec`/`pipe`:
+ * each built-in kind targets its like-named field, and `'custom'` carries a registered
+ * {@link CustomAnnotationInput} onto `annotations.custom`.
+ */
+export declare type AnnotationItem = {
+    type: 'annotation';
+    kind: 'differenceArrow';
+    annotation: DifferenceArrowInput;
+} | {
+    type: 'annotation';
+    kind: 'shape';
+    annotation: ShapeInput;
+} | {
+    type: 'annotation';
+    kind: 'freeformArrow';
+    annotation: FreeformArrowInput;
+} | {
+    type: 'annotation';
+    kind: 'text';
+    annotation: TextAnnotationInput;
+} | {
+    type: 'annotation';
+    kind: 'sticker';
+    annotation: StickerAnnotationInput;
+} | {
+    type: 'annotation';
+    kind: 'pinnedNumber';
+    annotation: PinnedNumberAnnotationInput;
+} | {
     type: 'annotation';
+    kind: 'comment';
+    annotation: CommentAnnotationInput;
+} | {
+    type: 'annotation';
+    kind: 'custom';
     annotation: CustomAnnotationInput;
-}
+};
 
 /** Recovers an annotation definition's params type — carried structurally by its `defaultParams`. */
 declare type AnnotationParamsOf<Definition> = Definition extends AnnotationDef<infer TParams> ? TParams : never;
@@ -182,17 +303,38 @@ declare interface AnnotationsCompilerInput {
     scales: CompiledScales;
 }
 
+/**
+ * Non-data marks layered onto the panel, set as the `annotations` field on a spec. Each field holds a
+ * different built-in kind.
+ *
+ * Anchoring differs per field and is the deciding detail: only `differenceArrows` snap to DATA (two
+ * observations). `shapes`, `textAnnotations` and `freeformArrows` position in panel fractions (`[0,1]`,
+ * top-left origin) — they re-flow on resize but do NOT snap to a data value. For a data-anchored callout,
+ * band, or marker beyond a difference arrow, author a `custom` annotation.
+ *
+ * `stickers`, `pinnedNumbers` and `comments` COMPILE but have no painter in `@graphysdk/react-renderer`
+ * (they draw only in the editor's legacy engine) — don't use them when authoring for the React renderer.
+ */
 export declare interface AnnotationsInput {
+    /** Labelled deltas between two data observations. The only built-in kind that anchors to data. */
     differenceArrows?: DifferenceArrowInput[];
+    /** Shaded boxes positioned in panel fractions (`[0,1]`), not data values. */
     shapes?: ShapeInput[];
+    /** Free-standing arrows positioned in panel fractions (`[0,1]`), not data values. */
     freeformArrows?: FreeformArrowInput[];
+    /** Free-standing rich-text labels positioned in panel fractions (`[0,1]`), not data values. */
     textAnnotations?: TextAnnotationInput[];
+    /** Compiles but has NO painter in `@graphysdk/react-renderer` (editor-only). Avoid here. */
     stickers?: StickerAnnotationInput[];
+    /** Compiles but has NO painter in `@graphysdk/react-renderer` (editor-only). Avoid here. */
     pinnedNumbers?: PinnedNumberAnnotationInput[];
+    /** Compiles but has NO painter in `@graphysdk/react-renderer` (editor-only). Avoid here. */
     comments?: CommentAnnotationInput[];
+    /** Registered custom-annotation instances; the data-anchorable escape hatch when no built-in fits. */
     custom?: CustomAnnotationInput[];
 }
 
+/** Resolved form of {@link AnnotationsInput} — every field present, each entry defaulted. */
 export declare interface AnnotationsSpec {
     differenceArrows: DifferenceArrowSpec[];
     shapes: ShapeSpec[];
@@ -271,6 +413,13 @@ export declare interface AppearanceSpec {
     highlightStyle: HighlightStyle;
 }
 
+/**
+ * Area marks — a line with the region below it filled. Same render knobs as line ({@link AreaGeomParams}).
+ * Use `position: 'stack'` for a stacked area chart or `'fill'` for a 100%-stacked one.
+ *
+ * @example
+ * pipe(createSpec({ x: 'month', y: 'sales', color: 'region' }), geom.area({ position: 'stack' }), scale.x(), scale.y(), scale.color.palette());
+ */
 declare function area(options?: GeomOptions<'area'>): LayerInputOf<'area'>;
 
 /**
@@ -291,21 +440,37 @@ declare class AreaGeom extends Geom {
 }
 
 /**
- * Area-specific parameters (same rendering knobs as line, but fills under the curve)
+ * Render parameters for `geom.area` — same knobs as {@link LineGeomParams}, but the region below the curve
+ * is filled. Passed under `params`.
  */
 export declare interface AreaGeomParams {
+    /**
+     * Outline stroke width in pixels, or `'auto'` to let the theme pick a width.
+     * @default 'auto'
+     */
     lineWidth: number | 'auto';
+    /**
+     * Interpolation method between points: `'linear'` for straight segments, `'catmull-rom'` for a smooth spline.
+     * @default 'linear'
+     */
     interpolate: InterpolateType;
+    /**
+     * How to handle missing (`null`) y-values: `'zero'` drops to zero, `'gap'` breaks the area, `'connect'`
+     * bridges across the gap.
+     * @default 'zero'
+     */
     missingValues: MissingValuesType;
 }
 
+/** An arrow endpoint as a panel fraction (`[0,1]`, top-left origin). */
 export declare interface ArrowEndpoint {
-    /** 0..1 of plot width. */
+    /** `[0,1]` of panel width (0 = left). */
     x: number;
-    /** 0..1 of plot height. */
+    /** `[0,1]` of panel height (0 = top). */
     y: number;
 }
 
+/** Arrowhead at an endpoint: `'none'` (bare line) or `'line-arrow'` (drawn head). */
 export declare type ArrowheadStyle = 'none' | 'line-arrow';
 
 export declare type ArrowLineStyle = 'solid' | 'dashed';
@@ -446,6 +611,14 @@ export declare type BackgroundSpec = {
     color?: string;
 };
 
+/**
+ * Bar/column marks. Drives most categorical charts: plain, stacked (`position: 'stack'`), grouped
+ * (`'dodge'`), 100%-stacked (`'fill'`), horizontal (add `coord.flip()`), and pie/donut (`position: 'fill'`
+ * inside `coord.polar({ theta: 'y' })`). No render `params`.
+ *
+ * @example
+ * pipe(createSpec({ x: 'quarter', y: 'sales', color: 'region' }), geom.bar({ position: 'stack' }), scale.x(), scale.y(), scale.color.palette());
+ */
 declare function bar(options?: GeomOptions<'bar'>): LayerInputOf<'bar'>;
 
 /**
@@ -496,27 +669,68 @@ declare interface BarOptions {
 }
 
 /**
- * Base params shared by all coordinate systems
+ * Params shared by every coordinate system. Axis limits clamp the displayed range
+ * after scaling.
  */
 declare interface BaseCoordParams {
     /**
-     * Limits for x-axis [min, max]
+     * Fixed x-axis range as `[min, max]` in data units, or `null` to auto-fit from data.
+     * @default null
      */
     xLimits: [number, number] | null;
     /**
-     * Limits for y-axis [min, max]
+     * Fixed y-axis range as `[min, max]` in data units, or `null` to auto-fit from data.
+     * @default null
      */
     yLimits: [number, number] | null;
 }
 
+/**
+ * Options accepted by every `geom.*` builder. All fields are optional; each builder fills defaults during
+ * resolution. The generic `T` is the per-geom `params` shape so `geom.line` accepts {@link LineGeomParams}
+ * while `geom.bar` accepts none.
+ */
 declare interface BaseGeomOptions<T extends GeomParams> {
+    /**
+     * Layer-level aesthetic overrides, shallow-merged OVER the spec-level mapping for this layer only.
+     * The place to retarget a channel per layer in a combo (`geom.line({ aes: { y: 'margin' } })`) or to pin a
+     * constant (`aes: { y: { value: 2500 } }` for a reference line).
+     */
     aes?: AesMapping;
+    /**
+     * 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?: StatName | StatInput;
+    /**
+     * How sibling marks sharing an x position are arranged. `'identity'` overlaps them; `'stack'` stacks by
+     * `color`; `'dodge'` places them side by side; `'fill'` stacks then normalises each column to 100% (also
+     * the basis of pie/donut under `coord.polar`). Default is per-geom: `area` → `'stack'`, `bar` → `'dodge'`,
+     * `point`/`line`/`rule` → `'identity'`.
+     */
     position?: PositionType;
+    /**
+     * Which Y axis this layer binds to. `'secondary'` puts it on the right-hand axis for dual-axis combos
+     * (pair with `scale.ySecondary()`); the layer still maps to the `y` channel.
+     * @default 'primary'
+     */
     yScaleType?: YScaleType;
+    /** Geom-specific render knobs — static styling only (widths, colors, interpolation), never data channels. */
     params?: Partial<T>;
+    /**
+     * Ordered transforms applied to this layer's view of the data, on top of the spec-level transforms. Use
+     * when this geom needs a different data shape than its siblings.
+     */
     transforms?: TransformInput[];
+    /**
+     * When `false`, the layer is excluded from hover hit-detection — set it on non-data overlays like
+     * average and trend lines so they don't steal the tooltip. Defaults to `true` for all geoms except `rule`,
+     * which defaults to `false`.
+     */
     interactive?: boolean;
+    /** Per-observation value labels drawn on the marks. Off by default; see {@link DataLabelsInput}. */
     dataLabels?: DataLabelsInput;
 }
 
@@ -989,6 +1203,9 @@ export declare interface CommandStackSnapshot {
  * Comment annotation: a marker dot pinned to a single observation, carrying
  * rich-text content. The renderer's mini view shows a truncated comment; hover
  * reveals the full text.
+ *
+ * NO PAINTER in `@graphysdk/react-renderer` — this compiles but never draws there (it renders only in
+ * the editor's legacy engine). Don't reach for it when authoring for the React renderer.
  */
 declare interface CommentAnnotationInput {
     id?: string;
@@ -996,6 +1213,7 @@ declare interface CommentAnnotationInput {
     content: RichTextContent;
 }
 
+/** Resolved form of {@link CommentAnnotationInput} — defaults applied, anchor normalised. */
 declare interface CommentAnnotationSpec {
     id: string;
     anchor: ObservationAnchor;
@@ -1114,10 +1332,25 @@ 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 reparameterized dataset (may have new computed variables) */
+    /**
+     * The reparameterised dataset: the input dataset with the position columns the mark owns added. Write
+     * each through `variableFor(axis, role | name)` — never a literal column string like `'yMin'` — so the
+     * value readers and the coord projection find them. A geom writes only the columns it owns; the mapper
+     * scales any `scalar` channel that declares an `aes` source in place from the author's mapping.
+     */
     data: Dataset;
-    /** Any mapping overrides produced by the geom */
+    /**
+     * Mapping overrides the geom injects, merged over the layer's mapping. The common case is attaching a
+     * scale a mark needs but the author never mapped — e.g. injecting `{ y: { variable } }` so a price
+     * scale forms for an OHLC mark whose extent comes from a y-interval. Return `{}` to inject nothing;
+     * never echo the author's own aesthetics back here.
+     */
     mapping: AesMapping;
     /**
      * Extra single-observation tooltip rows this geom contributes (e.g. OHLC). The compiler derives
@@ -1555,7 +1788,37 @@ declare interface ComputeFreeformArrowParams {
 }
 
 /**
- * Create a custom  configuration
+ * Pipeable spec item carrying chart-level configuration. Every group is
+ * optional; only the keys you set override the resolved defaults. Accepts:
+ *
+ * - `content`: titles and attribution — `title` / `subtitle` / `caption`
+ *   (each a {@link TextContent}) plus `source` ({@link SourceContent}), each
+ *   paired with an `isXVisible` toggle.
+ * - `legend`: `{ position }` — see {@link LegendPosition}.
+ * - `axes`: per-axis `{ x, y, ySecondary }` overrides, e.g. `{ label }`.
+ * - `numberFormat`: chart-wide number formatting — see {@link NumberFormatConfig}.
+ * - `headline`: big-number summary figure — `show` / `compareWith` / `size` /
+ *   `position` (see {@link HeadlineShow}, highlights-headlines.md).
+ * - `appearance`: render-only styling — `textScale`, `highlightStyle`,
+ *   `background`, `border`, `cornerRadius` (see {@link AppearanceSpec}).
+ *
+ * @example
+ *   import { pipe, createSpec, geom, scale, config } from '@graphysdk/viz-engine';
+ *
+ *   pipe(
+ *     createSpec({ x: 'quarter', y: 'revenue', color: 'region' }),
+ *     geom.bar({ position: 'stack' }),
+ *     scale.x(),
+ *     scale.y(),
+ *     config({
+ *       content: { title: 'Quarterly revenue by region', source: { label: 'Finance', url: 'https://…' } },
+ *       legend: { position: 'top' },
+ *       axes: { y: { label: 'Revenue ($)' } },
+ *       numberFormat: { decimals: 0, abbreviation: 'auto', prefix: '$' },
+ *       headline: { show: 'total' },
+ *       appearance: { highlightStyle: 'dim' },
+ *     })
+ *   );
  */
 export declare function config(options: ConfigInput): ConfigItem;
 
@@ -1572,6 +1835,10 @@ 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?: LegendConfigInput;
     content?: ContentInput;
@@ -1586,8 +1853,9 @@ declare interface ConfigItem {
 }
 
 /**
- * Feature configuration with resolved defaults.
- * All fields are required and always populated after resolution.
+ * Fully-resolved chart configuration: every group present with defaults
+ * applied. This is the shape carried on a compiled spec; authors pass the
+ * partial {@link ConfigInput} to `config(...)` instead.
  */
 export declare interface ConfigSpec {
     parsingLocale: Locale;
@@ -1624,15 +1892,20 @@ declare interface ConstantMappingCompilerOutput {
 /***************************************************************
  * Constant Transform
  ***************************************************************/
+/**
+ * Options for `transform.constant` — adds a new variable with the same value on every observation.
+ * Useful to synthesize a constant axis or a single-category grouping variable.
+ */
 declare interface ConstantOptions {
-    /** The name of the new variable. */
+    /** Name of the new variable to add. */
     variableName: VariableName;
-    /** The type of the new variable. */
+    /** Data type of the new variable. */
     type: DataType;
-    /** The constant value to assign to every observation. */
+    /** The constant value assigned to every observation. */
     value: DataValue;
 }
 
+/** Add-a-constant-column transform produced by `transform.constant`. */
 declare interface ConstantTransformInput {
     type: 'transform';
     transformType: 'constant';
@@ -1662,17 +1935,29 @@ declare interface Content {
  * hide cycles without losing the text the user typed.
  */
 export declare interface ContentConfig {
+    /** Main chart title. `null` = unset. */
     title: TextContent | null;
+    /** @default true */
     isTitleVisible: boolean;
+    /** Secondary line shown under the title. `null` = unset. */
     subtitle: TextContent | null;
+    /** @default true */
     isSubtitleVisible: boolean;
+    /** Explanatory note shown below the plot. `null` = unset. */
     caption: TextContent | null;
+    /** @default false */
     isCaptionVisible: boolean;
+    /** Data-source attribution shown under the caption. `null` = unset. */
     source: SourceContent | null;
+    /** @default false */
     isSourceVisible: boolean;
 }
 
-/** Content input — all fields optional. */
+/**
+ * Author-facing `content` argument to `config(...)`: all fields optional.
+ * Setting a text slot does not show it unless the matching `isXVisible` flag is
+ * also true (title and subtitle default visible; caption and source default hidden).
+ */
 declare type ContentInput = Partial<ContentConfig>;
 
 declare type ContinuousScaleInput = {
@@ -1758,27 +2043,60 @@ declare type ContinuousScaleSpec = Required<ContinuousScaleInput>;
  */
 export declare function convertSpecToInput(spec: Spec): SpecInput;
 
+/**
+ * Coordinate-system builder. A coord is a geom-agnostic projection applied AFTER scaling
+ * that remaps the already-scaled `[0,1]` positions of any geom; it changes neither the data,
+ * the scales, nor the chart's tier. Pipe at most one onto a spec — cartesian is assumed when
+ * none is given.
+ *
+ * - `cartesian` — standard x→horizontal, y→vertical (the default).
+ * - `flip` — swaps the x and y axes; the idiom for horizontal bars and long category labels.
+ * - `polar` — wraps x/y around a centre; `theta` selects the angle aesthetic and the other
+ *   becomes the radius. The basis for pie, donut, and radar charts.
+ *
+ * @example
+ *   import { pipe, createSpec, geom, scale, coord } from '@graphysdk/viz-engine';
+ *
+ *   // Donut: stacked value → angle, innerRadius > 0 carves the hole
+ *   pipe(
+ *     createSpec({ x: '', y: 'spend', color: 'department' }),
+ *     geom.bar({ position: 'fill' }),
+ *     coord.polar({ theta: 'y', innerRadius: 0.55 }),
+ *     scale.x(),
+ *     scale.y(),
+ *     scale.color.palette()
+ *   );
+ */
 export declare const coord: {
     /**
-     * Standard cartesian (x-y) coordinate system. This is the default if no coord is specified.
+     * Standard cartesian (x→horizontal, y→vertical) coordinate system. This is the default
+     * when no coord is piped onto the spec; declare it explicitly only to set axis limits.
      *
      * @example coord.cartesian() // auto-scaled axes
-     * @example coord.cartesian({ yLimits: [0, 100] }) // fixed y-axis
+     * @example coord.cartesian({ yLimits: [0, 100] }) // fixed y-axis range
      */
     cartesian: (params?: Partial<CartesianCoordParams>) => CartesianCoordInput;
     /**
-     * Flipped cartesian coordinates — swaps x and y axes.
-     * Useful for horizontal bar charts or when category labels are long.
+     * Flipped cartesian coordinates — swaps the x and y axes so the x aesthetic runs
+     * vertically and y runs horizontally. The idiom for horizontal bar charts and for
+     * long category labels. The mapping stays the same; only the on-screen orientation flips.
      *
-     * @example coord.flip() // horizontal bars
+     * @example coord.flip() // horizontal bars from a vertical-bar spec
      */
     flip: (params?: Partial<FlipCoordParams>) => FlipCoordInput;
     /**
-     * Polar coordinate system — maps data to angle (theta) and radius.
-     * Used for pie charts, donut charts, and radar/radial visualizations.
+     * Polar coordinate system — wraps the scaled positions around a centre, mapping one
+     * aesthetic to the angle (theta) and the other to the radius (scaled into
+     * `[innerRadius, 1]`). `theta` defaults to `'x'`.
+     *
+     * - Pie / donut: `geom.bar({ position: 'fill' })` with `theta: 'y'` (stacked value → angle);
+     *   set `innerRadius > 0` for a donut.
+     * - Radar / spider: `geom.line` or `geom.point` with `theta: 'x'` over a discrete x axis
+     *   (one evenly-spaced spoke per category).
      *
-     * @example coord.polar() // pie chart
-     * @example coord.polar({ innerRadius: 0.5 }) // donut chart
+     * @example coord.polar({ theta: 'y' }) // pie: stacked value → angle
+     * @example coord.polar({ theta: 'y', innerRadius: 0.5, startAngle: 90 }) // donut rotated 90°
+     * @example coord.polar({ theta: 'x' }) // radar: category → spoke angle
      */
     polar: (params?: Partial<PolarCoordParams>) => PolarCoordInput;
 };
@@ -1797,7 +2115,10 @@ declare class CoordCompiler {
 }
 
 /**
- * Discriminated union of all coordinate input specs (user-provided, optional params).
+ * A coordinate system produced by the `coord` builder, before resolution.
+ * A coord is a geom-agnostic projection applied AFTER scaling: it remaps the already-scaled
+ * `[0,1]` positions of any geom without touching the data, the scales, or the chart's tier.
+ * One coord per spec; defaults to cartesian when none is piped on.
  */
 declare type CoordInput = CartesianCoordInput | FlipCoordInput | PolarCoordInput;
 
@@ -1821,7 +2142,7 @@ declare type CoordSetupResult = {
 };
 
 /**
- * Discriminated union of all resolved coordinate specs (params fully defaulted).
+ * A fully resolved coordinate system (params defaulted) as it appears on the compiled spec.
  */
 declare type CoordSpec = CartesianCoordSpec | FlipCoordSpec | PolarCoordSpec;
 
@@ -1896,19 +2217,19 @@ export declare function createEmptyHighlight(strategy: HighlightStrategy | null)
 
 /**
  * Builds a Graphy authoring surface for a set of custom geoms and/or annotations: a `geom` builder that
- * merges the built-in methods with one method per registered custom geom, an `annotation` builder with
- * one method per registered annotation kind, plus the standard `createSpec`. The 90% case stays the
- * plain `import { geom, createSpec }`; reach for this only when authoring custom geoms (decision 8) or
- * custom annotations (ADR-035). Registration is per-instance — geoms are injected to
- * `createCompiler({ geoms })`; annotations need no compile-side registry (coordinate resolution is
- * generic), only the render plugin via `<GraphProvider annotationPlugins={[...]}>`.
+ * merges the built-in methods with one method per registered custom geom, an `annotation` builder that
+ * merges the built-in kinds with one method per registered annotation kind, plus the standard
+ * `createSpec`. The 90% case stays the plain `import { geom, annotation, 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 Annotations extends readonly AnnotationDef[] = readonly []>(options: {
     geoms?: Geoms;
     annotations?: Annotations;
 }): {
     geom: typeof geom & CustomGeomBuilders<Geoms>;
-    annotation: CustomAnnotationBuilders<Annotations>;
+    annotation: typeof annotation & CustomAnnotationBuilders<Annotations>;
     createSpec: typeof createSpec;
 };
 
@@ -1935,20 +2256,32 @@ export declare function createSegmentYReader(layer: CompiledLayer): (observation
 export declare const createSizeValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
 
 /**
- * Create a new spec, optionally piping spec items in one call. Data is passed separately
- * to {@link compile}.
+ * Seed a spec — the entry point for every chart. The first argument may be a bare {@link AesMapping}
+ * (`{ x, y, color, ... }`), which becomes the spec's global aesthetic mapping; any further arguments are
+ * pipeable spec items (geoms, scales, coords, transforms, config, ...) folded on in order. Data is supplied
+ * separately to `compile` / `<GraphProvider data>`.
+ *
+ * This is the builder pattern: `createSpec` seeds the mapping, then `pipe` (or extra args here) folds each
+ * item onto an immutable spec, accumulating layers/scales/etc. Always declare `scale.x()` / `scale.y()` for
+ * any position channel — they are NOT auto-inferred and yield NaN positions if omitted.
  *
  * @example
- * When the first arg is a mapping:
- *   createSpec({ x: 'date', y: 'value' })
+ * import { createSpec, pipe, geom, scale } from '@graphysdk/viz-engine';
  *
- * When piping spec items (more readable when chaining transforms):
- *   createSpec(
- *     transform.reshape({ reshape: ['revenue'], keyName: 'metric', valueName: 'amount' }),
- *     mapping({ x: 'month', y: 'amount', color: 'metric' }),
- *     geom.bar(),
- *     scale.x(),
- *   )
+ * // Most common: mapping first, then pipe the rest.
+ * const spec = pipe(createSpec({ x: 'category', y: 'revenue' }), geom.bar(), scale.x(), scale.y());
+ *
+ * @example
+ * import { createSpec, transform, mapping, geom, scale } from '@graphysdk/viz-engine';
+ *
+ * // All-in-one form, clearer when a transform must run before the mapping is read.
+ * const spec = createSpec(
+ *   transform.reshape({ reshape: ['revenue'], keyName: 'metric', valueName: 'amount' }),
+ *   mapping({ x: 'month', y: 'amount', color: 'metric' }),
+ *   geom.bar(),
+ *   scale.x(),
+ *   scale.y(),
+ * );
  */
 export declare function createSpec(...items: Array<AesMapping | SpecItem>): SpecInput;
 
@@ -2002,6 +2335,7 @@ declare interface CustomAnnotationOptions<TParams extends object> {
     id?: string;
 }
 
+/** Resolved form of {@link CustomAnnotationInput} — params defaulted to `{}`, coordinates resolved. */
 export declare interface CustomAnnotationSpec {
     id: string;
     type: string;
@@ -2065,12 +2399,13 @@ declare type CustomPaletteInput = {
 export declare type CustomPalettesInput = Record<string, string[]>;
 
 /**
- * Data to visualize. Structured as a table.
+ * The raw input dataset to visualize, structured as a table of `columns` + `rows`. This is what you
+ * hand to the compiler and to `<GraphProvider data>` — the untransformed, pre-compile shape, distinct
+ * from the per-observation {@link Observation} records a geom reads after compilation.
  *
- * The public-API contract. Row values must be {@link DataValue} (string, number,
- * Date, or null). Internal entry points (e.g. the dataset parser) accept a
- * looser row type — see {@link RawData} — because they must defensively handle
- * malformed input.
+ * The public-API contract: row values must be {@link DataValue} (string, number, Date, or null).
+ * Internal entry points (e.g. the dataset parser) accept a looser row type — see {@link RawData} —
+ * because they must defensively handle malformed input.
  */
 export declare interface Data {
     /**
@@ -2158,6 +2493,11 @@ export declare interface DataLabelsContent {
     labels: PlacedDataLabel[];
 }
 
+/**
+ * User-facing data-labels options for a layer (`geom.x({ dataLabels })`). A partial of {@link DataLabelsConfig}
+ * minus `labelSource` (the label source is derived from the geom, not set here); unset fields fall back to the
+ * config defaults. Set `{ showDataLabels: true }` to turn labels on.
+ */
 export declare type DataLabelsInput = DeepPartial<Omit<DataLabelsConfig, 'labelSource'>>;
 
 /**
@@ -2181,6 +2521,10 @@ export declare type DataLabelTextMeasurer = (kind: DataLabelKind, text: string)
  *
  * All transformation methods (filter, orderBy, addVariable etc.) return a new instance.
  *
+ * In a geom, this is what a `compile()` half reparameterises (e.g. `addVariable` to write computed
+ * columns) and what a render half receives as `layer.data` — iterate it (or `groupBy` it) to walk the
+ * compiled {@link Observation}s and read each mark's positions with the value readers.
+ *
  * @example
  * const data = new Dataset({
  *   age: { type: 'numeric', values: [25, 30, 35, null] },
@@ -2472,6 +2816,10 @@ declare type DefaultPaletteConfig = {
 };
 
 /**
+ * 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
@@ -2509,25 +2857,34 @@ declare interface DifferenceArrowDimensions {
 }
 
 /**
- * User-facing difference-arrow input. `size`, `color` and `labelCrossPosition`
- * are defaulted by the resolver.
+ * A labelled delta drawn between two data observations — the only built-in annotation that anchors to
+ * DATA. Both endpoints are observation anchors (main-axis value + series), so the arrow snaps to the
+ * dataset and survives resize. Only drawn under a cartesian coordinate system. `size`, `color` and
+ * `labelCrossPosition` are defaulted by the resolver.
  */
 export declare interface DifferenceArrowInput {
     id?: string;
+    /** Observation the arrow starts from. */
     start: ObservationAnchorInput;
+    /** Observation the arrow points to. */
     end: ObservationAnchorInput;
+    /** Which delta the label reports. */
     label: DifferenceArrowLabelKind;
+    /** Arrow colour; `null`/omitted falls back to the theme default. @default null */
     color?: string | null;
+    /** @default 'small' */
     size?: DifferenceArrowSize;
+    /** Where the label sits along the arrow's cross-axis, as a `[0,1]` fraction. @default 0.5 */
     labelCrossPosition?: number;
 }
 
+/** What the arrow's label reports about the `start → end` delta. */
 export declare type DifferenceArrowLabelKind = 'absolute-difference' | 'relative-difference' | 'proportion';
 
 export declare type DifferenceArrowSize = 'small' | 'medium' | 'large';
 
 /**
- * Resolved difference-arrow spec with all optional fields defaulted.
+ * Resolved form of {@link DifferenceArrowInput} — defaults applied, anchors normalised.
  */
 export declare interface DifferenceArrowSpec {
     id: string;
@@ -2619,15 +2976,19 @@ declare function filter(options: FilterOptions): FilterTransformInput;
 /***************************************************************
  * Filter Transform
  ***************************************************************/
+/**
+ * Options for `transform.filter` — keeps only observations where `variableName <operator> value`.
+ */
 declare interface FilterOptions {
     /** The variable to filter on. */
     variableName: VariableName;
-    /** The comparison operator. */
+    /** Comparison operator: `'eq'` | `'neq'` | `'gt'` | `'gte'` | `'lt'` | `'lte'`. */
     operator: ComparisonOperator;
-    /** The value to compare against. */
+    /** The value to compare each observation's `variableName` against. */
     value: DataValue;
 }
 
+/** Row-filtering transform produced by `transform.filter`. */
 declare interface FilterTransformInput {
     type: 'transform';
     transformType: 'filter';
@@ -2784,23 +3145,31 @@ export declare interface FormattedPerGroupHeadline {
 }
 
 /**
- * Freeform arrow annotation. Endpoints sit in plot-fractional coordinates
- * (0..1), so they re-flow with panel size. Distinct from
- * {@link DifferenceArrowInput}, which anchors to dataset observations.
+ * A free-standing arrow pointing at something on the panel. Both endpoints sit in panel fractions
+ * (`[0,1]`, top-left origin), so they re-flow with panel size but do NOT snap to a data point. Distinct
+ * from {@link DifferenceArrowInput}, which anchors to dataset observations.
  */
 export declare interface FreeformArrowInput {
     id?: string;
+    /** Tail endpoint. */
     start: ArrowEndpoint;
+    /** Head endpoint (the end pointed at). */
     end: ArrowEndpoint;
-    /** null falls back to the theme `defaultAnnotationArrowStroke`. */
+    /** `null` falls back to the theme `defaultAnnotationArrowStroke`. @default null */
     color?: string | null;
+    /** @default 'medium' */
     thickness?: ArrowThickness;
+    /** Arrowhead at the `start` (tail) endpoint. @default 'none' */
     startArrowheadStyle?: ArrowheadStyle;
+    /** Arrowhead at the `end` (head) endpoint. @default 'line-arrow' */
     endArrowheadStyle?: ArrowheadStyle;
+    /** @default 'solid' */
     lineStyle?: ArrowLineStyle;
+    /** Apply the editor's hand-drawn "sticker" styling. @default false */
     hasStickerStyle?: boolean;
 }
 
+/** Resolved form of {@link FreeformArrowInput} — defaults applied. */
 export declare interface FreeformArrowSpec {
     id: string;
     start: ArrowEndpoint;
@@ -2945,6 +3314,25 @@ 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;
@@ -3004,12 +3392,31 @@ 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 */
+    /**
+     * The dataset after stat transformation — one row per observation, columnar. Read a mapped channel's
+     * column with `extractVariableName(mapping[channel])`, then `data.getValues(column, { type })`; write
+     * computed columns with `data.addVariable` / `data.addConstantVariable` (each returns a new dataset —
+     * the Dataset is immutable).
+     */
     data: Dataset;
-    /** The effective mapping for the layer */
+    /**
+     * The effective mapping for the layer: which data column (or constant) backs each aesthetic the author
+     * declared. The source of every channel column the geom reads — including the custom `aes` channels in
+     * {@link Geom.requiredAesthetics} (an OHLC `open`, a box plot `q1`). Read a custom channel with
+     * `readAesthetic(mapping, channel)`.
+     */
     mapping: AesMapping;
-    /** Geom-specific params */
+    /**
+     * The geom's static params, already merged over {@link Geom.defaultParams} by the builder. Render
+     * configuration only (widths, radii, colours) — never data columns that bind to a scale, which belong
+     * in `aes`. Typed as the geom's `TParams` at the call site.
+     */
     params: LayerSpec['params'];
 }
 
@@ -3079,12 +3486,27 @@ export declare interface GeomTooltipRow {
     variable: VariableName;
 }
 
-/** Reads the resolved alpha (opacity) value from an observation. */
+/**
+ * Reads the observation's resolved opacity in `[0,1]` (0 = transparent, 1 = opaque) — pass straight to
+ * `fillOpacity`/`opacity`. The `alpha` aesthetic mapped through its scale. `null` when no `alpha`
+ * aesthetic is mapped.
+ */
 export declare function getAlpha(observation: Observation): NumericDataValue;
 
+/**
+ * Reads a polar observation's angular extent — the x interval projected to angles. Use it to draw the
+ * wedge of a pie/donut slice or polar bar; pair with {@link getRadiusExtent} for the radial span.
+ * `startAngle`/`endAngle` are in **radians** (0 = straight up, increasing clockwise). The compiler has
+ * already projected the x interval under `coord.polar()`, so no manual angle math is needed.
+ */
 export declare function getAngleExtent(observation: Observation): AngleExtent;
 
-/** Reads the resolved color string from an observation. */
+/**
+ * Reads the observation's resolved fill/stroke colour as a paint-ready CSS colour string. The visual
+ * mapper has already run the `color` aesthetic through the colour scale, so this is the final string to
+ * hand to `fill`/`stroke` — no further lookup needed. `undefined` when the layer maps no `color`
+ * aesthetic; supply your own series colour (e.g. via `useCategoricalColor`) in that case.
+ */
 export declare function getColor(observation: Observation): string | undefined;
 
 /** Reads the coordinate lying on the cross axis of the coord system. */
@@ -3098,6 +3520,13 @@ export declare function getCrossAxisCoordinate(mainAxis: MainAxis, point: XYPoin
  */
 export declare const getDifferenceArrowDimensions: (size: DifferenceArrowSize, textScale: number) => DifferenceArrowDimensions;
 
+/**
+ * Reads the observation's resolved series identity: the category the `group`/`color` aesthetic placed
+ * it in, as a plain string. Use it to split a layer's observations into series (one polygon, line, or
+ * colour per group) when painting. `null` when the layer maps no grouping aesthetic — a single,
+ * ungrouped series. Reads the compiler-emitted `group` column, so the value survives any renaming of
+ * the user's grouping mapping.
+ */
 export declare const getGroup: (observation: Observation) => CategoricalDataValue;
 
 /**
@@ -3108,20 +3537,33 @@ export declare const getGroup: (observation: Observation) => CategoricalDataValu
 export declare const getIdentityKey: (observation: Observation) => string;
 
 /**
- * Reads the resolved line type (stroke style) from an observation.
- * Falls back to `'solid'` when no `lineType` variable was derived.
+ * Reads the observation's resolved line style (`'solid'`, `'dashed'`, …) for use as a stroke pattern.
+ * The `lineType` aesthetic mapped through its scale, falling back to `'solid'` when no `lineType`
+ * aesthetic is mapped — so this reader, unlike the others, never returns `null`.
  */
 export declare function getLineType(observation: Observation): LineStyleType;
 
 /** Reads the coordinate lying on the main (independent) axis of the coord system. */
 export declare function getMainAxisCoordinate(mainAxis: MainAxis, point: XYPoint): number;
 
+/**
+ * Reads a polar observation's radial extent — the y interval projected to radii. Use it with
+ * {@link getAngleExtent} to draw a donut/polar-bar segment. `innerRadius`/`outerRadius` are in `[0,1]`
+ * (0 = centre, 1 = outer ring); `outerRadius` falls back to the `point` y radius when the observation
+ * carries no upper y endpoint (a pie slice, which has no inner cutout to oppose).
+ */
 export declare function getRadiusExtent(observation: Observation): RadiusExtent;
 
-/** Reads the resolved size value from an observation. */
+/**
+ * Reads the observation's resolved size in **pixels** (e.g. a point's diameter or a mark's nominal
+ * extent), already mapped through the `size` scale. `null` when no `size` aesthetic is mapped.
+ */
 export declare function getSize(observation: Observation): NumericDataValue;
 
-/** Reads the resolved stroke width value from an observation. */
+/**
+ * Reads the observation's resolved stroke width in **pixels** — pass straight to `strokeWidth`. The
+ * `strokeWidth` aesthetic mapped through its scale. `null` when no `strokeWidth` aesthetic is mapped.
+ */
 export declare function getStrokeWidth(observation: Observation): NumericDataValue;
 
 declare interface GetValuesOptions {
@@ -3133,29 +3575,61 @@ declare interface GetValuesOptions {
     distinct?: boolean;
 }
 
-/** Reads the normalized x position from an observation. */
+/**
+ * Reads the observation's scaled x position: the value of the `point` x channel, already mapped
+ * through the x scale to `[0,1]` of the panel width (0 = left edge, 1 = right edge). `null` when the
+ * observation has no x position. Under `coord.polar({ theta: 'x' })` this returns the vertex **angle
+ * in radians** instead (0 = straight up, increasing clockwise). The everyday position reader — pair
+ * it with {@link getY} to place a point-anchored mark.
+ */
 export declare function getX(observation: Observation): NumericDataValue;
 
-/** Reads the normalized xMax (right band edge) from an observation. */
+/**
+ * Reads the upper x endpoint of the observation's x interval, scaled to `[0,1]` of the panel width
+ * (1 = right edge). The right edge of a band/bar or the end of a horizontal range bar. Pairs with
+ * {@link getXMin}. `null` when the observation declares no x interval.
+ */
 export declare function getXMax(observation: Observation): NumericDataValue;
 
-/** Reads the normalized xMin (left band edge) from an observation. */
+/**
+ * Reads the lower x endpoint of the observation's x interval, scaled to `[0,1]` of the panel width
+ * (0 = left edge). The left edge of a band/bar, the start of a horizontal range bar, or a body's left
+ * side. Pairs with {@link getXMax}; `getXMin`/`getXMax` preserve the values `compile()` wrote and are
+ * never re-sorted, so `getXMin` can exceed `getXMax`. `null` when the observation declares no x interval.
+ */
 export declare function getXMin(observation: Observation): NumericDataValue;
 
-/** Reads the normalized y position from an observation. */
+/**
+ * Reads the observation's scaled y position: the value of the `point` y channel, already mapped
+ * through the y scale to `[0,1]` of the panel height with a **bottom origin** (0 = bottom, 1 = top).
+ * SVG y grows downward, so paint with `1 - getY(...)`. `null` when the observation has no y position.
+ * Under polar coords this returns the **radius in `[0,1]`** (0 = centre, 1 = outer ring). See
+ * {@link getYRaw} to recover the pre-stack segment magnitude.
+ */
 export declare function getY(observation: Observation): NumericDataValue;
 
-/** Reads the normalized yMax (upper extent) from an observation. */
+/**
+ * Reads the upper y endpoint of the observation's y interval, scaled to `[0,1]` of the panel height
+ * with a **bottom origin** (1 = top; paint with `1 - getYMax(...)`). The bar top, the top of a
+ * candlestick wick, or the end of a vertical range/gantt span. Pairs with {@link getYMin}.
+ * `null` when the observation declares no y interval.
+ */
 export declare function getYMax(observation: Observation): NumericDataValue;
 
-/** Reads the normalized yMin (lower extent) from an observation. */
+/**
+ * Reads the lower y endpoint of the observation's y interval, scaled to `[0,1]` of the panel height
+ * with a **bottom origin** (0 = bottom; paint with `1 - getYMin(...)`). The bar baseline, the bottom of
+ * a candlestick wick, or the start of a vertical range/gantt span. Pairs with {@link getYMax}; the pair
+ * preserves the values `compile()` wrote and is never re-sorted, so `getYMin` can exceed `getYMax`.
+ * `null` when the observation declares no y interval.
+ */
 export declare function getYMin(observation: Observation): NumericDataValue;
 
 /**
- * Reads the segment value written by stacking position adjusters.
- *
- * Survives theposition-mapper untouched, so renderers can recover original-unit values
- * for stacked segments after `mapping.y` has been rewritten to the cumulative band top.
+ * Reads the observation's pre-stack segment magnitude in **original data units** (not `[0,1]`).
+ * Stacking position adjusters rewrite the mapped `y` to the cumulative band top and stash the segment's
+ * own value here, so a renderer or data label can recover what the segment contributed before stacking.
+ * `null` when the layer was not stacked (the column is written only when stacking along y).
  */
 export declare function getYRaw(observation: Observation): NumericDataValue;
 
@@ -3542,15 +4016,29 @@ export declare class HeuristicTextMeasurer implements TextMeasurer {
 }
 
 /**
- * Create a pipeable highlight spec item.
+ * Pipeable spec item that emphasises the observations matching `predicate` and
+ * de-emphasises (dims or desaturates) everything else. Multiple `highlight(...)`
+ * calls accumulate — their matches union. The de-emphasis style is chosen
+ * separately via `config({ appearance: { highlightStyle: 'dim' | 'desaturate' } })`.
+ *
+ * @param predicate - which observations to emphasise (see {@link Predicate}).
+ * @param options - `scope` ({@link HighlightScope}, default `'data-point'`),
+ *   `layerIndex` (target a single layer; omit to apply to all layers), and an
+ *   optional explicit `id`.
  *
  * @example
+ *   import { pipe, createSpec, geom, scale, highlight } from '@graphysdk/viz-engine';
+ *
  *   pipe(
- *     createSpec(data, { x: 'month', y: 'revenue', color: 'region' }),
+ *     createSpec({ x: 'month', y: 'revenue', color: 'region' }),
  *     geom.bar(),
- *     highlight({ field: 'region', eq: 'EU' }),
- *     highlight({ field: 'region', eq: 'US' }, { scope: 'series' }),
- *   )
+ *     scale.x(),
+ *     scale.y(),
+ *     // emphasise one whole series; leave other layers untouched
+ *     highlight({ variable: 'region', eq: 'EU' }, { scope: 'series' }),
+ *     // and every observation at or above a threshold
+ *     highlight({ variable: 'revenue', gte: 2000 })
+ *   );
  */
 export declare function highlight(predicate: Predicate, options?: HighlightBuilderOptions): HighlightInput;
 
@@ -4169,8 +4657,9 @@ declare interface Legend {
  */
 declare interface LegendConfig {
     /**
-     * Position of the legend
-     * @default 'top'
+     * Where the legend sits relative to the plot. See {@link LegendPosition} for the values;
+     * `'auto'` lets the renderer pick based on chart type and series count.
+     * @default 'auto'
      */
     position: LegendPosition;
     /**
@@ -4230,8 +4719,23 @@ declare interface LegendItemVisual {
     lineType?: LineStyleType;
 }
 
+/**
+ * Where the legend sits relative to the plot, set via
+ * `config({ legend: { position: … } })`.
+ * - 'auto': let the compiler choose based on chart type (default).
+ * - 'right' | 'left' | 'top' | 'bottom': pin to that edge.
+ * - 'none': hide the legend entirely.
+ */
 declare type LegendPosition = 'auto' | 'right' | 'left' | 'top' | 'bottom' | 'none';
 
+/**
+ * Line marks — connected series. One line per `group` (defaults to the `color` column). Tune the stroke via
+ * {@link LineGeomParams}. Pair with `stat.smooth()` for a trendline. Observations are connected in data
+ * order, so sort by x first.
+ *
+ * @example
+ * pipe(createSpec({ x: 'month', y: 'sales', color: 'region' }), geom.line(), scale.x(), scale.y(), scale.color.palette());
+ */
 declare function line(options?: GeomOptions<'line'>): LayerInputOf<'line'>;
 
 /**
@@ -4254,17 +4758,22 @@ declare class LineGeom extends Geom {
 }
 
 /**
- * Line-specific parameters
+ * Render parameters for `geom.line`. Passed under `params`.
  */
 export declare interface LineGeomParams {
+    /**
+     * Stroke width in pixels, or `'auto'` to let the theme pick a width.
+     * @default 'auto'
+     */
     lineWidth: number | 'auto';
     /**
-     * Interpolation method to use for the line.
+     * Interpolation method between points: `'linear'` for straight segments, `'catmull-rom'` for a smooth spline.
      * @default 'linear'
      */
     interpolate: InterpolateType;
     /**
-     * How to handle missing (NULL/undefined) values.
+     * How to handle missing (`null`) y-values: `'gap'` breaks the line, `'zero'` drops to zero, `'connect'`
+     * bridges across the gap.
      * @default 'gap'
      */
     missingValues: MissingValuesType;
@@ -4291,7 +4800,12 @@ export declare type Locale = (typeof LOCALES)[number];
 /** A BCP-47 string representing a supported locale. */
 declare const LOCALES: readonly ["en-GB", "en-US", "ar", "pt-PT"];
 
-/** Logical composition of any predicate. */
+/**
+ * Boolean composition of nested predicates:
+ * - `and`: every sub-predicate matches.
+ * - `or`: at least one matches.
+ * - `not`: the sub-predicate does not match.
+ */
 export declare type LogicalPredicate = {
     and: Predicate[];
 } | {
@@ -4326,7 +4840,9 @@ export declare type MainAxis = 'x' | 'y';
 declare type MappableAes<Definition extends Geom> = Definition['requiredAesthetics'][number] | Definition['visualAesthetics'][number] | 'group';
 
 /**
- * Create a pipeable mapping spec item.
+ * Create a pipeable mapping spec item. Use this form (rather than passing the mapping as the first
+ * `createSpec` arg) when a transform must run before the mapping is read — e.g. reshaping wide columns
+ * to long so a freshly-created column can be bound to a channel.
  *
  * @example
  * createSpec(
@@ -4339,7 +4855,8 @@ declare type MappableAes<Definition extends Geom> = Definition['requiredAestheti
 export declare function mapping(aes: AesMapping): MappingItem;
 
 /**
- * A pipeable spec item that sets/merges the global aesthetic mapping.
+ * A pipeable spec item that sets/merges the global {@link AesMapping}. Produced by {@link mapping} and
+ * folded into the spec by `pipe`/`createSpec`; later mapping items shallow-merge over earlier channels.
  */
 declare interface MappingItem {
     type: 'mapping';
@@ -4455,14 +4972,16 @@ declare type NeonPaletteConfig = {
 declare type NeonPaletteVariant = 'default' | 'waterfall';
 
 /**
- * Configuration for formatting a single number.
- * Defines how numeric values should be displayed in the chart.
+ * Chart-wide number formatting, applied by the renderer to every numeric value
+ * (axis ticks, tooltips, data labels, headline figures). Set via
+ * `config({ numberFormat: { … } })`.
  */
 export declare interface NumberFormatConfig {
     /**
      * Number of decimal places to display.
      * - number: Fixed decimal places (e.g., 2 → "1234.56")
-     * - 'auto': Automatic based on value magnitude (default)
+     * - 'auto': Automatic based on value magnitude
+     * @default 'auto'
      */
     decimals: number | 'auto';
     /**
@@ -4472,6 +4991,7 @@ export declare interface NumberFormatConfig {
      * - 'k': Force thousands (1234567 → "1,234.6K")
      * - 'm': Force millions (1234567 → "1.2M")
      * - 'b': Force billions (1234567890 → "1.2B")
+     * @default 'auto'
      */
     abbreviation: 'auto' | 'k' | 'm' | 'b' | 'none';
     /**
@@ -4500,7 +5020,13 @@ declare interface NumericValueFormat {
     type: 'decimal' | 'integer' | 'percentage' | 'duration';
 }
 
-/** A single row of data, mapping every variable name to the value in that row. */
+/**
+ * One compiled per-observation record — the unit a geom's render half iterates and reads to paint a
+ * single mark. Maps every variable name (the author's data columns plus the compiler's internal
+ * position/visual/group columns) to that observation's value. Read positions and encodings off it with
+ * the value readers ({@link getX}, {@link getYMin}, {@link getColor}, …) rather than indexing internal
+ * keys by hand; read your own named columns with `readNumber`/`readString`.
+ */
 export declare type Observation = Record<VariableName, DataValue>;
 
 /**
@@ -4519,13 +5045,16 @@ export declare interface ObservationAnchor {
     groupValue: DataValue;
 }
 
-/** Points at a single observation by its anchor value and series. */
+/**
+ * Snaps to a single data observation by its main-axis value and series. The annotation tracks that
+ * observation across resize and re-layout (unlike panel-fractional positioning).
+ */
 export declare interface ObservationAnchorInput {
-    /** Pick a specific layer when multiple share the same `(anchorValue, groupValue)` pair. */
+    /** Pick a specific layer when multiple share the same `(anchorValue, groupValue)` pair. Index into the spec's layers. */
     layerIndex?: number;
-    /** Value on the main axis (x in cartesian, y in flipped). */
+    /** Value on the main axis (x in cartesian, y in flipped) that selects the observation. */
     anchorValue: DataValue;
-    /** Series identity (the `group` aesthetic value). */
+    /** Series identity — the `color`/`group` aesthetic value that disambiguates within the axis value. */
     groupValue: DataValue;
 }
 
@@ -4620,19 +5149,29 @@ declare interface PieOptions {
  * Pinned-number annotation: a marker dot pinned to a single observation. The
  * renderer's mini view shows the observation's measurement value; hover reveals
  * the full tooltip (x + y + trend).
+ *
+ * NO PAINTER in `@graphysdk/react-renderer` — this compiles but never draws there (it renders only in
+ * the editor's legacy engine). Don't reach for it when authoring for the React renderer.
  */
 declare interface PinnedNumberAnnotationInput {
     id?: string;
     anchor: ObservationAnchorInput;
 }
 
+/** Resolved form of {@link PinnedNumberAnnotationInput} — defaults applied, anchor normalised. */
 declare interface PinnedNumberAnnotationSpec {
     id: string;
     anchor: ObservationAnchor;
 }
 
 /**
- * Pipe a spec through a series of spec items (left-to-right).
+ * Fold a sequence of pipeable spec items onto an existing spec, left to right, returning a new spec.
+ * Each item is appended by kind: layers accumulate (call `geom.*` once per mark), scales accumulate,
+ * `config` deep-merges, `coord`/`mapping` overwrite/merge. The usual shape is
+ * `pipe(createSpec({...}), geom.x(), scale.x(), scale.y(), ...)`.
+ *
+ * @example
+ * pipe(createSpec({ x: 'month', y: 'sales', color: 'region' }), geom.line(), scale.x(), scale.y(), scale.color.palette());
  */
 export declare function pipe(spec: SpecInput, ...items: SpecItem[]): SpecInput;
 
@@ -4662,6 +5201,20 @@ export declare interface PlacedDataLabel {
     position: DataLabelPosition;
 }
 
+/**
+ * Point marks — scatter plots and bubble charts. Map `size` to a column for a bubble chart and `color` for
+ * categorical series. Sizing is controlled via {@link PointGeomParams} `size` or `scale.size.continuous`.
+ *
+ * @example
+ * pipe(
+ *   createSpec({ x: 'gdp', y: 'lifeExp', size: 'population', color: 'continent' }),
+ *   geom.point(),
+ *   scale.x(),
+ *   scale.y(),
+ *   scale.size.continuous({ range: [4, 40] }),
+ *   scale.color.palette(),
+ * );
+ */
 declare function point(options?: GeomOptions<'point'>): LayerInputOf<'point'>;
 
 /**
@@ -4680,9 +5233,14 @@ declare class PointGeom extends Geom {
 }
 
 /**
- * Point-specific parameters
+ * Render parameters for `geom.point`. Passed under `params`.
  */
 declare interface PointGeomParams {
+    /**
+     * Mark diameter in pixels, used when `size` is not a data channel. To size by data instead, map the `size`
+     * aesthetic and declare `scale.size.continuous({ range })`.
+     * @default 8
+     */
     size: number;
 }
 
@@ -4698,19 +5256,28 @@ declare interface PolarCoordInput {
 }
 
 /**
- * Params for polar coordinate system
+ * Resolved params for the polar coordinate system (defaults applied).
+ * Drives pie, donut, and radar/radial layouts by mapping one scaled aesthetic to the
+ * angle and the other to the radius.
  */
 declare interface PolarCoordParams extends BaseCoordParams {
     /**
-     * Which aesthetic maps to theta (angle): 'x' or 'y'
+     * Which aesthetic becomes the angle (theta); the other aesthetic becomes the radius,
+     * scaled into `[innerRadius, 1]`. Use `'y'` for pie/donut (stacked value → angle),
+     * `'x'` for radar (one spoke per category).
+     * @default 'x'
      */
     theta: 'x' | 'y';
     /**
-     * Starting angle in degrees
+     * Rotation offset of the whole layout, in degrees. Shifts where the first datum begins;
+     * the full sweep is 360°.
+     * @default 0
      */
     startAngle: number;
     /**
-     * Inner radius as fraction 0-1 (for donut charts)
+     * Hole radius as a fraction of the outer radius, `0`–`1`. `0` is a full pie;
+     * any value `> 0` produces a donut (e.g. `0.55`).
+     * @default 0
      */
     innerRadius: number;
 }
@@ -4880,6 +5447,10 @@ export declare type PositionType = 'stack' | 'dodge' | 'identity' | 'fill';
  */
 declare type PositionValueKind = 'value' | 'bandOffset';
 
+/**
+ * Selects which observations a highlight emphasises: either a single-column
+ * {@link VariablePredicate} or a {@link LogicalPredicate} combining several.
+ */
 export declare type Predicate = VariablePredicate | LogicalPredicate;
 
 export declare const prefixInternalVariable: (name: string) => string;
@@ -4902,6 +5473,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;
@@ -4916,19 +5492,28 @@ export declare interface RadiusExtent {
 export declare function readAesthetic(aesMapping: AesMapping, name: string): AestheticValue | undefined;
 
 /**
- * Reads an author-named numeric column from an observation with the same null-discipline as the
- * built-in position/visual readers (`getX`, `getColor`, …): a missing or wrong-typed value is
- * `null`, never silently coerced to `0`. A custom geom writes its own columns and has no typed
- * accessor for them; these readers fill that gap without re-deriving the coercion per geom.
+ * 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).
  *
- * 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.
+ * 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 an author-named string column from an observation; missing or wrong-typed is `null` unless a `fallback` is given. */
+/**
+ * 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;
@@ -4992,6 +5577,11 @@ declare function reshape(options?: ReshapeOptions): ReshapeTransformInput;
 /***************************************************************
  * Reshape Transform
  ***************************************************************/
+/**
+ * Options for `transform.reshape` — pivots a wide table to long ("tidy") form by collapsing
+ * several numeric columns into two: a key column (the original column name) and a value column.
+ * The idiom for turning a multi-metric table into a single series mappable by `color`.
+ */
 declare interface ReshapeOptions {
     /**
      * Numeric variables to collapse into rows.
@@ -5015,6 +5605,7 @@ declare interface ReshapeOptions {
     valueName?: VariableName;
 }
 
+/** Pivot-to-long transform produced by `transform.reshape`. */
 declare interface ReshapeTransformInput {
     type: 'transform';
     transformType: 'reshape';
@@ -5098,15 +5689,35 @@ export declare function resolveYScaleAesthetic(yScaleType: YScaleType): ScaledAe
  */
 export declare const RESTING_HOVER_STATE: HoverState;
 
-/** TipTap-compatible rich text node (no tiptap dependency). */
+/**
+ * A node in a ProseMirror/TipTap-style rich-text document tree (no tiptap
+ * dependency). NOT a plain string — it is a recursive node where `content`
+ * holds child nodes and a leaf text node carries `text`. Used both for chart
+ * titles/captions and for text annotation bodies.
+ *
+ * The root is a `{ type: 'doc' }` node; block children are `'paragraph'` or
+ * `'heading'` (with `attrs.level`); inline runs are `'text'` nodes whose
+ * `marks` apply styling (e.g. `{ type: 'bold' }`, `{ type: 'italic' }`,
+ * `{ type: 'link', attrs: { href } }`). Plain prose is one paragraph of one
+ * text node:
+ *
+ * ```ts
+ * { type: 'doc', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Quarterly sales' }] }] }
+ * ```
+ */
 export declare interface RichTextContent {
+    /** Node kind: `'doc'` (root), `'paragraph'`, `'heading'`, `'text'`, etc. */
     type?: string;
+    /** Child nodes. Present on container nodes; absent on `'text'` leaves. */
     content?: RichTextContent[];
+    /** The literal string carried by a `'text'` leaf node. */
     text?: string;
+    /** Inline formatting applied to a `'text'` node (bold, italic, link, …). */
     marks?: Array<{
         type: string;
         attrs?: Record<string, unknown>;
     }>;
+    /** Node attributes, e.g. `{ level: 2 }` on a heading or `{ href }` on a link mark target. */
     attrs?: Record<string, unknown>;
 }
 
@@ -5121,6 +5732,18 @@ declare interface RolePositionChannel extends PositionChannelBase {
     name?: string;
 }
 
+/**
+ * Rule marks — a single horizontal or vertical reference line, the built-in for goal/threshold/average
+ * lines (no custom geom needed). Pin a constant with `aes: { y: { value } }` (horizontal) or
+ * `aes: { x: { value } }` (vertical, numeric x), or compute a data-driven line with `stat.mean()`. Style and
+ * label it via {@link RuleGeomParams}; set `interactive: false` so it doesn't take hover.
+ *
+ * @example
+ * // Constant goal line at y = 2500
+ * geom.rule({ aes: { y: { value: 2500 } }, params: { label: 'Target', lineType: 'dashed', labelPosition: 'start' } });
+ * // Data-driven average line
+ * geom.rule({ aes: { y: 'revenue' }, stat: stat.mean(), params: { label: 'Average' }, interactive: false });
+ */
 declare function rule(options?: GeomOptions<'rule'>): LayerInputOf<'rule'>;
 
 /**
@@ -5143,20 +5766,34 @@ declare class RuleGeom extends Geom {
 }
 
 /**
- * Rule-specific parameters.
+ * Render parameters for `geom.rule`. Passed under `params`. The line's value comes from `aes`
+ * (`{ y: { value } }` or `stat.mean()`), not from here — these are styling and labelling only.
  */
 export declare interface RuleGeomParams {
-    /** Stroke color; falls back to a theme token. */
+    /** Stroke color (any CSS color). Falls back to a theme token when omitted. */
     color?: string;
+    /**
+     * Stroke width in pixels.
+     * @default 1
+     */
     strokeWidth: number;
+    /**
+     * Dash style of the line.
+     * @default 'dashed'
+     */
     lineType: LineStyleType;
-    /** Optional inline text label rendered alongside the line. */
+    /** Optional inline text label rendered alongside the line (e.g. `'Target'`, `'Average'`). */
     label?: string;
+    /**
+     * Which end of the line the `label` is anchored to.
+     * @default 'start'
+     */
     labelPosition: RuleLabelPosition;
 }
 
 /**
- * Where the optional inline label is anchored along a reference line.
+ * Where the optional inline label sits along a reference line: `'start'` (left/top end) or `'end'`
+ * (right/bottom end).
  */
 export declare type RuleLabelPosition = 'start' | 'end';
 
@@ -5188,6 +5825,31 @@ declare abstract class Scale {
     abstract compile(spec: ScaleSpec, values: DataValue[]): CompiledScale;
 }
 
+/**
+ * Scale builder — declares how each mapped variable is turned into a visual value
+ * (axis position, color, size, …). Pipe the result onto a spec.
+ *
+ * Position scales must be declared EXPLICITLY: the builder never auto-infers `x`/`y`,
+ * so omitting `scale.x()` / `scale.y()` yields NaN positions. `scale.x`/`.y`/`.ySecondary`
+ * are callable for an inferred scale (type auto-detected from the data) or expose explicit
+ * sub-methods: `.continuous` / `.discrete` / `.datetime` / `.log` / `.sqrt`. Use
+ * `scale.x.discrete()` for categorical or temporal-string axes.
+ *
+ * Non-position aesthetics auto-infer from the mapping, so their scale entry is optional —
+ * add one only to override the default (e.g. `scale.color.palette()`, `scale.size.continuous({ range })`).
+ *
+ * @example
+ *   import { pipe, createSpec, geom, scale } from '@graphysdk/viz-engine';
+ *
+ *   pipe(
+ *     createSpec({ x: 'gdp', y: 'lifeExp', size: 'population', color: 'continent' }),
+ *     geom.point(),
+ *     scale.x.log({ domainMin: 1 }),
+ *     scale.y.continuous({ zero: false, nice: true }),
+ *     scale.size.continuous({ range: [4, 40] }),
+ *     scale.color.palette()
+ *   );
+ */
 export declare const scale: ScaleAPI;
 
 declare interface ScaleAPI {
@@ -5297,7 +5959,10 @@ declare type ScaledPositionAestheticKey = 'x' | 'y' | 'ySecondary';
 export declare type ScaledVisualAestheticKey = 'color' | 'size' | 'alpha' | 'strokeWidth' | 'lineType';
 
 /**
- * Union type for all possible scale specifications (including inferred, pre-resolution).
+ * Any value the `scale` builder produces, before resolution. Each pipe item carries the
+ * target aesthetic plus its scale type and options; an `inferred` entry has its concrete
+ * type chosen from the data during compilation. This is the type accepted by the spec
+ * pipeline — author scales with the `scale` builder rather than constructing it by hand.
  */
 declare type ScaleInput = ContinuousScaleInput | DiscreteScaleInput | PaletteScaleInput | DatetimeScaleInput | IdentityScaleInput | InferredScaleInput;
 
@@ -5306,8 +5971,9 @@ declare class ScaleRegistry extends Registry<ScaleType, Scale> {
 }
 
 /**
- * Union of scale specs that can appear after resolution (all fields required).
- * InferredScaleInput is resolved to a concrete type during spec resolution.
+ * A fully resolved scale (every option defaulted) as it appears on the compiled spec.
+ * The `inferred` variant has already been collapsed to one of these concrete types
+ * during resolution, so this union has no `inferred` member.
  */
 declare type ScaleSpec = ContinuousScaleSpec | DiscreteScaleSpec | DatetimeScaleSpec | IdentityScaleSpec | PaletteScaleSpec;
 
@@ -5521,27 +6187,37 @@ declare type SetScaleDomainParams = {
 };
 
 /**
- * Freeform rectangle annotation. Position and size are expressed as
- * fractions of the plot rect (0..1) so the annotation re-flows when the
- * panel resizes.
+ * A shaded box layered onto the panel. Position and size are panel fractions (`[0,1]`, top-left
+ * origin) — NOT data values — so the shape re-flows on resize but does not snap to a data point. Use a
+ * difference arrow or a custom annotation when you need data anchoring.
  */
 export declare interface ShapeInput {
     id?: string;
+    /** @default 'rectangle' */
     kind?: ShapeKind;
+    /** @default 'foreground' */
     zOrder?: ShapeZOrder;
+    /** Left edge as a `[0,1]` fraction of panel width (0 = left). */
     x: number;
+    /** Top edge as a `[0,1]` fraction of panel height (0 = top). */
     y: number;
+    /** Width as a `[0,1]` fraction of panel width. */
     width: number;
+    /** Height as a `[0,1]` fraction of panel height. */
     height: number;
+    /** @default 'transparent' */
     fillColor?: string;
+    /** Fill alpha, `[0,1]`. @default 1 */
     fillOpacity?: number;
+    /** Stroke width in pixels. @default 1 */
     strokeWidth?: number;
-    /** null falls back to the theme `defaultAnnotationShapeStroke`. */
+    /** `null` falls back to the theme `defaultAnnotationShapeStroke`. @default null */
     strokeColor?: string | null;
 }
 
 export declare type ShapeKind = 'rectangle';
 
+/** Resolved form of {@link ShapeInput} — defaults applied. */
 export declare interface ShapeSpec {
     id: string;
     kind: ShapeKind;
@@ -5562,7 +6238,9 @@ export declare interface ShapeSpec {
 export declare type ShapeZOrder = 'background' | 'foreground';
 
 /**
- * Builder for the smooth stat.
+ * Builder for the smooth stat — fits a regression trendline through the observations.
+ * Pair with `geom.line` for a drawn trendline. `order` applies only to `'polynomial'`,
+ * `bandwidth` only to `'loess'`; both are ignored by the other methods.
  *
  * @example
  *   geom.line({ stat: stat.smooth({ method: 'linear' }) })
@@ -5576,7 +6254,14 @@ declare function smooth(options: {
 }): SmoothStatInput;
 
 /**
- * Regression methods supported by the `smooth` stat.
+ * Regression/trendline method fitted by the `smooth` stat through the observations:
+ * - `'linear'` — straight line of best fit (`y = a + b·x`). The default.
+ * - `'loess'` — locally weighted smoothing; follows local structure. Tune with `bandwidth`.
+ * - `'exponential'` — `y = a·e^(b·x)`; constant-rate growth/decay.
+ * - `'logarithmic'` — `y = a + b·ln(x)`; fast early then flattening.
+ * - `'quadratic'` — parabola (`y = a + b·x + c·x²`); a single bend.
+ * - `'power'` — `y = a·x^b`; scale-free relationships.
+ * - `'polynomial'` — degree-`order` polynomial; multiple bends. Tune with `order`.
  */
 export declare type SmoothMethod = 'linear' | 'loess' | 'exponential' | 'logarithmic' | 'quadratic' | 'power' | 'polynomial';
 
@@ -5586,7 +6271,9 @@ export declare type SmoothMethod = 'linear' | 'loess' | 'exponential' | 'logarit
 declare interface SmoothStatInput {
     type: 'smooth';
     method: SmoothMethod;
+    /** Polynomial degree. Only used when `method: 'polynomial'`. @default 3 */
     order?: number;
+    /** LOESS smoothing window as a fraction (0–1) of the data. Only used when `method: 'loess'`. @default 0.3 */
     bandwidth?: number;
 }
 
@@ -5612,6 +6299,10 @@ export declare const sortByXIfContinuous: (data: Dataset, mapping: AesMapping) =
 /***************************************************************
  * 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;
@@ -5619,15 +6310,18 @@ declare interface SortOptions {
     direction?: 'asc' | 'desc';
 }
 
+/** Observation-ordering transform produced by `transform.sort`. */
 declare interface SortTransformInput {
     type: 'transform';
     transformType: 'sort';
     options: SortOptions;
 }
 
-/** Data-source attribution shown under the caption. */
+/** Data-source attribution shown under the caption: a `label` and optional `url`. */
 export declare interface SourceContent {
+    /** Displayed attribution text, e.g. `'Internal pipeline'`. */
     label?: string;
+    /** Optional link the label points to. */
     url?: string;
 }
 
@@ -5701,17 +6395,30 @@ export declare interface Spec {
 }
 
 /**
- * The canonical spec type — plain JSON, serializable. Data is provided separately
- * (as a `Data` value to {@link compile}, or as a prop to `<GraphProvider>`).
+ * The canonical spec type — plain JSON, serializable. Built by `createSpec`/`pipe`; data is provided
+ * separately (as a `Data` value to {@link compile}, or as a prop to `<GraphProvider>`). Hand-construct it
+ * only when you cannot use the builders; otherwise prefer `pipe(createSpec({...}), geom.x(), scale.x(), ...)`.
  */
 export declare interface SpecInput {
+    /** Global aesthetic mapping (data columns → channels); layer `aes` overrides merge over this. */
     mapping: AesMapping;
+    /** Geometry layers to render, in draw order. One entry per `geom.*` call. */
     layers: LayerInput[];
+    /**
+     * Scale declarations, one per aesthetic. Position scales (`scale.x`/`scale.y`/`scale.ySecondary`) are NOT
+     * auto-inferred — declare them explicitly or position channels resolve to NaN. Visual scales
+     * (`color`/`size`/...) are inferred from the data when omitted.
+     */
     scales: ScaleInput[];
+    /** Spec-level data transforms applied before any layer is compiled (reshape, filter, ...). */
     transforms: TransformInput[];
+    /** Predicate-driven emphasis rules that dim or accentuate matching observations. */
     highlights: HighlightInput[];
+    /** Annotation overlays — difference arrows, shapes, text, freeform arrows. Optional. */
     annotations?: AnnotationsInput;
+    /** Coordinate system: cartesian (default), `coord.flip()`, or `coord.polar(...)`. Optional. */
     coords?: CoordInput;
+    /** Chart configuration: titles/captions, legend, axes, number format, headline, appearance. */
     config: ConfigInput;
 }
 
@@ -5781,6 +6488,23 @@ declare abstract class Stat {
     protected abstract computeStat(input: StatCompilerInput): CompiledStat;
 }
 
+/**
+ * Statistical-transform builder — sets a geom's `stat`, replacing each layer's raw observations
+ * with a derived summary before positions are computed. Defaults to `identity` (raw data).
+ *
+ * - `identity()` — pass observations through unchanged (the default).
+ * - `count()` — number of observations per x value, written to `y`; do NOT also map `y`.
+ * - `mean()` — reduce the mapped `y` to its average (a single value); the idiom for an
+ *   average line (`geom.rule({ stat: stat.mean() })`).
+ * - `smooth({ method })` — fit a regression trendline; the idiom for a trendline
+ *   (`geom.line({ stat: stat.smooth({ method: 'linear' }) })`).
+ *
+ * @example
+ *   import { geom, stat } from '@graphysdk/viz-engine';
+ *
+ *   geom.rule({ aes: { y: 'revenue' }, stat: stat.mean(), params: { label: 'Average' } });
+ *   geom.line({ stat: stat.smooth({ method: 'linear' }), interactive: false });
+ */
 export declare const stat: {
     identity: typeof identity;
     count: typeof count;
@@ -5816,7 +6540,9 @@ declare interface StatCompilerInput {
 }
 
 /**
- * User-facing stat input — either a {@link StatName} string shorthand or an object spec.
+ * 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.
  */
 declare type StatInput = IdentityStatSpec | CountStatSpec | SmoothStatInput | MeanStatSpec;
 
@@ -5844,6 +6570,9 @@ declare type StatSpec = IdentityStatSpec | CountStatSpec | SmoothStatSpec | Mean
 
 /**
  * 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;
@@ -5851,6 +6580,7 @@ declare interface StickerAnnotationInput {
     sticker: StickerId;
 }
 
+/** Resolved form of {@link StickerAnnotationInput} — defaults applied, anchor normalised. */
 declare interface StickerAnnotationSpec {
     id: string;
     anchor: ObservationAnchor;
@@ -5901,26 +6631,33 @@ declare interface TemporalValueFormat {
     dateFormat?: string;
 }
 
+/** How `backgroundColor` is applied: `'fade'` (soft gradient) or `'opaque'` (flat fill). */
 export declare type TextAnnotationBackgroundColorStyle = 'fade' | 'opaque';
 
 /**
- * Freeform rich-text annotation. Position and width are fractions of the plot
- * rect (0..1). Height is intrinsic to the rendered content.
+ * A free-standing text label on the panel. Positioned in panel fractions (`[0,1]`, top-left origin) —
+ * NOT data values — so it re-flows on resize but does not snap to a data point. There is no `height`
+ * field: height is intrinsic to the rendered content. `content` is a structured {@link RichTextContent}
+ * node tree (ProseMirror/TipTap-style), NOT a plain string — wrap a string as
+ * `{ type: 'doc', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Label' }] }] }`.
  */
 export declare interface TextAnnotationInput {
     id?: string;
+    /** Rich-text node tree to render (not a plain string). */
     content: RichTextContent;
-    /** 0..1 of plot width — top-left corner. */
+    /** Left edge as a `[0,1]` fraction of panel width (0 = left, top-left corner). */
     x: number;
-    /** 0..1 of plot height — top-left corner. */
+    /** Top edge as a `[0,1]` fraction of panel height (0 = top, top-left corner). */
     y: number;
-    /** 0..1 of plot width. */
+    /** Box width as a `[0,1]` fraction of panel width; text wraps within it (height is intrinsic). */
     width: number;
-    /** null falls back to a transparent background. */
+    /** `null` falls back to a transparent background. @default null */
     backgroundColor?: string | null;
+    /** @default 'opaque' */
     backgroundColorStyle?: TextAnnotationBackgroundColorStyle;
 }
 
+/** Resolved form of {@link TextAnnotationInput} — defaults applied. */
 export declare interface TextAnnotationSpec {
     id: string;
     content: RichTextContent;
@@ -5931,7 +6668,11 @@ export declare interface TextAnnotationSpec {
     backgroundColorStyle: TextAnnotationBackgroundColorStyle;
 }
 
-/** A text value — plain string or structured rich text. */
+/**
+ * A text value for a title, subtitle, or caption: either a plain `string`
+ * (rendered as-is) or a structured {@link RichTextContent} document tree for
+ * multi-style / multi-line text.
+ */
 export declare type TextContent = string | RichTextContent;
 
 export declare interface TextMeasurer {
@@ -5975,6 +6716,29 @@ export declare interface TooltipRow {
     key: string;
 }
 
+/**
+ * Data-transform builder — reshapes the dataset BEFORE any geom maps over it. Pipe one or more
+ * onto a spec; they apply in order, ahead of stats and scaling, and affect every layer.
+ *
+ * - `reshape(opts?)` — pivot wide numeric columns to long form (key/value); the move for plotting
+ *   several metrics as one color-split series.
+ * - `filter(opts)` — keep observations matching `variableName <operator> value`.
+ * - `sort(opts)` — order observations by a variable (`'asc'` | `'desc'`).
+ * - `aggregate(opts)` — group by variables and reduce each group (sum/mean/count/…).
+ * - `constant(opts)` — add a column with a fixed value on every observation.
+ *
+ * @example
+ *   import { pipe, createSpec, geom, scale, transform } from '@graphysdk/viz-engine';
+ *
+ *   pipe(
+ *     createSpec({ x: 'region', y: 'total', color: 'region' }),
+ *     transform.filter({ variableName: 'year', operator: 'eq', value: 2024 }),
+ *     transform.aggregate({ groupby: ['region'], operations: [{ op: 'sum', variableName: 'revenue', as: 'total' }] }),
+ *     geom.bar(),
+ *     scale.x(),
+ *     scale.y()
+ *   );
+ */
 export declare const transform: {
     reshape: typeof reshape;
     filter: typeof filter;
@@ -6003,6 +6767,10 @@ declare interface TransformCompilerInput {
 /***************************************************************
  * Transform Input
  ***************************************************************/
+/**
+ * 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.
+ */
 declare type TransformInput = ReshapeTransformInput | FilterTransformInput | SortTransformInput | AggregateTransformInput | ConstantTransformInput;
 
 /**
@@ -6020,6 +6788,7 @@ declare interface TransformStrategy {
     apply: (data: Dataset, transform: TransformInput) => Dataset;
 }
 
+/** Discriminant tag of a {@link TransformInput}. */
 declare type TransformType = TransformInput['transformType'];
 
 declare type TrendlineType = 'linear' | 'loess' | 'exponential' | 'logarithmic' | 'quadratic' | 'power' | 'polynomial';
@@ -6066,10 +6835,12 @@ export declare interface ValueFormatterFactoryParams<T = ValueFormat> {
 }
 
 /**
- * Constant mapping - a literal value applied to every observation.
- * Analogous to Vega-Lite's `{datum: X}` / ggplot2's `aes(color = "literal")`.
+ * Pins a channel to a single literal value applied to every observation, instead of reading a column.
+ * Use it for reference-line constants (`geom.rule({ aes: { y: { value: 2500 } } })`) or to force a fixed
+ * style (`aes: { lineType: { value: 'dashed' } }`). Analogous to Vega-Lite's `{datum: X}`.
  */
 declare interface ValueMapping {
+    /** The constant — a number, string, Date, or null — shared by all observations. */
     value: DataValue;
 }
 
@@ -6092,9 +6863,11 @@ export declare function variableFor(axis: ChannelAxis, name: string): string;
 declare type VariableMap = Record<VariableName, Variable>;
 
 /**
- * Variable mapping - references a column in the data
+ * Binds a channel to a data column by name. `{ variable: 'revenue' }` reads the `revenue` column
+ * per observation. Equivalent to the bare-string shorthand `'revenue'` in an {@link AesMapping}.
  */
 declare interface VariableMapping {
+    /** Column key in the data, matching a `columns[i].key`. */
     variable: string;
 }
 
@@ -6103,15 +6876,20 @@ declare type VariableMetadata = Record<VariableName, {
     valueFormat: ValueFormat;
 }>;
 
-/** A type alias for variable names. */
+/** A variable (column) name. Names with the internal prefix address compiler-emitted columns; address those through the value readers (`getX`, …) or `variableFor`, never by literal. */
 export declare type VariableName = string;
 
 /**
- * Field-based predicates against post-transform user columns.
+ * A value test against one post-transform user column. The selected operator
+ * decides which observations a highlight emphasises:
+ * - `eq`: column equals the value.
+ * - `oneOf`: column is one of the listed values.
+ * - `lt` / `lte` / `gt` / `gte`: ordering comparison (numeric / datetime only).
+ * - `range`: inclusive `[min, max]` interval.
  *
- * `lt`, `lte`, `gt`, `gte`, and `range` accept `DataValue`s and are coerced at
- * evaluation time by the referenced column's `DataType`. Ordering operators
- * against a categorical field are a resolve-time validation error.
+ * Comparison values are `DataValue`s coerced at evaluation time by the
+ * referenced column's `DataType`. Ordering operators against a categorical
+ * field are a resolve-time validation error.
  */
 export declare type VariablePredicate = {
     variable: VariableName;