@pixerate/editor 0.46.1 → 0.48.0

package/dist/chart/index.d.cts

@@ -1,301 +1,11 @@
-import { H as HistoryManager } from '../HistoryManager-DeQQMBCj.cjs';
-import { C as CommandSpec } from '../registry-vz6HOiiy.cjs';
+import { C as ChartNumberFormat, a as ChartValue, b as ChartRect, c as ChartScene, d as ChartSpec, e as ChartLayoutOptions, f as ChartWarning, g as ChartAxis, h as ChartLegend, i as ChartType, j as ChartStacking, k as ChartSeries, l as ChartIssue, m as ChartController, n as ChartValueScale, o as ChartSelection, p as ChartSpecPatch } from '../controller-ChjCCMLl.cjs';
+export { q as CHART_AXIS_KINDS, r as CHART_CURVES, s as CHART_LABEL_POSITIONS, t as CHART_LEGEND_POSITIONS, u as CHART_MARKERS, v as CHART_NUMBER_STYLES, w as CHART_ORIENTATIONS, x as CHART_SERIES_TYPES, y as CHART_STACKINGS, z as CHART_TRENDLINE_TYPES, A as CHART_TYPES, B as CHART_TYPE_LABELS, D as CSS_VARIABLE_CHART_THEME, E as ChartActionResult, F as ChartCircleMark, G as ChartControllerOptions, H as ChartCurve, I as ChartDomSpec, J as ChartEditOptions, K as ChartFamily, L as ChartLabelPosition, M as ChartLegendPosition, N as ChartLineMark, O as ChartMark, P as ChartMarkRole, Q as ChartMarker, R as ChartOrientation, S as ChartPathMark, T as ChartRectMark, U as ChartSeriesInput, V as ChartSeriesPatch, W as ChartSeriesType, X as ChartSparklineKind, Y as ChartSparklineOptions, Z as ChartState, _ as ChartSvgOptions, $ as ChartTableData, a0 as ChartTableOptions, a1 as ChartTextMark, a2 as ChartTextMeasure, a3 as ChartTheme, a4 as ChartTrendFit, a5 as ChartTrendline, a6 as ChartTrendlineType, a7 as DEFAULT_CHART_PALETTE, a8 as DEFAULT_CHART_THEME, a9 as chartColorInputValue, aa as chartColorsByCategory, ab as chartDataFromTable, ac as chartDataToTable, ad as chartFamily, ae as chartMovingAverage, af as chartPointColor, ag as chartSceneToDomSpec, ah as chartSceneToSvg, ai as chartSeriesColor, aj as chartSeriesType, ak as chartSliceColor, al as chartSupportsTrendlines, am as chartTextBaseline, an as chartTextTransform, ao as chartToSvg, ap as chartTrendlineName, aq as cloneChartSeries, ar as cloneChartSpec, as as contrastingTextColor, at as createChartController, au as createChartSpec, av as defaultChartAxis, aw as estimateChartTextWidth, ax as fitChartTrendline, ay as isCartesianChart, az as isXyChart, aA as layoutSparkline, aB as normalizeChartAxis, aC as normalizeChartSpec, aD as normalizeChartTrendline, aE as normalizeChartValues, aF as parseChartValue, aG as sameChartSelection, aH as sparklineToSvg, aI as trendNumberText, aJ as uniqueChartSeriesId } from '../controller-ChjCCMLl.cjs';
+import { C as CommandSpec } from '../registry-CaR7LC6W.cjs';
+import { A as AgentToolProvider } from '../registry-B4l-lYts.cjs';
+import '../HistoryManager-DeQQMBCj.cjs';
 import '../types-DsiXGmjo.cjs';
 import '../schema-Di0CS6Pe.cjs';
 
-/** Chart kinds. `bar`, `line`, `area` and `scatter` are cartesian; series may mix them (a combo chart). */
-type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'pie' | 'donut';
-/** How a series is drawn in a cartesian chart. */
-type ChartSeriesType = 'bar' | 'line' | 'area' | 'scatter';
-/** One data value; `null` is a gap (missing value). */
-type ChartValue = number | null;
-interface ChartSeries {
-    /** Stable id (unique within the chart). */
-    id: string;
-    name: string;
-    /** One value per category. */
-    values: ChartValue[];
-    /** CSS colour (default: the palette colour for the series' position). */
-    color?: string;
-    /** Overrides the chart type for this series (cartesian charts only). */
-    type?: ChartSeriesType;
-    /** Hidden series keep their data but are not drawn or scaled. */
-    hidden?: boolean;
-}
-interface ChartNumberFormat {
-    /** `number` (default), `percent` (0.25 → 25%), `currency` or `compact` (1.2K). */
-    style?: 'number' | 'percent' | 'currency' | 'compact';
-    /** Fixed decimals (default: as many as the ticks need, up to 2). */
-    decimals?: number;
-    /** ISO currency code for `currency` (default `USD`). */
-    currency?: string;
-    prefix?: string;
-    suffix?: string;
-}
-interface ChartAxis {
-    /** Draw the axis line, ticks and labels (default `true`). */
-    show: boolean;
-    title: string;
-    /** Fixed lower bound (default: from the data, including 0 for bars and areas). */
-    min: number | null;
-    /** Fixed upper bound (default: from the data). */
-    max: number | null;
-    /** Grid lines at each tick (default: on for the value axis). */
-    gridlines: boolean;
-    /** How tick and data labels are written (value axis only). */
-    format: ChartNumberFormat;
-}
-type ChartLegendPosition = 'top' | 'bottom' | 'left' | 'right';
-interface ChartLegend {
-    show: boolean;
-    position: ChartLegendPosition;
-}
-type ChartStacking = 'none' | 'stacked' | 'percent';
-type ChartOrientation = 'vertical' | 'horizontal';
-type ChartCurve = 'linear' | 'smooth' | 'step';
-/** A whole chart: data plus presentation. Plain JSON, safe to persist. */
-interface ChartSpec {
-    version: 1;
-    type: ChartType;
-    title: string;
-    subtitle: string;
-    /** Category labels (the x axis, or pie slices). */
-    categories: string[];
-    series: ChartSeries[];
-    /** The category axis. */
-    xAxis: ChartAxis;
-    /** The value axis. */
-    yAxis: ChartAxis;
-    legend: ChartLegend;
-    /** Stack bars and areas (`percent` scales each category to 100%). */
-    stacking: ChartStacking;
-    /** `horizontal` draws bars sideways (bar charts only). */
-    orientation: ChartOrientation;
-    /** Line and area interpolation. */
-    curve: ChartCurve;
-    /** Dots on line and area series. */
-    points: boolean;
-    /** Value labels on bars, points and slices. */
-    dataLabels: boolean;
-    /** Series colours in order (cycled). */
-    palette: string[];
-    /** Donut hole as a fraction of the radius (0–0.9). */
-    innerRadius: number;
-}
-/** What a click selects. */
-type ChartSelection = {
-    kind: 'chart';
-} | {
-    kind: 'title';
-} | {
-    kind: 'subtitle';
-} | {
-    kind: 'legend';
-} | {
-    kind: 'axis';
-    axis: 'x' | 'y';
-} | {
-    kind: 'series';
-    seriesId: string;
-} | {
-    kind: 'point';
-    seriesId: string;
-    index: number;
-} | {
-    kind: 'category';
-    index: number;
-};
-/** Colours and type used to lay out a chart. Any CSS colour strings work. */
-interface ChartTheme {
-    /** Fill behind the chart (`transparent` lets the page show through). */
-    background: string;
-    /** The page colour: slice separators and hollow points (set it when `background` is transparent). */
-    surface: string;
-    text: string;
-    mutedText: string;
-    grid: string;
-    axis: string;
-    /** Outline drawn around the selected mark. */
-    selection: string;
-    fontFamily: string;
-    fontSize: number;
-    titleSize: number;
-}
-interface ChartRect {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-/** What a mark is, for styling and tests. */
-type ChartMarkRole = 'background' | 'title' | 'subtitle' | 'grid' | 'axis' | 'tick' | 'tick-label' | 'axis-title' | 'bar' | 'line' | 'area' | 'point' | 'slice' | 'data-label' | 'legend-swatch' | 'legend-label' | 'selection' | 'empty';
-interface ChartMarkBase {
-    /** Unique within the scene (a stable key for frameworks). */
-    key: string;
-    role: ChartMarkRole;
-    /** What clicking this mark selects (none: not clickable). */
-    target?: ChartSelection;
-    /** Mark belongs to the current selection. */
-    selected?: boolean;
-    opacity?: number;
-}
-interface ChartRectMark extends ChartMarkBase {
-    kind: 'rect';
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    fill: string;
-    stroke?: string;
-    strokeWidth?: number;
-    radius?: number;
-}
-interface ChartPathMark extends ChartMarkBase {
-    kind: 'path';
-    d: string;
-    fill?: string;
-    stroke?: string;
-    strokeWidth?: number;
-    dash?: string;
-}
-interface ChartCircleMark extends ChartMarkBase {
-    kind: 'circle';
-    cx: number;
-    cy: number;
-    r: number;
-    fill: string;
-    stroke?: string;
-    strokeWidth?: number;
-}
-interface ChartLineMark extends ChartMarkBase {
-    kind: 'line';
-    x1: number;
-    y1: number;
-    x2: number;
-    y2: number;
-    stroke: string;
-    strokeWidth?: number;
-    dash?: string;
-}
-interface ChartTextMark extends ChartMarkBase {
-    kind: 'text';
-    x: number;
-    y: number;
-    text: string;
-    anchor: 'start' | 'middle' | 'end';
-    /** Vertical alignment of the text box to `y`. */
-    baseline: 'top' | 'middle' | 'bottom';
-    size: number;
-    weight?: number;
-    fill: string;
-    /** Degrees, around (x, y). */
-    rotate?: number;
-}
-type ChartMark = ChartRectMark | ChartPathMark | ChartCircleMark | ChartLineMark | ChartTextMark;
-/** Maps between data values and scene pixels along one axis of the plot. */
-interface ChartValueScale {
-    /** `y` for vertical charts, `x` for horizontal bars. */
-    axis: 'x' | 'y';
-    domain: [number, number];
-    range: [number, number];
-    ticks: number[];
-}
-/** A laid-out chart: drawing primitives in scene pixels, ready for SVG, canvas or anything else. */
-interface ChartScene {
-    width: number;
-    height: number;
-    /** The plot area (inside the axes). Empty for pies. */
-    plot: ChartRect;
-    /** Draw in order. */
-    marks: ChartMark[];
-    /** The value scale of a cartesian chart (absent for pies and empty charts). */
-    valueScale?: ChartValueScale;
-    /** Percent-stacked: values are shown as shares, so dragging is disabled. */
-    percent: boolean;
-    theme: ChartTheme;
-}
-interface ChartIssue {
-    path: string;
-    message: string;
-}
-
-declare const CHART_TYPES: readonly ChartType[];
-declare const CHART_SERIES_TYPES: readonly ChartSeriesType[];
-declare const CHART_STACKINGS: readonly ChartStacking[];
-declare const CHART_CURVES: readonly ChartCurve[];
-declare const CHART_ORIENTATIONS: readonly ChartOrientation[];
-declare const CHART_LEGEND_POSITIONS: readonly ChartLegendPosition[];
-declare const CHART_NUMBER_STYLES: readonly NonNullable<ChartNumberFormat['style']>[];
-/** Labels for pickers, shared by the React and Svelte components. */
-declare const CHART_TYPE_LABELS: Readonly<Record<ChartType, string>>;
-/** A colour-blind-friendly categorical palette (Okabe–Ito order, tuned for light and dark backgrounds). */
-declare const DEFAULT_CHART_PALETTE: readonly string[];
-declare const DEFAULT_CHART_THEME: ChartTheme;
-/**
- * A theme that reads the page's `--background`, `--foreground`, `--muted-foreground`,
- * `--border` and `--primary` colour variables (full colours, as the other components'
- * inline styles use them), with light fallbacks. The React and Svelte canvases use it.
- */
-declare const CSS_VARIABLE_CHART_THEME: ChartTheme;
-declare function isCartesianChart(type: ChartType): boolean;
-declare function defaultChartAxis(value: boolean): ChartAxis;
-/** A complete spec with every default filled in. */
-declare function createChartSpec(partial?: Partial<ChartSpec>): ChartSpec;
-/** The colour a series is drawn with. */
-declare function chartSeriesColor(spec: Pick<ChartSpec, 'palette' | 'series'>, seriesIndex: number): string;
-/** The colour a pie slice is drawn with (by category). */
-declare function chartSliceColor(spec: Pick<ChartSpec, 'palette'>, index: number): string;
-/** How a series is drawn in a cartesian chart. */
-declare function chartSeriesType(spec: Pick<ChartSpec, 'type'>, series: ChartSeries): ChartSeriesType;
-/** An id not used by any series (`series-1`, `series-2`, …). */
-declare function uniqueChartSeriesId(series: readonly Pick<ChartSeries, 'id'>[], base?: string): string;
-/**
- * Reads a number the way people type it in a data grid: `1,234.5`, `12%` (→ 0.12),
- * `$40`, `(3)` (→ -3). Blank → `null`. Returns `undefined` when it is not a number.
- */
-declare function parseChartValue(input: unknown): ChartValue | undefined;
-declare function normalizeChartAxis(value: unknown, fallback: ChartAxis, path: string, issues?: ChartIssue[]): ChartAxis;
-/** Values as numbers or nulls; bad entries become null and are reported. */
-declare function normalizeChartValues(value: unknown, length: number | undefined, path: string, issues?: ChartIssue[]): ChartValue[];
-/**
- * Turns any input (a partial spec, saved JSON, an agent's arguments) into a complete,
- * valid `ChartSpec`. Every value is checked; problems are reported as sentences in
- * `issues` and replaced by defaults, so the result is always drawable. Series values are
- * padded or trimmed to the number of categories.
- */
-declare function normalizeChartSpec(input: unknown): {
-    spec: ChartSpec;
-    issues: ChartIssue[];
-};
-/** A deep copy (specs are plain JSON). */
-declare function cloneChartSpec(spec: ChartSpec): ChartSpec;
-declare function cloneChartSeries(series: ChartSeries): ChartSeries;
-interface ChartTableOptions {
-    /**
-     * `columns` (default): the first column holds categories and each other column is a
-     * series. `rows`: the first row holds categories and each other row is a series.
-     */
-    seriesIn?: 'columns' | 'rows';
-    /** The first row (or column for `rows`) holds series names (default `true`). */
-    header?: boolean;
-}
-interface ChartTableData {
-    categories: string[];
-    series: ChartSeries[];
-    issues: ChartIssue[];
-}
-/**
- * Reads a grid of cells (from CSV, a spreadsheet range or the clipboard) as categories and
- * series. Cells that are not numbers become gaps and are reported.
- */
-declare function chartDataFromTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: ChartTableOptions): ChartTableData;
-/** The chart's data as a grid: a header row of series names, then one row per category. */
-declare function chartDataToTable(spec: Pick<ChartSpec, 'categories' | 'series'>, options?: {
-    categoryHeader?: string;
-}): (string | number | null)[][];
-/** A colour input value (`#rrggbb`) for a CSS colour: `#abc` expands, non-hex colours show as black. */
-declare function chartColorInputValue(color: string): string;
-
 /** A "nice" step (1, 2, 2.5 or 5 × 10ⁿ) for about `count` intervals over `span`. */
 declare function niceStep(span: number, count: number): number;
 interface NiceScale {
@@ -321,273 +31,389 @@ declare function formatChartNumber(value: number | null | undefined, format?: Ch
 /** Linear map from `domain` to `range`. */
 declare function linearMap(value: number, domain: readonly [number, number], range: readonly [number, number]): number;
 
-type ChartTextMeasure = (text: string, size: number, weight?: number) => number;
-interface ChartLayoutOptions {
-    width: number;
-    height: number;
-    theme?: Partial<ChartTheme>;
-    /** Highlighted in the scene (selection outlines, `selected` flags). */
-    selection?: ChartSelection | null;
-    /** Text width in pixels (default: an estimate from the character count). */
-    measureText?: ChartTextMeasure;
-    /** Shown when there is nothing to draw (default "No data"). */
-    emptyMessage?: string;
-    /**
-     * Fixes the value axis to this range (over `yAxis.min` / `yAxis.max`). Canvases pass
-     * `ChartPointDrag.valueDomain` during a drag so the axis does not rescale under the pointer.
-     */
-    valueDomain?: {
-        min: number;
-        max: number;
-    } | null;
+/**
+ * A compiled spreadsheet number format code for chart labels, e.g. `#,##0.00`, `0.0%`,
+ * `#,##0,,"M"`, `$#,##0;[Red]($#,##0);"–"` or `yyyy-mm-dd`. Backed by the spreadsheet's
+ * format engine (`NumberFormat`), so charts and sheets write numbers the same way; colours
+ * such as `[Red]` are ignored on charts.
+ */
+interface ChartFormatCode {
+    format(value: number): string;
+    /** The code is a date or time format (values are serial day numbers from 1899-12-30). */
+    isDate: boolean;
+    /** The code shows a percentage (values are multiplied by 100). */
+    isPercent: boolean;
+}
+/** Compiles a spreadsheet format code (cached). */
+declare function compileChartFormatCode(code: string): ChartFormatCode;
+/** Formats `value` with a spreadsheet format code. */
+declare function formatChartValueWithCode(value: number, code: string): string;
+/** A spreadsheet serial day number (1 = 1900-01-01, with the 1900 leap-year quirk) as a UTC date. */
+declare function chartSerialToDate(serial: number): Date;
+/** A UTC date as a spreadsheet serial day number. */
+declare function chartDateToSerial(date: Date): number;
+
+/** An sRGB colour with channels from 0 to 1. */
+type ChartRgb = [number, number, number];
+/**
+ * Reads `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb()` / `rgba()` and a few colour names. Returns
+ * `null` for anything else (CSS variables, `hsl()`, …), so callers can leave such colours alone.
+ */
+declare function parseChartColor(color: string): ChartRgb | null;
+declare function chartRgbToHex(rgb: ChartRgb): string;
+/**
+ * A lighter (`amount` > 0, towards white) or darker (`amount` < 0, towards black) shade of
+ * `color`. Colours it cannot read (CSS variables) come back unchanged.
+ */
+declare function shadeChartColor(color: string, amount: number): string;
+/** Shades used once a palette is used up: the same hues, lighter then darker (GridCraft's cycle). */
+declare const CHART_PALETTE_SHADES: readonly number[];
+/** The palette colour for the `index`-th item: the palette in order, then lighter and darker rounds of it. */
+declare function cyclePaletteColor(palette: readonly string[], index: number): string;
+/** WCAG relative luminance (0 black – 1 white). */
+declare function chartLuminance(rgb: ChartRgb): number;
+/** WCAG contrast ratio (1–21) between two colours, or `null` when either cannot be read. */
+declare function chartContrastRatio(a: string, b: string): number | null;
+/**
+ * Dark or white text, whichever reads better on `fill`; `fallback` when the fill cannot be
+ * read (a CSS variable).
+ */
+declare function chartTextOn(fill: string, fallback: string, dark?: string, light?: string): string;
+/** OKLab (Ottosson) from sRGB. */
+declare function chartRgbToOklab(rgb: ChartRgb): [number, number, number];
+/** Perceptual distance between two colours (Euclidean in OKLab; ≈0.02 is just noticeable). */
+declare function chartColorDistance(a: ChartRgb, b: ChartRgb): number;
+type ChartVision = 'normal' | 'protanopia' | 'deuteranopia' | 'tritanopia';
+/** How a colour looks with a colour-vision deficiency (Machado et al. 2009, full severity). */
+declare function simulateChartVision(rgb: ChartRgb, vision: ChartVision): ChartRgb;
+interface ChartColorPair {
+    a: number;
+    b: number;
+    colors: [string, string];
+    distance: number;
+}
+interface ChartColorCheck {
+    /** No problems found. */
+    ok: boolean;
+    /** Per vision: the closest pair of colours and their OKLab distance. */
+    closest: Partial<Record<ChartVision, ChartColorPair>>;
+    /** Contrast ratio of each colour against the surface (null when unreadable). */
+    contrast: (number | null)[];
+    /** Problems, as sentences. */
+    issues: string[];
+    /** Colours that could not be read (CSS variables, `hsl()`); they are skipped. */
+    skipped: string[];
+}
+interface ChartColorCheckOptions {
+    /** The page colour behind the marks (default white). */
+    surface?: string;
+    /** Smallest OKLab distance two series may have (default 0.08). */
+    minDistance?: number;
+    /** Smallest contrast ratio against the surface (default 1.5; WCAG asks 3 for graphics). */
+    minContrast?: number;
+    /** Visions to check (default all four). */
+    visions?: readonly ChartVision[];
+}
+/**
+ * Checks that series colours can be told apart, with normal vision and the three
+ * colour-vision deficiencies, and stand out from the surface. Returns the closest pair per
+ * vision and problems as sentences.
+ */
+declare function checkChartColors(colors: readonly string[], options?: ChartColorCheckOptions): ChartColorCheck;
+
+/**
+ * Reads a category label as a UTC date: `2024`, `2024-03`, `2024-03-05`, ISO date-times,
+ * `2024/03/05`, `Mar 2024` and `5 Mar 2024`. Returns milliseconds since the epoch, or `null`.
+ */
+declare function parseChartDate(label: string): number | null;
+/** Calendar steps from fine to coarse. */
+declare const CHART_DATE_STEPS: readonly [{
+    readonly unit: "day";
+    readonly count: 1;
+}, {
+    readonly unit: "day";
+    readonly count: 2;
+}, {
+    readonly unit: "week";
+    readonly count: 1;
+}, {
+    readonly unit: "week";
+    readonly count: 2;
+}, {
+    readonly unit: "month";
+    readonly count: 1;
+}, {
+    readonly unit: "month";
+    readonly count: 3;
+}, {
+    readonly unit: "month";
+    readonly count: 6;
+}, {
+    readonly unit: "year";
+    readonly count: 1;
+}, {
+    readonly unit: "year";
+    readonly count: 2;
+}, {
+    readonly unit: "year";
+    readonly count: 5;
+}, {
+    readonly unit: "year";
+    readonly count: 10;
+}, {
+    readonly unit: "year";
+    readonly count: 25;
+}, {
+    readonly unit: "year";
+    readonly count: 50;
+}, {
+    readonly unit: "year";
+    readonly count: 100;
+}];
+type ChartDateStep = (typeof CHART_DATE_STEPS)[number];
+/** A label for a date at `step`: years as `2024`, months as `Mar 2024` (`Mar` within a year), days as `5 Mar`. */
+declare function formatChartDate(t: number, step: ChartDateStep, previous?: number | null): string;
+interface ChartDateLabels {
+    /** The calendar step chosen. */
+    step: ChartDateStep;
+    /** Category indexes that get a label (the first category in each bucket). */
+    indexes: number[];
+    /** Label text by category index. */
+    labels: Map<number, string>;
+}
+/**
+ * Picks the finest calendar step whose labels fit along a category axis. Categories are
+ * evenly spaced (`band` pixels each), so a label goes on the first category of each bucket,
+ * and the step is the first on the ladder whose neighbouring labels are at least their own
+ * width plus `gap` apart. Returns `null` when fewer than half the categories read as dates.
+ */
+declare function chartDateLabels(categories: readonly string[], band: number, measure: (text: string) => number, gap?: number): ChartDateLabels | null;
+
+interface ChartHistogramBin {
+    /** Lower edge (exclusive, except for the first bin). */
+    from: number;
+    /** Upper edge (inclusive). */
+    to: number;
+    count: number;
+}
+/**
+ * Bins values into `bins` equal-width bins (default √n, from 1 to 100). Bins are
+ * right-inclusive, the first closed on both sides, so a value on an edge belongs to the bin
+ * that ends there. Gaps and non-finite values are ignored.
+ */
+declare function chartHistogram(values: readonly ChartValue[], bins?: number | null): ChartHistogramBin[];
+/** The `q` quantile (0–1) of sorted values, interpolating linearly between ranks (`q·(n-1)`). */
+declare function chartQuantile(sorted: readonly number[], q: number): number;
+interface ChartBoxStats {
+    min: number;
+    max: number;
+    q1: number;
+    median: number;
+    q3: number;
+    mean: number;
+    /** Whisker ends: the furthest values within 1.5 × IQR of the box. */
+    lowerWhisker: number;
+    upperWhisker: number;
+    /** Values beyond the whiskers. */
+    outliers: number[];
+    count: number;
 }
-/** A DOM-free text width estimate (average glyph ≈ 0.56 em, bold ≈ 0.6 em). */
-declare const estimateChartTextWidth: ChartTextMeasure;
-/** Whether two selections point at the same thing. */
-declare function sameChartSelection(a: ChartSelection | null | undefined, b: ChartSelection | null | undefined): boolean;
+/** Box-and-whisker statistics (Tukey fences at 1.5 × IQR); `null` without values. */
+declare function chartBoxStats(values: readonly ChartValue[]): ChartBoxStats | null;
+/** Squarified treemap (Bruls et al.): positive `values` packed into `rect`, largest first. Returns one rect per input index (zero-size for values ≤ 0). */
+declare function chartSquarify(values: readonly number[], rect: ChartRect): ChartRect[];
 /**
- * Black or white text for a label drawn on `fill` (#rgb, #rrggbb or rgb()), by perceived
- * luminance (0.299 R + 0.587 G + 0.114 B). Unparseable colours (CSS variables) get white.
+ * Thins a long polyline (sorted by x) to the first, lowest, highest and last point of each
+ * pixel column, which draws identically. Returns the input when it has `max` points or fewer.
  */
-declare function contrastingTextColor(fill: string): string;
+declare function decimateChartPoints<T extends {
+    x: number;
+    y: number;
+}>(points: readonly T[], max?: number): T[];
+interface ChartSeriesSummary {
+    id: string;
+    name: string;
+    /** Values present (not gaps). */
+    count: number;
+    gaps: number;
+    min: number | null;
+    max: number | null;
+    mean: number | null;
+    sum: number | null;
+    /** Category label of the minimum and maximum. */
+    minAt: string | null;
+    maxAt: string | null;
+    /** Direction of a least-squares line through the values in order. */
+    trend: 'rising' | 'falling' | 'flat' | null;
+    /** Relative change from the first to the last value, e.g. 0.25 for +25%. */
+    change: number | null;
+}
+/** Numbers about one series, for agents that check a chart without looking at it. */
+declare function summarizeChartSeries(series: {
+    id: string;
+    name: string;
+    values: readonly ChartValue[];
+}, categories: readonly string[]): ChartSeriesSummary;
+
 /**
  * Lays a chart out as drawing primitives (rects, paths, circles, lines and text) in a
  * `width × height` box. Pure and DOM-free: the React and Svelte canvases render the marks
  * as SVG, `chartSceneToSvg` writes them as a string, and anything else (canvas, PDF) can
- * draw them too. Clickable marks carry the `target` they select.
+ * draw them too. Clickable marks carry the `target` they select; what had to be left out
+ * (hidden labels, thinned lines) is listed in `warnings`.
  */
 declare function layoutChart(spec: ChartSpec, options: ChartLayoutOptions): ChartScene;
 /**
  * The data value at a scene point along the value axis (for dragging a bar or point), or
- * `undefined` when the scene has no value scale or is percent-stacked.
+ * `undefined` when the scene has no value scale or is percent-stacked. `secondary` reads the
+ * secondary axis.
  */
 declare function chartValueAtPoint(scene: ChartScene, point: {
     x: number;
     y: number;
+}, secondary?: boolean): number | undefined;
+/** The x value at a scene point on a scatter or bubble chart, or `undefined` without a numeric x axis. */
+declare function chartXAtPoint(scene: ChartScene, point: {
+    x: number;
+    y: number;
 }): number | undefined;
 /** The value a drag should store: snapped to a tenth of the tick step (or `step`) and kept finite. */
-declare function snapChartValue(scene: ChartScene, value: number, step?: number): number;
+declare function snapChartValue(scene: ChartScene, value: number, step?: number, ticks?: readonly number[]): number;
 
-/** SVG `dominant-baseline` for a text mark's baseline (shared by every renderer). */
-declare function chartTextBaseline(baseline: ChartTextMark['baseline']): 'hanging' | 'central' | 'text-after-edge';
-/** SVG `transform` for a rotated text mark, if any. */
-declare function chartTextTransform(mark: ChartTextMark): string | undefined;
-interface ChartSvgOptions {
-    /** Leave out selection outlines (default `true`: exports show the chart only). */
-    hideSelection?: boolean;
-    /** Accessible title (default: the chart title). */
-    ariaLabel?: string;
-}
-/** Writes a laid-out scene as a standalone SVG document string. */
-declare function chartSceneToSvg(scene: ChartScene, options?: ChartSvgOptions): string;
-/** Lays out and writes a chart as SVG, e.g. for export or server rendering. */
-declare function chartToSvg(spec: ChartSpec, options: Omit<ChartLayoutOptions, 'selection'> & ChartSvgOptions): string;
+/** Data labels are skipped on series with more points than this. */
+declare const MAX_CHART_DATA_LABELS = 200;
+/** Lines with more points than this are thinned per pixel column. */
+declare const MAX_CHART_LINE_POINTS = 2000;
+/** Markers beyond this many are thinned to one per 2px cell. */
+declare const MAX_CHART_MARKERS = 1000;
 
-interface ChartControllerOptions {
-    /** Starting chart (any partial or saved spec; problems are reported in `state.issues`). */
-    spec?: Partial<ChartSpec> | unknown;
-    /** History to record into, e.g. one shared with the rest of the app (default: a new one). */
-    history?: HistoryManager;
-    /** Called after the spec changes (edit, undo, redo, load). */
-    onChange?: (spec: Readonly<ChartSpec>) => void;
-}
-/** A snapshot of the controller. The same object is returned until something changes. */
-interface ChartState {
-    spec: Readonly<ChartSpec>;
-    selection: ChartSelection | null;
-    /** The series the selection belongs to (a series or one of its points). */
-    selectedSeries: ChartSeries | null;
-    /** The category the selection belongs to (a category or a point). */
-    selectedIndex: number | null;
-    /** Problems from the last load or rejected edit, as sentences. */
-    issues: readonly ChartIssue[];
-    /** The gesture in progress (e.g. a bar drag), if any. */
-    gesture: string | null;
-    canUndo: boolean;
-    canRedo: boolean;
-    undoLabel: string;
-    redoLabel: string;
-    /** Bumped on every change. */
-    revision: number;
-}
-type ChartActionResult = {
+interface ChartSummary {
+    type: ChartSpec['type'];
+    title: string;
+    categories: number;
+    series: ChartSeriesSummary[];
+    /** The value axis as drawn: range and ticks (absent for pies and treemaps). */
+    valueAxis?: {
+        min: number;
+        max: number;
+        ticks: number[];
+    };
+    secondaryAxis?: {
+        min: number;
+        max: number;
+        ticks: number[];
+    };
+    xAxis?: {
+        min: number;
+        max: number;
+        ticks: number[];
+    };
+    /** What the layout left out at this size (hidden labels, thinned lines, …). */
+    warnings: ChartWarning[];
+    /** Whether the series colours can be told apart (also with colour-blindness). */
+    colors: Pick<ChartColorCheck, 'ok' | 'issues'>;
+    /** A plain-language description (the SVG `<desc>`). */
+    description: string;
+}
+/**
+ * Numbers about a chart for agents and screen readers: per-series min / max / mean / trend,
+ * the axes as drawn, layout warnings at `size`, a colour check and a one-paragraph
+ * description. Lets an agent verify a chart without rendering it.
+ */
+declare function summarizeChart(spec: ChartSpec, size?: Pick<ChartLayoutOptions, 'width' | 'height' | 'measureText'>, scene?: ChartScene): ChartSummary;
+/** A plain-language description of a chart: type, what it compares, ranges and notable extremes. */
+declare function describeChart(spec: ChartSpec, series?: ChartSeriesSummary[]): string;
+
+/** A partial change several fields at once (what `ChartController.update` takes). */
+type ChartPresetPatch = Partial<Omit<ChartSpec, 'version' | 'xAxis' | 'yAxis' | 'yAxis2' | 'legend' | 'series' | 'categories'>> & {
+    xAxis?: Partial<ChartAxis>;
+    yAxis?: Partial<ChartAxis>;
+    yAxis2?: Partial<ChartAxis>;
+    legend?: Partial<ChartLegend>;
+};
+interface ChartLayoutPreset {
+    id: string;
+    label: string;
+    description: string;
+    patch: ChartPresetPatch;
+}
+/** Quick layouts: legend, labels and grid lines set together. */
+declare const CHART_LAYOUT_PRESETS: readonly ChartLayoutPreset[];
+interface ChartColorScheme {
+    id: string;
+    label: string;
+    description: string;
+    palette: readonly string[];
+}
+/** Shades of one hue, dark to light (for monochrome schemes). */
+declare function monochromeChartPalette(base: string, count?: number): string[];
+/** Named palettes. `default` and `okabe-ito` are colour-blind friendly. */
+declare const CHART_COLOR_SCHEMES: readonly ChartColorScheme[];
+/** The change a named layout and / or colour scheme makes, or a sentence saying which names exist. */
+declare function chartPresetPatch(options: {
+    layout?: string;
+    colors?: string;
+}): {
     ok: true;
+    patch: ChartPresetPatch;
 } | {
     ok: false;
     message: string;
-    issues?: ChartIssue[];
 };
-/** Top-level fields with partial axes and legend. */
-type ChartSpecPatch = Partial<Omit<ChartSpec, 'version' | 'xAxis' | 'yAxis' | 'legend'>> & {
-    xAxis?: Partial<ChartAxis>;
-    yAxis?: Partial<ChartAxis>;
-    legend?: Partial<ChartLegend>;
-};
-interface ChartSeriesInput {
-    id?: string;
-    name?: string;
-    values?: readonly unknown[];
-    color?: string;
-    type?: ChartSeriesType;
-    hidden?: boolean;
+
+interface ChartTableShape {
+    /** The first row holds series names (some text, every value cell text or blank). */
+    headerRow: boolean;
+    /** The first column holds category labels (all text, or a blank top-left cell above a header row). */
+    labelColumn: boolean;
+    /** Series run along rows (the block is much wider than tall). */
+    byRows: boolean;
+    series: number;
+    /** Points per series. */
+    points: number;
+    anyNumber: boolean;
+    nonNegative: boolean;
+    mixedSigns: boolean;
+    /** The category labels read as dates. */
+    dates: boolean;
 }
-interface ChartSeriesPatch {
-    name?: string;
-    /** `null` goes back to the palette colour. */
-    color?: string | null;
-    /** `null` follows the chart type. */
-    type?: ChartSeriesType | null;
-    hidden?: boolean;
-}
-interface ChartEditOptions {
-    /** Undo step label. */
-    label?: string;
+/**
+ * Reads the shape of a block of cells the way spreadsheets do: a header row when the first
+ * row is text, a label column when the first column is text (or the top-left cell is blank
+ * above a header row, the convention for years and x values), and series along the longer side.
+ */
+declare function analyzeChartTable(rows: ReadonlyArray<ReadonlyArray<unknown>>): ChartTableShape;
+interface ChartRecommendation {
+    type: ChartType;
+    stacking?: ChartStacking;
+    label: string;
+    /** Why it suits the data, as a sentence. */
+    reason: string;
 }
 /**
- * Headless state for a chart editor: a validated `ChartSpec`, a selection, and undoable
- * edits to data (values, series, categories, pasted grids, CSV) and presentation (type,
- * titles, axes, legend, stacking, …). Drags merge into one undo step (`beginGesture`).
- * `getState()` returns the same object until something changes, so it works with
- * `useSyncExternalStore` and Svelte runes alike.
- */
-declare class ChartController {
-    readonly history: HistoryManager;
-    private spec;
-    private selection;
-    private issues;
-    private gestureKey;
-    private gestureCount;
-    private gestureStart;
-    private revision;
-    private applying;
-    private readonly onChange?;
-    private readonly listeners;
-    private unsubscribeHistory?;
-    private state;
-    constructor(options?: ChartControllerOptions);
-    private connect;
-    /** The current snapshot (stable until the next change). */
-    getState: () => ChartState;
-    /** Calls `listener` after every change. Returns an unsubscribe function. */
-    subscribe: (listener: (state: ChartState) => void) => (() => void);
-    /** The current spec (do not mutate; edit through the controller). */
-    getSpec(): Readonly<ChartSpec>;
-    getSeries(id: string): ChartSeries | undefined;
-    private computeState;
-    private notify;
-    /** Drops a selection that no longer points at anything. */
-    private validSelection;
-    private applySpec;
-    private commit;
-    private reject;
-    /** A copy of the spec with `edit` applied (series and categories copied as needed). */
-    private edited;
-    private unknownSeries;
-    private badIndex;
-    /**
-     * Changes any presentation or data fields as one undo step. All-or-nothing: if anything
-     * is invalid, nothing changes and every problem is returned (and shown in `state.issues`).
-     */
-    update(patch: ChartSpecPatch, options?: ChartEditOptions): ChartActionResult;
-    setType(type: ChartType): ChartActionResult;
-    setTitle(title: string): ChartActionResult;
-    setSubtitle(subtitle: string): ChartActionResult;
-    /** Changes the category (`x`) or value (`y`) axis. */
-    setAxis(axis: 'x' | 'y', patch: Partial<ChartAxis>): ChartActionResult;
-    setLegend(patch: Partial<ChartLegend>): ChartActionResult;
-    /**
-     * Replaces categories and / or series as one undo step. Values are validated and padded
-     * to the categories; all-or-nothing like `update`.
-     */
-    setData(data: {
-        categories?: readonly unknown[];
-        series?: readonly ChartSeriesInput[];
-    }, options?: ChartEditOptions): ChartActionResult;
-    /**
-     * Sets one value (numbers, numeric text such as `1,200` or `12%`, or blank for a gap).
-     * One undo step, or part of the current gesture.
-     */
-    setValue(seriesId: string, index: number, value: unknown, options?: ChartEditOptions): ChartActionResult;
-    /** Several values as one undo step (all-or-nothing). */
-    setValues(cells: readonly {
-        seriesId: string;
-        index: number;
-        value: unknown;
-    }[], options?: ChartEditOptions): ChartActionResult;
-    /** Adds a series (values padded to the categories) and selects it. Returns its id. */
-    addSeries(input?: ChartSeriesInput, options?: {
-        at?: number;
-    }): {
-        ok: true;
-        id: string;
-    } | {
-        ok: false;
-        message: string;
-        issues?: ChartIssue[];
-    };
-    removeSeries(id: string): ChartActionResult;
-    updateSeries(id: string, patch: ChartSeriesPatch): ChartActionResult;
-    toggleSeries(id: string): ChartActionResult;
-    /** Moves a series to position `to` (drawing and legend order). */
-    moveSeries(id: string, to: number): ChartActionResult;
-    /** Inserts a category (with gaps in every series) at `at` (default: the end). Returns its index. */
-    addCategory(label?: string, options?: {
-        at?: number;
-    }): {
-        ok: true;
-        index: number;
-    };
-    removeCategory(index: number): ChartActionResult;
-    renameCategory(index: number, label: string): ChartActionResult;
-    moveCategory(from: number, to: number): ChartActionResult;
-    /**
-     * Pastes a block of cells (TSV / CSV text or rows) into the data grid with its top-left at
-     * `row` (category index) and `column` (series index; `-1` is the category column). The
-     * grid grows to fit. Non-numeric value cells become gaps and are reported in `issues`.
-     */
-    pasteCells(row: number, column: number, cells: string | ReadonlyArray<ReadonlyArray<unknown>>): ChartActionResult & {
-        issues?: ChartIssue[];
-    };
-    /**
-     * Replaces the data with a grid of cells (see `chartDataFromTable`): one undo step. Series
-     * colours and types are kept by name.
-     */
-    importTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: ChartTableOptions): ChartActionResult & {
-        issues?: ChartIssue[];
-    };
-    /** Imports CSV (or TSV, detected by tabs) text; see `importTable`. */
-    importCsv(text: string, options?: ChartTableOptions & {
-        delimiter?: string;
-    }): ChartActionResult & {
-        issues?: ChartIssue[];
-    };
-    /** Selects a chart element (view state; not an undo step). */
-    select(selection: ChartSelection | null): void;
-    /**
-     * Deletes what is selected: a series or category is removed, a point becomes a gap, a
-     * title is cleared, the legend or an axis is hidden.
-     */
-    deleteSelection(): ChartActionResult;
-    /** Adds `delta` to a value (a gap counts as 0). */
-    nudgeValue(seriesId: string, index: number, delta: number): ChartActionResult;
-    /** Starts a continuous edit (a drag): every change until `endGesture()` is one undo step. */
-    beginGesture(key: string): void;
-    endGesture(): void;
-    /** The spec, for saving (a copy). */
-    toJSON(): ChartSpec;
-    /**
-     * Replaces the chart without an undo step (e.g. when opening a document). Problems are
-     * fixed with defaults and reported in `state.issues` (and returned).
-     */
-    load(input: unknown, options?: {
-        clearHistory?: boolean;
-    }): ChartIssue[];
-    undo(): boolean;
-    redo(): boolean;
-    /** Stops listening to the history (reconnected by the next `subscribe`). */
-    destroy(): void;
-}
-declare function createChartController(options?: ChartControllerOptions): ChartController;
+ * Chart types that suit the shape of a block of cells, best first. A heuristic from the shape
+ * (series count, points per series, text or date categories, negative values), not a copy of
+ * any spreadsheet's ranking.
+ */
+declare function recommendChartTypes(rows: ReadonlyArray<ReadonlyArray<unknown>>): ChartRecommendation[];
+declare function recommendForShape(shape: Omit<ChartTableShape, 'headerRow' | 'byRows'> & Partial<ChartTableShape>): ChartRecommendation[];
+interface ChartFromTable {
+    type: ChartType;
+    stacking: ChartStacking;
+    categories: string[];
+    series: ChartSeries[];
+    issues: ChartIssue[];
+    shape: ChartTableShape;
+}
+/**
+ * Builds chart data from a block of cells (CSV, a clipboard grid or a spreadsheet range) using
+ * the spreadsheet conventions of `analyzeChartTable`. `type: 'auto'` (the default) takes the
+ * first recommendation. A scatter chart of a block without labels takes the first column as
+ * the x values of the others.
+ */
+declare function chartFromTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: {
+    type?: ChartType | 'auto';
+}): ChartFromTable;
 
 interface ChartCommandOptions {
     /** Id prefix (default `chart.`); use one per chart when several are registered. */
@@ -599,9 +425,12 @@ interface ChartCommandOptions {
 }
 /**
  * Palette and agent commands for a chart: describe, update presentation, replace data, set
- * values, add / remove series and categories, import CSV and export SVG. Register them in a
- * `CommandRegistry` and agents get them through `createCommandToolProvider`. Failures throw
- * sentences, which the registry returns as `{ ok: false, code: 'failed', message }`.
+ * values, add / remove series, categories and trendlines, apply presets, switch rows and
+ * columns, import CSV or Mermaid, export SVG, Mermaid or Office XML, recommend types and
+ * check colours. Register them in a `CommandRegistry` and agents get them through
+ * `createCommandToolProvider`; `createChartToolProvider` offers the same operations as
+ * individual tools. Failures throw sentences, which the registry returns as
+ * `{ ok: false, code: 'failed', message }`.
  */
 declare function createChartCommands(controller: ChartController, options?: ChartCommandOptions): CommandSpec[];
 
@@ -615,10 +444,22 @@ declare function chartClientToScene(scene: Pick<ChartScene, 'width' | 'height'>,
     x: number;
     y: number;
 };
-/** Whether a point can be dragged to a new value in this scene (cartesian, not percent-stacked, not hidden). */
+/**
+ * Whether a point can be dragged to a new value in this scene: bar, line, area and scatter
+ * charts (not percent-stacked), scatter and bubble charts with x values (x and y), and
+ * waterfall steps. Hidden series and gaps cannot be dragged.
+ */
 declare function canDragChartPoint(controller: ChartController, scene: ChartScene, target: ChartSelection | undefined): target is Extract<ChartSelection, {
     kind: 'point';
 }>;
+interface ChartDragMoveOptions {
+    /** Move a tenth as far as the pointer (fine adjustment; Alt). */
+    fine?: boolean;
+    /** Only change the axis the pointer has moved along most (scatter charts; Shift). */
+    lockAxis?: boolean;
+    /** Skip snapping to nearby values and ticks (e.g. while Ctrl / Cmd is held). */
+    noSnap?: boolean;
+}
 interface ChartPointDrag {
     /**
      * The value axis range when the drag started. Pass it to `layoutChart` (`valueDomain`)
@@ -628,25 +469,60 @@ interface ChartPointDrag {
         min: number;
         max: number;
     };
+    /** The secondary value axis range when the drag started (`layoutChart`'s `valueDomain2`). */
+    readonly valueDomain2?: {
+        min: number;
+        max: number;
+    };
+    /** The numeric x range of a scatter or bubble chart when the drag started (`xDomain`). */
+    readonly xDomain?: {
+        min: number;
+        max: number;
+    };
+    /** The point being dragged, for `layoutChart`'s `readout`. */
+    readonly target: {
+        seriesId: string;
+        index: number;
+    };
     /** Moves the value with the pointer (scene coordinates). */
     move(point: {
         x: number;
         y: number;
-    }): void;
+    }, options?: ChartDragMoveOptions): void;
     /** Ends the drag (one undo step for the whole drag). */
     end(): void;
+    /** Cancels the drag: the value goes back and no undo step is left (Escape). */
+    cancel(): void;
 }
+interface ChartSnapOptions {
+    /** Values to snap to when the pointer is within `tolerancePx` of them. */
+    candidates?: readonly number[];
+    /** Screen distance that snaps (default 6). */
+    tolerancePx?: number;
+    /** Fallback step when no candidate is close (default: a tenth of the tick step). */
+    step?: number;
+    /** The scale the value is on (default: the scene's value scale). */
+    scale?: ChartValueScale;
+}
+/**
+ * Snaps a dragged value: to the nearest candidate (other series at the same category, the
+ * neighbouring values, zero, the start value, ticks) within `tolerancePx` screen pixels, or
+ * else to a tenth of the tick step.
+ */
+declare function snapChartDragValue(scene: ChartScene, value: number, options?: ChartSnapOptions): number;
 /**
- * Starts dragging a bar or point: the value follows the pointer along the value axis,
- * snapped to a tenth of the tick step (`step` overrides), and the whole drag is one undo
- * step. Works for stacked bars too (the drag changes the segment by the distance moved).
- * Returns `null` when the target cannot be dragged.
+ * Starts dragging a bar or point: the value follows the pointer along its value axis (and
+ * along x on scatter and bubble charts), snapped to nearby values and then to a tenth of the
+ * tick step (`step` overrides), and the whole drag is one undo step. Works for stacked bars
+ * too (the drag changes the segment by the distance moved). Returns `null` when the target
+ * cannot be dragged.
  */
 declare function startChartPointDrag(controller: ChartController, scene: ChartScene, target: ChartSelection | undefined, start: {
     x: number;
     y: number;
 }, options?: {
     step?: number;
+    tolerancePx?: number;
 }): ChartPointDrag | null;
 interface ChartKeyInput {
     key: string;
@@ -657,12 +533,348 @@ interface ChartKeyInput {
 }
 /**
  * Keyboard editing on a focused chart: arrows move a point selection between categories
- * (← →) and change its value (↑ ↓, a tenth of the tick step; Shift: a whole step), Delete /
- * Backspace deletes the selection, Escape clears it. Returns `true` when the key was used
- * (call `preventDefault`).
+ * (← →) and change its value (↑ ↓, a tenth of the tick step; Shift: a whole step; Alt: a
+ * hundredth), Delete / Backspace deletes the selection, Escape cancels a drag or clears the
+ * selection. Returns `true` when the key was used (call `preventDefault`).
  */
 declare function handleChartKey(controller: ChartController, scene: ChartScene | null, event: ChartKeyInput): boolean;
 /** A short description of the selection for an inspector heading or a screen reader. */
 declare function describeChartSelection(controller: ChartController, selection?: ChartSelection | null): string;
+/**
+ * The mark under a scene point (topmost first), for hosts without DOM events and for agents
+ * that drive the pointer: rects, circles, lines (within 4 px) and text boxes. Returns the
+ * mark's `target`, or `{ kind: 'chart' }` over the background, or `null` outside.
+ */
+declare function chartHitTest(scene: ChartScene, point: {
+    x: number;
+    y: number;
+}, measure?: (text: string, size: number, weight?: number) => number): ChartSelection | null;
+
+/** The comment line that carries what Mermaid cannot express. Every Mermaid tool ignores `%%` comments. */
+declare const CHART_MERMAID_META_PREFIX = "%% @pixerate ";
+type ChartMermaidFamily = 'xychart' | 'pie' | 'radar';
+interface ChartMermaidOptions {
+    /** Write the `%% @pixerate {…}` line so the chart round-trips exactly (default `true`). */
+    meta?: boolean;
+    /** Indentation of statements (default four spaces). */
+    indent?: string;
+}
+/** The Mermaid family a chart is written as. */
+declare function chartMermaidFamily(spec: Pick<ChartSpec, 'type' | 'series'>): ChartMermaidFamily;
+/**
+ * Writes a chart as Mermaid: `xychart-beta` for bar, line, area and scatter charts (areas and
+ * scatters drawn as lines), `pie` for pies, donuts, funnels and treemaps, `radar-beta` for
+ * radars. Anything Mermaid cannot hold (stacking, colours, formats, gaps, trendlines, other
+ * chart types) goes into one `%% @pixerate {…}` comment so `chartFromMermaid` gets the chart
+ * back exactly, while any Mermaid renderer still draws the basic chart.
+ */
+declare function chartToMermaid(spec: ChartSpec, options?: ChartMermaidOptions): string;
+interface ChartMermaidParseOptions {
+    /** Accept a statement that is still being written (an unclosed `[` list): for streaming views. */
+    partial?: boolean;
+    /** Ignore the `%% @pixerate` line (what the Mermaid text alone says). */
+    ignoreMeta?: boolean;
+}
+interface ChartMermaidResult {
+    spec: ChartSpec;
+    /** Problems, with 1-based `line` numbers. Lines that could not be read are listed and skipped. */
+    issues: ChartIssue[];
+    family: ChartMermaidFamily | null;
+    /** The `%% @pixerate` line was found and applied. */
+    hasMeta: boolean;
+}
+/**
+ * Reads Mermaid `xychart-beta`, `pie` or `radar-beta` text as a chart. Never throws: lines it
+ * cannot read are reported with their line numbers and skipped, and the result always draws.
+ * A `%% @pixerate {…}` line written by `chartToMermaid` restores everything Mermaid cannot hold.
+ */
+declare function chartFromMermaid(text: string, options?: ChartMermaidParseOptions): ChartMermaidResult;
+interface FoundChartMermaid {
+    source: string;
+    family: ChartMermaidFamily;
+    /** 1-based line where the block starts in the input. */
+    line: number;
+}
+/**
+ * Finds Mermaid charts in Markdown or chat text: fenced ```mermaid blocks (and unlabelled
+ * fences) whose header is xychart-beta, pie or radar-beta, else the whole text when it is one.
+ */
+declare function findMermaidCharts(text: string): FoundChartMermaid[];
+
+declare const CHART_OOXML_NS = "http://schemas.openxmlformats.org/drawingml/2006/chart";
+declare const CHART_OOXML_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.drawingml.chart+xml";
+declare const CHART_OOXML_RELATIONSHIP = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart";
+type ParserCtor$1 = {
+    new (): DOMParser;
+};
+interface ChartOoxmlReadOptions {
+    /** `DOMParser` constructor (default: the global one; pass jsdom's or xmldom's in Node). */
+    DOMParser?: ParserCtor$1;
+}
+interface ChartOoxmlReadResult {
+    spec: ChartSpec;
+    /** Problems and simplifications, as sentences. */
+    issues: ChartIssue[];
+    /** Features the file uses that the spec cannot hold (3-D, stock, surface, gradients, …). */
+    unsupported: string[];
+    /**
+     * Nothing was dropped: writing `spec` back gives an equivalent chart. When false, keep the
+     * original part (or show the chart read-only) if the file must stay as it was.
+     */
+    lossless: boolean;
+}
+/**
+ * Reads a DrawingML chart part (`c:chartSpace`, e.g. `word/charts/chart1.xml`) or an Office
+ * 2016 chartex part (`cx:chartSpace`: waterfall, funnel, treemap, histogram, box & whisker)
+ * as a chart spec. Data comes from the cached values. Never throws for a malformed chart: it
+ * returns an empty chart and says why.
+ */
+declare function chartFromOoxml(xml: string, options?: ChartOoxmlReadOptions): ChartOoxmlReadResult;
+/** A spreadsheet format code equivalent to a chart number format (`General` when there is none). */
+declare function chartFormatToCode(format: ChartNumberFormat): string;
+interface ChartOoxmlWriteResult {
+    /** The `c:chartSpace` part. */
+    xml: string;
+    /** What could not be written as DrawingML, as sentences (empty when nothing was lost). */
+    issues: string[];
+}
+/**
+ * Writes a chart as a DrawingML chart part (`c:chartSpace`) with the data as literals (no
+ * embedded workbook), for `word/charts/chartN.xml` or `ppt/charts/chartN.xml`. Waterfall,
+ * histogram, box, funnel and treemap charts need Office 2016 chartex parts; they are written
+ * as the closest classic chart and reported in `issues`.
+ */
+declare function chartToOoxml(spec: ChartSpec): ChartOoxmlWriteResult;
+
+interface ChartPresenceActor {
+    id: string;
+    name: string;
+    color: string;
+    /** Cursor position in scene coordinates. */
+    x: number;
+    y: number;
+    /** The button is down (dragging). */
+    pressed: boolean;
+    /** A short note shown next to the cursor (what the agent is doing). */
+    message?: string;
+}
+interface ChartPresenceState {
+    actors: readonly ChartPresenceActor[];
+}
+/** Cursor positions and notes of agents acting on a chart, for an overlay. */
+declare class ChartPresence {
+    private state;
+    private readonly listeners;
+    getState: () => ChartPresenceState;
+    subscribe: (listener: (state: ChartPresenceState) => void) => (() => void);
+    /** Adds or changes an actor. */
+    set(actor: Pick<ChartPresenceActor, 'id'> & Partial<ChartPresenceActor>): void;
+    remove(id: string): void;
+}
+declare const CHART_PRESENCE_COLORS: readonly string[];
+/** Time for performances: real timers, or an instant clock for tests and recordings. */
+interface ChartClock {
+    now(): number;
+    wait(ms: number): Promise<void>;
+}
+declare const realChartClock: ChartClock;
+/** A clock whose waits finish at once while its time still advances (repeatable performances). */
+declare function createInstantChartClock(start?: number): ChartClock & {
+    elapsed(): number;
+};
+/** What an agent asks for. Each command commits as one undo step. */
+type ChartAgentCommand = {
+    kind: 'setValue';
+    seriesId: string;
+    index: number;
+    value: number;
+    note?: string;
+} | {
+    kind: 'select';
+    selection: ChartSelection | null;
+    note?: string;
+} | {
+    kind: 'update';
+    patch: ChartSpecPatch;
+    label?: string;
+    note?: string;
+} | {
+    kind: 'say';
+    text: string;
+};
+type ChartPerformanceStep = {
+    type: 'move';
+    to: {
+        x: number;
+        y: number;
+    };
+    ms: number;
+} | {
+    type: 'say';
+    text: string;
+    ms: number;
+} | {
+    type: 'press';
+} | {
+    type: 'drag';
+    to: {
+        x: number;
+        y: number;
+    };
+    ms: number;
+    from: number;
+    value: number;
+} | {
+    type: 'release';
+} | {
+    type: 'commit';
+};
+/** Where a point or bar sits in the scene (its top for bars), or null when it is not drawn. */
+declare function chartPointAnchor(scene: ChartScene, seriesId: string, index: number): {
+    x: number;
+    y: number;
+} | null;
+/**
+ * Plans how an agent acts out a command on the chart: cursor moves, a drag along the value
+ * axis for a value change (its end at the new value), a note, then a commit. Pure: the same
+ * scene and command give the same steps.
+ */
+declare function planChartCommand(spec: ChartSpec, scene: ChartScene, command: ChartAgentCommand, speed?: number): ChartPerformanceStep[];
+interface ChartDirectorOptions {
+    /** The scene as currently drawn (for cursor targets), e.g. the canvas' last layout. */
+    scene: () => ChartScene;
+    clock?: ChartClock;
+    /** 1 = natural speed; 2 = twice as fast. */
+    speed?: number;
+    /** Hide each actor's cursor this long after its last command (ms, default 1500; 0 keeps it). */
+    linger?: number;
+}
+interface ChartDirectorActor {
+    id: string;
+    name?: string;
+    color?: string;
+}
+type ChartPerformanceResult = {
+    ok: true;
+    command: ChartAgentCommand;
+} | {
+    ok: false;
+    command: ChartAgentCommand;
+    message: string;
+};
+/**
+ * Acts out agent commands on a chart: each actor's cursor moves to the target, drags values
+ * into place (the chart updates live) and the command commits as one undo step, while the
+ * user keeps editing. Commands queue per actor; a command whose target was deleted meanwhile
+ * fails with a sentence instead of editing something else.
+ */
+declare class ChartDirector {
+    private readonly controller;
+    readonly presence: ChartPresence;
+    private readonly options;
+    private readonly queues;
+    private readonly clock;
+    private calls;
+    constructor(controller: ChartController, presence: ChartPresence, options: ChartDirectorOptions);
+    /** Acts out `commands` in order for `actor`. Resolves with one result per command. */
+    perform(actor: ChartDirectorActor, commands: readonly ChartAgentCommand[]): Promise<ChartPerformanceResult[]>;
+    private stale;
+    private move;
+    private performOne;
+}
+
+type ParserCtor = {
+    new (): DOMParser;
+};
+interface ChartToolProviderOptions {
+    /** Provider id (unique per registry). Default `chart`. */
+    id?: string;
+    /** Always prefix tool names with `<namespace>__`. */
+    namespace?: string;
+    /**
+     * The chart cannot be edited: write tools are hidden and `get_chart` says why. A string
+     * is the reason ("The report is locked").
+     */
+    readOnly?: boolean | string | (() => boolean | string);
+    /** Size used for summaries, previews and pointer gestures (default 640 × 400). */
+    size?: {
+        width: number;
+        height: number;
+    };
+    /** Enables `import_chart_ooxml` (reading Office chart XML needs a DOMParser). Default: the global one, if any. */
+    DOMParser?: ParserCtor;
+    /**
+     * Acts out `set_chart_values` and `select_chart_element` with a visible cursor (see
+     * `ChartDirector`); each call is still one undo step. Without it, edits apply at once.
+     */
+    director?: ChartDirector;
+    /** Who the cursor belongs to (default `{ id: 'agent', name: 'Agent' }`). */
+    actor?: ChartDirectorActor;
+    /** Turns SVG into an image so `render_chart` can return PNG (e.g. through a canvas). */
+    rasterize?: (svg: string, size: {
+        width: number;
+        height: number;
+    }) => Promise<{
+        data: string;
+        mimeType: string;
+    }> | {
+        data: string;
+        mimeType: string;
+    };
+}
+/**
+ * Agent tools for a chart editor, for a `ToolRegistry`: one tool per operation with strict
+ * schemas. Reads (`get_chart`, `render_chart`, `check_chart_colors`, `recommend_chart`,
+ * `get_chart_trendline`, `list_chart_presets`, `export_chart_mermaid`, `export_chart_ooxml`)
+ * are always there; writes (data, series, categories, presentation, trendlines, presets,
+ * imports, selection, pointer and key input, undo / redo) are hidden while the chart is
+ * read-only. Every write is one undo step and returns what it changed.
+ */
+declare function createChartToolProvider(controller: ChartController, options?: ChartToolProviderOptions): AgentToolProvider;
+
+/**
+ * Reads JSON that is still arriving: closes open strings, arrays and objects and drops a
+ * dangling key or comma, so `{"type":"bar","series":[{"name":"A","values":[1,2` reads as far
+ * as it goes. Returns `undefined` when nothing usable has arrived yet.
+ */
+declare function parsePartialChartJson(text: string): unknown;
+type ChartStreamFormat = 'auto' | 'mermaid' | 'json';
+interface ChartStreamResult {
+    /** The chart as far as it has arrived, or `null` before anything can be drawn. */
+    spec: ChartSpec | null;
+    issues: ChartIssue[];
+    /**
+     * The value range to lay out with while incomplete: it only grows, so the axis does not
+     * jump as values arrive. `null` once complete (the chart's own scale takes over).
+     */
+    valueDomain: {
+        min: number;
+        max: number;
+    } | null;
+}
+/**
+ * Turns a chart source that is still being written (Mermaid or a JSON spec, e.g. streamed
+ * from a model) into drawable specs. Series appear once their values start, axis bounds only
+ * grow until `complete`, and parse problems are reported only once the source is complete.
+ */
+declare class ChartStream {
+    private readonly format;
+    private lo;
+    private hi;
+    private last;
+    constructor(format?: ChartStreamFormat);
+    /** Reads the source so far. `complete` when nothing more will arrive. */
+    update(source: string, complete?: boolean): ChartStreamResult;
+    /** Forgets the axis bounds (a new source). */
+    reset(): void;
+}
+/**
+ * A scene between two scenes, for animating changes (streamed data arriving, an agent's
+ * edit): marks are matched by `key`; numbers and same-shaped paths move from `from` to `to`;
+ * new marks fade in and marks that are gone are dropped. `t` runs from 0 to 1.
+ */
+declare function blendChartScenes(from: ChartScene | null, to: ChartScene, t: number): ChartScene;
+/** Ease-out cubic, for tweens. */
+declare const easeChartTween: (t: number) => number;
 
-export { CHART_CURVES, CHART_LEGEND_POSITIONS, CHART_NUMBER_STYLES, CHART_ORIENTATIONS, CHART_SERIES_TYPES, CHART_STACKINGS, CHART_TYPES, CHART_TYPE_LABELS, CSS_VARIABLE_CHART_THEME, type ChartActionResult, type ChartAxis, type ChartCircleMark, type ChartCommandOptions, ChartController, type ChartControllerOptions, type ChartCurve, type ChartEditOptions, type ChartIssue, type ChartKeyInput, type ChartLayoutOptions, type ChartLegend, type ChartLegendPosition, type ChartLineMark, type ChartMark, type ChartMarkRole, type ChartNumberFormat, type ChartOrientation, type ChartPathMark, type ChartPointDrag, type ChartRect, type ChartRectMark, type ChartScene, type ChartSelection, type ChartSeries, type ChartSeriesInput, type ChartSeriesPatch, type ChartSeriesType, type ChartSpec, type ChartSpecPatch, type ChartStacking, type ChartState, type ChartSvgOptions, type ChartTableData, type ChartTableOptions, type ChartTextMark, type ChartTextMeasure, type ChartTheme, type ChartType, type ChartValue, type ChartValueScale, DEFAULT_CHART_PALETTE, DEFAULT_CHART_THEME, type NiceScale, canDragChartPoint, chartClientToScene, chartColorInputValue, chartDataFromTable, chartDataToTable, chartSceneToSvg, chartSeriesColor, chartSeriesType, chartSliceColor, chartTextBaseline, chartTextTransform, chartToSvg, chartValueAtPoint, cloneChartSeries, cloneChartSpec, contrastingTextColor, createChartCommands, createChartController, createChartSpec, defaultChartAxis, describeChartSelection, estimateChartTextWidth, formatChartNumber, handleChartKey, isCartesianChart, layoutChart, linearMap, niceScale, niceStep, normalizeChartAxis, normalizeChartSpec, normalizeChartValues, parseChartValue, sameChartSelection, snapChartValue, startChartPointDrag, stepDecimals, uniqueChartSeriesId };
+export { CHART_COLOR_SCHEMES, CHART_DATE_STEPS, CHART_LAYOUT_PRESETS, CHART_MERMAID_META_PREFIX, CHART_OOXML_CONTENT_TYPE, CHART_OOXML_NS, CHART_OOXML_RELATIONSHIP, CHART_PALETTE_SHADES, CHART_PRESENCE_COLORS, type ChartAgentCommand, ChartAxis, type ChartBoxStats, type ChartClock, type ChartColorCheck, type ChartColorCheckOptions, type ChartColorPair, type ChartColorScheme, type ChartCommandOptions, ChartController, type ChartDateLabels, type ChartDateStep, ChartDirector, type ChartDirectorActor, type ChartDirectorOptions, type ChartDragMoveOptions, type ChartFormatCode, type ChartFromTable, type ChartHistogramBin, ChartIssue, type ChartKeyInput, ChartLayoutOptions, type ChartLayoutPreset, ChartLegend, type ChartMermaidFamily, type ChartMermaidOptions, type ChartMermaidParseOptions, type ChartMermaidResult, ChartNumberFormat, type ChartOoxmlReadOptions, type ChartOoxmlReadResult, type ChartOoxmlWriteResult, type ChartPerformanceResult, type ChartPerformanceStep, type ChartPointDrag, ChartPresence, type ChartPresenceActor, type ChartPresenceState, type ChartPresetPatch, type ChartRecommendation, ChartRect, type ChartRgb, ChartScene, ChartSelection, ChartSeries, type ChartSeriesSummary, type ChartSnapOptions, ChartSpec, ChartSpecPatch, ChartStacking, ChartStream, type ChartStreamFormat, type ChartStreamResult, type ChartSummary, type ChartTableShape, type ChartToolProviderOptions, ChartType, ChartValue, ChartValueScale, type ChartVision, ChartWarning, type FoundChartMermaid, MAX_CHART_DATA_LABELS, MAX_CHART_LINE_POINTS, MAX_CHART_MARKERS, type NiceScale, analyzeChartTable, blendChartScenes, canDragChartPoint, chartBoxStats, chartClientToScene, chartColorDistance, chartContrastRatio, chartDateLabels, chartDateToSerial, chartFormatToCode, chartFromMermaid, chartFromOoxml, chartFromTable, chartHistogram, chartHitTest, chartLuminance, chartMermaidFamily, chartPointAnchor, chartPresetPatch, chartQuantile, chartRgbToHex, chartRgbToOklab, chartSerialToDate, chartSquarify, chartTextOn, chartToMermaid, chartToOoxml, chartValueAtPoint, chartXAtPoint, checkChartColors, compileChartFormatCode, createChartCommands, createChartToolProvider, createInstantChartClock, cyclePaletteColor, decimateChartPoints, describeChart, describeChartSelection, easeChartTween, findMermaidCharts, formatChartDate, formatChartNumber, formatChartValueWithCode, handleChartKey, layoutChart, linearMap, monochromeChartPalette, niceScale, niceStep, parseChartColor, parseChartDate, parsePartialChartJson, planChartCommand, realChartClock, recommendChartTypes, recommendForShape, shadeChartColor, simulateChartVision, snapChartDragValue, snapChartValue, startChartPointDrag, stepDecimals, summarizeChart, summarizeChartSeries };