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

package/src/types/layout.ts

@@ -127,6 +127,12 @@ export interface AxisTick {
   position: number;
   /** Formatted label string for display. */
   label: string;
+  /**
+   * The untruncated label, set only when `label` was shortened with an ellipsis
+   * to fit the rotated-tick reservation. Renderers should surface this as the
+   * tick's accessible/tooltip text so the full category name is never lost.
+   */
+  fullLabel?: string;
   /** Secondary label text from axis.labelField. */
   subtitle?: string;
 }
@@ -190,6 +196,25 @@ export interface AxisLayout {
 // 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
@@ -277,6 +302,8 @@ export interface AreaMark {
   interpolate?: string;
   /** Fill color or gradient. */
   fill: string | GradientDef;
+  /** Resolved fill pattern. Present only when `mark.fillPattern: 'auto'` assigned one. */
+  pattern?: ResolvedFillPattern;
   /** Fill opacity. */
   fillOpacity: number;
   /** Optional stroke for the top boundary. */
@@ -323,6 +350,8 @@ export interface RectMark {
   height: number;
   /** Fill color or gradient. */
   fill: string | GradientDef;
+  /** Resolved fill pattern. Present only when `mark.fillPattern: 'auto'` assigned one. */
+  pattern?: ResolvedFillPattern;
   /** Stroke color. */
   stroke?: string;
   /** Stroke width. */
@@ -376,6 +405,8 @@ export interface ArcMark {
   endAngle: number;
   /** Fill color or gradient. */
   fill: string | GradientDef;
+  /** Resolved fill pattern. Present only when `mark.fillPattern: 'auto'` assigned one. */
+  pattern?: ResolvedFillPattern;
   /** Stroke color (usually white for slice separation). */
   stroke: string;
   /** Stroke width. */
@@ -434,10 +465,14 @@ export interface TextMarkLayout {
   type: 'textMark';
   /** Stable identity key for data-update transitions. */
   key?: string;
-  /** X position. */
+  /** X position, including any `dx` offset. */
   x: number;
-  /** Y position. */
+  /** Y position, including any `dy` offset. */
   y: number;
+  /** Data-space anchor before `dx` was applied. Set only when the mark is offset. */
+  anchorX?: number;
+  /** Data-space anchor before `dy` was applied. Set only when the mark is offset. */
+  anchorY?: number;
   /** Text content to display. */
   text: string;
   /** Fill color. */
@@ -450,6 +485,11 @@ export interface TextMarkLayout {
   fontFamily?: string;
   /** Horizontal text alignment. */
   textAnchor: 'start' | 'middle' | 'end';
+  /**
+   * Vertical baseline. Omit for the SVG default (alphabetic), which the calendar
+   * and parliament marks rely on — they hand-compute baseline-relative offsets.
+   */
+  dominantBaseline?: 'auto' | 'hanging' | 'central' | 'text-after-edge';
   /** Rotation angle in degrees. */
   angle?: number;
   /** Original data row. */
@@ -570,10 +610,19 @@ export interface ResolvedLabel {
     to: Point;
     /** Actual data point the connector is calling out. Renderer uses this for the endpoint marker. */
     endpoint?: Point;
+    /** Author's from-end nudge, re-applied on every geometry rebuild (mirrors `endpoint` for `to`). */
+    fromOffset?: { dx: number; dy: number };
     /** Connector line color. */
     stroke: string;
     /** Connector style: straight line, curved arrow, or vertical drop-line through the data point. */
     style: 'straight' | 'curve' | 'drop-line';
+    /** Whether to draw an arrowhead at the data-point end. */
+    arrow: boolean;
+    /**
+     * Which edge of the label block the connector leaves from. Renderers use it
+     * to shape the curve's control point. Internal; not part of the spec.
+     */
+    exit?: 'horizontal' | 'vertical';
   };
   /** Background color behind the label text. */
   background?: string;
@@ -595,6 +644,16 @@ export interface ResolvedAnnotation {
   type: 'text' | 'range' | 'refline';
   /** Stable identifier from the spec annotation, for selection/edit callbacks. */
   id?: string;
+  /**
+   * Index of the originating annotation in `spec.annotations`.
+   *
+   * The resolved array is a *filtered* view of the spec array -- an annotation
+   * whose position falls outside the scale domain resolves to nothing and is
+   * dropped -- so a resolved array index is NOT a spec index. Anything that has
+   * to reach back to the authored annotation (thinning's priority/responsive
+   * lookup, faceted footnote numbering) must key on this.
+   */
+  specIndex?: number;
   /** Label text (if any). */
   label?: ResolvedLabel;
   /** For range: the highlighted rectangle in pixel coordinates. */
@@ -614,8 +673,9 @@ export interface ResolvedAnnotation {
   /** Z-index for render ordering. Higher values render on top. */
   zIndex?: number;
   /**
-   * For text annotations: optional dot marker drawn at the connector's
-   * data-point endpoint. Coordinates match `label.connector.to` exactly.
+   * For text annotations: the endpoint marker drawn at the data point.
+   * Coordinates sit on the data point itself (plus any `connectorOffset.to`),
+   * not on the pulled-back `label.connector.to`.
    */
   dot?: {
     x: number;
@@ -671,10 +731,25 @@ export interface LegendEntry {
   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 {
-  /** Where the legend is positioned relative to the chart area. */
-  position: 'top' | 'right' | 'bottom' | 'bottom-right' | 'inline';
+  /**
+   * Which encoding channel this legend keys. Omitted means `'color'` (every
+   * legend was a color legend before size legends existed).
+   *
+   * This is the identity that makes plural legends safe: click-to-toggle-series
+   * must fire for color entries and never for size circles, and selection/drag
+   * must be able to tell two legends apart. Without it, `.oc-legend` and
+   * `data-legend-index` are ambiguous across legends and the DOM queries that
+   * read them silently pick whichever comes first.
+   */
+  channel?: LegendChannel;
+  /** Where the legend is positioned relative to the chart area. `'top-left'`
+   *  is a map-only overlay position (floats inside the map area). */
+  position: 'top' | 'top-left' | 'right' | 'bottom' | 'bottom-right' | 'inline';
   /** Bounding box for the legend (pixel coordinates). */
   bounds: Rect;
   /** Entry label style. */
@@ -733,8 +808,103 @@ export interface GradientLegendLayout extends BaseLegendLayout {
   maxLabel: string;
 }
 
-/** Resolved legend layout — either categorical (swatches) or gradient (continuous bar). */
-export type LegendLayout = CategoricalLegendLayout | GradientLegendLayout;
+/** 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)
@@ -826,7 +996,7 @@ export interface TooltipContent {
 
 /** Accessibility metadata for the entire visualization. */
 export interface A11yMetadata {
-  /** Generated alt text describing the visualization. */
+  /** Alt text describing the visualization: the author's `a11y.description` / `description` when set, auto-generated otherwise. */
   altText: string;
   /** Tabular data fallback for screen readers. Each inner array is a row. */
   dataTableFallback: unknown[][];
@@ -834,6 +1004,13 @@ export interface A11yMetadata {
   role: string;
   /** Whether the visualization is keyboard-navigable. */
   keyboardNavigable: boolean;
+  /**
+   * Hide the visualization from assistive technology (`aria-hidden="true"`,
+   * no screen-reader table, no keyboard mark navigation). Optional because
+   * only chart compilation sets it, and only on author opt-out via
+   * `a11y.hidden`.
+   */
+  hidden?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -900,6 +1077,108 @@ export interface ResolvedMetricBar {
   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)
 // ---------------------------------------------------------------------------
@@ -921,7 +1200,14 @@ export interface FacetPanelLayout {
   /** 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 };
+  header: {
+    text: string;
+    x: number;
+    y: number;
+    fontSize: number;
+    fontWeight: number;
+    textAnchor?: 'start' | 'middle' | 'end';
+  };
 }
 
 /** Layout for a faceted (small-multiples) chart. */
@@ -934,6 +1220,8 @@ export interface FacetLayout {
   columns: number;
   /** Whether scales are shared across panels. */
   sharedScales: boolean;
+  /** How panels are arranged: 'row' (vertical stack), 'column' (horizontal), 'wrap' (grid). */
+  direction: 'row' | 'column' | 'wrap';
 }
 
 /**
@@ -951,6 +1239,10 @@ export interface ChartLayout {
   chrome: ResolvedChrome;
   /** Resolved KPI metric bar. Present only when spec.metrics is supplied and fits. */
   metrics?: ResolvedMetricBar;
+  /** Reserved series-search band. Present only when spec.seriesSearch is enabled. */
+  seriesSearch?: ResolvedSeriesSearch;
+  /** Resolved "you draw it" config. Present only when spec.youDrawIt is enabled and valid. */
+  youDrawIt?: ResolvedYouDrawIt;
   /** Resolved axis layouts. */
   axes: {
     x?: AxisLayout;
@@ -962,8 +1254,22 @@ export interface ChartLayout {
   marks: Mark[];
   /** Resolved annotations with pixel positions. */
   annotations: ResolvedAnnotation[];
-  /** Legend layout (position, entries, bounds). */
+  /**
+   * Primary legend (the color legend). Kept as a singular slot: it is what every
+   * existing consumer reads, and a chart's legend is a color legend unless it
+   * says otherwise.
+   */
   legend: LegendLayout;
+  /**
+   * Every legend on the chart, in render order -- the color legend plus, when a
+   * quantitative `size` channel is encoded, a size legend.
+   *
+   * `legend` is `legends[0]` when a color legend exists. Consumers that reserve
+   * space or hit-test **must** iterate this array: a bubble chart keys both
+   * continent (color) and population (size), and reserving margin for only the
+   * first leaves the second drawing on top of the plot.
+   */
+  legends: LegendLayout[];
   /**
    * Right-side endpoint labels column for multi-series line/area charts.
    * Empty `entries` means the column is suppressed (single-series, opt-out, or
@@ -988,6 +1294,10 @@ export interface ChartLayout {
   crosshair: boolean;
   /** Real text measurement function from the adapter (for accurate SVG text wrapping). */
   measureText?: MeasureTextFn;
+  /** Scale inversion anchors for the x axis. Used by anchor drag to convert pixel to data-space. */
+  xInvert?: ScaleInvert;
+  /** Scale inversion anchors for the y axis. Used by anchor drag to convert pixel to data-space. */
+  yInvert?: ScaleInvert;
   /** Faceted (small-multiples) layout. When present, renderers iterate panels instead of using top-level marks/axes. */
   facet?: FacetLayout;
 }
@@ -1429,6 +1739,139 @@ export interface TileMapLayout {
   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)
 // ---------------------------------------------------------------------------
@@ -1529,6 +1972,24 @@ export interface CompileOptions {
   darkMode?: boolean;
   /** Whether to show the tryOpenData.ai watermark. Defaults to true. */
   watermark?: boolean;
+  /**
+   * Enable development-time diagnostics (WCAG contrast warnings via
+   * `console.warn`). The engine is isomorphic, so it never sniffs
+   * `process.env`; the host decides what "dev" means and passes this flag.
+   * Warnings are advisory only and never throw. Defaults to false.
+   */
+  dev?: boolean;
+  /**
+   * Sink for advisory spec warnings (deprecations, did-you-mean suggestions,
+   * unknown scheme names, overplotting/beeswarm budget notes, etc.). The engine
+   * is isomorphic and side-effect-free by default: rather than writing to the
+   * global `console`, it routes every advisory warning through this callback so
+   * a host can collect, reroute, or silence them (e.g. suppress under SSR, fail
+   * a test on any warning, surface them in a dev overlay). When omitted, the
+   * engine defaults to `console.warn`. Never called with fatal errors, which are
+   * thrown instead.
+   */
+  onWarn?: (message: string) => void;
   /**
    * Real text measurement function provided by the adapter.
    * Uses a hidden canvas or DOM element for accurate text dimensions.
@@ -1537,6 +1998,18 @@ export interface CompileOptions {
   measureText?: MeasureTextFn;
   /** Extra pixels to reserve on the right margin for a secondary y-axis. Set by compileLayer when resolve.scale.y is 'independent'. */
   rightAxisReserve?: number;
+  /**
+   * Extra pixels to reserve below the plot for the auto-thinning footnote list.
+   * Chicken-and-egg: thinning needs the chart area to decide what to demote, but
+   * the footnotes it produces need space carved out of that same area. compileChart
+   * resolves it by compiling once to learn the footnote count, then recompiling with
+   * this set. Callers should not set it; it is internal to that second pass.
+   */
+  footnoteReserve?: number;
+  /** Recursion depth of the footnote-reserve convergence pass. Internal to compileChart. */
+  footnotePass?: number;
+  /** Set after facet height growth to prevent unbounded recursion. Internal to compileFaceted. */
+  facetHeightGrown?: boolean;
   /**
    * Use this chart drawing area instead of computing one from chrome, axes,
    * and legend reservations. Set by compileLayer when compiling leaf layers so

package/src/types/schema-roots.ts

@@ -0,0 +1,32 @@
+/**
+ * Concrete (non-generic) type aliases used as JSON Schema generation roots.
+ *
+ * `ts-json-schema-generator` cannot instantiate generic type parameters, so the
+ * schema generator (`scripts/generate-schema.mjs`) points at these fixed
+ * aliases instead of the generic `ChartSpec<TData>` / `TableSpec` directly.
+ * They resolve every generic to its `DataRow` default, which is the shape an
+ * LLM actually emits (untyped rows).
+ *
+ * These aliases exist only to shape schema output. They are not re-exported
+ * from the package barrel and add no runtime surface.
+ */
+
+import type { ChartSpec, TableSpec, VizSpec } from './spec';
+
+/**
+ * Root for the full published schema (`vizspec.schema.json`). The complete
+ * discriminated union of every openchart spec kind.
+ */
+export type VizSpecSchema = VizSpec;
+
+/**
+ * Root for the ChartSpec subset schema (`chart.schema.json`). Covers all 16
+ * mark types. This is the LLM chart workhorse and the primary tool-use surface.
+ */
+export type ChartSpecSchema = ChartSpec;
+
+/**
+ * Root for the TableSpec subset schema (`table.schema.json`). The data-table
+ * visualization spec.
+ */
+export type TableSpecSchema = TableSpec;