@graphysdk/viz-engine 0.0.1-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,3415 @@
+import { internal } from 'arquero';
+
+export declare interface AesMapping {
+    x?: AestheticValue;
+    y?: AestheticValue;
+    label?: AestheticValue;
+    color?: AestheticValue;
+    size?: AestheticValue;
+    alpha?: AestheticValue;
+    group?: AestheticValue;
+    strokeWidth?: AestheticValue;
+}
+
+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)
+ */
+declare type AestheticValue = string | VariableMapping | ValueMapping;
+
+declare function aggregate(options: AggregateOptions): AggregateTransformInput;
+
+/***************************************************************
+ * Aggregate Transform
+ ***************************************************************/
+declare interface AggregateOperation {
+    /** The aggregation function to apply. */
+    op: AggregationFunction;
+    /** The variable to aggregate. */
+    variableName: VariableName;
+    /** The name of the output variable. */
+    as: VariableName;
+}
+
+declare interface AggregateOptions {
+    /** Variables to group by before aggregating. */
+    groupby: VariableName[];
+    /** Aggregation operations to apply per group. */
+    operations: AggregateOperation[];
+}
+
+declare interface AggregateTransformInput {
+    type: 'transform';
+    transformType: 'aggregate';
+    options: AggregateOptions;
+}
+
+/** A function that aggregates a variable's values. */
+declare type AggregationFunction = 'count' | 'sum' | 'mean' | 'median' | 'mode' | 'min' | 'max';
+
+/** A record of variable names and their aggregations. */
+declare type AggregationInput = Record<VariableName, {
+    variableName: VariableName;
+    aggregation: AggregationFunction;
+}>;
+
+export declare interface AngleExtent {
+    startAngle: NumericDataValue;
+    endAngle: NumericDataValue;
+}
+
+declare interface AnnotationDataPoint {
+    rowIndex?: number;
+    columnKey?: string;
+    rowValue?: DataValue;
+}
+
+declare interface Appearance {
+    paletteId?: string;
+    seriesStyles?: Record<string, SeriesStyle>;
+    useSingleColorForBars?: boolean;
+    background?: string;
+    backgroundModifier?: 'none' | 'tint';
+    border?: Partial<{
+        style: 'none' | 'custom' | 'tinted' | 'gradient' | 'preset' | 'grey';
+        color: string;
+        width: number;
+    }>;
+    hasRoundedCorners?: boolean;
+    textStyle?: Partial<{
+        heading: GraphTextStyle;
+        body: GraphTextStyle;
+    }>;
+    textScale?: number;
+    highlightStyle?: 'grey' | 'fade-color';
+    isLogoHidden?: boolean;
+    numberFormat?: Partial<{
+        decimalPlaces: 'auto' | number;
+        abbreviation: 'none' | 'auto' | 'k' | 'm' | 'b';
+    }>;
+    showTooltips?: boolean;
+    animateTransitions?: boolean;
+}
+
+/**
+ * Appearance configuration (after defaults applied)
+ */
+declare interface AppearanceConfig {
+    /**
+     * Background color for the chart canvas.
+     * null means inherit from the renderer/theme default.
+     * @default null
+     */
+    background: string | null;
+}
+
+declare function area(options?: GeomOptions<'area'>): LayerInputOf<'area'>;
+
+/**
+ * Area-specific parameters (same rendering knobs as line, but fills under the curve)
+ */
+export declare interface AreaGeomParams {
+    lineWidth: number | 'auto';
+    lineType: LineStyleType;
+    interpolate: InterpolateType;
+    missingValues: MissingValuesType;
+}
+
+declare interface AverageLine {
+    columnKey: string;
+}
+
+/** Configuration for the axes (if the graph supports them). */
+declare interface Axes {
+    x?: AxisOptions;
+    y?: AxisOptions;
+    y2?: Pick<AxisOptions, 'label'>;
+    hasDualYAxis?: boolean;
+    showGridLines?: boolean;
+}
+
+/**
+ * Axes configuration (after defaults applied)
+ * Groups all axis-related settings per axis.
+ */
+declare interface AxesConfig {
+    x: XAxisConfig;
+    y: YAxisConfig;
+    ySecondary?: YAxisConfig;
+}
+
+/**
+ * Configuration for a single axis's grid lines
+ */
+declare interface AxisGridConfig {
+    /**
+     * Whether grid lines are visible.
+     * - true/false: explicit visibility
+     * - null: let the compiler decide based on geom/coord policies
+     *   (defaults to false for x-axis, true for y-axis)
+     */
+    isVisible: boolean | null;
+}
+
+/**
+ * Label display mode for axis ticks
+ * - 'auto': Show all ticks (default behavior)
+ * - 'edges': Show only the first and last tick
+ */
+declare type AxisLabelMode = 'auto' | 'edges';
+
+/**
+ * Maps each positional aesthetic to its axis orientation.
+ * The guide compiler uses this to determine where axes are placed
+ * and what geometry they use (e.g., linear vs circular grid lines).
+ */
+declare interface AxisMapping {
+    x: {
+        position: AxisPosition;
+        geometry: GuideGeometry;
+    };
+    y: {
+        position: AxisPosition;
+        geometry: GuideGeometry;
+    };
+}
+
+declare interface AxisOptions {
+    label?: string;
+    isHidden?: boolean;
+    isReversed?: boolean;
+    scaleType?: 'linear' | 'logarithmic';
+    min?: number;
+    max?: number;
+    tickDisplayMode?: 'auto' | 'edges';
+}
+
+declare type AxisPosition = 'left' | 'right' | 'top' | 'bottom';
+
+/**
+ * A single axis tick with its raw value and normalized position. Ticks in one axis share the same
+ * `valueFormat` — it lives on `CompiledAxisGuide`, not per-tick.
+ */
+export declare interface AxisTick {
+    /** Raw value in data space (number, Date, or string) */
+    value: DataValue;
+    /** Normalized position in [0,1] space — used for placement */
+    position: number;
+}
+
+/**
+ * A tick-set candidate for an axis. The runtime picks the densest one whose labels fit. Datetime candidates
+ * may carry a `valueFormat` matched to their interval's granularity, overriding the axis-level format.
+ */
+export declare interface AxisTickCandidate {
+    ticks: AxisTick[];
+    valueFormat?: ValueFormat;
+}
+
+/**
+ * Configuration for a single axis's ticks
+ */
+declare interface AxisTicksConfig {
+    isVisible: boolean;
+    mode: AxisLabelMode;
+}
+
+declare function bar(options?: GeomOptions<'bar'>): LayerInputOf<'bar'>;
+
+/**
+ * Bar/Column-specific parameters
+ */
+declare type BarGeomParams = Record<string, never>;
+
+declare interface BarOptions {
+    sortBars?: boolean;
+}
+
+/**
+ * Base params shared by all coordinate systems
+ */
+declare interface BaseCoordParams {
+    /**
+     * Limits for x-axis [min, max]
+     */
+    xLimits: [number, number] | null;
+    /**
+     * Limits for y-axis [min, max]
+     */
+    yLimits: [number, number] | null;
+}
+
+declare interface BaseGeomOptions<T extends GeomParams> {
+    aes?: AesMapping;
+    stat?: StatName;
+    position?: PositionType;
+    yScaleType?: YScaleType;
+    params?: Partial<T>;
+    transforms?: TransformInput[];
+    interactive?: boolean;
+}
+
+export declare type BoxSize = {
+    width: number;
+    height: number;
+};
+
+/**
+ * Pure projection of `(compiled, hover)` into the tooltip's `{ header, rows }`.
+ *
+ * Row order is layer-declaration order across layers, color-scale domain order within a layer
+ * (= the legend's display order). The primary hit is emphasized in place — never reordered to
+ * the top — so the visual position stays anchored to the legend.
+ */
+export declare const buildTooltipContent: ({ compiled, hover, formattingLocale, }: BuildTooltipContentInput) => TooltipContent | null;
+
+declare interface BuildTooltipContentInput {
+    compiled: CompiledSpec;
+    hover: HoverState;
+    formattingLocale?: Locale;
+}
+
+/**
+ * Caching decorator for any TextMeasurer implementation.
+ *
+ * Cache key includes all dimensions that affect `measureText()` output:
+ * family, size, weight, style, and the text itself.
+ *
+ * No eviction policy is needed because chart text is bounded —
+ * a chart has at most tens to low hundreds of unique labels.
+ */
+export declare class CachedTextMeasurer implements TextMeasurer {
+    private readonly inner;
+    private readonly cache;
+    constructor(inner: TextMeasurer);
+    measureText(text: string, font: FontSpec): MeasuredText;
+    private getCacheKey;
+}
+
+declare interface CartesianCoordInput {
+    type: 'coord';
+    coordType: 'cartesian';
+    params?: Partial<BaseCoordParams>;
+}
+
+declare type CartesianCoordParams = BaseCoordParams;
+
+declare interface CartesianCoordSpec {
+    type: 'coord';
+    coordType: 'cartesian';
+    params: BaseCoordParams;
+}
+
+/**
+ * Cartesian coordinate system - standard x/y plot. Also used for flipped coordinates (flip is
+ * an axis-assignment variant, not a different geometric paradigm).
+ */
+export declare interface CartesianCoordSystem {
+    type: 'cartesian';
+    /**
+     * The data-space axis that is the main (independent) one. `'x'` for standard cartesian (bars
+     * rise, X ticks on the horizontal axis); `'y'` for `coord.flip()` (bars extend, Y ticks on the
+     * horizontal axis). Consumers that need to branch on flip read this; the runtime `coord/axes`
+     * helpers turn it into main/cross accessors so the branch lives in one place.
+     */
+    mainAxis: MainAxis;
+    /** Axis orientation metadata for the guide compiler */
+    axisMapping: AxisMapping;
+}
+
+declare type CategoricalDataValue = string | null;
+
+declare interface CategoricalValueFormat {
+    type: 'text';
+}
+
+/**
+ * Chart display and interaction mode.
+ * - 'readonly': Normal chart display with full interactivity but no editing (default)
+ * - 'editable': Chart with inline editing capabilities for labels, titles, etc.
+ */
+declare type ChartMode = 'readonly' | 'editable';
+
+declare interface ColorScaleMethods {
+    /**
+     * Continuous (numeric) color scale. Supports `transform`, `reverse`, `nice`, `zero`, `domainMin`, `domainMax`.
+     * @example scale.color.continuous({ reverse: true })
+     */
+    continuous: (options?: ContinuousScaleOptions) => ContinuousScaleInput;
+    /**
+     * Discrete (categorical) color scale. Supports explicit `range` values.
+     * @example scale.color.discrete({ range: ['red', 'blue', 'green'] })
+     */
+    discrete: (options?: DiscreteScaleOptions) => DiscreteScaleInput;
+    /**
+     * Color scale from a named Graphy palette.
+     * @example scale.color.palette({ palette: 'Bright' })
+     */
+    palette: (options?: PaletteScaleOptions) => PaletteScaleInput;
+}
+
+declare type ColumnMetadata = Record<string, {
+    type: DataType;
+    valueFormat: ValueFormat;
+    label?: string;
+}>;
+
+declare interface ComboOptions {
+    comboType?: 'grouped-bars' | 'stacked-bars' | 'lines';
+}
+
+export declare interface Command<TParams extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Command type discriminator for type guards
+     */
+    readonly type: string;
+    /**
+     * Metadata for tracking
+     */
+    readonly metadata: CommandMetadata;
+    /**
+     * Serializable parameters for this command.
+     */
+    readonly params: TParams;
+    /**
+     * Execute the command against a spec.
+     * Returns the new spec and a revert command that can undo this change.
+     */
+    apply: (spec: Spec) => CommandApplyResult | null;
+}
+
+/**
+ * Result of executing a command.
+ * Contains the new spec and a revert command that can undo the change.
+ */
+export declare interface CommandApplyResult {
+    /** The spec after applying the command */
+    readonly spec: Spec;
+    /** A standalone command that reverses this execution */
+    readonly revert: Command;
+}
+
+/**
+ * Unique identifier for commands.
+ */
+declare type CommandId = string;
+
+/**
+ * Metadata attached to every command for tracking.
+ */
+export declare interface CommandMetadata {
+    /** Unique identifier for this command */
+    readonly id: CommandId;
+    /** When the command was executed */
+    readonly timestamp: number;
+    /** Human-readable description for UI display */
+    readonly description: string;
+    /** Author of the command */
+    readonly author: string;
+}
+
+/**
+ * Event types emitted by CommandStackManager.
+ */
+export declare type CommandStackEvent = {
+    type: 'apply';
+    command: Command;
+    spec: Spec;
+} | {
+    type: 'undo';
+    command: Command;
+    spec: Spec;
+} | {
+    type: 'redo';
+    command: Command;
+    spec: Spec;
+} | {
+    type: 'clear';
+};
+
+/**
+ * Listener for command stack events.
+ */
+export declare type CommandStackListener = (event: CommandStackEvent) => void;
+
+/**
+ * Manages command execution with undo/redo support using revert commands.
+ *
+ * Commands are stateless — executing a command returns the new spec and a
+ * standalone revert command. The manager stores these revert commands on
+ * the undo stack. Undo executes the revert (producing a new forward command
+ * for redo), and redo executes that forward command (producing a new revert
+ * for undo again).
+ *
+ * @example
+ * ```typescript
+ * const manager = new CommandStackManager();
+ *
+ * // Execute a command
+ * let spec = manager.apply(command, spec);
+ *
+ * // Undo the last command
+ * const undoResult = manager.undo(spec);
+ * if (undoResult) {
+ *   spec = undoResult.spec;
+ * }
+ *
+ * // Redo the undone command
+ * const redoResult = manager.redo(spec);
+ * if (redoResult) {
+ *   spec = redoResult.spec;
+ * }
+ * ```
+ */
+export declare class CommandStackManager {
+    private undoStack;
+    private redoStack;
+    private listeners;
+    private readonly maxHistorySize;
+    private isEmitting;
+    private cachedSnapshot;
+    constructor(options?: CommandStackOptions);
+    /**
+     * Execute a command and add it to the undo stack.
+     * Clears the redo stack (standard undo/redo behavior).
+     */
+    apply(command: Command, spec: Spec): Spec;
+    /**
+     * Undo the most recent command.
+     * Executes the revert command and moves the entry to the redo stack.
+     * Returns the result with new spec and the original command, or null if nothing to undo.
+     */
+    undo(spec: Spec): UndoRedoResult | null;
+    /**
+     * Redo the most recently undone command.
+     * Executes the redo action and moves the entry back to the undo stack.
+     * Returns the result with new spec and the original command, or null if nothing to redo.
+     */
+    redo(spec: Spec): UndoRedoResult | null;
+    /**
+     * Clear all history (both undo and redo stacks).
+     */
+    clear(): void;
+    /**
+     * Get an immutable snapshot of the command stack state.
+     * Returns a cached object with referential stability.
+     */
+    getSnapshot(): CommandStackSnapshot;
+    /**
+     * Subscribe to command stack events.
+     * @returns Unsubscribe function
+     */
+    subscribe(listener: CommandStackListener): () => void;
+    private withReentrancyGuard;
+    private emit;
+}
+
+/**
+ * Options for CommandStackManager.
+ */
+declare interface CommandStackOptions {
+    /** Maximum number of commands to keep in history (default: 100) */
+    maxHistorySize?: number;
+}
+
+/**
+ * Immutable snapshot of command stack state.
+ * Designed for use with React's `useSyncExternalStore(manager.subscribe, manager.getSnapshot)`.
+ */
+export declare interface CommandStackSnapshot {
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    readonly undoDescription: string | null;
+    readonly redoDescription: string | null;
+}
+
+/** Comparison operators for declarative filtering. */
+declare type ComparisonOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte';
+
+/**
+ * Convenience entry point to create a fully wired {@link Compiler} and compile a spec.
+ *
+ * Accepts either a low-level {@link SpecInput} (constructed via `createSpec`/`pipe`)
+ * or a high-level {@link GraphConfig}. When given a `GraphConfig`, it parses the raw
+ * data and converts it to a `SpecInput` before running the pipeline.
+ */
+export declare const compile: (input: CompilerInput) => CompiledSpec;
+
+/**
+ * Axis guide produced from a position scale (x, y, ySecondary).
+ * Tick candidates carry normalized positions so the renderer needs no scale logic (selection
+ * happens at layout time).
+ */
+export declare interface CompiledAxisGuide {
+    /** Which scale this axis represents */
+    scaleAestheticKey: ScaledAestheticKey;
+    /** The aesthetic this axis serves (always 'x' or 'y') */
+    aesthetic: AestheticKey;
+    /** Axis placement */
+    position: AxisPosition;
+    /** Title text, null means no title */
+    label: string | null;
+    /** Whether the axis (line + ticks + labels) is visible */
+    isVisible: boolean;
+    /** Candidate tick sets, sorted by ascending count. Runtime picks the densest one that fits. */
+    tickCandidates: AxisTickCandidate[];
+    /** Resolved format descriptor shared by all ticks on this axis */
+    valueFormat: ValueFormat;
+    /** Tick mode from config */
+    tickMode: AxisLabelMode;
+    /** Whether tick marks are visible */
+    ticksVisible: boolean;
+    /** Whether grid lines are visible at tick positions */
+    gridVisible: boolean;
+    /** Scale type — the renderer uses this to select a formatting strategy */
+    scaleType: ScaleType;
+    /** Band width in [0, 1] space for discrete position scales. Undefined otherwise. */
+    bandwidth?: number;
+}
+
+declare interface CompiledGeom {
+    /** The reparameterized dataset (may have new computed variables) */
+    data: Dataset;
+    /** Any mapping overrides produced by the geom */
+    mapping: AesMapping;
+}
+
+declare interface CompiledGroup {
+    data: Dataset;
+}
+
+/**
+ * All compiled guides, ready for the renderer.
+ */
+export declare interface CompiledGuides {
+    axes: CompiledAxisGuide[];
+    legends: CompiledLegendGuide[];
+    panel: CompiledPanel;
+}
+
+/**
+ * Identity scales — pass-through, no transformation.
+ * Used when data already contains render-ready values.
+ */
+export declare interface CompiledIdentityScale extends CompiledScaleBase {
+    kind: 'identity';
+    map: (value: DataValue) => DataValue;
+}
+
+/**
+ * Render-ready layer with resolved mappings and transformed data.
+ */
+export declare interface CompiledLayer {
+    /** Stable identity carried over from `LayerSpec.id`. Preserved across recompiles. */
+    id: string;
+    data: Dataset;
+    geom: GeomName;
+    /** Final mapping after merging root + layer + stat + geom overrides */
+    mapping: AesMapping;
+    position: PositionType;
+    yScaleType: YScaleType;
+    params: LayerSpec['params'];
+    /**
+     * When `false`, the runtime hover engine excludes this layer from primary hit-detection — a
+     * colocated interactive layer (line/area/bar) wins instead. The layer can still be surfaced as
+     * a related companion when another layer is primary.
+     */
+    interactive: boolean;
+}
+
+/**
+ * `CompiledLayer` narrowed to a specific `geom`. Lets call sites that already know the geom
+ * (geom renderers dispatched off `layer.geom`) take a typed `params` directly, eliminating the
+ * `as ...GeomParams` cast that was needed when `params` was the full param union.
+ */
+export declare type CompiledLayerFor<G extends GeomName> = Omit<CompiledLayer, 'geom' | 'params'> & {
+    geom: G;
+    params: Extract<LayerSpec, {
+        geom: G;
+    }>['params'];
+};
+
+export declare interface CompiledLegendGuide {
+    /** Which aesthetics this legend represents (may be merged) */
+    aesthetics: AestheticKey[];
+    /** Title text, null means no title */
+    title: string | null;
+    /** Resolved legend position (never 'auto' or 'none') */
+    position: ResolvedLegendPosition;
+    /** Resolved legend display mode (never 'auto') */
+    display: ResolvedLegendDisplay;
+    /** Legend entries in domain order */
+    items: LegendItem[];
+    /** Resolved format descriptor shared by all items in this legend */
+    valueFormat: ValueFormat;
+}
+
+export declare interface CompiledPanel {
+    border: {
+        isVisible: boolean;
+    };
+}
+
+declare interface CompiledPositionAdjuster {
+    /** The position-adjusted dataset (may have new/modified variables) */
+    data: Dataset;
+    /** Any mapping overrides produced by the position adjustment */
+    mapping: AesMapping;
+}
+
+/**
+ * Position scales (x, y) — map data values to normalized [0,1] space.
+ * The renderer maps [0,1] to pixel coordinates.
+ */
+export declare interface CompiledPositionScale<Input = DataValue> extends CompiledScaleBase<Input> {
+    kind: 'position';
+    map: (value: Input) => number;
+    /** Band width in [0,1] space for discrete position scales. Null for continuous/datetime. */
+    bandwidth: number | null;
+}
+
+declare type CompiledPositionScaleOptions<Input = DataValue> = Omit<CompiledPositionScale<Input>, 'kind' | 'aesthetic' | 'spec'>;
+
+export declare type CompiledScale<Input = DataValue> = CompiledPositionScale<Input> | CompiledVisualScale<Input> | CompiledIdentityScale;
+
+declare interface CompiledScaleBase<Input = DataValue> {
+    aesthetic: AestheticKey;
+    domain: Input[];
+    spec: ScaleSpec;
+    generateTicks: (options?: GenerateTicksOptions) => Input[];
+}
+
+export declare type CompiledScales = Partial<Record<ScaledAestheticKey, CompiledScale>>;
+
+/**
+ * Fully compiled spec, ready for the renderer.
+ */
+export declare interface CompiledSpec {
+    spec: Spec;
+    coordSystem: CoordSystem;
+    layers: CompiledLayer[];
+    scales: CompiledScales;
+    guides: CompiledGuides;
+    config: ConfigSpec;
+}
+
+declare interface CompiledStat {
+    /** The transformed dataset */
+    data: Dataset;
+    /** Any mapping overrides produced by the stat (e.g., y → 'count' for CountStat) */
+    mapping: AesMapping;
+}
+
+/**
+ * Visual scales (color, size, alpha, …) — map data values to concrete visual outputs
+ * (color strings, pixel sizes, opacity values, etc.).
+ */
+export declare interface CompiledVisualScale<Input = DataValue> extends CompiledScaleBase<Input> {
+    kind: 'visual';
+    map: (value: Input) => DataValue;
+}
+
+declare type CompiledVisualScaleOptions<Input = DataValue> = Omit<CompiledVisualScale<Input>, 'kind' | 'aesthetic' | 'spec'>;
+
+/**
+ * The main compiler. It orchestrates the compilation of a spec into a render-ready output.
+ *
+ * Each layer is processed through the pipeline. Coords and scales are compiled separately as they apply to
+ * the entire plot.
+ */
+export declare class Compiler {
+    private readonly specCompiler;
+    private readonly transformCompiler;
+    private readonly layerCompiler;
+    private readonly scaleCompiler;
+    private readonly coordCompiler;
+    private readonly positionMapperCompiler;
+    private readonly visualMapperCompiler;
+    private readonly guideCompiler;
+    constructor(specCompiler: SpecResolver, transformCompiler: TransformCompiler, layerCompiler: LayerCompiler, scaleCompiler: ScaleCompiler, coordCompiler: CoordCompiler, positionMapperCompiler: PositionMapperCompiler, visualMapperCompiler: VisualMapperCompiler, guideCompiler: GuideCompiler);
+    compile(compilerInput: CompilerInput): CompiledSpec;
+}
+
+/**
+ * Any value accepted by {@link Compiler.compile}: a low-level {@link SpecInput}, a high-level {@link GraphConfig}
+ * or an already-resolved {@link Spec}.
+ */
+export declare type CompilerInput = SpecInput | GraphConfig | Spec;
+
+/**
+ * Create a custom  configuration
+ */
+export declare function config(options: ConfigInput): ConfigItem;
+
+export declare type ConfigInput = DeepPartial<ConfigSpec> & {
+    legend?: LegendConfigInput;
+    content?: ContentInput;
+};
+
+/**
+ * Config specification with type tag
+ */
+declare interface ConfigItem {
+    type: 'config';
+    config: ConfigInput;
+}
+
+/**
+ * Feature configuration with resolved defaults.
+ * All fields are required and always populated after resolution.
+ */
+export declare interface ConfigSpec {
+    mode: ChartMode;
+    parsingLocale: Locale;
+    legend: LegendConfig;
+    axes: AxesConfig;
+    panel: PanelConfig;
+    headline: HeadlineConfig;
+    numberFormat: NumberFormatConfig;
+    content: ContentConfig;
+    appearance: AppearanceConfig;
+}
+
+declare function constant(options: ConstantOptions): ConstantTransformInput;
+
+/***************************************************************
+ * Constant Transform
+ ***************************************************************/
+declare interface ConstantOptions {
+    /** The name of the new variable. */
+    variableName: VariableName;
+    /** The type of the new variable. */
+    type: DataType;
+    /** The constant value to assign to every observation. */
+    value: DataValue;
+}
+
+declare interface ConstantTransformInput {
+    type: 'transform';
+    transformType: 'constant';
+    options: ConstantOptions;
+}
+
+/** Text content in the graph. */
+declare interface Content {
+    title?: string | unknown;
+    isTitleHidden?: boolean;
+    subtitle?: string | unknown;
+    isSubtitleHidden?: boolean;
+    caption?: string | unknown;
+    isCaptionHidden?: boolean;
+    source?: Partial<{
+        label: string;
+        url: string;
+    }>;
+    isSourceHidden?: boolean;
+}
+
+/** Resolved content configuration (all fields populated). */
+export declare interface ContentConfig {
+    isVisible: boolean;
+    title: TextContent | null;
+    subtitle: TextContent | null;
+    caption: TextContent | null;
+}
+
+/** Content input — all fields optional, null means no content. */
+declare type ContentInput = Partial<ContentConfig>;
+
+declare type ContinuousScaleInput = {
+    type: 'scale';
+    scaledAesthetic: ScaledAestheticKey;
+    scaleType: 'continuous';
+    transform?: ScaleTransformType;
+    reverse?: boolean;
+    nice?: boolean;
+    zero?: boolean;
+    clamp?: boolean;
+    domainMin?: number | null;
+    domainMax?: number | null;
+    range?: [number, number] | null;
+};
+
+declare type ContinuousScaleOptions = {
+    /**
+     * Mathematical transformation to apply.
+     * - 'linear': No transformation (default)
+     * - 'log': Base-10 logarithm
+     * - 'sqrt': Square root
+     */
+    transform?: ScaleTransformType;
+    /**
+     * Reverse the scale direction.
+     * Can be combined with any transformation.
+     * @default false
+     * @example scale.y.continuous({ reverse: true }) // reversed continuous scale
+     */
+    reverse?: boolean;
+    /**
+     * Extend domain to nice round values.
+     * @example nice: true // [3, 97] becomes [0, 100]
+     */
+    nice?: boolean;
+    /**
+     * Include zero in the domain.
+     * Default is true for y-axis, false for x-axis.
+     * @example zero: false // Allow axis to start above zero
+     */
+    zero?: boolean;
+    /**
+     * Restrict output to the scale's range when input falls outside the domain.
+     * Without clamping, values extrapolate beyond the range boundaries.
+     * Default is false for position aesthetics (x, y), true for non-position (color, size, alpha, …).
+     * @example clamp: true // Pin out-of-domain values to range boundaries
+     */
+    clamp?: boolean;
+    /**
+     * Override the minimum domain value only.
+     * Maximum is still computed from data.
+     * @example domainMin: 0 // Ensure axis starts at 0
+     */
+    domainMin?: number;
+    /**
+     * Override the maximum domain value only.
+     * Minimum is still computed from data.
+     * @example domainMax: 100 // Cap axis at 100
+     */
+    domainMax?: number;
+    /**
+     * Output range for non-positional scales (size, alpha, strokeWidth).
+     * Ignored for position aesthetics (x, y).
+     * Aesthetic-specific defaults are applied when not specified:
+     * - size: [4, 20]
+     * - alpha: [0.1, 1]
+     * - strokeWidth: [1, 4]
+     * @example range: [2, 30] // custom size range in pixels
+     */
+    range?: [number, number];
+};
+
+declare type ContinuousScaleSpec = Required<ContinuousScaleInput>;
+
+export declare const coord: {
+    /**
+     * Standard cartesian (x-y) coordinate system. This is the default if no coord is specified.
+     *
+     * @example coord.cartesian() // auto-scaled axes
+     * @example coord.cartesian({ yLimits: [0, 100] }) // fixed y-axis
+     */
+    cartesian: (params?: Partial<CartesianCoordParams>) => CartesianCoordInput;
+    /**
+     * Flipped cartesian coordinates — swaps x and y axes.
+     * Useful for horizontal bar charts or when category labels are long.
+     *
+     * @example coord.flip() // horizontal bars
+     */
+    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.
+     *
+     * @example coord.polar() // pie chart
+     * @example coord.polar({ innerRadius: 0.5 }) // donut chart
+     */
+    polar: (params?: Partial<PolarCoordParams>) => PolarCoordInput;
+};
+
+/**
+ * Resolves a coordinate system by type and delegates compilation.
+ */
+declare class CoordCompiler {
+    private readonly registry;
+    constructor(registry: CoordRegistry);
+    setup(input: CoordSetupInput): CoordSystem;
+    transform(input: CoordTransformInput): CompiledLayer[];
+}
+
+/**
+ * Discriminated union of all coordinate input specs (user-provided, optional params).
+ */
+declare type CoordInput = CartesianCoordInput | FlipCoordInput | PolarCoordInput;
+
+/**
+ * Built-in coordinate system implementations keyed by {@link CoordType}.
+ */
+declare class CoordRegistry extends Registry<CoordType, CoordStrategy> {
+    constructor();
+}
+
+declare interface CoordSetupInput {
+    coordSpec: CoordSpec;
+}
+
+/**
+ * Discriminated union of all resolved coordinate specs (params fully defaulted).
+ */
+declare type CoordSpec = CartesianCoordSpec | FlipCoordSpec | PolarCoordSpec;
+
+/**
+ * Strategy interface for compiling a specific coordinate system type
+ */
+declare interface CoordStrategy {
+    /**
+     * The coordinate type this strategy handles.
+     * Must match the `coordType` property on the coordinate spec.
+     */
+    readonly coordType: CoordType;
+    /**
+     * Produces the coordinate system with axis orientation metadata.
+     * Called before the guide compiler.
+     */
+    setup: (input: CoordSetupInput) => CoordSystem;
+    /**
+     * Transforms position-mapped layers through the coordinate system.
+     * Called after the position mapper to produce render-ready coordinates.
+     */
+    transform: (input: CoordTransformInput) => CompiledLayer[];
+}
+
+/**
+ * Render-ready coordinate system (discriminated union).
+ * Discriminates on geometric paradigm: cartesian plane vs polar projection.
+ */
+export declare type CoordSystem = CartesianCoordSystem | PolarCoordSystem;
+
+declare interface CoordTransformInput {
+    coordSpec: CoordSpec;
+    layers: CompiledLayer[];
+}
+
+/**
+ * Coordinate system type for transforming geometric positions.
+ *
+ * - `'cartesian'` — Standard x/y Cartesian plane
+ * - `'polar'` — Polar coordinates for pie, radar, and radial charts
+ * - `'flip'` — Cartesian with x and y axes swapped
+ */
+declare type CoordType = 'cartesian' | 'polar' | 'flip';
+
+export declare const createAlphaValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
+
+export declare const createColorValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
+
+export declare const createGroupValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
+
+export declare const createLabelValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
+
+export declare const createSizeValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
+
+/**
+ * Create a new spec, optionally piping spec items in one call.
+ *
+ * @example
+ * When using the mapping as second arg:
+ *   createSpec(data, { x: 'date', y: 'value' })
+ *
+ * When using the mapping as a spec item (more readable when chaining transforms):
+ *   createSpec(
+ *     data,
+ *     transform.reshape({ reshape: ['revenue'], keyName: 'metric', valueName: 'amount' }),
+ *     mapping({ x: 'month', y: 'amount', color: 'metric' }),
+ *     geom.bar(),
+ *     scale.x(),
+ *   )
+ */
+export declare function createSpec(data: Data, ...items: Array<AesMapping | SpecItem>): SpecInput;
+
+export declare const createStrokeWidthValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
+
+export declare const createXValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
+
+export declare const createYValueReader: (data: Dataset, mapping: AesMapping) => (observation: Observation) => DataValue;
+
+/** Three letter ISO string representing the currency */
+declare type CurrencyIso = 'aed' | 'aud' | 'bdt' | 'bhd' | 'brl' | 'cad' | 'chf' | 'clp' | 'cny' | 'cop' | 'czk' | 'dkk' | 'egp' | 'eur' | 'gbp' | 'hkd' | 'huf' | 'idr' | 'ils' | 'inr' | 'jpy' | 'krw' | 'kwd' | 'mxn' | 'myr' | 'ngn' | 'nok' | 'nzd' | 'php' | 'pkr' | 'pln' | 'qar' | 'ron' | 'rub' | 'sar' | 'sek' | 'sgd' | 'thb' | 'try' | 'twd' | 'usd' | 'vnd' | 'zar';
+
+declare interface CurrencyValueFormat {
+    type: 'currency';
+    iso: CurrencyIso;
+}
+
+/**
+ * Data to visualize. Structured as a table.
+ *
+ * The public-API contract. Row values must be {@link DataValue} (string, number,
+ * Date, or null). Internal entry points (e.g. the dataset parser) accept a
+ * looser row type — see {@link RawData} — because they must defensively handle
+ * malformed input.
+ */
+export declare interface Data {
+    /**
+     * Column definitions. Every column is an object with a stable `key` that matches the keys used in each row and an optional `label` to show in the UI.
+     */
+    columns: Array<{
+        /** Unique, stable identifier. */
+        key: string;
+        /** Friendly label for the column. */
+        label?: string;
+        /* Excluded from this release type: _metadata */
+    }>;
+    /**
+     * Data rows. Each row object must contain keys that match `columns[i].key`.
+     */
+    rows: Array<Record<string, DataValue>>;
+    /* Excluded from this release type: _metadata */
+}
+
+declare interface DataLabels {
+    showDataLabels?: boolean;
+    dataLabelFormat?: 'absolute' | 'percentage';
+    showStackTotals?: boolean;
+    showCategoryLabels?: boolean;
+}
+
+/**
+ * An immutable, columnar dataset. Uses Arquero internally for filtering, grouping and aggregation.
+ *
+ * Data is organised as **variables** (columns) and **observations** (rows). The values of each variable are typed and must match the variable's {@link DataType}. Missing values are represented as `null`.
+ *
+ * All transformation methods (filter, orderBy, addVariable etc.) return a new instance.
+ *
+ * @example
+ * const data = new Dataset({
+ *   age: { type: 'numeric', values: [25, 30, 35, null] },
+ *   name: { type: 'categorical', values: ['John', 'Jane', 'Jim', 'Joanna'] },
+ * });
+ *
+ * data.filter('age', 'gt', 30).print();
+ */
+export declare class Dataset {
+    private table;
+    private variableMetadata;
+    /**
+     * Constructs a new dataset from typed columnar input.
+     * @param variables - A record mapping variable names to their type and values.
+     *
+     * @example
+     * const data = new Dataset({
+     *   age: { type: 'numeric', values: [25, 30, 35] },
+     *   name: { type: 'categorical', values: ['John', 'Jane', 'Jim'] },
+     * });
+     */
+    constructor(variables?: VariableMap);
+    /**
+     * Merges multiple datasets into a single one.
+     */
+    static merge(...datasets: Dataset[]): Dataset;
+    /* Excluded from this release type: fromTrusted */
+    /**
+     * Returns the number of observations in the dataset.
+     */
+    size(): number;
+    /**
+     * Returns the names of all variables in the dataset.
+     */
+    getVariableNames(): VariableName[];
+    /**
+     * Returns true if the dataset has the given variable.
+     */
+    hasVariable(variable: VariableName): boolean;
+    /**
+     * Returns a JSON-serialisable {@link Data} representation of this dataset. Inverse of
+     * {@link parseDataset}: feeding the result back through the parser reconstructs an
+     * equivalent dataset.
+     */
+    toData(): Data;
+    /**
+     * Adds a new variable to the dataset.
+     */
+    addVariable(variable: VariableName, type: DataType, values: DataValue[]): Dataset;
+    /**
+     * Adds a new constant variable to the dataset.
+     */
+    addConstantVariable(variable: VariableName, type: DataType, value: DataValue): Dataset;
+    /**
+     * Derives a new variable based on existing variables, using a table expression.
+     */
+    deriveVariable(variable: VariableName, type: DataType, expression: (observation: Observation) => DataValue): Dataset;
+    /**
+     * Renames a variable.
+     */
+    renameVariable(oldName: VariableName, newName: VariableName): Dataset;
+    /**
+     * Selects a subset of variables from the dataset.
+     */
+    selectVariables(...variables: VariableName[]): Dataset;
+    /**
+     * Returns the type of a variable.
+     */
+    getType(variable: VariableName): DataType;
+    /**
+     * Groups the variable names by their type.
+     */
+    groupVariableNamesByType(): GroupedVariableNames;
+    /**
+     * Returns the values of a given variable.
+     *
+     * @param options.type - The expected type of the values. If provided, the return type is narrowed to the matching concrete type and a runtime check ensures the variable actually carries that type.
+     * @param options.skipNulls - Whether to skip null values. Defaults to `false`.
+     * @param options.distinct - Whether to remove duplicate values from the result. Defaults to `false`.
+     */
+    getValues(variable: VariableName, options: GetValuesOptions & {
+        type: 'numeric';
+        skipNulls?: false;
+    }): Array<number | null>;
+    getValues(variable: VariableName, options: GetValuesOptions & {
+        type: 'categorical';
+        skipNulls?: false;
+    }): Array<string | null>;
+    getValues(variable: VariableName, options: GetValuesOptions & {
+        type: 'temporal';
+        skipNulls?: false;
+    }): Array<Date | null>;
+    getValues(variable: VariableName, options: GetValuesOptions & {
+        type: 'numeric';
+        skipNulls: true;
+    }): number[];
+    getValues(variable: VariableName, options: GetValuesOptions & {
+        type: 'categorical';
+        skipNulls: true;
+    }): string[];
+    getValues(variable: VariableName, options: GetValuesOptions & {
+        type: 'temporal';
+        skipNulls: true;
+    }): Date[];
+    getValues(variable: VariableName, options?: GetValuesOptions): DataValue[];
+    /**
+     * Filters the dataset using a declarative predicate.
+     */
+    filter(variableName: VariableName, operator: ComparisonOperator, value: DataValue): Dataset;
+    /**
+     * Orders the dataset by a variable, in ascending (default) or descending order.
+     */
+    orderBy(variable: VariableName, direction?: 'asc' | 'desc'): Dataset;
+    /**
+     * Returns the first observation in the dataset.
+     */
+    getFirst(): Observation | null;
+    /**
+     * Returns the last observation in the dataset.
+     */
+    getLast(): Observation | null;
+    /**
+     * Returns the last observation matching a predicate, scanning backwards from the end.
+     */
+    findLast(predicate: (observation: Observation) => boolean): Observation | null;
+    /**
+     * Groups the dataset by one or more variables.
+     */
+    groupBy(...variables: VariableName[]): GroupBy;
+    /**
+     * Aggregates the dataset.
+     */
+    rollup(aggregations: AggregationInput): Dataset;
+    /**
+     * Reshapes data from wide to long format by collapsing multiple numeric variables
+     * into key–value pairs.
+     *
+     * ```
+     * ┌─────────┬──────┬──────┬──────┐        ┌─────────┬──────┬─────┐
+     * │ country │ 2020 │ 2021 │ 2022 │        │ country │ year │ gdp │
+     * ├─────────┼──────┼──────┼──────┤  ───►  ├─────────┼──────┼─────┤
+     * │ US      │  100 │  110 │  120 │        │ US      │ 2020 │ 100 │
+     * │ UK      │  200 │  210 │  220 │        │ US      │ 2021 │ 110 │
+     * └─────────┴──────┴──────┴──────┘        │ US      │ 2022 │ 120 │
+     *                                         │ UK      │ 2020 │ 200 │
+     *                                         │ UK      │ 2021 │ 210 │
+     *                                         │ UK      │ 2022 │ 220 │
+     *                                         └─────────┴──────┴─────┘
+     * ```
+     *
+     * @param keep - Variables to carry through unchanged. Defaults to all
+     *   categorical and temporal variables.
+     * @param reshape - Numeric variables to collapse into rows. Defaults to all
+     *   numeric variables.
+     * @param keyName - Name of the new variable whose values are the
+     *   original variable names (default: 'key').
+     * @param valueName - Name of the new variable whose values are the
+     *   original values of the variables to reshape (default: 'value').
+     * @throws If `keyName` or `valueName` conflicts with a variable in `keep`.
+     * @throws If any variable in `reshape` is not numeric.
+     *
+     * @example
+     * const reshaped = data.reshapeFromWideToLong({
+     *   keep: ['country'],
+     *   reshape: ['2020', '2021'],
+     *   keyName: 'year',
+     *   valueName: 'gdp',
+     * });
+     */
+    reshapeFromWideToLong({ keep, reshape, keyName, valueName, }?: {
+        keep?: VariableName[];
+        reshape?: VariableName[];
+        keyName?: VariableName;
+        valueName?: VariableName;
+    }): Dataset;
+    /**
+     * Prints the dataset to the console.
+     */
+    print(): void;
+    /**
+     * Returns an iterator over the observations in the dataset.
+     */
+    [Symbol.iterator](): Iterator<Observation>;
+    /**
+     * Parses the variable map into a table and variable metadata.
+     */
+    private parseVariableMap;
+    /**
+     * Normalizes raw values into typed values.
+     */
+    private normalizeRawValues;
+    /**
+     * Skips nulls when retrieving values from a variable.
+     */
+    private skipNulls;
+    /**
+     * Returns distinct values.
+     */
+    private getDistinctValues;
+}
+
+/**
+ * Metadata about the dataset (before we reshape it from wide to long format).
+ */
+declare interface DatasetMetadata {
+    /**
+     * Column metadata, keyed by column key. For each column,
+     * we store the inferred value format and a function to get the default label.
+     */
+    columns: ColumnMetadata;
+}
+
+/** The type of a variable's values. Internally, numeric values are stored as numbers, dates as Date objects and categorical values as strings. */
+export declare type DataType = 'numeric' | 'categorical' | 'temporal';
+
+/** The smallest unit of data in the dataset. `null` represents a missing value. */
+export declare type DataValue = number | string | Date | null;
+
+declare interface DatetimeScaleInput {
+    type: 'scale';
+    scaledAesthetic: ScaledAestheticKey;
+    scaleType: 'datetime';
+    domainMin?: number | null;
+    domainMax?: number | null;
+    nice?: boolean;
+    reverse?: boolean;
+    clamp?: boolean;
+}
+
+declare type DatetimeScaleOptions = {
+    /** Minimum domain override (milliseconds since epoch). */
+    domainMin?: number;
+    /** Maximum domain override (milliseconds since epoch). */
+    domainMax?: number;
+    /**
+     * Reverse the scale direction.
+     * Can be combined with any transformation.
+     * @default false
+     * @example scale.y.log({ reverse: true }) // reversed log scale
+     */
+    reverse?: boolean;
+    /**
+     * Extend domain to nice round values.
+     * @example nice: true // [3, 97] becomes [0, 100]
+     */
+    nice?: boolean;
+    /**
+     * Restrict output to the scale's range when input falls outside the domain.
+     * Without clamping, values extrapolate beyond the range boundaries.
+     * Defaults to false for datetime scales (always positional).
+     * @example clamp: true // Pin out-of-domain values to range boundaries
+     */
+    clamp?: boolean;
+};
+
+declare type DatetimeScaleSpec = Required<DatetimeScaleInput>;
+
+declare interface DatetimeTickInterval {
+    unit: DatetimeTickIntervalUnit;
+    step: number;
+}
+
+declare type DatetimeTickIntervalUnit = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+
+/**
+ * Recursively makes every property of `T` optional.
+ * Unlike the built-in `Partial`, this applies to nested objects as well.
+ */
+declare type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends Array<infer U> ? Array<DeepPartial<U>> : NonNullable<T[K]> extends object ? DeepPartial<NonNullable<T[K]>> : T[K];
+};
+
+/**
+ * Default Graphy color palette.
+ *
+ * Used as the built-in palette for `scale.color.palette()` when no
+ * explicit palette name is provided.
+ */
+export declare const DEFAULT_COLOR_PALETTE: readonly ["#B399FE", "#FC7E91", "#33B6E0", "#FFC849", "#25CDA5", "#FA9B65", "#D93C95", "#845FD8", "#3F8EEB", "#58C8D8", "#F35074", "#6EA0DA"];
+
+/**
+ * Default font style.
+ */
+export declare const DEFAULT_FONT_STYLE = "normal";
+
+/**
+ * Default font weight.
+ */
+export declare const DEFAULT_FONT_WEIGHT = 500;
+
+export declare const DEFAULT_LOCALE: Locale;
+
+export declare const DEFAULT_PALETTE_NAME = "default";
+
+declare interface DiscreteScaleInput {
+    type: 'scale';
+    scaledAesthetic: ScaledAestheticKey;
+    scaleType: 'discrete';
+    range?: Array<number | string> | null;
+    sort?: DiscreteSort | null;
+    domain?: Array<string | number> | null;
+    padding?: number | null;
+}
+
+declare type DiscreteScaleOptions = {
+    /**
+     * Explicit output values mapped to domain categories in order.
+     */
+    range?: Array<number | string>;
+    /**
+     * Sort order for discrete domain values.
+     * @default 'none'
+     */
+    sort?: DiscreteSort | null;
+    /**
+     * Explicit domain values controlling category order and membership.
+     * Only these values appear in the scale; sort is ignored when domain is set.
+     */
+    domain?: Array<string | number>;
+    /**
+     * Padding between bands as a fraction of the band step (0–1).
+     * Applied as `innerPadding = padding` and `outerPadding = padding / 2`.
+     * @default 0.1
+     */
+    padding?: number;
+};
+
+declare type DiscreteScaleSpec = Required<DiscreteScaleInput>;
+
+declare type DiscreteSort = 'ascending' | 'descending' | 'none';
+
+/** Measured heights of content regions (header: title+subtitle, footer: caption). */
+export declare interface ExternalMeasurements {
+    headerSize: BoxSize;
+    footerSize: BoxSize;
+}
+
+declare function filter(options: FilterOptions): FilterTransformInput;
+
+/***************************************************************
+ * Filter Transform
+ ***************************************************************/
+declare interface FilterOptions {
+    /** The variable to filter on. */
+    variableName: VariableName;
+    /** The comparison operator. */
+    operator: ComparisonOperator;
+    /** The value to compare against. */
+    value: DataValue;
+}
+
+declare interface FilterTransformInput {
+    type: 'transform';
+    transformType: 'filter';
+    options: FilterOptions;
+}
+
+declare interface FlipCoordInput {
+    type: 'coord';
+    coordType: 'flip';
+    params?: Partial<BaseCoordParams>;
+}
+
+declare type FlipCoordParams = BaseCoordParams;
+
+declare interface FlipCoordSpec {
+    type: 'coord';
+    coordType: 'flip';
+    params: BaseCoordParams;
+}
+
+export declare interface FontSpec {
+    family: string;
+    size: number;
+    weight?: NamedWeightKey | number;
+    style?: 'normal' | 'italic' | 'oblique';
+}
+
+/**
+ * Formats all legend guides by attaching a `formattedLabel` to each item.
+ */
+export declare const formatLegends: (compiled: CompiledSpec, { formattingLocale }?: {
+    formattingLocale?: Locale;
+}) => FormattedLegend[];
+
+export declare interface FormattedAxis extends Omit<CompiledAxisGuide, 'tickCandidates'> {
+    ticks: Array<AxisTick & {
+        formattedLabel: string;
+    }>;
+    /** Rotation in degrees applied uniformly to all tick labels. 0 = no rotation. */
+    labelRotation: number;
+    /** Max label width in px before ellipsis truncation. null = no cap. */
+    labelMaxWidthPx: number | null;
+}
+
+export declare interface FormattedLegend extends Omit<CompiledLegendGuide, 'items'> {
+    items: Array<LegendItem & {
+        formattedLabel: string;
+    }>;
+}
+
+/**
+ * Options for `generateTicks`:
+ * - `{ count }` — approximate tick count (continuous, datetime).
+ * - `{ interval }` — fixed time interval (datetime only).
+ * - `{ atInputs: true }` — ticks at the deduped input values (datetime only).
+ *
+ * Discrete scales ignore options. Unsupported variants on a given scale fall back to defaults.
+ */
+declare type GenerateTicksOptions = {
+    count: number;
+} | {
+    interval: DatetimeTickInterval;
+} | {
+    atInputs: true;
+};
+
+/**
+ * Base class for geoms that turn observations into visual marks (points, bars, lines etc).
+ */
+declare abstract class Geom {
+    readonly requiredAesthetics: AestheticKey[];
+    abstract readonly type: GeomName;
+    abstract compile(input: GeomCompilerInput): CompiledGeom;
+}
+
+export declare const geom: {
+    point: typeof point;
+    line: typeof line;
+    area: typeof area;
+    bar: typeof bar;
+};
+
+/**
+ * Resolves a geom by name and delegates compilation.
+ */
+declare class GeomCompiler {
+    private readonly registry;
+    constructor(registry: GeomRegistry);
+    compile(geomName: GeomName, input: GeomCompilerInput): CompiledGeom;
+}
+
+declare interface GeomCompilerInput {
+    /** The dataset after stat transformation */
+    data: Dataset;
+    /** The effective mapping for the layer */
+    mapping: AesMapping;
+    /** Geom-specific params */
+    params: LayerSpec['params'];
+}
+
+/**
+ * The type of geometric mark used to represent data in a layer.
+ *
+ * - `'point'` — Scatter-style dot marks
+ * - `'line'` — Connected line marks
+ * - `'area'` — Filled area marks
+ * - `'bar'` — Rectangular bar marks
+ */
+export declare type GeomName = 'point' | 'line' | 'area' | 'bar';
+
+declare type GeomOptions<G extends GeomName> = BaseGeomOptions<GeomParamsMap[G]>;
+
+declare type GeomParams = GeomParamsMap[keyof GeomParamsMap];
+
+/**
+ * Maps each geom type name to its resolved parameter type.
+ */
+declare interface GeomParamsMap {
+    point: PointGeomParams;
+    line: LineGeomParams;
+    area: AreaGeomParams;
+    bar: BarGeomParams;
+}
+
+/**
+ * Built-in geom implementations keyed by {@link GeomName}.
+ */
+declare class GeomRegistry extends Registry<GeomName, Geom> {
+    constructor();
+}
+
+/** Reads the resolved alpha (opacity) value from an observation. */
+export declare function getAlpha(observation: Observation): NumericDataValue;
+
+export declare function getAngleExtent(observation: Observation): AngleExtent;
+
+/** Reads the resolved color string from an observation. */
+export declare function getColor(observation: Observation): string | undefined;
+
+/** Reads the coordinate lying on the cross axis of the coord system. */
+export declare function getCrossAxisCoordinate(mainAxis: MainAxis, point: XYPoint): number;
+
+export declare const getGroup: (observation: Observation) => CategoricalDataValue;
+
+/** Reads the coordinate lying on the main (independent) axis of the coord system. */
+export declare function getMainAxisCoordinate(mainAxis: MainAxis, point: XYPoint): number;
+
+export declare function getRadiusExtent(observation: Observation): RadiusExtent;
+
+/** Reads the resolved size value from an observation. */
+export declare function getSize(observation: Observation): NumericDataValue;
+
+/** Reads the resolved stroke width value from an observation. */
+export declare function getStrokeWidth(observation: Observation): NumericDataValue;
+
+declare interface GetValuesOptions {
+    /** The expected type of the values. */
+    type?: DataType;
+    /** Whether to skip null values. Defaults to `false`. */
+    skipNulls?: boolean;
+    /** Whether to return distinct values. Defaults to `false`. */
+    distinct?: boolean;
+}
+
+/** Reads the normalized x position from an observation. */
+export declare function getX(observation: Observation): NumericDataValue;
+
+/** Reads the normalized xMax (right band edge) from an observation. */
+export declare function getXMax(observation: Observation): NumericDataValue;
+
+/** Reads the normalized xMin (left band edge) from an observation. */
+export declare function getXMin(observation: Observation): NumericDataValue;
+
+/** Reads the normalized y position from an observation. */
+export declare function getY(observation: Observation): NumericDataValue;
+
+/** Reads the normalized yMax (upper extent) from an observation. */
+export declare function getYMax(observation: Observation): NumericDataValue;
+
+/** Reads the normalized yMin (lower extent) from an observation. */
+export declare function getYMin(observation: Observation): NumericDataValue;
+
+/** Goal line with a target value. */
+declare interface GoalLine {
+    target: number;
+    marker?: DataValue;
+    label?: string;
+}
+
+declare type GraphAnnotation = GraphStickerAnnotation | GraphTooltipAnnotation | GraphHighlightAnnotation | GraphTextAnnotation | GraphArrowAnnotation | GraphDifferenceArrowAnnotation | GraphShapeAnnotation;
+
+declare interface GraphArrowAnnotation {
+    id: string;
+    type: 'arrow';
+    startX: number;
+    startY: number;
+    endX: number;
+    endY: number;
+    color?: string;
+    thickness: 'thin' | 'medium' | 'thick';
+    startArrowheadStyle: 'none' | 'line-arrow';
+    lineStyle: 'solid' | 'dashed';
+    endArrowheadStyle: 'none' | 'line-arrow';
+    hasStickerStyle: boolean;
+}
+
+export declare interface GraphConfig {
+    data: Data;
+    type?: GraphType;
+    options?: Options;
+    axes?: Axes;
+    legend?: Legend;
+    appearance?: Appearance;
+    themeOverrides?: unknown;
+    content?: Content;
+    headlineNumbers?: HeadlineNumbers;
+    dataLabels?: DataLabels;
+    annotations?: GraphAnnotation[];
+    referenceLines?: ReferenceLines;
+}
+
+declare interface GraphDifferenceArrowAnnotation {
+    id: string;
+    type: 'difference-arrow';
+    show: 'absolute-difference' | 'relative-difference' | 'proportion';
+    start: AnnotationDataPoint;
+    end: AnnotationDataPoint;
+    color?: string;
+    size: 'medium' | 'small' | 'large';
+    labelPosition?: number;
+}
+
+declare type GraphHighlightAnnotation = {
+    id: string;
+    type: 'highlight';
+    highlight: 'data-point' | 'series' | 'x-value';
+} & AnnotationDataPoint;
+
+/** Output of the layout computation. */
+export declare interface GraphLayout {
+    /** The full graphical area (axes + panel + axis labels), excluding header and footer. */
+    plot: Rect;
+    /** The panel area where geom layers render i.e. the data rectangle inside the axes. */
+    panel: Rect;
+    /** Rects for axis regions (ticks + tick labels), keyed by edge. */
+    axes: Partial<Record<LayoutEdge, Rect>>;
+    /** Rects for axis title labels, keyed by edge. */
+    axisLabels: Partial<Record<LayoutEdge, Rect>>;
+    /** Rect for the header region (title + subtitle, above the panel). */
+    header: Rect;
+    /** Rect for the footer region (caption, below the panel). */
+    footer: Rect;
+    /** Rects for the legend regions, keyed by edge. */
+    legends: Partial<Record<LayoutEdge, Rect>>;
+}
+
+declare interface GraphShapeAnnotation {
+    id: string;
+    type: 'shape';
+    shape: 'rectangle';
+    layer: 'belowPlot' | 'abovePlot';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fillColor: string;
+    fillOpacity: number;
+    strokeWidth: number;
+}
+
+declare type GraphStickerAnnotation = {
+    id: string;
+    type: 'sticker';
+    sticker: 'rocket' | 'clapping-hands' | 'thumbs-up' | 'thumbs-down' | 'grinning-face';
+} & AnnotationDataPoint;
+
+declare interface GraphTextAnnotation {
+    id: string;
+    type: 'text';
+    content: unknown;
+    x: number;
+    y: number;
+    width: number;
+    backgroundColor?: string;
+    backgroundColorStyle?: 'fade' | 'opaque';
+}
+
+declare interface GraphTextStyle {
+    fontId?: string;
+    color?: string;
+}
+
+declare type GraphTooltipAnnotation = {
+    id: string;
+    type: 'tooltip';
+    caption: unknown;
+} & AnnotationDataPoint;
+
+/** Type of graph to use for the data. */
+export declare type GraphType = 'line' | 'areaStacked' | 'bar' | 'barStacked' | 'barStackedFill' | 'column' | 'columnStacked' | 'columnStackedFill' | 'combo' | 'pie' | 'donut' | 'funnel' | 'heatmap' | 'scatter' | 'bubble' | 'waterfall' | 'mekko' | 'table';
+
+export declare const GROUP_VARIABLES: {
+    readonly group: string;
+};
+
+/**
+ * A group by operation on a dataset. This is returned when calling `new Dataset(...).groupBy(...)`.
+ */
+declare class GroupBy {
+    private groupedBy;
+    private grouped;
+    private variableMetadata;
+    constructor(groupedBy: VariableName[], grouped: Table, variableMetadata: VariableMetadata);
+    /**
+     * Iterates over each group.
+     */
+    forEach(callback: (group: Dataset, groupKey: string, groupIndex: number) => void): void;
+    /**
+     * Aggregates the variables in each group.
+     */
+    rollup(aggregations: AggregationInput): Dataset;
+    /**
+     * Computes the group key based on the first value of the grouped variable. If multiple variables are grouped, returns a composite key.
+     */
+    private getStableKey;
+}
+
+/**
+ * Computes a `group` variable with composite group keys. If a `group` aesthetic is explicitly mapped, it is used as
+ * the sole group variable. Otherwise, the grouping is determined by discrete aesthetics (where a group is created
+ * for each unique combination of the discrete aesthetics). When no group variables exist, fills the variable with null.
+ */
+declare class GroupCompiler {
+    compute({ data, mapping }: GroupCompilerInput): CompiledGroup;
+}
+
+declare interface GroupCompilerInput {
+    data: Dataset;
+    mapping: AesMapping;
+}
+
+/** A map of variable names grouped by their type. */
+declare type GroupedVariableNames = {
+    [key in DataType]: VariableName[];
+};
+
+/**
+ * Compiles guides (axes and legends) from compiled scales and config.
+ *
+ * Legends are compiled first because the resolved legend position influences
+ * axis compilation (e.g. legend on right forces Y-axis to left).
+ *
+ * Axes are produced from position scales (x, y, ySecondary).
+ * Legends are produced from non-position, non-identity visual scales.
+ * Legends that share the same variable and domain are merged.
+ */
+declare class GuideCompiler {
+    compile(input: GuideCompilerInput): CompiledGuides;
+}
+
+declare interface GuideCompilerInput {
+    scales: CompiledScales;
+    config: ConfigSpec;
+    layers: CompiledLayer[];
+    coordSystem: CoordSystem;
+    datasetMetadata: DatasetMetadata;
+}
+
+declare type GuideGeometry = 'linear' | 'circular' | 'radial';
+
+/**
+ * Comparison reference for trend indicator
+ * - 'previous': Compare to preceding data point
+ * - 'first': Compare to initial value in series
+ * - 'none': No comparison indicator
+ */
+declare type HeadlineCompare = 'previous' | 'first' | 'none';
+
+/**
+ * Headline numbers configuration
+ */
+declare interface HeadlineConfig {
+    /**
+     * Which aggregate to display
+     * @default 'none'
+     */
+    show: HeadlineShow;
+    /**
+     * Reference point for trend comparison
+     * @default 'none'
+     */
+    compareWith: HeadlineCompare;
+    /**
+     * Visual size of the headline numbers
+     * @default 'auto'
+     */
+    size: HeadlineSize;
+    /**
+     * Where to display the headline
+     * - 'above': In the header region above the chart (default)
+     * - 'center': In the center of a donut chart hole (only valid for donut charts with inner radius)
+     * @default 'above'
+     */
+    position: HeadlinePosition;
+}
+
+declare interface HeadlineNumbers {
+    show?: 'current' | 'average' | 'total' | 'conversion' | 'none';
+    compareWith?: 'previous' | 'first' | 'none';
+    size?: 'auto' | 'small' | 'medium' | 'large';
+}
+
+/**
+ * Placement of headline numbers
+ * - 'above': Display above the chart (default, in the header region)
+ * - 'center': Display in the center of a donut chart hole (only valid for donut charts)
+ */
+declare type HeadlinePosition = 'above' | 'center';
+
+/**
+ * Display mode for headline numbers
+ * - 'total': Sum of all values
+ * - 'average': Arithmetic mean
+ * - 'current': Last value in series (for time series)
+ * - 'conversion': Percentage change from first to last
+ * - 'none': Disable headline numbers
+ */
+declare type HeadlineShow = 'total' | 'average' | 'current' | 'conversion' | 'none';
+
+/**
+ * Size of headline numbers
+ * - 'auto': Automatically scale based on available space and number of series
+ * - 'small': Compact display
+ * - 'medium': Standard display
+ * - 'large': Prominent display
+ */
+declare type HeadlineSize = 'auto' | 'small' | 'medium' | 'large';
+
+/**
+ * A zero-dependency text measurer that estimates dimensions using
+ * per-character width ratios calibrated from Inter Regular.
+ *
+ * Accuracy is approximately 5-8% for Inter and 10-15% for other fonts.
+ * Intended for use in test environments (jsdom) where no Canvas API is available.
+ */
+export declare class HeuristicTextMeasurer implements TextMeasurer {
+    measureText(text: string, font: FontSpec): MeasuredText;
+}
+
+/**
+ * The mouse position captured alongside a hit. Present even when the cursor is over no geom.
+ *
+ * Both coordinates are normalized pane-local values in `[0, 1]`. `y` is data-space (0 at the
+ * bottom of the plot, 1 at the top), matching the compiler's `POSITION_VARIABLES.y` convention
+ * — so the tracker is responsible for flipping SVG's top-origin Y before calling `query()`.
+ */
+export declare interface HoverCursor {
+    x: number;
+    y: number;
+}
+
+/**
+ * The transferable hover core. Indexes a compiled spec, diffs on update, and produces a
+ * `HoverState` for any cursor position. No DOM access, no framework coupling.
+ */
+export declare class HoverEngine {
+    private layerIndexes;
+    private layerRefs;
+    private aspectRatio;
+    private warmStarts;
+    private cachedState;
+    private cachedKey;
+    /**
+     * IDs of layers whose `CompiledLayer.interactive` is `false`. Recomputed on every `update()`
+     * so toggling the flag does not force an index rebuild. Used to filter the layer list before
+     * `hitTest` and `classify` see it — non-interactive layers participate in neither primary
+     * detection nor group/related, so they are visual decoration only as far as hover is concerned.
+     */
+    private nonInteractiveLayerIds;
+    constructor(spec: CompiledSpec);
+    /**
+     * Diff-aware re-index. Layers whose `data`, `geom`, `position` or the graph's coord-system
+     * reference changed are rebuilt; others are retained, including their warm-start seed. All
+     * four references live in `LayerRefSnapshot`, so `areRefsEqual` is the single source of truth
+     * for invalidation.
+     *
+     * Prev state is keyed by the stable `CompiledLayer.id` (== `LayerIndex.layerId`), not by array
+     * position, so reordering, insertion or removal of layers does not spuriously invalidate
+     * untouched layers' indexes or warm-starts.
+     */
+    update(spec: CompiledSpec): void;
+    /**
+     * Renderers call this on mount and on resize. Viewport is set-once, not per-query.
+     *
+     * On every call, viewport-dependent indexes are asked to re-prep themselves for the new
+     * viewport (`reindexPoints2DForAspect` is idempotent on aspect match, so unchanged-aspect
+     * calls are cheap). The renderer is expected to debounce resize events so the underlying
+     * Delaunay rebuild does not fire on every observed frame during a drag.
+     */
+    setViewport(viewport: HoverViewport): void;
+    /**
+     * Synchronous query. Returns the same `HoverState` reference while the primary stays on the
+     * same `(layerId, pointIndex)`, so subscribers using identity-based equality can short-circuit
+     * intra-geom cursor moves without re-rendering. Cache invalidates on `update()`. Warm-start
+     * seeds are written after every match so the next call walks a minimum number of Delaunay edges.
+     */
+    query(cursor: HoverCursor): HoverState;
+    private invalidateCache;
+}
+
+/**
+ * A single hit returned by the hover engine.
+ *
+ * `layerId` is the stable `CompiledLayer.id` — *not* an array position. The engine preserves it
+ * across `update()` calls regardless of layer reordering or insertion, so callers must resolve a
+ * layer by matching `layer.id === hit.layerId`, never by `layers[layerId]`.
+ *
+ * `pointIndex` is an opaque per-layer stable handle for the hit geom, used by the engine as a
+ * warm-start seed for subsequent queries. The encoding is per index kind:
+ * - `buckets` / `rects` / `arcs`: the dataset row inside the layer's observations.
+ * - `points`: the entry's position inside the layer's `points[]` (i.e. the Delaunay's array
+ *   index). Diverges from the dataset row when the dataset has null x/y gaps, so callers must
+ *   read `observation` rather than indexing `data` by `pointIndex`.
+ *
+ * In every case the handle is stable across `update()` calls for layers whose `data`/`geom`/
+ * `position` references were not replaced (the warm-start identity promised by the ADR), and
+ * callers that need the observation row should read `observation` — never index into the dataset
+ * by `pointIndex`.
+ */
+export declare interface HoverHit {
+    layerId: string;
+    pointIndex: number;
+    /**
+     * Normalized panel-local position. Cartesian: `[0, 1]²` in data-space (y=0 at the bottom,
+     * y=1 at the top — matching the compiler's `POSITION_VARIABLES.y`). Polar: `(angle in radians
+     * clockwise from 12 o'clock, radius in [0, 1])`.
+     */
+    x: number;
+    y: number;
+    /** The observation being hovered over. Renderers read values from here; the engine does not format. */
+    observation: Observation;
+}
+
+/** Output of `HoverEngine.query()`. */
+export declare interface HoverState {
+    primary: HoverHit | null;
+    group: HoverHit[];
+    /**
+     * Cross-layer and same-layer companion hits, bucketed by `CompiledLayer.id` so a per-layer
+     * consumer reads its own hits in O(1) (`related.get(layer.id) ?? []`) instead of filtering
+     * a flat array on every render. Layers with no companions are absent from the map — callers
+     * fall back to an empty array on miss.
+     */
+    related: ReadonlyMap<string, HoverHit[]>;
+}
+
+/** Viewport facts the engine needs for aspect-corrected hit testing. */
+export declare interface HoverViewport {
+    /** Panel width in pixels. */
+    width: number;
+    /** Pane height in pixels. */
+    height: number;
+}
+
+declare interface IdentityScaleInput {
+    type: 'scale';
+    scaledAesthetic: ScaledAestheticKey;
+    scaleType: 'identity';
+}
+
+declare type IdentityScaleOptions = Record<string, never>;
+
+declare type IdentityScaleSpec = IdentityScaleInput;
+
+declare interface InferredScaleInput {
+    type: 'scale';
+    scaledAesthetic: ScaledAestheticKey;
+    scaleType: 'inferred';
+    options?: InferredScaleOptions;
+}
+
+declare type InferredScaleOptions = ContinuousScaleOptions | DiscreteScaleOptions | DatetimeScaleOptions;
+
+/**
+ * Curve interpolation method for lines and areas.
+ *
+ * - `'linear'` — Straight segments between points
+ * - `'catmull-rom'` — Smooth spline through points
+ */
+export declare type InterpolateType = 'linear' | 'catmull-rom';
+
+/** Narrows a coord system to the cartesian variant. */
+export declare function isCartesian(coordSystem: CoordSystem): coordSystem is CartesianCoordSystem;
+
+/**
+ * Type guard that checks if a value is neither null nor undefined.
+ */
+export declare function isDefined<T>(value: T | null | undefined): value is T;
+
+/**
+ * Type guard for narrowing a `CompiledLayer` to its per-geom flavour. Use at dispatch sites that
+ * pick a renderer based on `layer.geom`:
+ *
+ *   if (isLayerOf(layer, 'line')) renderLine(layer); // layer is CompiledLayerFor<'line'>
+ */
+export declare function isLayerOf<G extends GeomName>(layer: CompiledLayer, geom: G): layer is CompiledLayerFor<G>;
+
+export declare function isStackedPosition(position: PositionType): boolean;
+
+/**
+ * Compiles each layer through the transforms → stat → group → geom → position adjusters pipeline.
+ */
+declare class LayerCompiler {
+    private readonly transformCompiler;
+    private readonly statCompiler;
+    private readonly groupCompiler;
+    private readonly geomCompiler;
+    private readonly positionAdjusterCompiler;
+    private readonly layerValidator;
+    constructor(transformCompiler: TransformCompiler, statCompiler: StatCompiler, groupCompiler: GroupCompiler, geomCompiler: GeomCompiler, positionAdjusterCompiler: PositionAdjusterCompiler, layerValidator: LayerValidator);
+    compile(input: LayerCompilerInput): CompiledLayer[];
+    /**
+     * Applies each layer's transforms once and computes its effective mapping.
+     * The resulting data is used for both validation and the stat/group/geom pipeline.
+     */
+    private prepareLayers;
+    /**
+     * Validates each layer against its post-transform dataset and effective mapping.
+     */
+    private validateLayers;
+    private compileLayer;
+}
+
+declare interface LayerCompilerInput {
+    /** The input dataset */
+    data: Dataset;
+    /** The layers to compile */
+    layers: LayerSpec[];
+    /** The effective mapping for the layers */
+    mapping: AesMapping;
+}
+
+/**
+ * Discriminated union of all layer inputs, keyed on `geom`.
+ * This is the user-facing type — fields are optional and will be resolved with defaults.
+ */
+declare type LayerInput = {
+    [G in GeomName]: LayerInputOf<G>;
+}[GeomName];
+
+declare interface LayerInputBase {
+    type: 'layer';
+    id?: string;
+    mapping?: AesMapping;
+    stat?: StatName;
+    position?: PositionType;
+    yScaleType?: YScaleType;
+    /**
+     * Ordered transforms applied to this layer's view of the data, on top of any
+     * spec-level transforms. Use this when a geom needs a different shape of the
+     * data than its siblings (e.g. a line overlay on top of reshaped stacked bars).
+     */
+    transforms?: TransformInput[];
+    /**
+     * When `false`, the layer is skipped from main hover hit-detection.
+     * @default true
+     */
+    interactive?: boolean;
+}
+
+declare type LayerInputOf<G extends GeomName> = LayerInputBase & {
+    geom: G;
+    params?: Partial<GeomParamsMap[G]>;
+};
+
+/**
+ * Discriminated union of all resolved layer specs, keyed on `geom`.
+ * All properties are fully resolved — no optionals.
+ */
+declare type LayerSpec = {
+    [G in GeomName]: LayerSpecOf<G>;
+}[GeomName];
+
+declare interface LayerSpecBase {
+    type: 'layer';
+    id: string;
+    mapping: AesMapping;
+    stat: StatName;
+    position: PositionType;
+    yScaleType: YScaleType;
+    transforms: TransformInput[];
+    interactive: boolean;
+}
+
+declare type LayerSpecOf<G extends GeomName> = LayerSpecBase & {
+    geom: G;
+    params: GeomParamsMap[G];
+};
+
+declare interface LayerValidationInput {
+    layerId: string;
+    geom: GeomName;
+    stat: StatName;
+    /** `spec.mapping` merged with `layer.mapping` */
+    effectiveMapping: AesMapping;
+    /** Layer's dataset after its own transforms have been applied */
+    data: Dataset;
+}
+
+/**
+ * Validates a single layer against a set of invariants.
+ *
+ * Checks:
+ * 1. All required aesthetics are present (accounting for stat-computed variables).
+ * 2. All mapped variables exist in the layer's dataset (after transforms).
+ *
+ * Returns issues rather than throwing. The caller (LayerCompiler) batches issues across all layers and throws
+ * a single SpecValidationError at the end.
+ */
+declare class LayerValidator {
+    private readonly geomRegistry;
+    private readonly statRegistry;
+    constructor(geomRegistry: GeomRegistry, statRegistry: StatRegistry);
+    validate(input: LayerValidationInput): ValidationIssue[];
+    /**
+     * Checks that all aesthetics required by the geom are present (accounting for stat-computed variables).
+     */
+    private validateRequiredAesthetics;
+    /**
+     * Checks that every mapped variable in the effective mapping exists in the layer's dataset (after
+     * transforms). Skips aesthetics that will be computed by stats (e.g. `y` when `stat='count'`).
+     */
+    private validateVariableExistence;
+}
+
+/** Outer padding around the whole chart, in pixels. */
+export declare const LAYOUT_PADDING = 24;
+
+/**
+ * Compiles layout geometry and final axis ticks. Output rects are in container coordinates.
+ *
+ * Horizontal axis edge height is candidate-independent (~line-height), so `panel.height` is
+ * settled after the first resolve.
+ *
+ * Here's the pipeline:
+ *   1. **Seed**: stamp each axis with a placeholder label so the grid has something to measure.
+ *   2. **Resolve v1**: first grid pass; `panel.height` is now final.
+ *   3. **Finalize vertical**: pick the densest candidate that fits `panel.height` for left/right
+ *      axes; horizontal axes keep their seed.
+ *   4. **Resolve v2**: vertical edge widths now reflect final labels, so `panel.width` is final.
+ *   5. **Finalize horizontal**: pick the densest candidate that fits `panel.width` for top/bottom
+ *      axes. Vertical axes carry over from step 3.
+ *   6. **Resolve v3**: final grid pass with all axes finalized.
+ */
+export declare class LayoutCompiler {
+    private readonly measurer;
+    constructor(measurer: LayoutMeasurer);
+    compile(input: LayoutCompilerInput): LayoutCompileResult;
+    /**
+     * Stamps each axis with a single hardcoded-label placeholder tick. This gives the grid something to measure in
+     * the first pass. The finalize pass replaces it with the real candidate selected for the resolved panel size.
+     */
+    private seedAxis;
+    private finalizeAxis;
+    private resolveLayout;
+    /**
+     * Measures all graph elements from the formatted guides.
+     * Returns three EdgeSizes records. A size of 0 means the element is absent.
+     */
+    private measureGuides;
+}
+
+/**
+ * Full output of {@link LayoutCompiler.compile} — the geometry plus the axes with their final formatted ticks.
+ */
+export declare interface LayoutCompileResult {
+    layout: GraphLayout;
+    formattedAxes: FormattedAxis[];
+}
+
+/** Input for the layout compiler. */
+export declare interface LayoutCompilerInput {
+    compiled: CompiledSpec;
+    formattedLegends: FormattedLegend[];
+    containerSize: BoxSize;
+    externalMeasurements: ExternalMeasurements;
+    formattingLocale?: Locale;
+}
+
+/** Positions where axes/labels/legends can be placed around the panel. */
+export declare type LayoutEdge = 'top' | 'right' | 'bottom' | 'left';
+
+/** Strategy for measuring chart element sizes in pixels. */
+export declare interface LayoutMeasurer {
+    /** Returns the pixel size for an axis (height for top/bottom, width for left/right). */
+    measureAxis: (axis: FormattedAxis) => number;
+    /** Returns the pixel height for an axis label row. */
+    measureAxisLabel: () => number;
+    /** Returns the pixel size for a legend (height for top/bottom, width for left/right). */
+    measureLegend: (legend: FormattedLegend) => number;
+    /** Returns the size of a single tick label. */
+    measureTickLabel: (label: string) => MeasuredText;
+}
+
+declare interface Legend {
+    position?: 'auto' | 'top' | 'right' | 'none';
+}
+
+/**
+ * Legend configuration (after defaults applied)
+ */
+declare interface LegendConfig {
+    /**
+     * Position of the legend
+     * @default 'top'
+     */
+    position: LegendPosition;
+    /**
+     * Display mode for the legend.
+     * - 'pill': Standard boxed legend with icons and labels
+     * - 'direct': Labels rendered directly next to series endpoints
+     * - 'auto': Resolved during compilation based on chart type and legend position
+     *
+     * @default 'auto'
+     */
+    display: LegendDisplay;
+}
+
+/**
+ * Legend configuration input type (all fields optional)
+ */
+declare type LegendConfigInput = Partial<LegendConfig>;
+
+/**
+ * Legend display mode type
+ * - 'pill': Standard boxed legend with icons and labels
+ * - 'direct': Labels rendered directly next to series endpoints
+ * - 'auto': Resolved during compilation based on chart type
+ */
+declare type LegendDisplay = 'pill' | 'direct' | 'auto';
+
+export declare interface LegendItem {
+    /** Raw data value (e.g., "Apples") */
+    value: DataValue;
+    /**
+     * Mapped visual values per aesthetic (e.g., { color: '#ff0000' }).
+     * An array signals multi-swatch rendering — used when a color scale is
+     * collapsed into a single legend item.
+     */
+    visual: Partial<Record<ScaledVisualAestheticKey, string | string[]>>;
+    /** Normalized y position in [0,1]. Null when display is not 'direct' or no endpoint found. */
+    normalizedY: number | null;
+}
+
+export declare type LegendPosition = 'auto' | 'right' | 'left' | 'top' | 'bottom' | 'none';
+
+declare function line(options?: GeomOptions<'line'>): LayerInputOf<'line'>;
+
+/**
+ * Line-specific parameters
+ */
+export declare interface LineGeomParams {
+    lineWidth: number | 'auto';
+    lineType: LineStyleType;
+    /**
+     * Interpolation method to use for the line.
+     * @default 'linear'
+     */
+    interpolate: InterpolateType;
+    /**
+     * How to handle missing (NULL/undefined) values.
+     * @default 'gap'
+     */
+    missingValues: MissingValuesType;
+}
+
+declare interface LineOptions {
+    isSmoothLine?: boolean;
+    lineThickness?: number | 'auto';
+    showPoints?: boolean;
+    missingValues?: 'gap' | 'connect' | 'zero';
+}
+
+/**
+ * Stroke style for line rendering.
+ *
+ * - `'solid'` — Continuous unbroken stroke
+ * - `'dashed'` — Repeating dash pattern
+ * - `'dotted'` — Repeating dot pattern
+ */
+export declare type LineStyleType = 'solid' | 'dashed' | 'dotted';
+
+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"];
+
+/** The data-space axis a `CartesianCoordSystem` uses as the main (independent) axis. */
+export declare type MainAxis = 'x' | 'y';
+
+/**
+ * Create a pipeable mapping spec item.
+ *
+ * @example
+ * createSpec(
+ *   data,
+ *   transform.reshape({ reshape: ['revenue'], keyName: 'metric', valueName: 'amount' }),
+ *   mapping({ x: 'month', y: 'amount', color: 'metric' }),
+ *   geom.bar(),
+ * )
+ */
+export declare function mapping(aes: AesMapping): MappingItem;
+
+/**
+ * A pipeable spec item that sets/merges the global aesthetic mapping.
+ */
+declare interface MappingItem {
+    type: 'mapping';
+    mapping: AesMapping;
+}
+
+export declare interface MeasuredText {
+    width: number;
+    height: number;
+    ascent: number;
+    descent: number;
+}
+
+/**
+ * Strategy for handling null/undefined values in lines and areas.
+ *
+ * - `'zero'` — Replace missing values with zero
+ * - `'gap'` — Leave a visible gap where values are missing
+ * - `'connect'` — Skip missing values and connect adjacent valid points
+ */
+export declare type MissingValuesType = 'zero' | 'gap' | 'connect';
+
+/**
+ * Named font weights mapped to their numeric values.
+ *
+ * See: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-weight#common_weight_name_mapping
+ */
+declare const NAMED_WEIGHTS: {
+    readonly thin: 100;
+    readonly hairline: 100;
+    readonly extraLight: 200;
+    readonly ultraLight: 200;
+    readonly light: 300;
+    readonly normal: 400;
+    readonly regular: 400;
+    readonly medium: 500;
+    readonly semiBold: 600;
+    readonly demiBold: 600;
+    readonly bold: 700;
+    readonly extraBold: 800;
+    readonly ultraBold: 800;
+    readonly black: 900;
+    readonly heavy: 900;
+    readonly extraBlack: 950;
+    readonly ultraBlack: 950;
+};
+
+declare type NamedWeightKey = keyof typeof NAMED_WEIGHTS;
+
+/**
+ * Configuration for formatting a single number.
+ * Defines how numeric values should be displayed in the chart.
+ */
+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)
+     */
+    decimals: number | 'auto';
+    /**
+     * Abbreviation style for large numbers.
+     * - 'none': No abbreviation (1234567 → "1,234,567")
+     * - 'auto': Automatic based on magnitude (1234567 → "1.2M")
+     * - 'k': Force thousands (1234567 → "1,234.6K")
+     * - 'm': Force millions (1234567 → "1.2M")
+     * - 'b': Force billions (1234567890 → "1.2B")
+     */
+    abbreviation: 'auto' | 'k' | 'm' | 'b' | 'none';
+    /**
+     * Thousands separator character.
+     * Default: ',' (US) or locale-aware if locale is set
+     */
+    thousandsSeparator?: string;
+    /**
+     * Decimal separator character.
+     * Default: '.' (US) or locale-aware if locale is set
+     */
+    decimalSeparator?: string;
+    /**
+     * Prefix to prepend (e.g., '$', '€').
+     */
+    prefix?: string;
+    /**
+     * Suffix to append (e.g., '%', ' units').
+     */
+    suffix?: string;
+}
+
+declare type NumericDataValue = number | null;
+
+declare interface NumericValueFormat {
+    type: 'decimal' | 'integer' | 'percentage' | 'duration';
+}
+
+/** A single row of data, mapping every variable name to the value in that row. */
+export declare type Observation = Record<VariableName, DataValue>;
+
+declare type Options = Partial<LineOptions & BarOptions & ScatterOptions & ComboOptions & PieOptions & TableOptions>;
+
+/**
+ * A named store for color palettes used by scale compilation.
+ *
+ * Each palette is registered under a unique string key and maps to an ordered
+ * array of color strings (e.g. hex values). The registry is consumed during
+ * scale resolution to look up the concrete colors for a given palette name.
+ *
+ * Inherits `register`, `get`, `has`, and `getAll` from {@link Registry}.
+ * Calling `get` with an unregistered name throws with a descriptive error
+ * listing available palettes.
+ *
+ * @example
+ * ```ts
+ * const palettes = new PaletteRegistry();
+ * palettes.register('brand', ['#1a1a2e', '#16213e', '#0f3460']);
+ *
+ * palettes.has('brand');  // true
+ * palettes.get('brand');  // ['#1a1a2e', '#16213e', '#0f3460']
+ * palettes.get('unknown'); // throws Error: Unknown palette: 'unknown'
+ * ```
+ */
+declare class PaletteRegistry extends Registry<string, string[]> {
+    constructor();
+}
+
+declare interface PaletteScaleInput {
+    type: 'scale';
+    scaledAesthetic: ScaledAestheticKey;
+    scaleType: 'palette';
+    palette?: string | null;
+}
+
+declare interface PaletteScaleOptions {
+    /** Graphy palette name. Defaults to the first registered palette. */
+    palette?: string | null;
+}
+
+declare type PaletteScaleSpec = Required<PaletteScaleInput> & {
+    palette: string;
+};
+
+/**
+ * Panel configuration
+ */
+declare interface PanelConfig {
+    border: {
+        isVisible: boolean;
+    };
+}
+
+declare interface PieOptions {
+    pieTotalPosition?: 'center' | 'outside';
+}
+
+/**
+ * Pipe a spec through a series of spec items (left-to-right).
+ */
+export declare function pipe(spec: SpecInput, ...items: SpecItem[]): SpecInput;
+
+declare function point(options?: GeomOptions<'point'>): LayerInputOf<'point'>;
+
+/**
+ * Point-specific parameters
+ */
+declare interface PointGeomParams {
+    size: number;
+}
+
+declare interface PolarCoordInput {
+    type: 'coord';
+    coordType: 'polar';
+    params?: Partial<PolarCoordParams>;
+}
+
+/**
+ * Params for polar coordinate system
+ */
+declare interface PolarCoordParams extends BaseCoordParams {
+    /**
+     * Which aesthetic maps to theta (angle): 'x' or 'y'
+     */
+    theta: 'x' | 'y';
+    /**
+     * Starting angle in degrees
+     */
+    startAngle: number;
+    /**
+     * Inner radius as fraction 0-1 (for donut charts)
+     */
+    innerRadius: number;
+}
+
+declare interface PolarCoordSpec {
+    type: 'coord';
+    coordType: 'polar';
+    params: PolarCoordParams;
+}
+
+/**
+ * Polar coordinate system - for pie charts, radar charts, etc.
+ * Projection params (theta, startAngle, innerRadius) are consumed by the compiler
+ * during coordTransform — the renderer only needs this for dispatch (drawing strategy, axes).
+ */
+export declare interface PolarCoordSystem {
+    type: 'polar';
+    /** Axis orientation metadata for the guide compiler */
+    axisMapping: AxisMapping;
+}
+
+export declare const POSITION_VARIABLES: {
+    readonly x: string;
+    readonly y: string;
+    readonly xMin: string;
+    readonly xMax: string;
+    readonly yMin: string;
+    readonly yMax: string;
+};
+
+/**
+ * Base class for position adjustments that modify mark placement (e.g. stacking, dodging, jittering).
+ */
+declare abstract class PositionAdjuster {
+    abstract readonly type: PositionType;
+    abstract adjust(input: PositionAdjusterCompilerInput): CompiledPositionAdjuster;
+}
+
+/**
+ * Resolves a position adjustment by name and delegates to the appropriate implementation.
+ */
+declare class PositionAdjusterCompiler {
+    private readonly registry;
+    constructor(registry: PositionAdjusterRegistry);
+    adjust(positionName: PositionType, input: PositionAdjusterCompilerInput): CompiledPositionAdjuster;
+}
+
+declare interface PositionAdjusterCompilerInput {
+    /** The dataset after stat and geom transformations */
+    data: Dataset;
+    /** The effective mapping for the layer */
+    mapping: AesMapping;
+}
+
+/**
+ * Built-in position adjustments keyed by {@link PositionType}.
+ */
+declare class PositionAdjusterRegistry extends Registry<PositionType, PositionAdjuster> {
+    constructor();
+}
+
+declare interface PositionalScaleMethods {
+    /**
+     * Continuous (numeric) scale. Supports `transform`, `reverse`, `nice`, `zero`, `domainMin`, `domainMax`.
+     * @example scale.x.continuous({ domainMin: 0, nice: true })
+     */
+    continuous: (options?: ContinuousScaleOptions) => ContinuousScaleInput;
+    /**
+     * Discrete (categorical) scale. Supports explicit `range` values.
+     * @example scale.x.discrete({ range: ['A', 'B', 'C'] })
+     */
+    discrete: (options?: DiscreteScaleOptions) => DiscreteScaleInput;
+    /**
+     * Datetime (temporal) scale. Supports `domainMin` / `domainMax` in epoch ms.
+     * @example scale.x.datetime({ domainMin: Date.parse('2020-01-01') })
+     */
+    datetime: (options?: DatetimeScaleOptions) => DatetimeScaleInput;
+    /**
+     * Continuous scale with base-10 logarithmic transformation.
+     * @example scale.y.log({ domainMin: 1 })
+     */
+    log: (options?: ContinuousScaleOptions) => ContinuousScaleInput;
+    /**
+     * Continuous scale with square-root transformation.
+     * @example scale.y.sqrt({ nice: true })
+     */
+    sqrt: (options?: ContinuousScaleOptions) => ContinuousScaleInput;
+}
+
+/**
+ * A position variable mapper that applies position scaling for a single concern
+ * (e.g. primary x, band extents, y baseline extents).
+ *
+ * Returns the dataset with any new positional variables added,
+ * or the same dataset unchanged if this mapper does not apply.
+ */
+declare interface PositionMapper {
+    map: (input: PositionMapperInput) => Dataset;
+}
+
+/**
+ * Applies position scales to raw data values, producing scale-normalized
+ * `x` and `y` variables ([0,1]) on each layer's dataset.
+ *
+ * Delegates to an ordered list of {@link PositionMapper} handlers,
+ * each responsible for one position concern.
+ */
+declare class PositionMapperCompiler {
+    private readonly mappers;
+    constructor(mappers?: PositionMapper[]);
+    compile(input: PositionMapperCompilerInput): CompiledLayer[];
+    private compileLayer;
+}
+
+declare interface PositionMapperCompilerInput {
+    layers: CompiledLayer[];
+    scales: CompiledScales;
+}
+
+/**
+ * Context passed to each column mapper during position mapping.
+ */
+declare interface PositionMapperInput {
+    data: Dataset;
+    layer: CompiledLayer;
+    getPositionScale: (scaleAestheticKey: ScaledAestheticKey) => CompiledPositionScale | null;
+}
+
+/**
+ * Position adjustment for overlapping geometries.
+ *
+ * - `'stack'` — Stack geometries on top of each other (e.g. stacked bar chart)
+ * - `'dodge'` — Place geometries side by side (e.g. grouped bar chart)
+ * - `'identity'` — No adjustment, use raw positions (e.g. scatter plot, allows overlapping)
+ * - `'fill'` — Normalize stacks to fill 100% of the axis (e.g. 100% stacked bar chart)
+ */
+export declare type PositionType = 'stack' | 'dodge' | 'identity' | 'fill';
+
+export declare const prefixInternalVariable: (name: string) => string;
+
+declare interface QuantitativeScaleMethods {
+    /**
+     * Continuous (numeric) scale. Supports `transform`, `reverse`, `nice`, `zero`, `domainMin`, `domainMax`.
+     * @example scale.size.continuous({ domainMin: 0 })
+     */
+    continuous: (options?: ContinuousScaleOptions) => ContinuousScaleInput;
+    /**
+     * Discrete (categorical) scale. Supports explicit `range` values.
+     * @example scale.size.discrete({ range: [4, 8, 12] })
+     */
+    discrete: (options?: DiscreteScaleOptions) => DiscreteScaleInput;
+    /**
+     * Identity scale — data values used directly as visual values without transformation.
+     * @example scale.size.identity() // { size: 10 } → 10px
+     */
+    identity: (options?: IdentityScaleOptions) => IdentityScaleInput;
+}
+
+export declare interface RadiusExtent {
+    innerRadius: NumericDataValue;
+    outerRadius: NumericDataValue;
+}
+
+/** A rectangle in pixel coordinates, origin at top-left. */
+export declare interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+declare interface ReferenceLines {
+    goalLine?: GoalLine;
+    trendline?: TrendlineType;
+    averageLine?: AverageLine;
+}
+
+/**
+ * A typed key-value store for looking up registered implementations by name.
+ *
+ * Used by the compiler to map type names (e.g. `'bar'`, `'stack'`) to
+ * their corresponding implementations (e.g. `BarGeom`, `StackPosition`).
+ *
+ * @typeParam K - The key type (typically a string union like `GeomName`).
+ * @typeParam T - The implementation type (e.g. `Geom`, `Stat`).
+ */
+declare class Registry<K extends string, T> {
+    private label;
+    private items;
+    constructor(label: string);
+    /**
+     * Add an implementation under the given key.
+     */
+    register(key: K, value: T): this;
+    /**
+     * Retrieve an implementation by key. Throws if not registered.
+     */
+    get(key: K): T;
+    getAll(): T[];
+    /**
+     * Check whether a key has been registered.
+     */
+    has(key: K): boolean;
+}
+
+/***************************************************************
+ * Builders
+ ***************************************************************/
+declare function reshape(options?: ReshapeOptions): ReshapeTransformInput;
+
+/***************************************************************
+ * Reshape Transform
+ ***************************************************************/
+declare interface ReshapeOptions {
+    /**
+     * Numeric variables to collapse into rows.
+     * Defaults to all numeric variables
+     * */
+    reshape?: VariableName[];
+    /**
+     * Variables to carry through unchanged.
+     * Defaults to all categorical/temporal variables
+     * */
+    keep?: VariableName[];
+    /**
+     * Name of the output column containing the original variable names.
+     * @default 'key'
+     * */
+    keyName?: VariableName;
+    /**
+     * Name of the output column containing the original values.
+     * @default 'value'
+     * */
+    valueName?: VariableName;
+}
+
+declare interface ReshapeTransformInput {
+    type: 'transform';
+    transformType: 'reshape';
+    options: ReshapeOptions;
+}
+
+/**
+ * Concrete legend display after 'auto' has been resolved.
+ * - 'auto' is resolved based on legend position and geom characteristics
+ */
+export declare type ResolvedLegendDisplay = Exclude<LegendDisplay, 'auto'>;
+
+/**
+ * Discrete legend — one entry per domain value.
+ * Produced from discrete and palette scales.
+ */
+/**
+ * Concrete legend position after 'auto' and 'none' have been resolved.
+ * - 'none' is handled upstream (compileLegends returns [] when position is 'none')
+ * - 'auto' is resolved to a concrete position by resolveLegendPosition
+ */
+export declare type ResolvedLegendPosition = Exclude<LegendPosition, 'auto' | 'none'>;
+
+/**
+ * Canonical resting `HoverState`. Exported so the renderer-side store can reuse this exact
+ * reference instead of maintaining a parallel literal that could drift.
+ */
+export declare const RESTING_HOVER_STATE: HoverState;
+
+/** TipTap-compatible rich text node (no tiptap dependency). */
+export declare interface RichTextContent {
+    type: string;
+    content?: RichTextContent[];
+    text?: string;
+    marks?: Array<{
+        type: string;
+        attrs?: Record<string, unknown>;
+    }>;
+    attrs?: Record<string, unknown>;
+}
+
+declare abstract class Scale {
+    /** Data types this scale accepts. */
+    abstract readonly compatibleDataTypes: readonly DataType[];
+    protected createPositionScale<Input extends DataValue = DataValue>(spec: ScaleSpec, options: CompiledPositionScaleOptions<Input>): CompiledScale;
+    protected createVisualScale<Input extends DataValue = DataValue>(spec: ScaleSpec, options: CompiledVisualScaleOptions<Input>): CompiledScale;
+    abstract compile(spec: ScaleSpec, values: DataValue[]): CompiledScale;
+}
+
+export declare const scale: ScaleAPI;
+
+declare interface ScaleAPI {
+    /**
+     * X-axis scale. Callable for inferred (auto-detects type from data), or use explicit methods.
+     * @example scale.x() // inferred
+     * @example scale.x({ nice: true }) // inferred with options
+     * @example scale.x.continuous({ domainMin: 0 })
+     * @example scale.x.log()
+     */
+    x: ((options?: InferredScaleOptions) => InferredScaleInput) & PositionalScaleMethods;
+    /**
+     * Y-axis scale. Callable for inferred (auto-detects type from data), or use explicit methods.
+     * @example scale.y() // inferred
+     * @example scale.y.continuous({ zero: true, nice: true })
+     * @example scale.y.log({ reverse: true })
+     */
+    y: ((options?: InferredScaleOptions) => InferredScaleInput) & PositionalScaleMethods;
+    /**
+     * Secondary Y-axis scale. Independent position scale rendered on the opposite axis.
+     * Callable for inferred (auto-detects type from data), or use explicit methods.
+     * @example scale.ySecondary() // inferred
+     * @example scale.ySecondary.continuous({ nice: true })
+     */
+    ySecondary: ((options?: InferredScaleOptions) => InferredScaleInput) & PositionalScaleMethods;
+    /**
+     * Color scale. Use `.continuous()`, `.discrete()`, or `.palette()`.
+     * @example scale.color.palette({ palette: 'Bright' })
+     * @example scale.color.discrete({ range: ['red', 'blue'] })
+     */
+    color: ColorScaleMethods;
+    /**
+     * Size scale. Use `.continuous()`, `.discrete()`, or `.identity()`.
+     * Defaults to sqrt transform for area-proportional encoding.
+     * @example scale.size.continuous({ range: [2, 30] })
+     * @example scale.size.identity() // use data values directly as px
+     */
+    size: QuantitativeScaleMethods;
+    /**
+     * Alpha (opacity) scale. Use `.continuous()`, `.discrete()`, or `.identity()`.
+     * @example scale.alpha.continuous({ range: [0.2, 0.9] })
+     * @example scale.alpha.identity() // use data values directly as opacity
+     */
+    alpha: QuantitativeScaleMethods;
+    /**
+     * Stroke width scale. Use `.continuous()`, `.discrete()`, or `.identity()`.
+     * @example scale.strokeWidth.continuous({ range: [1, 6] })
+     * @example scale.strokeWidth.identity() // use data values directly as px
+     */
+    strokeWidth: QuantitativeScaleMethods;
+}
+
+/**
+ * Compiles scale specs into render-ready CompiledScale objects.
+ */
+declare class ScaleCompiler {
+    private readonly registry;
+    constructor(registry: ScaleRegistry);
+    compile(input: ScaleCompilerInput): CompiledScales;
+    /**
+     * Pre-pass: each scale's source variable must have a data type the scale can handle.
+     */
+    private validateScaleTypeCompatibility;
+    /**
+     * Walk all layers' mappings and collect data values per scale aesthetic key.
+     *
+     * For layers with `yScaleType: 'secondary'`, the `y` aesthetic values are
+     * collected under the `ySecondary` scale aesthetic key instead of `y`.
+     *
+     * When a position adjuster (e.g. fill/stack) has written `yMin`/`yMax` columns,
+     * those values are collected instead of the raw `y` mapping. This ensures the
+     * y scale domain reflects the position-adjusted range (e.g. [0, 1] after fill).
+     */
+    private collectValues;
+    /**
+     * Determines which dataset variables to collect for a given aesthetic.
+     *
+     * For `y`, if position adjusters have written `yMin`/`yMax`, those columns
+     * are returned instead of the raw mapping variable so the scale domain
+     * reflects the adjusted range.
+     */
+    private resolveVariables;
+    private hasPositionAdjustedY;
+    private collectFromVariables;
+}
+
+declare interface ScaleCompilerInput {
+    layers: CompiledLayer[];
+    scales: ScaleSpec[];
+}
+
+/**
+ * Identifiers for scales. Superset of AestheticKey — includes `ySecondary`
+ * which is a scale aesthetic key but NOT an aesthetic (layers still map to `y`).
+ */
+export declare type ScaledAestheticKey = ScaledPositionAestheticKey | ScaledVisualAestheticKey;
+
+declare type ScaledPositionAestheticKey = 'x' | 'y' | 'ySecondary';
+
+declare type ScaledVisualAestheticKey = 'color' | 'size' | 'alpha' | 'strokeWidth';
+
+/**
+ * Union type for all possible scale specifications (including inferred, pre-resolution).
+ */
+declare type ScaleInput = ContinuousScaleInput | DiscreteScaleInput | PaletteScaleInput | DatetimeScaleInput | IdentityScaleInput | InferredScaleInput;
+
+declare class ScaleRegistry extends Registry<ScaleType, Scale> {
+    private readonly paletteRegistry;
+    constructor(paletteRegistry: PaletteRegistry);
+}
+
+/**
+ * Union of scale specs that can appear after resolution (all fields required).
+ * InferredScaleInput is resolved to a concrete type during spec resolution.
+ */
+declare type ScaleSpec = ContinuousScaleSpec | DiscreteScaleSpec | DatetimeScaleSpec | IdentityScaleSpec | PaletteScaleSpec;
+
+/**
+ * Mathematical transformation for continuous scales.
+ *
+ * - `'linear'` — No transformation applied
+ * - `'log'` — Base-10 logarithmic scale
+ * - `'sqrt'` — Square root scale
+ */
+declare type ScaleTransformType = 'linear' | 'log' | 'sqrt';
+
+/**
+ * Scale mapping type that defines how data values map to visual properties.
+ *
+ * - `'continuous'` — Continuous numeric range (e.g., min to max)
+ * - `'discrete'` — Discrete categorical values
+ * - `'datetime'` — Date/time range
+ * - `'identity'` — Pass-through, values used as-is
+ */
+declare type ScaleType = 'continuous' | 'discrete' | 'datetime' | 'identity' | 'palette';
+
+declare interface ScatterOptions {
+    pointSize?: number | 'auto';
+}
+
+/**
+ * Serialized representation of a command for wire transport and persistence.
+ * Only forward commands are serialized — inverses are recomputed at execution time.
+ */
+export declare interface SerializedCommand {
+    readonly type: string;
+    readonly params: Record<string, unknown>;
+    readonly metadata: CommandMetadata;
+}
+
+/** Config for styling a specific series. */
+declare interface SeriesStyle {
+    paletteColorId?: string;
+    customColor?: string;
+    fillStyle?: 'solid' | 'hatched';
+    lineStyle?: 'solid' | 'dashed' | 'dotted';
+}
+
+/**
+ * Sets the chart background color.
+ * When set to null, the renderer falls back to its theme default.
+ */
+export declare class SetAppearanceBackgroundCommand implements Command<SetAppearanceBackgroundParams> {
+    readonly type: "set-appearance-background";
+    readonly metadata: CommandMetadata;
+    readonly params: SetAppearanceBackgroundParams;
+    constructor(params: SetAppearanceBackgroundParams, metadata?: Partial<CommandMetadata>);
+    apply(spec: Spec): CommandApplyResult | null;
+}
+
+export declare type SetAppearanceBackgroundParams = {
+    background: string | null;
+};
+
+/**
+ * Toggles visibility of the chart's textual content (title, subtitle, caption) as a group.
+ * Underlying text values are preserved so toggling back restores them.
+ */
+export declare class SetContentVisibilityCommand implements Command<SetContentVisibilityParams> {
+    readonly type: "set-content-visibility";
+    readonly metadata: CommandMetadata;
+    readonly params: SetContentVisibilityParams;
+    constructor(params: SetContentVisibilityParams, metadata?: Partial<CommandMetadata>);
+    apply(spec: Spec): CommandApplyResult | null;
+}
+
+export declare type SetContentVisibilityParams = {
+    isVisible: boolean;
+};
+
+/**
+ * Command that swaps the dataset on a spec while preserving layer identity and all other
+ * configuration. Enables data-change transitions — existing layer ids are retained, so
+ * renderers using id-based keys can morph geoms instead of unmounting them.
+ *
+ * Accepts either raw `Data` (parsed on apply) or a pre-parsed `Dataset` (used by the revert
+ * command). Revert commands are not serialized, so carrying a `Dataset` is safe.
+ */
+export declare class SetDataCommand implements Command<SetDataParams> {
+    readonly type: "set-data";
+    readonly metadata: CommandMetadata;
+    readonly params: SetDataParams;
+    constructor(params: SetDataParams, metadata?: Partial<CommandMetadata>);
+    apply(spec: Spec): CommandApplyResult | null;
+}
+
+export declare type SetDataParams = {
+    /** Raw data (will be parsed) or a pre-parsed `Dataset` (used for reverts). */
+    data: Data | Dataset;
+};
+
+/**
+ * Controls grid line visibility for both axes simultaneously.
+ * Takes independent x/y visibility flags to allow per-axis grid control and proper revert support.
+ */
+export declare class SetGridVisibilityCommand implements Command<SetGridVisibilityParams> {
+    readonly type: "set-grid-visibility";
+    readonly metadata: CommandMetadata;
+    readonly params: SetGridVisibilityParams;
+    constructor(params: SetGridVisibilityParams, metadata?: Partial<CommandMetadata>);
+    apply(spec: Spec): CommandApplyResult | null;
+}
+
+export declare type SetGridVisibilityParams = {
+    xIsVisible: boolean | null;
+    yIsVisible: boolean | null;
+};
+
+/**
+ * Sets the legend placement relative to the chart (e.g. auto, top, bottom, left, right, none).
+ * 'auto' lets the renderer choose the best position; 'none' hides the legend entirely.
+ */
+export declare class SetLegendPositionCommand implements Command<SetLegendPositionParams> {
+    readonly type: "set-legend-position";
+    readonly metadata: CommandMetadata;
+    readonly params: SetLegendPositionParams;
+    constructor(params: SetLegendPositionParams, metadata?: Partial<CommandMetadata>);
+    apply(spec: Spec): CommandApplyResult | null;
+}
+
+export declare type SetLegendPositionParams = {
+    position: LegendPosition;
+};
+
+declare function sort(options: SortOptions): SortTransformInput;
+
+/***************************************************************
+ * Sort Transform
+ ***************************************************************/
+declare interface SortOptions {
+    /** The variable to sort by. */
+    variableName: VariableName;
+    /** Sort direction. @default 'asc' */
+    direction?: 'asc' | 'desc';
+}
+
+declare interface SortTransformInput {
+    type: 'transform';
+    transformType: 'sort';
+    options: SortOptions;
+}
+
+/**
+ * Fully resolved spec — all fields populated, defaults applied, inferred types resolved.
+ * This is what the compilation pipeline consumes.
+ *
+ * @example
+ * ```ts
+ * const spec = pipe(
+ *   createSpec(data, { x: 'date', y: 'revenue', color: 'region' }),
+ *   geom.bar(),
+ * );
+ * const resolved = resolveSpec(spec);
+ *
+ * // resolved.layers   → at least one layer with resolved geom params, stat, and position
+ * // resolved.scales   → concrete scale types (no 'inferred'), all defaults filled
+ * // resolved.coords   → coordinate system with fully defaulted params
+ * // resolved.config   → axes, legend, headline, panel, numberFormat with defaults
+ * ```
+ */
+export declare interface Spec {
+    /** The dataset backing the visualization. */
+    data: Dataset;
+    /** Per-column metadata captured at parse time (inferred value formats). Used by guide compilation to format tick and legend labels. */
+    datasetMetadata: DatasetMetadata;
+    /** Global aesthetic mappings (data columns → visual channels). */
+    mapping: AesMapping;
+    /** Geometry layers to render. Each layer has resolved geom, stat, position, and params. */
+    layers: LayerSpec[];
+    /** Resolved scale specs — one per aesthetic, all defaults filled, no 'inferred' types remaining. */
+    scales: ScaleSpec[];
+    /** Data transforms applied to `data` before layer compilation. */
+    transforms: TransformInput[];
+    /** Coordinate system (cartesian, flip, or polar) with fully defaulted params. */
+    coords: CoordSpec;
+    /** Chart configuration: axes, legend, headline, panel, number formatting. */
+    config: ConfigSpec;
+}
+
+/**
+ * The canonical spec type — plain JSON, serializable.
+ * This is what commands operate on and what gets stored in undo/redo snapshots.
+ */
+export declare interface SpecInput {
+    data: Data;
+    mapping: AesMapping;
+    layers: LayerInput[];
+    scales: ScaleInput[];
+    transforms: TransformInput[];
+    coords?: CoordInput;
+    config: ConfigInput;
+}
+
+declare type SpecItem = LayerInput | ScaleInput | CoordInput | ConfigItem | TransformInput | MappingItem;
+
+/**
+ * Compiles a raw compiler input or graph config into a resolved Spec.
+ */
+export declare class SpecResolver {
+    compile(compilerInput: SpecInput | GraphConfig): Spec;
+    resolveFromInput(input: SpecInput | GraphConfig, dataset: Dataset, datasetMetadata: DatasetMetadata): Spec;
+}
+
+/**
+ * Base class for statistical transformations applied to layer data (e.g. binning, counting, smoothing).
+ */
+declare abstract class Stat {
+    abstract readonly type: StatName;
+    /**
+     * Aesthetics this stat will compute (e.g. count computes 'y'). Used by validation to skip existence checks.
+     */
+    abstract readonly computedVariables: ReadonlySet<AestheticKey>;
+    compute(input: StatCompilerInput): CompiledStat;
+    protected abstract computeStat(input: StatCompilerInput): CompiledStat;
+}
+
+/**
+ * Resolves a stat by name and delegates computation.
+ */
+declare class StatCompiler {
+    private readonly registry;
+    constructor(registry: StatRegistry);
+    compute(statName: StatName, input: StatCompilerInput): CompiledStat;
+}
+
+declare interface StatCompilerInput {
+    /** The input dataset */
+    data: Dataset;
+    /** The effective mapping for the layer */
+    mapping: AesMapping;
+}
+
+/**
+ * Statistical transformation applied to data before rendering.
+ *
+ * - `'identity'` — No transformation, data passed through unchanged
+ * - `'count'` — Count the number of observations per x-axis value
+ */
+declare type StatName = 'identity' | 'count';
+
+/**
+ * Built-in stat implementations keyed by {@link StatName}.
+ */
+declare class StatRegistry extends Registry<StatName, Stat> {
+    constructor();
+}
+
+/**
+ * Visual signature of the source geom.
+ */
+export declare type SwatchShape = 'square' | 'line' | 'circle' | 'area' | 'slice';
+
+declare type Table = internal.ColumnTable;
+
+declare interface TableOptions {
+    tableColumnRatios?: Record<string, number>;
+}
+
+declare interface TemporalValueFormat {
+    type: 'datetime' | 'time' | 'date' | 'year' | 'quarter' | 'month_year' | 'month' | 'weekly_date_range_with_year' | 'weekly_date_range' | 'day_month';
+    /** Template string representing how values of this type have been formatted. ie. dd-mm-yyyy  */
+    dateFormat?: string;
+}
+
+/** A text value — plain string or structured rich text. */
+export declare type TextContent = string | RichTextContent;
+
+export declare interface TextMeasurer {
+    measureText: (text: string, font: FontSpec) => MeasuredText;
+}
+
+/** Fully-derived tooltip content. The popover renders directly from this. */
+export declare interface TooltipContent {
+    /** Formatted main-axis value of the primary's observation. `null` for polar. */
+    header: string | null;
+    rows: TooltipRow[];
+}
+
+/**
+ * One row in the chart tooltip popover. Pure projection of a `HoverHit` against the layer's
+ * compiled scales.
+ */
+export declare interface TooltipRow {
+    /**
+     * Resolved color string applied as the row's swatch fill/stroke. `null` only when the chart
+     * has no color scale at all — the popover suppresses the swatch cell in that edge case.
+     */
+    swatchColor: string | null;
+    /** Visual signature of the row's source geom. Drives the swatch shape. */
+    swatchShape: SwatchShape;
+    /** Row label — color value (multi-series) or layer's Y-axis title (single-series). */
+    label: string;
+    /** Formatted Y reading for this hit. */
+    value: string;
+    /** Styling hint: the row whose hit `=== primary`. Never re-orders. */
+    isPrimary: boolean;
+    /** Stable key — `${layerId}:${pointIndex}`. */
+    key: string;
+}
+
+export declare const transform: {
+    reshape: typeof reshape;
+    filter: typeof filter;
+    sort: typeof sort;
+    aggregate: typeof aggregate;
+    constant: typeof constant;
+};
+
+/**
+ * Applies spec-level transforms to a dataset by delegating to registered strategies.
+ */
+declare class TransformCompiler {
+    private readonly registry;
+    constructor(registry: TransformRegistry);
+    compile(data: Dataset, transforms: TransformInput[]): Dataset;
+}
+
+/***************************************************************
+ * Transform Input
+ ***************************************************************/
+declare type TransformInput = ReshapeTransformInput | FilterTransformInput | SortTransformInput | AggregateTransformInput | ConstantTransformInput;
+
+/**
+ * Built-in transform implementations keyed by transform type.
+ */
+declare class TransformRegistry extends Registry<TransformType, TransformStrategy> {
+    constructor();
+}
+
+/**
+ * Strategy interface for compiling a specific transform type.
+ */
+declare interface TransformStrategy {
+    readonly transformType: TransformType;
+    apply: (data: Dataset, transform: TransformInput) => Dataset;
+}
+
+declare type TransformType = TransformInput['transformType'];
+
+declare type TrendlineType = 'linear' | 'loess' | 'exponential' | 'logarithmic' | 'quadratic' | 'power' | 'polynomial';
+
+/**
+ * Result of an undo/redo operation.
+ */
+declare interface UndoRedoResult {
+    /** The new spec after the operation */
+    spec: Spec;
+    /** The original command that was undone/redone */
+    command: Command;
+}
+
+/**
+ * Shared validation types used across compiler stages.
+ *
+ * Each validation stage (e.g. {@link LayerValidator}, the pre-pass in {@link ScaleCompiler}) collects
+ * {@link ValidationIssue}s and throws a single {@link SpecValidationError} at the end of its stage.
+ */
+declare type ValidationCode = 'UNKNOWN_VARIABLE' | 'INCOMPATIBLE_TYPE' | 'MISSING_AESTHETIC';
+
+declare interface ValidationIssue {
+    code: ValidationCode;
+    message: string;
+    layerId?: string;
+    aesthetic?: string;
+}
+
+declare type ValueFormat = TemporalValueFormat | NumericValueFormat | CurrencyValueFormat | CategoricalValueFormat;
+
+/**
+ * Constant mapping - a literal value applied to every observation.
+ * Analogous to Vega-Lite's `{datum: X}` / ggplot2's `aes(color = "literal")`.
+ */
+declare interface ValueMapping {
+    value: DataValue;
+}
+
+/** A column of a variable in the dataset. */
+declare type Variable = {
+    type: DataType;
+    values: DataValue[];
+};
+
+/** A map of variable names to their type and values. */
+declare type VariableMap = Record<VariableName, Variable>;
+
+/**
+ * Variable mapping - references a column in the data
+ */
+declare interface VariableMapping {
+    variable: string;
+}
+
+declare type VariableMetadata = Record<VariableName, {
+    type: DataType;
+}>;
+
+/** A type alias for variable names. */
+export declare type VariableName = string;
+
+export declare const VISUAL_VARIABLES: {
+    readonly color: string;
+    readonly size: string;
+    readonly alpha: string;
+    readonly strokeWidth: string;
+};
+
+/**
+ * Applies visual scales to raw data values, producing render-ready variables (e.g. `color`, `size`, `alpha`,
+ * `strokeWidth`) on each layer's dataset.
+ */
+declare class VisualMapperCompiler {
+    compile(input: VisualMapperCompilerInput): CompiledLayer[];
+    private compileLayer;
+}
+
+declare interface VisualMapperCompilerInput {
+    layers: CompiledLayer[];
+    scales: CompiledScales;
+}
+
+/**
+ * X-axis configuration (after defaults applied)
+ */
+declare interface XAxisConfig {
+    /**
+     * Whether the x axis is visible.
+     * @default true
+     */
+    isVisible: boolean;
+    /**
+     * Axis title text. null means explicitly no label.
+     * @default null
+     */
+    label: string | null;
+    /**
+     * Position of the y axis.
+     * @default 'bottom'
+     */
+    position: AxisPosition;
+    /** Grid lines for this axis */
+    grid: AxisGridConfig;
+    /** Tick marks for this axis */
+    ticks: AxisTicksConfig;
+}
+
+/** Minimal x/y shape — most runtime records satisfy this (HoverCursor, HoverHit, etc.). */
+export declare interface XYPoint {
+    x: number;
+    y: number;
+}
+
+/**
+ * Y-axis configuration (after defaults applied)
+ */
+declare interface YAxisConfig {
+    /**
+     * Whether the y axis is visible.
+     * @default true
+     */
+    isVisible: boolean;
+    /**
+     * Axis title text. null means explicitly no label.
+     * @default null
+     */
+    label: string | null;
+    /**
+     * Position of the y axis.
+     * @default 'right'
+     */
+    position: AxisPosition;
+    /** Grid lines for this axis */
+    grid: AxisGridConfig;
+    /** Tick marks for this axis */
+    ticks: AxisTicksConfig;
+}
+
+/**
+ * Which Y axis a layer binds to.
+ */
+export declare type YScaleType = 'primary' | 'secondary';
+
+export { }