@pixerate/editor 0.46.0 → 0.47.0

package/dist/chart/index.d.ts

@@ -1,225 +1,16 @@
+import { C as ChartAxis, a as ChartCurve, b as ChartLabelPosition, c as ChartLegendPosition, d as ChartMarker, e as ChartNumberFormat, f as ChartOrientation, g as ChartSeriesType, h as ChartStacking, i as ChartTrendlineType, j as ChartType, k as ChartTheme, l as ChartSeries, m as ChartIssue, n as ChartSpec, o as ChartTrendline, p as ChartValue, q as ChartRect, r as ChartSelection, s as ChartScene, t as ChartTextMark, u as ChartWarning, v as ChartLegend, w as ChartValueScale } from '../types-BVqWm3d1.js';
+export { x as ChartCircleMark, y as ChartLineMark, z as ChartMark, A as ChartMarkRole, B as ChartPathMark, D as ChartRectMark } from '../types-BVqWm3d1.js';
 import { H as HistoryManager } from '../HistoryManager-DWSLd6Tf.js';
-import { C as CommandSpec } from '../registry-BfVD-vVg.js';
+import { C as CommandSpec } from '../registry-rVtFJjRM.js';
+import { A as AgentToolProvider } from '../registry-CSlH4iUn.js';
 import '../types-DsiXGmjo.js';
 import '../schema-Di0CS6Pe.js';
 
-/** 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_MARKERS: readonly ChartMarker[];
+declare const CHART_TRENDLINE_TYPES: readonly ChartTrendlineType[];
+declare const CHART_LABEL_POSITIONS: readonly ChartLabelPosition[];
+declare const CHART_AXIS_KINDS: readonly NonNullable<ChartAxis['kind']>[];
 declare const CHART_SERIES_TYPES: readonly ChartSeriesType[];
 declare const CHART_STACKINGS: readonly ChartStacking[];
 declare const CHART_CURVES: readonly ChartCurve[];
@@ -228,6 +19,8 @@ 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>>;
+/** How a chart type is laid out. */
+type ChartFamily = 'cartesian' | 'xy' | 'pie' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap';
 /** 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;
@@ -237,7 +30,14 @@ declare const DEFAULT_CHART_THEME: ChartTheme;
  * inline styles use them), with light fallbacks. The React and Svelte canvases use it.
  */
 declare const CSS_VARIABLE_CHART_THEME: ChartTheme;
+/** Bar, line, area and scatter: categories (or numeric x) against values, series may mix. */
 declare function isCartesianChart(type: ChartType): boolean;
+/** Whether the chart plots series against a numeric x axis (bubble charts, and scatter charts with x values). */
+declare function isXyChart(spec: Pick<ChartSpec, 'type' | 'series'>): boolean;
+/** How a chart is laid out (see `ChartType`). */
+declare function chartFamily(spec: Pick<ChartSpec, 'type' | 'series'>): ChartFamily;
+/** Chart types whose legend lists categories (one colour per category) rather than series. */
+declare function chartColorsByCategory(type: ChartType): boolean;
 declare function defaultChartAxis(value: boolean): ChartAxis;
 /** A complete spec with every default filled in. */
 declare function createChartSpec(partial?: Partial<ChartSpec>): ChartSpec;
@@ -245,6 +45,8 @@ declare function createChartSpec(partial?: Partial<ChartSpec>): ChartSpec;
 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;
+/** The colour of one bar or point: its override, else the series colour. */
+declare function chartPointColor(spec: Pick<ChartSpec, 'palette' | 'series'>, seriesIndex: number, 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`, …). */
@@ -257,6 +59,8 @@ 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[];
+/** Checks one trendline; `null` (reported) when it is unusable. */
+declare function normalizeChartTrendline(value: unknown, path: string, issues?: ChartIssue[]): ChartTrendline | null;
 /**
  * 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
@@ -276,8 +80,16 @@ interface ChartTableOptions {
      * 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;
+    /**
+     * The first row (or column for `rows`) holds series names (default `true`). `auto`: only
+     * when one of its value cells is not a number.
+     */
+    header?: boolean | 'auto';
+    /**
+     * Read the first column as numeric x values (scatter and bubble charts): every series gets
+     * them as `x`, and the categories are their labels.
+     */
+    xFromFirstColumn?: boolean;
 }
 interface ChartTableData {
     categories: string[];
@@ -310,7 +122,7 @@ interface NiceScale {
  * inside them.
  */
 declare function niceScale(min: number, max: number, count?: number, fixedMin?: number | null, fixedMax?: number | null): NiceScale;
-/** Decimals needed to tell ticks `step` apart (at most 6). */
+/** Decimals needed to write ticks `step` apart exactly: 1 → 0, 2.5 → 1, 0.25 → 2 (at most 6). */
 declare function stepDecimals(step: number): number;
 /**
  * Writes a number for a chart label. Locale-independent (so labels and tests are the same
@@ -321,6 +133,266 @@ 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;
 
+/**
+ * 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;
+}
+/** 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[];
+/**
+ * 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 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;
+
+/**
+ * A fitted regression trendline. Exponential, logarithmic and power fits are linear fits of
+ * transformed data (`ln y ~ x`, `y ~ ln x`, `ln y ~ ln x`), as spreadsheets document them;
+ * points the transform cannot take (values ≤ 0) are skipped, and R² is for the transformed fit.
+ */
+interface ChartTrendFit {
+    type: Exclude<ChartTrendlineType, 'moving-average'>;
+    /** Coefficients `c0…cd` of `Y = Σ cₖ·Xᵏ` in the transformed variables. */
+    coefficients: number[];
+    /** Coefficient of determination; `null` when undefined (all y equal). */
+    r2: number | null;
+    /** The equation as a label, e.g. `y = 0.5x² - 2x + 1` or `y = 3e^(0.2x)`. */
+    equation: string;
+    /** Number of points used. */
+    points: number;
+    /** The fitted y at `x`, or `null` outside the fit's domain (x ≤ 0 for log and power). */
+    evaluate(x: number): number | null;
+}
+/**
+ * Fits `trendline` to the points. Returns `null` for moving averages (see
+ * `chartMovingAverage`) and degenerate data: too few usable points, all x equal, or a
+ * singular system.
+ */
+declare function fitChartTrendline(trendline: ChartTrendline, points: ReadonlyArray<readonly [number, number]>): ChartTrendFit | null;
+/** A coefficient as trendline labels show it: up to four decimals, scientific when tiny or huge. */
+declare function trendNumberText(v: number): string;
+/**
+ * Moving average of `period` consecutive points in plotted order: point `i` (from
+ * `period - 1`) is `(xᵢ, mean(yᵢ₋ₚ₊₁ … yᵢ))`. Empty when there are fewer points than `period`.
+ */
+declare function chartMovingAverage(points: ReadonlyArray<readonly [number, number]>, period: number): [number, number][];
+/** The legend name spreadsheets give a trendline, e.g. `Linear (Sales)`. */
+declare function chartTrendlineName(trendline: ChartTrendline, seriesName: string): string;
+/** Whether trendlines can be drawn for this chart type and stacking (unstacked cartesian and xy charts). */
+declare function chartSupportsTrendlines(type: string, stacking: string): boolean;
+
 type ChartTextMeasure = (text: string, size: number, weight?: number) => number;
 interface ChartLayoutOptions {
     width: number;
@@ -332,28 +404,71 @@ interface ChartLayoutOptions {
     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;
+    /** Fixes the secondary value axis the same way (`ChartPointDrag.valueDomain2`). */
+    valueDomain2?: {
+        min: number;
+        max: number;
+    } | null;
+    /** Fixes the numeric x axis of a scatter or bubble chart (`ChartPointDrag.xDomain`). */
+    xDomain?: {
+        min: number;
+        max: number;
+    } | null;
+    /** Shows the value of this point next to it (a `drag-readout` text mark, kept inside the plot). */
+    readout?: {
+        seriesId: string;
+        index: number;
+    } | null;
 }
 /** 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;
+/**
+ * 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.
+ */
+declare function contrastingTextColor(fill: string): string;
+
 /**
  * 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;
+
+/** 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;
 
 /** SVG `dominant-baseline` for a text mark's baseline (shared by every renderer). */
 declare function chartTextBaseline(baseline: ChartTextMark['baseline']): 'hanging' | 'central' | 'text-after-edge';
@@ -364,12 +479,170 @@ interface ChartSvgOptions {
     hideSelection?: boolean;
     /** Accessible title (default: the chart title). */
     ariaLabel?: string;
+    /** A longer description written as `<desc>` (`chartToSvg` defaults to `describeChart`). */
+    description?: 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;
 
+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;
+
+type ChartSparklineKind = 'line' | 'column' | 'win-loss';
+interface ChartSparklineOptions {
+    kind?: ChartSparklineKind;
+    width: number;
+    height: number;
+    /** Line, positive column and win colour (default the first palette colour). */
+    color?: string;
+    /** Negative column and loss colour (default red). */
+    negativeColor?: string;
+    /** Dots on every line point (thinned past 500). */
+    markers?: boolean;
+    /** Highlight the highest and lowest point of a line (or column). */
+    highLow?: boolean;
+    /** Fixed value range (default: the data, including 0 for columns). */
+    min?: number;
+    max?: number;
+}
+/**
+ * Lays out a word-sized chart (a sparkline) as marks: a line broken at gaps, columns
+ * (negatives in `negativeColor`) or win/loss bars of equal height. Long lines are thinned past
+ * 4000 points. Returns a scene with no axes, legend or targets.
+ */
+declare function layoutSparkline(values: readonly ChartValue[], options: ChartSparklineOptions): ChartScene;
+/** A sparkline as a standalone SVG string (e.g. for an inline image in rich text). */
+declare function sparklineToSvg(values: readonly ChartValue[], options: ChartSparklineOptions & {
+    ariaLabel?: string;
+}): 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;
+};
+
+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;
+}
+/**
+ * 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;
+}
+/**
+ * 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 ChartControllerOptions {
     /** Starting chart (any partial or saved spec; problems are reported in `state.issues`). */
     spec?: Partial<ChartSpec> | unknown;
@@ -382,7 +655,7 @@ interface ChartControllerOptions {
 interface ChartState {
     spec: Readonly<ChartSpec>;
     selection: ChartSelection | null;
-    /** The series the selection belongs to (a series or one of its points). */
+    /** The series the selection belongs to (a series, one of its points or one of its trendlines). */
     selectedSeries: ChartSeries | null;
     /** The category the selection belongs to (a category or a point). */
     selectedIndex: number | null;
@@ -405,9 +678,10 @@ type ChartActionResult = {
     issues?: ChartIssue[];
 };
 /** Top-level fields with partial axes and legend. */
-type ChartSpecPatch = Partial<Omit<ChartSpec, 'version' | 'xAxis' | 'yAxis' | 'legend'>> & {
+type ChartSpecPatch = Partial<Omit<ChartSpec, 'version' | 'xAxis' | 'yAxis' | 'yAxis2' | 'legend'>> & {
     xAxis?: Partial<ChartAxis>;
     yAxis?: Partial<ChartAxis>;
+    yAxis2?: Partial<ChartAxis>;
     legend?: Partial<ChartLegend>;
 };
 interface ChartSeriesInput {
@@ -417,7 +691,17 @@ interface ChartSeriesInput {
     color?: string;
     type?: ChartSeriesType;
     hidden?: boolean;
+    axis?: 'primary' | 'secondary';
+    x?: readonly unknown[];
+    sizes?: readonly unknown[];
+    pointColors?: readonly (string | null)[];
+    marker?: ChartMarker;
+    curve?: ChartCurve;
+    dataLabels?: boolean;
+    format?: ChartNumberFormat;
+    trendlines?: readonly ChartTrendline[];
 }
+/** Changes to one series; `null` resets a field to the chart's default. */
 interface ChartSeriesPatch {
     name?: string;
     /** `null` goes back to the palette colour. */
@@ -425,6 +709,14 @@ interface ChartSeriesPatch {
     /** `null` follows the chart type. */
     type?: ChartSeriesType | null;
     hidden?: boolean;
+    axis?: 'primary' | 'secondary' | null;
+    x?: readonly unknown[] | null;
+    sizes?: readonly unknown[] | null;
+    pointColors?: readonly (string | null)[] | null;
+    marker?: ChartMarker | null;
+    curve?: ChartCurve | null;
+    dataLabels?: boolean | null;
+    format?: ChartNumberFormat | null;
 }
 interface ChartEditOptions {
     /** Undo step label. */
@@ -444,6 +736,7 @@ declare class ChartController {
     private issues;
     private gestureKey;
     private gestureCount;
+    private gestureStart;
     private revision;
     private applying;
     private readonly onChange?;
@@ -478,8 +771,16 @@ declare class ChartController {
     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;
+    /** Changes the category (`x`), value (`y`) or secondary value (`y2`) axis. */
+    setAxis(axis: 'x' | 'y' | 'y2', patch: Partial<ChartAxis>): ChartActionResult;
+    /**
+     * Applies a named quick layout and / or colour scheme (see `CHART_LAYOUT_PRESETS` and
+     * `CHART_COLOR_SCHEMES`) as one undo step.
+     */
+    applyPreset(options: {
+        layout?: string;
+        colors?: string;
+    }): ChartActionResult;
     setLegend(patch: Partial<ChartLegend>): ChartActionResult;
     /**
      * Replaces categories and / or series as one undo step. Values are validated and padded
@@ -547,6 +848,30 @@ declare class ChartController {
     }): ChartActionResult & {
         issues?: ChartIssue[];
     };
+    /** Adds a trendline to a series and selects it. Returns its index (and the fit, when it can be computed). */
+    addTrendline(seriesId: string, input: ChartTrendline): {
+        ok: true;
+        index: number;
+        fit: ChartTrendFit | null;
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Changes a trendline (all-or-nothing). */
+    updateTrendline(seriesId: string, index: number, patch: Partial<ChartTrendline>): ChartActionResult;
+    removeTrendline(seriesId: string, index: number): ChartActionResult;
+    /** The points a series' trendlines are fitted to: (x, y) with x = 1, 2, 3 … on category charts. */
+    trendlinePoints(seriesId: string): [number, number][];
+    /** The fitted coefficients, R² and equation of a trendline (null for moving averages or unfittable data). */
+    trendlineFit(seriesId: string, index: number): ChartTrendFit | null;
+    /** The moving-average points of a trendline (empty for other kinds). */
+    trendlineMovingAverage(seriesId: string, index: number): [number, number][];
+    /**
+     * Switches rows and columns: series become categories and categories become series (one
+     * undo step). Series colours, types and other per-series settings are dropped.
+     */
+    transpose(): ChartActionResult;
     /** Selects a chart element (view state; not an undo step). */
     select(selection: ChartSelection | null): void;
     /**
@@ -558,6 +883,11 @@ declare class ChartController {
     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;
+    /**
+     * Cancels the gesture in progress (Escape during a drag): everything it changed is taken
+     * back and leaves no undo or redo step.
+     */
+    cancelGesture(): void;
     endGesture(): void;
     /** The spec, for saving (a copy). */
     toJSON(): ChartSpec;
@@ -585,9 +915,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[];
 
@@ -601,30 +934,85 @@ 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`)
+     * until `end()` so the axis does not rescale under the pointer.
+     */
+    readonly valueDomain: {
+        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;
 }
 /**
- * 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.
+ * 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 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;
@@ -635,12 +1023,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, createChartCommands, createChartController, createChartSpec, defaultChartAxis, describeChartSelection, estimateChartTextWidth, formatChartNumber, handleChartKey, isCartesianChart, layoutChart, linearMap, niceScale, niceStep, normalizeChartAxis, normalizeChartSpec, normalizeChartValues, parseChartValue, sameChartSelection, snapChartValue, startChartPointDrag, stepDecimals, uniqueChartSeriesId };
+export { CHART_AXIS_KINDS, CHART_COLOR_SCHEMES, CHART_CURVES, CHART_DATE_STEPS, CHART_LABEL_POSITIONS, CHART_LAYOUT_PRESETS, CHART_LEGEND_POSITIONS, CHART_MARKERS, CHART_MERMAID_META_PREFIX, CHART_NUMBER_STYLES, CHART_OOXML_CONTENT_TYPE, CHART_OOXML_NS, CHART_OOXML_RELATIONSHIP, CHART_ORIENTATIONS, CHART_PALETTE_SHADES, CHART_PRESENCE_COLORS, CHART_SERIES_TYPES, CHART_STACKINGS, CHART_TRENDLINE_TYPES, CHART_TYPES, CHART_TYPE_LABELS, CSS_VARIABLE_CHART_THEME, type ChartActionResult, type ChartAgentCommand, ChartAxis, type ChartBoxStats, type ChartClock, type ChartColorCheck, type ChartColorCheckOptions, type ChartColorPair, type ChartColorScheme, type ChartCommandOptions, ChartController, type ChartControllerOptions, ChartCurve, type ChartDateLabels, type ChartDateStep, ChartDirector, type ChartDirectorActor, type ChartDirectorOptions, type ChartDragMoveOptions, type ChartEditOptions, type ChartFamily, type ChartFormatCode, type ChartFromTable, type ChartHistogramBin, ChartIssue, type ChartKeyInput, ChartLabelPosition, type ChartLayoutOptions, type ChartLayoutPreset, ChartLegend, ChartLegendPosition, ChartMarker, type ChartMermaidFamily, type ChartMermaidOptions, type ChartMermaidParseOptions, type ChartMermaidResult, ChartNumberFormat, type ChartOoxmlReadOptions, type ChartOoxmlReadResult, type ChartOoxmlWriteResult, ChartOrientation, type ChartPerformanceResult, type ChartPerformanceStep, type ChartPointDrag, ChartPresence, type ChartPresenceActor, type ChartPresenceState, type ChartPresetPatch, type ChartRecommendation, ChartRect, type ChartRgb, ChartScene, ChartSelection, ChartSeries, type ChartSeriesInput, type ChartSeriesPatch, type ChartSeriesSummary, ChartSeriesType, type ChartSnapOptions, type ChartSparklineKind, type ChartSparklineOptions, ChartSpec, type ChartSpecPatch, ChartStacking, type ChartState, ChartStream, type ChartStreamFormat, type ChartStreamResult, type ChartSummary, type ChartSvgOptions, type ChartTableData, type ChartTableOptions, type ChartTableShape, ChartTextMark, type ChartTextMeasure, ChartTheme, type ChartToolProviderOptions, type ChartTrendFit, ChartTrendline, ChartTrendlineType, ChartType, ChartValue, ChartValueScale, type ChartVision, ChartWarning, DEFAULT_CHART_PALETTE, DEFAULT_CHART_THEME, type FoundChartMermaid, MAX_CHART_DATA_LABELS, MAX_CHART_LINE_POINTS, MAX_CHART_MARKERS, type NiceScale, analyzeChartTable, blendChartScenes, canDragChartPoint, chartBoxStats, chartClientToScene, chartColorDistance, chartColorInputValue, chartColorsByCategory, chartContrastRatio, chartDataFromTable, chartDataToTable, chartDateLabels, chartDateToSerial, chartFamily, chartFormatToCode, chartFromMermaid, chartFromOoxml, chartFromTable, chartHistogram, chartHitTest, chartLuminance, chartMermaidFamily, chartMovingAverage, chartPointAnchor, chartPointColor, chartPresetPatch, chartQuantile, chartRgbToHex, chartRgbToOklab, chartSceneToSvg, chartSerialToDate, chartSeriesColor, chartSeriesType, chartSliceColor, chartSquarify, chartSupportsTrendlines, chartTextBaseline, chartTextOn, chartTextTransform, chartToMermaid, chartToOoxml, chartToSvg, chartTrendlineName, chartValueAtPoint, chartXAtPoint, checkChartColors, cloneChartSeries, cloneChartSpec, compileChartFormatCode, contrastingTextColor, createChartCommands, createChartController, createChartSpec, createChartToolProvider, createInstantChartClock, cyclePaletteColor, decimateChartPoints, defaultChartAxis, describeChart, describeChartSelection, easeChartTween, estimateChartTextWidth, findMermaidCharts, fitChartTrendline, formatChartDate, formatChartNumber, formatChartValueWithCode, handleChartKey, isCartesianChart, isXyChart, layoutChart, layoutSparkline, linearMap, monochromeChartPalette, niceScale, niceStep, normalizeChartAxis, normalizeChartSpec, normalizeChartTrendline, normalizeChartValues, parseChartColor, parseChartDate, parseChartValue, parsePartialChartJson, planChartCommand, realChartClock, recommendChartTypes, recommendForShape, sameChartSelection, shadeChartColor, simulateChartVision, snapChartDragValue, snapChartValue, sparklineToSvg, startChartPointDrag, stepDecimals, summarizeChart, summarizeChartSeries, trendNumberText, uniqueChartSeriesId };