graphein 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -764,6 +764,269 @@ type FilterClause = {
     param: string;
 } | LiteralPredicate;
 
+/**
+ * Declarative data transforms.
+ *
+ * A `transform` is an ordered pipeline that reshapes the `data` array *inside*
+ * the spec — so an agent fixes data shape by editing validatable JSON instead of
+ * pre-massaging rows in code. Every transform is plain JSON (no functions) and
+ * pure: `applyTransforms` never mutates its input.
+ *
+ * The pipeline is applied before the chart model is built (and before any
+ * cross-filter selection), so encodings can reference fields the transforms
+ * produce (e.g. an `aggregate` output column).
+ */
+
+/** One aggregation within an {@link AggregateTransform}. */
+interface AggregateOp {
+    /** Aggregation operation. `count` needs no `field`. */
+    op: AggOp;
+    /** Source column to aggregate (omit only for `count`). */
+    field?: string;
+    /** Output column receiving the aggregated value. */
+    as: string;
+}
+/**
+ * Group rows by `groupby` and summarize each group into a single output row.
+ * Omitting `groupby` collapses the whole dataset into one row.
+ */
+interface AggregateTransform {
+    aggregate: AggregateOp[];
+    groupby?: string[];
+}
+/**
+ * Bucket a quantitative `bin` field into evenly sized bins. Drives the histogram
+ * chart and any "distribution" view without pre-binning in user code.
+ */
+interface BinTransform {
+    /** Numeric column to bin. */
+    bin: string;
+    /**
+     * Output column(s). A single name receives the bin **start**; a `[start, end]`
+     * pair receives both edges (handy for histogram bars and range labels).
+     */
+    as: string | [string, string];
+    /** Target bin count; a "nice" step approximates it. Default 10. */
+    maxbins?: number;
+    /** Explicit bin width. Overrides `maxbins` when set. */
+    step?: number;
+    /** Restrict binning to this `[min, max]`; values outside get a `null` bin. */
+    extent?: [number, number];
+    /** Snap the bin domain to round numbers (default true). */
+    nice?: boolean;
+}
+/**
+ * A declarative, JSON predicate for {@link FilterTransform}. Leaf predicates test
+ * one `field`; `and` / `or` / `not` compose them. Comparisons coerce numerically
+ * (numbers first, then dates), so temporal bounds work as ISO strings.
+ */
+type FilterPredicate = {
+    field: string;
+    equals: unknown;
+} | {
+    field: string;
+    ne: unknown;
+} | {
+    field: string;
+    oneOf: unknown[];
+} | {
+    field: string;
+    range: [number | string, number | string];
+} | {
+    field: string;
+    contains: string;
+} | {
+    field: string;
+    gt: number | string;
+} | {
+    field: string;
+    gte: number | string;
+} | {
+    field: string;
+    lt: number | string;
+} | {
+    field: string;
+    lte: number | string;
+} | {
+    field: string;
+    valid: boolean;
+} | {
+    and: FilterPredicate[];
+} | {
+    or: FilterPredicate[];
+} | {
+    not: FilterPredicate;
+};
+/** Keep only rows matching `filter`. */
+interface FilterTransform {
+    filter: FilterPredicate;
+}
+/**
+ * Gather several columns into key/value rows (wide → long). Each input row is
+ * repeated once per folded column. Use it to turn a wide table into a tidy one a
+ * `series` channel can split.
+ */
+interface FoldTransform {
+    fold: string[];
+    /** Output `[key, value]` column names. Default `['key', 'value']`. */
+    as?: [string, string];
+}
+/** Calendar unit a {@link TimeUnitTransform} truncates a timestamp to. */
+type TimeUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
+/**
+ * Truncate a temporal `field` to the start of a calendar unit (e.g. month),
+ * writing a `Date` to `as`. Lets agents aggregate by period without date math.
+ */
+interface TimeUnitTransform {
+    timeUnit: TimeUnit;
+    field: string;
+    as: string;
+}
+/**
+ * Derive a new column from a **safe expression** evaluated per row, writing the
+ * result to `as`. The expression language supports arithmetic, comparison,
+ * logical and ternary operators, string concatenation, member access
+ * (`datum['my field']`), and a whitelist of functions (e.g. `round`, `lower`,
+ * `if`, `coalesce`). Bare identifiers reference row columns. It is parsed to an
+ * AST and evaluated with **no `eval`/`Function`** and no access to globals.
+ */
+interface CalculateTransform {
+    calculate: string;
+    as: string;
+}
+/**
+ * A single declarative transform step. Distinguished by its operator key
+ * (`aggregate` / `bin` / `filter` / `fold` / `timeUnit` / `calculate`); a step
+ * carries exactly one. Applied in array order by {@link applyTransforms}.
+ */
+type Transform = AggregateTransform | BinTransform | FilterTransform | FoldTransform | TimeUnitTransform | CalculateTransform;
+/** Operator keys that identify a transform step (one per step). */
+declare const TRANSFORM_KINDS: readonly ["aggregate", "bin", "filter", "fold", "timeUnit", "calculate"];
+/** Supported {@link TimeUnit} values, for validation/UX. */
+declare const TIME_UNITS: readonly TimeUnit[];
+
+/** The transform pipeline: dispatch each step by its operator key, in order. */
+
+/** Apply a single {@link Transform} step, returning a new array (never mutating). */
+declare function applyTransform(transform: Transform, data: Datum[]): Datum[];
+/**
+ * Apply a transform pipeline in array order. Pure — the input array and rows are
+ * never mutated. Returns the original reference unchanged when there are no
+ * transforms, so callers can cheaply detect a no-op.
+ */
+declare function applyTransforms(transforms: Transform[] | undefined, data: Datum[]): Datum[];
+
+/** The `filter` transform: keep rows satisfying a declarative JSON predicate. */
+
+/**
+ * Compile a {@link FilterPredicate} into a fast `row → boolean` tester, hoisting
+ * accessors and lookup sets out of the per-row path. An unrecognized leaf shape
+ * compiles to "match nothing" (validation flags it as an error first).
+ */
+declare function compilePredicate(pred: FilterPredicate): (row: Datum) => boolean;
+/** Apply a {@link FilterTransform}, returning a new array of matching rows. */
+declare function applyFilter(transform: FilterTransform, data: Datum[]): Datum[];
+
+/** The `aggregate` transform: group rows and summarize each group into one row. */
+
+/**
+ * Apply an {@link AggregateTransform}. Groups are emitted in first-seen order and
+ * keep the **original** group-key values (not stringified). With no `groupby`,
+ * the whole dataset collapses to a single summary row.
+ */
+declare function applyAggregate(transform: AggregateTransform, data: Datum[]): Datum[];
+
+/** The `bin` transform: bucket a quantitative field into evenly sized bins. */
+
+interface BinLayout {
+    /** Lower edge of the first bin. */
+    start: number;
+    /** Bin width. */
+    step: number;
+    /** Number of bins. */
+    count: number;
+}
+/**
+ * Choose a bin layout for `values`. Honors an explicit `step`, otherwise picks a
+ * "nice" step approximating `maxbins` (default 10). Returns `null` when there is
+ * no finite data to bin.
+ */
+declare function computeBins(values: readonly number[], opts?: {
+    maxbins?: number;
+    step?: number;
+    extent?: [number, number];
+    nice?: boolean;
+}): BinLayout | null;
+/**
+ * Apply a {@link BinTransform}, writing the bin start (and optional end) onto each
+ * row. Rows whose value is non-numeric or outside an explicit `extent` get `null`.
+ */
+declare function applyBin(transform: BinTransform, data: Datum[]): Datum[];
+
+/** The `fold` transform: gather several columns into key/value rows (wide → long). */
+
+/**
+ * Apply a {@link FoldTransform}. Each input row is repeated once per folded
+ * column, carrying all original fields plus the `[key, value]` pair (default
+ * names `key` / `value`).
+ */
+declare function applyFold(transform: FoldTransform, data: Datum[]): Datum[];
+
+/** The `timeUnit` transform: truncate a timestamp to the start of a calendar unit. */
+
+/** Truncate `date` to the start of `unit` (local time). */
+declare function truncateTo(date: Date, unit: TimeUnit): Date;
+/**
+ * Apply a {@link TimeUnitTransform}, writing a truncated `Date` to `as`. Rows whose
+ * field can't be parsed as a date receive `null`.
+ */
+declare function applyTimeUnit(transform: TimeUnitTransform, data: Datum[]): Datum[];
+
+/**
+ * `calculate` transform: derive a new column from a safe expression evaluated
+ * per row. The expression is compiled once and never uses `eval`/`Function`.
+ */
+
+/** Apply a {@link CalculateTransform}, returning new rows with the `as` column. */
+declare function applyCalculate(transform: CalculateTransform, data: Datum[]): Datum[];
+
+/** Error thrown by the `calculate` expression tokenizer/parser/evaluator. */
+declare class ExpressionError extends Error {
+    /** Source offset where the problem was detected, when known. */
+    readonly pos: number | undefined;
+    constructor(message: string, pos?: number);
+}
+
+/**
+ * Evaluator for the `calculate` AST. Pure and sandboxed: the only callable names
+ * are the {@link FUNCTIONS} whitelist, member access is guarded against prototype
+ * keys, and there is no access to `eval`, `Function`, globals, or row mutation.
+ * All functions are deterministic (no `now()`/`random()`), per the transform
+ * determinism convention.
+ */
+
+/** Names the parser may treat as callable — exposed for validation. */
+declare const FUNCTION_NAMES: readonly string[];
+
+/**
+ * Safe `calculate` expression engine — public surface.
+ *
+ * `compileExpression(src)` parses once and returns a pure `(row) => value`
+ * function used by the calculate transform. No `eval`/`Function` is ever used;
+ * see {@link evaluate} for the sandbox guarantees.
+ */
+
+/** Parse `src` once; returns a reusable, pure evaluator over a row. */
+declare function compileExpression(src: string): (row: Datum) => unknown;
+/**
+ * Validate an expression's syntax without evaluating it. Returns an error message
+ * (and source offset) when the expression cannot be parsed, else `null`.
+ */
+declare function checkExpression(src: string): {
+    message: string;
+    pos: number | undefined;
+} | null;
+
 /**
  * Graphein declarative chart specs.
  *
@@ -902,6 +1165,13 @@ interface SketchConfig {
 interface BaseSpec {
     /** Row-oriented (tidy) data. Required for all charts/tables. */
     data?: Datum[];
+    /**
+     * Declarative data transforms applied to `data` (in order) before the chart is
+     * built — aggregate, bin, filter, fold, timeUnit. Reshape data *inside* the
+     * spec instead of pre-massaging the array, so encodings can reference fields
+     * the pipeline produces. Pure JSON; see {@link Transform}.
+     */
+    transform?: Transform[];
     /** Theme name ('light' | 'dark') or a partial override object. */
     theme?: ThemeInput;
     dimensions?: Dimensions;
@@ -946,6 +1216,103 @@ interface BaseSpec {
     filter?: FilterClause[];
 }
 type CurveType = 'linear' | 'monotone' | 'step' | 'stepBefore' | 'stepAfter' | 'catmullRom';
+/**
+ * A reference annotation overlaid on a cartesian chart: a single reference
+ * **line** at a value, or a filled **band** / threshold **zone** between two
+ * values. Useful for targets, goals, averages, control limits, and "danger"
+ * ranges. Drawn over the gridlines and data marks; labels render in the overlay.
+ */
+interface Annotation {
+    /**
+     * What to draw. Omit to infer: a `line` when `value` is set, a `band` when
+     * `from`/`to` are set. `zone` is a band — a semantic alias for a threshold band.
+     * A `point` marks a single (`x`, `y`) data coordinate with a labeled dot.
+     */
+    type?: 'line' | 'band' | 'zone' | 'point';
+    /**
+     * Which axis the value(s) are measured against. `y` (default) draws a
+     * horizontal line / full-width band; `x` draws a vertical line / full-height band.
+     */
+    axis?: 'x' | 'y';
+    /** Reference value for a `line` (number, category, or date — matching the axis). */
+    value?: number | string | Date;
+    /** Start of the span for a `band`/`zone`. */
+    from?: number | string | Date;
+    /** End of the span for a `band`/`zone`. */
+    to?: number | string | Date;
+    /** X coordinate of a `point` callout (a data value on the x-axis). */
+    x?: number | string | Date;
+    /** Y coordinate of a `point` callout (a data value on the y-axis). */
+    y?: number | string | Date;
+    /** Marker radius in pixels for a `point` (default 3.5). */
+    markerRadius?: number;
+    /** Short text label drawn beside the annotation. */
+    label?: string;
+    /** Stroke (line) / fill (band) color. Defaults to a muted theme color. */
+    color?: string;
+    /** Line width in pixels for a `line` (default 1.5). */
+    strokeWidth?: number;
+    /** Dash pattern for the stroke; `[]` is solid. Lines/bands default to dashed. */
+    strokeDash?: number[];
+    /** Fill opacity for a `band`/`zone` (0..1, default 0.12). */
+    fillOpacity?: number;
+    /** Where the label anchors along the annotation (default `end`). */
+    labelPosition?: 'start' | 'middle' | 'end';
+}
+/**
+ * Which automatic data insights to mark on a cartesian plot. Enable via a
+ * chart's `insights` field — `true` marks the max and min; an object opts into
+ * specific callouts. The library derives the points and draws labeled markers,
+ * so an agent never has to reason out (or hardcode) where the peak is.
+ */
+interface InsightOptions {
+    /** Mark the maximum point (default true). */
+    max?: boolean;
+    /** Mark the minimum point (default true). */
+    min?: boolean;
+    /** Mark statistical outliers beyond the 1.5×IQR fences (default false). */
+    outliers?: boolean;
+}
+/**
+ * A derived **trendline** (line of best fit) overlaid on a cartesian plot.
+ * Enable via a chart's `trendline` field — `true` fits a single linear
+ * regression; an object configures the fit and its styling. The library
+ * computes the regression from the plotted rows, so an agent never has to
+ * derive slope/intercept coordinates by hand. Requires a continuous or temporal
+ * x-axis (scatter, line, area) — it is meaningless on a categorical/band axis.
+ */
+interface TrendlineConfig {
+    /** Fit method. Currently `'linear'` (ordinary least squares). */
+    method?: 'linear';
+    /**
+     * Fit a separate line per color/series group. Defaults to `true` when the
+     * chart splits into multiple series, `false` (one overall fit) otherwise.
+     */
+    groupBy?: boolean;
+    /** Draw an `R²=…` label at the end of each fitted line (default false). */
+    label?: boolean;
+    /** Line color. Defaults to the series color (grouped) or a muted ink. */
+    color?: string;
+    /** Line width in px (default 2). */
+    strokeWidth?: number;
+    /** Dash pattern; `[]` is solid (the default). */
+    strokeDash?: number[];
+}
+/**
+ * **Faceting** (small multiples): split a chart into a trellis grid of panels,
+ * one per distinct value of a field, all sharing identical x/y/color scales so
+ * the panels are directly comparable. Enable via a chart's `facet` field — a
+ * single field reference yields a whole comparison grid, which is why it is so
+ * agent-friendly. Supported on `line`, `area`, `bar`, and `scatter`.
+ */
+interface FacetConfig {
+    /** The field whose distinct values become one panel each. */
+    field: string;
+    /** Number of grid columns. Defaults to roughly √n, capped for readability. */
+    columns?: number;
+    /** Order the panels by their facet value (default `ascending`). */
+    sort?: 'ascending' | 'descending' | 'none';
+}
 interface LineSpec extends BaseSpec {
     type: 'line';
     encoding: Encoding & {
@@ -957,6 +1324,14 @@ interface LineSpec extends BaseSpec {
     points?: boolean;
     /** Fill the area under the line. */
     area?: boolean;
+    /** Reference lines, bands, and threshold zones overlaid on the plot. */
+    annotations?: Annotation[];
+    /** Auto-mark notable data points (`true` = max + min). See {@link InsightOptions}. */
+    insights?: boolean | InsightOptions;
+    /** Overlay a linear line of best fit. See {@link TrendlineConfig}. */
+    trendline?: boolean | TrendlineConfig;
+    /** Split into a trellis grid of small multiples. See {@link FacetConfig}. */
+    facet?: FacetConfig;
 }
 interface AreaSpec extends BaseSpec {
     type: 'area';
@@ -967,6 +1342,14 @@ interface AreaSpec extends BaseSpec {
     curve?: CurveType;
     /** Stack multiple series. */
     stack?: boolean;
+    /** Reference lines, bands, and threshold zones overlaid on the plot. */
+    annotations?: Annotation[];
+    /** Auto-mark notable data points (`true` = max + min). See {@link InsightOptions}. */
+    insights?: boolean | InsightOptions;
+    /** Overlay a linear line of best fit. See {@link TrendlineConfig}. */
+    trendline?: boolean | TrendlineConfig;
+    /** Split into a trellis grid of small multiples. See {@link FacetConfig}. */
+    facet?: FacetConfig;
 }
 interface BarSpec extends BaseSpec {
     type: 'bar';
@@ -980,6 +1363,12 @@ interface BarSpec extends BaseSpec {
     /** Group series side-by-side (default when `series` present and not stacked). */
     group?: boolean;
     cornerRadius?: number;
+    /** Reference lines, bands, and threshold zones overlaid on the plot. */
+    annotations?: Annotation[];
+    /** Auto-mark notable data points (`true` = top + bottom category). See {@link InsightOptions}. */
+    insights?: boolean | InsightOptions;
+    /** Split into a trellis grid of small multiples. See {@link FacetConfig}. */
+    facet?: FacetConfig;
 }
 interface ScatterSpec extends BaseSpec {
     type: 'scatter';
@@ -987,6 +1376,87 @@ interface ScatterSpec extends BaseSpec {
         x: FieldDef;
         y: FieldDef;
     };
+    /** Reference lines, bands, and threshold zones overlaid on the plot. */
+    annotations?: Annotation[];
+    /** Overlay a linear line of best fit. See {@link TrendlineConfig}. */
+    trendline?: boolean | TrendlineConfig;
+    /** Split into a trellis grid of small multiples. See {@link FacetConfig}. */
+    facet?: FacetConfig;
+}
+/** The mark a single combo layer draws. */
+type ComboMark = 'line' | 'bar' | 'area' | 'scatter';
+/**
+ * One layer of a {@link ComboSpec}: a mark plus the measure it plots on `y`. All
+ * layers share the combo's `x`. A layer can be measured against the primary
+ * (`left`) y-axis or an independent secondary (`right`) axis — the basis of a
+ * dual-axis bar+line chart.
+ */
+interface ComboLayer {
+    /** Which mark to draw for this layer. */
+    mark: ComboMark;
+    /** The measure (and optional per-layer formatting) plotted on `y`. */
+    encoding: {
+        y: FieldDef;
+    };
+    /** Which y-axis this layer is measured against. Defaults to `left`. */
+    axis?: 'left' | 'right';
+    /** Curve interpolation for `line`/`area` layers. */
+    curve?: CurveType;
+    /** Show point markers (line/area layers). */
+    points?: boolean;
+    /** Fill under the line (line layers — equivalent to an `area` mark). */
+    area?: boolean;
+    /** Bar corner radius (bar layers). */
+    cornerRadius?: number;
+    /** Legend label for the layer. Defaults to the y field's title or name. */
+    name?: string;
+    /** Override the layer's color (otherwise drawn from the theme palette). */
+    color?: string;
+}
+/**
+ * Combo / dual-axis chart: composes multiple cartesian {@link ComboLayer}s over a
+ * shared `x` axis — the canonical BI "bar + line" view. Layers may target a primary
+ * (`left`) or secondary (`right`) y-axis, each with its own independent scale.
+ * Bars require a categorical `x`; lines/areas/points align to category centers.
+ */
+interface ComboSpec extends BaseSpec {
+    type: 'combo';
+    encoding: {
+        x: FieldDef;
+    };
+    layers: ComboLayer[];
+}
+/** Binning controls for a {@link HistogramSpec} (mirror the `bin` transform). */
+interface HistogramBin {
+    /** Target bin count (approximate — a "nice" step is chosen). Default 10. */
+    maxbins?: number;
+    /** Explicit bin width (overrides `maxbins`). */
+    step?: number;
+    /** Restrict binning to `[min, max]`; values outside are dropped. */
+    extent?: [number, number];
+    /** Snap bin edges to nice round numbers (default true). */
+    nice?: boolean;
+}
+/**
+ * Histogram: bins a single quantitative field and draws the per-bin frequency as
+ * gapless bars. Binning happens inside the chart (reusing the `bin` transform), so
+ * an agent passes raw observations — no manual pre-binning. Bar height is the bin
+ * count by default, or a probability density (area sums to 1) when `density:true`.
+ */
+interface HistogramSpec extends BaseSpec {
+    type: 'histogram';
+    /** `x` is the quantitative field to bin (also carries the axis title/format). */
+    encoding: {
+        x: FieldDef;
+    };
+    /** Binning controls (default ~10 nice bins, or an explicit `step`/`extent`). */
+    bin?: HistogramBin;
+    /** Normalize bar heights to a probability density (area sums to 1). */
+    density?: boolean;
+    /** Bar colour (defaults to the first theme palette colour). */
+    color?: string;
+    /** Bar corner radius. */
+    cornerRadius?: number;
 }
 interface PieSpec extends BaseSpec {
     type: 'pie';
@@ -1073,6 +1543,173 @@ interface KpiSpec extends BaseSpec {
         field: string;
     };
 }
+/**
+ * Treemap — part-to-whole as nested rectangles sized by a measure. Pass tidy
+ * rows (one per leaf); the area of each tile is proportional to `value`. An
+ * optional `group` field nests leaves under parent tiles (one level), and
+ * `color` overrides the default per-group/leaf fill (numeric → sequential scale,
+ * categorical → palette).
+ */
+interface TreemapSpec extends BaseSpec {
+    type: 'treemap';
+    encoding: Encoding & {
+        /** Leaf tile label + identity. */
+        category: FieldDef;
+        /** Numeric field sizing each tile's area (summed per leaf). */
+        value: FieldDef;
+        /** Optional parent grouping → nested parent tiles (one level deep). */
+        group?: FieldDef;
+        /** Optional field driving tile color (numeric → sequential, else palette). */
+        color?: FieldDef;
+    };
+    /** Sequential color scheme name when `color` is numeric (default 'teal'). */
+    scheme?: string;
+    /** Show the value beneath the label inside each tile (default true). */
+    labels?: boolean;
+}
+/**
+ * Gauge — a radial dial showing a single value against a `[min, max]` scale,
+ * with an optional `target` needle and qualitative background `bands`. The
+ * value is a literal or a field (optionally aggregated, like {@link KpiSpec}).
+ */
+interface GaugeSpec extends BaseSpec {
+    type: 'gauge';
+    /** The measured value (literal or a field, optionally aggregated over data). */
+    value: ValueRef;
+    /** Scale start (default 0). */
+    min?: number;
+    /** Scale end — the gauge's full-scale (required). */
+    max: number;
+    /** Optional target/threshold marker drawn as a needle/tick. */
+    target?: ValueRef;
+    /** Caption under the value (defaults to the spec title or value field). */
+    label?: string;
+    /** Number format for the value + scale ticks (e.g. ',.0f', '.0%'). */
+    format?: string;
+    /** Qualitative arc bands, each filling the scale up to `to`. */
+    bands?: {
+        to: number;
+        color?: string;
+    }[];
+}
+/**
+ * Bullet graph — a compact linear KPI-vs-target: a measure bar over qualitative
+ * `ranges` (poor/ok/good background bands) with a `target` comparative marker.
+ * The featured value/target are literals or fields (optionally aggregated).
+ */
+interface BulletSpec extends BaseSpec {
+    type: 'bullet';
+    /** The featured measure (literal or a field, optionally aggregated). */
+    value: ValueRef;
+    /** Target/comparative marker (literal or field) drawn as a vertical tick. */
+    target?: ValueRef;
+    /** Scale start (default 0). */
+    min?: number;
+    /** Scale end (default: derived from value/target/ranges). */
+    max?: number;
+    /** Qualitative range boundaries on the scale (e.g. [50, 75, 100]). */
+    ranges?: number[];
+    /** Caption to the left of the bar (defaults to the spec title or value field). */
+    label?: string;
+    /** Number format for the value + axis ticks. */
+    format?: string;
+}
+/**
+ * Calendar heatmap — a GitHub-contributions-style grid of one cell per day,
+ * colored by a value via a sequential scale, with weekday rows and month
+ * labels. Pass tidy rows of `{ date, value }`; dates may be `Date` objects or
+ * ISO strings.
+ */
+interface CalendarHeatmapSpec extends BaseSpec {
+    type: 'calendarHeatmap';
+    encoding: Encoding & {
+        /** Date field (Date or ISO string) → one cell per day. */
+        date: FieldDef;
+        /** Numeric value field → cell color via a sequential scale. */
+        color: FieldDef;
+    };
+    /** Sequential color scheme name for the value scale (default 'teal'). */
+    scheme?: string;
+}
+/**
+ * Waterfall — a column chart of signed steps where each bar floats from the
+ * running total to its new level, showing how sequential increases and decreases
+ * build to a final value. Each `value` is the **signed change** at that stage
+ * (positive rises, negative falls). Stages named in `totals` (and an optional
+ * appended grand total) draw as absolute bars from the baseline. Increases,
+ * decreases, and totals are colored distinctly and joined by connector lines.
+ */
+interface WaterfallSpec extends BaseSpec {
+    type: 'waterfall';
+    encoding: Encoding & {
+        /** Stage label along the x-axis (one bar per row, in data order). */
+        stage: FieldDef;
+        /** Signed change at each stage (positive rises, negative falls). */
+        value: FieldDef;
+    };
+    /** Stage labels to draw as absolute running-total bars from the baseline. */
+    totals?: string[];
+    /** Append a final bar summing every step (default false). */
+    showTotal?: boolean;
+    /** Label for the appended total bar (default 'Total'). */
+    totalLabel?: string;
+    /** Show the per-bar value labels (default true). */
+    labels?: boolean;
+    /** Bar corner radius in pixels (default 2). */
+    cornerRadius?: number;
+    /** Color for upward steps (default theme positive/green). */
+    increaseColor?: string;
+    /** Color for downward steps (default theme negative/red). */
+    decreaseColor?: string;
+    /** Color for total/subtotal bars (default theme accent). */
+    totalColor?: string;
+}
+/**
+ * Slope graph — a minimal "before/after" chart: each `series` is a line joining
+ * its `y` value across two (or a few) ordinal `x` positions, with direct end
+ * labels instead of a legend. Reads change-in-rank and rise/fall at a glance.
+ * Pass tidy rows of `{ x, y, series }` (one row per series per x position).
+ */
+interface SlopeSpec extends BaseSpec {
+    type: 'slope';
+    encoding: Encoding & {
+        /** The ordinal positions along the x-axis (typically two: e.g. start/end). */
+        x: FieldDef;
+        /** Numeric value plotted on the y-axis. */
+        y: FieldDef;
+        /** One line per series (the entity whose change is traced). */
+        series: FieldDef;
+    };
+    /** Direct labels (series name + value) at each line's ends (default true). */
+    labels?: boolean;
+    /** Color each line green/red by its net rise/fall instead of by series. */
+    colorByChange?: boolean;
+    /** Number format for value labels and the y-axis. */
+    format?: string;
+}
+/**
+ * Dumbbell / connected dot plot — for each `category`, a dot per `group` placed
+ * on a shared horizontal value axis and joined by a connector, so the gap between
+ * groups (e.g. before vs. after, male vs. female) reads directly. Categories run
+ * down the y-axis. Pass tidy rows of `{ category, value, group }`.
+ */
+interface DumbbellSpec extends BaseSpec {
+    type: 'dumbbell';
+    encoding: Encoding & {
+        /** The category for each row (one band down the y-axis). */
+        category: FieldDef;
+        /** Numeric value → dot position on the horizontal axis. */
+        value: FieldDef;
+        /** The group each dot belongs to (2+ levels → one dot each, connected). */
+        group: FieldDef;
+    };
+    /** Value labels beside the dots (default false). */
+    labels?: boolean;
+    /** Number format for value labels and the x-axis. */
+    format?: string;
+    /** Order the category rows (default: data order). `gap` sorts by dot spread. */
+    sort?: 'ascending' | 'descending' | 'gap';
+}
 type ConditionalFormat = {
     type: 'colorScale';
     scheme?: string;
@@ -1193,6 +1830,8 @@ interface BoxSpec extends BaseSpec {
     whisker?: 'tukey' | 'minMax';
     /** Draw outlier points beyond the whiskers (tukey only; default true). */
     outliers?: boolean;
+    /** Reference lines, bands, and threshold zones overlaid on the plot. */
+    annotations?: Annotation[];
 }
 interface SankeySpec extends BaseSpec {
     type: 'sankey';
@@ -1335,7 +1974,7 @@ interface DateRangeSlicerSpec extends BaseSlicerSpec {
 type SlicerSpec = DropdownSlicerSpec | SearchSlicerSpec | ListSlicerSpec | RangeSlicerSpec | DateRangeSlicerSpec;
 type SlicerType = SlicerSpec['type'];
 declare const SLICER_TYPES: readonly SlicerType[];
-type ChartSpec = LineSpec | AreaSpec | BarSpec | ScatterSpec | PieSpec | HeatmapSpec | FunnelSpec | KpiSpec | TableSpec | MatrixSpec | BoxSpec | SankeySpec | ChoroplethSpec | DropdownSlicerSpec | SearchSlicerSpec | ListSlicerSpec | RangeSlicerSpec | DateRangeSlicerSpec;
+type ChartSpec = LineSpec | AreaSpec | BarSpec | ScatterSpec | ComboSpec | HistogramSpec | PieSpec | HeatmapSpec | FunnelSpec | KpiSpec | TreemapSpec | GaugeSpec | BulletSpec | CalendarHeatmapSpec | WaterfallSpec | SlopeSpec | DumbbellSpec | TableSpec | MatrixSpec | BoxSpec | SankeySpec | ChoroplethSpec | DropdownSlicerSpec | SearchSlicerSpec | ListSlicerSpec | RangeSlicerSpec | DateRangeSlicerSpec;
 type ChartType = ChartSpec['type'];
 declare const CHART_TYPES: readonly ChartType[];
 
@@ -1486,6 +2125,13 @@ declare class Surface {
     width: number;
     height: number;
     dpr: number;
+    /**
+     * When true, overlay text (axis labels, titles, legends, annotation labels) is
+     * painted onto the `marks` canvas instead of the HTML overlay. Set by headless
+     * renderers (`@graphein/node`) where there is no DOM to host crisp text.
+     * Defaults to false (browser).
+     */
+    headless: boolean;
     constructor(container: HTMLElement);
     resize(width: number, height: number, dpr?: number): void;
     /** Clear both canvas layers and empty the HTML overlay. */
@@ -1503,6 +2149,211 @@ declare class Surface {
 
 declare function applyA11y(surface: Surface, spec: ChartSpec): void;
 
+/**
+ * Data insight analysis — the pure analytical core behind self-explaining charts.
+ *
+ * Given a {@link ChartSpec} (spec + its `data`), {@link analyzeChart} derives a
+ * structured, dependency-free set of facts about what the numbers *say*: the
+ * trend and net change of a series, the largest/smallest category and its share,
+ * outliers, scatter correlation, a value vs. its target. Two consumers build on
+ * it without re-deriving anything:
+ *   - {@link summarize} turns insights into a deterministic plain-English summary
+ *     (doubles as alt-text — no LLM).
+ *   - auto-insight annotations turn the same `PointRef`s into on-chart callouts.
+ *
+ * The analysis is a pure function of the spec; it reads rows as-is (charts plot
+ * rows in data order, so first/last reflect data order) and never mutates input.
+ */
+
+/** A single salient point in a series: its value, its x-label, and row index. */
+interface PointRef {
+    /** The x-axis label for this point (formatted as a string). */
+    label: string;
+    /** The numeric value at this point. */
+    value: number;
+    /** Index of the originating row within its series. */
+    index: number;
+    /**
+     * The raw x-axis domain value (a `Date`, string, or number) for this point,
+     * suitable for mapping back to a pixel via a chart's x-scale. Undefined when
+     * the analysis had no x channel (e.g. a raw distribution).
+     */
+    raw?: unknown;
+}
+/** Trend + spread facts for one ordered numeric series. */
+interface SeriesInsights {
+    /** Series name (`''` for a single, unsplit series). */
+    key: string;
+    /** Number of points. */
+    count: number;
+    first: PointRef;
+    last: PointRef;
+    min: PointRef;
+    max: PointRef;
+    /** Arithmetic mean of the values. */
+    mean: number;
+    /** Sum of the values. */
+    sum: number;
+    /** `last - first`. */
+    netChange: number;
+    /** `(last - first) / |first|`, or `null` when `first` is 0. */
+    pctChange: number | null;
+    /** Overall direction of travel from first to last. */
+    direction: 'up' | 'down' | 'flat';
+    /** The largest single step between consecutive points (by absolute delta). */
+    biggestJump: {
+        from: PointRef;
+        to: PointRef;
+        delta: number;
+    } | null;
+    /** Points beyond the 1.5×IQR Tukey fences (empty when none). */
+    outliers: PointRef[];
+}
+/** Part-to-whole facts for a categorical measure. */
+interface CategoryInsights {
+    /** Number of categories. */
+    count: number;
+    /** Sum of the measure across all categories. */
+    total: number;
+    /** The largest category. */
+    top: PointRef;
+    /** The smallest category. */
+    bottom: PointRef;
+    /** `top.value / total` (0..1), or 0 when the total is not positive. */
+    topShare: number;
+}
+/** Relationship facts for an x/y point cloud. */
+interface ScatterInsights {
+    count: number;
+    xExtent: [number, number];
+    yExtent: [number, number];
+    /** Pearson correlation coefficient (−1..1), or `null` when undefined. */
+    correlation: number | null;
+}
+/** A single value measured against an optional target. */
+interface ValueInsights {
+    value: number;
+    target: number | null;
+    /** `value - target`, or `null` when there is no target. */
+    toTarget: number | null;
+    /** `value / target`, or `null` when there is no (non-zero) target. */
+    pctOfTarget: number | null;
+}
+type InsightFamily = 'series' | 'category' | 'scatter' | 'value' | 'distribution';
+/** The structured insight payload for a chart (see {@link analyzeChart}). */
+interface ChartInsights {
+    type: ChartType;
+    family: InsightFamily;
+    /** Rows backing the chart. */
+    rowCount: number;
+    /** The measure field name (y / value / theta), when there is one. */
+    measureField?: string;
+    /** The measure's number-format hint (for downstream formatting). */
+    measureFormat?: string;
+    /** Display title for the measure (field title or field name). */
+    measureLabel?: string;
+    /** The category / x field name, when there is one. */
+    categoryField?: string;
+    /** Inferred type of the x / category field. */
+    categoryType?: FieldType;
+    /** Per-series trend facts (family `series`). */
+    series?: SeriesInsights[];
+    /** Highest-ending series (multi-series only). */
+    leader?: {
+        key: string;
+        value: number;
+    };
+    /** The series that moved most from first→last (multi-series only). */
+    biggestMover?: {
+        key: string;
+        delta: number;
+    };
+    /** Part-to-whole facts (family `category`). */
+    category?: CategoryInsights;
+    /** Point-cloud facts (family `scatter`). */
+    scatter?: ScatterInsights;
+    /** Single value vs. target (family `value`). */
+    value?: ValueInsights;
+    /** Distribution of one measure (family `distribution`, e.g. histogram). */
+    distribution?: SeriesInsights;
+}
+/**
+ * Compute trend + spread insights for a parallel `values`/`labels` series.
+ * Returns `null` when there are no finite values.
+ */
+declare function computeSeriesInsights(values: readonly number[], labels: readonly string[], key?: string, raws?: readonly unknown[]): SeriesInsights | null;
+/**
+ * Derive structured insights from a chart spec, or `null` when the chart type
+ * carries no summarizable trend (e.g. table, matrix, sankey, maps).
+ */
+declare function analyzeChart(spec: ChartSpec): ChartInsights | null;
+
+/**
+ * Deterministic natural-language chart summaries — the chart explains itself.
+ *
+ * {@link summarize} turns the structured facts from {@link analyzeChart} into one
+ * or two plain-English sentences ("Users rose 46% from 4,200 to 6,150…"). It is
+ * a pure, LLM-free function of the spec, so the same string is reproducible in a
+ * report, an email, or — crucially — as the alt-text behind a canvas chart.
+ *
+ * Returns `''` for chart types that carry no summarizable trend (tables, maps,
+ * sankey), so callers can treat an empty string as "nothing worth narrating".
+ */
+
+/**
+ * Build a deterministic, plain-English summary of what a chart's data shows.
+ * Doubles as alt-text. Returns `''` when the chart type isn't summarizable.
+ */
+declare function summarize(spec: ChartSpec): string;
+
+/**
+ * Auto-insight annotations — turn a chart's {@link analyzeChart} facts into
+ * on-chart callouts. A cartesian chart opts in with `insights: true` (or an
+ * {@link InsightOptions} object); the library finds the notable points (the peak,
+ * the trough, statistical outliers, or the top/bottom category) and emits labeled
+ * `point` {@link Annotation}s — so an agent never has to reason out *where* the
+ * maximum is or hardcode its coordinates.
+ *
+ * Pure and deterministic: a function of the spec + its data, reusing the same
+ * analytical core as {@link summarize}. Multi-series charts are skipped (markers
+ * on every series would clutter the plot); use `insights` on a single series.
+ */
+
+/** Normalize the `insights` field to concrete flags, or `null` when disabled. */
+declare function resolveInsightOptions(insights: boolean | InsightOptions | undefined): Required<InsightOptions> | null;
+/**
+ * Expand a chart's `insights` option into `point` annotations for its notable
+ * data points. Returns `[]` when insights are disabled, the chart has no
+ * summarizable trend, or it splits into multiple series.
+ */
+declare function autoInsightAnnotations(spec: ChartSpec): Annotation[];
+
+/**
+ * Pure linear-regression helpers — the analytical core behind the `trendline`
+ * overlay. Dependency-free and deterministic so the same fit is computed in the
+ * browser and headless. Mirrors the covariance math used by `pearson()` in
+ * `./insights`, exposed here as a reusable line-of-best-fit.
+ */
+interface RegressionFit {
+    /** Slope (dy/dx) of the fitted line. */
+    slope: number;
+    /** Y-intercept of the fitted line. */
+    intercept: number;
+    /** Coefficient of determination (R²), in [0, 1]. */
+    r2: number;
+    /** Number of finite (x, y) pairs the fit used. */
+    n: number;
+    /** Predict y for a given x along the fitted line. */
+    predict(x: number): number;
+}
+/**
+ * Ordinary-least-squares linear fit over paired numeric samples.
+ *
+ * Returns `null` when there are fewer than two points or the x values have no
+ * spread (a vertical fit has an undefined slope). Non-finite pairs are ignored.
+ */
+declare function linearRegression(xs: readonly number[], ys: readonly number[]): RegressionFit | null;
+
 /** Environment helpers — safe in both browser and Node (SSR/test). */
 declare const isBrowser: boolean;
 /** Current device pixel ratio (defaults to 1 outside the browser). */
@@ -1535,10 +2386,88 @@ declare function createDiv(className?: string, style?: Partial<CSSStyleDeclarati
 /** Absolute-position a layer to fill its positioned parent. */
 declare const fillParentStyle: Partial<CSSStyleDeclaration>;
 
+/**
+ * Canvas painting for chart "overlay" text (axis labels, titles, legends,
+ * annotation labels). In the browser this text lives in a crisp, selectable
+ * HTML overlay; headless (no DOM) there is no overlay, so the very same text is
+ * painted onto the marks canvas with these helpers.
+ *
+ * The geometry is shared: call sites compute one set of positions and either
+ * realise them as absolutely-positioned DOM nodes (browser) or feed them here
+ * (headless). The transform/width vocabulary the DOM path uses
+ * (`translateX(-50%)`, `translateY(-50%)`, `translate(-50%,-50%) rotate(±90deg)`,
+ * box `width` + `align`) maps deterministically onto canvas
+ * `textAlign`/`textBaseline`/rotation, so both paths land the same pixels.
+ */
+interface CanvasPillStyle {
+    background: string;
+    border?: string;
+    radius?: number;
+    padX?: number;
+    padY?: number;
+}
+interface CanvasTextCmd {
+    /** Anchor x (interpreted per `align`). */
+    x: number;
+    /** Anchor y (interpreted per `baseline`). */
+    y: number;
+    text: string;
+    /** CSS font shorthand (authoritative — already encodes size + weight). */
+    font: string;
+    color: string;
+    /** Font pixel size, used to size the optional pill. */
+    size: number;
+    align?: CanvasTextAlign;
+    baseline?: CanvasTextBaseline;
+    /** Rotation about (x, y), in radians. */
+    rotate?: number;
+    opacity?: number;
+    /** Draw a rounded "pill"/badge behind the text (solid fill + hairline border). */
+    pill?: CanvasPillStyle;
+}
+/** Paint a single text command onto a 2D context. Self-contained (save/restore). */
+declare function paintCanvasText(ctx: CanvasRenderingContext2D, c: CanvasTextCmd): void;
+/** Option shape shared by the DOM text helpers (axes + chrome). */
+interface OverlayTextOpts {
+    left: number;
+    top: number;
+    width?: number;
+    text: string;
+    color: string;
+    size: number;
+    align?: 'left' | 'center' | 'right';
+    transform?: string;
+    opacity?: number;
+    pill?: CanvasPillStyle;
+}
+/**
+ * Translate an absolutely-positioned overlay text node (left/top/width/align +
+ * a CSS `transform` from the known vocabulary) into the equivalent canvas
+ * command. Keeps the headless output pixel-aligned with the browser overlay.
+ */
+declare function overlayTextToCanvasCmd(o: OverlayTextOpts, font: string): CanvasTextCmd;
+type LegendSymbol = 'square' | 'circle' | 'line';
+/** Total horizontal footprint of a legend swatch (square/circle = 11, line = 14). */
+declare function legendSwatchWidth(symbol: LegendSymbol | undefined, swatch?: number): number;
+/**
+ * Paint a legend swatch onto canvas, vertically centered on `midY`. Mirrors the
+ * DOM swatch (square/circle 11px, line 14×3px).
+ */
+declare function paintLegendSwatch(ctx: CanvasRenderingContext2D, x: number, midY: number, symbol: LegendSymbol | undefined, color: string, swatch?: number): void;
+
 /**
  * Text measurement using a shared offscreen canvas context. Falls back to a
- * rough heuristic when no canvas is available (SSR/test).
+ * rough heuristic when no canvas is available (SSR/test). In a non-DOM
+ * environment (e.g. `@graphein/node`) a real 2D context can be injected via
+ * {@link setMeasureContext} so layout uses true font metrics.
  */
+/**
+ * Provide a 2D context used to measure text advance widths when no DOM is
+ * available (headless rendering). Pass `null` to clear and fall back to the
+ * DOM canvas / heuristic. The context's `font` is overwritten on each measure,
+ * so use a dedicated measurement context rather than your drawing context.
+ */
+declare function setMeasureContext(ctx: CanvasRenderingContext2D | null): void;
 interface TextMetricsLite {
     width: number;
 }
@@ -1685,6 +2614,12 @@ interface DashboardSpec {
      */
     interactions?: 'auto' | 'none' | InteractionLink[];
 }
+/**
+ * Any top-level Graphein spec: a chart, a slicer, or a dashboard. This is the
+ * root type the JSON Schema (`docs/chart-spec.schema.json`) is generated from,
+ * and the broadest type `validateSpec` accepts.
+ */
+type AnySpec = ChartSpec | DashboardSpec;
 
 /** Infer the channel type of a single value. */
 declare function inferValueType(value: unknown): FieldType | undefined;
@@ -1696,10 +2631,65 @@ declare function inferFieldType(data: Datum[], field: string, sample?: number):
 /** Infer types for every field present in the first rows of the dataset. */
 declare function inferFieldTypes(data: Datum[]): Record<string, FieldType>;
 
+/**
+ * Minimal, apply-only JSON Patch (RFC 6902) used by `repairSpec` to apply the
+ * safe `fix` operations that `validateSpec` attaches to errors. Pure: returns a
+ * new document, never mutates the input. Preserves `Date` values (specs may hold
+ * `Date` objects for temporal fields), unlike a JSON round-trip clone.
+ */
+type JsonPatchOp = {
+    op: 'add';
+    path: string;
+    value: unknown;
+} | {
+    op: 'replace';
+    path: string;
+    value: unknown;
+} | {
+    op: 'remove';
+    path: string;
+};
+/**
+ * Convert a dotted/bracketed validation path (`encoding.x.type`,
+ * `transform[0].calculate`, `values[2].op`) into a JSON Pointer
+ * (`/encoding/x/type`, `/transform/0/calculate`, `/values/2/op`). Authoring
+ * fixes from the same `path` an error already reports keeps the two in sync.
+ */
+declare function toPointer(path: string): string;
+/** Apply an ordered list of patch ops to a deep clone of `doc`. */
+declare function applyPatch<T>(doc: T, ops: readonly JsonPatchOp[]): T;
+
 interface ValidationError {
     /** JSON-path-ish location, e.g. "encoding.x.field". */
     path: string;
     message: string;
+    /**
+     * Stable rule id for lint findings (e.g. "pie-too-many-slices"), so agents can
+     * recognize, suppress, or learn from a specific best-practice warning. Absent
+     * on structural validation errors.
+     */
+    rule?: string;
+    /**
+     * Severity of a lint finding. Structural problems are reported via `errors`
+     * (implicitly 'error'); lint findings in `warnings` are 'warning' or 'info'.
+     */
+    severity?: 'error' | 'warning' | 'info';
+    /**
+     * Safe, unambiguous JSON Patch (RFC 6902) operations that resolve this problem
+     * — present only when a correction is clear (e.g. a misspelled enum or chart
+     * type, or a temporal-looking field typed as a category). An agent can apply
+     * these directly instead of regenerating; {@link repairSpec} applies them for
+     * you. Absent when the right fix is ambiguous.
+     */
+    fix?: JsonPatchOp[];
+    /**
+     * "Did you mean" candidates, nearest first, for an unrecognized value. `kind`
+     * names what is being suggested so an agent can react appropriately.
+     */
+    suggestion?: {
+        kind: 'chartType' | 'enum' | 'field' | 'channel';
+        candidates: string[];
+    };
 }
 interface ValidationResult {
     valid: boolean;
@@ -1720,6 +2710,57 @@ declare function validateSpec(spec: unknown): ValidationResult;
 declare function validateDashboard(spec: Record<string, unknown>): ValidationResult;
 declare function assertValidSpec(spec: unknown): ChartSpec;
 
+/**
+ * Dataviz linter — best-practice rules that encode the visualization expertise an
+ * agent may lack. Each rule is pure and returns findings with a stable `rule` id
+ * and a `severity` ('warning' | 'info'), so an agent can recognize, suppress, or
+ * learn from a specific issue. Findings are surfaced through `validateSpec`'s
+ * `warnings`, and directly via {@link lintSpec}.
+ *
+ * Rules lint the *effective* data (after `transform`), so cardinality reflects
+ * what actually renders (e.g. pie slices after an `aggregate`). The linter never
+ * throws and never blocks rendering — it is advisory only.
+ */
+
+/** A lint finding always carries a `rule` id and a non-error `severity`. */
+interface LintFinding extends ValidationError {
+    rule: string;
+    severity: 'warning' | 'info';
+}
+/**
+ * Lint a (structurally valid) chart spec for best-practice issues. Returns an
+ * empty array for slicers/dashboards or when no rule fires. Pure and total.
+ */
+declare function lintSpec(spec: ChartSpec): LintFinding[];
+
+/**
+ * Self-repairing validation. {@link repairSpec} applies the safe, unambiguous
+ * JSON Patch fixes that {@link validateSpec} attaches to its findings, then
+ * re-validates — turning common agent mistakes (a misspelled chart type or enum,
+ * a temporal field typed as a category) into a one-step correction instead of a
+ * full regenerate. Only fixes the validator deems unambiguous are applied; when
+ * the right correction is unclear, the error is left for the agent to resolve.
+ */
+
+interface RepairResult {
+    /** The (possibly) corrected spec — a new object; the input is never mutated. */
+    spec: unknown;
+    /** Patch operations that were applied, in order. Empty when nothing changed. */
+    applied: JsonPatchOp[];
+    /**
+     * Structural errors that remain after repair. `remaining.length === 0` means
+     * the repaired spec is valid. Advisory lint warnings are not counted here.
+     */
+    remaining: ValidationError[];
+}
+/**
+ * Apply every safe auto-fix `validateSpec` proposes, iterating until the spec is
+ * valid or no further progress can be made (a fix may unlock another — e.g.
+ * correcting the chart `type` changes which channels are required). Pure: the
+ * input spec is deep-cloned before any patch is applied.
+ */
+declare function repairSpec(spec: unknown): RepairResult;
+
 /**
  * Resolve a spec's `sketch` option into concrete, fully-defaulted knobs for the
  * rough engine. Returns `null` when sketching is off, which lets every chart
@@ -1840,6 +2881,9 @@ interface FrameInput {
     height: number;
     padding: Insets;
     font: ThemeFont;
+    /** Optional origin offset — lay the frame out within a sub-region (e.g. a facet cell). */
+    originX?: number;
+    originY?: number;
     title?: TitleInput;
     legend?: {
         items: LegendItem[];
@@ -1848,10 +2892,15 @@ interface FrameInput {
     /** Cartesian charts pass both axes; non-cartesian omit them. */
     xAxis?: AxisInput;
     yAxis?: AxisInput;
+    /** Secondary (right) y-axis for dual-axis combo charts; reserves a right gutter. */
+    y2Axis?: AxisInput;
 }
 interface Frame {
     width: number;
     height: number;
+    /** Absolute origin offset of this frame within the surface (0 unless faceted). */
+    originX: number;
+    originY: number;
     plot: Rect;
     titleRect?: Rect;
     subtitleRect?: Rect;
@@ -2007,6 +3056,22 @@ declare function resolveCurve(curve?: CurveType): Curve;
 interface BuildOptions {
     width: number;
     height: number;
+    /** Origin offset, so the model lays out within a sub-region (a facet cell). */
+    originX?: number;
+    originY?: number;
+    /** Shared scale domains/colors, so faceted panels stay directly comparable. */
+    shared?: SharedScales;
+}
+/** Scale state shared across a facet grid so every panel is comparable. */
+interface SharedScales {
+    /** Band/point category domain (the full ordered category list). */
+    categories?: string[];
+    /** Continuous (linear) or temporal (epoch ms) x-domain. */
+    xDomain?: [number, number];
+    /** Linear y-domain (already accounting for any zero baseline). */
+    yDomain?: [number, number];
+    /** Series-key → color, so the same series keeps its color in every panel. */
+    colorOf?: (key: string) => string;
 }
 declare function buildCartesianModel(spec: CartesianChartSpec, tokens: ThemeTokens, opts: BuildOptions): CartesianModel;
 
@@ -2023,6 +3088,8 @@ declare function buildCartesianModel(spec: CartesianChartSpec, tokens: ThemeToke
 declare function drawAxesUnderlay(surface: Surface, model: CartesianModel): void;
 /** Draw all overlay text: tick labels, axis titles, chart title, legend. */
 declare function drawOverlay(surface: Surface, model: CartesianModel): void;
+declare function drawTitle(surface: Surface, frame: Frame, spec: CartesianModel['spec'], tokens: ThemeTokens): void;
+declare function drawLegend(surface: Surface, items: PositionedLegendItem[], model: CartesianModel): void;
 
 /**
  * SelectionStore — the dependency-free bus that links interactive visuals.
@@ -2054,6 +3121,51 @@ interface SelectionStore {
 }
 declare function createSelectionStore(initial?: Record<string, SelectionValue | null>): SelectionStore;
 
+/**
+ * Reference annotations for cartesian charts — lines, bands, and threshold zones.
+ *
+ * A cross-cutting overlay primitive available to every cartesian chart via
+ * `spec.annotations`. Marks (the rule strokes and band fills) are painted on the
+ * marks canvas; labels live in the HTML overlay for crisp, selectable text,
+ * mirroring how axes render. Geometry comes from the already-resolved
+ * `CartesianModel` scales, so this module is pure presentation.
+ */
+
+/**
+ * Paint reference lines and band/zone fills on the marks canvas, clipped to the
+ * plot. Call after the chart's data marks so reference lines sit on top.
+ */
+declare function drawAnnotations(surface: Surface, model: CartesianModel): void;
+/**
+ * Append annotation labels to the HTML overlay. Call after `drawOverlay` so the
+ * labels layer on top of axis text. No-op when there are no labeled annotations.
+ */
+declare function drawAnnotationLabels(surface: Surface, model: CartesianModel): void;
+
+/**
+ * Derived trendlines for cartesian charts — a linear line of best fit overlaid
+ * on a scatter, line, or area plot via `spec.trendline`.
+ *
+ * The regression is computed from the already-resolved `CartesianModel` series
+ * (one fit per group, or a single overall fit), and the fitted line is stroked
+ * across each group's x-extent. Marks land on the marks canvas; optional `R²`
+ * labels live in the HTML overlay (or are painted to canvas when headless),
+ * mirroring how `annotations` render. Pure presentation — no data reshaping.
+ */
+
+/**
+ * Stroke the fitted line(s) on the marks canvas, clipped to the plot. Call after
+ * the chart's data marks so the trendline sits on top. No-op unless the spec
+ * opts in via `trendline` and the x-axis is continuous/temporal.
+ */
+declare function drawTrendlines(surface: Surface, model: CartesianModel): void;
+/**
+ * Append `R²` labels for each fitted line to the HTML overlay (or paint them to
+ * canvas when headless). Call after `drawAnnotationLabels`. No-op unless
+ * `trendline.label` is set.
+ */
+declare function drawTrendlineLabels(surface: Surface, model: CartesianModel): void;
+
 /**
  * Chart registry.
  *
@@ -2248,6 +3360,257 @@ declare function resolveFilterValues(filter: FilterClause[] | undefined, store:
 /** The set of param names a spec reacts to (for change-driven redraws). */
 declare function dependentParams(highlight: HighlightConfig | HighlightConfig[] | undefined, filter: FilterClause[] | undefined, ownParams?: readonly string[]): Set<string>;
 
+/**
+ * Combo / dual-axis model builder.
+ *
+ * A `combo` spec composes several cartesian layers (bar, line, area, scatter) over
+ * a shared x axis, optionally split across a primary (left) and secondary (right)
+ * y axis. This builder resolves one shared frame / plot / x-scale and, for every
+ * layer, a fully-formed {@link CartesianModel} that the existing mark renderers
+ * (`drawLine`, `drawBar`, …) consume unchanged. Two independent y-scales back the
+ * left and right axes; bar layers are offset side-by-side so multiple bars group.
+ *
+ * The builder is deliberately self-contained (it reuses only the public scale /
+ * tick / frame / color primitives) so the single-chart `buildCartesianModel` path
+ * stays untouched.
+ */
+
+type ComboSide = 'left' | 'right';
+interface ComboLayerModel {
+    mark: ComboMark;
+    side: ComboSide;
+    color: string;
+    name: string;
+    /** A ready-to-draw cartesian model for this layer's mark renderer. */
+    model: CartesianModel;
+}
+interface ComboAxisModel {
+    show: boolean;
+    ticks: Tick[];
+    title?: string;
+}
+interface ComboModel {
+    spec: ComboSpec;
+    tokens: ThemeTokens;
+    frame: Frame;
+    plot: Rect;
+    x: XModel;
+    xTicks: Tick[];
+    left: ComboAxisModel;
+    right?: ComboAxisModel;
+    layers: ComboLayerModel[];
+    legendItems: LegendItem[];
+    /** Primary-axis cartesian model reused for the axis underlay / overlay chrome. */
+    base: CartesianModel;
+    sketch: ResolvedSketch | null;
+    emphasis?: Emphasis | null;
+}
+declare function buildComboModel(spec: ComboSpec, tokens: ThemeTokens, opts: BuildOptions): ComboModel;
+
+/**
+ * Histogram model builder.
+ *
+ * A `histogram` bins a single quantitative field (reusing the shared `bin`
+ * transform's {@link computeBins}) and draws the per-bin frequency as gapless
+ * bars on a continuous x-axis. Like the combo builder, it resolves a synthetic
+ * `base` {@link CartesianModel} so the existing axis chrome (`drawAxesUnderlay` /
+ * `drawOverlay`) renders the gridlines, ticks, labels and titles unchanged — the
+ * bars themselves are painted by {@link drawHistogram}.
+ */
+
+/** One resolved histogram bin (closed-open `[start, end)`). */
+interface HistogramBinDatum {
+    start: number;
+    end: number;
+    mid: number;
+    /** Raw observation count in the bin. */
+    count: number;
+    /** Plotted height: `count`, or a probability density when `density:true`. */
+    value: number;
+}
+interface HistogramModel {
+    spec: HistogramSpec;
+    tokens: ThemeTokens;
+    frame: Frame;
+    plot: Rect;
+    bins: HistogramBinDatum[];
+    layout: BinLayout | null;
+    color: string;
+    /** Map a quantitative x value to a pixel. */
+    xPixel: (v: number) => number;
+    /** Map a bar height (count/density) to a pixel. */
+    yPixel: (v: number) => number;
+    /** Pixel of the y=0 baseline. */
+    yBaseline: number;
+    cornerRadius: number;
+    /** Drives the shared axis underlay / overlay chrome. */
+    base: CartesianModel;
+    sketch: ResolvedSketch | null;
+}
+declare function buildHistogramModel(spec: HistogramSpec, tokens: ThemeTokens, opts: BuildOptions): HistogramModel;
+
+/**
+ * Render report / introspection API.
+ *
+ * After a chart draws, `buildRenderReport` derives a machine-readable set of
+ * diagnostics from the *resolved* model (scales, plot rect, ticks, legend,
+ * theme colors) — no pixels are read back. This lets an agent verify a chart
+ * "looks right" without vision: it can see the mark count, whether axis labels
+ * collide, whether the legend was truncated, whether marks fall outside the
+ * plot, and whether colors clear contrast thresholds.
+ *
+ * The builder is pure and dependency-free so it runs identically in the browser
+ * and headless (the server-side critique loop consumes the same report).
+ */
+
+type ReportSeverity = 'error' | 'warning' | 'info';
+/** One machine-readable finding about the rendered chart. */
+interface RenderDiagnostic {
+    /** Stable identifier an agent can match/suppress on (e.g. `axis-label-overlap`). */
+    code: string;
+    severity: ReportSeverity;
+    /** Human- and agent-readable explanation. */
+    message: string;
+    /** The axis a layout diagnostic refers to, when applicable. */
+    axis?: 'x' | 'y';
+    /** Structured extras (counts, ratios) for programmatic consumers. */
+    details?: Record<string, unknown>;
+}
+/** A post-render, vision-free description of what was drawn. */
+interface RenderReport {
+    type: ChartType;
+    /** Surface size in CSS pixels. */
+    size: Size;
+    /** Plot rectangle (cartesian-derived reports only). */
+    plot?: Rect;
+    /** Number of data marks the chart drew. */
+    markCount: number;
+    /** Number of distinct series. */
+    seriesCount: number;
+    /** Number of distinct colors used for series. */
+    colorCount: number;
+    /** True when no `error` or `warning` diagnostics were raised. */
+    ok: boolean;
+    /** All findings, ordered most-severe first. */
+    diagnostics: RenderDiagnostic[];
+    /**
+     * Deterministic plain-English summary of what the data shows (alt-text without
+     * an LLM). Absent for chart types that carry no summarizable trend.
+     */
+    summary?: string;
+}
+/** Inputs for {@link buildRenderReport}. */
+interface ReportInput {
+    type: ChartType;
+    spec: ChartSpec;
+    /** Effective (post-transform, post-filter) data that was rendered. */
+    data: Datum[];
+    tokens: ThemeTokens;
+    size: Size;
+    /** The resolved cartesian model, when the chart type is cartesian. */
+    model?: CartesianModel;
+}
+/**
+ * Build the render report for a freshly-drawn chart. Pure: it reads the
+ * resolved model + theme, never the canvas bitmap.
+ */
+declare function buildRenderReport(input: ReportInput): RenderReport;
+
+/**
+ * Faceting / small multiples.
+ *
+ * A faceted chart splits into a trellis grid of panels — one per distinct value
+ * of a field — all sharing identical x/y/color scales so the panels are directly
+ * comparable. Each panel is a full {@link CartesianModel} laid out into its grid
+ * cell (via the frame's origin offset), drawn with the very same cartesian
+ * pipeline (underlay → marks → trendline → annotations → overlay) on a single
+ * canvas. That means faceting works identically headless, preserving the
+ * critique-loop moat.
+ *
+ * The shared scales are derived from a *reference model* built over the full
+ * dataset: its domains and color map ARE the shared state every panel reuses, so
+ * a series keeps its color and position in every panel even when a panel's subset
+ * is missing some categories or series.
+ */
+
+/** Cartesian chart kinds that can be split into a facet grid. */
+declare const FACETABLE_TYPES: ReadonlySet<string>;
+/** One panel of a facet grid: its facet value plus the resolved model. */
+interface FacetPanel {
+    value: string;
+    model: CartesianModel;
+}
+/** The resolved layout of a faceted chart — the header frame plus panel models. */
+interface FacetLayout {
+    field: string;
+    columns: number;
+    rows: number;
+    /** Outer frame: reserves the overall title + shared legend; its plot is the grid region. */
+    outerFrame: Frame;
+    panels: FacetPanel[];
+    /** Positioned shared legend items (multi-series only). */
+    legendItems?: PositionedLegendItem[];
+    /** A representative panel model (panels[0]) for token/legend draw. */
+    repModel: CartesianModel;
+}
+/** True when `spec` declares a usable facet on a facet-eligible cartesian type. */
+declare function isFaceted(spec: ChartSpec): boolean;
+/**
+ * Resolve a faceted spec into a grid of panel models sharing one set of scales.
+ * Returns `null` when there is nothing to facet (no rows / no distinct values),
+ * so the caller can fall back to the normal single-chart path.
+ */
+declare function buildFacetModels(spec: ChartSpec, tokens: ThemeTokens, size: Size): FacetLayout | null;
+/**
+ * Draw a faceted chart onto `surface`: the shared header (overall title + legend)
+ * then every panel through the full cartesian pipeline. Static — no interaction
+ * in v1. The background is assumed already painted by the caller.
+ */
+declare function drawFacet(surface: Surface, spec: ChartSpec, layout: FacetLayout, tokens: ThemeTokens): void;
+/**
+ * Merge per-panel render reports into one report for the faceted chart: mark
+ * counts sum, series/color counts take the panel maximum, diagnostics union by
+ * code (most-severe first), and `ok` holds only if every panel is ok.
+ */
+declare function facetReport(spec: ChartSpec, layout: FacetLayout, tokens: ThemeTokens, size: Size): RenderReport;
+
+/**
+ * Headless rendering — paint a chart onto any caller-supplied 2D context
+ * (e.g. `@napi-rs/canvas`, `node-canvas`, an `OffscreenCanvas`) with **no DOM**.
+ *
+ * This is the server-side half of the critique loop: it reuses the exact same
+ * model build + mark renderers as the browser, but routes overlay text through
+ * the canvas text path (see `render/overlayText.ts`) instead of the HTML overlay.
+ * It is dependency-free — the caller owns canvas creation and PNG/SVG encoding,
+ * so `graphein` itself stays zero-dependency. The companion `@graphein/node`
+ * package wires this to `@napi-rs/canvas`.
+ *
+ * Returns the same {@link RenderReport} as `instance.report()`, so an agent can
+ * generate → validate → render → critique entirely on the server.
+ */
+
+/** A minimal 2D-context target. Pass `interaction` if any renderer needs it. */
+interface HeadlessTarget {
+    /** The primary 2D context chart marks + text are painted onto. */
+    marks: CanvasRenderingContext2D;
+    /** Optional secondary context for hover layers (unused on the static path). */
+    interaction?: CanvasRenderingContext2D;
+    /** Logical (CSS-pixel) width to draw at. */
+    width: number;
+    /** Logical (CSS-pixel) height to draw at. */
+    height: number;
+}
+/**
+ * Paint `spec` onto `target.marks` (in CSS pixels — the caller sets up any
+ * device-pixel-ratio scaling on the context beforehand) and return the render
+ * report. No animation, no interactivity, no DOM.
+ *
+ * Supports every canvas-backed chart: line, area, bar, scatter, box, pie,
+ * heatmap, sankey, choropleth, combo, histogram, funnel. DOM-only kinds
+ * (kpi/table/matrix/slicers/dashboard) are unsupported headlessly.
+ */
+declare function renderToContext(target: HeadlessTarget, spec: ChartSpec): RenderReport;
+
 /**
  * Chart runtime: the public `render(container, spec)` entry point.
  *
@@ -2284,6 +3647,14 @@ interface ChartInstance {
     readonly spec: ChartSpec;
     /** The mounted surface (advanced/imperative use). */
     readonly surface: Surface;
+    /**
+     * Machine-readable diagnostics from the most recent render: mark count,
+     * clipped axis labels, legend overflow, low-contrast colors, degenerate axes,
+     * and out-of-bounds marks. Lets an agent verify the chart "looks right"
+     * without vision. Computed purely from the resolved model, so it works
+     * identically in the browser and headless.
+     */
+    report(): RenderReport;
     /** The selection bus this chart is bound to (advanced/linking use). */
     readonly store: SelectionStore;
     /** Read a param's current value, or a snapshot of all params when omitted. */
@@ -2389,4 +3760,4 @@ declare function renderDashboard(target: HTMLElement | string, spec: DashboardSp
  */
 declare const VERSION = "0.1.0";
 
-export { type AggOp, type AnimateOptions, type AnimationConfig, type AnimationHandle, type ArcOptions, type AreaOptions, type AreaPoint, type AreaSpec, type AxesConfig, type AxisConfig, type AxisInput, type BackingSize, type BandScale, type BandScaleOptions, type BarSpec, type BaseSlicerSpec, type BaseSpec, type BoxSpec, type BuildOptions, CARTESIAN_TYPES, CHART_TYPES, CanvasLayer, type CartesianChartSpec, type CartesianInteractionBuilder, type CartesianModel, type CartesianRenderer, type ChartInstance, type ChartSpec, type ChartSummary, type ChartType, type ChoroplethSpec, type ColorScale, type Comparable, type ConditionalFormat, type ContinuousScale, type ControllerSelect, type Curve, type CurveType, type CustomRenderer, DEFAULT_ENTRANCE_DURATION, DEFAULT_ROUGH_STYLE, DEFAULT_UPDATE_DURATION, DIM_ALPHA, type DashboardInstance, type DashboardLayout, type DashboardResponsiveSpan, type DashboardSection, type DashboardSpec, type DashboardView, type DateRangeSlicerSpec, type Datum, type DecimateOptions, type Dimensions, type DropdownSlicerSpec, type EasingFunction, type Emphasis, type Encoding, type EntranceContext, type Extent, type FieldDef, type FieldType, type FieldValue, type FillStyle, type FilterClause, type Frame, type FrameInput, type FunnelSpec, type GeoFeature, type GeoFeatureCollection, type GeoGeometry, type GeoMultiPolygon, type GeoPolygon, type GeoPosition, type GroupedMap, type HachureSegment, type HeatmapSpec, type HighlightConfig, type Hover, type IconRule, type Insets, InteractionController, type InteractionLink, type InteractionModel, type Interpolator, type KpiSpec, type LegendConfig, type LegendItem, type LegendPosition, type LineOptions, type LineSpec, type LinearScaleOptions, type ListSlicerSpec, type LiteralPredicate, type LogScaleOptions, type MapProjection, type MarkOptions, type MatrixSpec, type MatrixValueDef, type NumberFormatSpec, type OKLCH, type OKLab, type PathSink, type PieLabels, type PieSpec, type PivotCell, type PivotFlatRow, type PivotHeaderNode, type PivotOptions, type PivotResult, type PivotValueDef, type Point, type PointScale, type PointScaleOptions, type PointSelection, type PositionedLegendItem, type RGBA, type RangeSelection, type RangeSlicerSpec, type Rect, type RenderContext, type RenderDashboardOptions, type RenderOptions, type ResolvedEntrance, type ResolvedSeries, type ResolvedSketch, type Rng, type RoughContext, RoughPen, type RoughStyle, SKETCH_FONT_FAMILY, SKETCH_FONT_NAME, SLICER_TYPES, SR_ONLY_STYLE, type SankeySpec, type ScaleConfig, type ScaleType, type ScatterSpec, type SearchSlicerSpec, type SelectConfig, type SelectionChangeListener, type SelectionDef, type SelectionListener, type SelectionParam, type SelectionStore, type SelectionValue, type SetSelection, type Size, type SketchConfig, type SlicerSpec, type SlicerType, Surface, TICK_SIZE, type TableColumn, type TableSpec, type TextMetricsLite, type TextSelection, type ThemeColors, type ThemeFont, type ThemeInput, type ThemeTokens, type Tick, type TimeScaleOptions, type TitleConfig, type TitleInput, Tooltip, type TooltipConfig, type TooltipContent, type TooltipRow, type UpdateContext, VERSION, type ValidationError, type ValidationResult, type ValueRef, type ValueRule, type XKind, type XModel, type YModel, aggregateValues, animate, applyA11y, applyPick, arc, area, assertValidSpec, backOut, bandScale, bounceOut, buildCartesianInteraction, buildCartesianModel, buildDataTableFallback, cartesianInteractionBuilders, cartesianRenderers, categorical, chartTitleText, chartTypeLabel, clamp01, clamp255, computeBackingSize, computeFrame, contrastRatio, createDiv, createRoughPen, createSelectionStore, cubicIn, cubicInOut, cubicOut, curveCatmullRom, curveLinear, curveMonotoneX, curveStep, curveStepAfter, curveStepBefore, customRenderers, darkTheme, decimate, dependentParams, diverging, divergingColorScale, divergingSchemes, drawAxesUnderlay, drawOverlay, easings, elasticOut, ensureSketchFont, expoInOut, expoOut, fillParentStyle, filterRows, fontString, formatDate, formatNumber, formatValue, getDevicePixelRatio, groupBy, hashString, inferFieldType, inferFieldTypes, inferValueType, interpolateArray, interpolateNumber, interpolateNumberArray, interpolateObject, interpolateOklab, interpolateRgb, isBrowser, isEmptyValue, isParamClause, isSlicerType, keyFields, lightTheme, line, linear, linearScale, linearToSrgb, literalToValue, logScale, lttbRun, makeMatcher, matchesValue, measureText, monotoneXTangents, mulberry32, niceDomain, oklabToOklch, oklabToRgb, oklchToOklab, ordinalColorScale, parseColor, parseNumberFormat, pivot, pointScale, polygonHachureLines, prefersReducedMotion, prettyDate, quadIn, quadInOut, quadOut, rampFromStops, readableTextColor, relativeLuminance, render, renderDashboard, resolveCurve, resolveDashboardLayout, resolveDashboardSections, resolveEmphasis, resolveEntrance, resolveFilterValues, resolveSketch, resolveTheme, resolveUpdate, rgbToOklab, rgbaToCss, rotatePoint, roundedRect, sampleArc, sequential, sequentialColorScale, sequentialSchemes, setStyle, sinInOut, slicerParamName, smartDate, specFields, srgbToLinear, summarizeChart, themes, tickIncrement, tickStep, ticks, timeScale, timeTickFormat, timeTicks, toHex, tooltipEnabled, validateDashboard, validateSpec, wireViews, withAlpha, withSketchFont };
+export { type AggOp, type AggregateOp, type AggregateTransform, type AnimateOptions, type AnimationConfig, type AnimationHandle, type Annotation, type AnySpec, type ArcOptions, type AreaOptions, type AreaPoint, type AreaSpec, type AxesConfig, type AxisConfig, type AxisInput, type BackingSize, type BandScale, type BandScaleOptions, type BarSpec, type BaseSlicerSpec, type BaseSpec, type BinLayout, type BinTransform, type BoxSpec, type BuildOptions, type BulletSpec, CARTESIAN_TYPES, CHART_TYPES, type CalculateTransform, type CalendarHeatmapSpec, CanvasLayer, type CanvasPillStyle, type CanvasTextCmd, type CartesianChartSpec, type CartesianInteractionBuilder, type CartesianModel, type CartesianRenderer, type CategoryInsights, type ChartInsights, type ChartInstance, type ChartSpec, type ChartSummary, type ChartType, type ChoroplethSpec, type ColorScale, type ComboAxisModel, type ComboLayer, type ComboLayerModel, type ComboMark, type ComboModel, type ComboSide, type ComboSpec, type Comparable, type ConditionalFormat, type ContinuousScale, type ControllerSelect, type Curve, type CurveType, type CustomRenderer, DEFAULT_ENTRANCE_DURATION, DEFAULT_ROUGH_STYLE, DEFAULT_UPDATE_DURATION, DIM_ALPHA, type DashboardInstance, type DashboardLayout, type DashboardResponsiveSpan, type DashboardSection, type DashboardSpec, type DashboardView, type DateRangeSlicerSpec, type Datum, type DecimateOptions, type Dimensions, type DropdownSlicerSpec, type DumbbellSpec, type EasingFunction, type Emphasis, type Encoding, type EntranceContext, ExpressionError, type Extent, FACETABLE_TYPES, FUNCTION_NAMES, type FacetConfig, type FacetLayout, type FacetPanel, type FieldDef, type FieldType, type FieldValue, type FillStyle, type FilterClause, type FilterPredicate, type FilterTransform, type FoldTransform, type Frame, type FrameInput, type FunnelSpec, type GaugeSpec, type GeoFeature, type GeoFeatureCollection, type GeoGeometry, type GeoMultiPolygon, type GeoPolygon, type GeoPosition, type GroupedMap, type HachureSegment, type HeadlessTarget, type HeatmapSpec, type HighlightConfig, type HistogramBin, type HistogramBinDatum, type HistogramModel, type HistogramSpec, type Hover, type IconRule, type Insets, type InsightFamily, type InsightOptions, InteractionController, type InteractionLink, type InteractionModel, type Interpolator, type JsonPatchOp, type KpiSpec, type LegendConfig, type LegendItem, type LegendPosition, type LegendSymbol, type LineOptions, type LineSpec, type LinearScaleOptions, type LintFinding, type ListSlicerSpec, type LiteralPredicate, type LogScaleOptions, type MapProjection, type MarkOptions, type MatrixSpec, type MatrixValueDef, type NumberFormatSpec, type OKLCH, type OKLab, type OverlayTextOpts, type PathSink, type PieLabels, type PieSpec, type PivotCell, type PivotFlatRow, type PivotHeaderNode, type PivotOptions, type PivotResult, type PivotValueDef, type Point, type PointRef, type PointScale, type PointScaleOptions, type PointSelection, type PositionedLegendItem, type RGBA, type RangeSelection, type RangeSlicerSpec, type Rect, type RegressionFit, type RenderContext, type RenderDashboardOptions, type RenderDiagnostic, type RenderOptions, type RenderReport, type RepairResult, type ReportInput, type ReportSeverity, type ResolvedEntrance, type ResolvedSeries, type ResolvedSketch, type Rng, type RoughContext, RoughPen, type RoughStyle, SKETCH_FONT_FAMILY, SKETCH_FONT_NAME, SLICER_TYPES, SR_ONLY_STYLE, type SankeySpec, type ScaleConfig, type ScaleType, type ScatterInsights, type ScatterSpec, type SearchSlicerSpec, type SelectConfig, type SelectionChangeListener, type SelectionDef, type SelectionListener, type SelectionParam, type SelectionStore, type SelectionValue, type SeriesInsights, type SetSelection, type SharedScales, type Size, type SketchConfig, type SlicerSpec, type SlicerType, type SlopeSpec, Surface, TICK_SIZE, TIME_UNITS, TRANSFORM_KINDS, type TableColumn, type TableSpec, type TextMetricsLite, type TextSelection, type ThemeColors, type ThemeFont, type ThemeInput, type ThemeTokens, type Tick, type TimeScaleOptions, type TimeUnit, type TimeUnitTransform, type TitleConfig, type TitleInput, Tooltip, type TooltipConfig, type TooltipContent, type TooltipRow, type Transform, type TreemapSpec, type TrendlineConfig, type UpdateContext, VERSION, type ValidationError, type ValidationResult, type ValueInsights, type ValueRef, type ValueRule, type WaterfallSpec, type XKind, type XModel, type YModel, aggregateValues, analyzeChart, animate, applyA11y, applyAggregate, applyBin, applyCalculate, applyFilter, applyFold, applyPatch, applyPick, applyTimeUnit, applyTransform, applyTransforms, arc, area, assertValidSpec, autoInsightAnnotations, backOut, bandScale, bounceOut, buildCartesianInteraction, buildCartesianModel, buildComboModel, buildDataTableFallback, buildFacetModels, buildHistogramModel, buildRenderReport, cartesianInteractionBuilders, cartesianRenderers, categorical, chartTitleText, chartTypeLabel, checkExpression, clamp01, clamp255, compileExpression, compilePredicate, computeBackingSize, computeBins, computeFrame, computeSeriesInsights, contrastRatio, createDiv, createRoughPen, createSelectionStore, cubicIn, cubicInOut, cubicOut, curveCatmullRom, curveLinear, curveMonotoneX, curveStep, curveStepAfter, curveStepBefore, customRenderers, darkTheme, decimate, dependentParams, diverging, divergingColorScale, divergingSchemes, drawAnnotationLabels, drawAnnotations, drawAxesUnderlay, drawFacet, drawLegend, drawOverlay, drawTitle, drawTrendlineLabels, drawTrendlines, easings, elasticOut, ensureSketchFont, expoInOut, expoOut, facetReport, fillParentStyle, filterRows, fontString, formatDate, formatNumber, formatValue, getDevicePixelRatio, groupBy, hashString, inferFieldType, inferFieldTypes, inferValueType, interpolateArray, interpolateNumber, interpolateNumberArray, interpolateObject, interpolateOklab, interpolateRgb, isBrowser, isEmptyValue, isFaceted, isParamClause, isSlicerType, keyFields, legendSwatchWidth, lightTheme, line, linear, linearRegression, linearScale, linearToSrgb, lintSpec, literalToValue, logScale, lttbRun, makeMatcher, matchesValue, measureText, monotoneXTangents, mulberry32, niceDomain, oklabToOklch, oklabToRgb, oklchToOklab, ordinalColorScale, overlayTextToCanvasCmd, paintCanvasText, paintLegendSwatch, parseColor, parseNumberFormat, pivot, pointScale, polygonHachureLines, prefersReducedMotion, prettyDate, quadIn, quadInOut, quadOut, rampFromStops, readableTextColor, relativeLuminance, render, renderDashboard, renderToContext, repairSpec, resolveCurve, resolveDashboardLayout, resolveDashboardSections, resolveEmphasis, resolveEntrance, resolveFilterValues, resolveInsightOptions, resolveSketch, resolveTheme, resolveUpdate, rgbToOklab, rgbaToCss, rotatePoint, roundedRect, sampleArc, sequential, sequentialColorScale, sequentialSchemes, setMeasureContext, setStyle, sinInOut, slicerParamName, smartDate, specFields, srgbToLinear, summarize, summarizeChart, themes, tickIncrement, tickStep, ticks, timeScale, timeTickFormat, timeTicks, toHex, toPointer, tooltipEnabled, truncateTo, validateDashboard, validateSpec, wireViews, withAlpha, withSketchFont };