@opendata-ai/openchart-core 3.0.0 → 6.1.0

package/dist/index.d.ts

@@ -157,20 +157,82 @@ interface ColumnConfig {
  * These types define what a user (or Claude) writes to describe a visualization.
  * The engine validates, normalizes, and compiles specs into layout objects.
  *
- * Encoding vocabulary follows Vega-Lite conventions (field/type/aggregate)
+ * Encoding vocabulary follows Vega-Lite conventions (field/type/aggregate/mark)
  * with editorial extensions for chrome, annotations, responsive, and dark mode.
  */
 
-/** Supported chart types. Graph is separate since it uses nodes/edges, not data + encoding. */
-type ChartType = 'line' | 'area' | 'bar' | 'column' | 'pie' | 'donut' | 'dot' | 'scatter';
+/**
+ * Supported mark types, following Vega-Lite conventions.
+ *
+ * Mapping from previous OpenChart chart types:
+ * - 'bar' covers both horizontal bars (old 'bar') and vertical columns (old 'column')
+ * - 'arc' covers both pie (old 'pie') and donut (old 'donut')
+ * - 'point' replaces old 'scatter'
+ * - 'circle' replaces old 'dot'
+ * - 'line' and 'area' unchanged
+ *
+ * New mark types not in previous OpenChart:
+ * - 'text': data-positioned text labels
+ * - 'rule': reference lines as data marks
+ * - 'tick': strip/rug plot marks
+ * - 'rect': heatmaps and 2D binned plots
+ */
+type MarkType = 'bar' | 'line' | 'area' | 'point' | 'circle' | 'arc' | 'text' | 'rule' | 'tick' | 'rect';
+/** @deprecated Use MarkType instead. Kept for internal migration references. */
+type ChartType = MarkType;
+/**
+ * Mark definition object with visual properties.
+ *
+ * When `mark` is a string, it's shorthand for `{ type: markString }`.
+ * When it's an object, it can include properties like interpolation,
+ * point markers, orientation, and more.
+ */
+interface MarkDef {
+    /** The mark type. */
+    type: MarkType;
+    /**
+     * Show point markers on line/area marks.
+     * - true: filled circles at each data point
+     * - 'transparent': invisible hover targets (legacy behavior)
+     * - false: no point marks (default; uses voronoi overlay for tooltips)
+     */
+    point?: boolean | 'transparent';
+    /**
+     * Curve interpolation for line/area marks.
+     * Maps to d3-shape curve factories.
+     */
+    interpolate?: 'linear' | 'monotone' | 'step' | 'step-before' | 'step-after' | 'basis' | 'cardinal' | 'natural';
+    /** Explicit orientation override for bar marks. */
+    orient?: 'horizontal' | 'vertical';
+    /** Inner radius for arc marks. >0 produces a donut, 0 or omitted produces a pie. */
+    innerRadius?: number;
+    /** Outer radius for arc marks. */
+    outerRadius?: number;
+    /** Corner radius for rect/bar marks. */
+    cornerRadius?: number;
+    /** Whether the mark is filled (vs stroked only). */
+    filled?: boolean;
+    /** Default opacity (0-1). */
+    opacity?: number;
+    /** Default fill color. */
+    fill?: string;
+    /** Default stroke color. */
+    stroke?: string;
+    /** Default stroke width. */
+    strokeWidth?: number;
+    /** Tooltip behavior. null disables tooltips. */
+    tooltip?: boolean | null;
+    /** Clip marks to the chart area. */
+    clip?: boolean;
+}
 /** Data field type, following Vega-Lite conventions. */
 type FieldType = 'quantitative' | 'temporal' | 'nominal' | 'ordinal';
 /** Aggregate function applied to a field before encoding. */
 type AggregateOp = 'count' | 'sum' | 'mean' | 'median' | 'min' | 'max';
 /** Axis configuration for an encoding channel. */
 interface AxisConfig {
-    /** Axis label text. If omitted, the field name is used. */
-    label?: string;
+    /** Axis title text. If omitted, the field name is used. */
+    title?: string;
     /** Number format string (d3-format). e.g. ",.0f" for comma-separated integers. */
     format?: string;
     /** Override tick count. Engine picks a sensible default if omitted. */
@@ -178,6 +240,28 @@ interface AxisConfig {
     /** Whether to show gridlines for this axis. */
     grid?: boolean;
     /** Rotation angle in degrees for tick labels. Common values: -45, -90, 90. */
+    labelAngle?: number;
+    /** Axis orientation override. */
+    orient?: 'top' | 'bottom' | 'left' | 'right';
+    /** Explicit tick values. */
+    values?: unknown[];
+    /** How to handle overlapping labels. */
+    labelOverlap?: boolean | 'parity' | 'greedy';
+    /** Whether to flush labels to the axis edges. */
+    labelFlush?: boolean;
+    /** Whether to show the axis domain line. */
+    domain?: boolean;
+    /** Whether to show tick marks. */
+    ticks?: boolean;
+    /** Axis position offset in pixels. */
+    offset?: number;
+    /** Padding between axis title and axis. */
+    titlePadding?: number;
+    /** Padding between tick labels and axis. */
+    labelPadding?: number;
+    /** @deprecated Use `title` instead. */
+    label?: string;
+    /** @deprecated Use `labelAngle` instead. */
     tickAngle?: number;
 }
 /** Scale configuration for an encoding channel. */
@@ -185,14 +269,34 @@ interface ScaleConfig {
     /** Explicit domain override. Auto-derived from data if omitted. */
     domain?: [number, number] | string[];
     /** Scale type override. Usually inferred from field type. */
-    type?: 'linear' | 'log' | 'time' | 'band' | 'point' | 'ordinal';
+    type?: ScaleType;
     /** Whether to nice-ify the domain for clean tick values. Defaults to true. */
     nice?: boolean;
     /** Whether the domain should include zero. Defaults to true for quantitative. */
     zero?: boolean;
     /** When true and domain is set, filter out data rows with values outside the domain range. */
     clip?: boolean;
-}
+    /** Explicit range override. */
+    range?: unknown[];
+    /** Reverse the range direction. */
+    reverse?: boolean;
+    /** Clamp output to the range. */
+    clamp?: boolean;
+    /** Padding for band/point scales. */
+    padding?: number;
+    /** Inner padding for band scales. */
+    paddingInner?: number;
+    /** Outer padding for band scales. */
+    paddingOuter?: number;
+    /** Exponent for pow scales. */
+    exponent?: number;
+    /** Base for log scales (default 10). */
+    base?: number;
+    /** Constant for symlog scales. */
+    constant?: number;
+}
+/** Scale type, following Vega-Lite conventions. */
+type ScaleType = 'linear' | 'log' | 'pow' | 'sqrt' | 'symlog' | 'time' | 'utc' | 'ordinal' | 'band' | 'point' | 'quantile' | 'quantize' | 'threshold';
 /**
  * A single encoding channel mapping a data field to a visual property.
  *
@@ -220,20 +324,44 @@ interface EncodingChannel {
 }
 /**
  * Encoding object mapping visual channels to data fields.
- * Which channels are required depends on the chart type.
- * See ChartEncodingRules in encoding.ts for per-type requirements.
+ * Which channels are required depends on the mark type.
+ * See MARK_ENCODING_RULES in encoding.ts for per-type requirements.
  */
 interface Encoding {
     /** Horizontal position channel. */
     x?: EncodingChannel;
     /** Vertical position channel. */
     y?: EncodingChannel;
-    /** Color channel (series differentiation or heatmap). */
-    color?: EncodingChannel;
-    /** Size channel (bubble charts, dot plots). */
-    size?: EncodingChannel;
+    /** Color channel (series differentiation or heatmap). Accepts conditional definitions. */
+    color?: EncodingChannel | ConditionalValueDef;
+    /** Size channel (bubble charts, dot plots). Accepts conditional definitions. */
+    size?: EncodingChannel | ConditionalValueDef;
     /** Detail channel (group without encoding to a visual property). */
     detail?: EncodingChannel;
+    /** Secondary x position (for ranges, error bars). */
+    x2?: EncodingChannel;
+    /** Secondary y position (for ranges, error bars). */
+    y2?: EncodingChannel;
+    /** Data-driven opacity (0-1). Accepts conditional definitions. */
+    opacity?: EncodingChannel | ConditionalValueDef;
+    /** Point shape encoding (circle, square, diamond, triangle-up, etc.). */
+    shape?: EncodingChannel;
+    /** Data-driven stroke dash patterns. */
+    strokeDash?: EncodingChannel;
+    /** Rotation angle encoding. */
+    angle?: EncodingChannel;
+    /** Text content for text marks. */
+    text?: EncodingChannel;
+    /** Tooltip field(s). Can be a single channel or array. */
+    tooltip?: EncodingChannel | EncodingChannel[];
+    /** Hyperlink encoding. */
+    href?: EncodingChannel;
+    /** Stacking/drawing order. */
+    order?: EncodingChannel;
+    /** Angular position for arc marks. */
+    theta?: EncodingChannel;
+    /** Radial position for arc marks. */
+    radius?: EncodingChannel;
 }
 /** Encoding channel for graph nodes and edges. Same structure as EncodingChannel. */
 interface GraphEncodingChannel {
@@ -522,15 +650,21 @@ interface ChartSpecOverride {
 /**
  * Chart specification: the primary input for standard chart types.
  *
- * Combines a chart type with data, encoding channels, editorial chrome,
- * annotations, and configuration. The engine validates, normalizes, and
- * compiles this into a ChartLayout.
+ * Uses the Vega-Lite `mark` property instead of `type` to specify
+ * the visualization mark. The mark can be a string shorthand or an
+ * object with additional properties (interpolation, point markers, etc.).
  */
 interface ChartSpec {
-    /** The chart type to render. */
-    type: ChartType;
+    /**
+     * The mark type to render.
+     * String shorthand: `mark: 'bar'`
+     * Object with properties: `mark: { type: 'line', interpolate: 'step' }`
+     */
+    mark: MarkType | MarkDef;
     /** Data array: each element is a row with field values. */
     data: DataRow[];
+    /** Data transforms applied in order before encoding (filter, bin, calculate, timeUnit). */
+    transform?: Transform[];
     /** Encoding mapping data fields to visual channels. */
     encoding: Encoding;
     /** Editorial chrome (title, subtitle, source, etc.). */
@@ -608,13 +742,6 @@ interface GraphEdge {
     /** Arbitrary data fields (weight, type, confidence, etc.). */
     [key: string]: unknown;
 }
-/**
- * Graph specification: input for network/relationship visualizations.
- *
- * Uses a nodes + edges data model instead of the flat data + encoding model
- * used by chart types. The graph type is defined here for forward compatibility
- * but rendering is deferred to a future phase.
- */
 /** Per-node visual overrides, keyed by node id. */
 interface NodeOverride {
     /** Override fill color. */
@@ -651,12 +778,64 @@ interface GraphSpec {
     darkMode?: DarkMode;
 }
 /**
- * Top-level visualization spec: discriminated union on the `type` field.
+ * Resolution strategy for shared resources across layers.
+ * 'shared' (default): union domains, single axis/legend.
+ * 'independent': each layer gets its own scale/axis/legend.
+ */
+type ResolveMode = 'shared' | 'independent';
+/**
+ * Per-channel resolution config. Controls whether scales, axes, and legends
+ * are shared or independent across layers.
+ */
+interface ResolveConfig {
+    scale?: Partial<Record<'x' | 'y' | 'color' | 'size', ResolveMode>>;
+    axis?: Partial<Record<'x' | 'y', ResolveMode>>;
+    legend?: Partial<Record<'color' | 'size', ResolveMode>>;
+}
+/**
+ * Layer specification: composites multiple chart layers into a single view.
  *
- * This is the primary API contract. Users (and Claude) write VizSpec objects,
- * the engine validates and compiles them into layout objects for rendering.
+ * Each element in `layer` is either a ChartSpec or another LayerSpec (nested).
+ * Shared data, encoding, and transforms at the LayerSpec level are inherited
+ * by children that don't define their own.
  */
-type VizSpec = ChartSpec | TableSpec | GraphSpec;
+interface LayerSpec {
+    /** Array of child layers (ChartSpec or nested LayerSpec). */
+    layer: (ChartSpec | LayerSpec)[];
+    /** Shared data inherited by children without their own data. */
+    data?: DataRow[];
+    /** Shared encoding inherited by children (overridden per-channel by child). */
+    encoding?: Encoding;
+    /** Shared transforms. Parent transforms run before child transforms. */
+    transform?: Transform[];
+    /** Editorial chrome (title, subtitle, source, etc.). */
+    chrome?: Chrome;
+    /** Annotations on the layered view. */
+    annotations?: Annotation[];
+    /** Label display configuration. */
+    labels?: LabelConfig;
+    /** Legend display configuration. */
+    legend?: LegendConfig;
+    /** Whether the chart adapts to container width. Defaults to true. */
+    responsive?: boolean;
+    /** Theme configuration overrides. */
+    theme?: ThemeConfig;
+    /** Dark mode behavior. Defaults to "off". */
+    darkMode?: DarkMode;
+    /** Resolution strategy for shared scales/axes/legends. */
+    resolve?: ResolveConfig;
+    /** Hidden series names. */
+    hiddenSeries?: string[];
+}
+/**
+ * Top-level visualization spec: union discriminated by structural shape.
+ *
+ * - ChartSpec: has `mark` field (no `type`, no `layer`)
+ * - LayerSpec: has `layer` field
+ * - TableSpec: has `type: 'table'`
+ * - GraphSpec: has `type: 'graph'`
+ */
+type VizSpec = ChartSpec | LayerSpec | TableSpec | GraphSpec;
 /** Chart spec without runtime data, for persistence/storage. */
 type ChartSpecWithoutData = Omit<ChartSpec, 'data'>;
 /** Table spec without runtime data and columns, for persistence/storage. Columns can be auto-generated via dataTable(). */
@@ -665,25 +844,160 @@ type TableSpecWithoutData = Omit<TableSpec, 'data' | 'columns'>;
 type GraphSpecWithoutData = Omit<GraphSpec, 'nodes' | 'edges'>;
 /** Union of data-stripped spec types for persistence/storage. */
 type StoredVizSpec = ChartSpecWithoutData | TableSpecWithoutData | GraphSpecWithoutData;
-/** All valid chart type strings for runtime checking. */
+/** Logical AND combinator for filter predicates. */
+interface LogicalAnd<T> {
+    and: T[];
+}
+/** Logical OR combinator for filter predicates. */
+interface LogicalOr<T> {
+    or: T[];
+}
+/** Logical NOT combinator for filter predicates. */
+interface LogicalNot<T> {
+    not: T;
+}
+/** A predicate that tests a field value against a condition. */
+interface FieldPredicate {
+    /** Data field to test. */
+    field: string;
+    /** Equals comparison. */
+    equal?: unknown;
+    /** Less than. */
+    lt?: number;
+    /** Less than or equal. */
+    lte?: number;
+    /** Greater than. */
+    gt?: number;
+    /** Greater than or equal. */
+    gte?: number;
+    /** Inclusive range [min, max]. */
+    range?: [number, number];
+    /** Value is one of these. */
+    oneOf?: unknown[];
+    /** Whether the value is valid (non-null, non-undefined, non-NaN). */
+    valid?: boolean;
+}
+/**
+ * A filter predicate: a field predicate or logical combination of predicates.
+ */
+type FilterPredicate = FieldPredicate | LogicalAnd<FilterPredicate> | LogicalOr<FilterPredicate> | LogicalNot<FilterPredicate>;
+/** Parameters for binning a field. */
+interface BinParams {
+    /** Maximum number of bins. */
+    maxbins?: number;
+    /** Exact step size between bins. */
+    step?: number;
+    /** Whether to nice-ify bin boundaries. */
+    nice?: boolean;
+    /** Explicit extent [min, max] for binning. */
+    extent?: [number, number];
+}
+/** Expression for calculate transforms. */
+interface CalculateExpression {
+    /** Arithmetic operation to apply. */
+    op: '+' | '-' | '*' | '/' | 'abs' | 'round' | 'floor' | 'ceil' | 'log' | 'sqrt';
+    /** Primary field to operate on. */
+    field: string;
+    /** Secondary field for binary operations (+, -, *, /). */
+    field2?: string;
+    /** Constant value for binary operations when field2 is not provided. */
+    value?: number;
+}
+/**
+ * Time unit granularity for temporal field transformations.
+ * Follows Vega-Lite conventions.
+ */
+type TimeUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'dayofyear' | 'date' | 'hours' | 'minutes' | 'seconds' | 'milliseconds' | 'yearmonth' | 'yearmonthdate' | 'monthdate' | 'hoursminutes';
+/** Filter transform: removes rows that don't match the predicate. */
+interface FilterTransform {
+    filter: FilterPredicate;
+}
+/** Bin transform: adds binned field(s) to each row. */
+interface BinTransform {
+    bin: true | BinParams;
+    field: string;
+    as: string | [string, string];
+}
+/** Calculate transform: adds a computed field to each row. */
+interface CalculateTransform {
+    calculate: CalculateExpression;
+    as: string;
+}
+/** Time unit transform: extracts a time unit from a temporal field. */
+interface TimeUnitTransform {
+    timeUnit: TimeUnit;
+    field: string;
+    as: string;
+}
+/** Discriminated union of all transform types. */
+type Transform = FilterTransform | BinTransform | CalculateTransform | TimeUnitTransform;
+/**
+ * A single condition with a test predicate and resulting value/field.
+ * When the test passes for a datum, the condition's value/field is used.
+ */
+interface Condition {
+    /** Predicate to test against each datum. */
+    test: FilterPredicate;
+    /** Static value to use when the condition is true. */
+    value?: unknown;
+    /** Data field to use when the condition is true. */
+    field?: string;
+    /** Field type for the conditional field. */
+    type?: FieldType;
+}
+/**
+ * A conditional value definition for an encoding channel.
+ * Evaluates conditions in order, falling back to the default value.
+ */
+interface ConditionalValueDef {
+    /** One or more conditions to evaluate. */
+    condition: Condition | Condition[];
+    /** Default value when no condition matches. */
+    value?: unknown;
+}
+/**
+ * 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).
+ */
+declare function isEncodingChannel(def: EncodingChannel | ConditionalValueDef | undefined): def is EncodingChannel;
+/**
+ * Check if a channel definition is a ConditionalValueDef.
+ */
+declare function isConditionalDef(def: EncodingChannel | ConditionalValueDef | undefined): def is ConditionalValueDef;
+/** 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>;
-/** Check if a spec is a ChartSpec (any standard chart type). */
-declare function isChartSpec(spec: VizSpec): spec is ChartSpec;
+/**
+ * Extract the mark type string from a mark field (string or MarkDef).
+ */
+declare function resolveMarkType(mark: MarkType | MarkDef): MarkType;
+/**
+ * Extract the full MarkDef from a mark field, filling in defaults for string shorthand.
+ */
+declare function resolveMarkDef(mark: MarkType | MarkDef): MarkDef;
+/** Check if a spec is a ChartSpec (has `mark` field, not a layer/table/graph). */
+declare function isChartSpec(spec: VizSpec | Record<string, unknown>): spec is ChartSpec;
+/** Check if a spec is a LayerSpec (has `layer` array). */
+declare function isLayerSpec(spec: VizSpec | Record<string, unknown>): spec is LayerSpec;
 /** Check if a spec is a TableSpec. */
-declare function isTableSpec(spec: VizSpec): spec is TableSpec;
+declare function isTableSpec(spec: VizSpec | Record<string, unknown>): spec is TableSpec;
 /** Check if a spec is a GraphSpec. */
-declare function isGraphSpec(spec: VizSpec): spec is GraphSpec;
+declare function isGraphSpec(spec: VizSpec | Record<string, unknown>): spec is GraphSpec;
 /** 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. */
 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>;
 
 /**
- * Per-chart-type encoding validation rules.
+ * Per-mark-type encoding validation rules.
  *
- * Defines which encoding channels are required vs optional for each chart type.
+ * Defines which encoding channels are required vs optional for each mark type.
  * The engine compiler uses these rules to validate specs at runtime (TypeScript
  * catches compile-time errors; these catch runtime JSON from Claude or APIs).
  */
@@ -699,25 +1013,41 @@ interface ChannelRule {
 interface EncodingRule {
     x: ChannelRule;
     y: ChannelRule;
+    x2?: ChannelRule;
+    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;
 }
 /**
- * Encoding rules per chart type.
+ * Encoding rules per mark type.
  *
  * Defines which channels are required and what field types they accept.
  * The compiler uses this map to validate user specs at runtime.
  *
  * Key design decisions:
  * - line/area: x is temporal/ordinal (the axis), y is quantitative (the value)
- * - bar: horizontal bars, so y is the category axis, x is the value
- * - column: vertical columns, so x is the category axis, y is the value
- * - pie/donut: no x axis; y is the value (quantitative), color is the category
- * - dot: y is the category, x is quantitative
- * - scatter: both axes are quantitative
- */
-declare const CHART_ENCODING_RULES: Record<ChartType, EncodingRule>;
+ * - bar: covers both horizontal and vertical orientations, so both axes accept
+ *   all relevant types. The engine validates the combination later (one axis
+ *   must be quantitative).
+ * - arc: no x axis; y is the value (quantitative), color is the category
+ * - circle: y is the category, x is quantitative
+ * - point: both axes are quantitative
+ * - text/rule: fully optional positioning
+ * - tick/rect: both axes required, any type
+ */
+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. */
@@ -1070,6 +1400,22 @@ interface AxisLayout {
     start: Point;
     /** Axis line end position. */
     end: Point;
+    /** Axis orientation (which side it appears on). */
+    orient?: 'top' | 'bottom' | 'left' | 'right';
+    /** Whether to show the axis domain line. Defaults to true. */
+    domainLine?: boolean;
+    /** Whether to show tick marks. Defaults to true. */
+    tickMarks?: boolean;
+    /** Axis position offset in pixels. */
+    offset?: number;
+    /** Padding between axis title and axis in pixels. */
+    titlePadding?: number;
+    /** Padding between tick labels and axis in pixels. */
+    labelPadding?: number;
+    /** How overlapping labels should be handled. */
+    labelOverlap?: boolean | 'parity' | 'greedy';
+    /** Whether to flush labels to the axis edges. */
+    labelFlush?: boolean;
 }
 /** Accessibility attributes for a mark. */
 interface MarkAria {
@@ -1103,6 +1449,16 @@ interface LineMark {
     seriesKey?: string;
     /** Original data rows for this series. */
     data: Record<string, unknown>[];
+    /**
+     * Pixel-coordinate data points for spatial tooltip lookup (voronoi overlay).
+     * Each entry pairs a pixel position with its original data row.
+     */
+    dataPoints?: Array<{
+        x: number;
+        y: number;
+        datum: Record<string, unknown>;
+        tooltip?: TooltipContent;
+    }>;
     /** Resolved label after collision detection. */
     label?: ResolvedLabel;
     /** Accessibility attributes. */
@@ -1134,6 +1490,16 @@ interface AreaMark {
     seriesKey?: string;
     /** Original data rows. */
     data: Record<string, unknown>[];
+    /**
+     * Pixel-coordinate data points for spatial tooltip lookup (voronoi overlay).
+     * Each entry pairs a pixel position with its original data row.
+     */
+    dataPoints?: Array<{
+        x: number;
+        y: number;
+        datum: Record<string, unknown>;
+        tooltip?: TooltipContent;
+    }>;
     /** Accessibility attributes. */
     aria: MarkAria;
 }
@@ -1226,8 +1592,91 @@ interface PointMark {
     /** Accessibility attributes. */
     aria: MarkAria;
 }
+/**
+ * Text mark: data-positioned text label.
+ * Used by text charts for showing values directly at data coordinates.
+ */
+interface TextMarkLayout {
+    type: 'textMark';
+    /** X position. */
+    x: number;
+    /** Y position. */
+    y: number;
+    /** Text content to display. */
+    text: string;
+    /** Fill color. */
+    fill: string;
+    /** Font size in pixels. */
+    fontSize: number;
+    /** Font weight. */
+    fontWeight?: number;
+    /** Font family override. */
+    fontFamily?: string;
+    /** Horizontal text alignment. */
+    textAnchor: 'start' | 'middle' | 'end';
+    /** Rotation angle in degrees. */
+    angle?: number;
+    /** Original data row. */
+    data: Record<string, unknown>;
+    /** Resolved label. */
+    label?: ResolvedLabel;
+    /** Accessibility attributes. */
+    aria: MarkAria;
+}
+/**
+ * Rule mark: a line segment between two points.
+ * Used for reference lines rendered as data marks.
+ */
+interface RuleMarkLayout {
+    type: 'rule';
+    /** Start x position. */
+    x1: number;
+    /** Start y position. */
+    y1: number;
+    /** End x position. */
+    x2: number;
+    /** End y position. */
+    y2: number;
+    /** Stroke color. */
+    stroke: string;
+    /** Stroke width in pixels. */
+    strokeWidth: number;
+    /** Stroke dash pattern (e.g. "4 2"). */
+    strokeDasharray?: string;
+    /** Opacity (0-1). */
+    opacity?: number;
+    /** Original data row. */
+    data: Record<string, unknown>;
+    /** Accessibility attributes. */
+    aria: MarkAria;
+}
+/**
+ * Tick mark: a short line segment at a data coordinate.
+ * Used for strip plots and rug plots.
+ */
+interface TickMarkLayout {
+    type: 'tick';
+    /** X position. */
+    x: number;
+    /** Y position. */
+    y: number;
+    /** Length of the tick mark in pixels. */
+    length: number;
+    /** Whether the tick is horizontal or vertical. */
+    orient: 'horizontal' | 'vertical';
+    /** Stroke color. */
+    stroke: string;
+    /** Stroke width in pixels. */
+    strokeWidth: number;
+    /** Opacity (0-1). */
+    opacity?: number;
+    /** Original data row. */
+    data: Record<string, unknown>;
+    /** Accessibility attributes. */
+    aria: MarkAria;
+}
 /** Discriminated union of all mark types. */
-type Mark = LineMark | AreaMark | RectMark | ArcMark | PointMark;
+type Mark = LineMark | AreaMark | RectMark | ArcMark | PointMark | TextMarkLayout | RuleMarkLayout | TickMarkLayout;
 /**
  * A resolved label: text with a computed position after collision detection.
  * The collision engine determines whether labels are visible or demoted to tooltip-only.
@@ -2152,4 +2601,4 @@ declare function scatterChart(data: DataRow[], x: FieldRef, y: FieldRef, options
  */
 declare function dataTable(data: DataRow[], options?: TableBuilderOptions): TableSpec;
 
-export { type A11yMetadata, type AggregateOp, type Annotation, type AnnotationAnchor, type AnnotationOffset, type AnnotationPosition, type ArcMark, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_RESERVE_WIDTH, type BarColumnConfig, type BarTableCell, type Breakpoint, CATEGORICAL_PALETTE, CHART_ENCODING_RULES, CHART_TYPES, 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 ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DateGranularity, type DivergingPalette, type ElementEdit, type Encoding, type EncodingChannel, type EncodingRule, type FieldRef, type FieldType, type FlagTableCell, GRAPH_ENCODING_RULES, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type ImageColumnConfig, type ImageTableCell, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LayoutStrategy, type LegendConfig, type LegendEntry, type LegendLayout, type LegendPosition, type LineMark, type Margins, type Mark, type MarkAria, type MarkEvent, type MeasureTextFn, type NodeOverride, type PaginationState, type Point, type PointMark, type RangeAnnotation, type Rect, type RectMark, type RefLineAnnotation, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedLabel, type ResolvedTheme, SEQUENTIAL_PALETTES, type ScaleConfig, type SequentialPalette, type SeriesStyle, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type StoredVizSpec, type TableBuilderOptions, type TableCell, type TableCellBase, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TextAnnotation, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeSpacing, type TooltipContent, type TooltipField, type VizSpec, abbreviateNumber, adaptColorForDarkMode, adaptTheme, areaChart, barChart, buildD3Formatter, checkPaletteDistinguishability, columnChart, computeChrome, computeLabelBounds, contrastRatio, dataTable, detectCollision, donutChart, dotChart, estimateTextWidth, findAccessibleColor, formatDate, formatNumber, generateAltText, generateAriaLabels, generateDataTable, getBreakpoint, getHeightClass, getLayoutStrategy, inferFieldType, isChartSpec, isGraphSpec, isRangeAnnotation, isRefLineAnnotation, isTableSpec, isTextAnnotation, lineChart, meetsAA, pieChart, resolveCollisions, resolveTheme, scatterChart, simulateColorBlindness };
+export { type A11yMetadata, type AggregateOp, type Annotation, type AnnotationAnchor, type AnnotationOffset, type AnnotationPosition, type ArcMark, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_RESERVE_WIDTH, type BarColumnConfig, type BarTableCell, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_PALETTE, CHART_ENCODING_RULES, CHART_TYPES, type CalculateExpression, type CalculateTransform, 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 ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type Condition, type ConditionalValueDef, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DateGranularity, type DivergingPalette, type ElementEdit, type Encoding, type EncodingChannel, type EncodingRule, type FieldPredicate, type FieldRef, type FieldType, type FilterPredicate, type FilterTransform, type FlagTableCell, GRAPH_ENCODING_RULES, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type ImageColumnConfig, type ImageTableCell, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LayerSpec, type LayoutStrategy, type LegendConfig, type LegendEntry, type LegendLayout, type LegendPosition, type LineMark, type LogicalAnd, type LogicalNot, type LogicalOr, MARK_DISPLAY_NAMES, MARK_ENCODING_RULES, MARK_TYPES, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type NodeOverride, type PaginationState, type Point, type PointMark, type RangeAnnotation, type Rect, type RectMark, type RefLineAnnotation, type ResolveConfig, type ResolveMode, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedLabel, type ResolvedTheme, type RuleMarkLayout, SEQUENTIAL_PALETTES, type ScaleConfig, type ScaleType, type SequentialPalette, type SeriesStyle, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type StoredVizSpec, type TableBuilderOptions, type TableCell, type TableCellBase, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TextAnnotation, type TextMarkLayout, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeSpacing, type TickMarkLayout, type TimeUnit, type TimeUnitTransform, type TooltipContent, type TooltipField, type Transform, type VizSpec, abbreviateNumber, adaptColorForDarkMode, adaptTheme, areaChart, barChart, buildD3Formatter, checkPaletteDistinguishability, columnChart, computeChrome, computeLabelBounds, contrastRatio, dataTable, detectCollision, donutChart, dotChart, estimateTextWidth, findAccessibleColor, formatDate, formatNumber, generateAltText, generateAriaLabels, generateDataTable, getBreakpoint, getHeightClass, getLayoutStrategy, inferFieldType, isChartSpec, isConditionalDef, isEncodingChannel, isGraphSpec, isLayerSpec, isRangeAnnotation, isRefLineAnnotation, isTableSpec, isTextAnnotation, lineChart, meetsAA, pieChart, resolveCollisions, resolveMarkDef, resolveMarkType, resolveTheme, scatterChart, simulateColorBlindness };