@opendata-ai/openchart-core 8.0.0-rc.9 → 8.0.0

package/src/types/layout.ts

@@ -1,2024 +0,0 @@
-/**
- * Layout types: the engine output contract.
- *
- * These are the structured layout objects that the engine produces after
- * compiling a spec. Framework adapters consume these to render real DOM.
- *
- * The key distinction: spec.ts types are USER INPUT, layout.ts types are
- * ENGINE OUTPUT. Input types have optionals and unions. Output types are
- * fully resolved with computed positions, colors, and dimensions.
- */
-
-import type { GradientDef } from './spec';
-import type { ResolvedTheme } from './theme';
-
-// ---------------------------------------------------------------------------
-// Geometry primitives
-// ---------------------------------------------------------------------------
-
-/** A rectangle defined by position and dimensions. */
-export interface Rect {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-}
-
-/** Margins around a region (top, right, bottom, left). */
-export interface Margins {
-  top: number;
-  right: number;
-  bottom: number;
-  left: number;
-}
-
-/** A 2D point. */
-export interface Point {
-  x: number;
-  y: number;
-}
-
-// ---------------------------------------------------------------------------
-// Text styling
-// ---------------------------------------------------------------------------
-
-/** Resolved text style with all computed values. */
-export interface TextStyle {
-  /** Font family. */
-  fontFamily: string;
-  /** Font size in pixels. */
-  fontSize: number;
-  /** Font weight. */
-  fontWeight: number;
-  /** Text color (CSS color string). */
-  fill: string;
-  /** Line height multiplier. */
-  lineHeight: number;
-  /** Text anchor for SVG: start, middle, or end. */
-  textAnchor?: 'start' | 'middle' | 'end';
-  /** Dominant baseline for SVG text vertical alignment. */
-  dominantBaseline?: 'auto' | 'hanging' | 'central' | 'text-after-edge';
-  /** Font variant (e.g. "tabular-nums" for fixed-width digits). */
-  fontVariant?: string;
-}
-
-/** Cell style for table cells. */
-export interface CellStyle {
-  /** Background color. */
-  backgroundColor?: string;
-  /** Text color. */
-  color?: string;
-  /** Font weight. */
-  fontWeight?: number;
-  /** Font variant. */
-  fontVariant?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Chrome (resolved)
-// ---------------------------------------------------------------------------
-
-/** A single resolved chrome text element with computed position and style. */
-export interface ResolvedChromeElement {
-  /** The text content. */
-  text: string;
-  /** X position in the layout coordinate system. */
-  x: number;
-  /** Y position (baseline) in the layout coordinate system. */
-  y: number;
-  /** Maximum width for line wrapping. */
-  maxWidth: number;
-  /** Computed text style. */
-  style: TextStyle;
-}
-
-/**
- * Fully resolved chrome with computed positions for all elements.
- * Only present elements are included (no undefined checks needed at render time).
- */
-export interface ResolvedChrome {
-  /** Total height consumed by chrome elements above the chart area. */
-  topHeight: number;
-  /** Total height consumed by chrome elements below the chart area. */
-  bottomHeight: number;
-  /** Resolved chrome elements. Only present if specified in the spec. */
-  eyebrow?: ResolvedChromeElement;
-  title?: ResolvedChromeElement;
-  subtitle?: ResolvedChromeElement;
-  source?: ResolvedChromeElement;
-  byline?: ResolvedChromeElement;
-  footer?: ResolvedChromeElement;
-  brand?: ResolvedChromeElement;
-  /** Annotation footnotes generated by auto-thinning. Rendered as a numbered list above the source line. */
-  footnotes?: AnnotationFootnote[];
-  /** Absolute y at which bottom-chrome relative offsets are anchored: area.y + area.height + x-axis extent. */
-  bottomAnchorY?: number;
-}
-
-// ---------------------------------------------------------------------------
-// Axes
-// ---------------------------------------------------------------------------
-
-/** A single axis tick with computed position and formatted label. */
-export interface AxisTick {
-  /** The raw data value at this tick. */
-  value: unknown;
-  /** Pixel position along the axis. */
-  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;
-}
-
-/** A single gridline with computed positions. */
-export interface Gridline {
-  /** Pixel position along the axis. */
-  position: number;
-  /** Whether this is a major or minor gridline. */
-  major: boolean;
-}
-
-/** Resolved axis layout with computed tick positions and labels. */
-export interface AxisLayout {
-  /** Axis ticks with positions and labels. */
-  ticks: AxisTick[];
-  /** Gridlines at tick positions. */
-  gridlines: Gridline[];
-  /** Axis label text (e.g. "GDP Growth (%)"). */
-  label?: string;
-  /** Label style. */
-  labelStyle?: TextStyle;
-  /** Tick label style. */
-  tickLabelStyle: TextStyle;
-  /** Rotation angle in degrees for tick labels. */
-  tickAngle?: number;
-  /** Axis line start position. */
-  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;
-  /**
-   * Where tick labels render relative to the chart area.
-   * `'inline'` puts y-axis labels above their gridlines at chart-area x and
-   * suppresses the axis line and tick marks. `'gutter'` (default) keeps the
-   * classic outside-the-area placement.
-   */
-  tickPosition?: 'inline' | 'gutter';
-  /** Extent in px beyond the chart-area edge occupied by tick labels + title. Engine-resolved from the final (post-thinning) tick set. */
-  extent?: number;
-  /** Absolute anchor for the axis title. Replaces renderer-side offset math. */
-  titlePosition?: { x: number; y: number; angle?: number };
-}
-
-// ---------------------------------------------------------------------------
-// Marks (data visual elements)
-// ---------------------------------------------------------------------------
-
-/** The four built-in fill pattern shapes for series reinforcement. */
-export 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.
- */
-export 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. */
-export interface MarkAria {
-  /** ARIA label for the mark. Optional when `decorative: true` — decorative
-   *  marks render with `aria-hidden="true"` and don't need a label. */
-  label?: string;
-  /** Optional longer description. */
-  description?: string;
-  /** ARIA role override. */
-  role?: string;
-  /** When true, the mark is purely decorative (e.g. a sparkline endpoint dot
-   *  that duplicates an existing data point). Renderers translate this into
-   *  `aria-hidden="true"` and skip the mark from the screen-reader data table. */
-  decorative?: boolean;
-}
-
-/**
- * Line mark: a series of connected points.
- * Used by line charts and area chart boundaries.
- */
-export interface LineMark {
-  type: 'line';
-  /** Stable identity key for data-update transitions. */
-  key?: string;
-  /** Per-point identity keys parallel to `points`, for data-update transitions. */
-  pointKeys?: string[];
-  /** Ordered array of points defining the line path. */
-  points: Point[];
-  /** Pre-computed SVG path string (D3 monotone curve). When present, renderers
-   *  should use this instead of reconstructing straight M/L segments from points. */
-  path?: string;
-  /** Curve interpolation method used to build the path. Stored so the transition
-   *  driver can reconstruct paths from interpolated point positions. */
-  interpolate?: string;
-  /** Stroke color. */
-  stroke: string;
-  /** Stroke width in pixels. */
-  strokeWidth: number;
-  /** Line dash pattern (empty for solid). */
-  strokeDasharray?: string;
-  /** Overall opacity for the line (0-1). */
-  opacity?: number;
-  /** Series identifier (for multi-series charts). */
-  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. */
-  aria: MarkAria;
-  /** Index for stagger animation ordering. */
-  animationIndex?: number;
-  /** Which y-scale produced this mark ('y' = left, 'y2' = right). */
-  yScale?: 'y' | 'y2';
-}
-
-/**
- * Area mark: a filled region bounded by a top line and a baseline.
- * Used by area charts.
- */
-export interface AreaMark {
-  type: 'area';
-  /** Stable identity key for data-update transitions. */
-  key?: string;
-  /** Per-point identity keys parallel to `topPoints`, for data-update transitions. */
-  pointKeys?: string[];
-  /** Upper boundary points. */
-  topPoints: Point[];
-  /** Lower boundary points (baseline, usually y=0). */
-  bottomPoints: Point[];
-  /** SVG path string for the complete area shape. */
-  path: string;
-  /** SVG path string for just the top boundary (for stroking the data line only). */
-  topPath: string;
-  /** Curve interpolation method used to build the path. */
-  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. */
-  stroke?: string;
-  /** Stroke width. */
-  strokeWidth?: number;
-  /** Series identifier. */
-  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;
-  /** Index for stagger animation ordering. */
-  animationIndex?: number;
-  /** Which y-scale produced this mark ('y' = left, 'y2' = right). */
-  yScale?: 'y' | 'y2';
-}
-
-/**
- * Rect mark: a rectangle.
- * Used by bar charts, column charts, and heatmap cells.
- */
-export interface RectMark {
-  type: 'rect';
-  /** Stable identity key for data-update transitions. */
-  key?: string;
-  /** X position. */
-  x: number;
-  /** Y position. */
-  y: number;
-  /** Width. */
-  width: number;
-  /** Height. */
-  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. */
-  strokeWidth?: number;
-  /** Corner radius. */
-  cornerRadius?: number;
-  /**
-   * Which corners receive `cornerRadius`. Defaults to all four when unset.
-   * Used by stacked bars/columns to round only the leading edge of the
-   * topmost (vertical) or rightmost (horizontal) segment so the seams
-   * between stacked segments stay square and visually contiguous.
-   */
-  cornerRadiusSides?: { tl?: boolean; tr?: boolean; br?: boolean; bl?: boolean };
-  /** Original data row. */
-  data: Record<string, unknown>;
-  /** Resolved label. */
-  label?: ResolvedLabel;
-  /** Accessibility attributes. */
-  aria: MarkAria;
-  /** Index for stagger animation ordering. */
-  animationIndex?: number;
-  /** Bar orientation for animation direction. Set by the engine based on encoding. */
-  orient?: 'horizontal' | 'vertical';
-  /** Stacking group key (e.g. category name). Segments sharing this key animate together. */
-  stackGroup?: string;
-  /** Position of this segment within its stack group (0, 1, 2...). Set by engine for stacked bars. */
-  stackPos?: number;
-  /** Which y-scale produced this mark ('y' = left, 'y2' = right). */
-  yScale?: 'y' | 'y2';
-}
-
-/**
- * Arc mark: a pie/donut slice.
- * Used by pie and donut charts.
- */
-export interface ArcMark {
-  type: 'arc';
-  /** SVG path string for the arc. */
-  path: string;
-  /** Centroid point (center of the arc, for label positioning). */
-  centroid: Point;
-  /** Center of the pie/donut chart (for SVG translate). */
-  center: Point;
-  /** Inner radius (0 for pie, >0 for donut). */
-  innerRadius: number;
-  /** Outer radius. */
-  outerRadius: number;
-  /** Start angle in radians. */
-  startAngle: number;
-  /** End angle in radians. */
-  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. */
-  strokeWidth: number;
-  /** Original data row. */
-  data: Record<string, unknown>;
-  /** Resolved label. */
-  label?: ResolvedLabel;
-  /** Accessibility attributes. */
-  aria: MarkAria;
-  /** Stable identity key for data-update transitions. */
-  key?: string;
-  /** Index for stagger animation ordering. */
-  animationIndex?: number;
-}
-
-/**
- * Point mark: a circle or dot.
- * Used by scatter/bubble charts and dot plots.
- */
-export interface PointMark {
-  type: 'point';
-  /** Stable identity key for data-update transitions. */
-  key?: string;
-  /** Center x position. */
-  cx: number;
-  /** Center y position. */
-  cy: number;
-  /** Radius in pixels. */
-  r: number;
-  /** Fill color or gradient. */
-  fill: string | GradientDef;
-  /** Stroke color. */
-  stroke: string;
-  /** Stroke width. */
-  strokeWidth: number;
-  /** Fill opacity. */
-  fillOpacity?: number;
-  /** Original data row. */
-  data: Record<string, unknown>;
-  /** Resolved label. */
-  label?: ResolvedLabel;
-  /** Accessibility attributes. */
-  aria: MarkAria;
-  /** Index for stagger animation ordering. */
-  animationIndex?: number;
-  /** Which y-scale produced this mark ('y' = left, 'y2' = right). */
-  yScale?: 'y' | 'y2';
-}
-
-/**
- * Text mark: data-positioned text label.
- * Used by text charts for showing values directly at data coordinates.
- */
-export interface TextMarkLayout {
-  type: 'textMark';
-  /** Stable identity key for data-update transitions. */
-  key?: string;
-  /** X position, including any `dx` offset. */
-  x: number;
-  /** 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. */
-  fill: string;
-  /** Font size in pixels. */
-  fontSize: number;
-  /** Font weight. */
-  fontWeight?: number;
-  /** Font family override. */
-  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. */
-  data: Record<string, unknown>;
-  /** Resolved label. */
-  label?: ResolvedLabel;
-  /** Accessibility attributes. */
-  aria: MarkAria;
-  /** Index for stagger animation ordering. */
-  animationIndex?: number;
-  /** Which y-scale produced this mark ('y' = left, 'y2' = right). */
-  yScale?: 'y' | 'y2';
-}
-
-/**
- * Rule mark: a line segment between two points.
- * Used for reference lines rendered as data marks.
- */
-export interface RuleMarkLayout {
-  type: 'rule';
-  /** Stable identity key for data-update transitions. */
-  key?: string;
-  /** 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;
-  /** Index for stagger animation ordering. */
-  animationIndex?: number;
-  /** Which y-scale produced this mark ('y' = left, 'y2' = right). */
-  yScale?: 'y' | 'y2';
-}
-
-/**
- * Tick mark: a short line segment at a data coordinate.
- * Used for strip plots and rug plots.
- */
-export interface TickMarkLayout {
-  type: 'tick';
-  /** Stable identity key for data-update transitions. */
-  key?: string;
-  /** 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;
-  /** Index for stagger animation ordering. */
-  animationIndex?: number;
-  /** Which y-scale produced this mark ('y' = left, 'y2' = right). */
-  yScale?: 'y' | 'y2';
-}
-
-/** Discriminated union of all mark types. */
-export type Mark =
-  | LineMark
-  | AreaMark
-  | RectMark
-  | ArcMark
-  | PointMark
-  | TextMarkLayout
-  | RuleMarkLayout
-  | TickMarkLayout;
-
-// ---------------------------------------------------------------------------
-// Labels
-// ---------------------------------------------------------------------------
-
-/**
- * A resolved label: text with a computed position after collision detection.
- * The collision engine determines whether labels are visible or demoted to tooltip-only.
- */
-export interface ResolvedLabel {
-  /** Label text content. */
-  text: string;
-  /** Computed x position. */
-  x: number;
-  /** Computed y position (baseline). */
-  y: number;
-  /** Text style. */
-  style: TextStyle;
-  /** Whether this label is visible or was demoted to tooltip-only by collision detection. */
-  visible: boolean;
-  /** Maximum available width for the label text. When set, the renderer should wrap or truncate. */
-  maxWidth?: number;
-  /** If not at the anchor point, draw a connector line from label to anchor. */
-  connector?: {
-    /** Connector start (at the label). */
-    from: Point;
-    /** Connector end (pulled back from the data point so the line doesn't touch it). */
-    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;
-  /** Whether to show the paint-order stroke halo. Default true. */
-  halo?: boolean;
-  /** Engine-measured text-block bounds. Renderers should use this for background rects instead of re-estimating. */
-  bounds?: Rect;
-  /** Source index carried through from the LabelCandidate, if the caller set one. */
-  index?: number;
-}
-
-// ---------------------------------------------------------------------------
-// Annotations (resolved)
-// ---------------------------------------------------------------------------
-
-/** A resolved annotation with computed pixel positions. */
-export interface ResolvedAnnotation {
-  /** Original annotation type. */
-  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. */
-  rect?: Rect;
-  /** For refline: the line start and end in pixel coordinates. */
-  line?: { start: Point; end: Point };
-  /** Fill color. */
-  fill?: string;
-  /** Stroke color. */
-  stroke?: string;
-  /** Opacity. */
-  opacity?: number;
-  /** Line dash pattern for reflines. */
-  strokeDasharray?: string;
-  /** Stroke width. */
-  strokeWidth?: number;
-  /** Z-index for render ordering. Higher values render on top. */
-  zIndex?: number;
-  /**
-   * 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;
-    y: number;
-    radius: number;
-    fill: string;
-    stroke: string;
-    strokeWidth: number;
-  };
-  /**
-   * For text annotations: optional muted subtitle rendered below the primary
-   * label. Positioned `lineHeight * primaryLineCount + gap` below `label.y`.
-   */
-  subtitle?: {
-    text: string;
-    x: number;
-    y: number;
-    style: TextStyle;
-  };
-  /** Full placed extent: label bounds unioned with subtitle bounds. Collision and placement source of truth. */
-  bounds?: Rect;
-  /**
-   * When set, this annotation was demoted to a footnote marker by auto-thinning.
-   * The label is replaced by a numbered dot at the data point; the original text
-   * appears in the chrome footnote band. 1-indexed.
-   */
-  footnoteIndex?: number;
-}
-
-/** A footnote entry generated by annotation auto-thinning. */
-export interface AnnotationFootnote {
-  /** 1-indexed footnote number matching the dot marker on the chart. */
-  index: number;
-  /** The original annotation text that was demoted. */
-  text: string;
-}
-
-// ---------------------------------------------------------------------------
-// Legend
-// ---------------------------------------------------------------------------
-
-/** A single entry in a categorical legend. */
-export interface LegendEntry {
-  /** The label text (category name or range description). */
-  label: string;
-  /** The color swatch. */
-  color: string;
-  /** Shape of the swatch (matches the mark type). */
-  shape: 'circle' | 'square' | 'line';
-  /** Whether this entry is currently highlighted/active. */
-  active?: boolean;
-  /** True for overflow indicator entries ("+N more"). Not interactive. */
-  overflow?: boolean;
-}
-
-/** The encoding channel a legend keys. */
-export type LegendChannel = 'color' | 'size';
-
-/** Base legend layout fields shared by all legend types. */
-export interface BaseLegendLayout {
-  /**
-   * 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. */
-  labelStyle: TextStyle;
-}
-
-/** Engine-resolved absolute position for a single legend entry. */
-export interface LegendEntryPosition {
-  x: number;
-  y: number;
-  labelX: number;
-  labelY: number;
-  width: number;
-  row: number;
-}
-
-/** Categorical legend with discrete swatch entries. */
-export interface CategoricalLegendLayout extends BaseLegendLayout {
-  /** Discriminant for legend type. Omitted means categorical (backwards compat). */
-  type?: 'categorical';
-  /** Legend entries. */
-  entries: LegendEntry[];
-  /** Swatch size in pixels. */
-  swatchSize: number;
-  /** Gap between swatch and label. */
-  swatchGap: number;
-  /** Gap between entries. */
-  entryGap: number;
-  /** Fill color for the rounded chip background behind the colored bar. */
-  swatchChipFill: string;
-  /** Engine-resolved absolute positions, parallel to `entries`. */
-  entryPositions?: LegendEntryPosition[];
-  /** Row advance used to build entryPositions (single source of truth). */
-  rowHeight?: number;
-}
-
-/** A color stop in a gradient legend. */
-export interface GradientColorStop {
-  /** Position along the gradient (0 to 1). */
-  offset: number;
-  /** CSS color value. */
-  color: string;
-  /** Optional stop-opacity (0 to 1). */
-  opacity?: number;
-}
-
-/** Gradient legend for continuous color scales. */
-export interface GradientLegendLayout extends BaseLegendLayout {
-  /** Discriminant for legend type. */
-  type: 'gradient';
-  /** Color stops for the gradient bar. */
-  colorStops: GradientColorStop[];
-  /** Formatted minimum value label. */
-  minLabel: string;
-  /** Formatted maximum value label. */
-  maxLabel: string;
-}
-
-/** A positioned value label on a continuous/binned color legend. */
-export 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. */
-export 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.
- */
-export 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.
- */
-export 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.
- */
-export 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).
- */
-export type LegendLayout =
-  | CategoricalLegendLayout
-  | GradientLegendLayout
-  | ContinuousLegendLayout
-  | SizeLegendLayout;
-
-// ---------------------------------------------------------------------------
-// Endpoint labels (right-side per-series column for line/area charts)
-// ---------------------------------------------------------------------------
-
-/** A single resolved endpoint-label entry, fully positioned. */
-export interface EndpointLabelEntry {
-  /** Series identifier (matches mark.seriesKey). */
-  seriesKey: string;
-  /** Pre-wrapped label text lines. */
-  labelLines: string[];
-  /** Formatted value string for the last data point. */
-  value: string;
-  /** Series color. */
-  color: string;
-  /** True pixel y of the last data point on the line. */
-  dataY: number;
-  /** Displaced y after the bidirectional collision sweep. */
-  labelY: number;
-  /** True when |labelY - dataY| exceeds the threshold (renderer draws a leader line). */
-  showLeader: boolean;
-  /** Optional anchor circle drawn on the line at the chart's right edge. */
-  marker?: {
-    /** Rendered cx (offset right by radius so the line terminates at the circle edge). */
-    x: number;
-    y: number;
-    /** Original data point x (used to suppress the underlying point mark). */
-    dataX: number;
-    fill: string;
-    stroke: string;
-    strokeWidth: number;
-    radius: number;
-  };
-}
-
-/** Resolved layout for the endpoint labels column. */
-export interface EndpointLabelsLayout {
-  /** Per-series resolved entries. */
-  entries: EndpointLabelEntry[];
-  /** Bounding box for the column. */
-  bounds: Rect;
-  /** Style for the series-name text. */
-  labelStyle: TextStyle;
-  /** Style for the formatted value text. */
-  valueStyle: TextStyle;
-  /** Width of the colored swatch line drawn left of the label. */
-  swatchSize: number;
-  /** Horizontal gap between swatch and label text. */
-  gap: number;
-  /**
-   * Vertical gap between the last wrapped label line and the value text
-   * directly below it. Resolved by the engine so the renderer can't drift
-   * away from the height the collision sweep budgeted for each entry.
-   */
-  valueGap: number;
-  /** Fill color for the rounded chip background behind the colored bar. */
-  swatchChipFill: string;
-  /** Leading-edge (left side) entries when `ends: 'both'`. Empty when trailing only. */
-  leading?: EndpointLabelEntry[];
-  /** Bounding box for the leading column. Only set when `ends: 'both'`. */
-  leadingBounds?: Rect;
-}
-
-// ---------------------------------------------------------------------------
-// Tooltips
-// ---------------------------------------------------------------------------
-
-/** A single field-value pair in a tooltip. */
-export interface TooltipField {
-  /** Field label (e.g. "GDP Growth"). */
-  label: string;
-  /** Formatted value (e.g. "4.2%"). */
-  value: string;
-  /** Optional color swatch for series identification. */
-  color?: string;
-}
-
-/** Tooltip content descriptor for a data point. */
-export interface TooltipContent {
-  /** Title line (e.g. the x-axis value like "2020-Q1"). */
-  title?: string;
-  /** Field-value pairs to display. */
-  fields: TooltipField[];
-}
-
-// ---------------------------------------------------------------------------
-// Accessibility
-// ---------------------------------------------------------------------------
-
-/** Accessibility metadata for the entire visualization. */
-export interface A11yMetadata {
-  /** 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[][];
-  /** ARIA role for the visualization root element. */
-  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;
-}
-
-// ---------------------------------------------------------------------------
-// Animation (resolved)
-// ---------------------------------------------------------------------------
-
-/** One fully-resolved animation phase. */
-export interface ResolvedAnimationPhase {
-  /** Duration in ms. */
-  duration: number;
-  /** Easing preset name. */
-  ease: import('./spec').AnimationEase;
-  /** Stagger delay between elements in ms. */
-  staggerDelay: number;
-  /** Stagger ordering. */
-  staggerOrder: 'index' | 'value' | 'reverse';
-}
-
-/** Resolved animation config. A phase is present iff that phase is enabled. */
-export interface ResolvedAnimation {
-  /** Entrance animation phase. Present when enter animation is enabled. */
-  enter?: ResolvedAnimationPhase;
-  /** Data-update transition phase. Present when update animation is enabled. */
-  update?: ResolvedAnimationPhase;
-  /** Exit animation phase. Present when exit animation is enabled. */
-  exit?: ResolvedAnimationPhase;
-  /** Delay before annotations animate in (ms after marks). */
-  annotationDelay: number;
-}
-
-// ---------------------------------------------------------------------------
-// Metric bar (resolved)
-// ---------------------------------------------------------------------------
-
-/**
- * A resolved KPI metric cell with computed positions for label, value, and
- * supplementary text spans. Cells render as a row above the chart area.
- */
-export interface ResolvedMetricCell {
-  /** Cell left x in layout coordinates. */
-  x: number;
-  /** Cell width. */
-  cellWidth: number;
-  /** Baseline y for the uppercase label. */
-  labelY: number;
-  /** Baseline y for the primary value. */
-  valueY: number;
-  /** The original metric spec (label/value/delta/etc.). */
-  metric: import('./spec').Metric;
-  /** True if value+delta+secondary would overflow cellWidth. Set by layout for diagnostics. */
-  overflowed: boolean;
-}
-
-/**
- * The full metric-bar layout. Present only when spec.metrics is supplied
- * and the bar fits the container.
- */
-export interface ResolvedMetricBar {
-  /** Top y of the metric row in layout coordinates. */
-  y: number;
-  /** Total reserved height of the row. */
-  height: number;
-  /** Cells laid out evenly across the chart width. */
-  cells: ResolvedMetricCell[];
-}
-
-// ---------------------------------------------------------------------------
-// Series search (resolved)
-// ---------------------------------------------------------------------------
-
-/**
- * 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.
- */
-export 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[];
-}
-
-// ---------------------------------------------------------------------------
-// You draw it (resolved)
-// ---------------------------------------------------------------------------
-
-/**
- * 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.
- */
-export 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).
- */
-export 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.
- */
-export 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.
- */
-export 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[];
-}
-
-// ---------------------------------------------------------------------------
-// ChartLayout (the main engine output for charts)
-// ---------------------------------------------------------------------------
-
-/**
- * A single panel in a faceted (small-multiples) layout.
- * Each panel has its own marks, axes, and drawing area but typically
- * shares scales with sibling panels.
- */
-export interface FacetPanelLayout {
-  /** Facet value that produced this panel. */
-  key: string;
-  /** Panel drawing area in SVG coordinates. */
-  area: Rect;
-  /** Data marks for this panel. */
-  marks: Mark[];
-  /** Per-panel axis layouts. Inner panels may have ticks suppressed. */
-  axes: { x?: AxisLayout; y?: AxisLayout };
-  /** Per-panel annotations. */
-  annotations: ResolvedAnnotation[];
-  /** Panel header label (facet value) positioned above the panel. */
-  header: { text: string; x: number; y: number; fontSize: number; fontWeight: number };
-}
-
-/** Layout for a faceted (small-multiples) chart. */
-export interface FacetLayout {
-  /** Ordered array of panel layouts. */
-  panels: FacetPanelLayout[];
-  /** The data field used for faceting. */
-  facetField: string;
-  /** Number of columns in the wrap grid. */
-  columns: number;
-  /** Whether scales are shared across panels. */
-  sharedScales: boolean;
-}
-
-/**
- * ChartLayout: the complete engine output for chart visualizations.
- *
- * Contains everything an adapter needs to render the chart: dimensions,
- * chrome text, axes, data marks, annotations, legend, tooltip descriptors,
- * and accessibility metadata. All values are fully computed pixel positions
- * and resolved colors.
- */
-export interface ChartLayout {
-  /** The chart drawing area (after chrome, axes, and legend are subtracted). */
-  area: Rect;
-  /** Resolved chrome text elements with positions and styles. */
-  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;
-    y?: AxisLayout;
-    /** Right-side y-axis for independent-scale layers (dual-axis charts). */
-    y2?: AxisLayout;
-  };
-  /** Data marks: the visual representation of data points. */
-  marks: Mark[];
-  /** Resolved annotations with pixel positions. */
-  annotations: ResolvedAnnotation[];
-  /**
-   * 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
-   * auto-suppressed by the truth table).
-   */
-  endpointLabels?: EndpointLabelsLayout;
-  /** Tooltip descriptors keyed by a mark identifier. */
-  tooltipDescriptors: Map<string, TooltipContent>;
-  /** Accessibility metadata. */
-  a11y: A11yMetadata;
-  /** The resolved theme used for rendering. */
-  theme: ResolvedTheme;
-  /** Total SVG dimensions. */
-  dimensions: { width: number; height: number };
-  /** Resolved animation config. Present only when animation is enabled. */
-  animation?: ResolvedAnimation;
-  /** Whether the tryOpenData.ai watermark is enabled. */
-  watermark: boolean;
-  /** Display mode controlling chrome/axes/legend stripping. `'sparkline'` produces an edge-to-edge mini chart. */
-  display: import('./spec').Display;
-  /** Whether the crosshair (vertical snap line) is enabled. */
-  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;
-}
-
-// ---------------------------------------------------------------------------
-// TableLayout (engine output for tables)
-// ---------------------------------------------------------------------------
-
-/** A resolved column definition with computed properties. */
-export interface ResolvedColumn {
-  /** Column key (data field name). */
-  key: string;
-  /** Display label. */
-  label: string;
-  /** Computed width in pixels. */
-  width: number;
-  /** Whether sorting is enabled. */
-  sortable: boolean;
-  /** Text alignment. */
-  align: 'left' | 'center' | 'right';
-  /** Column cell type (determines rendering strategy). */
-  cellType: 'text' | 'heatmap' | 'category' | 'bar' | 'sparkline' | 'image' | 'flag';
-}
-
-/** Base properties for all table cell types. */
-export interface TableCellBase {
-  /** Raw value from the data. */
-  value: unknown;
-  /** Formatted display value. */
-  formattedValue: string;
-  /** Computed cell style. */
-  style: CellStyle;
-  /** ARIA label for the cell. */
-  aria?: string;
-}
-
-/** Plain text cell. */
-export interface TextTableCell extends TableCellBase {
-  cellType: 'text';
-}
-
-/** Heatmap-colored cell. */
-export interface HeatmapTableCell extends TableCellBase {
-  cellType: 'heatmap';
-}
-
-/** Category-colored cell. */
-export interface CategoryTableCell extends TableCellBase {
-  cellType: 'category';
-}
-
-/** Cell with an inline bar visualization. */
-export interface BarTableCell extends TableCellBase {
-  cellType: 'bar';
-  /** Bar width as a proportion (0 to 1) of available cell width. */
-  barWidth: number;
-  /** Bar left-edge offset as a proportion (0 to 1). 0 = left edge. */
-  barOffset: number;
-  /** Bar fill color. */
-  barColor: string;
-  /** Whether this bar represents a negative value. */
-  isNegative: boolean;
-}
-
-/** Normalized sparkline data ready for rendering. */
-export interface SparklineData {
-  /** Sparkline type. */
-  type: 'line' | 'bar' | 'column';
-  /** Normalized points in 0-1 range (for line type: x/y coordinates). */
-  points: Array<{ x: number; y: number }>;
-  /** For bar/column: widths or heights as 0-1 proportions. */
-  bars: number[];
-  /** Sparkline stroke/fill color. */
-  color: string;
-  /** Number of data points. */
-  count: number;
-  /** Raw value of the first data point. */
-  startValue: number;
-  /** Raw value of the last data point. */
-  endValue: number;
-}
-
-/** Cell with an inline sparkline. */
-export interface SparklineTableCell extends TableCellBase {
-  cellType: 'sparkline';
-  /** Sparkline rendering data (normalized points, color, type). Null when no valid data. */
-  sparklineData: SparklineData | null;
-}
-
-/** Cell with an image. */
-export interface ImageTableCell extends TableCellBase {
-  cellType: 'image';
-  /** Image URL. */
-  src: string;
-  /** Image width. */
-  imageWidth: number;
-  /** Image height. */
-  imageHeight: number;
-  /** Whether to apply rounded styling. */
-  rounded: boolean;
-}
-
-/** Cell displaying a flag. */
-export interface FlagTableCell extends TableCellBase {
-  cellType: 'flag';
-  /** Country code or flag identifier. */
-  countryCode: string;
-}
-
-/** Discriminated union of all table cell types. */
-export type TableCell =
-  | TextTableCell
-  | HeatmapTableCell
-  | CategoryTableCell
-  | BarTableCell
-  | SparklineTableCell
-  | ImageTableCell
-  | FlagTableCell;
-
-/** A resolved table row. */
-export interface TableRow {
-  /** Unique row identifier. */
-  id: string;
-  /** Resolved cells in column order. */
-  cells: TableCell[];
-  /** Original data row. */
-  data: Record<string, unknown>;
-}
-
-/** Pagination state for the table. */
-export interface PaginationState {
-  /** Current page (0-indexed). */
-  page: number;
-  /** Rows per page. */
-  pageSize: number;
-  /** Total number of rows. */
-  totalRows: number;
-  /** Total number of pages. */
-  totalPages: number;
-}
-
-/** Sort state for the table. */
-export interface SortState {
-  /** Column key being sorted. */
-  column: string;
-  /** Sort direction. */
-  direction: 'asc' | 'desc';
-}
-
-/**
- * TableLayout: the complete engine output for table visualizations.
- *
- * Contains resolved columns, rows with computed cell values and styles,
- * pagination, sort, search state, and accessibility metadata.
- */
-export interface TableLayout {
-  /** Resolved chrome text elements. */
-  chrome: ResolvedChrome;
-  /** Resolved column definitions. */
-  columns: ResolvedColumn[];
-  /** Resolved table rows with computed cell values and styles. */
-  rows: TableRow[];
-  /** Current sort state. */
-  sort?: SortState;
-  /** Pagination state. */
-  pagination?: PaginationState;
-  /** Whether search is enabled. */
-  search: { enabled: boolean; placeholder: string; query: string };
-  /** Whether the first column is sticky. */
-  stickyFirstColumn: boolean;
-  /** Whether compact mode is active. */
-  compact: boolean;
-  /** Accessibility metadata. */
-  a11y: { caption: string; summary: string };
-  /** The resolved theme. */
-  theme: ResolvedTheme;
-  /** Resolved animation config. Present only when animation is enabled. */
-  animation?: ResolvedAnimation;
-  /** Whether the tryOpenData.ai watermark is enabled. */
-  watermark: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// GraphLayout (engine output for network graphs)
-// ---------------------------------------------------------------------------
-
-/** A resolved graph node with computed position and visual properties. */
-export interface GraphNodeLayout {
-  /** Node id. */
-  id: string;
-  /** Computed x position. */
-  x: number;
-  /** Computed y position. */
-  y: number;
-  /** Node radius in pixels. */
-  radius: number;
-  /** Fill color. */
-  fill: string;
-  /** Stroke color. */
-  stroke: string;
-  /** Stroke width. */
-  strokeWidth: number;
-  /** Node label. */
-  label?: ResolvedLabel;
-  /** Original node data. */
-  data: Record<string, unknown>;
-  /** Community/cluster identifier (from clustering config). */
-  community?: string;
-  /** Accessibility attributes. */
-  aria: MarkAria;
-}
-
-/** A resolved graph edge with computed positions and visual properties. */
-export interface GraphEdgeLayout {
-  /** Source node id. */
-  source: string;
-  /** Target node id. */
-  target: string;
-  /** Source x position. */
-  x1: number;
-  /** Source y position. */
-  y1: number;
-  /** Target x position. */
-  x2: number;
-  /** Target y position. */
-  y2: number;
-  /** Stroke color. */
-  stroke: string;
-  /** Stroke width. */
-  strokeWidth: number;
-  /** Line style. */
-  style: 'solid' | 'dashed' | 'dotted';
-  /** Original edge data. */
-  data: Record<string, unknown>;
-}
-
-/**
- * GraphLayout: the complete engine output for network graph visualizations.
- *
- * Note: GraphLayout is defined here for forward compatibility but the engine
- * won't produce it until the graph renderer is implemented in a future phase.
- */
-export interface GraphLayout {
-  /** The graph drawing area. */
-  area: Rect;
-  /** Resolved chrome text. */
-  chrome: ResolvedChrome;
-  /** Resolved node positions and visual properties. */
-  nodes: GraphNodeLayout[];
-  /** Resolved edge positions and visual properties. */
-  edges: GraphEdgeLayout[];
-  /** Legend layout. */
-  legend: LegendLayout;
-  /** Tooltip descriptors. */
-  tooltipDescriptors: Map<string, TooltipContent>;
-  /** Accessibility metadata. */
-  a11y: A11yMetadata;
-  /** The resolved theme. */
-  theme: ResolvedTheme;
-  /** Total dimensions. */
-  dimensions: { width: number; height: number };
-}
-
-// ---------------------------------------------------------------------------
-// SankeyLayout (engine output for sankey diagrams)
-// ---------------------------------------------------------------------------
-
-/** A resolved sankey node with computed position and visual properties. */
-export interface SankeyNodeMark {
-  type: 'sankeyNode';
-  /** Left edge x position. */
-  x: number;
-  /** Top edge y position. */
-  y: number;
-  /** Node rectangle width. */
-  width: number;
-  /** Node rectangle height (proportional to throughput). */
-  height: number;
-  /** Fill color. */
-  fill: string;
-  /** Stroke color. */
-  stroke?: string;
-  /** Stroke width. */
-  strokeWidth?: number;
-  /** Corner radius for subtle rounding. */
-  cornerRadius: number;
-  /** Node label positioned outside the node. */
-  label: ResolvedLabel;
-  /** Node identifier (unique across the diagram). */
-  nodeId: string;
-  /** Total value flowing through this node. */
-  value: number;
-  /** Depth column (0 = leftmost). */
-  depth: number;
-  /** Original data associated with this node. */
-  data: Record<string, unknown>;
-  /** Accessibility attributes. */
-  aria: MarkAria;
-  /** Index for stagger animation ordering. */
-  animationIndex?: number;
-}
-
-/** A resolved sankey link with computed path and visual properties. */
-export interface SankeyLinkMark {
-  type: 'sankeyLink';
-  /** SVG path string for the curved ribbon. */
-  path: string;
-  /** Source node color (for gradient start). */
-  sourceColor: string;
-  /** Target node color (for gradient end). */
-  targetColor: string;
-  /** Fill opacity (0.35 default, increases on hover). */
-  fillOpacity: number;
-  /** Source node identifier. */
-  sourceId: string;
-  /** Target node identifier. */
-  targetId: string;
-  /** Link ribbon width at its thinnest point. */
-  width: number;
-  /** Flow value this link represents. */
-  value: number;
-  /** Original data row for this link. */
-  data: Record<string, unknown>;
-  /** Accessibility attributes. */
-  aria: MarkAria;
-  /** Index for stagger animation ordering. */
-  animationIndex?: number;
-}
-
-/**
- * SankeyLayout: the complete engine output for sankey diagram visualizations.
- *
- * Contains everything an adapter needs to render the sankey: dimensions,
- * chrome, nodes, links, legend, tooltip descriptors, and accessibility metadata.
- * No axes (sankey has no traditional axis system).
- */
-export interface SankeyLayout {
-  /** The sankey drawing area (after chrome and legend are subtracted). */
-  area: Rect;
-  /** Resolved chrome text elements with positions and styles. */
-  chrome: ResolvedChrome;
-  /** Resolved sankey node marks with positions and colors. */
-  nodes: SankeyNodeMark[];
-  /** Resolved sankey link marks with paths and gradient colors. */
-  links: SankeyLinkMark[];
-  /** Legend layout (position, entries, bounds). */
-  legend: LegendLayout;
-  /** Tooltip descriptors keyed by node/link identifier. */
-  tooltipDescriptors: Map<string, TooltipContent>;
-  /** Accessibility metadata. */
-  a11y: A11yMetadata;
-  /** The resolved theme used for rendering. */
-  theme: ResolvedTheme;
-  /** Total SVG dimensions. */
-  dimensions: { width: number; height: number };
-  /** Resolved animation config. Present only when animation is enabled. */
-  animation?: ResolvedAnimation;
-  /** Whether the tryOpenData.ai watermark is enabled. */
-  watermark: boolean;
-  /** Real text measurement function from the adapter (for accurate SVG text wrapping). */
-  measureText?: MeasureTextFn;
-}
-
-// ---------------------------------------------------------------------------
-// TileMapLayout (engine output for tile map visualizations)
-// ---------------------------------------------------------------------------
-
-/** A resolved tile map tile with computed position and visual properties. */
-export interface TileMapTileMark {
-  type: 'tile';
-  /** Left edge x position. */
-  x: number;
-  /** Top edge y position. */
-  y: number;
-  /** Tile width and height (tiles are square). */
-  size: number;
-  /** Fill color from the sequential color scale. */
-  fill: string;
-  /** Fill opacity (0-1). Used for opacity-based encoding. */
-  fillOpacity: number;
-  /** Tile border color. */
-  stroke: string;
-  /** Tile border width. */
-  strokeWidth: number;
-  /** Corner radius. */
-  cornerRadius: number;
-  /** US state abbreviation (e.g. "CA", "TX"). */
-  stateCode: string;
-  /** Numeric value (null if state has no data). */
-  value: number | null;
-  /** Formatted value string (e.g. "12,000" or "–" for missing). */
-  formattedValue: string;
-  /** Whether this state has data. False for missing states. */
-  hasData: boolean;
-  /** State code text label (positioned inside tile). */
-  label: ResolvedLabel;
-  /** Value text label (positioned inside tile, below state code). */
-  valueLabel: ResolvedLabel;
-  /** Accessibility attributes. */
-  aria: MarkAria;
-  /** Index for stagger animation ordering. */
-  animationIndex?: number;
-  /** Original data associated with this tile. */
-  data: Record<string, unknown>;
-}
-
-/**
- * TileMapLayout: the complete engine output for tile map visualizations.
- *
- * Contains everything an adapter needs to render the tile map: dimensions,
- * chrome, tiles, gradient legend, tooltip descriptors, and accessibility metadata.
- */
-export interface TileMapLayout {
-  /** The tile map drawing area (after chrome and legend are subtracted). */
-  area: Rect;
-  /** Resolved chrome text elements with positions and styles. */
-  chrome: ResolvedChrome;
-  /** Resolved tile marks with positions, colors, and labels. */
-  tiles: TileMapTileMark[];
-  /** Gradient color legend for quantitative mode (null if hidden or categorical). */
-  gradientLegend: GradientLegendLayout | null;
-  /** Categorical swatch legend for nominal mode (null if hidden or quantitative). */
-  categoricalLegend: CategoricalLegendLayout | null;
-  /** Tooltip content descriptors keyed by state code. */
-  tooltipDescriptors: Map<string, TooltipContent>;
-  /** Accessibility metadata for the tile 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;
-}
-
-// ---------------------------------------------------------------------------
-// MapLayout (engine output for map visualizations)
-// ---------------------------------------------------------------------------
-
-/** A structured compile warning with a code and context. */
-export interface CompileWarning {
-  code: string;
-  message: string;
-  context?: Record<string, unknown>;
-}
-
-/** Resolved focus target for map camera framing. */
-export 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. */
-export 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. */
-export 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). */
-export 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.
- */
-export 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;
-}
-
-// ---------------------------------------------------------------------------
-// BarListLayout (engine output for bar list visualizations)
-// ---------------------------------------------------------------------------
-
-/** A resolved bar list row with computed positions and visual properties. */
-export interface BarListRowMark {
-  type: 'barlist-row';
-  /** Row index (0-based). */
-  index: number;
-  /** Row top y position. */
-  y: number;
-  /** Row height (includes spacing). */
-  height: number;
-  /** Label text for this row. */
-  label: ResolvedLabel;
-  /** Optional subtitle text. */
-  subtitle?: ResolvedLabel;
-  /** Track rectangle (the muted background bar). */
-  track: { x: number; y: number; width: number; height: number; cornerRadius: number };
-  /** Fill bar rectangle (the colored bar proportional to value). */
-  bar: { x: number; y: number; width: number; height: number; cornerRadius: number; fill: string };
-  /** Formatted value label (right-aligned). */
-  valueLabel: ResolvedLabel;
-  /** Raw numeric value. */
-  value: number;
-  /** Formatted value string. */
-  formattedValue: string;
-  /** Accessibility attributes. */
-  aria: MarkAria;
-  /** Index for stagger animation ordering. */
-  animationIndex: number;
-  /** Original data row. */
-  data: Record<string, unknown>;
-}
-
-/**
- * BarListLayout: the complete engine output for bar list visualizations.
- *
- * Contains everything an adapter needs to render the bar list: dimensions,
- * chrome, row marks, tooltip descriptors, and accessibility metadata.
- */
-export interface BarListLayout {
-  /** The bar list drawing area. */
-  area: Rect;
-  /** Resolved chrome text elements with positions and styles. */
-  chrome: ResolvedChrome;
-  /** Resolved row marks with positions, colors, and labels. */
-  rows: BarListRowMark[];
-  /** Tooltip content descriptors keyed by row index. */
-  tooltipDescriptors: Map<string, TooltipContent>;
-  /** Accessibility metadata. */
-  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;
-}
-
-// ---------------------------------------------------------------------------
-// Compile options (engine input)
-// ---------------------------------------------------------------------------
-
-/** Function signature for text measurement provided by adapters. */
-export type MeasureTextFn = (
-  text: string,
-  fontSize: number,
-  fontWeight?: number,
-) => { width: number; height: number };
-
-/**
- * Options passed to the engine's compile functions.
- *
- * Width and height define the total available space. The engine subtracts
- * chrome, axes, and legend to compute the chart drawing area.
- */
-export interface CompileOptions {
-  /** Total available width in pixels. */
-  width: number;
-  /** Total available height in pixels. */
-  height: number;
-  /** Theme overrides. */
-  theme?: import('./spec').ThemeConfig;
-  /**
-   * Resolved dark mode boolean.
-   *
-   * Note: this is a boolean, not the DarkMode union ("auto" | "force" | "off").
-   * Adapters resolve "auto" by checking window.matchMedia('(prefers-color-scheme: dark)')
-   * before calling compile. The engine always receives a resolved boolean.
-   */
-  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.
-   * If not provided, the engine falls back to heuristic estimation.
-   */
-  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
-   * their marks land in the primary layout's coordinate space; leaf specs lack
-   * the layer-level chrome/legend/theme and would otherwise compute a
-   * different area than the one the axes are rendered in.
-   */
-  frozenChartArea?: Rect;
-}
-
-/** Extended compile options for table visualizations. */
-export interface CompileTableOptions extends CompileOptions {
-  /** Current sort state to apply. */
-  sort?: SortState;
-  /** Search query to filter rows. */
-  search?: string;
-  /** Current page (0-indexed). */
-  page?: number;
-  /** Rows per page. */
-  pageSize?: number;
-}