graphein 0.16.2 → 0.18.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.
@@ -642,6 +647,20 @@ interface ThemeTokens {
         thick: number;
     };
 }
+/** 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>;
@@ -654,6 +673,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.
@@ -1193,6 +1217,19 @@ interface SketchConfig {
     /** Apply the hand-drawn font to titles/labels/axes (default true). */
     font?: boolean;
 }
+/** Individual panels the debug view can render. */
+type DebugSection = 'preview' | 'spec' | 'data' | 'validation' | 'report' | 'summary';
+/**
+ * Debug-view options. Set `debug: true` on any spec to replace the chart with a
+ * diagnostic view, or pass this object to tune it. All fields are plain JSON so
+ * specs still round-trip through `JSON.stringify`. See {@link BaseSpec.debug}.
+ */
+interface DebugConfig {
+    /** Which panels to show, in order. Omit for all of them. */
+    sections?: DebugSection[];
+    /** Max number of data rows to list in the data table (default 50). */
+    rows?: number;
+}
 /** Fields shared by all spec types. */
 interface BaseSpec {
     /** Row-oriented (tidy) data. Required for all charts/tables. */
@@ -1230,6 +1267,17 @@ interface BaseSpec {
      * to tune it. Omit (or `false`) for the default clean rendering.
      */
     sketch?: boolean | SketchConfig;
+    /**
+     * Replace the chart with an interactive **debug view** — a live preview of the
+     * real chart alongside the resolved spec (JSON), a sample of the data (with
+     * inferred column types and row count), validation errors/warnings,
+     * render-report diagnostics, and the plain-English summary. `true` shows every
+     * panel; pass a {@link DebugConfig} to select panels or cap the data sample.
+     * Omit (or `false`) to render normally. The original `type` is preserved, so
+     * clearing the flag restores the chart. Rich HTML view in the browser; headless
+     * PNG export (`@graphein/node`) gets a simple text fallback.
+     */
+    debug?: boolean | DebugConfig;
     /**
      * Named selections this visual publishes. Clicking marks, brushing, or
      * changing a slicer updates the param's value on the shared selection store,
@@ -2211,6 +2259,147 @@ 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';
+}
+/** Collects label records for a single render pass. */
+declare class LabelLedger {
+    readonly records: LabelRecord[];
+    add(record: LabelRecord): 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;
+/**
+ * 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;
+
 /**
  * A rendering Surface mounted inside a user-provided container. It owns a stack
  * of layers:
@@ -2239,9 +2428,15 @@ 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;
     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;
@@ -2510,75 +2705,6 @@ declare function createDiv(className?: string, style?: Partial<CSSStyleDeclarati
 /** 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
@@ -2883,11 +3009,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.
@@ -2900,7 +3045,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
@@ -2923,6 +3068,28 @@ interface ResolvedSketch extends RoughStyle {
  */
 declare function resolveSketch(spec: ChartSpec): ResolvedSketch | null;
 
+/** 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;
+}
+/**
+ * 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 chart type with its purpose, required channels/properties, and a
+ * ready-to-render starter spec.
+ */
+declare function listChartTypes(): ChartTypeInfo[];
+
 /**
  * Number formatting — a pragmatic subset of the d3-format mini-language, enough
  * for agent-authored specs without a runtime dependency.
@@ -3050,6 +3217,10 @@ interface FrameInput {
     /** Secondary (right) y-axis for dual-axis combo charts; reserves a right gutter. */
     y2Axis?: AxisInput;
 }
+/** 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;
@@ -3064,6 +3235,34 @@ 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;
+    /** 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;
 /**
@@ -3074,6 +3273,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;
 
@@ -3757,6 +3958,12 @@ 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[];
 }
 /**
  * Build the render report for a freshly-drawn chart. Pure: it reads the
@@ -3936,6 +4143,49 @@ declare global {
 }
 declare function render(target: HTMLElement | string, spec: ChartSpec, options?: RenderOptions): ChartInstance;
 
+/**
+ * Debug view — renders a spec's *internals* instead of the chart, as a diagnostic
+ * aid. Opt in with `debug: true` (or a {@link DebugConfig}) on any spec.
+ *
+ * This is a runtime concern rather than a leaf chart renderer: it composes
+ * `validateSpec` (spec) + a render report (runtime) + `summarize` (analyze) and,
+ * for the live preview, a *nested* chart render. To avoid an import cycle
+ * (`charts → runtime → charts`), the caller injects the `render` function via
+ * {@link DebugViewDeps.renderPreview}; nothing here imports the runtime entry.
+ *
+ * Two surfaces:
+ *   - Browser: {@link renderDebugView} builds rich HTML panels in `surface.overlay`.
+ *   - Headless (`@graphein/node`): {@link drawDebugCanvas} paints a plain text
+ *     fallback (there is no DOM to host the panels).
+ */
+
+/** Dependencies the browser debug view needs from the runtime (injected to avoid a cycle). */
+interface DebugViewDeps {
+    /**
+     * Mount the *real* chart (the spec with debug turned off) into `host` and return
+     * the instance. The caller supplies the runtime `render`; this module never
+     * imports it, keeping the module graph acyclic.
+     */
+    renderPreview: (host: HTMLElement, spec: ChartSpec) => ChartInstance;
+}
+interface DebugViewResult {
+    /** The mounted live-preview instance, or null when the preview panel is disabled/failed. */
+    preview: ChartInstance | null;
+    /** Report describing the *underlying* chart (from the preview when available). */
+    report: RenderReport;
+}
+/**
+ * Build the browser debug view into `surface.overlay` and mount the live preview.
+ * Returns the preview instance (for lifecycle management by the caller) and the
+ * report describing the underlying chart.
+ */
+declare function renderDebugView(surface: Surface, spec: ChartSpec, tokens: ThemeTokens, size: Size, deps: DebugViewDeps): DebugViewResult;
+/**
+ * Headless fallback: paint a plain-text dump (type, validation summary, and the
+ * pretty spec JSON) onto the canvas. There is no DOM to host the rich panels.
+ */
+declare function drawDebugCanvas(surface: Surface, spec: ChartSpec, tokens: ThemeTokens, size: Size): void;
+
 /**
  * DOM spec publishing — makes a rendered chart identifiable and editable by
  * external tools (agents, devtools extensions, page scripts) straight from the
@@ -4097,11 +4347,81 @@ declare function placeViews(views: WiredView[], cols: number, preset: DashboardL
 declare function resolveDashboardSections(views: WiredView[], layout: Pick<ResolvedLayout, 'cols' | 'rowHeight' | 'sections'>): SectionPlan[];
 declare function renderDashboard(target: HTMLElement | string, spec: DashboardSpec, options?: RenderDashboardOptions): DashboardInstance;
 
+/**
+ * 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';
+    /**
+     * Optional headless 2D canvas target. When provided and the repaired spec is
+     * valid, `draft()` paints to this target via {@link renderToContext} and
+     * returns the resulting {@link RenderReport}. This path needs no DOM.
+     */
+    target?: HeadlessTarget;
+    /**
+     * Optional browser container or selector. When provided and `target` is
+     * omitted, `draft()` mounts the chart with {@link render} and returns
+     * `instance.report()` and the instance itself 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 {
+    /** The original spec or its safely repaired replacement. */
+    spec: unknown;
+    /** True when structural validation passed after optional repair. */
+    valid: boolean;
+    /** True when an optional headless or browser render was attempted. */
+    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?: RenderReport;
+    /** Browser chart instance, present only when `container` rendering happened. */
+    instance?: ChartInstance;
+    /** 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: ChartSpec | 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.18.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 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, 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, 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 AnimateOptions, type AnimationConfig, type AnimationHandle, type Annotation, 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 CartesianChartSpec, type CartesianInteractionBuilder, type CartesianModel, type CartesianRenderer, type CategoryInsights, 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 DashboardResponsiveSpan, type DashboardSection, type DashboardSpec, type DashboardView, type DateRangeSlicerSpec, type Datum, type DebugConfig, type DebugSection, type DebugViewDeps, type DebugViewResult, type DecimateOptions, type Dimensions, type DraftOptions, type DraftResult, type DropdownSlicerSpec, type DroppedChrome, 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 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, MIN_VIABLE_PLOT_SIZE, 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 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, 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 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 UpdateContext, VERSION, type ValidationError, type ValidationResult, type ValueInsights, type ValueRef, type ValueRule, type WaterfallSpec, type WiredView, type XKind, type XModel, type YModel, adaptPaletteForDarkBackground, 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, isParamClause, isSlicerType, keyFields, labelBox, legendSwatchWidth, lightTheme, line, linear, linearRegression, linearScale, linearToSrgb, lintSpec, listChartTypes, 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, recordLabel, relativeLuminance, render, renderDashboard, renderDebugView, renderToContext, repairReport, repairSpec, resolveCurve, resolveDashboardLayout, resolveDashboardSections, resolveEmphasis, resolveEntrance, resolveFilterValues, resolveInsightOptions, resolveSketch, resolveTheme, resolveThemeChecked, resolveUpdate, resolveValueRef, rgbToOklab, rgbaToCss, rotatePoint, roundedRect, sampleArc, sequential, sequentialColorScale, sequentialSchemes, serializeSpec, 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 };