@opendata-ai/openchart-core 7.11.0 → 8.0.0-rc.10

package/dist/index.d.ts

@@ -31,8 +31,13 @@ declare const HEIGHT_SHORT_MAX = 350;
 declare function getHeightClass(height: number): HeightClass;
 /** Label display mode at a given breakpoint. */
 type LabelMode = 'all' | 'important' | 'none';
-/** Legend position at a given breakpoint. */
-type LegendPosition = 'top' | 'right' | 'bottom' | 'bottom-right' | 'inline';
+/**
+ * Legend position at a given breakpoint. `'top-left'` is a map-only overlay
+ * position: the legend floats inside the map area's top-left corner (with its
+ * own backdrop) instead of reserving a block of figure height. Charts treat
+ * it as the default position.
+ */
+type LegendPosition = 'top' | 'top-left' | 'right' | 'bottom' | 'bottom-right' | 'inline';
 /** Annotation position strategy. */
 type AnnotationPosition = 'inline' | 'tooltip-only';
 /** Axis label density (controls tick count reduction). */
@@ -139,8 +144,9 @@ interface ColumnConfig {
     /** Explicit column width (CSS value like "200px" or "20%"). Auto-sized if omitted. */
     width?: string;
     /**
-     * Number/date format string (d3-format or d3-time-format).
-     * Applied to the raw value before display. e.g. ",.0f" or "%Y-%m-%d".
+     * Number/date format string (d3-format or d3-time-format), or semantic
+     * keyword `'percent'` / `'currency'`. e.g. ",.0f", "%Y-%m-%d", "percent".
+     * Tables always show full precision (no compact notation).
      */
     format?: string;
     /** Heatmap: color the cell background based on numeric value. */
@@ -361,10 +367,12 @@ interface ResolvedTheme extends Theme {
  * - 'rule': reference lines as data marks
  * - 'tick': strip/rug plot marks
  * - 'rect': heatmaps and 2D binned plots
+ * - 'range': dumbbell / arrow / range-bar plots spanning two values per category
+ * - 'waffle': unit grids ("x of 100") for part-to-whole counts
+ * - 'calendar': GitHub-style calendar heatmap (weeks x weekdays, daily dates)
+ * - 'parliament': hemicycle seat-dot chart for election/legislature results
  */
-type MarkType = 'bar' | 'line' | 'area' | 'point' | 'circle' | 'arc' | 'text' | 'rule' | 'tick' | 'rect' | 'lollipop';
-/** @deprecated Use MarkType instead. Kept for internal migration references. */
-type ChartType = MarkType;
+type MarkType = 'bar' | 'line' | 'area' | 'point' | 'circle' | 'arc' | 'text' | 'rule' | 'tick' | 'rect' | 'lollipop' | 'beeswarm' | 'range' | 'waffle' | 'calendar' | 'parliament';
 /** A single color stop in a gradient definition. */
 interface GradientStop {
     /** Position along the gradient, 0 to 1. */
@@ -456,6 +464,19 @@ interface MarkDef {
     innerRadius?: number;
     /** Outer radius for arc marks. */
     outerRadius?: number;
+    /**
+     * Start angle in radians for arc marks. Defaults to 0 (full pie/donut).
+     * Combined with `endAngle`, restricts the pie/donut to a partial sweep,
+     * e.g. `startAngle: -Math.PI / 2, endAngle: Math.PI / 2` for a half-donut
+     * (election-style results donut). Angles follow d3's convention: 0 is
+     * straight up, increasing clockwise. Only meaningful when `type` is `'arc'`.
+     */
+    startAngle?: number;
+    /**
+     * End angle in radians for arc marks. Defaults to 2*Math.PI (full pie/donut).
+     * See `startAngle`. Only meaningful when `type` is `'arc'`.
+     */
+    endAngle?: number;
     /** Corner radius for rect/bar marks. 'pill' sets rx to half the bar thickness. */
     cornerRadius?: number | 'pill';
     /** Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band. */
@@ -482,6 +503,102 @@ interface MarkDef {
      * two competing diagonals.
      */
     trendline?: boolean;
+    /**
+     * Horizontal pixel offset from the data anchor. Only meaningful when `type`
+     * is `'text'`. Use it to lift a label clear of the mark it annotates instead
+     * of shifting the underlying data value.
+     */
+    dx?: number;
+    /**
+     * Vertical pixel offset from the data anchor (negative = up). Only meaningful
+     * when `type` is `'text'`. `{ type: 'text', dy: -10 }` floats each label ten
+     * pixels above its point.
+     */
+    dy?: number;
+    /** Horizontal alignment of text marks relative to their anchor. Defaults to `'center'`. */
+    align?: 'left' | 'center' | 'right';
+    /** Vertical alignment of text marks relative to their anchor. Defaults to `'middle'`. */
+    baseline?: 'top' | 'middle' | 'bottom';
+    /**
+     * Font size in pixels for text marks. Ignored when the `size` encoding channel
+     * is present (which scales font size from a data field). `size` is already
+     * taken by bar thickness, hence the distinct name.
+     */
+    fontSize?: number;
+    /**
+     * Pattern-fill reinforcement for filled marks (bar, area, arc).
+     *
+     * - `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,
+     *   crosshatch, vertical lines) layered over each series color so series
+     *   remain distinguishable without color vision. Marks too small to show
+     *   a legible pattern keep their solid fill.
+     * - `'none'` (default): solid fills only.
+     */
+    fillPattern?: 'auto' | 'none';
+    /**
+     * Visual style for range marks. Only meaningful when `type` is `'range'`.
+     * - 'dumbbell' (default): a dot at each end joined by a connector line.
+     *   The start dot is muted, the end dot carries the accent color.
+     * - 'arrow': a line with an arrowhead at the x2/y2 end, the strongest
+     *   "change between two points in time" form.
+     * - 'bar': a plain floating range bar spanning start to end.
+     */
+    style?: 'dumbbell' | 'arrow' | 'bar';
+    /**
+     * Color range marks by direction of change. Only meaningful when `type` is
+     * `'range'`. When true, increases (x2 > x, or y2 > y) use the theme's
+     * `positive` semantic color and decreases use `negative`. A field-based
+     * `encoding.color` takes precedence over direction coloring.
+     */
+    colorByDirection?: boolean;
+    /**
+     * Total number of cells in a waffle grid. Only meaningful when `type` is
+     * `'waffle'`. Category values normalize to this many cells via
+     * largest-remainder rounding so the grid always sums exactly. Default 100.
+     */
+    units?: number;
+    /**
+     * Number of columns in a waffle grid. Only meaningful when `type` is
+     * `'waffle'`. Rows derive from `units / columns`. Default 10.
+     */
+    columns?: number;
+    /**
+     * First day of the week for calendar marks. Only meaningful when `type` is
+     * `'calendar'`. Controls which weekday occupies the top row of each band.
+     * Defaults to 'monday' (ISO week convention).
+     */
+    weekStart?: 'monday' | 'sunday';
+    /**
+     * Corner radius in pixels for calendar day cells. Only meaningful when
+     * `type` is `'calendar'`. Defaults to 1.
+     */
+    cellRadius?: number;
+    /**
+     * Seat layout shape for parliament marks. Only meaningful when `type` is
+     * `'parliament'`. `'hemicycle'` (default, and currently the only shape)
+     * packs seats into concentric semicircular arcs, party-grouped left to
+     * right.
+     */
+    shape?: 'hemicycle';
+    /**
+     * Seat dot radius in pixels for parliament marks. `'auto'` (default) sizes
+     * dots to fill the available hemicycle rings for the given seat count.
+     * Only meaningful when `type` is `'parliament'`.
+     */
+    seatRadius?: number | 'auto';
+    /**
+     * The majority-threshold line and "N to win" label on parliament marks. Only
+     * meaningful when `type` is `'parliament'`. `true` (default) draws the line at
+     * a simple majority (half the seats plus one); `false` hides it. The object
+     * form overrides the threshold and label: `{ seats }` sets a custom seat count
+     * (e.g. a two-thirds supermajority) and `{ label }` overrides the default
+     * "N to win" text. A `seats` value outside `1..totalSeats` warns and falls
+     * back to the simple-majority default.
+     */
+    majorityLine?: boolean | {
+        seats?: number;
+        label?: string;
+    };
 }
 /** Data field type, following Vega-Lite conventions. */
 type FieldType = 'quantitative' | 'temporal' | 'nominal' | 'ordinal';
@@ -491,7 +608,11 @@ type AggregateOp = 'count' | 'sum' | 'mean' | 'median' | 'min' | 'max' | 'varian
 interface AxisConfig {
     /** Axis title text. If omitted, the field name is used. */
     title?: string;
-    /** Number format string (d3-format). e.g. ",.0f" for comma-separated integers. */
+    /**
+     * Number format: d3-format string (e.g. ",.0f"), or semantic keyword
+     * `'percent'` / `'currency'`. When omitted, compact notation (1k, 2.5M)
+     * is applied automatically.
+     */
     format?: string;
     /** Override tick count. Engine picks a sensible default if omitted. */
     tickCount?: number;
@@ -534,8 +655,12 @@ interface AxisConfig {
 }
 /** Scale configuration for an encoding channel. */
 interface ScaleConfig {
-    /** Explicit domain override. Auto-derived from data if omitted. */
-    domain?: [number, number] | string[];
+    /**
+     * Explicit domain override. Auto-derived from data if omitted.
+     * Continuous scales take `[min, max]`; threshold scales take the full
+     * list of class break values; categorical scales take the value list.
+     */
+    domain?: number[] | string[];
     /** Scale type override. Usually inferred from field type. */
     type?: ScaleType;
     /** Whether to nice-ify the domain for clean tick values. Defaults to true. */
@@ -546,6 +671,15 @@ interface ScaleConfig {
     clip?: boolean;
     /** Explicit range override. */
     range?: unknown[];
+    /**
+     * Named color scheme (Vega-Lite aligned). Resolved against the core palette
+     * registry (sequential: blue, green, orange, purple, teal; diverging:
+     * redBlue, brownTeal; categorical) during the pre-validation sugar
+     * expansion; common VL names (blues, greens, category10, ...) are accepted
+     * as aliases. Unknown names fail validation with the supported list.
+     * An explicit `range` wins over `scheme`.
+     */
+    scheme?: string;
     /** Reverse the range direction. */
     reverse?: boolean;
     /** Clamp output to the range. */
@@ -565,6 +699,28 @@ interface ScaleConfig {
 }
 /** Scale type, following Vega-Lite conventions. */
 type ScaleType = 'linear' | 'log' | 'pow' | 'sqrt' | 'symlog' | 'time' | 'utc' | 'ordinal' | 'band' | 'point' | 'quantile' | 'quantize' | 'threshold';
+/**
+ * Sort a categorical domain by the aggregated values of another field
+ * (Vega-Lite EncodingSortField).
+ */
+interface SortByField {
+    /** Data field whose values determine the category order. */
+    field: string;
+    /** Aggregate applied per category before comparing. Defaults to 'sum'. */
+    op?: AggregateOp;
+    /** Sort direction. Defaults to 'ascending'. */
+    order?: 'ascending' | 'descending';
+}
+/**
+ * A constant value definition for an encoding channel (Vega-Lite aligned).
+ * The VL idiom for a fixed visual property, e.g. `color: { value: '#1b7fa3' }`.
+ * Expanded to the matching mark-level property (fill/stroke, size, opacity)
+ * during the pre-validation sugar expansion.
+ */
+interface ValueDef {
+    /** The constant value: CSS color string, size number, opacity (0-1), or gradient. */
+    value: string | number | boolean | null | GradientDef;
+}
 /**
  * A single encoding channel mapping a data field to a visual property.
  *
@@ -596,8 +752,11 @@ interface EncodingChannel<TData extends DataRow = DataRow> {
     type: FieldType;
     /** Optional aggregate to apply before encoding. */
     aggregate?: AggregateOp;
-    /** Axis configuration. Set to `false` to suppress axis entirely (no space reserved). */
-    axis?: AxisConfig | false;
+    /**
+     * Axis configuration. Set to `false` to suppress axis entirely (no space
+     * reserved). `null` is accepted as a VL-aligned alias for `false`.
+     */
+    axis?: AxisConfig | false | null;
     /** Scale configuration. */
     scale?: ScaleConfig;
     /**
@@ -609,26 +768,28 @@ interface EncodingChannel<TData extends DataRow = DataRow> {
      * The string forms are still the canonical input — the boolean shorthand is
      * normalized to the matching string before reaching layout.
      *
-     * - undefined: chart-type default (see below)
+     * - undefined: chart-type default (see below) -- stacked for bar/column/area
      * - true | 'zero': stack from zero baseline
      * - 'normalize': stack and normalize to fraction of total (0-1 per category)
      * - 'center': center stacks around zero (streamgraph style)
-     * - null | false: no stacking -- renders overlap (area) or grouped/dodged (bar)
+     * - null | false: no stacking -- renders grouped/dodged (bar) or overlap (area)
      *
      * **Defaults differ by chart type:**
-     * - **Bar/Column**: defaults to grouped (side-by-side). Use `stack: 'zero'` (or `true`) for stacked bars.
-     * - **Area**: defaults to overlap (v6 breaking change). Use `stack: 'zero'` (or `true`)
-     *   to opt into stacked areas. Each overlapping series renders as a translucent
-     *   gradient band anchored at the y-domain baseline.
+     * - **Bar/Column**: defaults to stacked (`'zero'`), Vega-Lite aligned. Use
+     *   `stack: null` (or `false`) for grouped/side-by-side bars.
+     * - **Area**: defaults to stacked (`'zero'`), Vega-Lite aligned. Use
+     *   `stack: null` (or `false`) to opt into overlap rendering, where each
+     *   series renders as a translucent gradient band anchored at the
+     *   y-domain baseline.
      * - **Line**: stacking is not applied (lines always overlap).
      *
      * @example
-     * // Stacked horizontal bars (opt-in; default is grouped):
-     * "x": { "field": "revenue", "type": "quantitative", "stack": "zero" }
+     * // Grouped horizontal bars (opt-out; default is stacked):
+     * "x": { "field": "revenue", "type": "quantitative", "stack": null }
      *
      * @example
-     * // Stacked area (opt-in; default is overlap):
-     * "y": { "field": "value", "type": "quantitative", "stack": "zero" }
+     * // Overlap area (opt-out; default is stacked):
+     * "y": { "field": "value", "type": "quantitative", "stack": null }
      */
     stack?: boolean | 'zero' | 'normalize' | 'center' | null;
     /**
@@ -651,8 +812,22 @@ interface EncodingChannel<TData extends DataRow = DataRow> {
      * - 'descending': sort domain values descending
      * - null: use data order (no sorting)
      * - undefined: ascending (VL default)
+     * - 'x' | '-x' | 'y' | '-y': sort by another channel's values ('-' prefix
+     *   for descending). The VL ranked-bar idiom: `sort: '-y'` orders categories
+     *   by value, largest first. Resolved into an explicit domain during the
+     *   pre-validation sugar expansion.
+     * - string[]: explicit value order. Listed values come first (in the given
+     *   order); unlisted data values follow in data order.
+     * - SortByField: sort by the aggregated values of another field.
      */
-    sort?: 'ascending' | 'descending' | null;
+    sort?: 'ascending' | 'descending' | null | 'x' | '-x' | 'y' | '-y' | string[] | SortByField;
+    /**
+     * Legend configuration for this channel (Vega-Lite aligned).
+     * Only meaningful on the `color` channel. `null` hides the legend (the VL
+     * idiom for `legend.show = false`); a config object merges into the
+     * top-level `legend` (top-level keys win on conflict).
+     */
+    legend?: LegendConfig | null;
     /**
      * Display title override (Vega-Lite aligned).
      * Used as the label in tooltips instead of the raw field name.
@@ -661,7 +836,8 @@ interface EncodingChannel<TData extends DataRow = DataRow> {
     title?: string;
     /**
      * Format string for values (Vega-Lite aligned).
-     * For quantitative fields: d3-format string (e.g. ",.0f", "$,.2f").
+     * For quantitative fields: d3-format string (e.g. ",.0f", "$,.2f"),
+     * or semantic keyword `'percent'` / `'currency'`.
      * For temporal fields: d3-time-format string (e.g. "%Y", "%b %d").
      * Used in tooltips; `axis.format` takes precedence for axis tick labels.
      */
@@ -721,14 +897,16 @@ interface Encoding<TData extends DataRow = DataRow> {
     /**
      * Color channel. Required for arc marks (determines pie/donut slice coloring).
      * Optional for all other marks -- used for series differentiation on multi-series charts,
-     * or heatmap intensity. Accepts a conditional definition to apply colors based on data predicates.
+     * or heatmap intensity. Accepts a conditional definition to apply colors based on data predicates,
+     * or a bare `{ value }` constant (VL aligned; expanded to the mark-level fill/stroke).
      */
-    color?: EncodingChannel<TData> | ConditionalValueDef<TData>;
+    color?: EncodingChannel<TData> | ConditionalValueDef<TData> | ValueDef;
     /**
      * Size channel. Used by point/bubble charts to scale dot area by a quantitative field.
-     * Accepts a conditional definition to vary size based on data predicates.
+     * Accepts a conditional definition to vary size based on data predicates,
+     * or a bare `{ value }` constant (VL aligned; expanded to `mark.size`).
      */
-    size?: EncodingChannel<TData> | ConditionalValueDef<TData>;
+    size?: EncodingChannel<TData> | ConditionalValueDef<TData> | ValueDef;
     /**
      * Detail channel. Groups data into multiple series without mapping to a visual property.
      * Useful when you want separate lines per category but don't need the color to differ.
@@ -752,17 +930,14 @@ interface Encoding<TData extends DataRow = DataRow> {
     y2?: EncodingChannel<TData>;
     /**
      * Data-driven opacity (0-1 range). Accepts a conditional definition to vary opacity
-     * based on data predicates (e.g., highlight selected points).
-     */
-    opacity?: EncodingChannel<TData> | ConditionalValueDef<TData>;
-    /**
-     * Point shape encoding. Valid values: 'circle', 'square', 'diamond', 'triangle-up',
-     * 'triangle-down', 'cross'. Used on point/scatter marks to differentiate series by shape.
+     * based on data predicates (e.g., highlight selected points), or a bare `{ value }`
+     * constant (VL aligned; expanded to `mark.opacity`).
      */
-    shape?: EncodingChannel<TData>;
+    opacity?: EncodingChannel<TData> | ConditionalValueDef<TData> | ValueDef;
     /**
-     * Stroke dash pattern encoding. Maps a nominal field to different dash patterns
-     * on line marks. Useful when color alone doesn't distinguish series well.
+     * Stroke dash pattern encoding. Maps a nominal/ordinal field to different
+     * dash patterns on line and rule marks. Useful when color alone doesn't
+     * distinguish series well.
      */
     strokeDash?: EncodingChannel<TData>;
     /** Rotation angle encoding for point marks. Maps a quantitative field to 0-360 degrees. */
@@ -777,25 +952,15 @@ interface Encoding<TData extends DataRow = DataRow> {
      * multi-field tooltips. Independent of the x/y/color encoding.
      */
     tooltip?: EncodingChannel<TData> | EncodingChannel<TData>[];
-    /** Hyperlink encoding. Maps a field containing URLs to clickable marks. */
-    href?: EncodingChannel<TData>;
     /**
-     * Drawing order. Controls z-order and stacking sort order for bar/area marks.
-     * Lower values are drawn first (behind higher values).
-     */
-    order?: EncodingChannel<TData>;
-    /**
-     * Angular position for arc marks (pie/donut).
-     * Optional -- defaults to the `y` channel value when omitted.
-     * Not used by any other mark type.
+     * Angular position (slice value) for arc marks (pie/donut), the canonical
+     * value channel in v8. Waffle and parliament marks accept it too (the same
+     * part-to-whole value channel). `y` is still accepted on these marks as a
+     * deprecated alias for backward compatibility (a compile warning is emitted
+     * and `y` is populated from `theta` internally). Not used by any other mark
+     * type.
      */
     theta?: EncodingChannel<TData>;
-    /**
-     * Radial distance from center for arc marks.
-     * Optional -- only meaningful on donut charts (controls inner radius boundary).
-     * Not used by any other mark type.
-     */
-    radius?: EncodingChannel<TData>;
     /**
      * Facet channel: partitions data into a grid of small-multiple panels.
      * Each unique value of the facet field produces one panel. Panels share
@@ -803,6 +968,20 @@ interface Encoding<TData extends DataRow = DataRow> {
      * per-panel axes.
      */
     facet?: FacetChannel<TData>;
+    /**
+     * Row facet channel: partitions data into vertically-stacked panels.
+     * Each unique value of the row field produces one panel, arranged in a
+     * single column. Shares the x-axis scale by default; y-axis is independent.
+     * Mutually exclusive with `facet` and `column`.
+     */
+    row?: FacetChannel<TData>;
+    /**
+     * Column facet channel: partitions data into side-by-side panels.
+     * Each unique value of the column field produces one panel, arranged in a
+     * single row. Shares the y-axis scale by default; x-axis is independent.
+     * Mutually exclusive with `facet` and `row`.
+     */
+    column?: FacetChannel<TData>;
 }
 /** Encoding channel for graph nodes and edges. */
 interface GraphEncodingChannel {
@@ -907,15 +1086,24 @@ interface AnnotationOffset {
 }
 /** Anchor direction for annotation label placement relative to the data point. */
 type AnnotationAnchor = 'top' | 'bottom' | 'left' | 'right' | 'auto';
-/** Style overrides for the dot marker drawn at the connector's data-point endpoint. */
+/** Connector type for annotation labels. */
+type ConnectorType = 'straight' | 'curve' | 'drop-line';
+/** Object form of the connector config, allowing arrow control. */
+interface ConnectorConfig {
+    /** Connector style. */
+    type: ConnectorType;
+    /** Whether to draw an arrowhead at the data-point end. Default: true for curve, false for straight. Drop-line never takes a head. */
+    arrow?: boolean;
+}
+/** Style overrides for the dot marker drawn at the data point. */
 interface AnnotationDot {
-    /** Circle radius in pixels. Default 5. */
+    /** Circle radius in pixels. Default 4. */
     radius?: number;
     /** Fill color. Defaults to theme background for an "open ring" look. */
     fill?: string;
-    /** Stroke color. Defaults to theme text color. */
+    /** Stroke color. Defaults to the connector's resolved stroke, so marker and leader read as one system. */
     stroke?: string;
-    /** Stroke width in pixels. Default 2. */
+    /** Stroke width in pixels. Default 1.5. */
     strokeWidth?: number;
 }
 /** Base properties shared by all annotation types. */
@@ -945,7 +1133,13 @@ interface TextAnnotation extends AnnotationBase {
     x: string | number;
     /** Y-axis data value or position. */
     y: string | number;
-    /** The annotation text. Required for text annotations. */
+    /**
+     * The annotation text. Required for text annotations.
+     *
+     * Supports inline `**bold**` spans, so emphasis lands on the key phrase rather
+     * than the whole block: `'Inflation peaked at **8.5%**'`. Unmatched `**` (and
+     * empty `****`) render literally. `\n` starts a new line.
+     */
     text: string;
     /** Thinning priority (lower = kept longer at narrow widths). When omitted, spec order is used. */
     priority?: number;
@@ -953,12 +1147,23 @@ interface TextAnnotation extends AnnotationBase {
      * Optional muted second-tone text rendered below the primary `text`.
      * Used for supporting context (e.g. methodology, source). Newlines in
      * `text` still produce multi-line primary; subtitle is a separate block.
+     *
+     * Supports the same inline `**bold**` spans as `text`. When a subtitle is
+     * present and no `fontWeight` is set, the primary `text` resolves to weight
+     * 700 — the lede + context stack.
      */
     subtitle?: string;
     /**
-     * Optional dot marker drawn at the connector's data-point endpoint.
-     * `true` enables the default open-ring style. Pass an object to override
-     * radius, fill, stroke, or strokeWidth.
+     * Open-ring marker drawn on the data point itself (not on the pulled-back
+     * connector tip).
+     *
+     * Left unset, a default marker appears whenever a connector is enabled and
+     * carries no arrowhead — the leader points, the ring lands. An arrowed
+     * connector gets no marker unless you ask for one: the head already marks the
+     * spot. `dot: false` is always bare; an explicit `dot` always wins.
+     *
+     * `true` uses the default style; pass an object to override radius, fill,
+     * stroke, or strokeWidth.
      */
     dot?: boolean | AnnotationDot;
     /** Font size override. */
@@ -971,13 +1176,19 @@ interface TextAnnotation extends AnnotationBase {
     anchor?: AnnotationAnchor;
     /**
      * Connector from label to anchor point.
-     * - `true` (default): straight line
-     * - `'straight'`: straight line (alias of `true`)
+     * - `true` (default): straight line, no arrow
+     * - `'straight'`: straight line, no arrow
      * - `'curve'`: curved arrow with arrowhead
-     * - `'drop-line'`: vertical line through the data point's x; label sits beside the line and auto-flips to the opposite side if it would overflow the chart area
+     * - `'drop-line'`: vertical line through the data point's x
+     * - `{ type, arrow? }`: object form for explicit arrow control
      * - `false`: no connector
+     *
+     * The connector leaves the text block on the side facing the data point, with
+     * a small standoff gap. A leader shorter than 8px is dropped as noise (the
+     * marker alone reads better), as is a connector whose target sits inside the
+     * text block. Widen `offset` if you want the line back.
      */
-    connector?: boolean | 'straight' | 'curve' | 'drop-line';
+    connector?: boolean | ConnectorType | ConnectorConfig;
     /** Per-endpoint offsets for the connector line. Allows fine-tuning where the connector starts and ends. */
     connectorOffset?: {
         /** Offset for the label-end of the connector. */
@@ -985,8 +1196,14 @@ interface TextAnnotation extends AnnotationBase {
         /** Offset for the data-point-end of the connector. */
         to?: AnnotationOffset;
     };
-    /** Background color behind the text. Useful for readability over chart lines. */
-    background?: string;
+    /**
+     * Background plate behind the text, for readability over chart lines.
+     *
+     * `true` uses the theme surface, so the plate follows light/dark mode. A
+     * color string sets it explicitly. Prefer `true`: a hardcoded '#ffffff' stays
+     * white in dark mode and the text turns light-gray-on-white.
+     */
+    background?: string | true;
     /** Whether to show the paint-order stroke halo behind text. Default true. Set false for white text on colored backgrounds. */
     halo?: boolean;
 }
@@ -1028,7 +1245,14 @@ interface RangeAnnotation extends AnnotationBase {
  * Useful for baselines (zero), targets, or thresholds.
  */
 interface RefLineAnnotation extends AnnotationBase {
-    type: 'refline' | 'rule';
+    /**
+     * Discriminant. `'refline'` is canonical and the only value in the type.
+     * `'rule'` (it collides with the `rule` mark type) is still accepted at
+     * runtime for backward compatibility -- the spec-sugar pass rewrites it to
+     * `'refline'` with a deprecation warning before validation -- but it is not
+     * part of this type. Use `'refline'`.
+     */
+    type: 'refline';
     /** X-axis value for a vertical reference line. */
     x?: string | number;
     /** Y-axis value for a horizontal reference line. */
@@ -1212,7 +1436,11 @@ interface LabelConfig {
     suffix?: string;
     /** Fixed CSS color for all labels. Overrides the default fill-derived color. */
     color?: string;
-    /** Per-series pixel offsets for fine-tuning label positions, keyed by series name. */
+    /**
+     * Per-series pixel offsets for fine-tuning label positions, keyed by series name.
+     * @deprecated Per-series pixel offsets are a workaround for collision bugs
+     * now fixed by the layout engine. Will be removed in a future version.
+     */
     offsets?: Record<string, AnnotationOffset>;
     /** Font size in pixels for bar/column value labels. */
     fontSize?: number;
@@ -1236,6 +1464,46 @@ interface LegendConfig {
     /** Series names to exclude from the legend. Excluded series still render in the chart. */
     exclude?: string[];
 }
+/**
+ * Configuration for the searchable series highlight input (`seriesSearch`).
+ * The boolean form (`seriesSearch: true`) uses the defaults.
+ */
+interface SeriesSearchConfig {
+    /** Placeholder text for the search input. Defaults to "Find a series". */
+    placeholder?: string;
+}
+/**
+ * Configuration for the "you draw it" interactive engagement format
+ * (`youDrawIt`). The reader draws their guess of the trend from `from` to the
+ * right edge before the real line reveals. Line marks only, single-series only.
+ */
+interface YouDrawItConfig {
+    /**
+     * The x value (matching `encoding.x`'s domain) where drawing starts. Data
+     * before this point renders normally; data at or after it is hidden behind
+     * a hatched "draw here" region until reveal.
+     */
+    from: string | number;
+    /** Prompt text shown in the hatched drawing region. Defaults to "Draw your guess". */
+    prompt?: string;
+    /** Label for the skip-to-reveal button. Defaults to "Show me". */
+    revealLabel?: string;
+    /**
+     * Optional extra comparison line (e.g. "what everyone else guessed"),
+     * supplied by the host app. Rendered in a third, visually distinct style
+     * alongside the reader's guess and the real line after reveal.
+     */
+    comparisonLine?: Array<{
+        x: string | number;
+        y: number;
+    }>;
+}
+/**
+ * Content composition for an endpoint-label entry: the series name, the
+ * formatted value, or both joined on one line. See
+ * {@link EndpointLabelsConfig.content}.
+ */
+type EndpointLabelContent = 'label' | 'value' | 'label value';
 /**
  * Configuration for the endpoint labels column rendered at the chart's right edge
  * for multi-series line/area charts. Each entry pairs the series name with its
@@ -1273,6 +1541,21 @@ interface EndpointLabelsConfig {
      * - `'both'`: labels on both left (leading) and right (trailing) edges.
      */
     ends?: 'end' | 'both';
+    /**
+     * What each entry renders.
+     * - `'label'`: series name only.
+     * - `'value'`: formatted value only.
+     * - `'label value'`: series name and value joined on one line.
+     *
+     * When omitted, entries render the series name with the formatted value on
+     * a second line (the classic endpoint column). Pass an object to set the
+     * leading and trailing columns independently, e.g. the classic slope-chart
+     * look is `{ leading: 'label value', trailing: 'value' }`.
+     */
+    content?: EndpointLabelContent | {
+        leading?: EndpointLabelContent;
+        trailing?: EndpointLabelContent;
+    };
     /** Field to read the displayed value from. Defaults to `encoding.y.field`. */
     valueField?: string;
     /** d3-format string for the value. Defaults to `encoding.y.axis.format`. */
@@ -1422,14 +1705,14 @@ interface Metric {
 }
 /**
  * Encoding for arc marks (pie/donut charts).
- * - `y`: required (quantitative — the slice value)
+ * - `theta`: required (quantitative — the canonical slice value channel)
  * - `color`: required (nominal/ordinal — the category)
- * - `theta`: optional (defaults to `y` channel)
- * - `radius`: optional (donut inner radius)
+ * - `y`: deprecated alias for `theta`, accepted for backward compatibility
  */
 interface ArcEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
-    y: EncodingChannel<TData>;
-    color: EncodingChannel<TData>;
+    /** Canonical value channel for arc marks (quantitative — the slice value). */
+    theta: EncodingChannel<TData>;
+    color: EncodingChannel<TData> | ConditionalValueDef<TData>;
 }
 /**
  * Encoding for line marks.
@@ -1485,6 +1768,62 @@ interface LollipopEncoding<TData extends DataRow = DataRow> extends Encoding<TDa
     x: EncodingChannel<TData>;
     y: EncodingChannel<TData>;
 }
+/**
+ * Encoding for beeswarm marks (dodged distribution dots).
+ * - Exactly one positional channel is quantitative: the value axis
+ *   (x = horizontal swarm, y = vertical swarm).
+ * - The other positional channel is optional (nominal/ordinal): grouped
+ *   swarms, one lane per category. The cross axis has no scale; the dodge
+ *   layout computes pixel offsets around each lane center.
+ */
+interface BeeswarmEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+    x?: EncodingChannel<TData>;
+    y?: EncodingChannel<TData>;
+}
+/**
+ * Encoding for range marks (dumbbell / arrow / range-bar plots).
+ * - Horizontal (the common editorial form): `y` nominal/ordinal category,
+ *   `x` quantitative start, `x2` quantitative end.
+ * - Vertical: `x` nominal/ordinal category, `y` quantitative start,
+ *   `y2` quantitative end.
+ */
+interface RangeEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+    x: EncodingChannel<TData>;
+    y: EncodingChannel<TData>;
+}
+/**
+ * Encoding for waffle marks (unit grids for part-to-whole counts).
+ * - `color`: required (nominal/ordinal, the category)
+ * - `theta`: the canonical quantitative share, the same part-to-whole value
+ *   channel arc marks use. `y` is a deprecated alias, accepted for backward
+ *   compatibility.
+ */
+interface WaffleEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+    color: EncodingChannel<TData> | ConditionalValueDef<TData>;
+}
+/**
+ * Encoding for parliament marks (hemicycle seat-dot charts).
+ * - `color`: required (nominal/ordinal, the party)
+ * - `theta`: the canonical quantitative seat count, the same part-to-whole
+ *   value channel arc/waffle marks use. `y` is a deprecated alias, accepted
+ *   for backward compatibility.
+ */
+interface ParliamentEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+    color: EncodingChannel<TData> | ConditionalValueDef<TData>;
+}
+/**
+ * Encoding for calendar marks (GitHub-style calendar heatmaps).
+ * - `x`: required (temporal, daily dates, one row per day)
+ * - `color`: required (quantitative, the per-day value)
+ *
+ * The calendar computes its own weeks-x-weekdays geometry: no positional
+ * scales or axes. Multi-year data partitions into one stacked band per year,
+ * all bands sharing a single color scale and legend.
+ */
+interface CalendarEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+    x: EncodingChannel<TData>;
+    color: EncodingChannel<TData>;
+}
 /**
  * Encoding for text marks (data-positioned labels).
  * - `text`: required (the field to render as text)
@@ -1511,6 +1850,28 @@ interface RectEncoding<TData extends DataRow = DataRow> extends Encoding<TData>
     x: EncodingChannel<TData>;
     y: EncodingChannel<TData>;
 }
+/**
+ * Author-facing accessibility overrides.
+ *
+ * Everything here is optional; when omitted, openchart auto-generates alt
+ * text, ARIA labels, and a screen-reader data table from the spec and data.
+ */
+interface A11yConfig {
+    /**
+     * Alt text announced by screen readers for the chart as a whole. Replaces
+     * the auto-generated description. Also settable via the top-level
+     * `description` field (Vega-Lite convention); this field wins when both
+     * are present.
+     */
+    description?: string;
+    /**
+     * Hide the chart from assistive technology entirely (`aria-hidden`).
+     * Use only when the chart is decorative or the surrounding content
+     * already conveys the same information. Also suppresses the hidden
+     * screen-reader data table and keyboard mark navigation.
+     */
+    hidden?: boolean;
+}
 /**
  * Properties shared across all ChartSpec mark variants.
  * Extracted to avoid repeating them in every union member.
@@ -1518,12 +1879,47 @@ interface RectEncoding<TData extends DataRow = DataRow> extends Encoding<TData>
  * @internal
  */
 interface BaseChartSpec<TData extends DataRow = DataRow> {
-    /** Data array: each element is a row with field values. */
+    /**
+     * Data array: each element is a row with field values.
+     * The Vega-Lite object form `{ values: [...] }` is also accepted at runtime
+     * and unwrapped during the pre-validation sugar expansion. `{ url }` is not
+     * supported (openchart does not fetch data).
+     */
     data: TData[];
     /** Data transforms applied in order before encoding (filter, bin, calculate, timeUnit). */
     transform?: Transform[];
     /** Editorial chrome (title, subtitle, source, etc.). */
     chrome?: Chrome;
+    /**
+     * Top-level title sugar (Vega-Lite aligned). Expanded into `chrome.title`
+     * (and `chrome.subtitle` for the object form). `chrome.title` wins when
+     * both are set.
+     */
+    title?: string | {
+        text: string;
+        subtitle?: string;
+    };
+    /** Top-level subtitle sugar. Expanded into `chrome.subtitle`; `chrome.subtitle` wins. */
+    subtitle?: string;
+    /**
+     * Alt text for the rendered chart (Vega-Lite aligned). Sugar for
+     * `a11y.description`; `a11y.description` wins when both are set.
+     * When absent, alt text is auto-generated from the spec and data.
+     */
+    description?: string;
+    /** Accessibility overrides. See {@link A11yConfig}. */
+    a11y?: A11yConfig;
+    /**
+     * Fixed render width in pixels (Vega-Lite aligned). Overrides the
+     * container-derived width. When both `width` and `height` are set,
+     * `responsive: false` is implied unless `responsive` is set explicitly.
+     * Omit for the default container-driven sizing.
+     */
+    width?: number;
+    /** Fixed render height in pixels (Vega-Lite aligned). See `width`. */
+    height?: number;
+    /** Accepted for Vega-Lite compatibility and ignored (with a compile warning). */
+    $schema?: string;
     /**
      * KPI/metric cells rendered as a horizontal row between subtitle and chart
      * area. Each cell shows a label/value pair with optional delta and secondary
@@ -1560,7 +1956,12 @@ interface BaseChartSpec<TData extends DataRow = DataRow> {
     darkMode?: DarkMode;
     /** Whether to show the tryOpenData.ai watermark. Defaults to true. */
     watermark?: boolean;
-    /** Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed. */
+    /**
+     * Series names to hide from rendering by default. This is the authored
+     * persistence target for legend visibility. Runtime legend toggles
+     * (legend-toggle edit events) layer on top of this via ephemeral runtime
+     * sets but never modify it.
+     */
     hiddenSeries?: string[];
     /** Per-series visual overrides, keyed by series name (the color field value). */
     seriesStyles?: Record<string, SeriesStyle>;
@@ -1584,6 +1985,22 @@ interface BaseChartSpec<TData extends DataRow = DataRow> {
      * explicitly set.
      */
     crosshair?: boolean;
+    /**
+     * Searchable series highlight ("find your country"). Renders a compact
+     * search input above the chart with typeahead over the color channel's
+     * distinct values. Selecting a value adds it to the highlight set
+     * (multi-select chips, removable); clearing restores the authored
+     * `encoding.color.highlight` baseline. Requires a categorical color
+     * encoding. Mutually exclusive with edit mode (search wins).
+     */
+    seriesSearch?: boolean | SeriesSearchConfig;
+    /**
+     * "You draw it" interactive engagement format: the reader draws their
+     * guess of the trend before the real line reveals. Line marks only,
+     * single-series only. Mutually exclusive with edit mode (validation
+     * warning if both are enabled; youDrawIt is disabled).
+     */
+    youDrawIt?: YouDrawItConfig;
     /**
      * Display mode controlling how much chart chrome is rendered.
      *
@@ -1684,6 +2101,21 @@ type ChartSpec<TData extends DataRow = DataRow> = (BaseChartSpec<TData> & {
         type: 'lollipop';
     });
     encoding: LollipopEncoding<TData>;
+}) | (BaseChartSpec<TData> & {
+    mark: 'beeswarm' | (MarkDef & {
+        type: 'beeswarm';
+    });
+    encoding: BeeswarmEncoding<TData>;
+}) | (BaseChartSpec<TData> & {
+    mark: 'range' | (MarkDef & {
+        type: 'range';
+    });
+    encoding: RangeEncoding<TData>;
+}) | (BaseChartSpec<TData> & {
+    mark: 'waffle' | (MarkDef & {
+        type: 'waffle';
+    });
+    encoding: WaffleEncoding<TData>;
 }) | (BaseChartSpec<TData> & {
     mark: 'text' | (MarkDef & {
         type: 'text';
@@ -1704,6 +2136,16 @@ type ChartSpec<TData extends DataRow = DataRow> = (BaseChartSpec<TData> & {
         type: 'rule';
     });
     encoding: Encoding<TData>;
+}) | (BaseChartSpec<TData> & {
+    mark: 'calendar' | (MarkDef & {
+        type: 'calendar';
+    });
+    encoding: CalendarEncoding<TData>;
+}) | (BaseChartSpec<TData> & {
+    mark: 'parliament' | (MarkDef & {
+        type: 'parliament';
+    });
+    encoding: ParliamentEncoding<TData>;
 });
 /**
  * Table specification: input for data table visualizations.
@@ -1834,7 +2276,29 @@ interface LayerSpec<TData extends DataRow = DataRow> {
     transform?: Transform[];
     /** Editorial chrome (title, subtitle, source, etc.). */
     chrome?: Chrome;
-    /** Annotations on the layered view. */
+    /** Top-level title sugar (VL aligned). Expanded into `chrome.title`; `chrome.title` wins. */
+    title?: string | {
+        text: string;
+        subtitle?: string;
+    };
+    /** Top-level subtitle sugar. Expanded into `chrome.subtitle`; `chrome.subtitle` wins. */
+    subtitle?: string;
+    /** Fixed render width in pixels (VL aligned). Overrides the container-derived width. */
+    width?: number;
+    /** Fixed render height in pixels (VL aligned). Overrides the container-derived height. */
+    height?: number;
+    /** Accepted for Vega-Lite compatibility and ignored (with a compile warning). */
+    $schema?: string;
+    /**
+     * Annotations for the layered chart. When present, these are the
+     * annotations rendered and available for editing. When absent, falls back
+     * to the first leaf layer's annotations. Annotations on second and later
+     * leaf layers are not rendered.
+     *
+     * For edit persistence: the `data-annotation-index` stamped on each
+     * rendered annotation maps to this array (or the first leaf's if this is
+     * unset). Place annotations here for reliable index-based edit matching.
+     */
     annotations?: Annotation[];
     /** Label display configuration. `false` disables all labels, `true` uses defaults. */
     labels?: LabelSpec;
@@ -1850,7 +2314,12 @@ interface LayerSpec<TData extends DataRow = DataRow> {
     watermark?: boolean;
     /** Resolution strategy for shared scales/axes/legends. */
     resolve?: ResolveConfig;
-    /** Hidden series names. */
+    /**
+     * Series names to hide from rendering by default. This is the authored
+     * persistence target for legend visibility. Runtime legend toggles
+     * (legend-toggle edit events) layer on top of this via ephemeral runtime
+     * sets but never modify it.
+     */
     hiddenSeries?: string[];
     /** Endpoint labels column, inherited by child layers that don't set their own. */
     endpointLabels?: boolean | EndpointLabelsConfig;
@@ -1924,6 +2393,8 @@ interface SankeySpec {
      * number (data value 28 renders as "28%"). For currency: "$,.0f" or "$~s".
      * For SI suffixes: "~s" (renders 1000 as "1k"). When not set, values use
      * the default number formatter.
+     * @deprecated Use the encoding channel's `format` field instead. This
+     * property is expanded into the encoding during compilation.
      */
     valueFormat?: string;
 }
@@ -1983,6 +2454,102 @@ interface TileMapSpec {
     /**
      * d3-format string applied to tile values, legend labels, and tooltips.
      * Examples: ".1f" for one decimal, "$,.0f" for currency, "~s" for SI.
+     * @deprecated Use the encoding channel's `format` field instead. This
+     * property is expanded into the encoding during compilation.
+     */
+    valueFormat?: string;
+}
+/** Supported map projections. */
+type MapProjection = 'albersUsa' | 'mercator' | 'equalEarth' | 'identity';
+/** Focus target for map camera: feature id(s) to zoom/pan to. */
+/**
+ * Fit the point layer's cluster. `true` fits every point; `{ field, value }`
+ * fits only the points whose data row has `row[field] === value` (e.g. only the
+ * campuses rated "F"), which lets a story pan between sub-clusters.
+ */
+type MapPointsFocus = true | {
+    field: string;
+    value: string | number;
+};
+type MapFocus = string | number | Array<string | number> | {
+    features: string | number | Array<string | number>;
+    padding?: number;
+} | {
+    points: MapPointsFocus;
+    padding?: number;
+};
+/** Geo configuration for map specs. */
+interface MapGeo {
+    /** TopoJSON topology object. User imports this from us-atlas, world-atlas, or their own source. */
+    features: unknown;
+    /** Field in the TopoJSON feature properties to use as the join key. Defaults to 'id'. */
+    idField?: string;
+    /** Map projection. Defaults to 'albersUsa'. */
+    projection?: MapProjection;
+    /**
+     * Focus the camera. A feature id (or array) fits those features; `{ features, padding }`
+     * adds breathing room; `{ points: true, padding }` fits the points layer's cluster
+     * instead of any feature (use when points occupy a small part of a large feature, so
+     * fitting the feature would leave the cluster small and off-center);
+     * `{ points: { field, value }, padding }` fits only the matching point subset, so a
+     * story can pan between sub-clusters. null clears focus from a prior story step.
+     */
+    focus?: MapFocus | null;
+}
+/** Encoding channels specific to map visualizations. */
+interface MapEncoding {
+    /** Join key field in the data. Required for choropleth; optional in basemap-only mode (points layer with empty data). */
+    key?: EncodingChannel;
+    /** Color encoding (quantitative or nominal). Drives fill color of features. Optional when a points layer is present (basemap-only mode). */
+    color?: EncodingChannel;
+    /** Tooltip encoding (optional). */
+    tooltip?: EncodingChannel | EncodingChannel[];
+}
+/** Point/symbol layer rendered above choropleth features. */
+interface MapPointsLayer {
+    /** Tabular data for the points. Independent of the choropleth data join. */
+    data: DataRow[];
+    /** Field holding longitude (x coordinate). */
+    longitude: EncodingChannel;
+    /** Field holding latitude (y coordinate). */
+    latitude: EncodingChannel;
+    /** Optional quantitative size encoding. Area-proportional: r proportional to sqrt(value). No size legend is rendered in v1; explain the scale in chrome.subtitle if needed. */
+    size?: EncodingChannel;
+    /** Optional color encoding (nominal or quantitative). Independent scale from choropleth. */
+    color?: EncodingChannel;
+    /** Tooltip channel(s), same shape as MapEncoding.tooltip. */
+    tooltip?: EncodingChannel | EncodingChannel[];
+    /** Stable id for event callbacks. Data-update transitions for points are not yet supported. */
+    key?: EncodingChannel;
+    /** Fill opacity for point circles. Default 0.65. Range 0-1. */
+    opacity?: number;
+}
+interface MapSpec {
+    /** Discriminant: always "map". */
+    type: 'map';
+    /** Geo configuration: TopoJSON features, join key, and projection. */
+    geo: MapGeo;
+    /** Tabular data to join to geo features. */
+    data: DataRow[];
+    /** Encoding channels mapping data fields to visual properties. */
+    encoding: MapEncoding;
+    /** Editorial chrome (title, subtitle, source, byline, footer). */
+    chrome?: Chrome;
+    /** Legend display configuration. */
+    legend?: LegendConfig;
+    /** Theme configuration overrides. */
+    theme?: ThemeConfig;
+    /** Dark mode behavior. Defaults to "off". */
+    darkMode?: DarkMode;
+    /** Whether to show the tryOpenData.ai watermark. Defaults to true. */
+    watermark?: boolean;
+    /** Optional point/symbol layer rendered above choropleth features. */
+    points?: MapPointsLayer;
+    /** Animation configuration for entrance animations. */
+    animation?: AnimationSpec;
+    /**
+     * d3-format string applied to color values in tooltips and legend.
+     * @deprecated Use the encoding channel's `format` field instead.
      */
     valueFormat?: string;
 }
@@ -2015,6 +2582,8 @@ interface BarListSpec {
     /**
      * d3-format string applied to bar values and tooltips.
      * Examples: ".1f" for one decimal, "$,.0f" for currency, "~s" for SI.
+     * @deprecated Use the encoding channel's `format` field instead. This
+     * property is expanded into the encoding during compilation.
      */
     valueFormat?: string;
 }
@@ -2040,9 +2609,17 @@ interface BarListEncoding {
  * - GraphSpec: has `type: 'graph'`
  * - SankeySpec: has `type: 'sankey'`
  * - TileMapSpec: has `type: 'tilemap'`
+ * - MapSpec: has `type: 'map'`
  * - BarListSpec: has `type: 'barlist'`
+ *
+ * Election parliament (hemicycle) charts are `ChartSpec` with `mark:
+ * 'parliament'`, not a separate top-level type: seat data (party + seats)
+ * maps naturally onto encoding.color/y like arc and waffle, and riding the
+ * existing chart pipeline gets scales, legend, tooltips, a11y, and dark mode
+ * for free instead of a second bespoke compile path (see
+ * `packages/engine/src/charts/parliament/`).
  */
-type VizSpec = ChartSpec | LayerSpec | TableSpec | GraphSpec | SankeySpec | TileMapSpec | BarListSpec;
+type VizSpec = ChartSpec | LayerSpec | TableSpec | GraphSpec | SankeySpec | TileMapSpec | MapSpec | BarListSpec;
 /**
  * Chart spec without runtime data, for persistence/storage.
  * Generic: `ChartSpecWithoutData<MyRow>` constrains encoding field names.
@@ -2056,10 +2633,14 @@ type GraphSpecWithoutData = Omit<GraphSpec, 'nodes' | 'edges'>;
 type SankeySpecWithoutData = Omit<SankeySpec, 'data'>;
 /** TileMap spec without runtime data, for persistence/storage. */
 type TileMapSpecWithoutData = Omit<TileMapSpec, 'data'>;
+/** Map spec without runtime data, for persistence/storage. */
+type MapSpecWithoutData = Omit<MapSpec, 'data' | 'points'> & {
+    points?: Omit<MapPointsLayer, 'data'>;
+};
 /** BarList spec without runtime data, for persistence/storage. */
 type BarListSpecWithoutData = Omit<BarListSpec, 'data'>;
 /** Union of data-stripped spec types for persistence/storage. */
-type StoredVizSpec = ChartSpecWithoutData | TableSpecWithoutData | GraphSpecWithoutData | SankeySpecWithoutData | TileMapSpecWithoutData | BarListSpecWithoutData;
+type StoredVizSpec = ChartSpecWithoutData | TableSpecWithoutData | GraphSpecWithoutData | SankeySpecWithoutData | TileMapSpecWithoutData | MapSpecWithoutData | BarListSpecWithoutData;
 /** Logical AND combinator for filter predicates. */
 interface LogicalAnd<T> {
     and: T[];
@@ -2215,9 +2796,10 @@ interface Condition<TData extends DataRow = DataRow> {
     test: FilterPredicate;
     /**
      * Static value to use when the condition is true.
-     * Accepted values: CSS color string, opacity (0-1), size number, or boolean flag.
+     * Accepted values: CSS color string, opacity (0-1), size number, boolean flag,
+     * or a gradient definition for color channels.
      */
-    value?: string | number | boolean | null;
+    value?: string | number | boolean | null | GradientDef;
     /**
      * Data field to use when the condition is true.
      * Constrained to column names of `TData` when using `ChartSpec<TData>`.
@@ -2237,24 +2819,34 @@ interface ConditionalValueDef<TData extends DataRow = DataRow> {
     condition: Condition<TData> | Condition<TData>[];
     /**
      * Default value when no condition matches.
-     * Accepted values: CSS color string, opacity (0-1), size number, or boolean flag.
+     * Accepted values: CSS color string, opacity (0-1), size number, boolean flag,
+     * or a gradient definition for color channels.
      */
-    value?: string | number | boolean | null;
+    value?: string | number | boolean | null | GradientDef;
 }
 /**
  * Check if a channel definition is a regular EncodingChannel (has 'field' at top level).
- * Use this to narrow `EncodingChannel | ConditionalValueDef` in encoding channels
- * that support conditional encoding (color, size, opacity).
+ * Use this to narrow `EncodingChannel | ConditionalValueDef | ValueDef` in encoding
+ * channels that support conditional encoding (color, size, opacity).
  */
-declare function isEncodingChannel<TData extends DataRow = DataRow>(def: EncodingChannel<TData> | ConditionalValueDef<TData> | undefined): def is EncodingChannel<TData>;
+declare function isEncodingChannel<TData extends DataRow = DataRow>(def: EncodingChannel<TData> | ConditionalValueDef<TData> | ValueDef | undefined): def is EncodingChannel<TData>;
 /**
  * Check if a channel definition is a ConditionalValueDef.
  */
-declare function isConditionalDef<TData extends DataRow = DataRow>(def: EncodingChannel<TData> | ConditionalValueDef<TData> | undefined): def is ConditionalValueDef<TData>;
+declare function isConditionalDef<TData extends DataRow = DataRow>(def: EncodingChannel<TData> | ConditionalValueDef<TData> | ValueDef | undefined): def is ConditionalValueDef<TData>;
+/**
+ * Check if a channel definition is a bare ValueDef (constant value, no field
+ * or condition). These are expanded to mark-level properties during the
+ * pre-validation sugar expansion.
+ */
+declare function isValueDef<TData extends DataRow = DataRow>(def: EncodingChannel<TData> | ConditionalValueDef<TData> | ValueDef | undefined): def is ValueDef;
 /** All valid mark type strings for runtime checking. */
 declare const MARK_TYPES: ReadonlySet<string>;
-/** @deprecated Use MARK_TYPES instead. */
-declare const CHART_TYPES: ReadonlySet<string>;
+/**
+ * Mark types that lay out inside the chart area without positional axes
+ * (no axis or gridline computation; margins shrink to padding).
+ */
+declare function isAxislessMark(markType: MarkType): boolean;
 /**
  * Extract the mark type string from a mark field (string or MarkDef).
  */
@@ -2277,11 +2869,17 @@ declare function isSankeySpec(spec: VizSpec | Record<string, unknown>): spec is
 declare function isTileMapSpec(spec: VizSpec | Record<string, unknown>): spec is TileMapSpec;
 /** Check if a spec is a BarListSpec. */
 declare function isBarListSpec(spec: VizSpec | Record<string, unknown>): spec is BarListSpec;
+/** Check if a spec is a MapSpec. */
+declare function isMapSpec(spec: VizSpec | Record<string, unknown>): spec is MapSpec;
 /** Check if an annotation is a TextAnnotation. */
 declare function isTextAnnotation(annotation: Annotation): annotation is TextAnnotation;
 /** Check if an annotation is a RangeAnnotation. */
 declare function isRangeAnnotation(annotation: Annotation): annotation is RangeAnnotation;
-/** Check if an annotation is a RefLineAnnotation. */
+/**
+ * Check if an annotation is a RefLineAnnotation. Also accepts the deprecated
+ * `'rule'` type at runtime (pre-sugar-expansion input), since `annotation.type`
+ * may not yet be narrowed to the canonical `'refline'` form.
+ */
 declare function isRefLineAnnotation(annotation: Annotation): annotation is RefLineAnnotation;
 /** Human-readable display names for mark types (used in alt text, error messages). */
 declare const MARK_DISPLAY_NAMES: Record<MarkType, string>;
@@ -2309,15 +2907,11 @@ interface EncodingRule {
     y2?: ChannelRule;
     color: ChannelRule;
     size: ChannelRule;
-    shape?: ChannelRule;
     opacity?: ChannelRule;
     strokeDash?: ChannelRule;
     text?: ChannelRule;
     tooltip?: ChannelRule;
-    href?: ChannelRule;
-    order?: ChannelRule;
     theta?: ChannelRule;
-    radius?: ChannelRule;
     detail: ChannelRule;
 }
 /**
@@ -2336,10 +2930,17 @@ interface EncodingRule {
  * - point: both axes are quantitative
  * - text/rule: fully optional positioning
  * - tick/rect: both axes required, any type
+ * - beeswarm: both axes optional at the channel level; the compiler enforces
+ *   the combination (exactly one quantitative value axis, the other axis an
+ *   optional nominal/ordinal lane channel)
+ * - waffle: no positional axes; y is the share value (quantitative, with
+ *   theta accepted as an alias like arc), color is the category
+ * - calendar: x is the daily date (temporal), color the per-day value
+ *   (quantitative); no y channel (the calendar owns its own geometry)
+ * - parliament: no positional axes; theta (aliased to y) is the seat count
+ *   (quantitative), color the party
  */
 declare const MARK_ENCODING_RULES: Record<MarkType, EncodingRule>;
-/** @deprecated Use MARK_ENCODING_RULES instead. */
-declare const CHART_ENCODING_RULES: Record<MarkType, EncodingRule>;
 /** Encoding rule for a single graph visual channel. */
 interface GraphChannelRule {
     /** Whether this channel is required. */
@@ -2379,26 +2980,36 @@ type ElementRef = {
     type: 'annotation';
     index: number;
     id?: string;
+    /** RFC 6901 JSON Pointer to the edited property in the spec. */
+    path?: string;
 } | {
     type: 'chrome';
     key: ChromeKey;
+    /** RFC 6901 JSON Pointer to the edited property in the spec. */
+    path?: string;
 } | {
     type: 'series-label';
     series: string;
+    /** RFC 6901 JSON Pointer to the edited property in the spec. */
+    path?: string;
 } | {
     type: 'legend';
+    /** RFC 6901 JSON Pointer to the edited property in the spec. */
+    path?: string;
 } | {
     type: 'legend-entry';
     series: string;
     index: number;
+    /** RFC 6901 JSON Pointer to the edited property in the spec. */
+    path?: string;
 };
 /** Helper constructors for ergonomic ElementRef creation. */
 declare const elementRef: {
-    readonly annotation: (index: number, id?: string) => ElementRef;
-    readonly chrome: (key: ChromeKey) => ElementRef;
-    readonly seriesLabel: (series: string) => ElementRef;
-    readonly legend: () => ElementRef;
-    readonly legendEntry: (series: string, index: number) => ElementRef;
+    readonly annotation: (index: number, id?: string, path?: string) => ElementRef;
+    readonly chrome: (key: ChromeKey, path?: string) => ElementRef;
+    readonly seriesLabel: (series: string, path?: string) => ElementRef;
+    readonly legend: (path?: string) => ElementRef;
+    readonly legendEntry: (series: string, index: number, path?: string) => ElementRef;
 };
 /**
  * Discriminated union of all element edit events.
@@ -2413,21 +3024,31 @@ declare const elementRef: {
  */
 type ElementEdit = {
     type: 'annotation';
+    element: ElementRef;
     annotation: TextAnnotation;
     offset: AnnotationOffset;
 } | {
     type: 'annotation-connector';
+    element: ElementRef;
     annotation: TextAnnotation;
     endpoint: 'from' | 'to';
     offset: AnnotationOffset;
 } | {
     type: 'range-label';
+    element: ElementRef;
     annotation: RangeAnnotation;
     labelOffset: AnnotationOffset;
 } | {
     type: 'refline-label';
+    element: ElementRef;
     annotation: RefLineAnnotation;
     labelOffset: AnnotationOffset;
+} | {
+    type: 'annotation-anchor';
+    element: ElementRef;
+    annotation: TextAnnotation;
+    x: string | number;
+    y: string | number;
 } | {
     type: 'chrome';
     key: ChromeKey;
@@ -2440,10 +3061,21 @@ type ElementEdit = {
 } | {
     type: 'legend';
     offset: AnnotationOffset;
-} | {
+}
+/**
+ * Transient legend visibility toggle. Reports the same runtime show/hide
+ * a reader triggers; not persisted by openchart. To author default-hidden
+ * series, set `spec.hiddenSeries` directly. Hosts building spec
+ * persistence should generally not write legend-toggle edits back into
+ * the authored spec. `hidden: true` means the series was just hidden.
+ */
+ | {
     type: 'legend-toggle';
     series: string;
     hidden: boolean;
+} | {
+    type: 'add';
+    annotation: TextAnnotation;
 } | {
     type: 'delete';
     element: ElementRef;
@@ -2479,6 +3111,14 @@ interface MarkEvent {
  * or ChartProps (React component) to receive interaction callbacks.
  */
 interface ChartEventHandlers {
+    /**
+     * Explicitly enable or disable edit interactions (drag, select, keyboard
+     * delete/edit). When true, the interaction layer is wired even without
+     * onEdit. When false, all edit interactions are suppressed even when
+     * onEdit is provided. When omitted, each interaction block uses its
+     * existing callback-presence gate.
+     */
+    editable?: boolean;
     /** Called when a data mark is clicked. */
     onMarkClick?: (event: MarkEvent) => void;
     /** Called when the mouse enters a data mark. */
@@ -2487,6 +3127,12 @@ interface ChartEventHandlers {
     onMarkLeave?: () => void;
     /** Called when a legend entry is toggled (clicked to show/hide a series). */
     onLegendToggle?: (series: string, visible: boolean) => void;
+    /**
+     * Called when the series search (`seriesSearch`) changes the highlight set.
+     * Receives the full set of highlighted values after the change, including
+     * the authored `encoding.color.highlight` baseline.
+     */
+    onHighlightChange?: (values: string[]) => void;
     /** Called when an annotation element is clicked. */
     onAnnotationClick?: (annotation: Annotation, event: MouseEvent) => void;
     /** Called when a text annotation label is dragged to a new position. */
@@ -2499,6 +3145,15 @@ interface ChartEventHandlers {
     onDeselect?: (element: ElementRef) => void;
     /** Fired when inline text editing commits. Also flows through onEdit as a 'text-edit' event. */
     onTextEdit?: (element: ElementRef, oldText: string, newText: string) => void;
+    /**
+     * Fired when a "you draw it" (`youDrawIt`) drawing is revealed (button click
+     * or programmatic reveal), with the reader's guess in data coordinates,
+     * ordered by x. For newsrooms aggregating reader guesses.
+     */
+    onReveal?: (guess: Array<{
+        x: string | number;
+        y: number;
+    }>) => void;
 }
 
 /** A rectangle defined by position and dimensions. */
@@ -2593,6 +3248,12 @@ interface AxisTick {
     position: number;
     /** Formatted label string for display. */
     label: string;
+    /**
+     * The untruncated label, set only when `label` was shortened with an ellipsis
+     * to fit the rotated-tick reservation. Renderers should surface this as the
+     * tick's accessible/tooltip text so the full category name is never lost.
+     */
+    fullLabel?: string;
     /** Secondary label text from axis.labelField. */
     subtitle?: string;
 }
@@ -2653,6 +3314,23 @@ interface AxisLayout {
         angle?: number;
     };
 }
+/** The four built-in fill pattern shapes for series reinforcement. */
+type FillPatternType = 'diagonal' | 'dot' | 'crosshatch' | 'vertical';
+/**
+ * A resolved per-mark fill pattern (engine output for `mark.fillPattern: 'auto'`).
+ *
+ * The renderer builds one SVG `<pattern>` per unique (type, base, line)
+ * combination: a tile of `base` color overlaid with `line`-colored pattern
+ * geometry. Marks referencing the same resolved pattern share one def.
+ */
+interface ResolvedFillPattern {
+    /** Pattern shape assigned to this mark's series. */
+    type: FillPatternType;
+    /** Base tile color: the series' solid color. */
+    base: string;
+    /** Pattern line/dot color, contrast-picked against `base`. */
+    line: string;
+}
 /** Accessibility attributes for a mark. */
 interface MarkAria {
     /** ARIA label for the mark. Optional when `decorative: true` — decorative
@@ -2738,6 +3416,8 @@ interface AreaMark {
     interpolate?: string;
     /** Fill color or gradient. */
     fill: string | GradientDef;
+    /** Resolved fill pattern. Present only when `mark.fillPattern: 'auto'` assigned one. */
+    pattern?: ResolvedFillPattern;
     /** Fill opacity. */
     fillOpacity: number;
     /** Optional stroke for the top boundary. */
@@ -2783,6 +3463,8 @@ interface RectMark {
     height: number;
     /** Fill color or gradient. */
     fill: string | GradientDef;
+    /** Resolved fill pattern. Present only when `mark.fillPattern: 'auto'` assigned one. */
+    pattern?: ResolvedFillPattern;
     /** Stroke color. */
     stroke?: string;
     /** Stroke width. */
@@ -2840,6 +3522,8 @@ interface ArcMark {
     endAngle: number;
     /** Fill color or gradient. */
     fill: string | GradientDef;
+    /** Resolved fill pattern. Present only when `mark.fillPattern: 'auto'` assigned one. */
+    pattern?: ResolvedFillPattern;
     /** Stroke color (usually white for slice separation). */
     stroke: string;
     /** Stroke width. */
@@ -2896,10 +3580,14 @@ interface TextMarkLayout {
     type: 'textMark';
     /** Stable identity key for data-update transitions. */
     key?: string;
-    /** X position. */
+    /** X position, including any `dx` offset. */
     x: number;
-    /** Y position. */
+    /** Y position, including any `dy` offset. */
     y: number;
+    /** Data-space anchor before `dx` was applied. Set only when the mark is offset. */
+    anchorX?: number;
+    /** Data-space anchor before `dy` was applied. Set only when the mark is offset. */
+    anchorY?: number;
     /** Text content to display. */
     text: string;
     /** Fill color. */
@@ -2912,6 +3600,11 @@ interface TextMarkLayout {
     fontFamily?: string;
     /** Horizontal text alignment. */
     textAnchor: 'start' | 'middle' | 'end';
+    /**
+     * Vertical baseline. Omit for the SVG default (alphabetic), which the calendar
+     * and parliament marks rely on — they hand-compute baseline-relative offsets.
+     */
+    dominantBaseline?: 'auto' | 'hanging' | 'central' | 'text-after-edge';
     /** Rotation angle in degrees. */
     angle?: number;
     /** Original data row. */
@@ -3016,10 +3709,22 @@ interface ResolvedLabel {
         to: Point;
         /** Actual data point the connector is calling out. Renderer uses this for the endpoint marker. */
         endpoint?: Point;
+        /** Author's from-end nudge, re-applied on every geometry rebuild (mirrors `endpoint` for `to`). */
+        fromOffset?: {
+            dx: number;
+            dy: number;
+        };
         /** Connector line color. */
         stroke: string;
         /** Connector style: straight line, curved arrow, or vertical drop-line through the data point. */
         style: 'straight' | 'curve' | 'drop-line';
+        /** Whether to draw an arrowhead at the data-point end. */
+        arrow: boolean;
+        /**
+         * Which edge of the label block the connector leaves from. Renderers use it
+         * to shape the curve's control point. Internal; not part of the spec.
+         */
+        exit?: 'horizontal' | 'vertical';
     };
     /** Background color behind the label text. */
     background?: string;
@@ -3036,6 +3741,16 @@ interface ResolvedAnnotation {
     type: 'text' | 'range' | 'refline';
     /** Stable identifier from the spec annotation, for selection/edit callbacks. */
     id?: string;
+    /**
+     * Index of the originating annotation in `spec.annotations`.
+     *
+     * The resolved array is a *filtered* view of the spec array -- an annotation
+     * whose position falls outside the scale domain resolves to nothing and is
+     * dropped -- so a resolved array index is NOT a spec index. Anything that has
+     * to reach back to the authored annotation (thinning's priority/responsive
+     * lookup, faceted footnote numbering) must key on this.
+     */
+    specIndex?: number;
     /** Label text (if any). */
     label?: ResolvedLabel;
     /** For range: the highlighted rectangle in pixel coordinates. */
@@ -3058,8 +3773,9 @@ interface ResolvedAnnotation {
     /** Z-index for render ordering. Higher values render on top. */
     zIndex?: number;
     /**
-     * For text annotations: optional dot marker drawn at the connector's
-     * data-point endpoint. Coordinates match `label.connector.to` exactly.
+     * For text annotations: the endpoint marker drawn at the data point.
+     * Coordinates sit on the data point itself (plus any `connectorOffset.to`),
+     * not on the pulled-back `label.connector.to`.
      */
     dot?: {
         x: number;
@@ -3108,10 +3824,24 @@ interface LegendEntry {
     /** True for overflow indicator entries ("+N more"). Not interactive. */
     overflow?: boolean;
 }
+/** The encoding channel a legend keys. */
+type LegendChannel = 'color' | 'size';
 /** Base legend layout fields shared by all legend types. */
 interface BaseLegendLayout {
-    /** Where the legend is positioned relative to the chart area. */
-    position: 'top' | 'right' | 'bottom' | 'bottom-right' | 'inline';
+    /**
+     * Which encoding channel this legend keys. Omitted means `'color'` (every
+     * legend was a color legend before size legends existed).
+     *
+     * This is the identity that makes plural legends safe: click-to-toggle-series
+     * must fire for color entries and never for size circles, and selection/drag
+     * must be able to tell two legends apart. Without it, `.oc-legend` and
+     * `data-legend-index` are ambiguous across legends and the DOM queries that
+     * read them silently pick whichever comes first.
+     */
+    channel?: LegendChannel;
+    /** Where the legend is positioned relative to the chart area. `'top-left'`
+     *  is a map-only overlay position (floats inside the map area). */
+    position: 'top' | 'top-left' | 'right' | 'bottom' | 'bottom-right' | 'inline';
     /** Bounding box for the legend (pixel coordinates). */
     bounds: Rect;
     /** Entry label style. */
@@ -3165,8 +3895,94 @@ interface GradientLegendLayout extends BaseLegendLayout {
     /** Formatted maximum value label. */
     maxLabel: string;
 }
-/** Resolved legend layout — either categorical (swatches) or gradient (continuous bar). */
-type LegendLayout = CategoricalLegendLayout | GradientLegendLayout;
+/** A positioned value label on a continuous/binned color legend. */
+interface ContinuousLegendTick {
+    /** The data value this label marks. */
+    value: number;
+    /** Formatted label text (channel format applied). */
+    label: string;
+    /** Label x position (pixel coordinates). */
+    x: number;
+    /** Horizontal text anchor for the label. */
+    anchor: 'start' | 'middle' | 'end';
+}
+/** A discrete class swatch in a binned continuous legend. */
+interface ContinuousLegendBin {
+    /** Swatch x position (pixel coordinates). */
+    x: number;
+    /** Swatch width in pixels. */
+    width: number;
+    /** Fill color. */
+    color: string;
+}
+/**
+ * Continuous color legend for quantitative color scales on charts.
+ *
+ * Two rendering modes, resolved from the color channel's scale type:
+ * - `gradient`: a single gradient-filled bar with min/max labels (plus a
+ *   midpoint label at the neutral value for diverging ramps).
+ * - `binned`: a contiguous swatch row (quantile/quantize/threshold scales)
+ *   with boundary value labels between swatches at the class breaks.
+ */
+interface ContinuousLegendLayout extends BaseLegendLayout {
+    /** Discriminant for legend type. */
+    type: 'continuous';
+    /** Rendering mode: gradient bar or binned swatch row. */
+    mode: 'gradient' | 'binned';
+    /** The color bar rectangle (pixel coordinates). */
+    bar: Rect;
+    /** Gradient color stops (empty in binned mode). */
+    colorStops: GradientColorStop[];
+    /** Class swatches, left to right (empty in gradient mode). */
+    bins: ContinuousLegendBin[];
+    /** Value labels rendered below the bar. */
+    ticks: ContinuousLegendTick[];
+    /** Text baseline y for the value labels (pixel coordinates). */
+    labelY: number;
+}
+/**
+ * One graduated circle in a size legend: a representative value from the size
+ * scale's domain, drawn at the radius that value actually resolves to.
+ */
+interface SizeLegendCircle {
+    /** The data value this circle stands for. */
+    value: number;
+    /** Formatted label text. */
+    label: string;
+    /** Radius in pixels -- the *same* scale the marks use, never a re-derivation. */
+    radius: number;
+    /** Center x, relative to the legend bounds. */
+    cx: number;
+    /** Center y, relative to the legend bounds. Circles sit on a common baseline. */
+    cy: number;
+    /** Label baseline y, relative to the legend bounds. */
+    labelY: number;
+}
+/**
+ * Size legend: graduated circles keying a quantitative `size` encoding.
+ *
+ * The circles are drawn nested (concentric, sharing a bottom edge) rather than
+ * side by side -- the newsroom convention, and it makes the *ratio* between
+ * magnitudes legible instead of just their order.
+ *
+ * The keyed values come from the scale's DOMAIN, not the data extent. The size
+ * scale clamps, so with an explicit `scale.domain` every datum past `domain[1]`
+ * renders at max radius; keying the data extent would imply the biggest circle
+ * equals the biggest datum when it may not.
+ */
+interface SizeLegendLayout extends BaseLegendLayout {
+    /** Discriminant for legend type. */
+    type: 'size';
+    /** Graduated circles, smallest first. */
+    circles: SizeLegendCircle[];
+    /** Stroke color for the circle outlines. */
+    stroke: string;
+}
+/**
+ * Resolved legend layout: categorical (swatches), gradient (tilemap bar),
+ * continuous (chart color bar), or size (graduated circles).
+ */
+type LegendLayout = CategoricalLegendLayout | GradientLegendLayout | ContinuousLegendLayout | SizeLegendLayout;
 /** A single resolved endpoint-label entry, fully positioned. */
 interface EndpointLabelEntry {
     /** Series identifier (matches mark.seriesKey). */
@@ -3241,7 +4057,7 @@ interface TooltipContent {
 }
 /** Accessibility metadata for the entire visualization. */
 interface A11yMetadata {
-    /** Generated alt text describing the visualization. */
+    /** Alt text describing the visualization: the author's `a11y.description` / `description` when set, auto-generated otherwise. */
     altText: string;
     /** Tabular data fallback for screen readers. Each inner array is a row. */
     dataTableFallback: unknown[][];
@@ -3249,6 +4065,13 @@ interface A11yMetadata {
     role: string;
     /** Whether the visualization is keyboard-navigable. */
     keyboardNavigable: boolean;
+    /**
+     * Hide the visualization from assistive technology (`aria-hidden="true"`,
+     * no screen-reader table, no keyboard mark navigation). Optional because
+     * only chart compilation sets it, and only on author opt-out via
+     * `a11y.hidden`.
+     */
+    hidden?: boolean;
 }
 /** One fully-resolved animation phase. */
 interface ResolvedAnimationPhase {
@@ -3302,6 +4125,95 @@ interface ResolvedMetricBar {
     /** Cells laid out evenly across the chart width. */
     cells: ResolvedMetricCell[];
 }
+/**
+ * Reserved band for the series search input (`seriesSearch`). The band is
+ * empty SVG space between the chrome/metrics block and the top legend; the
+ * vanilla adapter overlays an absolutely-positioned DOM combobox aligned to
+ * this rect, so mounting it never changes the container's size.
+ */
+interface ResolvedSeriesSearch {
+    /** Band left x in layout coordinates. */
+    x: number;
+    /** Band top y in layout coordinates. */
+    y: number;
+    /** Band width. */
+    width: number;
+    /** Input row height (the reservation adds a gap below this). */
+    height: number;
+    /** Resolved input placeholder text. */
+    placeholder: string;
+    /** Distinct color-channel values available for search, in data order. */
+    values: string[];
+}
+/**
+ * One x-sample the reader's drawing snaps to: a pixel x position paired with
+ * its data-x value. `xValue` is the value reported by `onReveal`; it falls
+ * back to the pixel x when the data value can't be recovered.
+ */
+interface YouDrawItSample {
+    /** Pixel x position within the chart area. */
+    px: number;
+    /** Data-coordinate x value at this sample (from the target line's data). */
+    xValue: string | number;
+}
+/**
+ * Linear y pixel-to-data anchors, so the vanilla layer can map a drawn pixel
+ * y back to a data value for `onReveal` without holding the scale object.
+ * Present only when the y scale is invertible (continuous scales).
+ */
+interface YouDrawItYInvert {
+    /** Top pixel of the drawing area. */
+    topPixel: number;
+    /** Bottom pixel of the drawing area. */
+    bottomPixel: number;
+    /** Data value at the top pixel. */
+    topData: number;
+    /** Data value at the bottom pixel. */
+    bottomData: number;
+}
+/**
+ * Scale inversion anchors serialized from the engine so the vanilla layer
+ * can convert pixel positions to data-space values without holding d3
+ * scale objects. Generalizes the YouDrawItYInvert pattern to both axes.
+ */
+interface ScaleInvert {
+    /** For continuous scales: two reference pixel-to-data anchor points. */
+    topPixel: number;
+    bottomPixel: number;
+    topData: number;
+    bottomData: number;
+    /** Scale type so the vanilla layer applies the correct inverse transform. */
+    scaleType?: 'linear' | 'log' | 'pow' | 'sqrt' | 'symlog' | 'time';
+    /** For band/point scales: ordered domain values and their pixel centers. */
+    domain?: (string | number)[];
+    positions?: number[];
+}
+/**
+ * Resolved geometry and config for the "you draw it" interactive format
+ * (`youDrawIt`). The vanilla adapter uses this to render the hatched drawing
+ * region, capture pointer input, and mask/reveal the real line. Present only
+ * when the spec enables `youDrawIt` on a valid single-series line chart.
+ */
+interface ResolvedYouDrawIt {
+    /** Pixel x position of `from` within the chart area (drawing starts here). */
+    fromX: number;
+    /** The chart drawing area, for clamping pointer input and sizing the hatch region. */
+    area: Rect;
+    /** X samples (pixel + data value) at or after `from`, ascending by pixel x. Drawing snaps to these. */
+    samples: YouDrawItSample[];
+    /** Resolved prompt text for the hatched region. */
+    prompt: string;
+    /** Resolved skip-to-reveal button label. */
+    revealLabel: string;
+    /** Stroke color of the target line (the reader's guess uses a distinct pen style, but shares the palette for continuity). */
+    lineColor: string;
+    /** seriesKey of the target line mark, so the vanilla layer can find its DOM element. Undefined for a single-series line with no color encoding. */
+    targetSeriesKey?: string;
+    /** Pixel-to-data y anchors for reporting the guess in data coordinates. Absent when the y scale isn't invertible. */
+    yInvert?: YouDrawItYInvert;
+    /** Optional comparison line, resolved to pixel points parallel to the target line's points. */
+    comparisonPoints?: Point[];
+}
 /**
  * A single panel in a faceted (small-multiples) layout.
  * Each panel has its own marks, axes, and drawing area but typically
@@ -3328,6 +4240,7 @@ interface FacetPanelLayout {
         y: number;
         fontSize: number;
         fontWeight: number;
+        textAnchor?: 'start' | 'middle' | 'end';
     };
 }
 /** Layout for a faceted (small-multiples) chart. */
@@ -3340,6 +4253,8 @@ interface FacetLayout {
     columns: number;
     /** Whether scales are shared across panels. */
     sharedScales: boolean;
+    /** How panels are arranged: 'row' (vertical stack), 'column' (horizontal), 'wrap' (grid). */
+    direction: 'row' | 'column' | 'wrap';
 }
 /**
  * ChartLayout: the complete engine output for chart visualizations.
@@ -3356,6 +4271,10 @@ interface ChartLayout {
     chrome: ResolvedChrome;
     /** Resolved KPI metric bar. Present only when spec.metrics is supplied and fits. */
     metrics?: ResolvedMetricBar;
+    /** Reserved series-search band. Present only when spec.seriesSearch is enabled. */
+    seriesSearch?: ResolvedSeriesSearch;
+    /** Resolved "you draw it" config. Present only when spec.youDrawIt is enabled and valid. */
+    youDrawIt?: ResolvedYouDrawIt;
     /** Resolved axis layouts. */
     axes: {
         x?: AxisLayout;
@@ -3367,8 +4286,22 @@ interface ChartLayout {
     marks: Mark[];
     /** Resolved annotations with pixel positions. */
     annotations: ResolvedAnnotation[];
-    /** Legend layout (position, entries, bounds). */
+    /**
+     * Primary legend (the color legend). Kept as a singular slot: it is what every
+     * existing consumer reads, and a chart's legend is a color legend unless it
+     * says otherwise.
+     */
     legend: LegendLayout;
+    /**
+     * Every legend on the chart, in render order -- the color legend plus, when a
+     * quantitative `size` channel is encoded, a size legend.
+     *
+     * `legend` is `legends[0]` when a color legend exists. Consumers that reserve
+     * space or hit-test **must** iterate this array: a bubble chart keys both
+     * continent (color) and population (size), and reserving margin for only the
+     * first leaves the second drawing on top of the plot.
+     */
+    legends: LegendLayout[];
     /**
      * Right-side endpoint labels column for multi-series line/area charts.
      * Empty `entries` means the column is suppressed (single-series, opt-out, or
@@ -3396,6 +4329,10 @@ interface ChartLayout {
     crosshair: boolean;
     /** Real text measurement function from the adapter (for accurate SVG text wrapping). */
     measureText?: MeasureTextFn;
+    /** Scale inversion anchors for the x axis. Used by anchor drag to convert pixel to data-space. */
+    xInvert?: ScaleInvert;
+    /** Scale inversion anchors for the y axis. Used by anchor drag to convert pixel to data-space. */
+    yInvert?: ScaleInvert;
     /** Faceted (small-multiples) layout. When present, renderers iterate panels instead of using top-level marks/axes. */
     facet?: FacetLayout;
 }
@@ -3806,6 +4743,143 @@ interface TileMapLayout {
     /** Text measurement function for the rendering adapter. */
     measureText: MeasureTextFn;
 }
+/** A structured compile warning with a code and context. */
+interface CompileWarning {
+    code: string;
+    message: string;
+    context?: Record<string, unknown>;
+}
+/** Resolved focus target for map camera framing. */
+interface MapFocusLayout {
+    target: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        padding: number;
+    };
+    ids: Array<string | number>;
+}
+/** A resolved map feature mark with computed SVG path and fill. */
+interface MapFeatureMark {
+    type: 'map-feature';
+    /** SVG path `d` attribute for this feature's shape. */
+    path: string;
+    /** CSS fill color. */
+    fill: string;
+    /** CSS stroke color (border). */
+    stroke: string;
+    /** Stroke width in px. */
+    strokeWidth: number;
+    /** Feature ID (from TopoJSON). */
+    id: string | number;
+    /** Feature name (from properties, if available). */
+    name?: string;
+    /** Original joined data row (null if no data matched this feature). */
+    data: Record<string, unknown> | null;
+    /** Accessibility attributes. */
+    aria: MarkAria;
+    /** Index for stagger animation ordering. */
+    animationIndex: number;
+    /** Bounding box in map-local coordinates. */
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Centroid in map-local coordinates. */
+    centroid: [number, number];
+}
+/** A resolved map point mark with projected coordinates and visual properties. */
+interface MapPointMark {
+    type: 'map-point';
+    /** Projected center x in map-local coordinates. */
+    cx: number;
+    /** Projected center y in map-local coordinates. */
+    cy: number;
+    /** Radius in pixels (base radius before camera counter-scaling). */
+    r: number;
+    /** CSS fill color. */
+    fill: string;
+    /** CSS stroke color. */
+    stroke: string;
+    /** Stroke width in px. */
+    strokeWidth: number;
+    /** Fill opacity (0-1). */
+    fillOpacity: number;
+    /** Stable key for events. */
+    key: string;
+    /** Original data row. */
+    data: Record<string, unknown>;
+    /** Accessibility attributes. */
+    aria: MarkAria;
+    /** Index for stagger animation ordering. */
+    animationIndex: number;
+}
+/** Border paths for the map (interior borders and coastline/outline). */
+interface MapBorders {
+    /** SVG path `d` for interior borders between features. */
+    interiorPath: string;
+    /** SVG path `d` for the outer boundary / coastline. */
+    outlinePath: string;
+    /** Stroke color for interior borders. */
+    interiorStroke: string;
+    /** Stroke color for outer boundary. */
+    outlineStroke: string;
+}
+/**
+ * MapLayout: the complete engine output for map visualizations.
+ *
+ * Contains everything an adapter needs to render the map: dimensions,
+ * chrome, feature paths, borders, legend, tooltip descriptors, and
+ * accessibility metadata.
+ */
+interface MapLayout {
+    /** The map drawing area (after chrome and legend are subtracted). */
+    area: Rect;
+    /** Resolved chrome text elements with positions and styles. */
+    chrome: ResolvedChrome;
+    /** Resolved feature marks with paths, fills, and joined data. */
+    features: MapFeatureMark[];
+    /** Border paths (interior mesh and outline). */
+    borders: MapBorders;
+    /** Resolved point marks for the symbol layer (empty array if no points layer). */
+    pointMarks: MapPointMark[];
+    /** Categorical legend for the point color channel (null if no point color). */
+    pointCategoricalLegend: CategoricalLegendLayout | null;
+    /** Continuous legend for the point color channel (null if no point color). */
+    pointContinuousLegend: ContinuousLegendLayout | null;
+    /** Continuous color legend for quantitative mode (null if hidden or categorical). */
+    continuousLegend: ContinuousLegendLayout | null;
+    /** Categorical swatch legend for nominal mode (null if hidden or quantitative). */
+    categoricalLegend: CategoricalLegendLayout | null;
+    /** Tooltip content descriptors keyed by feature ID. */
+    tooltipDescriptors: Map<string, TooltipContent>;
+    /** Accessibility metadata for the map. */
+    a11y: A11yMetadata;
+    /** Resolved theme. */
+    theme: ResolvedTheme;
+    /** Total SVG width in pixels. */
+    width: number;
+    /** Total SVG height in pixels. */
+    height: number;
+    /** Resolved animation config (undefined if animation is disabled). */
+    animation: ResolvedAnimation | undefined;
+    /** Whether to render the watermark. */
+    watermark: boolean;
+    /** Text measurement function for the rendering adapter. */
+    measureText: MeasureTextFn;
+    /** Structured compile warnings (unmatched keys, missing data, winding issues). */
+    warnings: CompileWarning[];
+    /** The (width, height) passed to the projection's fitSize -- camera fits against this, not the SVG viewBox. */
+    mapSize: {
+        width: number;
+        height: number;
+    };
+    /** Resolved focus target for camera framing (null if no focus). */
+    focus: MapFocusLayout | null;
+}
 /** A resolved bar list row with computed positions and visual properties. */
 interface BarListRowMark {
     type: 'barlist-row';
@@ -3907,6 +4981,24 @@ interface CompileOptions {
     darkMode?: boolean;
     /** Whether to show the tryOpenData.ai watermark. Defaults to true. */
     watermark?: boolean;
+    /**
+     * Enable development-time diagnostics (WCAG contrast warnings via
+     * `console.warn`). The engine is isomorphic, so it never sniffs
+     * `process.env`; the host decides what "dev" means and passes this flag.
+     * Warnings are advisory only and never throw. Defaults to false.
+     */
+    dev?: boolean;
+    /**
+     * Sink for advisory spec warnings (deprecations, did-you-mean suggestions,
+     * unknown scheme names, overplotting/beeswarm budget notes, etc.). The engine
+     * is isomorphic and side-effect-free by default: rather than writing to the
+     * global `console`, it routes every advisory warning through this callback so
+     * a host can collect, reroute, or silence them (e.g. suppress under SSR, fail
+     * a test on any warning, surface them in a dev overlay). When omitted, the
+     * engine defaults to `console.warn`. Never called with fatal errors, which are
+     * thrown instead.
+     */
+    onWarn?: (message: string) => void;
     /**
      * Real text measurement function provided by the adapter.
      * Uses a hidden canvas or DOM element for accurate text dimensions.
@@ -3915,6 +5007,18 @@ interface CompileOptions {
     measureText?: MeasureTextFn;
     /** Extra pixels to reserve on the right margin for a secondary y-axis. Set by compileLayer when resolve.scale.y is 'independent'. */
     rightAxisReserve?: number;
+    /**
+     * Extra pixels to reserve below the plot for the auto-thinning footnote list.
+     * Chicken-and-egg: thinning needs the chart area to decide what to demote, but
+     * the footnotes it produces need space carved out of that same area. compileChart
+     * resolves it by compiling once to learn the footnote count, then recompiling with
+     * this set. Callers should not set it; it is internal to that second pass.
+     */
+    footnoteReserve?: number;
+    /** Recursion depth of the footnote-reserve convergence pass. Internal to compileChart. */
+    footnotePass?: number;
+    /** Set after facet height growth to prevent unbounded recursion. Internal to compileFaceted. */
+    facetHeightGrown?: boolean;
     /**
      * Use this chart drawing area instead of computing one from chrome, axes,
      * and legend reservations. Set by compileLayer when compiling leaf layers so
@@ -3945,8 +5049,8 @@ interface CompileTableOptions extends CompileOptions {
  * These are approximations suitable for checking palette accessibility,
  * not medical-grade simulations.
  */
-/** The three common types of color vision deficiency. */
-type ColorBlindnessType = 'protanopia' | 'deuteranopia' | 'tritanopia';
+/** The four common types of color vision deficiency. */
+type ColorBlindnessType = 'protanopia' | 'deuteranopia' | 'tritanopia' | 'achromatopsia';
 /**
  * Simulate how a color appears under a given color blindness type.
  * Returns a hex color string.
@@ -3961,6 +5065,13 @@ declare function simulateColorBlindness(color: string, type: ColorBlindnessType)
  */
 declare function checkPaletteDistinguishability(colors: string[], type: ColorBlindnessType, minDistance?: number): boolean;
 
+/**
+ * Check whether a color string parses to a fully opaque color.
+ * Contrast ratios are only meaningful against opaque backgrounds; the
+ * default chart background ('transparent') defers to the host page and
+ * can't be checked at compile time.
+ */
+declare function isOpaqueColor(color: string): boolean;
 /**
  * Compute the WCAG contrast ratio between two colors.
  * Returns a value between 1 (identical) and 21 (black on white).
@@ -4062,6 +5173,15 @@ interface DivergingPalette {
 }
 /** All diverging palettes keyed by name. */
 declare const DIVERGING_PALETTES: Record<string, string[]>;
+/**
+ * Resolve a scheme name to its palette stops. Accepts openchart palette names
+ * (blue, green, orange, purple, teal, redBlue, brownTeal, categorical) and
+ * common Vega-Lite aliases (blues, greens, ..., redblue, category10).
+ * Case-insensitive. Returns undefined for unknown names.
+ */
+declare function resolveSchemeName(name: string): string[] | undefined;
+/** Scheme names accepted by `scale: { scheme }`, for validation messages. */
+declare const SUPPORTED_SCHEME_NAMES: readonly string[];
 
 /**
  * Dark mode theme adaptation.
@@ -4175,6 +5295,23 @@ declare function resolveTheme(userTheme?: ThemeConfig, base?: Theme): ResolvedTh
  * chrome proportional to the container.
  */
 
+/**
+ * Line-height multiplier for the auto-thinning footnote list.
+ *
+ * Exported because the chrome renderer steps each footnote line down by it
+ * while the band height below is computed from it -- the two have to agree, or
+ * the last line drifts outside the band that was reserved for it.
+ */
+declare const FOOTNOTE_LINE_HEIGHT = 1.3;
+/**
+ * Vertical space a footnote list of `count` lines occupies below the plot.
+ *
+ * Single source of truth, deliberately: the engine reserves this band in the
+ * bottom margin, the chrome renderer shifts the source row down by it, and the
+ * brand watermark shifts by it too. When those three disagree the footnotes
+ * land on top of the watermark, which is exactly the bug this centralizes away.
+ */
+declare function footnoteBandHeight(count: number, theme: ResolvedTheme): number;
 /**
  * Compute resolved chrome layout from a Chrome spec and resolved theme.
  *
@@ -4369,10 +5506,13 @@ declare const X_AXIS_BAND_HEIGHT = 26;
 declare const X_AXIS_TITLE_BAND = 22;
 declare const X_AXIS_TITLE_BAND_ROTATED = 20;
 /**
- * Ceiling on the vertical extent reserved for rotated x tick labels. Labels
- * whose rotated projection exceeds this clip at the reservation edge, so the
- * angle ladder (engine layout/axes/rotation) avoids -90° for labels longer
- * than this.
+ * Ceiling on the vertical extent reserved for rotated x tick labels. The angle
+ * ladder (engine layout/axes/rotation) avoids -90° for labels longer than this.
+ *
+ * The cap bounds the RESERVATION, so a label whose rotated projection exceeds it
+ * must be truncated to fit — see `truncateRotatedLabel`. Reserving a capped band
+ * while drawing the full string is what let long ticks spill past the axis and
+ * collide with the source line.
  */
 declare const X_AXIS_ROTATED_EXTENT_CAP = 120;
 /**
@@ -4392,6 +5532,28 @@ interface XAxisExtentInput {
     measure?: (text: string, fontSize: number, fontWeight: number) => number;
 }
 declare function computeXAxisExtentFromLabels(input: XAxisExtentInput): number;
+/**
+ * The widest a rotated tick label may be before its vertical projection exceeds
+ * `X_AXIS_ROTATED_EXTENT_CAP`.
+ *
+ * Inverts the rotated-extent formula in `computeXAxisExtentFromLabels`:
+ *
+ *   extent = width*sin(θ) + lineHeight*cos(θ) + gap
+ *   width  = (cap - lineHeight*cos(θ) - gap) / sin(θ)
+ *
+ * Deriving it from the same terms (rather than hardcoding a second number) keeps
+ * the truncation budget and the space reservation locked together — if one
+ * changes, the other follows.
+ */
+declare function maxRotatedLabelWidth(tickAngle: number, tickFontSize: number): number;
+/**
+ * Truncate a rotated tick label with an ellipsis so it fits inside the capped
+ * reservation. Returns the label unchanged when it already fits.
+ *
+ * Binary-search on character count against the real measure function, so it
+ * respects proportional fonts rather than assuming a fixed character width.
+ */
+declare function truncateRotatedLabel(label: string, tickAngle: number, tickFontSize: number, tickFontWeight: number, measure?: (text: string, fontSize: number, fontWeight?: number) => number): string;
 
 /**
  * Label collision detection and resolution.
@@ -4491,23 +5653,42 @@ declare function computeLabelBounds(label: ResolvedLabel): Rect;
  * @param locale - Locale string (currently unused, reserved for i18n).
  */
 declare function formatNumber(value: number, _locale?: string): string;
+declare function abbreviateNumber(value: number): string;
 /**
- * Abbreviate a large number with a suffix.
- *
- * Examples:
- * - 1500000 -> "1.5M"
- * - 2300 -> "2.3K"
- * - 42 -> "42"
- * - 1000000000 -> "1B"
+ * Format a number as an English ordinal: 1 -> "1st", 2 -> "2nd", 3 -> "3rd",
+ * 11 -> "11th", 22 -> "22nd". Values are rounded to the nearest integer first;
+ * intended for rank axes where the domain is integer positions.
  */
-declare function abbreviateNumber(value: number): string;
+declare function formatOrdinal(value: number): string;
 /**
  * Build a number formatter from a d3-format string, with support for a
  * trailing literal suffix that d3-format itself would reject.
  *
+ * Also accepts the OpenChart extension `'ordinal'`, which renders English
+ * ordinals ("1st", "2nd", "3rd") for rank axes.
+ *
  * Returns null if the format string is falsy or unparseable.
  */
 declare function buildD3Formatter(formatStr: string | undefined): ((v: number) => string) | null;
+type NumberFormatter = (value: number) => string;
+declare function formatPercent(value: number, options?: {
+    fraction?: boolean;
+}): string;
+declare function formatCurrency(value: number, options?: {
+    compact?: boolean;
+}): string;
+interface FieldFormatContext {
+    extent?: [number, number];
+    allIntegers?: boolean;
+    surface?: 'chart' | 'table';
+    step?: number;
+    stepReference?: number;
+}
+declare function computeFieldFormatContext(values: Iterable<unknown>, surface?: 'chart' | 'table'): FieldFormatContext;
+declare function isYearContext(ctx: FieldFormatContext | undefined): boolean;
+declare function resolveNumberFormatter(formatStr: string | undefined, ctx?: FieldFormatContext): NumberFormatter | null;
+declare function defaultNumberFormatter(ctx?: FieldFormatContext): NumberFormatter;
+declare function buildCompactStepFormatter(step: number): NumberFormatter;
 /** Granularity levels for date formatting. */
 type DateGranularity = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute';
 /**
@@ -4673,12 +5854,12 @@ declare function columnChart(data: DataRow[], x: FieldRef, y: FieldRef, options?
 /**
  * Create a pie chart spec.
  *
- * Convention: category maps to the color channel, value maps to y.
+ * Convention: category maps to the color channel, value maps to theta.
  * Pie charts have no x-axis.
  *
  * @param data - Array of data rows.
  * @param category - Category field (color channel, nominal).
- * @param value - Value field (y channel, quantitative).
+ * @param value - Value field (theta channel, quantitative).
  * @param options - Optional chrome, annotations, theme, etc.
  *                  Note: color option is ignored since category is used for color.
  */
@@ -4695,12 +5876,12 @@ declare function areaChart(data: DataRow[], x: FieldRef, y: FieldRef, options?:
 /**
  * Create a donut chart spec.
  *
- * Convention: category maps to the color channel, value maps to y.
+ * Convention: category maps to the color channel, value maps to theta.
  * Donut charts have no x-axis.
  *
  * @param data - Array of data rows.
  * @param category - Category field (color channel, nominal).
- * @param value - Value field (y channel, quantitative).
+ * @param value - Value field (theta channel, quantitative).
  * @param options - Optional chrome, annotations, theme, etc.
  *                  Note: color option is ignored since category is used for color.
  */
@@ -4771,4 +5952,39 @@ interface TileMapBuilderOptions {
  */
 declare function tileMap(data: Record<string, number | string | null> | DataRow[], options?: TileMapBuilderOptions): TileMapSpec;
 
-export { type A11yMetadata, ACHROMATIC_RAMP, AXIS_TITLE_GAP, AXIS_TITLE_OFFSET_COMPACT, AXIS_TITLE_OFFSET_DEFAULT, AXIS_TITLE_TRAILING_PAD, type AggregateOp, type AggregateTransform, type AnimationConfig, type AnimationEase, type AnimationPhaseConfig, type AnimationSpec, type AnimationStagger, type Annotation, type AnnotationAnchor, type AnnotationFootnote, type AnnotationOffset, type AnnotationPosition, type ArcEncoding, type ArcMark, type AreaEncoding, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_FONT_SIZE, BRAND_MIN_WIDTH, BRAND_RESERVE_WIDTH, BREAKPOINT_COMPACT_MAX, BREAKPOINT_MEDIUM_MAX, type BarColumnConfig, type BarEncoding, type BarListEncoding, type BarListLayout, type BarListRowMark, type BarListSpec, type BarListSpecWithoutData, type BarTableCell, type BaseLegendLayout, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_PALETTE, CHART_ENCODING_RULES, CHART_TYPES, COMPACT_WIDTH, type CalculateExpression, type CalculateTransform, type CategoricalLegendLayout, type CategoricalPalette, type CategoryColorsConfig, type CategoryTableCell, type CellStyle, type ChannelRule, type ChartBuilderOptions, type ChartEventHandlers, type ChartLayout, type ChartSpec, type ChartSpecOverride, type ChartSpecWithoutData, type ChartType, type Chrome, type ChromeDefaults, type ChromeKey, type ChromeMode, type ChromeText, type ChromeTextStyle, type ChromeThemeOverride, type CircleEncoding, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type Condition, type ConditionalValueDef, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DateGranularity, type Display, type DivergingPalette, EXTENDED_OFFSET_STRATEGIES, type ElementEdit, type ElementRef, type Encoding, type EncodingChannel, type EncodingRule, type EndpointLabelEntry, type EndpointLabelsConfig, type EndpointLabelsLayout, type FacetChannel, type FacetLayout, type FacetPanelLayout, type FieldPredicate, type FieldRef, type FieldType, type FilterPredicate, type FilterTransform, type FlagTableCell, type FoldTransform, GRAPH_ENCODING_RULES, type GradientColorStop, type GradientDef, type GradientLegendLayout, type GradientStop, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, HEIGHT_CRAMPED_MAX, HEIGHT_SHORT_MAX, HPAD_COMPACT_FRACTION, HPAD_COMPACT_MIN, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type ImageColumnConfig, type ImageTableCell, LABEL_GAP_COMPACT, LABEL_GAP_DEFAULT, LABEL_GAP_NARROW_MAX, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LabelSpec, type LayerSpec, type LayoutStrategy, type LegendConfig, type LegendEntry, type LegendEntryPosition, type LegendLayout, type LegendPosition, type LineEncoding, type LineMark, type LinearGradient, type LogicalAnd, type LogicalNot, type LogicalOr, type LollipopEncoding, MARK_DISPLAY_NAMES, MARK_ENCODING_RULES, MARK_TYPES, MAX_LEFT_LABEL_FRACTION_COMPACT, MAX_LEFT_LABEL_FRACTION_DEFAULT, MAX_LEFT_LABEL_FRACTION_MEDIUM, MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type Metric, NARROW_VIEWPORT_MAX, type NodeOverride, OFFSET_STRATEGIES, type OffsetStrategy, type PaginationState, type Point, type PointEncoding, type PointMark, type RadialGradient, type RangeAnnotation, type Rect, type RectEncoding, type RectMark, type RefLineAnnotation, type RelativeTimeRef, type ResolveConfig, type ResolveMode, type ResolvedAnimation, type ResolvedAnimationPhase, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedLabel, type ResolvedMetricBar, type ResolvedMetricCell, type ResolvedTheme, type ResponsiveConfig, type RuleMarkLayout, SEQUENTIAL_PALETTES, type SankeyEncoding, type SankeyLayout, type SankeyLinkColor, type SankeyLinkMark, type SankeyNodeAlign, type SankeyNodeMark, type SankeySpec, type SankeySpecWithoutData, type ScaleConfig, type ScaleType, type SequentialPalette, type SeriesStrategy, type SeriesStyle, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type StoredVizSpec, TICK_LABEL_OFFSET, TICK_LINE_HEIGHT_FACTOR, TOP_PAD_EXTRA_NARROW, TOP_PAD_NARROW_MAX, type TableBuilderOptions, type TableCell, type TableCellBase, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TextAnnotation, type TextEncoding, type TextMarkLayout, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeSpacing, type TickEncoding, type TickMarkLayout, type TileMapBuilderOptions, type TileMapEncoding, type TileMapLayout, type TileMapPalette, type TileMapSpec, type TileMapSpecWithoutData, type TileMapTileMark, type TimeUnit, type TimeUnitTransform, type TokenValue, type TooltipContent, type TooltipField, type Transform, type VizSpec, type WindowFieldDef, type WindowOp, type WindowSortField, type WindowTransform, type XAxisExtentInput, X_AXIS_BAND_HEIGHT, X_AXIS_ROTATED_EXTENT_CAP, X_AXIS_TITLE_BAND, X_AXIS_TITLE_BAND_ROTATED, abbreviateNumber, adaptColorForDarkMode, adaptForLightLineStroke, adaptTheme, areaChart, axisTitleOffset, barChart, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, columnChart, computeChrome, computeLabelBounds, computeXAxisExtentFromLabels, contrastRatio, dataTable, detectCollision, donutChart, dotChart, editorial, elementRef, essay, estimateTextWidth, findAccessibleColor, formatDate, formatNumber, generateAltText, generateAriaLabels, generateDataTable, getAxisTitleOffset, getBreakpoint, getHeightClass, getLayoutStrategy, getRepresentativeColor, heuristicMeasure, inferFieldType, isBarListSpec, isChartSpec, isConditionalDef, isEncodingChannel, isGradientDef, isGraphSpec, isLayerSpec, isRangeAnnotation, isRefLineAnnotation, isSankeySpec, isTableSpec, isTextAnnotation, isTileMapSpec, lineChart, meetsAA, overlapArea, pickLabelColor, pieChart, resolveCollisions, resolveMarkDef, resolveMarkType, resolveMeasurer, resolveTheme, scatterChart, simulateColorBlindness, textAscent, tileMap, wire, wrapText };
+/**
+ * Deep merge for applying partial patches onto a spec-shaped object.
+ *
+ * Used by the scrollytelling story layer (`vanilla/story`) to apply
+ * cumulative deep-partial spec patches onto a base spec. Arrays REPLACE
+ * rather than merge element-by-element: predictable behavior for things
+ * like `annotations` or `data`, where index-wise merging would silently
+ * produce nonsense. Plain objects merge key-by-key, recursively.
+ */
+declare function deepMergeSpec(target: any, source: any): any;
+
+interface CssTokenDef {
+    name: string;
+    light: string;
+    dark?: string;
+    comment?: string;
+    consumers?: string;
+    section?: string;
+}
+declare const CSS_TOKEN_ROOT_SELECTORS: readonly string[];
+/**
+ * Text levels. Names invert across modes: in light mode "muted" sits at
+ * a lighter zinc step than "subtle" because both are picked relative to
+ * the active background, not from a fixed lightness ladder. The intent
+ * is "muted = first step away from primary text"; "subtle = next step
+ * down"; etc.
+ *
+ *   Light mode: text=zinc-950, secondary=zinc-700, muted=zinc-500,
+ *               subtle=zinc-400, faint=zinc-300
+ *   Dark mode (dark.css): inverts the surface tokens but keeps the same
+ *               muted -> subtle -> faint progression away from primary.
+ */
+declare const CSS_TOKENS: readonly CssTokenDef[];
+declare function cssTokenDefault(name: string, mode: 'light' | 'dark'): string;
+
+export { type A11yConfig, type A11yMetadata, ACHROMATIC_RAMP, AXIS_TITLE_GAP, AXIS_TITLE_OFFSET_COMPACT, AXIS_TITLE_OFFSET_DEFAULT, AXIS_TITLE_TRAILING_PAD, type AggregateOp, type AggregateTransform, type AnimationConfig, type AnimationEase, type AnimationPhaseConfig, type AnimationSpec, type AnimationStagger, type Annotation, type AnnotationAnchor, type AnnotationFootnote, type AnnotationOffset, type AnnotationPosition, type ArcEncoding, type ArcMark, type AreaEncoding, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_FONT_SIZE, BRAND_MIN_WIDTH, BRAND_RESERVE_WIDTH, BREAKPOINT_COMPACT_MAX, BREAKPOINT_MEDIUM_MAX, type BarColumnConfig, type BarEncoding, type BarListEncoding, type BarListLayout, type BarListRowMark, type BarListSpec, type BarListSpecWithoutData, type BarTableCell, type BaseLegendLayout, type BeeswarmEncoding, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_PALETTE, COMPACT_WIDTH, CSS_TOKENS, CSS_TOKEN_ROOT_SELECTORS, type CalculateExpression, type CalculateTransform, type CalendarEncoding, type CategoricalLegendLayout, type CategoricalPalette, type CategoryColorsConfig, type CategoryTableCell, type CellStyle, type ChannelRule, type ChartBuilderOptions, type ChartEventHandlers, type ChartLayout, type ChartSpec, type ChartSpecOverride, type ChartSpecWithoutData, type Chrome, type ChromeDefaults, type ChromeKey, type ChromeMode, type ChromeText, type ChromeTextStyle, type ChromeThemeOverride, type CircleEncoding, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type CompileWarning, type Condition, type ConditionalValueDef, type ConnectorConfig, type ConnectorType, type ContinuousLegendBin, type ContinuousLegendLayout, type ContinuousLegendTick, type CssTokenDef, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DateGranularity, type Display, type DivergingPalette, EXTENDED_OFFSET_STRATEGIES, type ElementEdit, type ElementRef, type Encoding, type EncodingChannel, type EncodingRule, type EndpointLabelContent, type EndpointLabelEntry, type EndpointLabelsConfig, type EndpointLabelsLayout, FOOTNOTE_LINE_HEIGHT, type FacetChannel, type FacetLayout, type FacetPanelLayout, type FieldFormatContext, type FieldPredicate, type FieldRef, type FieldType, type FillPatternType, type FilterPredicate, type FilterTransform, type FlagTableCell, type FoldTransform, GRAPH_ENCODING_RULES, type GradientColorStop, type GradientDef, type GradientLegendLayout, type GradientStop, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, HEIGHT_CRAMPED_MAX, HEIGHT_SHORT_MAX, HPAD_COMPACT_FRACTION, HPAD_COMPACT_MIN, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type ImageColumnConfig, type ImageTableCell, LABEL_GAP_COMPACT, LABEL_GAP_DEFAULT, LABEL_GAP_NARROW_MAX, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LabelSpec, type LayerSpec, type LayoutStrategy, type LegendChannel, type LegendConfig, type LegendEntry, type LegendEntryPosition, type LegendLayout, type LegendPosition, type LineEncoding, type LineMark, type LinearGradient, type LogicalAnd, type LogicalNot, type LogicalOr, type LollipopEncoding, MARK_DISPLAY_NAMES, MARK_ENCODING_RULES, MARK_TYPES, MAX_LEFT_LABEL_FRACTION_COMPACT, MAX_LEFT_LABEL_FRACTION_DEFAULT, MAX_LEFT_LABEL_FRACTION_MEDIUM, MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX, type MapBorders, type MapEncoding, type MapFeatureMark, type MapFocus, type MapFocusLayout, type MapGeo, type MapLayout, type MapPointMark, type MapPointsLayer, type MapProjection, type MapSpec, type MapSpecWithoutData, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type Metric, NARROW_VIEWPORT_MAX, type NodeOverride, type NumberFormatter, OFFSET_STRATEGIES, type OffsetStrategy, type PaginationState, type ParliamentEncoding, type Point, type PointEncoding, type PointMark, type RadialGradient, type RangeAnnotation, type RangeEncoding, type Rect, type RectEncoding, type RectMark, type RefLineAnnotation, type RelativeTimeRef, type ResolveConfig, type ResolveMode, type ResolvedAnimation, type ResolvedAnimationPhase, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedFillPattern, type ResolvedLabel, type ResolvedMetricBar, type ResolvedMetricCell, type ResolvedSeriesSearch, type ResolvedTheme, type ResolvedYouDrawIt, type ResponsiveConfig, type RuleMarkLayout, SEQUENTIAL_PALETTES, SUPPORTED_SCHEME_NAMES, type SankeyEncoding, type SankeyLayout, type SankeyLinkColor, type SankeyLinkMark, type SankeyNodeAlign, type SankeyNodeMark, type SankeySpec, type SankeySpecWithoutData, type ScaleConfig, type ScaleInvert, type ScaleType, type SequentialPalette, type SeriesSearchConfig, type SeriesStrategy, type SeriesStyle, type SizeLegendCircle, type SizeLegendLayout, type SortByField, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type StoredVizSpec, TICK_LABEL_OFFSET, TICK_LINE_HEIGHT_FACTOR, TOP_PAD_EXTRA_NARROW, TOP_PAD_NARROW_MAX, type TableBuilderOptions, type TableCell, type TableCellBase, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TextAnnotation, type TextEncoding, type TextMarkLayout, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeSpacing, type TickEncoding, type TickMarkLayout, type TileMapBuilderOptions, type TileMapEncoding, type TileMapLayout, type TileMapPalette, type TileMapSpec, type TileMapSpecWithoutData, type TileMapTileMark, type TimeUnit, type TimeUnitTransform, type TokenValue, type TooltipContent, type TooltipField, type Transform, type ValueDef, type VizSpec, type WaffleEncoding, type WindowFieldDef, type WindowOp, type WindowSortField, type WindowTransform, type XAxisExtentInput, X_AXIS_BAND_HEIGHT, X_AXIS_ROTATED_EXTENT_CAP, X_AXIS_TITLE_BAND, X_AXIS_TITLE_BAND_ROTATED, type YouDrawItConfig, type YouDrawItSample, type YouDrawItYInvert, abbreviateNumber, adaptColorForDarkMode, adaptForLightLineStroke, adaptTheme, areaChart, axisTitleOffset, barChart, buildCompactStepFormatter, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, columnChart, computeChrome, computeFieldFormatContext, computeLabelBounds, computeXAxisExtentFromLabels, contrastRatio, cssTokenDefault, dataTable, deepMergeSpec, defaultNumberFormatter, detectCollision, donutChart, dotChart, editorial, elementRef, essay, estimateTextWidth, findAccessibleColor, footnoteBandHeight, formatCurrency, formatDate, formatNumber, formatOrdinal, formatPercent, generateAltText, generateAriaLabels, generateDataTable, getAxisTitleOffset, getBreakpoint, getHeightClass, getLayoutStrategy, getRepresentativeColor, heuristicMeasure, inferFieldType, isAxislessMark, isBarListSpec, isChartSpec, isConditionalDef, isEncodingChannel, isGradientDef, isGraphSpec, isLayerSpec, isMapSpec, isOpaqueColor, isRangeAnnotation, isRefLineAnnotation, isSankeySpec, isTableSpec, isTextAnnotation, isTileMapSpec, isValueDef, isYearContext, lineChart, maxRotatedLabelWidth, meetsAA, overlapArea, pickLabelColor, pieChart, resolveCollisions, resolveMarkDef, resolveMarkType, resolveMeasurer, resolveNumberFormatter, resolveSchemeName, resolveTheme, scatterChart, simulateColorBlindness, textAscent, tileMap, truncateRotatedLabel, wire, wrapText };