graphein 0.17.0 → 0.19.0

package/dist/index.d.ts

@@ -176,6 +176,11 @@ declare function interpolateOklab(a: RGBA, b: RGBA): Interpolator;
 /** Get a categorical palette by name (defaults to the 'graphein' palette). */
 declare function categorical(name?: string): string[];
 declare const categoricalSchemes: string[];
+/**
+ * Derive a categorical palette for dark surfaces while preserving each swatch's
+ * OKLCH hue identity. Invalid colors are passed through unchanged.
+ */
+declare function adaptPaletteForDarkBackground(palette: readonly string[], background?: string, minContrast?: number): string[];
 /**
  * Build a continuous ramp from ordered color stops, interpolating each segment
  * in OKLab. Endpoints (t=0,1) return the first/last stop exactly.
@@ -604,48 +609,71 @@ interface ThemeColors {
     /** Negative / down semantics. */
     negative: string;
 }
+interface ThemeFontSizes {
+    tiny: number;
+    small: number;
+    base: number;
+    large: number;
+    title: number;
+}
+interface ThemeFontWeights {
+    normal: number;
+    medium: number;
+    bold: number;
+}
 interface ThemeFont {
     family: string;
-    size: {
-        tiny: number;
-        small: number;
-        base: number;
-        large: number;
-        title: number;
-    };
-    weight: {
-        normal: number;
-        medium: number;
-        bold: number;
-    };
+    size: ThemeFontSizes;
+    weight: ThemeFontWeights;
+}
+interface ThemeSpacing {
+    xs: number;
+    sm: number;
+    md: number;
+    lg: number;
+    xl: number;
+}
+interface ThemeRadii {
+    sm: number;
+    md: number;
+    lg: number;
+}
+interface ThemeStrokes {
+    thin: number;
+    base: number;
+    thick: number;
 }
 interface ThemeTokens {
     name: string;
     dark: boolean;
     color: ThemeColors;
     font: ThemeFont;
-    spacing: {
-        xs: number;
-        sm: number;
-        md: number;
-        lg: number;
-        xl: number;
-    };
-    radius: {
-        sm: number;
-        md: number;
-        lg: number;
-    };
-    stroke: {
-        thin: number;
-        base: number;
-        thick: number;
-    };
+    spacing: ThemeSpacing;
+    radius: ThemeRadii;
+    stroke: ThemeStrokes;
+}
+/** Non-fatal theme resolution warning. */
+interface ThemeWarning {
+    /** Dot path to the invalid override token. */
+    path: string;
+    /** Human-readable warning. */
+    message: string;
+}
+/** Theme resolution result with non-fatal warnings. */
+interface ResolvedTheme {
+    /** Concrete theme tokens after applying valid overrides. */
+    tokens: ThemeTokens;
+    /** Non-fatal warnings for ignored invalid overrides. */
+    warnings: ThemeWarning[];
 }
 declare const lightTheme: ThemeTokens;
 declare const darkTheme: ThemeTokens;
 declare const themes: Record<string, ThemeTokens>;
-type ThemeInput = string | (Partial<ThemeTokens> & {
+type TokenOverrides<T> = {
+    [K in keyof T]?: T[K] extends readonly unknown[] ? T[K] : T[K] extends object ? TokenOverrides<T[K]> : T[K];
+};
+/** Named theme or nested token overrides; unspecified tokens retain their base values. */
+type ThemeInput = string | (TokenOverrides<ThemeTokens> & {
     base?: string;
 });
 /**
@@ -654,6 +682,11 @@ type ThemeInput = string | (Partial<ThemeTokens> & {
  * - an object deep-merges onto a base theme (override.base or override.dark picks it)
  */
 declare function resolveTheme(theme?: ThemeInput): ThemeTokens;
+/**
+ * Resolve a theme reference into concrete tokens plus non-fatal warnings for
+ * invalid color overrides that fell back to the selected base theme.
+ */
+declare function resolveThemeChecked(theme?: ThemeInput): ResolvedTheme;
 
 /**
  * Theme-side support for the hand-drawn ("sketch") style.
@@ -2235,6 +2268,292 @@ declare class CanvasLayer {
     clear(): void;
 }
 
+/**
+ * Canvas painting for chart "overlay" text (axis labels, titles, legends,
+ * annotation labels). In the browser this text lives in a crisp, selectable
+ * HTML overlay; headless (no DOM) there is no overlay, so the very same text is
+ * painted onto the marks canvas with these helpers.
+ *
+ * The geometry is shared: call sites compute one set of positions and either
+ * realise them as absolutely-positioned DOM nodes (browser) or feed them here
+ * (headless). The transform/width vocabulary the DOM path uses
+ * (`translateX(-50%)`, `translateY(-50%)`, `translate(-50%,-50%) rotate(±90deg)`,
+ * box `width` + `align`) maps deterministically onto canvas
+ * `textAlign`/`textBaseline`/rotation, so both paths land the same pixels.
+ */
+interface CanvasPillStyle {
+    background: string;
+    border?: string;
+    radius?: number;
+    padX?: number;
+    padY?: number;
+}
+interface CanvasTextCmd {
+    /** Anchor x (interpreted per `align`). */
+    x: number;
+    /** Anchor y (interpreted per `baseline`). */
+    y: number;
+    text: string;
+    /** CSS font shorthand (authoritative — already encodes size + weight). */
+    font: string;
+    color: string;
+    /** Font pixel size, used to size the optional pill. */
+    size: number;
+    align?: CanvasTextAlign;
+    baseline?: CanvasTextBaseline;
+    /** Rotation about (x, y), in radians. */
+    rotate?: number;
+    opacity?: number;
+    /** Draw a rounded "pill"/badge behind the text (solid fill + hairline border). */
+    pill?: CanvasPillStyle;
+}
+/** Paint a single text command onto a 2D context. Self-contained (save/restore). */
+declare function paintCanvasText(ctx: CanvasRenderingContext2D, c: CanvasTextCmd): void;
+/** Option shape shared by the DOM text helpers (axes + chrome). */
+interface OverlayTextOpts {
+    left: number;
+    top: number;
+    width?: number;
+    text: string;
+    color: string;
+    size: number;
+    align?: 'left' | 'center' | 'right';
+    transform?: string;
+    opacity?: number;
+    pill?: CanvasPillStyle;
+}
+/**
+ * Translate an absolutely-positioned overlay text node (left/top/width/align +
+ * a CSS `transform` from the known vocabulary) into the equivalent canvas
+ * command. Keeps the headless output pixel-aligned with the browser overlay.
+ */
+declare function overlayTextToCanvasCmd(o: OverlayTextOpts, font: string): CanvasTextCmd;
+type LegendSymbol = 'square' | 'circle' | 'line';
+/** Total horizontal footprint of a legend swatch (square/circle = 11, line = 14). */
+declare function legendSwatchWidth(symbol: LegendSymbol | undefined, swatch?: number): number;
+/**
+ * Paint a legend swatch onto canvas, vertically centered on `midY`. Mirrors the
+ * DOM swatch (square/circle 11px, line 14×3px).
+ */
+declare function paintLegendSwatch(ctx: CanvasRenderingContext2D, x: number, midY: number, symbol: LegendSymbol | undefined, color: string, swatch?: number): void;
+
+/**
+ * Label ledger — a record of every text label a chart actually drew.
+ *
+ * Both text chokepoints push here as they render: `axes/draw.ts` for cartesian
+ * charts and `charts/chrome.ts` for every other visual. That gives the render
+ * report one chart-type-agnostic source of truth for text diagnostics — a pie's
+ * callouts, a sankey's node names and a bar chart's tick labels all land in the
+ * same ledger — so clipping and collision checks work everywhere instead of only
+ * where a `CartesianModel` happens to exist.
+ */
+
+/** What a recorded label is for, so diagnostics can name it meaningfully. */
+type LabelRole = 'axis-label' | 'axis-title' | 'title' | 'subtitle' | 'legend' | 'data-label' | 'annotation' | 'other';
+/** One label as drawn, with the box it occupies and the budget it was given. */
+interface LabelRecord {
+    role: LabelRole;
+    /** The string actually painted (already shortened when it did not fit). */
+    text: string;
+    /** The full string before any truncation. */
+    fullText: string;
+    /** True when `text` had to be shortened to fit `budget`. */
+    truncated: boolean;
+    /** Axis-aligned bounding box in CSS pixels, relative to the surface. */
+    box: Rect;
+    /** Rotation in degrees; 0 for upright text. */
+    angle: number;
+    /** Font pixel size — the box includes line-box leading, this is the ink height. */
+    size: number;
+    /** The width the caller allowed, when it declared one. */
+    budget?: number;
+    /** The axis a tick label belongs to. */
+    axis?: 'x' | 'y';
+    color?: string;
+    opacity?: number;
+    /** Known background behind this label, not a guessed universal theme token. */
+    background?: string;
+    /** JSON Pointer into the effective spec, when the label has a config origin. */
+    path?: string;
+    clip?: Rect;
+}
+interface SuppressedLabel {
+    role: LabelRole;
+    reason: 'space' | 'collision' | 'unreadable' | 'static-viewport' | 'frame';
+    /** Identifying text (axes, category names, titles) versus optional value labels. */
+    required: boolean;
+    count: number;
+    example?: string;
+    axis?: 'x' | 'y';
+    path?: string;
+}
+/** Collects label records for a single render pass. */
+declare class LabelLedger {
+    readonly records: LabelRecord[];
+    readonly suppressed: SuppressedLabel[];
+    add(record: LabelRecord): void;
+    /** One aggregate per reason/role/path, never an allocation for every omitted tick. */
+    omit(record: Omit<SuppressedLabel, 'count'> & {
+        count?: number;
+    }): void;
+    clear(): void;
+    /** Records matching any of `roles`. */
+    byRole(...roles: LabelRole[]): LabelRecord[];
+}
+/**
+ * Record a label when a ledger is present.
+ *
+ * Renderers reach the ledger through a `Surface`, and some callers (headless
+ * targets, unit-test doubles) hand-roll a partial surface object, so the ledger
+ * is treated as best-effort: diagnostics degrade rather than the render failing.
+ */
+declare function recordLabel(ledger: LabelLedger | undefined, record: LabelRecord): void;
+/** Record text painted by a native canvas helper that does not use overlay chrome. */
+declare function recordCanvasLabel(ledger: LabelLedger | undefined, command: CanvasTextCmd, options?: {
+    role?: LabelRole;
+    background?: string;
+    fullText?: string;
+    budget?: number;
+    path?: string;
+    clip?: Rect;
+}): void;
+/**
+ * Snapshot already-mounted DOM text; no retained nodes. Missing DOM layout
+ * (e.g. jsdom) returns false rather than inventing measured text geometry.
+ */
+declare function recordDomLabels(ledger: LabelLedger | undefined, host: HTMLElement, origin: {
+    x: number;
+    y: number;
+}, background?: string, role?: LabelRole, path?: string, scrollViewport?: Rect): boolean;
+/**
+ * Shorten `text` so it fits `budget` pixels, reporting whether it had to be cut.
+ * A missing or non-positive budget means "unconstrained" — the caller had no
+ * room to declare, so the text is left intact rather than blanked.
+ */
+declare function fitLabel(text: string, budget: number | undefined, font: string): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * Resolve an overlay text node's layout into an axis-aligned bounding box.
+ *
+ * Reuses {@link overlayTextToCanvasCmd} so the box lands exactly where the glyphs
+ * do, including the `translateX(-50%)` / `translateY(-50%)` / `rotate(-45deg)`
+ * transform vocabulary the DOM path uses.
+ */
+declare function labelBox(o: OverlayTextOpts, font: string): {
+    box: Rect;
+    angle: number;
+};
+/** True when two boxes overlap by more than `tolerance` pixels on both axes. */
+declare function boxesOverlap(a: Rect, b: Rect, tolerance?: number): boolean;
+/** Test the text rectangles, not just the overlapping envelopes of rotated labels. */
+declare function labelsOverlap(a: LabelRecord, b: LabelRecord, tolerance?: number): boolean;
+
+type EvidenceCoverage = 'complete' | 'partial' | 'none';
+type MarkKind = 'point' | 'line-run' | 'area-region' | 'bar' | 'box' | 'slice' | 'cell' | 'region' | 'node' | 'link' | 'stage' | 'tile' | 'comparison' | 'value' | 'control';
+type DataRepresentation = 'rows' | 'aggregate' | 'derived' | 'literal' | 'control' | 'unknown';
+interface LogicalMarkCount {
+    drawn: number;
+    visible: number;
+}
+/** An actually painted perimeter that keeps a pale filled mark identifiable. */
+interface MarkBoundary {
+    color: string;
+    opacity: number;
+    width: number;
+}
+/** A bounded sample of actual primary mark paints, not theme palette guesses. */
+interface PaintEvidence {
+    color: string;
+    opacity: number;
+    /** Supplied nominal backdrop; not a pixel-level analysis of overlapping marks. */
+    background?: string;
+    count: number;
+    /** Intentional cross-highlight dimming is recorded, but not a contrast defect. */
+    intentionalDim?: boolean;
+    boundary?: MarkBoundary;
+}
+/**
+ * Lightweight facts from a draw pass. Logical marks are not canvas paint calls:
+ * a box/whisker is one box, a pie category one slice, and a line one finite run.
+ * Points additionally painted on a line count separately; `segments` counts its
+ * adjacent finite observations, not curve tessellation. An area band includes its
+ * boundary stroke; a line's optional fill is decoration, not an extra mark.
+ * A table counts mounted/painted body cells, not rows; a matrix counts resolved
+ * aggregate measure cells (not row headers or missing-value placeholders). Value cards count
+ * one resolved primary value (including a zero readout); dropdown/search/range
+ * count one composite control and lists count their mounted/painted options.
+ * Axes, legends, annotations and trendline decorations are not data marks.
+ *
+ * `visible` means finite positive primitive bounds intersect the renderer's clip
+ * at nonzero opacity. It does not promise unoccluded pixels or distinguishability.
+ * Counts describe the final static pass, not intermediate animation frames.
+ */
+interface RenderEvidence {
+    marks: LogicalMarkCount & {
+        byKind: Partial<Record<MarkKind, LogicalMarkCount>>;
+        segments: number;
+    };
+    data: {
+        inputRows: number;
+        representation: DataRepresentation;
+        /** Source rows accounted for, including aggregation; absent if not established. */
+        representedRows?: number;
+        omittedRows?: number;
+        /** Valid observations not individually drawn after draw-side reduction; zero is explicit when established. */
+        reducedRows?: number;
+        /** Rows retained behind an intentional interactive scroll/window, not discarded; zero is explicit when established. */
+        deferredRows?: number;
+    };
+    geometry: {
+        method: 'primitive-bounds';
+        bounds?: Rect;
+        nonFinite: number;
+        clipped: number;
+    };
+    colors: {
+        samples: PaintEvidence[];
+        truncated: boolean;
+    };
+    coverage: {
+        marks: EvidenceCoverage;
+        data: EvidenceCoverage;
+        geometry: EvidenceCoverage;
+        colors: EvidenceCoverage;
+        text: EvidenceCoverage;
+        textContrast: EvidenceCoverage;
+    };
+    labels?: {
+        drawn: number;
+        suppressed: number;
+        requiredSuppressed: number;
+        contrastChecked: number;
+    };
+}
+/** Counters and bounded paint styles only: no retained point/shape scene graph. */
+declare class EvidenceLedger {
+    private value;
+    private paints;
+    private alphas;
+    private boundsOverflow;
+    private viewport;
+    background?: string;
+    reset(size: Size, inputRows?: number, background?: string, clip?: Rect): void;
+    visibleViewport(): Rect;
+    /** Call even on an early empty return, so zero marks is observed, not guessed. */
+    begin(representation?: DataRepresentation): void;
+    /** Only supply source-row accounting when the renderer can establish it. */
+    data(representedRows: number, representation?: DataRepresentation, reducedRows?: number, deferredRows?: number): void;
+    unknownData(representation: DataRepresentation): void;
+    partial(...areas: Array<keyof RenderEvidence['coverage']>): void;
+    /** Record a logical mark at its paint site; positional args avoid per-point objects. */
+    mark(kind: MarkKind, x: number, y: number, width: number, height: number, color?: string, opacity?: number, clip?: Rect, count?: number, background?: string | undefined, intentionalDim?: boolean, boundary?: MarkBoundary): void;
+    segments(count: number): void;
+    private paint;
+    snapshot(): RenderEvidence;
+}
+
 /**
  * A rendering Surface mounted inside a user-provided container. It owns a stack
  * of layers:
@@ -2263,9 +2582,19 @@ declare class Surface {
      * Defaults to false (browser).
      */
     headless: boolean;
+    /**
+     * Every overlay label drawn during the current pass, recorded by the text
+     * helpers in `axes/draw.ts` and `charts/chrome.ts`. The render report reads it
+     * to detect clipped and colliding text for any chart type, cartesian or not.
+     */
+    readonly labels: LabelLedger;
+    /** Logical marks and bounded geometry/paint counters for the current pass. */
+    readonly evidence: EvidenceLedger;
+    /** DOM visuals may refresh measurements after scrolling or an in-place control change. */
+    collectEvidence?: () => void;
     constructor(container: HTMLElement);
     resize(width: number, height: number, dpr?: number): void;
-    /** Clear both canvas layers and empty the HTML overlay. */
+    /** Clear both canvas layers, empty the HTML overlay, and reset the ledger. */
     clear(): void;
     /** Remove all DOM created by this Surface. */
     destroy(): void;
@@ -2485,22 +2814,167 @@ interface RegressionFit {
  */
 declare function linearRegression(xs: readonly number[], ys: readonly number[]): RegressionFit | null;
 
+/** The original, compact column profile contract. */
 interface ColumnProfile {
     field: string;
-    type: 'quantitative' | 'temporal' | 'nominal' | 'ordinal';
+    type: FieldType;
+    /** Distinct existing grouping keys, including the shared null/undefined/"" key. */
     cardinality: number;
 }
+interface NumericEvidence {
+    /** Non-missing values accepted by the existing numeric coercion. */
+    valid: number;
+    /** Non-missing values not accepted by numeric coercion. */
+    invalid: number;
+    numbers: number;
+    numericStrings: number;
+    booleans: number;
+    dates: number;
+    nonFinite: number;
+    negative: number;
+    zero: number;
+    positive: number;
+    range: [number, number] | null;
+}
+interface TemporalEvidence {
+    /** Includes numeric epochs and supported date strings, not just inferred dates. */
+    valid: number;
+    invalid: number;
+    dateObjects: number;
+    strings: number;
+    numericEpochs: number;
+    /** Epoch milliseconds; uses the same local-date parsing as rendering. */
+    range: [number, number] | null;
+}
+type TypeAmbiguity = 'mixed-types' | 'numeric-identifier' | 'numeric-date' | 'date-order' | 'invalid-temporal';
+interface DetailedColumnProfile extends ColumnProfile {
+    /** All counts describe inspected rows, not estimates of uninspected rows. */
+    inspectedRows: number;
+    /** Presence counts keys even when their value is null or undefined. */
+    present: number;
+    absent: number;
+    /** Absent, null, undefined, and blank strings (never numeric zero). */
+    missing: number;
+    /** Non-missing values usable under `type`, or the explicitly requested type. */
+    valid: number;
+    invalid: number;
+    /** Objects/arrays are structural containers, not scalar chart values. */
+    structured: number;
+    expectedType?: FieldType;
+    nonMissingCardinality: number;
+    quantitative: NumericEvidence;
+    temporal: TemporalEvidence;
+    /** Counts are exact, but legacy type inference inspects at most 200 values. */
+    inference: {
+        inspectedValues: number;
+        exact: boolean;
+    };
+    ambiguity: TypeAmbiguity[];
+}
+interface ProfileField {
+    field: string;
+    /** An explicit encoding type affects validity evidence, never inferred `type`. */
+    type?: FieldType;
+}
+interface ProfileEncoding {
+    /** Fields that jointly identify an encoded position, cell, or comparison pair. */
+    keys: readonly (string | ProfileField)[];
+    /** Required values at that position; omitted types use the inferred type. */
+    values?: readonly (string | ProfileField)[];
+    /** Ask about missing combinations of observed keys; never infers a time cadence. */
+    complete?: boolean;
+}
+interface ProfileOptions {
+    /** Defaults to all discovered fields, including nested/dotted paths. */
+    fields?: readonly (string | ProfileField)[];
+    /** Optional deterministic, evenly spaced row sample. Default: inspect all rows. */
+    sampleSize?: number;
+    encoding?: ProfileEncoding;
+}
+interface DataFinding {
+    code: string;
+    severity: 'info' | 'warning';
+    message: string;
+    fields?: string[];
+    count?: number;
+    /** Meaning-affecting choices are disclosed, never applied by profiling. */
+    requiresDecision: boolean;
+}
+interface EncodingProfile {
+    keys: string[];
+    /** Rows with usable key fields, independent of their measure validity. */
+    keyRows: number;
+    /** Distinct observed key combinations, including those with unusable measures. */
+    observedKeys: number;
+    usableRows: number;
+    /** Missing takes precedence over invalid so these row counts are disjoint. */
+    missingRows: number;
+    invalidRows: number;
+    /** Distinct keys with a complete, usable observation. */
+    distinctKeys: number;
+    /** Number of encoded key groups with more than one usable observation. */
+    duplicateKeys: number;
+    /** Additional usable observations beyond the first at each key. */
+    duplicateRows: number;
+    /** Only supplied for exact evidence and an explicit `complete` request. */
+    possibleCombinations?: number;
+    missingCombinations?: number;
+}
+interface DatasetProfile {
+    rowCount: number;
+    invalidRows: number;
+    sampling: {
+        mode: 'exact' | 'sampled';
+        inspectedRows: number;
+        totalRows: number;
+    };
+    columns: DetailedColumnProfile[];
+    encoding?: EncodingProfile;
+    findings: DataFinding[];
+}
+/**
+ * Inspect data without cleaning, grouping, inferring units, or changing types.
+ * Numeric/date evidence uses the same coercions as rendering. Explicit encoding
+ * keys opt into duplicate/completeness evidence; no grid or cadence is invented.
+ */
+declare function profileData(data: readonly Datum[], options?: ProfileOptions): DatasetProfile;
+/** Backward-compatible column list with additive, detailed evidence. */
+declare function profileColumns(data: readonly Datum[], options?: ProfileOptions): DetailedColumnProfile[];
+
+interface RecommendationEvidence {
+    columns: DetailedColumnProfile[];
+    sampling: DatasetProfile['sampling'];
+    encoding?: EncodingProfile;
+    intent?: RecommendOptions['intent'];
+    targetSize?: Size;
+}
 interface RecommendedChart {
     spec: ChartSpec;
     score: number;
     rationale: string;
+    /** A valid candidate can still need an explicit meaning/field decision. */
+    status?: 'ready' | 'needs-decision';
+    findings?: DataFinding[];
+    evidence?: RecommendationEvidence;
+    alternatives?: ChartType[];
 }
 interface RecommendOptions {
     intent?: 'trend' | 'comparison' | 'distribution' | 'relationship' | 'composition';
     maxResults?: number;
+    /** Layout guidance only; no data is filtered or grouped to fit this size. */
+    targetSize?: Size;
 }
-declare function profileColumns(data: Datum[]): ColumnProfile[];
-declare function recommendChart(data: Datum[], opts?: RecommendOptions): RecommendedChart[];
+interface RecommendationResult {
+    recommendations: RecommendedChart[];
+    profile: DatasetProfile;
+    findings: DataFinding[];
+    status: 'ready' | 'needs-decision' | 'no-candidate';
+}
+/** Return ranked valid candidates, without applying any proposed data decisions. */
+declare function recommendChart(data: readonly Datum[], opts: RecommendOptions & {
+    detailed: true;
+}): RecommendationResult;
+declare function recommendChart(data: readonly Datum[], opts?: RecommendOptions): RecommendedChart[];
 
 /** Environment helpers — safe in both browser and Node (SSR/test). */
 declare const isBrowser: boolean;
@@ -2529,80 +3003,14 @@ interface BackingSize {
 declare function computeBackingSize(width: number, height: number, dpr: number): BackingSize;
 
 /** Tiny DOM helpers (browser-only). */
+
+/** Space available to a child, excluding host padding (client dimensions already exclude borders). */
+declare function measureContentSize(el: HTMLElement): Size;
 declare function setStyle(el: HTMLElement, style: Partial<CSSStyleDeclaration>): void;
 declare function createDiv(className?: string, style?: Partial<CSSStyleDeclaration>): HTMLDivElement;
 /** Absolute-position a layer to fill its positioned parent. */
 declare const fillParentStyle: Partial<CSSStyleDeclaration>;
 
-/**
- * Canvas painting for chart "overlay" text (axis labels, titles, legends,
- * annotation labels). In the browser this text lives in a crisp, selectable
- * HTML overlay; headless (no DOM) there is no overlay, so the very same text is
- * painted onto the marks canvas with these helpers.
- *
- * The geometry is shared: call sites compute one set of positions and either
- * realise them as absolutely-positioned DOM nodes (browser) or feed them here
- * (headless). The transform/width vocabulary the DOM path uses
- * (`translateX(-50%)`, `translateY(-50%)`, `translate(-50%,-50%) rotate(±90deg)`,
- * box `width` + `align`) maps deterministically onto canvas
- * `textAlign`/`textBaseline`/rotation, so both paths land the same pixels.
- */
-interface CanvasPillStyle {
-    background: string;
-    border?: string;
-    radius?: number;
-    padX?: number;
-    padY?: number;
-}
-interface CanvasTextCmd {
-    /** Anchor x (interpreted per `align`). */
-    x: number;
-    /** Anchor y (interpreted per `baseline`). */
-    y: number;
-    text: string;
-    /** CSS font shorthand (authoritative — already encodes size + weight). */
-    font: string;
-    color: string;
-    /** Font pixel size, used to size the optional pill. */
-    size: number;
-    align?: CanvasTextAlign;
-    baseline?: CanvasTextBaseline;
-    /** Rotation about (x, y), in radians. */
-    rotate?: number;
-    opacity?: number;
-    /** Draw a rounded "pill"/badge behind the text (solid fill + hairline border). */
-    pill?: CanvasPillStyle;
-}
-/** Paint a single text command onto a 2D context. Self-contained (save/restore). */
-declare function paintCanvasText(ctx: CanvasRenderingContext2D, c: CanvasTextCmd): void;
-/** Option shape shared by the DOM text helpers (axes + chrome). */
-interface OverlayTextOpts {
-    left: number;
-    top: number;
-    width?: number;
-    text: string;
-    color: string;
-    size: number;
-    align?: 'left' | 'center' | 'right';
-    transform?: string;
-    opacity?: number;
-    pill?: CanvasPillStyle;
-}
-/**
- * Translate an absolutely-positioned overlay text node (left/top/width/align +
- * a CSS `transform` from the known vocabulary) into the equivalent canvas
- * command. Keeps the headless output pixel-aligned with the browser overlay.
- */
-declare function overlayTextToCanvasCmd(o: OverlayTextOpts, font: string): CanvasTextCmd;
-type LegendSymbol = 'square' | 'circle' | 'line';
-/** Total horizontal footprint of a legend swatch (square/circle = 11, line = 14). */
-declare function legendSwatchWidth(symbol: LegendSymbol | undefined, swatch?: number): number;
-/**
- * Paint a legend swatch onto canvas, vertically centered on `midY`. Mirrors the
- * DOM swatch (square/circle 11px, line 14×3px).
- */
-declare function paintLegendSwatch(ctx: CanvasRenderingContext2D, x: number, midY: number, symbol: LegendSymbol | undefined, color: string, swatch?: number): void;
-
 /**
  * Text measurement using a shared offscreen canvas context. Falls back to a
  * rough heuristic when no canvas is available (SSR/test). In a non-DOM
@@ -2855,6 +3263,16 @@ interface ValidationError {
         kind: 'chartType' | 'enum' | 'field' | 'channel';
         candidates: string[];
     };
+    /** A data/meaning choice, rather than a safe automatic correction. */
+    requiresDecision?: boolean;
+    /** Exact, inspected field counts for data-quality findings. */
+    evidence?: {
+        inspectedRows: number;
+        present: number;
+        missing: number;
+        valid: number;
+        invalid: number;
+    };
 }
 interface ValidationResult {
     valid: boolean;
@@ -2907,11 +3325,30 @@ declare function lintSpec(spec: ChartSpec): LintFinding[];
  * the right correction is unclear, the error is left for the agent to resolve.
  */
 
+/** How aggressively {@link repairSpec} may infer missing or misspelled parts. */
+interface RepairOptions {
+    /**
+     * Repair level. `'safe'` preserves the historical behavior and only applies
+     * validator-provided fixes; `'data'` may additionally infer unambiguous fixes
+     * from the spec's own data array.
+     */
+    level?: 'safe' | 'data';
+}
+/** A patch operation plus the human-readable reason it was considered safe. */
+interface AppliedRepair {
+    /** The JSON Patch operation that was applied. */
+    op: JsonPatchOp;
+    /** Short explanation of why this repair was applied. */
+    rationale: string;
+}
+/** Result returned by {@link repairSpec}. */
 interface RepairResult {
     /** The (possibly) corrected spec — a new object; the input is never mutated. */
     spec: unknown;
     /** Patch operations that were applied, in order. Empty when nothing changed. */
     applied: JsonPatchOp[];
+    /** Applied patch operations paired with their repair rationales. */
+    appliedDetails: AppliedRepair[];
     /**
      * Structural errors that remain after repair. `remaining.length === 0` means
      * the repaired spec is valid. Advisory lint warnings are not counted here.
@@ -2924,7 +3361,7 @@ interface RepairResult {
  * correcting the chart `type` changes which channels are required). Pure: the
  * input spec is deep-cloned before any patch is applied.
  */
-declare function repairSpec(spec: unknown): RepairResult;
+declare function repairSpec(spec: unknown, options?: RepairOptions): RepairResult;
 
 /**
  * Resolve a spec's `sketch` option into concrete, fully-defaulted knobs for the
@@ -2947,6 +3384,67 @@ interface ResolvedSketch extends RoughStyle {
  */
 declare function resolveSketch(spec: ChartSpec): ResolvedSketch | null;
 
+interface FieldRoleInfo {
+    /** Spec path, including [] for repeated definitions. */
+    path: string;
+    role: 'position' | 'measure' | 'category' | 'series' | 'size' | 'time' | 'target' | 'geography' | 'filter' | 'text';
+    types: FieldType[];
+    required: boolean;
+}
+interface DataRequirement {
+    code: string;
+    fields: string[];
+    description: string;
+}
+interface CardinalityGuidance {
+    fields: string[];
+    minimum?: number;
+    maximum?: number;
+    recommendedMaximum?: number;
+    unique?: boolean;
+    description: string;
+}
+interface AggregationCapability {
+    mode: 'rows' | 'aggregate' | 'bin' | 'distribution' | 'value' | 'pivot' | 'lookup' | 'filter-domain' | 'running-total';
+    by: string[];
+    defaultOp?: string;
+    /** Spec path controlling the operation, only when the renderer consumes it. */
+    operationPath?: string;
+    caveats: string[];
+}
+interface ChartCapabilities {
+    fieldRoles: FieldRoleInfo[];
+    requirements: DataRequirement[];
+    cardinality: CardinalityGuidance[];
+    aggregation: AggregationCapability;
+    features: string[];
+}
+/** Agent-facing metadata for one chart family and its starter template. */
+interface ChartTypeInfo {
+    /** The chart type string accepted by {@link starterSpec}. */
+    type: ChartType;
+    /** A one-line description of when to use this chart type. */
+    purpose: string;
+    /** Required channels, fields, or top-level properties needed for validity. */
+    requiredChannels: string[];
+    /** A minimal valid starter spec for this chart type. */
+    example: ChartSpec;
+    /** Additive machine-readable authoring guidance, populated by listChartTypes. */
+    capabilities?: ChartCapabilities;
+}
+/**
+ * Return a minimal valid starter spec for a chart type, including placeholder
+ * inline data whose fields match the spec's encodings and field references.
+ */
+declare function starterSpec(type: ChartType): ChartSpec;
+/**
+ * List every registered chart/slicer type, machine-readable data requirements
+ * and capabilities, and a ready-to-render starter. Guidance never transforms data.
+ */
+declare function listChartTypes(): (ChartTypeInfo & {
+    capabilities: ChartCapabilities;
+})[];
+
 /**
  * Number formatting — a pragmatic subset of the d3-format mini-language, enough
  * for agent-authored specs without a runtime dependency.
@@ -2970,6 +3468,8 @@ interface NumberFormatSpec {
     precision?: number;
     type?: 'f' | '%' | 's' | 'd' | 'e' | 'g' | '';
 }
+/** Whether a hint uses the supported numeric mini-language rather than date tokens. */
+declare function isNumberFormat(spec: string): boolean;
 declare function parseNumberFormat(spec: string): NumberFormatSpec;
 /** Format a number according to a parsed or string spec. */
 declare function formatNumber(value: number, spec?: string | NumberFormatSpec): string;
@@ -2999,6 +3499,8 @@ declare function prettyDate(value: Date | number): string;
  * strings. When a `%` (date) hint is supplied for such a string we parse it and
  * format as a date, so e.g. a table column `{ format: '%b %e, %Y' }` over
  * `"2024-05-02"` renders `May 2, 2024` rather than the raw string.
+ * An explicit numeric hint also formats numeric strings; without a hint strings
+ * stay intact, including identifiers with leading zeros.
  */
 declare function formatValue(value: unknown, hint?: string): string;
 /**
@@ -3073,7 +3575,15 @@ interface FrameInput {
     yAxis?: AxisInput;
     /** Secondary (right) y-axis for dual-axis combo charts; reserves a right gutter. */
     y2Axis?: AxisInput;
-}
+    /** Internal caption spacing for small-multiple panels; normal charts use density defaults. */
+    titleGap?: number;
+    /** Minimum mark extent before dropping chrome; compact sparklines may use less than 24px. */
+    minimumPlotSize?: number;
+}
+/** Resolved chrome density, derived only from the available layout size. */
+type FrameDensity = 'comfortable' | 'compact';
+/** Chrome rungs removed to keep a viable mark area in very small containers. */
+type DroppedChrome = 'subtitle' | 'axis-titles' | 'legend' | 'title';
 interface Frame {
     width: number;
     height: number;
@@ -3088,6 +3598,36 @@ interface Frame {
     legendPosition?: LegendPosition;
     /** Resolved x tick-label rotation in degrees (0 = horizontal). */
     xLabelAngle: number;
+    /**
+     * Pixel budget one x tick label may occupy along its own text direction.
+     * Rotated labels are capped so long names can't swallow the plot; renderers
+     * ellipsize to this rather than overflowing the reserved band.
+     */
+    xLabelMaxWidth: number;
+    /** Pixel budget for a left-gutter tick label, capped so one outlier value
+     * can't consume the plot. Renderers ellipsize to it. */
+    yLabelMaxWidth: number;
+    /** Matching text budget for a secondary right-hand value axis. */
+    y2LabelMaxWidth?: number;
+    /** Legend items that did not fit and were dropped from {@link legendItems}. */
+    legendOverflow: number;
+    /** Where to draw the "+N more" chip, when {@link legendOverflow} is non-zero. */
+    legendOverflowRect?: Rect;
+    /** Pixel budget for a legend label, capped so long series names can't consume
+     * the plot. Renderers ellipsize to it. */
+    legendLabelMaxWidth: number;
+    /**
+     * Layout density derived from the available plot budget. `comfortable` is the
+     * normal chrome used at dashboard/card sizes; `compact` marks small containers
+     * so renderers can switch to their compact font/spacing ramp. It is never
+     * spec-controlled.
+     */
+    density: FrameDensity;
+    /**
+     * Chrome rungs omitted, in priority order, so the mark area remains viable.
+     * Dropped regions are not reserved in the frame.
+     */
+    dropped: DroppedChrome[];
 }
 declare const TICK_SIZE = 6;
 /**
@@ -3098,6 +3638,8 @@ declare const TICK_SIZE = 6;
  * `spec.padding` over it (`{ ...NO_PADDING, ...spec.padding }`) to allow overrides.
  */
 declare const NO_PADDING: Insets;
+/** A plot must keep at least this many pixels on each side to render marks. */
+declare const MIN_VIABLE_PLOT_SIZE = 24;
 /** Reserve space for every region and return the plot rect + positioned chrome. */
 declare function computeFrame(input: FrameInput): Frame;
 
@@ -3262,6 +3804,8 @@ interface CartesianModel {
     xTicks: Tick[];
     yTicks: Tick[];
     colorOf(key: string): string;
+    /** Stable first-seen series keys used for palette assignment. */
+    colorDomain?: string[];
     /** Hand-drawn render settings, or null for the default clean rendering. */
     sketch: ResolvedSketch | null;
     /**
@@ -3285,6 +3829,8 @@ interface CartesianModel {
     };
 }
 declare function resolveCurve(curve?: CurveType): Curve;
+/** Retain category color identity without retaining or changing source rows. */
+declare function seriesColorDomain(spec: CartesianChartSpec, previous?: readonly string[]): string[];
 interface BuildOptions {
     width: number;
     height: number;
@@ -3293,6 +3839,11 @@ interface BuildOptions {
     originY?: number;
     /** Shared scale domains/colors, so faceted panels stay directly comparable. */
     shared?: SharedScales;
+    /** Previous/unfiltered series keys; explicit color-channel domains take priority. */
+    colorDomain?: readonly string[];
+    /** Caption/mark budgets for compact small-multiple panels. */
+    titleGap?: number;
+    minimumPlotSize?: number;
 }
 /** Scale state shared across a facet grid so every panel is comparable. */
 interface SharedScales {
@@ -3664,6 +4215,8 @@ interface ComboModel {
     plot: Rect;
     x: XModel;
     xTicks: Tick[];
+    /** Full category names wrapped into bounded horizontal lines, parallel to xTicks. */
+    wrappedXLabels?: string[][];
     left: ComboAxisModel;
     right?: ComboAxisModel;
     layers: ComboLayerModel[];
@@ -3732,6 +4285,7 @@ declare function buildHistogramModel(spec: HistogramSpec, tokens: ThemeTokens, o
  */
 
 type ReportSeverity = 'error' | 'warning' | 'info';
+
 /** One machine-readable finding about the rendered chart. */
 interface RenderDiagnostic {
     /** Stable identifier an agent can match/suppress on (e.g. `axis-label-overlap`). */
@@ -3747,6 +4301,15 @@ interface RenderDiagnostic {
     fix?: JsonPatchOp[];
     /** One-line advisory when there is no unambiguous safe patch. */
     hint?: string;
+    /** JSON Pointer into the effective spec (dashboard findings are view-scoped). */
+    path?: string;
+    viewId?: string;
+    /** Eligibility guidance only; fixes are never automatically applied by reporting. */
+    action?: {
+        kind: 'presentation' | 'semantic';
+        safety: 'default-only' | 'requires-review';
+        paths: string[];
+    };
 }
 /** A post-render, vision-free description of what was drawn. */
 interface RenderReport {
@@ -3755,7 +4318,7 @@ interface RenderReport {
     size: Size;
     /** Plot rectangle (cartesian-derived reports only). */
     plot?: Rect;
-    /** Number of data marks the chart drew. */
+    /** Legacy bound-row count (or effective data.length); NOT evidence of drawing. */
     markCount: number;
     /** Number of distinct series. */
     seriesCount: number;
@@ -3770,7 +4333,22 @@ interface RenderReport {
      * an LLM). Absent for chart types that carry no summarizable trend.
      */
     summary?: string;
+    /** Observed logical marks and explicit diagnostic coverage, when available. */
+    evidence?: RenderEvidence;
+    /** Child reports retain their own sizes, evidence and local diagnostic paths. */
+    views?: Array<{
+        id: string;
+        index: number;
+        report: RenderReport;
+    }>;
+}
+/** A dashboard has the same facts as a chart report, with its own discriminant. */
+interface DashboardRenderReport extends Omit<RenderReport, 'type' | 'views'> {
+    type: 'dashboard';
+    views: NonNullable<RenderReport['views']>;
 }
+/** Common report type for APIs that accept either a chart or a dashboard. */
+type AnyRenderReport = RenderReport | DashboardRenderReport;
 /** Inputs for {@link buildRenderReport}. */
 interface ReportInput {
     type: ChartType;
@@ -3781,12 +4359,34 @@ interface ReportInput {
     size: Size;
     /** The resolved cartesian model, when the chart type is cartesian. */
     model?: CartesianModel;
+    /**
+     * Every label the chart drew, from the surface's label ledger. Supplying it
+     * enables the text diagnostics (clipping, collision, occlusion) for *any*
+     * chart type, including the non-cartesian ones that have no model.
+     */
+    labels?: LabelRecord[];
+    suppressedLabels?: SuppressedLabel[];
+    evidence?: RenderEvidence;
 }
 /**
  * Build the render report for a freshly-drawn chart. Pure: it reads the
  * resolved model + theme, never the canvas bitmap.
  */
 declare function buildRenderReport(input: ReportInput): RenderReport;
+/** Scope child pointers/patches to their original view index, never display order. */
+declare function scopeViewDiagnostic(diagnostic: RenderDiagnostic, id: string, index: number, type: string): RenderDiagnostic;
+/** Add counters, but do not conflate repeated row participation across views with unique source rows. */
+declare function mergeRenderEvidence(items: readonly RenderEvidence[], inputRows?: number): RenderEvidence;
+/** Browser and headless dashboard reports use identical aggregation and patch scoping. */
+declare function aggregateDashboardReports(input: {
+    spec: DashboardSpec;
+    size: Size;
+    views: NonNullable<RenderReport['views']>;
+    labels?: LabelRecord[];
+    suppressedLabels?: SuppressedLabel[];
+    chromeMeasured?: boolean;
+    diagnostics?: RenderDiagnostic[];
+}): DashboardRenderReport;
 /** Apply safe render-report JSON Patch fixes to a clone of the spec. Pure: no rendering. */
 declare function repairReport(spec: ChartSpec, report: RenderReport): {
     spec: ChartSpec;
@@ -3816,6 +4416,8 @@ declare const FACETABLE_TYPES: ReadonlySet<string>;
 interface FacetPanel {
     value: string;
     model: CartesianModel;
+    report?: RenderReport;
+    compactAxes?: Array<'x' | 'y'>;
 }
 /** The resolved layout of a faceted chart — the header frame plus panel models. */
 interface FacetLayout {
@@ -3827,8 +4429,12 @@ interface FacetLayout {
     panels: FacetPanel[];
     /** Positioned shared legend items (multi-series only). */
     legendItems?: PositionedLegendItem[];
+    legendCount?: number;
     /** A representative panel model (panels[0]) for token/legend draw. */
     repModel: CartesianModel;
+    labels?: LabelRecord[];
+    suppressedLabels?: SuppressedLabel[];
+    evidence?: RenderEvidence;
 }
 /** True when `spec` declares a usable facet on a facet-eligible cartesian type. */
 declare function isFaceted(spec: ChartSpec): boolean;
@@ -3836,8 +4442,9 @@ declare function isFaceted(spec: ChartSpec): boolean;
  * Resolve a faceted spec into a grid of panel models sharing one set of scales.
  * Returns `null` when there is nothing to facet (no rows / no distinct values),
  * so the caller can fall back to the normal single-chart path.
+ * Retained/unfiltered color keys seed the reference model's shared color map.
  */
-declare function buildFacetModels(spec: ChartSpec, tokens: ThemeTokens, size: Size): FacetLayout | null;
+declare function buildFacetModels(spec: ChartSpec, tokens: ThemeTokens, size: Size, colorDomain?: readonly string[]): FacetLayout | null;
 /**
  * Draw a faceted chart onto `surface`: the shared header (overall title + legend)
  * then every panel through the full cartesian pipeline. Static — no interaction
@@ -3876,6 +4483,12 @@ interface HeadlessTarget {
     width: number;
     /** Logical (CSS-pixel) height to draw at. */
     height: number;
+    /** Visible clip already applied by a composing caller, in this target's coordinates. */
+    clip?: Rect;
+    /** Shared selection state for composed static views; absent means a private store. */
+    store?: SelectionStore;
+    /** The composing host already provides card chrome (same convention as render options). */
+    frame?: boolean;
 }
 /**
  * Paint `spec` onto `target.marks` (in CSS pixels — the caller sets up any
@@ -3887,7 +4500,9 @@ interface HeadlessTarget {
  * DOM-only) kpi, table, matrix, slicers and dashboard, which now paint a static
  * canvas snapshot so the whole catalog validates server-side.
  */
+declare function renderToContext(target: HeadlessTarget, spec: DashboardSpec): DashboardRenderReport;
 declare function renderToContext(target: HeadlessTarget, spec: ChartSpec): RenderReport;
+declare function renderToContext(target: HeadlessTarget, spec: ChartSpec | DashboardSpec): AnyRenderReport;
 
 /**
  * Chart runtime: the public `render(container, spec)` entry point.
@@ -3901,6 +4516,11 @@ declare function renderToContext(target: HeadlessTarget, spec: ChartSpec): Rende
 type SelectionChangeListener = (name: string, value: SelectionValue | null) => void;
 /** Options for {@link render}. */
 interface RenderOptions {
+    /**
+     * Paint final frames without entrance/update animation, preserving spec.animation.
+     * Re-read on every draw so a scoped caller can restore this option after a pass.
+     */
+    synchronous?: boolean;
     /**
      * A shared selection bus. Pass the same store to multiple `render()` calls to
      * link them (cross-highlight / cross-filter). Omit to give the chart its own
@@ -4100,6 +4720,8 @@ declare function wireViews(views: DashboardView[], interactions: 'auto' | 'none'
  */
 
 interface RenderDashboardOptions {
+    /** Forward a dynamically scoped final-frame animation override to every child. */
+    synchronous?: boolean;
     /** Share a bus with charts/dashboards outside this one. */
     store?: SelectionStore;
     /**
@@ -4123,6 +4745,8 @@ interface DashboardInstance {
     readonly store: SelectionStore;
     /** The mounted chart instances, in view order. */
     readonly views: ChartInstance[];
+    /** Aggregate current child diagnostics/evidence, with original view IDs and scoped patches. */
+    report(): DashboardRenderReport;
     getSelection(name?: string): SelectionValue | null | Record<string, SelectionValue | null>;
     setSelection(name: string, value: SelectionValue | null): void;
     clearSelection(name?: string): void;
@@ -4141,6 +4765,8 @@ type DashboardCell = {
     w: number;
     h: number;
     baseCols: number;
+    /** Responsive hidden views do not reserve a grid footprint. */
+    hidden?: boolean;
 };
 type Cell = DashboardCell;
 
@@ -4160,15 +4786,159 @@ declare function defaultSpan(spec: ChartSpec, cols: number): {
 declare function resolveDashboardLayout(layout?: DashboardLayout): ResolvedLayout;
 /** Inherit the dashboard's data/theme/background onto a (wired) view spec. */
 declare function inheritInto(spec: ChartSpec, dash: DashboardSpec, tokens: ThemeTokens, suppressTitle?: boolean): ChartSpec;
-declare function placeViews(views: WiredView[], cols: number, preset: DashboardLayout['preset']): Cell[];
+interface DashboardPlacementOptions {
+    /** Effective responsive columns; defaults to the full-width `cols`. */
+    columns?: number;
+    /** Grid width for per-view responsive rules. Omit to resolve base placement. */
+    width?: number;
+}
+/** Resolve grid positions once for browser and headless, keeping spans distinct from coordinates. */
+declare function placeViews(views: readonly WiredView[], cols: number, preset: DashboardLayout['preset'], options?: DashboardPlacementOptions): Cell[];
 declare function resolveDashboardSections(views: WiredView[], layout: Pick<ResolvedLayout, 'cols' | 'rowHeight' | 'sections'>): SectionPlan[];
 declare function renderDashboard(target: HTMLElement | string, spec: DashboardSpec, options?: RenderDashboardOptions): DashboardInstance;
 
+/** Opt-in presentation improvement. The budget includes initial and rollback renders. */
+interface QualityOptions {
+    /** Hard whole-visual render ceiling; default 3. Mutable targets reserve one rollback pass. */
+    maxPasses?: 1 | 2 | 3;
+}
+type QualityStopReason = 'no-target' | 'invalid-spec' | 'satisfied' | 'no-actions' | 'blocked' | 'no-progress' | 'repeated-spec' | 'pass-limit' | 'candidate-invalid' | 'candidate-failed' | 'candidate-regressed' | 'render-failed' | 'restore-failed';
+/** A proposed presentation change and its disposition, never a data repair. */
+interface QualityAction {
+    diagnostic: string;
+    path?: string;
+    viewId?: string;
+    patches: JsonPatchOp[];
+    reason: string;
+}
+interface QualityIteration {
+    /** One-based actual render attempt, including failed and restoration attempts. */
+    pass: number;
+    phase: 'initial' | 'candidate' | 'restore';
+    outcome: 'selected' | 'rejected' | 'failed';
+    /** Changes attempted in this pass; restoration reapplies the selected spec instead. */
+    patches: JsonPatchOp[];
+    report?: AnyRenderReport;
+    error?: string;
+}
+/** Evidence and decisions from a bounded loop; no claim of visual perfection. */
+interface QualityResult {
+    enabled: true;
+    /** False for invalid input, a missing target, or a failed initial render. */
+    evaluated: boolean;
+    maxPasses: 1 | 2 | 3;
+    renderPasses: number;
+    /** The pass that produced the returned frame/report, absent if rendering failed. */
+    selectedPass?: number;
+    stopReason: QualityStopReason;
+    iterations: QualityIteration[];
+    /** Only actions retained in the selected effective spec. */
+    applied: QualityAction[];
+    /** Blocked, ineffective, invalid, failed, or rolled-back actions, with reasons. */
+    rejected: QualityAction[];
+}
+
+/**
+ * Headless dashboard composition — `renderDashboardToContext`.
+ *
+ * Lays a dashboard's views out on the same responsive grid as the browser
+ * runtime, then paints each view onto one canvas via {@link renderToContext}
+ * translated into its cell. No DOM: the whole page rasterizes to a single PNG
+ * server-side, and the per-view reports fold into one aggregate {@link RenderReport}.
+ */
+
+/** Compose a dashboard spec onto a single canvas context. */
+declare function renderDashboardToContext(target: HeadlessTarget, spec: DashboardSpec): DashboardRenderReport;
+
+/**
+ * One-call agent drafting loop: validate → repair → render/report → summarize.
+ *
+ * `draft()` is the dependency-free core version of the MCP render loop. It can
+ * run without a DOM (validation/repair/summary only), paint into a caller-owned
+ * headless canvas target, or mount into a browser container when one is supplied.
+ */
+
+/** Options for {@link draft}. */
+interface DraftOptions {
+    /**
+     * Auto-apply safe JSON Patch repairs before returning. Defaults to true.
+     * Disable when you need a read-only validation/lint pass over the original
+     * input.
+     */
+    repair?: boolean;
+    /**
+     * How hard repair may try. `'safe'` (the default) applies only the fixes
+     * validation itself proposes; `'data'` additionally infers unambiguous
+     * corrections from the spec's own `data` — a typo'd field name, a missing
+     * `encoding`, a missing `type`. Every inferred change is reported in
+     * {@link DraftResult.repairs} with its rationale, so nothing is silent.
+     */
+    repairLevel?: 'safe' | 'data';
+    /**
+     * Opt in to presentation-default improvement, with at most three whole-visual
+     * render passes including initial and rollback passes. Never changes data or
+     * explicit settings. Omit (or false) to retain the single-render behavior.
+     */
+    quality?: boolean | QualityOptions;
+    /**
+     * Optional headless 2D canvas target. When provided and the repaired spec is
+     * valid, `draft()` paints the chart or dashboard and returns its corresponding
+     * {@link AnyRenderReport}. This path needs no DOM.
+     */
+    target?: HeadlessTarget;
+    /**
+     * Optional browser container or selector. When provided and `target` is
+     * omitted, `draft()` mounts the chart or dashboard and returns its report and
+     * the corresponding instance for lifecycle management.
+     */
+    container?: HTMLElement | string;
+    /** Browser render options forwarded when `container` is used. */
+    renderOptions?: RenderOptions;
+}
+/** Result of a {@link draft} validation/repair/render pass. */
+interface DraftResult<R extends AnyRenderReport = AnyRenderReport> {
+    /** Selected effective spec after optional authoring repairs and presentation defaults. */
+    spec: unknown;
+    /** True when structural validation passed after optional repair. */
+    valid: boolean;
+    /** True when a final rendered frame and matching report are available. */
+    rendered: boolean;
+    /** JSON Patch operations applied by repair, in order. */
+    patches: JsonPatchOp[];
+    /** The same operations paired with a human-readable rationale for each. */
+    repairs: AppliedRepair[];
+    /** Structural validation errors remaining after optional repair. */
+    errors: ValidationError[];
+    /** Advisory validation/lint findings for the returned spec. */
+    warnings: ValidationError[];
+    /** Vision-free render diagnostics, present only when rendering happened. */
+    report?: R;
+    /** Browser chart instance, present only when `container` rendering happened. */
+    instance?: ChartInstance;
+    /** Browser dashboard instance; separate from `instance` to retain its chart-specific type. */
+    dashboardInstance?: DashboardInstance;
+    /** Bounded presentation decisions and pass history; present only when opted in. */
+    quality?: QualityResult;
+    /** Opt-in rendering failure, when no matching final frame/report could be returned. */
+    renderError?: string;
+    /** Deterministic alt-text style summary, when the valid spec is summarizable. */
+    summary?: string;
+}
+/**
+ * Validate a chart spec, apply safe repairs, optionally render it, and return
+ * everything an agent needs for the next iteration. Rendering is skipped when
+ * validation still has errors after repair so invalid specs never reach the
+ * renderer.
+ */
+declare function draft(spec: DashboardSpec, options?: DraftOptions): DraftResult<DashboardRenderReport>;
+declare function draft(spec: ChartSpec, options?: DraftOptions): DraftResult<RenderReport>;
+declare function draft(spec: unknown, options?: DraftOptions): DraftResult;
+
 /**
  * graphein — public entry point.
  *
  * The barrel grows as modules land. Keep exports explicit and tree-shakeable.
  */
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.19.0";
 
-export { type AggOp, type AggregateOp, type AggregateTransform, type AnimateOptions, type AnimationConfig, type AnimationHandle, type Annotation, type AnySpec, type ArcOptions, type AreaOptions, type AreaPoint, type AreaSpec, type AxesConfig, type AxisConfig, type AxisInput, type BackingSize, type BandScale, type BandScaleOptions, type BarSpec, type BaseSlicerSpec, type BaseSpec, type BinLayout, type BinTransform, type BoxSpec, type BuildOptions, type BulletSpec, CARTESIAN_TYPES, CHART_TYPES, type CalculateTransform, type CalendarHeatmapSpec, CanvasLayer, type CanvasPillStyle, type CanvasTextCmd, type CartesianChartSpec, type CartesianInteractionBuilder, type CartesianModel, type CartesianRenderer, type CategoryInsights, type ChartInsights, type ChartInstance, type ChartSpec, type ChartSummary, type ChartType, type ChoroplethSpec, type ColorScale, type ColumnProfile, type ComboAxisModel, type ComboLayer, type ComboLayerModel, type ComboMark, type ComboModel, type ComboSide, type ComboSpec, type Comparable, type ConditionalFormat, type ContinuousScale, type ControllerSelect, type Curve, type CurveType, type CustomRenderer, DEFAULT_ENTRANCE_DURATION, DEFAULT_ROUGH_STYLE, DEFAULT_UPDATE_DURATION, DIM_ALPHA, type DashboardCell, type DashboardInstance, type DashboardLayout, type DashboardResponsiveSpan, type DashboardSection, type DashboardSpec, type DashboardView, type DateRangeSlicerSpec, type Datum, type DebugConfig, type DebugSection, type DebugViewDeps, type DebugViewResult, type DecimateOptions, type Dimensions, type DropdownSlicerSpec, type DumbbellSpec, type EasingFunction, type Emphasis, type Encoding, type EntranceContext, ExpressionError, type Extent, FACETABLE_TYPES, FUNCTION_NAMES, type FacetConfig, type FacetLayout, type FacetPanel, type FieldDef, type FieldType, type FieldValue, type FillStyle, type FilterClause, type FilterPredicate, type FilterTransform, type FoldTransform, type Frame, type FrameInput, type FunnelSpec, type GaugeSpec, type GeoFeature, type GeoFeatureCollection, type GeoGeometry, type GeoMultiPolygon, type GeoPolygon, type GeoPosition, type GroupedMap, type HachureSegment, type HeadlessTarget, type HeatmapSpec, type HighlightConfig, type HistogramBin, type HistogramBinDatum, type HistogramModel, type HistogramSpec, type Hover, type IconRule, type Insets, type InsightFamily, type InsightOptions, type Inspector, type InspectorOptions, InteractionController, type InteractionLink, type InteractionModel, type Interpolator, type JsonPatchOp, type KpiComparison, type KpiSpec, type LegendConfig, type LegendHitRegion, type LegendItem, type LegendPosition, type LegendSymbol, type LineOptions, type LineSpec, type LinearScaleOptions, type LintFinding, type ListSlicerSpec, type LiteralPredicate, type LogScaleOptions, type MapProjection, type MarkOptions, type MatrixSpec, type MatrixValueDef, NO_PADDING, type NumberFormatSpec, type OKLCH, type OKLab, type OverlayTextOpts, type PathSink, type PieLabels, type PieSpec, type PivotCell, type PivotFlatRow, type PivotHeaderNode, type PivotOptions, type PivotResult, type PivotValueDef, type Point, type PointRef, type PointScale, type PointScaleOptions, type PointSelection, type PositionedLegendItem, type RGBA, type RangeSelection, type RangeSlicerSpec, type RecommendOptions, type RecommendedChart, type Rect, type RegressionFit, type RenderContext, type RenderDashboardOptions, type RenderDiagnostic, type RenderOptions, type RenderReport, type RepairResult, type ReportInput, type ReportSeverity, type ResolvedEntrance, type ResolvedSeries, type ResolvedSketch, type Rng, type RoughContext, RoughPen, type RoughStyle, SKETCH_FONT_FAMILY, SKETCH_FONT_NAME, SLICER_TYPES, SPEC_ATTR, SR_ONLY_STYLE, type SankeySpec, type ScaleConfig, type ScaleType, type ScatterInsights, type ScatterSpec, type SearchSlicerSpec, type SelectConfig, type SelectionChangeListener, type SelectionDef, type SelectionListener, type SelectionParam, type SelectionStore, type SelectionValue, type SeriesInsights, type SetSelection, type SharedScales, type Size, type SketchConfig, type SlicerSpec, type SlicerType, type SlopeSpec, Surface, TICK_SIZE, TIME_UNITS, TRANSFORM_KINDS, TYPE_ATTR, type TableColumn, type TableSpec, type TextMetricsLite, type TextSelection, type ThemeColors, type ThemeFont, type ThemeInput, type ThemeTokens, type Tick, type TimeScaleOptions, type TimeUnit, type TimeUnitTransform, type TitleConfig, type TitleInput, Tooltip, type TooltipConfig, type TooltipContent, type TooltipRow, type Transform, type TreemapSpec, type TrendlineConfig, type UpdateContext, VERSION, type ValidationError, type ValidationResult, type ValueInsights, type ValueRef, type ValueRule, type WaterfallSpec, type WiredView, type XKind, type XModel, type YModel, aggregateValues, analyzeChart, animate, applyA11y, applyAggregate, applyBin, applyCalculate, applyFilter, applyFold, applyPatch, applyPick, applyTimeUnit, applyTransform, applyTransforms, arc, area, assertValidSpec, autoInsightAnnotations, backOut, bandScale, bounceOut, buildCartesianInteraction, buildCartesianModel, buildComboModel, buildDataTableFallback, buildFacetModels, buildHistogramModel, buildRenderReport, cartesianInteractionBuilders, cartesianRenderers, categorical, categoricalSchemes, chartTitleText, chartTypeLabel, checkExpression, clamp01, clamp255, compileExpression, compilePredicate, computeBackingSize, computeBins, computeFrame, computeSeriesInsights, contrastRatio, createDiv, createInspector, createRoughPen, createSelectionStore, cubicIn, cubicInOut, cubicOut, curveCatmullRom, curveLinear, curveMonotoneX, curveStep, curveStepAfter, curveStepBefore, customRenderers, darkTheme, decimate, defaultSpan, dependentParams, diverging, divergingColorScale, divergingSchemes, drawAnnotationLabels, drawAnnotations, drawAxesUnderlay, drawDebugCanvas, drawFacet, drawLegend, drawOverlay, drawTitle, drawTrendlineLabels, drawTrendlines, easings, elasticOut, ellipsize, ensureSketchFont, expoInOut, expoOut, facetReport, fillParentStyle, filterRows, fontString, formatCountUp, formatDate, formatNumber, formatValue, getDevicePixelRatio, groupBy, hashString, inferFieldType, inferFieldTypes, inferValueType, inheritInto, interpolateArray, interpolateNumber, interpolateNumberArray, interpolateObject, interpolateOklab, interpolateRgb, isBrowser, isEmptyValue, isFaceted, isParamClause, isSlicerType, keyFields, legendSwatchWidth, lightTheme, line, linear, linearRegression, linearScale, linearToSrgb, lintSpec, literalToValue, logScale, lttbRun, makeMatcher, matchesValue, measureText, monotoneXTangents, mulberry32, niceDomain, oklabToOklch, oklabToRgb, oklchToOklab, ordinalColorScale, overlayTextToCanvasCmd, paintCanvasText, paintLegendSwatch, parseColor, parseNumberFormat, pivot, placeViews, pointScale, polygonHachureLines, prefersReducedMotion, prettyDate, profileColumns, quadIn, quadInOut, quadOut, rampFromStops, readableTextColor, recommendChart, relativeLuminance, render, renderDashboard, renderDebugView, renderToContext, repairReport, repairSpec, resolveCurve, resolveDashboardLayout, resolveDashboardSections, resolveEmphasis, resolveEntrance, resolveFilterValues, resolveInsightOptions, resolveSketch, resolveTheme, resolveUpdate, resolveValueRef, rgbToOklab, rgbaToCss, rotatePoint, roundedRect, sampleArc, sequential, sequentialColorScale, sequentialSchemes, serializeSpec, setMeasureContext, setStyle, sinInOut, slicerParamName, smartDate, specFields, srgbToLinear, stripData, summarize, summarizeChart, themes, tickIncrement, tickStep, ticks, timeScale, timeTickFormat, timeTicks, toHex, toPointer, tooltipEnabled, truncateTo, validateDashboard, validateSpec, wireViews, withAlpha, withSketchFont };
+export { type AggOp, type AggregateOp, type AggregateTransform, type AggregationCapability, type AnimateOptions, type AnimationConfig, type AnimationHandle, type Annotation, type AnyRenderReport, type AnySpec, type AppliedRepair, type ArcOptions, type AreaOptions, type AreaPoint, type AreaSpec, type AxesConfig, type AxisConfig, type AxisInput, type BackingSize, type BandScale, type BandScaleOptions, type BarSpec, type BaseSlicerSpec, type BaseSpec, type BinLayout, type BinTransform, type BoxSpec, type BuildOptions, type BulletSpec, CARTESIAN_TYPES, CHART_TYPES, type CalculateTransform, type CalendarHeatmapSpec, CanvasLayer, type CanvasPillStyle, type CanvasTextCmd, type CardinalityGuidance, type CartesianChartSpec, type CartesianInteractionBuilder, type CartesianModel, type CartesianRenderer, type CategoryInsights, type ChartCapabilities, type ChartInsights, type ChartInstance, type ChartSpec, type ChartSummary, type ChartType, type ChartTypeInfo, type ChoroplethSpec, type ColorScale, type ColumnProfile, type ComboAxisModel, type ComboLayer, type ComboLayerModel, type ComboMark, type ComboModel, type ComboSide, type ComboSpec, type Comparable, type ConditionalFormat, type ContinuousScale, type ControllerSelect, type Curve, type CurveType, type CustomRenderer, DEFAULT_ENTRANCE_DURATION, DEFAULT_ROUGH_STYLE, DEFAULT_UPDATE_DURATION, DIM_ALPHA, type DashboardCell, type DashboardInstance, type DashboardLayout, type DashboardPlacementOptions, type DashboardRenderReport, type DashboardResponsiveSpan, type DashboardSection, type DashboardSpec, type DashboardView, type DataFinding, type DataRepresentation, type DataRequirement, type DatasetProfile, type DateRangeSlicerSpec, type Datum, type DebugConfig, type DebugSection, type DebugViewDeps, type DebugViewResult, type DecimateOptions, type DetailedColumnProfile, type Dimensions, type DraftOptions, type DraftResult, type DropdownSlicerSpec, type DroppedChrome, type DumbbellSpec, type EasingFunction, type Emphasis, type Encoding, type EncodingProfile, type EntranceContext, type EvidenceCoverage, ExpressionError, type Extent, FACETABLE_TYPES, FUNCTION_NAMES, type FacetConfig, type FacetLayout, type FacetPanel, type FieldDef, type FieldRoleInfo, type FieldType, type FieldValue, type FillStyle, type FilterClause, type FilterPredicate, type FilterTransform, type FoldTransform, type Frame, type FrameDensity, type FrameInput, type FunnelSpec, type GaugeSpec, type GeoFeature, type GeoFeatureCollection, type GeoGeometry, type GeoMultiPolygon, type GeoPolygon, type GeoPosition, type GroupedMap, type HachureSegment, type HeadlessTarget, type HeatmapSpec, type HighlightConfig, type HistogramBin, type HistogramBinDatum, type HistogramModel, type HistogramSpec, type Hover, type IconRule, type Insets, type InsightFamily, type InsightOptions, type Inspector, type InspectorOptions, InteractionController, type InteractionLink, type InteractionModel, type Interpolator, type JsonPatchOp, type KpiComparison, type KpiSpec, LabelLedger, type LabelRecord, type LabelRole, type LegendConfig, type LegendHitRegion, type LegendItem, type LegendPosition, type LegendSymbol, type LineOptions, type LineSpec, type LinearScaleOptions, type LintFinding, type ListSlicerSpec, type LiteralPredicate, type LogScaleOptions, type LogicalMarkCount, MIN_VIABLE_PLOT_SIZE, type MapProjection, type MarkBoundary, type MarkKind, type MarkOptions, type MatrixSpec, type MatrixValueDef, NO_PADDING, type NumberFormatSpec, type NumericEvidence, type OKLCH, type OKLab, type OverlayTextOpts, type PaintEvidence, type PathSink, type PieLabels, type PieSpec, type PivotCell, type PivotFlatRow, type PivotHeaderNode, type PivotOptions, type PivotResult, type PivotValueDef, type Point, type PointRef, type PointScale, type PointScaleOptions, type PointSelection, type PositionedLegendItem, type ProfileEncoding, type ProfileField, type ProfileOptions, type QualityAction, type QualityIteration, type QualityOptions, type QualityResult, type QualityStopReason, type RGBA, type RangeSelection, type RangeSlicerSpec, type RecommendOptions, type RecommendationEvidence, type RecommendationResult, type RecommendedChart, type Rect, type RegressionFit, type RenderContext, type RenderDashboardOptions, type RenderDiagnostic, type RenderEvidence, type RenderOptions, type RenderReport, type RepairOptions, type RepairResult, type ReportInput, type ReportSeverity, type ResolvedEntrance, type ResolvedSeries, type ResolvedSketch, type ResolvedTheme, type Rng, type RoughContext, RoughPen, type RoughStyle, SKETCH_FONT_FAMILY, SKETCH_FONT_NAME, SLICER_TYPES, SPEC_ATTR, SR_ONLY_STYLE, type SankeySpec, type ScaleConfig, type ScaleType, type ScatterInsights, type ScatterSpec, type SearchSlicerSpec, type SelectConfig, type SelectionChangeListener, type SelectionDef, type SelectionListener, type SelectionParam, type SelectionStore, type SelectionValue, type SeriesInsights, type SetSelection, type SharedScales, type Size, type SketchConfig, type SlicerSpec, type SlicerType, type SlopeSpec, type SuppressedLabel, Surface, TICK_SIZE, TIME_UNITS, TRANSFORM_KINDS, TYPE_ATTR, type TableColumn, type TableSpec, type TemporalEvidence, type TextMetricsLite, type TextSelection, type ThemeColors, type ThemeFont, type ThemeFontSizes, type ThemeFontWeights, type ThemeInput, type ThemeRadii, type ThemeSpacing, type ThemeStrokes, type ThemeTokens, type ThemeWarning, type Tick, type TimeScaleOptions, type TimeUnit, type TimeUnitTransform, type TitleConfig, type TitleInput, Tooltip, type TooltipConfig, type TooltipContent, type TooltipRow, type Transform, type TreemapSpec, type TrendlineConfig, type TypeAmbiguity, type UpdateContext, VERSION, type ValidationError, type ValidationResult, type ValueInsights, type ValueRef, type ValueRule, type WaterfallSpec, type WiredView, type XKind, type XModel, type YModel, adaptPaletteForDarkBackground, aggregateDashboardReports, aggregateValues, analyzeChart, animate, applyA11y, applyAggregate, applyBin, applyCalculate, applyFilter, applyFold, applyPatch, applyPick, applyTimeUnit, applyTransform, applyTransforms, arc, area, assertValidSpec, autoInsightAnnotations, backOut, bandScale, bounceOut, boxesOverlap, buildCartesianInteraction, buildCartesianModel, buildComboModel, buildDataTableFallback, buildFacetModels, buildHistogramModel, buildRenderReport, cartesianInteractionBuilders, cartesianRenderers, categorical, categoricalSchemes, chartTitleText, chartTypeLabel, checkExpression, clamp01, clamp255, compileExpression, compilePredicate, computeBackingSize, computeBins, computeFrame, computeSeriesInsights, contrastRatio, createDiv, createInspector, createRoughPen, createSelectionStore, cubicIn, cubicInOut, cubicOut, curveCatmullRom, curveLinear, curveMonotoneX, curveStep, curveStepAfter, curveStepBefore, customRenderers, darkTheme, decimate, defaultSpan, dependentParams, diverging, divergingColorScale, divergingSchemes, draft, drawAnnotationLabels, drawAnnotations, drawAxesUnderlay, drawDebugCanvas, drawFacet, drawLegend, drawOverlay, drawTitle, drawTrendlineLabels, drawTrendlines, easings, elasticOut, ellipsize, ensureSketchFont, expoInOut, expoOut, facetReport, fillParentStyle, filterRows, fitLabel, fontString, formatCountUp, formatDate, formatNumber, formatValue, getDevicePixelRatio, groupBy, hashString, inferFieldType, inferFieldTypes, inferValueType, inheritInto, interpolateArray, interpolateNumber, interpolateNumberArray, interpolateObject, interpolateOklab, interpolateRgb, isBrowser, isEmptyValue, isFaceted, isNumberFormat, isParamClause, isSlicerType, keyFields, labelBox, labelsOverlap, legendSwatchWidth, lightTheme, line, linear, linearRegression, linearScale, linearToSrgb, lintSpec, listChartTypes, literalToValue, logScale, lttbRun, makeMatcher, matchesValue, measureContentSize, measureText, mergeRenderEvidence, monotoneXTangents, mulberry32, niceDomain, oklabToOklch, oklabToRgb, oklchToOklab, ordinalColorScale, overlayTextToCanvasCmd, paintCanvasText, paintLegendSwatch, parseColor, parseNumberFormat, pivot, placeViews, pointScale, polygonHachureLines, prefersReducedMotion, prettyDate, profileColumns, profileData, quadIn, quadInOut, quadOut, rampFromStops, readableTextColor, recommendChart, recordCanvasLabel, recordDomLabels, recordLabel, relativeLuminance, render, renderDashboard, renderDashboardToContext, renderDebugView, renderToContext, repairReport, repairSpec, resolveCurve, resolveDashboardLayout, resolveDashboardSections, resolveEmphasis, resolveEntrance, resolveFilterValues, resolveInsightOptions, resolveSketch, resolveTheme, resolveThemeChecked, resolveUpdate, resolveValueRef, rgbToOklab, rgbaToCss, rotatePoint, roundedRect, sampleArc, scopeViewDiagnostic, sequential, sequentialColorScale, sequentialSchemes, serializeSpec, seriesColorDomain, setMeasureContext, setStyle, sinInOut, slicerParamName, smartDate, specFields, srgbToLinear, starterSpec, stripData, summarize, summarizeChart, themes, tickIncrement, tickStep, ticks, timeScale, timeTickFormat, timeTicks, toHex, toPointer, tooltipEnabled, truncateTo, validateDashboard, validateSpec, wireViews, withAlpha, withSketchFont };