@graphysdk/viz-engine 0.0.1-plugins.9 → 1.8.1-beta.1786024899180

package/dist/graph-config.d.ts

@@ -0,0 +1,2569 @@
+/**
+ * Maps each aesthetic to a variable or constant value. The built-in channels (x, y, color, …) keep
+ * exact types and autocomplete; the index signature also admits a geom's **custom positional
+ * aesthetics** — an OHLC candlestick's `open`/`high`/`low`/`close` — which the geom declares on its
+ * position contract and the engine then trains and scales like a built-in channel.
+ */
+declare interface AesMapping extends KnownAesthetics {
+    [aesthetic: string]: AestheticValue | undefined;
+}
+
+/**
+ * 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;
+
+/***************************************************************
+ * 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';
+
+/**
+ * Which point of a target's box an anchor resolves to. Compass directions name the
+ * eight edge/corner points; `center` is the box centre. Omitted means the geom-natural
+ * point (e.g. a bar's top-edge midpoint).
+ */
+declare type AnchorAlign = 'center' | 'top' | 'right' | 'bottom' | 'left' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+/**
+ * A nudge applied after a target resolves. `unit` selects the frame: `'panel'` is a
+ * fraction of the plot rect, `'px'` is device pixels (resolved at runtime).
+ */
+declare interface AnchorOffset {
+    x?: number;
+    y?: number;
+    /** Defaults to `'panel'`. */
+    unit?: 'panel' | 'px';
+}
+
+/** Anchors an annotation to a data point by row position, column, and/or category value. */
+export declare interface AnnotationDataPoint {
+    rowIndex?: number;
+    columnKey?: string;
+    rowValue?: DataValue;
+}
+
+/**
+ * A point on the box of the annotation with id `ref`, reduced to the box-point named by `align`.
+ * Dropped on a missing ref or a reference cycle. Nothing to resolve, so the input and resolved unions
+ * share this type.
+ */
+declare interface AnnotationPointAnchor {
+    anchorType: 'annotation';
+    /** Explicit id of the target annotation. */
+    ref: string;
+    align?: AnchorAlign;
+    offset?: AnchorOffset;
+}
+
+/**
+ * Copies the box of the annotation with id `ref`. Dropped on a missing ref, a cycle, or a zero-area
+ * (point) target. Nothing to resolve, so the input and resolved unions share this type.
+ */
+declare interface AnnotationRegionAnchor {
+    anchorType: 'annotation';
+    /** Explicit id of the target annotation. */
+    ref: string;
+}
+
+/** All annotations attached to a graph, as user-facing input. */
+declare interface AnnotationsInput {
+    differenceArrows?: DifferenceArrowInput[];
+    shapes?: ShapeInput[];
+    arrows?: ArrowInput[];
+    textAnnotations?: TextAnnotationInput[];
+    images?: ImageAnnotationInput[];
+    stickers?: StickerAnnotationInput[];
+    pinnedNumbers?: PinnedNumberAnnotationInput[];
+    comments?: CommentAnnotationInput[];
+}
+
+/**
+ * Whether an annotation renders beneath the geoms (background) or on top (foreground).
+ */
+declare type AnnotationZOrder = 'background' | 'foreground';
+
+/**
+ * A transform input that may be built-in or custom. Used at the spec-construction boundary
+ * (`pipe`/`createSpec` items, `SpecInput.transforms`) and the transform compile stage, so a custom
+ * transform pipes in and applies through the registry — while {@link TransformInput} stays the clean
+ * built-in union everywhere a `transformType` is narrowed.
+ */
+declare type AnyTransformInput = TransformInput | CustomTransformInput<string>;
+
+export declare interface Appearance {
+    /** Id of the color palette to apply to all series. */
+    paletteId?: string;
+    /** Per-series style overrides, keyed by series id. */
+    seriesStyles?: Record<string, SeriesStyle>;
+    /** Colors all bars the same instead of giving each category its own palette color. */
+    useSingleColorForBars?: boolean;
+    /** Tints the graph background with the palette instead of leaving it plain. */
+    backgroundModifier?: 'none' | 'tint';
+    border?: Partial<{
+        style: 'none' | 'custom' | 'tinted' | 'gradient' | 'preset' | 'grey';
+        color: string;
+        width: number;
+    }>;
+    hasRoundedCorners?: boolean;
+    textStyle?: AppearanceTextStyle;
+    /** One of the {@link CHART_TEXT_SCALES} multipliers applied to all text sizes. */
+    textScale?: number;
+    /** How non-highlighted series are de-emphasized when one series is highlighted. */
+    highlightStyle?: 'grey' | 'fade-color';
+    isLogoHidden?: boolean;
+    numberFormat?: Partial<{
+        /** Fixed number of decimal places, or 'auto' to choose per value. */
+        decimalPlaces: 'auto' | number;
+        /** Large-number suffix: none, automatic, or a forced thousands/millions/billions unit. */
+        abbreviation: 'none' | 'auto' | 'k' | 'm' | 'b';
+    }>;
+    showTooltips?: boolean;
+    animateTransitions?: boolean;
+}
+
+/**
+ * Visual appearance settings that travel through the spec but only affect
+ * rendering (not data, scales, or layout math).
+ */
+declare interface AppearanceSpec {
+    /**
+     * Multiplier applied to every text element. The renderer sets a CSS
+     * variable; em-based theme tokens scale automatically.
+     *
+     * Renderer contract: apply this at both text measurement and CSS render time.
+     * The engine assumes the measured sizes it receives already include the
+     * multiplier, so layout will be wrong if it is applied to only one of the two.
+     * @default 1
+     */
+    textScale: number;
+    /**
+     * Chart background fill. Defaults to the theme's `graphBackground` token.
+     * @default { type: 'theme' }
+     */
+    background: BackgroundSpec;
+    /**
+     * Border ring painted inside the chart bounds. Defaults to no border.
+     * @default { type: 'none' }
+     */
+    border: BorderSpec;
+    /**
+     * Corner radius (px) applied to both the chart frame and its inner content.
+     * Use `0` for square corners.
+     * @default 8
+     */
+    cornerRadius: number;
+}
+
+/** Font and color overrides split by text role: `heading` covers titles, `body` covers all other chart text. */
+export declare type AppearanceTextStyle = Partial<{
+    heading: GraphTextStyle;
+    body: GraphTextStyle;
+}>;
+
+/**
+ * Area-specific parameters.
+ */
+declare interface AreaGeomParams {
+    /**
+     * Interpolation method between points — a d3-shape curve family (`'linear'` ⇒
+     * `curveLinear`, `'catmull-rom'` ⇒ `curveCatmullRom`).
+     * @default 'linear'
+     */
+    interpolate: InterpolateType;
+    /**
+     * How to handle missing (null/undefined) values. As for line:
+     * - `'zero'`: nulls arrive already substituted with zero by the compiler.
+     * - `'gap'`: break the path at a null.
+     * - `'connect'`: drop nulls before pathing so the line spans the gap.
+     * @default 'gap'
+     * */
+    missingValues: MissingValuesType;
+}
+
+/**
+ * The paint vocabulary of the area geom — the shared paint plus the outline's width, dash, and
+ * opacity. `alpha` is the fill's opacity; `strokeAlpha` the outline's.
+ */
+declare type AreaStyleDeclarations = Pick<StyleDeclarations, 'color' | 'alpha' | 'saturation' | 'strokeWidth' | 'lineType' | 'strokeAlpha'>;
+
+/** Whether an arrow end carries an arrowhead. */
+declare type ArrowheadStyle = 'none' | 'line-arrow';
+
+/**
+ * Arrow annotation. Each endpoint is a {@link PointAnchorInput}, so it can float in
+ * panel fractions or pin to an observation. Distinct from {@link DifferenceArrowInput},
+ * which reads the measured gap between two observations.
+ */
+declare interface ArrowInput {
+    id?: string;
+    /** Tail endpoint. */
+    start: PointAnchorInput;
+    /** Head endpoint. */
+    end: PointAnchorInput;
+    /** null falls back to the theme `defaultAnnotationArrowStroke`. */
+    color?: string | null;
+    thickness?: ArrowThickness;
+    startArrowheadStyle?: ArrowheadStyle;
+    endArrowheadStyle?: ArrowheadStyle;
+    lineStyle?: ArrowLineStyle;
+    /** Render with a raised, outlined sticker-like appearance. */
+    hasStickerStyle?: boolean;
+}
+
+/** Whether an arrow's line is drawn solid or dashed. */
+declare type ArrowLineStyle = 'solid' | 'dashed';
+
+/** Preset stroke weight for an arrow annotation. */
+declare type ArrowThickness = 'thin' | 'medium' | 'thick';
+
+export declare interface AverageLine {
+    /** Column whose mean value the average line is drawn at. */
+    columnKey: string;
+}
+
+/** Configuration for the axes (if the graph supports them). */
+export declare interface Axes {
+    x?: AxisOptions;
+    y?: AxisOptions;
+    /** Secondary (right-hand) y-axis; only its label is configurable. */
+    y2?: Pick<AxisOptions, 'label'>;
+    /** Splits series across a primary and secondary y-axis. */
+    hasDualYAxis?: boolean;
+    showGridLines?: boolean;
+}
+
+/**
+ * Axes configuration (after defaults applied)
+ * Groups all axis-related settings per axis.
+ */
+declare interface AxesConfig {
+    x: XAxisConfig;
+    y: YAxisConfig;
+    ySecondary?: SecondaryAxisOverride;
+}
+
+/**
+ * A point given as axis values, mapped through the position scales. Dropped when either coordinate
+ * fails to map: a value outside a discrete scale's domain, a missing scale, or a polar coord.
+ * Nothing to resolve, so the input and resolved unions share this type.
+ */
+declare interface AxisAnchor {
+    anchorType: 'axis';
+    x: DataValue;
+    y: DataValue;
+    align?: AnchorAlign;
+    offset?: AnchorOffset;
+}
+
+/**
+ * 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
+     *   (visible unless a geom policy hides it, e.g. bar charts hide the x grid)
+     */
+    isVisible: boolean | null;
+    /**
+     * Line style of this axis's grid lines.
+     * @default 'dashed'
+     */
+    lineStyle: LineStyleType;
+    /**
+     * Stroke width of this axis's grid lines in px. null inherits the theme's grid line width.
+     * @default null
+     */
+    lineWidth: number | null;
+}
+
+export declare interface AxisOptions {
+    label?: string;
+    isHidden?: boolean;
+    /** Flips the axis orientation (left↔right for y, top↔bottom for x); for combo graphs it swaps the two y-axes. */
+    isReversed?: boolean;
+    scaleType?: 'linear' | 'logarithmic';
+    /** Forces the lower bound of the axis domain instead of deriving it from the data. */
+    min?: number;
+    /** Forces the upper bound of the axis domain instead of deriving it from the data. */
+    max?: number;
+    /** Whether to show ticks at every step ('auto') or only at the domain edges ('edges'). */
+    tickDisplayMode?: 'auto' | 'edges';
+}
+
+declare type AxisPosition = 'left' | 'right' | 'top' | 'bottom';
+
+/**
+ * Display mode for axis ticks
+ * - 'auto': Show all ticks (default behavior)
+ * - 'edges': Show only the first and last tick
+ */
+declare type AxisTickMode = 'auto' | 'edges';
+
+/**
+ * Configuration for a single axis's ticks
+ */
+declare interface AxisTicksConfig {
+    isVisible: boolean;
+    mode: AxisTickMode;
+}
+
+/**
+ * Background fill behind the chart.
+ * - 'theme': inherit the active theme's `graphBackground` token (default).
+ * - 'solid': override with an explicit CSS color string (use `'transparent'` for no fill).
+ * - 'tinted': mix the theme background with an anchor color. When `color` is
+ *   omitted the compiler resolves it to the first color of the active palette.
+ */
+declare type BackgroundSpec = {
+    type: 'theme';
+} | {
+    type: 'solid';
+    color: string;
+} | {
+    type: 'tinted';
+    color?: string;
+};
+
+/**
+ * Bar/Column-specific parameters. `width` is geometry — it sets the band envelope the compiler
+ * writes into the position variables. Paint (fill, border, corner rounding) is not a param: it
+ * lives in the stylesheet (`spec.styles`), resolved per observation by the style resolver.
+ */
+declare interface BarGeomParams {
+    /**
+     * Bar width as a fraction of the band the discrete scale allocates to the category, in `(0, 1]`.
+     * @default 0.7
+     */
+    width: number;
+}
+
+declare interface BarOptions {
+    sortBars?: boolean;
+}
+
+/** The paint vocabulary of the bar geom — the shared paint plus corner rounding and a border. */
+declare type BarStyleDeclarations = Pick<StyleDeclarations, 'color' | 'alpha' | 'saturation' | 'borderRadius' | 'borderColor' | 'borderWidth'>;
+
+/**
+ * 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;
+}
+
+/** Named gradient presets available to `border.type === 'preset'`. */
+declare const BORDER_PRESETS: readonly ["lilac", "neon_pink", "blackberry", "sun", "iceland", "sunset", "ultraviolet", "purple", "ice_cream", "mint", "cool", "fresh"];
+
+/** Name of a built-in gradient available to `border.type === 'preset'`. */
+declare type BorderPreset = (typeof BORDER_PRESETS)[number];
+
+/**
+ * Named corner-rounding scale for geoms that paint rect-like shapes. Semantic rather than a pixel
+ * value so each coordinate system renders it in its own frame. `'none'` is square; `'full'` rounds
+ * to half the shape's cross-axis thickness (a pill for bars).
+ */
+declare type BorderRadiusToken = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+
+/**
+ * Border ring painted around the chart. The ring is drawn INSIDE the
+ * configured chart dimensions — increasing `width` shrinks the plot/panel
+ * area accordingly.
+ *
+ * - 'none': no border.
+ * - 'solid': fill the ring with `color` as-is. Pass a theme token (e.g.
+ *   `'var(--graphy-grey-70)'`) for a theme-aware grey ring.
+ * - 'tinted': fill the ring with `color` lightened/darkened by the active
+ *   color scheme. When `color` is omitted the compiler resolves it to the
+ *   first color of the active palette.
+ * - 'gradient': fill the ring with a linear gradient derived from `color`,
+ *   adjusted for the active color scheme. When `color` is omitted the
+ *   compiler resolves it to the first color of the active palette.
+ * - 'preset': fill the ring with a named gradient from `BORDER_PRESETS`.
+ */
+declare type BorderSpec = {
+    type: 'none';
+} | {
+    type: 'solid';
+    color: string;
+    width: number;
+} | {
+    type: 'tinted';
+    color?: string;
+    width: number;
+} | {
+    type: 'gradient';
+    color?: string;
+    width: number;
+} | {
+    type: 'preset';
+    preset: BorderPreset;
+    width: number;
+};
+
+/**
+ * The "Made with Graphy" provenance badge. A discovery signal (not a lock) — distinct from
+ * `source`, which is the user's own attribution.
+ */
+declare interface BrandMarkConfig {
+    enabled: boolean;
+    placement: BrandMarkPlacement;
+    variant: BrandMarkVariant;
+}
+
+/** Where the Graphy provenance badge anchors on the chart frame. */
+declare type BrandMarkPlacement = 'footer' | 'header';
+
+/**
+ * Visual treatment for the badge when the frame is large enough for the full pill.
+ * Below 200 px wide the renderer always collapses to the circular mini form regardless.
+ */
+declare type BrandMarkVariant = 'full' | 'mini';
+
+declare interface CartesianCoordInput {
+    type: 'coord';
+    coordType: 'cartesian';
+    params?: Partial<BaseCoordParams>;
+}
+
+/**
+ * Discrete text-size multipliers exposed to consumers. The renderer multiplies
+ * its base font-size by this value, so all em-based theme tokens scale together.
+ * */
+export declare const CHART_TEXT_SCALES: readonly [0.8, 1, 1.2, 1.4, 1.6, 1.8, 2, 2.5, 3, 4];
+
+export declare type ChartTextScale = (typeof CHART_TEXT_SCALES)[number];
+
+/**
+ * Colour interpolation space for an explicit ramp's stops. `'lab'` (perceptually near-uniform) is the
+ * engine default; `'rgb'` reproduces d3's own default output; `'hcl'` matches Vega-Lite's. Named schemes
+ * carry their own baked-in interpolation, so this never applies to them.
+ */
+declare const COLOR_INTERPOLATION_SPACES: readonly ["rgb", "lab", "hcl", "hsl"];
+
+declare type ColorInterpolationSpace = (typeof COLOR_INTERPOLATION_SPACES)[number];
+
+/** The light/dark axis a {@link LightDarkColor} resolves against. */
+declare type ColorScheme = 'light' | 'dark';
+
+/** Any named colour scheme accepted by a continuous colour scale. */
+declare type ColorSchemeName = SequentialSchemeName | DivergingSchemeName;
+
+declare interface ComboOptions {
+    /** Geometry used for the bar-like series alongside line series in a combo graph. */
+    comboType?: 'grouped-bars' | 'stacked-bars' | 'lines';
+}
+
+/**
+ * Comment annotation: a marker dot pinned to a single observation, carrying
+ * rich-text content. The renderer's mini view shows a truncated comment; hover
+ * reveals the full text.
+ */
+declare interface CommentAnnotationInput {
+    id?: string;
+    at: ObservationAnchorInput;
+    content: RichTextContent;
+}
+
+/** Comparison operators for declarative filtering. */
+declare type ComparisonOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte';
+
+declare type ConfigInput = Omit<DeepPartial<ConfigSpec>, 'legend' | 'content'> & {
+    legend?: LegendConfigInput;
+    content?: ContentInput;
+};
+
+/**
+ * Feature configuration with resolved defaults.
+ * All fields are required and always populated after resolution.
+ */
+declare interface ConfigSpec {
+    /**
+     * Locale used to interpret source values and, by default, to format display
+     * output (axis labels, tooltips, numbers). Pass `formattingLocale` to a
+     * `format*` helper to override display only. It resolves to
+     * `formattingLocale ?? parsingLocale`. The `duration` format is always
+     * English regardless of locale.
+     */
+    parsingLocale: Locale;
+    legend: LegendConfig;
+    axes: AxesConfig;
+    panel: PanelConfig;
+    headline: HeadlineConfig;
+    numberFormat: NumberFormatConfig;
+    content: ContentConfig;
+    appearance: AppearanceSpec;
+    layout: LayoutConfig;
+}
+
+/***************************************************************
+ * 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. */
+export declare interface Content {
+    title?: string | RichTextContent;
+    isTitleHidden?: boolean;
+    subtitle?: string | RichTextContent;
+    isSubtitleHidden?: boolean;
+    caption?: string | RichTextContent;
+    isCaptionHidden?: boolean;
+    /** Attribution shown in the footer; optional label text and link target. */
+    source?: Partial<{
+        label: string;
+        url: string;
+    }>;
+    isSourceHidden?: boolean;
+    /**
+     * Structured "Made with Graphy" provenance badge. Prefer this over {@link isBrandMarkHidden}.
+     * Defaults: disabled at the low-level renderer; `@graphysdk/react` seeds enabled on.
+     */
+    brandMark?: Partial<{
+        enabled: boolean;
+        placement: 'footer' | 'header';
+        variant: 'full' | 'mini';
+    }>;
+    /**
+     * Legacy opt-out for the provenance badge (`true` = hide). Inverted to `brandMark.enabled` /
+     * `isBrandMarkVisible`. Ignored when `brandMark.enabled` is set explicitly.
+     */
+    isBrandMarkHidden?: boolean;
+}
+
+/**
+ * Resolved content configuration (all fields populated).
+ *
+ * `null` on a text slot means "no content set". The matching `isXVisible` flag
+ * is a separate visibility toggle that lets a value be preserved across show /
+ * hide cycles without losing the text the user typed.
+ */
+declare interface ContentConfig {
+    title: TextContent | null;
+    isTitleVisible: boolean;
+    subtitle: TextContent | null;
+    isSubtitleVisible: boolean;
+    caption: TextContent | null;
+    isCaptionVisible: boolean;
+    source: SourceContent | null;
+    isSourceVisible: boolean;
+    /**
+     * Structured provenance-badge config. Canonical source of truth for enabled /
+     * placement / variant after {@link resolveConfig}.
+     */
+    brandMark: BrandMarkConfig;
+    /**
+     * Legacy alias for {@link BrandMarkConfig.enabled}. Kept in sync by resolveConfig so
+     * existing callers and the node-renderer path keep working. Prefer `brandMark.enabled`.
+     */
+    isBrandMarkVisible: boolean;
+}
+
+/** Content input — all fields optional. Partial brandMark merges onto defaults. */
+declare type ContentInput = Partial<Omit<ContentConfig, 'brandMark'>> & {
+    brandMark?: Partial<BrandMarkConfig>;
+};
+
+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;
+    /**
+     * Output range. A numeric `[min, max]` for magnitude aesthetics (size, alpha, strokeWidth); a ramp of
+     * two-or-more colour strings for a continuous `color` scale, interpolated in the
+     * {@link ContinuousScaleInput.interpolate} space.
+     */
+    range?: ReadonlyArray<number | string> | null;
+    /**
+     * Named colormap for a continuous `color` scale (e.g. `'viridis'`, `'RdBu'`). Superseded by an explicit
+     * `range`. Inert for non-colour aesthetics.
+     */
+    scheme?: ColorSchemeName | null;
+    /** Interpolation space for a colour `range`'s stops. Ignored for `scheme`. Inert for non-colour aesthetics. */
+    interpolate?: ColorInterpolationSpace;
+    /** Diverging midpoint — pins a colour ramp's neutral stop to this value. Inert for non-colour aesthetics. */
+    domainMid?: number | null;
+    /** Symmetrise the domain about `domainMid`. Defaults to `true` when `domainMid` is set; inert otherwise. */
+    symmetric?: boolean;
+};
+
+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 magnitude scales (size, alpha, strokeWidth). Ignored for position
+     * aesthetics (x, y). A numeric `[min, max]`; aesthetic-specific defaults apply when omitted
+     * (size `[4, 20]`, alpha `[0.1, 1]`, strokeWidth `[1, 4]`).
+     *
+     * A continuous `color` scale takes a colour ramp instead — see {@link ColorContinuousScaleOptions}.
+     * @example scale.size.continuous({ range: [2, 30] })
+     */
+    range?: [number, number];
+};
+
+/**
+ * Convert a high-level {@link GraphConfig} into the low-level {@link SpecInput} the compiler takes.
+ *
+ * `data` is read for inference only — column types decide the x/y mapping, and any wide-to-long
+ * reshape the graph type needs is emitted as a spec transform rather than applied here. The same
+ * `data` value the caller passed goes on to `compile`/`<GraphProvider>` untouched.
+ *
+ * This is a one-way, lossy conversion. Features Spec has no equivalent for (series styles beyond
+ * line type, theme overrides, content) are silently dropped. `GraphConfig.themeOverrides` and
+ * `appearance.textStyle` are renderer concerns — see react-renderer's `convertGraphConfigTheme`.
+ */
+export declare function convertGraphConfig(graphConfig: GraphConfig, data: Data, ctx?: GraphConfigContext): SpecInput;
+
+/**
+ * Discriminated union of all coordinate input specs (user-provided, optional params).
+ */
+declare type CoordInput = CartesianCoordInput | FlipCoordInput | PolarCoordInput;
+
+/**
+ * Resolved count stat spec.
+ */
+declare interface CountStatSpec {
+    type: 'count';
+}
+
+/**
+ * A layer for a custom (plugin-contributed) geom. Its `geom` is a name outside {@link GeomName},
+ * resolved downstream through the geom registry; `params` are validated at the typed builder call
+ * site, so the node itself carries them as an open record.
+ */
+declare interface CustomGeomLayerInput extends LayerInputBase {
+    geom: string;
+    params?: Record<string, unknown>;
+}
+
+/** A single named color slot within a custom palette supplied by the host. */
+declare type CustomPaletteColor = {
+    id: string;
+    hex: string;
+    name?: string;
+};
+
+/** Reference to a user-registered custom palette by id, resolved against the palette registry. */
+declare type CustomPaletteInput = {
+    type: 'custom';
+    id: string;
+};
+
+/** Host-owned custom palettes, keyed by `paletteId`, that a `scale.color.palette` may reference by id. */
+declare type CustomPalettesInput = Record<string, CustomPaletteColor[]>;
+
+/**
+ * The input node a custom (plugin-contributed) stat builder produces.
+ */
+declare interface CustomStatInput<Name extends string = string> {
+    type: Name;
+}
+
+/***************************************************************
+ * Transform Input
+ ***************************************************************/
+/**
+ * The input node a custom (plugin-contributed) transform builder produces.
+ */
+declare interface CustomTransformInput<Name extends string = string> {
+    type: 'transform';
+    transformType: Name;
+    options?: Record<string, unknown>;
+}
+
+/**
+ * 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.
+ */
+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 */
+}
+
+/**
+ * Anchor along one axis of the geom's box, CSS-flexbox style. `justify` runs along the value
+ * axis — `'end'` is the value tip whatever the orientation or sign (e.g. the bottom of a negative
+ * column). `align` runs across it: bandwidth for bars, angular for pie wedges, x for
+ * point/line/area.
+ */
+declare type DataLabelAnchor = 'start' | 'center' | 'end';
+
+/**
+ * Value-axis anchors. `'panel-start'`/`'panel-end'` resolve against the panel instead of the
+ * geom's box, so labels sit flush at the chart edge regardless of the geom's length. They stay
+ * sign-aware like `'end'` and always inset inward, ignoring `position` on the value axis — past
+ * the panel edge is off-canvas.
+ */
+declare type DataLabelJustify = DataLabelAnchor | 'panel-start' | 'panel-end';
+
+/**
+ * Where data labels sit relative to the geom they decorate.
+ * - `'auto'` — the engine chooses: fit inside, flip outside, drop or rotate as needed.
+ *   `justify`/`align` are ignored.
+ * - `'inside'` — within the geom's box, hugging the `(justify, align)` anchor. Never dropped,
+ *   flipped or rotated. On line/point geoms the label centres on the data point/marker.
+ * - `'outside'` — just past the value-axis edge selected by `justify`; `align` stays within the
+ *   geom's width (line/point labels sit beside the geom). Never dropped. Stacked/filled cartesian
+ *   bar segments coerce to `'inside'` — every segment edge borders a neighbour; use
+ *   `showStackTotals` for stack-end totals. (Pie wedges keep `'outside'`.)
+ *
+ * Styling follows the label's effective position: over the geom → inside styling (white text,
+ * no plate); off it — by placement, offset, or not fitting — outside styling (dark text on a
+ * plate). Area labels always use the plated styling: the translucent fill can't back white text.
+ */
+declare type DataLabelPlacement = 'auto' | 'inside' | 'outside';
+
+export declare interface DataLabels {
+    showDataLabels?: boolean;
+    /** Whether labels show raw values or each point's share of its stack/total. */
+    dataLabelFormat?: 'absolute' | 'percentage';
+    /** Shows the summed total above each stack in stacked graphs. */
+    showStackTotals?: boolean;
+    showCategoryLabels?: boolean;
+}
+
+/**
+ * Resolved data-labels config carried per-layer.
+ */
+declare interface DataLabelsConfig {
+    /**
+     * Whether to show data labels on the layer.
+     * @default false
+     */
+    showDataLabels: boolean;
+    /**
+     * The format to use for the data labels.
+     * @default 'absolute'
+     */
+    format: 'absolute' | 'percentage';
+    /**
+     * Whether to show stack totals on the layer.
+     * @default false
+     */
+    showStackTotals: boolean;
+    /**
+     * Polar bars (pie/donut) prepend the category to the value label ("Europe · 35%"). Cartesian
+     * bars emit a second label per observation, placed by the `category*` fields independently of
+     * `showDataLabels`. Other geoms ignore it.
+     * @default false
+     */
+    showCategoryLabels: boolean;
+    /**
+     * The source of the data labels.
+     * @default { variable: POSITION_VARIABLES.yRaw }
+     */
+    labelSource: AestheticValue;
+    /**
+     * Where labels sit relative to the geom. Explicit values render exactly as asked; dropping,
+     * flipping and rotation happen only under `'auto'`.
+     * @default 'auto'
+     */
+    position: DataLabelPlacement;
+    /**
+     * Anchor along the geom's value/growth axis. Only consulted when `position` is explicit.
+     * Panel anchors pin the label to the panel's edge instead of the geom's; see
+     * {@link DataLabelJustify}.
+     * @default 'end' ('center' for stacked/filled bars)
+     */
+    justify: DataLabelJustify;
+    /**
+     * Anchor across the geom's secondary axis. Only consulted when `position` is explicit.
+     * @default 'center'
+     */
+    align: DataLabelAnchor;
+    /**
+     * Gap in pixels between the geom's edge and the label box. Stack totals ignore it.
+     * @default 4 for bars and polar wedges, 12 for point/line/area
+     */
+    offset: number;
+    /**
+     * Where the cartesian-bar category label sits relative to its bar. No `'auto'`: category labels
+     * have no fit heuristics and render exactly as asked. Stacked/filled segments coerce
+     * `'outside'` to `'inside'` — every segment edge borders a neighbour.
+     * @default 'inside'
+     */
+    categoryPosition: Exclude<DataLabelPlacement, 'auto'>;
+    /**
+     * Category label's anchor along the bar's value axis; accepts panel anchors like `justify`.
+     * @default 'start'
+     */
+    categoryJustify: DataLabelJustify;
+    /**
+     * Category label's anchor across the bar's bandwidth.
+     * @default 'center'
+     */
+    categoryAlign: DataLabelAnchor;
+    /**
+     * Gap in pixels between the anchored edge and the category label box.
+     * @default 4
+     */
+    categoryOffset: number;
+}
+
+/** User-facing data-labels options; any omitted field falls back to its resolved default. */
+declare type DataLabelsInput = DeepPartial<Omit<DataLabelsConfig, 'labelSource'>>;
+
+/** The type of a variable's values. Internally, numeric values are stored as numbers, dates as Date objects and categorical values as strings. */
+declare type DataType = 'numeric' | 'categorical' | 'temporal';
+
+/** The smallest unit of data in the dataset. `null` represents a missing value. */
+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;
+};
+
+/**
+ * Recursively makes every property of `T` optional.
+ * Unlike the built-in `Partial`, this applies to nested objects as well.
+ */
+declare type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends Array<infer U> ? Array<DeepPartial<U>> : unknown extends T[K] ? T[K] : NonNullable<T[K]> extends object ? DeepPartial<NonNullable<T[K]>> : T[K];
+};
+
+declare type DefaultPaletteConfig = {
+    type: 'default';
+};
+
+/**
+ * User-facing difference-arrow input. `size`, `color` and `labelCrossPosition`
+ * are defaulted by the resolver.
+ */
+declare interface DifferenceArrowInput {
+    /** Stable id; generated by the resolver when omitted. */
+    id?: string;
+    /** Observation the arrow's tail points from. */
+    start: ObservationAnchorInput;
+    /** Observation the arrow's head points to. */
+    end: ObservationAnchorInput;
+    /** What the arrow's label measures (raw gap, relative change, or share). */
+    label: DifferenceArrowLabelKind;
+    /** null falls back to a theme default. */
+    color?: string | null;
+    size?: DifferenceArrowSize;
+    /** AnchorOffset of the label along the arrow, as a fraction of the arrow's length. */
+    labelCrossPosition?: number;
+}
+
+/** What a difference arrow's label measures: the raw gap, the relative change, or one value as a share of the other. */
+declare type DifferenceArrowLabelKind = 'absolute-difference' | 'relative-difference' | 'proportion';
+
+/** Preset visual scale for a difference arrow. */
+declare type DifferenceArrowSize = 'small' | 'medium' | 'large';
+
+declare interface DiscreteScaleInput {
+    type: 'scale';
+    scaledAesthetic: ScaledAestheticKey;
+    scaleType: 'discrete';
+    range?: Array<number | string> | null;
+    domain?: Array<string | number> | null;
+    padding?: number | null;
+    reverse?: boolean;
+}
+
+declare type DiscreteScaleOptions<RangeValue extends number | string = number | string> = {
+    /**
+     * Explicit output values mapped to domain categories in order.
+     */
+    range?: RangeValue[];
+    /**
+     * Explicit domain values controlling category order and membership.
+     * Only these values appear in the scale.
+     */
+    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;
+    /**
+     * Reverse band order. First domain entry maps to the end of the range.
+     * @default false
+     */
+    reverse?: boolean;
+};
+
+/**
+ * Diverging colormap names from `d3-scale-chromatic`, in Brewer's capitalisation. `RdBu`, `BrBG` and
+ * `PuOr` are colour-vision-deficiency safe; `Spectral` is offered for its familiar rainbow look but is not
+ * CVD-safe. Red-green ramps are deliberately excluded.
+ */
+declare const DIVERGING_SCHEME_NAMES: readonly ["RdBu", "BrBG", "PuOr", "Spectral"];
+
+/** A diverging colormap: its canonical ColorBrewer code or a friendly alias. */
+declare type DivergingSchemeName = (typeof DIVERGING_SCHEME_NAMES)[number] | SchemeAlias;
+
+/**
+ * Layout configuration.
+ *
+ * A general per-region map (rather than a theme token per gap) because the set of boundaries is
+ * open-ended and reads naturally as part of the chart spec. Anything left unset keeps the engine
+ * defaults.
+ */
+/**
+ * Per-side outer padding, in pixels. Any side left unset falls back to the engine default padding
+ * ({@link LAYOUT_PADDING}), so `{ top: 40 }` keeps the other three sides at the default. Use an
+ * explicit `0` to remove a side's padding.
+ */
+declare type EdgePaddingConfig = {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+};
+
+/***************************************************************
+ * 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>;
+}
+
+/**
+ * The type of geometric mark used to represent data in a layer.
+ *
+ * - `'point'` — Scatter-style dot marks
+ * - `'line'` — Connected line marks
+ * - `'area'` — Filled area marks
+ * - `'bar'` — Rectangular bar marks (cartesian) or pie wedge (polar)
+ * - `'rule'` — Horizontal or vertical reference line at a constant value
+ */
+declare type GeomName = 'point' | 'line' | 'area' | 'bar' | 'rule';
+
+/**
+ * Maps each geom type name to its resolved parameter type.
+ */
+declare interface GeomParamsMap {
+    point: PointGeomParams;
+    line: LineGeomParams;
+    area: AreaGeomParams;
+    bar: BarGeomParams;
+    rule: RuleGeomParams;
+}
+
+/** The paint declarations every geom kind shares. */
+declare type GeomStyleDeclarations = Pick<StyleDeclarations, 'color' | 'alpha' | 'saturation'>;
+
+/** Goal line with a target value. */
+export declare interface GoalLine {
+    /** Value on the measure axis where the line is drawn. */
+    target: number;
+    /** Category value at which to anchor an optional marker on the line. */
+    marker?: DataValue;
+    label?: string;
+}
+
+declare type GraphAnnotation = GraphStickerAnnotation | GraphTooltipAnnotation | GraphHighlightAnnotation | GraphTextAnnotation | GraphArrowAnnotation | GraphDifferenceArrowAnnotation | GraphShapeAnnotation | GraphImageAnnotation;
+
+export declare interface GraphArrowAnnotation {
+    id: string;
+    type: 'arrow';
+    /** Tail position as fractions (0-1) of the plot width and height. */
+    startX: number;
+    startY: number;
+    /** Head position as fractions (0-1) of the plot width and height. */
+    endX: number;
+    endY: number;
+    color?: string;
+    thickness: 'thin' | 'medium' | 'thick';
+    startArrowheadStyle: 'none' | 'line-arrow';
+    lineStyle: 'solid' | 'dashed';
+    endArrowheadStyle: 'none' | 'line-arrow';
+    /** Adds a white outline so the arrow reads as a sticker on top of the chart. */
+    hasStickerStyle: boolean;
+}
+
+/**
+ * The full set of options a consumer passes to configure a chart's type, styling, axes, and content.
+ * Every field is optional, so omitted settings fall back to engine defaults.
+ */
+export declare interface GraphConfig {
+    type?: GraphType;
+    /** Geometry-specific settings, unioned across all graph types. */
+    options?: Options;
+    axes?: Axes;
+    legend?: Legend;
+    appearance?: Appearance;
+    /** Ad-hoc overrides of individual theme tokens, plus a shortcut for the graph background. */
+    themeOverrides?: {
+        [key: string]: unknown;
+        graphBackground?: string;
+    };
+    content?: Content;
+    headlineNumbers?: HeadlineNumbers;
+    dataLabels?: DataLabels;
+    annotations?: GraphAnnotation[];
+    referenceLines?: ReferenceLines;
+}
+
+/**
+ * Presentation context a {@link GraphConfig} conversion needs to resolve its opaque `paletteId` into
+ * a structured palette: the color scheme picks the variant of scheme-dependent presets, and the
+ * palette catalog says which ids name a host-registered custom palette.
+ */
+export declare interface GraphConfigContext {
+    /** Color scheme used to resolve scheme-dependent palettes; defaults to light when omitted. */
+    colorScheme?: ColorScheme;
+    /** Renderer-owned palette catalog, keyed by `paletteId`. */
+    customPalettes?: CustomPalettesInput;
+}
+
+export declare interface GraphDifferenceArrowAnnotation {
+    id: string;
+    type: 'difference-arrow';
+    /** How the gap between the two points is expressed in the label. */
+    show: 'absolute-difference' | 'relative-difference' | 'proportion';
+    start: AnnotationDataPoint;
+    end: AnnotationDataPoint;
+    color?: string;
+    size: 'medium' | 'small' | 'large';
+    /** Position of the label along the arrow as a fraction (0-1) from start to end. */
+    labelPosition?: number;
+}
+
+declare type GraphHighlightAnnotation = {
+    id: string;
+    type: 'highlight';
+    /** Scope of the emphasis: a single point, a whole series, or all points at one x value. */
+    highlight: 'data-point' | 'series' | 'x-value';
+} & AnnotationDataPoint;
+
+export declare interface GraphImageAnnotation {
+    id: string;
+    type: 'image';
+    /** Image URL or data URI. */
+    src: string;
+    /** Whether the image is drawn behind or in front of the plotted data. */
+    layer: 'belowPlot' | 'abovePlot';
+    /** Top-left position as fractions (0-1) of the plot width and height. */
+    x: number;
+    y: number;
+    /** Size as fractions (0-1) of the plot width and height. */
+    width: number;
+    height: number;
+    /** How the image scales inside its box: stretch, letterbox, or crop-to-fill. */
+    fit?: 'fill' | 'contain' | 'cover';
+    /** Opacity from 0 (transparent) to 1 (opaque). */
+    opacity?: number;
+}
+
+export declare interface GraphShapeAnnotation {
+    id: string;
+    type: 'shape';
+    shape: 'rectangle';
+    /** Whether the shape is drawn behind or in front of the plotted data. */
+    layer: 'belowPlot' | 'abovePlot';
+    /** Top-left position as fractions (0-1) of the plot width and height. */
+    x: number;
+    y: number;
+    /** Size as fractions (0-1) of the plot width and height. */
+    width: number;
+    height: number;
+    fillColor: string;
+    /** Fill opacity from 0 (transparent) to 1 (opaque). */
+    fillOpacity: number;
+    strokeWidth: number;
+}
+
+export declare type GraphStickerAnnotation = {
+    id: string;
+    type: 'sticker';
+    sticker: 'rocket' | 'clapping-hands' | 'thumbs-up' | 'thumbs-down' | 'grinning-face';
+} & AnnotationDataPoint;
+
+export declare interface GraphTextAnnotation {
+    id: string;
+    type: 'text';
+    content: RichTextContent;
+    /** Left position as a fraction (0-1) of the plot width. */
+    x: number;
+    /** Top position as a fraction (0-1) of the plot height. */
+    y: number;
+    /** Box width as a fraction (0-1) of the plot width; text wraps within it. */
+    width: number;
+    backgroundColor?: string;
+    /** Whether the background is semi-transparent ('fade') or fully opaque. */
+    backgroundColorStyle?: 'fade' | 'opaque';
+}
+
+export declare interface GraphTextStyle {
+    /** Id of a font registered with the engine; resolved to a concrete family at compile time. */
+    fontId?: string;
+    color?: string;
+}
+
+export declare type GraphTooltipAnnotation = {
+    id: string;
+    type: 'tooltip';
+    /** Tooltip body as TipTap rich-text content; omit or `null` for a pinned-number annotation (no caption). */
+    caption?: RichTextContent | null;
+} & 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';
+
+declare type GraphyPaletteConfig = {
+    type: 'graphy';
+    variant?: GraphyPaletteVariant;
+};
+
+/** `waterfall` swaps in the positive/negative/total colors used by waterfall graphs. */
+declare type GraphyPaletteVariant = 'default' | 'waterfall';
+
+/**
+ * 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;
+}
+
+export declare interface HeadlineNumbers {
+    /** Which aggregate to surface as the big headline figure. */
+    show?: 'current' | 'average' | 'total' | 'conversion' | 'none';
+    /** Baseline the headline is compared against to compute the change indicator. */
+    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 (not implemented yet — compiles to no headline)
+ * - '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';
+
+/**
+ * User-facing highlight definition. `id` is auto-assigned by the resolver when
+ * omitted. Omit the layer scope to evaluate against every layer.
+ */
+declare interface HighlightInput {
+    type: 'highlight';
+    id?: string;
+    predicate: Predicate;
+    scope?: HighlightScope;
+    layerId?: string;
+}
+
+/**
+ * Scope of a highlight match — what visual unit gets the matched treatment.
+ *
+ * - `data-point` (default): rows that satisfy the predicate are matched
+ *   individually; siblings in the same series stay un-matched.
+ * - `series`: any row that satisfies the predicate expands to its whole series
+ *   (group). The entire series renders as matched; sibling rows in the series
+ *   are matched too. Use this to highlight a whole line / area / bar group.
+ * - `x-value`: any row that satisfies the predicate expands to all rows
+ *   sharing the same x value. Use this to highlight a vertical slice across
+ *   series.
+ */
+declare type HighlightScope = 'data-point' | 'series' | 'x-value';
+
+declare interface IdentityScaleInput {
+    type: 'scale';
+    scaledAesthetic: ScaledAestheticKey;
+    scaleType: 'identity';
+}
+
+/**
+ * Resolved identity stat spec.
+ */
+declare interface IdentityStatSpec {
+    type: 'identity';
+}
+
+/** How an image annotation scales inside its box: stretch, letterbox, or crop-to-fill. */
+declare type ImageAnnotationFit = 'fill' | 'contain' | 'cover';
+
+/**
+ * Image annotation. Its area is positioned by a {@link RegionAnchorInput} so it
+ * re-resolves each compile (re-flows on resize, tracks data when bound).
+ */
+declare interface ImageAnnotationInput {
+    id?: string;
+    /** Image URL or data URI. */
+    src: string;
+    /** Draw beneath the geoms (background) or on top (foreground). */
+    zOrder?: AnnotationZOrder;
+    /** The area the image fills. */
+    region: RegionAnchorInput;
+    /** How the image scales inside its box. */
+    fit?: ImageAnnotationFit;
+    /** Opacity, 0 (transparent) to 1 (opaque). */
+    opacity?: number;
+}
+
+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. Maps to d3-shape `curveLinear`.
+ * - `'catmull-rom'` — Smooth spline through points. Maps to d3-shape `curveCatmullRom`.
+ */
+declare type InterpolateType = 'linear' | 'catmull-rom';
+
+/**
+ * Each geom kind's vocabulary, keyed by the kind name a `select.kind` can carry.
+ */
+declare interface KindStyleDeclarationsMap {
+    bar: BarStyleDeclarations;
+    line: LineStyleDeclarations;
+    area: AreaStyleDeclarations;
+    point: PointStyleDeclarations;
+    rule: RuleStyleDeclarations;
+}
+
+/** The aesthetic channels with first-class engine support — the source of {@link AestheticKey}. */
+declare interface KnownAesthetics {
+    x?: AestheticValue;
+    y?: AestheticValue;
+    label?: AestheticValue;
+    color?: AestheticValue;
+    size?: AestheticValue;
+    /** Opacity (0–1). */
+    alpha?: AestheticValue;
+    /** Splits geoms into groups (separate lines/areas) without assigning a visual aesthetic. */
+    group?: AestheticValue;
+    strokeWidth?: AestheticValue;
+    /** Dash-pattern aesthetic (solid, dashed, dotted, ...). */
+    lineType?: AestheticValue;
+}
+
+/**
+ * Discriminated union of all layer inputs, keyed on `geom`. The built-in arms stay exactly typed;
+ * the {@link CustomGeomLayerInput} arm admits a plugin geom carrying a name outside {@link GeomName}.
+ * This is the user-facing type — fields are optional and will be resolved with defaults.
+ */
+declare type LayerInput = {
+    [G in GeomName]: LayerInputOf<G>;
+}[GeomName] | CustomGeomLayerInput;
+
+/**
+ * Fields shared by every layer input regardless of geom. All optional fields fall back to resolved
+ * defaults; the geom-specific arms of {@link LayerInput} add `geom` and `params` on top.
+ */
+declare interface LayerInputBase {
+    type: 'layer';
+    /** Stable identifier; auto-assigned during resolution when omitted. */
+    id?: string;
+    /** Layer-local aesthetic mapping, merged over the spec-level mapping. */
+    mapping?: AesMapping;
+    /**
+     * Statistical transform applied to this layer (e.g. count, mean, smooth), or a custom plugin stat.
+     * @default 'identity'
+     */
+    stat?: StatName | StatInput | CustomStatInput<string>;
+    /** How overlapping geoms are arranged (stack, dodge, fill, identity). */
+    position?: PositionType;
+    /** Which y scale this layer binds to — the primary or secondary axis. */
+    yScaleType?: YScaleType;
+    dataLabels?: DataLabelsInput;
+    /**
+     * 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]>;
+};
+
+/** Pixel gaps around each col. Same max(prev.after, next.before) rule as rows. */
+declare const LAYOUT_COL_GAPS: {
+    readonly leftLegend: {
+        readonly after: 10;
+        readonly before: 0;
+    };
+    readonly leftAxis: {
+        readonly after: 4;
+        readonly before: 0;
+    };
+    readonly rightAxis: {
+        readonly after: 10;
+        readonly before: 4;
+    };
+};
+
+/**
+ * Pixel gaps around each row. The boundary between two present rows is sized
+ * as max(prev.after, next.before), so either side can claim breathing room.
+ * Spacers are only materialised when both neighbours resolve to non-zero size.
+ */
+declare const LAYOUT_ROW_GAPS: {
+    readonly header: {
+        readonly after: 10;
+        readonly before: 0;
+    };
+    readonly headline: {
+        readonly after: 4;
+        readonly before: 0;
+    };
+    readonly topLegend: {
+        readonly after: 8;
+        readonly before: 0;
+    };
+    readonly topAxisLabel: {
+        readonly after: 8;
+        readonly before: 0;
+    };
+    readonly topAxis: {
+        readonly after: 0;
+        readonly before: 0;
+    };
+    readonly bottomAxis: {
+        readonly after: 4;
+        readonly before: 0;
+    };
+    readonly bottomAxisLabel: {
+        readonly after: 16;
+        readonly before: 0;
+    };
+    readonly bottomLegend: {
+        readonly after: 10;
+        readonly before: 16;
+    };
+    readonly footer: {
+        readonly after: 0;
+        readonly before: 16;
+    };
+};
+
+declare interface LayoutConfig {
+    /**
+     * Outer padding around the whole chart, in pixels. A number applies to all four sides; an
+     * {@link EdgePaddingConfig} sets sides individually. `null` uses the engine default padding
+     * ({@link LAYOUT_PADDING}) on every side.
+     */
+    padding: number | EdgePaddingConfig | null;
+    /** Per-region overrides for the grid spacing around each named region. */
+    gaps: Partial<Record<LayoutGapName, LayoutGapOverride>>;
+}
+
+/**
+ * Named regions in the chart's layout grid whose surrounding pixel gaps can be overridden via
+ * {@link LayoutConfig.gaps}. Derived from the engine's default gap maps so the overridable set
+ * cannot drift from the grid regions that actually consume the overrides.
+ */
+declare type LayoutGapName = keyof typeof LAYOUT_ROW_GAPS | keyof typeof LAYOUT_COL_GAPS;
+
+/**
+ * Override for a single named grid gap. A bare number sets the trailing (`after`) gap; the object
+ * form sets either edge, and an omitted edge keeps the engine default for that side. Overrides feed
+ * the `max(prev.after, next.before)` boundary rule described on {@link LayoutGapName}, so a lone
+ * `after` cannot shrink a boundary below the following region's `before`.
+ */
+declare type LayoutGapOverride = number | {
+    before?: number;
+    after?: number;
+};
+
+export declare interface Legend {
+    position?: 'auto' | 'top' | 'right' | 'none';
+}
+
+/**
+ * Placement of the legend items along its flow.
+ * - For a horizontal (`top`/`bottom`) legend this runs along the row: `start` = left, `end` = right.
+ * - For a vertical (`left`/`right`) legend it runs down the column: `start` = top, `end` = bottom.
+ * Vertical legends always pin to the plot border across the flow regardless of this value.
+ * `'auto'` resolves during compilation to `start` for horizontal legends and `center` for vertical.
+ */
+declare type LegendAlign = 'auto' | 'start' | 'center' | 'end';
+
+/**
+ * Legend configuration (after defaults applied)
+ */
+declare interface LegendConfig {
+    /**
+     * Position of the legend
+     * @default 'auto'
+     */
+    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;
+    /**
+     * Placement of the legend items along its flow.
+     * - For a horizontal (`top`/`bottom`) legend this runs along the row: `start` = left, `end` = right.
+     * - For a vertical (`left`/`right`) legend it runs down the column: `start` = top, `end` = bottom.
+     * Vertical legends always pin to the plot border across the flow regardless of this value.
+     * `'auto'` resolves to `start` for horizontal legends and `center` for vertical ones.
+     *
+     * @default 'auto'
+     */
+    align: LegendAlign;
+}
+
+/**
+ * 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';
+
+declare type LegendPosition = 'auto' | 'right' | 'left' | 'top' | 'bottom' | 'none';
+
+/** A color with one variant per {@link ColorScheme}, resolved against the active scheme at read time. */
+declare interface LightDarkColor {
+    light: string;
+    dark: string;
+}
+
+/**
+ * Line-specific parameters.
+ */
+declare interface LineGeomParams {
+    /**
+     * Interpolation method to use for the line. Names a d3-shape curve family:
+     * `'linear'` ⇒ `curveLinear`, `'catmull-rom'` ⇒ `curveCatmullRom`.
+     * @default 'linear'
+     */
+    interpolate: InterpolateType;
+    /**
+     * How to handle missing (NULL/undefined) values:
+     * - `'zero'`: nulls arrive already substituted with zero by the compiler —
+     *   render normally, no special handling.
+     * - `'gap'`: break the path wherever x or y is null (d3 `defined()`).
+     * - `'connect'`: drop null rows before pathing so the line spans the gap.
+     * @default 'gap'
+     */
+    missingValues: MissingValuesType;
+}
+
+declare interface LineOptions {
+    isSmoothLine?: boolean;
+    lineThickness?: number | 'auto';
+    showPoints?: boolean;
+    /** How gaps in the data are drawn: leave a gap, connect across, or treat as zero. */
+    missingValues?: 'gap' | 'connect' | 'zero';
+    /** Draws a gradient fill beneath the line (single series only) */
+    showFill?: boolean;
+}
+
+/**
+ * The paint vocabulary of the line geom — the shared paint plus the path's width, dash and the
+ * gradient wash beneath it. `alpha` is the stroke's opacity; `fillAlpha` the wash's.
+ */
+declare type LineStyleDeclarations = Pick<StyleDeclarations, 'color' | 'alpha' | 'saturation' | 'strokeWidth' | 'lineType' | 'fillAlpha'>;
+
+/**
+ * Stroke style for line rendering.
+ *
+ * - `'solid'` — Continuous unbroken stroke
+ * - `'dashed'` — Repeating dash pattern
+ * - `'dotted'` — Repeating dot pattern
+ */
+declare type LineStyleType = 'solid' | 'dashed' | 'dotted';
+
+/** One of the BCP-47 locale strings the engine supports for number and date formatting. */
+declare type Locale = (typeof LOCALES)[number];
+
+/** The full set of supported BCP-47 locale strings. */
+declare const LOCALES: readonly ["en-GB", "en-US", "ar", "pt-PT"];
+
+/** Logical composition of any predicate. */
+declare type LogicalPredicate = {
+    and: Predicate[];
+} | {
+    or: Predicate[];
+} | {
+    not: Predicate;
+};
+
+/**
+ * Resolved mean stat spec.
+ */
+declare interface MeanStatSpec {
+    type: 'mean';
+}
+
+/**
+ * Strategy for handling null/undefined values in lines and areas.
+ *
+ * - `'zero'` — Replace missing values with zero. Pre-substituted by the compiler, so the renderer
+ *   sees no nulls and paths normally.
+ * - `'gap'` — Leave a visible gap where values are missing. The renderer breaks the path at any
+ *   null x / y (e.g. d3's `defined()`).
+ * - `'connect'` — Skip missing values and connect adjacent valid points. The renderer drops nulls before pathing.
+ */
+declare type MissingValuesType = 'zero' | 'gap' | 'connect';
+
+/** The hues available as a base for monochrome palettes, in pick order. */
+declare const MONO_BASES: readonly ["grey", "red", "orange", "yellow", "green", "cyan", "blue", "purple", "pink"];
+
+/** One of the base hues a monochrome palette can be built from. */
+declare type MonoPaletteBase = (typeof MONO_BASES)[number];
+
+declare type MonoPaletteConfig = {
+    type: 'mono';
+    base: MonoPaletteBase;
+    variant?: MonoPaletteVariant;
+};
+
+/** Tints the single-hue ramp for use on light vs dark backgrounds. */
+declare type MonoPaletteVariant = 'light' | 'dark';
+
+/** The hues available as a base for neon palettes, in pick order. */
+declare const NEON_BASES: readonly ["cyan", "pink", "purple", "red", "orange", "yellow", "green", "blue"];
+
+/** One of the base hues a neon palette can be built from. */
+declare type NeonPaletteBase = (typeof NEON_BASES)[number];
+
+declare type NeonPaletteConfig = {
+    type: 'neon';
+    base: NeonPaletteBase;
+    variant?: NeonPaletteVariant;
+};
+
+/** `waterfall` swaps in the positive/negative/total colors used by waterfall graphs. */
+declare type NeonPaletteVariant = 'default' | 'waterfall';
+
+/**
+ * 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;
+}
+
+/** Points at a single observation by its anchor value and series. */
+declare interface ObservationAnchorInput {
+    /** Stable id of a layer; picks one out when several share the same `(anchorValue, groupValue)` pair. */
+    layerId?: string;
+    /** Value on the main axis (x in cartesian, y in flipped). */
+    anchorValue: DataValue;
+    /** The group value to match if any, otherwise match any group. */
+    groupValue?: DataValue;
+    /** Which point of the matched geom's box to resolve to. Omitted means the geom-natural point. */
+    align?: AnchorAlign;
+}
+
+export declare type Options = Partial<LineOptions & BarOptions & ScatterOptions & ComboOptions & PieOptions & TableOptions>;
+
+/**
+ * Configure a different overflow strategy per direction.
+ */
+declare interface OverflowStrategyConfig {
+    x: PanelOverflowStrategy;
+    y: PanelOverflowStrategy;
+}
+
+/** Palette selector accepted from users; a custom palette is referenced by `id` only. */
+declare type PaletteConfigInput = DefaultPaletteConfig | GraphyPaletteConfig | PastelPaletteConfig | NeonPaletteConfig | MonoPaletteConfig | CustomPaletteInput;
+
+/**
+ * Sparse override map.  Keys are group numbers (1-indexed), values are either a raw
+ * hex value, or a color id to look up in the active custom palette.
+ *
+ * Indexes that are not specified fallback to the palette default.
+ *
+ * If both are set, `hex` wins.  If `id` is set but not found in the active custom palette,
+ * the override is ignored.
+ */
+declare type PaletteOverridesInput = Record<number, {
+    hex?: string;
+    id?: string;
+}>;
+
+/** User-facing palette color scale; defaults to the active theme palette when `palette` is omitted. */
+declare interface PaletteScaleInput {
+    type: 'scale';
+    /** Which aesthetic this scale drives — only color aesthetics accept palettes. */
+    scaledAesthetic: ScaledAestheticKey;
+    scaleType: 'palette';
+    /** Named or custom palette to draw group colors from. */
+    palette?: PaletteConfigInput;
+    /** Per-group color overrides on top of the chosen palette. */
+    overrides?: PaletteOverridesInput;
+}
+
+/** One side of the panel border. */
+declare type PanelBorderEdge = 'top' | 'right' | 'bottom' | 'left';
+
+/**
+ * Configuration for one edge of the panel border.
+ */
+declare interface PanelBorderEdgeConfig {
+    /**
+     * Whether this edge is drawn.
+     * @default true
+     */
+    isVisible: boolean;
+    /**
+     * Line style of this edge.
+     * @default 'dashed'
+     */
+    lineStyle: LineStyleType;
+    /**
+     * Stroke width of this edge in px. null inherits the theme's grid line width.
+     * @default null
+     */
+    lineWidth: number | null;
+    /**
+     * Stroke color of this edge. Accepts any CSS color, including theme tokens
+     * (e.g. `'var(--graphy-grey-70)'`). null inherits the theme's grid line color.
+     * @default null
+     */
+    color: string | null;
+}
+
+/**
+ * Panel configuration. The border is configured per edge; a corner is rounded
+ * only when both edges meeting at it are visible.
+ */
+declare interface PanelConfig {
+    border: Record<PanelBorderEdge, PanelBorderEdgeConfig>;
+    /**
+     * Corner radius of the panel border in px. A corner is rounded only when both edges meeting
+     * at it are visible.
+     * @default 8
+     */
+    cornerRadius: number;
+    /** Per-source, per-axis strategy to use for content that overflows the panel edge. */
+    overflow: {
+        dataLabels: OverflowStrategyConfig;
+        differenceArrows: OverflowStrategyConfig;
+    };
+}
+
+/**
+ * How the panel adapts to content that would otherwise overflow its edge.
+ * - `outside`: the overflowing element lands outside the panel frame and the frame shrinks to
+ *    accomodate it.
+ * - `inside`: the overflowing element stays inside the panel frame and the content inside the
+ *   frame shrinks to accomodate it.
+ * - `none`: no accomodation, content may overflow and overlap with other elements
+ */
+declare type PanelOverflowStrategy = 'outside' | 'inside' | 'none';
+
+declare type PastelPaletteConfig = {
+    type: 'pastel';
+    variant?: PastelPaletteVariant;
+};
+
+/** `waterfall` swaps in the positive/negative/total colors used by waterfall graphs. */
+declare type PastelPaletteVariant = 'default' | 'waterfall';
+
+declare interface PieOptions {
+    /** Where the aggregate total is shown: inside the ring (donut) or outside the graph. */
+    pieTotalPosition?: 'center' | 'outside';
+}
+
+/**
+ * Pinned-number annotation: a marker dot pinned to a single observation. The
+ * renderer's mini view shows the observation's measurement value; hover reveals
+ * the full tooltip (x + y + trend).
+ */
+declare interface PinnedNumberAnnotationInput {
+    id?: string;
+    at: ObservationAnchorInput;
+}
+
+/**
+ * A single position, expressed as a relationship to the graph that re-resolves each compile.
+ *
+ * - `panel`: a fraction of the plot rect (`[0,1]`), top-left origin. Does not snap to data.
+ * - `observation`: pinned to one observation by its `(anchorValue, groupValue)` pair.
+ * - `axis`: see {@link AxisAnchor}.
+ * - `selection`: see {@link SelectionPointAnchor}.
+ * - `annotation`: see {@link AnnotationPointAnchor}.
+ */
+declare type PointAnchorInput = {
+    anchorType: 'panel';
+    x: number;
+    y: number;
+    offset?: AnchorOffset;
+} | {
+    anchorType: 'observation';
+    /** Stable id of a layer; picks one out when several share the same `(anchorValue, groupValue)` pair. */
+    layerId?: string;
+    anchorValue: DataValue;
+    groupValue?: DataValue;
+    align?: AnchorAlign;
+    offset?: AnchorOffset;
+} | AxisAnchor | SelectionPointAnchor | AnnotationPointAnchor;
+
+/**
+ * Point-specific parameters.
+ */
+declare interface PointGeomParams {
+}
+
+/** The paint vocabulary of the point geom — the shared paint plus marker diameter and border. */
+declare type PointStyleDeclarations = Pick<StyleDeclarations, 'color' | 'alpha' | 'saturation' | 'size' | 'borderColor' | 'borderWidth'>;
+
+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;
+}
+
+/**
+ * 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)
+ */
+declare type PositionType = 'stack' | 'dodge' | 'identity' | 'fill';
+
+/**
+ * An observation match condition: a variable test or a logical combination of them.
+ * Shared by every predicated spec feature (highlights, style rules).
+ */
+declare type Predicate = VariablePredicate | LogicalPredicate;
+
+export declare interface ReferenceLines {
+    goalLine?: GoalLine;
+    trendline?: TrendlineType;
+    averageLine?: AverageLine;
+}
+
+/**
+ * An area, expressed as a relationship to the graph.
+ *
+ * - `panel`: a rectangle in panel-rect fractions (`[0,1]`), top-left origin.
+ * - `selection`: see {@link SelectionRegionAnchor}.
+ * - `annotation`: see {@link AnnotationRegionAnchor}.
+ */
+declare type RegionAnchorInput = {
+    anchorType: 'panel';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | SelectionRegionAnchor | AnnotationRegionAnchor;
+
+/***************************************************************
+ * 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;
+}
+
+/**
+ * TipTap-compatible rich text node (no tiptap dependency).
+ */
+declare interface RichTextContent {
+    type?: string;
+    content?: RichTextContent[];
+    text?: string;
+    marks?: Array<{
+        type: string;
+        attrs?: Record<string, unknown>;
+    }>;
+    /**
+     * Per-node attributes the renderer recognizes: `heading.level` (1–3),
+     * `paragraph.textAlign`, and on the `textStyle` mark `color`, `font` (a font
+     * id), and `fontSize` — a number read as `n/10` em. Unrecognized keys are
+     * ignored.
+     */
+    attrs?: Record<string, unknown>;
+}
+
+/**
+ * Rule-specific parameters.
+ *
+ * A rule is a single reference line. The renderer reads one observation —
+ * `data.getFirst()` — via `getX`/`getY`. Orientation: horizontal when the layer
+ * maps `y` (a constant-y line spanning the panel width), vertical otherwise;
+ * under a flipped coord system the orientation inverts with the axes.
+ */
+declare interface RuleGeomParams {
+    /** Optional inline text label rendered alongside the line. */
+    label?: string;
+    labelPosition: RuleLabelPosition;
+}
+
+/**
+ * Where the optional inline label is anchored along a reference line.
+ */
+declare type RuleLabelPosition = 'start' | 'end';
+
+/**
+ * The paint vocabulary of the rule geom.
+ */
+declare type RuleStyleDeclarations = Pick<StyleDeclarations, 'color' | 'strokeWidth' | 'lineType'>;
+
+/**
+ * Identifiers for scales. Superset of AestheticKey — includes `ySecondary`
+ * which is a scale aesthetic key but NOT an aesthetic (layers still map to `y`).
+ */
+declare type ScaledAestheticKey = ScaledPositionAestheticKey | ScaledVisualAestheticKey;
+
+/** Scale keys whose output is a spatial coordinate. `ySecondary` is the optional second y axis. */
+declare type ScaledPositionAestheticKey = 'x' | 'y' | 'ySecondary';
+
+/** Scale keys whose output is a visual channel rather than a position. */
+declare type ScaledVisualAestheticKey = 'color' | 'size' | 'alpha' | 'strokeWidth' | 'lineType';
+
+/**
+ * Union type for all possible scale specifications (including inferred, pre-resolution).
+ */
+declare type ScaleInput = ContinuousScaleInput | DiscreteScaleInput | PaletteScaleInput | DatetimeScaleInput | IdentityScaleInput | InferredScaleInput;
+
+/**
+ * Mathematical transformation for continuous scales.
+ *
+ * - `'linear'` — No transformation applied
+ * - `'log'` — Base-10 logarithmic scale
+ * - `'sqrt'` — Square root scale
+ */
+declare type ScaleTransformType = 'linear' | 'log' | 'sqrt';
+
+declare interface ScatterOptions {
+    pointSize?: number | 'auto';
+}
+
+/** Friendly aliases for the ColorBrewer diverging codes: `'red-blue'` resolves to the same ramp as `'RdBu'`. */
+declare const SCHEME_ALIASES: {
+    readonly 'red-blue': "RdBu";
+    readonly 'brown-teal': "BrBG";
+    readonly 'purple-orange': "PuOr";
+    readonly spectral: "Spectral";
+};
+
+/** A human-readable alias for a cryptic ColorBrewer diverging code (e.g. `'red-blue'` → `'RdBu'`). */
+declare type SchemeAlias = keyof typeof SCHEME_ALIASES;
+
+/**
+ * Overrides for the optional second y axis. Sparse where `x` and `y` are fully resolved: a field
+ * left unset is inherited at compile time — `position` from the side opposite `y`, `isVisible`,
+ * `grid` and `ticks` from `y` itself, and `label` from no label at all. An absent override
+ * therefore means "mirror the primary axis", which stops being expressible once a field is pinned.
+ */
+declare type SecondaryAxisOverride = DeepPartial<YAxisConfig>;
+
+/**
+ * A point at the box of every observation matching `predicate` (a {@link Predicate} — the same
+ * matcher language highlights use), reduced to the box-point named by `align`. Dropped when nothing
+ * matches. Nothing to resolve, so the input and resolved unions share this type.
+ */
+declare interface SelectionPointAnchor {
+    anchorType: 'selection';
+    predicate: Predicate;
+    align: AnchorAlign;
+    offset?: AnchorOffset;
+}
+
+/**
+ * The tight bounding box of every observation matching `predicate` (a {@link Predicate} — the same
+ * matcher language highlights use), grown by `padding`. Dropped when nothing matches. Nothing to
+ * resolve, so the input and resolved unions share this type.
+ */
+declare interface SelectionRegionAnchor {
+    anchorType: 'selection';
+    predicate: Predicate;
+    /**
+     * Padding around the box: a number pads both axes in panel fractions, an {@link AnchorOffset} pads
+     * each axis in its `unit` (`px` padding is applied by the runtime resolution pass).
+     */
+    padding?: number | AnchorOffset;
+}
+
+/**
+ * Sequential colormap names from `d3-scale-chromatic`. Matplotlib schemes are lowercase (`viridis`),
+ * ColorBrewer schemes keep Brewer's capitalisation (`Blues`) — lookup is case-insensitive, so casing only
+ * drives autocomplete. `viridis`/`cividis` are perceptually uniform and colour-vision-deficiency safe.
+ */
+declare const SEQUENTIAL_SCHEME_NAMES: readonly ["viridis", "magma", "inferno", "plasma", "cividis", "turbo", "Blues", "Greens", "Greys", "Oranges", "Purples", "Reds"];
+
+declare type SequentialSchemeName = (typeof SEQUENTIAL_SCHEME_NAMES)[number];
+
+/** Config for styling a specific series. */
+export declare interface SeriesStyle {
+    /** Id of a slot in the active palette; takes precedence over the palette's default assignment. */
+    paletteColorId?: string;
+    /** Explicit color that overrides any palette slot for this series. */
+    customColor?: string;
+    fillStyle?: 'solid' | 'hatched';
+    lineStyle?: 'solid' | 'dashed' | 'dotted';
+}
+
+/**
+ * Rectangle annotation. Its area is positioned by a {@link RegionAnchorInput} so it
+ * re-resolves each compile (re-flows on resize, tracks data when bound).
+ */
+declare interface ShapeInput {
+    id?: string;
+    kind?: ShapeKind;
+    /** Draw beneath the geoms (background) or on top (foreground). */
+    zOrder?: AnnotationZOrder;
+    /** The area this shape fills. */
+    region: RegionAnchorInput;
+    fillColor?: string;
+    /** Fill alpha, 0 (transparent) to 1 (opaque). */
+    fillOpacity?: number;
+    strokeWidth?: number;
+    /** null falls back to the theme `defaultAnnotationShapeStroke`. */
+    strokeColor?: string | null;
+}
+
+/** The geometry a shape annotation draws. */
+declare type ShapeKind = 'rectangle';
+
+/**
+ * Regression methods supported by the `smooth` stat.
+ */
+declare type SmoothMethod = 'linear' | 'loess' | 'exponential' | 'logarithmic' | 'quadratic' | 'power' | 'polynomial';
+
+/**
+ * User-facing input for the `smooth` stat (params optional).
+ */
+declare interface SmoothStatInput {
+    type: 'smooth';
+    method: SmoothMethod;
+    /** Polynomial order — only meaningful when `method: 'polynomial'`. */
+    order?: number;
+    /** LOESS bandwidth — only meaningful when `method: 'loess'`. */
+    bandwidth?: number;
+}
+
+/***************************************************************
+ * 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;
+}
+
+/** Data-source attribution shown under the caption. */
+declare interface SourceContent {
+    label?: string;
+    url?: string;
+}
+
+/**
+ * The canonical spec type — plain JSON, serializable. Data is provided separately
+ * (as a `Data` value to {@link compile}, or as a prop to `<GraphProvider>`).
+ */
+declare interface SpecInput {
+    mapping: AesMapping;
+    layers: LayerInput[];
+    scales: ScaleInput[];
+    transforms: AnyTransformInput[];
+    highlights: HighlightInput[];
+    styles?: StylesheetInput;
+    annotations?: AnnotationsInput;
+    coords?: CoordInput;
+    config: ConfigInput;
+}
+
+/**
+ * User-facing stat input — either a {@link StatName} string shorthand or an object spec.
+ */
+declare type StatInput = IdentityStatSpec | CountStatSpec | SmoothStatInput | MeanStatSpec;
+
+/**
+ * Statistical transformation applied to data before rendering.
+ *
+ * - `'identity'` — No transformation, data passed through unchanged
+ * - `'count'` — Count the number of observations per x-axis value
+ * - `'smooth'` — Fit a regression curve through `(x, y)` and emit the fitted points
+ * - `'mean'` — Reduce the dataset to a single observation holding the mean of `y`
+ */
+declare type StatName = 'identity' | 'count' | 'smooth' | 'mean';
+
+/**
+ * Sticker annotation: a built-in emoji-like image positioned by a {@link PointAnchorInput}.
+ */
+declare interface StickerAnnotationInput {
+    id?: string;
+    at: PointAnchorInput;
+    sticker: StickerId;
+}
+
+/** Identifier of a built-in sticker image, resolved by the renderer's sticker catalogue. */
+declare type StickerId = string;
+
+/**
+ * The runtime states a style entry can scope to. States are paint-only — they never feed layout.
+ *
+ * - `dimmed` — de-emphasized: a highlight matched elsewhere, or the pointer hovers another element.
+ * - `hovered` — the pointer is on the element.
+ */
+declare const STYLE_STATES: readonly ["dimmed", "hovered"];
+
+/**
+ * A color-valued declaration in any of its authored forms: a CSS color literal, an inline
+ * light-dark pair, or a reference into the stylesheet's token table.
+ */
+declare type StyleColorValue = string | LightDarkColor | StyleTokenRef;
+
+/** The declarations an entry can author, color-valued properties in any {@link StyleColorValue} form. */
+declare type StyleDeclarations = StyleDeclarationsFor<StyleColorValue>;
+
+/**
+ * Every style property any geom kind understands, in one flat shape. Which subset a given entry may
+ * declare is the kind's vocabulary — the per-kind `Pick` aliases below; the compile stage drops
+ * declarations outside the entry's vocabulary. The parameter is the shape of the color-valued
+ * properties: authored entries take a {@link StyleColorValue}, resolved reads yield a single string.
+ *
+ * - `color` — fill color.
+ * - `alpha` — fill opacity, `0..1`.
+ * - `saturation` — saturation multiplier, `0..1`; `0` is grey.
+ * - `borderRadius` — corner rounding token, resolved to pixels by the bar recipes.
+ * - `borderColor` — border stroke color. A bar draws a border only when this resolves; a point marker
+ *   always has one (built-in white).
+ * - `borderWidth` — border stroke width in pixels; `0` is an explicit no-border.
+ * - `strokeWidth` — path stroke width in pixels for line and area outlines.
+ * - `lineType` — dash pattern of a line or area outline.
+ * - `strokeAlpha` — area outline opacity, `0..1`, independent of the fill's `alpha`.
+ * - `fillAlpha` — peak opacity of the gradient wash beneath a line, `0..1`. Undeclared draws no wash.
+ * - `size` — point marker diameter in pixels.
+ */
+declare interface StyleDeclarationsFor<ColorValue> {
+    color?: ColorValue;
+    alpha?: number;
+    saturation?: number;
+    borderRadius?: BorderRadiusToken;
+    borderColor?: ColorValue;
+    borderWidth?: number;
+    strokeWidth?: number;
+    lineType?: LineStyleType;
+    strokeAlpha?: number;
+    fillAlpha?: number;
+    size?: number;
+}
+
+/**
+ * One entry in a stylesheet list — the serialized shape the {@link style} builders emit. `select`
+ * addresses what the entry styles, `when` holds the conditions under which it applies, and `id` is an
+ * optional stable identity carried into diagnostics, so tooling can point at "that entry" across
+ * edits. Within a list, order is specificity: the last matching entry that declares a property wins.
+ */
+declare type StyleRule = {
+    id?: string;
+    select: {
+        target: 'geom';
+        kind?: undefined;
+        layer?: string;
+    };
+    declarations: GeomStyleDeclarations;
+    when?: WhenClause;
+} | {
+    [K in keyof KindStyleDeclarationsMap]: {
+        id?: string;
+        select: {
+            target: 'geom';
+            kind: K;
+            layer?: string;
+        };
+        declarations: KindStyleDeclarationsMap[K];
+        when?: WhenClause;
+    };
+}[keyof KindStyleDeclarationsMap];
+
+/**
+ * A stylesheet — the reusable shape a preset or theme ships as, and the body of the pipeable
+ * {@link StylesheetInput}. `defaults` apply only where no mapped aesthetic decided a value;
+ * `overrides` replace what one decided. `tokens` names colors entries reference via {@link token}.
+ * `extends` composes other stylesheets under this one: tokens merge name-by-name, lists
+ * concatenate, later wins.
+ */
+declare interface Stylesheet {
+    extends?: Stylesheet[];
+    tokens?: StyleTokenTable;
+    defaults?: StyleRule[];
+    overrides?: StyleRule[];
+}
+
+/** The pipeable stylesheet item: a {@link Stylesheet} tagged for `pipe`. */
+declare interface StylesheetInput extends Stylesheet {
+    type: 'styles';
+}
+
+declare type StyleState = (typeof STYLE_STATES)[number];
+
+/** The serialized form of a {@link token} reference. */
+declare interface StyleTokenRef {
+    token: string;
+}
+
+/** The stylesheet's token table, mapping the names {@link token} references to their colors. */
+declare type StyleTokenTable = Record<string, StyleTokenValue>;
+
+/** A named color in the stylesheet's token table: one literal or a light-dark pair. */
+declare type StyleTokenValue = string | LightDarkColor;
+
+declare interface TableOptions {
+    /** Relative widths per column, keyed by column key; values are normalized into fractions. */
+    tableColumnRatios?: Record<string, number>;
+}
+
+/** How a text annotation's background fill is applied: faded into the plot or fully opaque. */
+declare type TextAnnotationBackgroundColorStyle = 'fade' | 'opaque';
+
+/**
+ * Rich-text annotation positioned by a {@link PointAnchorInput}; `width` is a fraction of the plot
+ * rect and the height is intrinsic to the rendered content.
+ */
+declare interface TextAnnotationInput {
+    id?: string;
+    /** Rich-text body to render. */
+    content: RichTextContent;
+    /** The point the text is positioned at; `align` decides which point of the text's box sits here. */
+    at: PointAnchorInput;
+    /** 0..1 of plot width. */
+    width: number;
+    /** Which point of the text's own box sits at `at`. Defaults to `center`. */
+    align?: AnchorAlign;
+    /** null falls back to a transparent background. */
+    backgroundColor?: string | null;
+    /** Whether the background fill fades into the plot or is fully opaque. */
+    backgroundColorStyle?: TextAnnotationBackgroundColorStyle;
+}
+
+/** A text value — plain string or structured rich text. */
+declare type TextContent = string | RichTextContent;
+
+/**
+ * Discriminated union of the built-in transform inputs, keyed on `transformType`. Use
+ * {@link AnyTransformInput} where a plugin-contributed transform may also appear.
+ */
+declare type TransformInput = ReshapeTransformInput | FilterTransformInput | SortTransformInput | AggregateTransformInput | ConstantTransformInput;
+
+export declare type TrendlineType = 'linear' | 'loess' | 'exponential' | 'logarithmic' | 'quadratic' | 'power' | 'polynomial';
+
+/**
+ * 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;
+}
+
+/**
+ * Variable mapping - references a column in the data
+ */
+declare interface VariableMapping {
+    variable: string;
+}
+
+/** A type alias for variable names. */
+declare type VariableName = string;
+
+/**
+ * Predicates over the layer's post-transform variables.
+ *
+ * `lt`, `lte`, `gt`, `gte`, and `range` accept `DataValue`s and are coerced at
+ * evaluation time by the referenced variable's `DataType`. Ordering operators
+ * on a categorical variable are a resolve-time validation error.
+ */
+declare type VariablePredicate = {
+    variable: VariableName;
+    eq: DataValue;
+} | {
+    variable: VariableName;
+    oneOf: DataValue[];
+} | {
+    variable: VariableName;
+    lt: DataValue;
+} | {
+    variable: VariableName;
+    lte: DataValue;
+} | {
+    variable: VariableName;
+    gt: DataValue;
+} | {
+    variable: VariableName;
+    gte: DataValue;
+} | {
+    variable: VariableName;
+    range: [DataValue, DataValue];
+};
+
+/**
+ * The conditions under which a style entry applies — facts that need data or runtime context, as
+ * opposed to the structural address in {@link StyleSelect}.
+ *
+ * - `where` — match observations over the layer's post-transform variables. Absent, every observation
+ *   matches.
+ * - `state` — apply only while the renderer reads with this {@link StyleState} active. Absent, the
+ *   entry is stateless.
+ */
+declare interface WhenClause {
+    where?: Predicate;
+    state?: StyleState;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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.
+ */
+declare type YScaleType = 'primary' | 'secondary';
+
+export { }