@pixerate/editor 0.162.1 → 0.164.0

package/dist/chart/layout-annotations.d.cts

@@ -0,0 +1,29 @@
+import { type LayoutCtx } from './layout-shared.cjs';
+import type { ScaleInfo } from './layout-cartesian.cjs';
+import type { ChartRect, ChartReferenceAxis, ChartSpec } from './types.cjs';
+/** Chart families that draw reference lines, bands and callouts. */
+export declare const chartAnnotationFamily: (family: string) => family is "cartesian" | "xy";
+/** Values the reference lines and bands on `axis` need the axis to reach. */
+export declare function referenceValues(spec: Pick<ChartSpec, 'referenceLines' | 'referenceBands'>, axis: ChartReferenceAxis): number[];
+/** One axis the references can be drawn on: its scale, and whether values run up the screen (`vertical`). */
+export interface ReferenceAxis {
+    info: ScaleInfo;
+    vertical: boolean;
+}
+/**
+ * Draws the reference bands (`layer` `bands`, under the data) or lines (`lines`, over it) on
+ * the axes given. References on an axis the chart does not have are skipped with a warning.
+ */
+export declare function drawReferences(ctx: LayoutCtx, plot: ChartRect, axes: Partial<Record<ChartReferenceAxis, ReferenceAxis>>, layer: 'bands' | 'lines'): void;
+/** Draws each series' callouts: a boxed label with a leader line to its bar or point, kept inside the plot and clear of the other callouts. */
+export declare function drawCallouts(ctx: LayoutCtx, plot: ChartRect): void;
+/**
+ * Mutes every data mark that `spec.highlight` does not name. A point stays bright when its
+ * category or its series is named; a whole series (line, area, legend entry) when it is named
+ * or no series is; a category when it is named or no category is.
+ */
+export declare function applyHighlight(ctx: LayoutCtx): void;
+/** Height the note takes at the bottom of the chart (0 without one). */
+export declare const noteHeight: (spec: ChartSpec, fs: number) => number;
+/** Writes the note along the bottom left, shortened to the width. */
+export declare function drawNote(ctx: LayoutCtx, pad: number): void;

package/dist/chart/layout-annotations.d.ts

@@ -0,0 +1,29 @@
+import { type LayoutCtx } from './layout-shared.js';
+import type { ScaleInfo } from './layout-cartesian.js';
+import type { ChartRect, ChartReferenceAxis, ChartSpec } from './types.js';
+/** Chart families that draw reference lines, bands and callouts. */
+export declare const chartAnnotationFamily: (family: string) => family is "cartesian" | "xy";
+/** Values the reference lines and bands on `axis` need the axis to reach. */
+export declare function referenceValues(spec: Pick<ChartSpec, 'referenceLines' | 'referenceBands'>, axis: ChartReferenceAxis): number[];
+/** One axis the references can be drawn on: its scale, and whether values run up the screen (`vertical`). */
+export interface ReferenceAxis {
+    info: ScaleInfo;
+    vertical: boolean;
+}
+/**
+ * Draws the reference bands (`layer` `bands`, under the data) or lines (`lines`, over it) on
+ * the axes given. References on an axis the chart does not have are skipped with a warning.
+ */
+export declare function drawReferences(ctx: LayoutCtx, plot: ChartRect, axes: Partial<Record<ChartReferenceAxis, ReferenceAxis>>, layer: 'bands' | 'lines'): void;
+/** Draws each series' callouts: a boxed label with a leader line to its bar or point, kept inside the plot and clear of the other callouts. */
+export declare function drawCallouts(ctx: LayoutCtx, plot: ChartRect): void;
+/**
+ * Mutes every data mark that `spec.highlight` does not name. A point stays bright when its
+ * category or its series is named; a whole series (line, area, legend entry) when it is named
+ * or no series is; a category when it is named or no category is.
+ */
+export declare function applyHighlight(ctx: LayoutCtx): void;
+/** Height the note takes at the bottom of the chart (0 without one). */
+export declare const noteHeight: (spec: ChartSpec, fs: number) => number;
+/** Writes the note along the bottom left, shortened to the width. */
+export declare function drawNote(ctx: LayoutCtx, pad: number): void;

package/dist/chart/layout-families.d.cts

@@ -15,3 +15,26 @@ export declare function layoutFunnel(ctx: LayoutCtx, area: ChartRect, series: Ch
 /** Treemap: the first series' positive values as nested rectangles (squarified), labelled where they fit. */
 export declare function layoutTreemap(ctx: LayoutCtx, area: ChartRect, series: ChartSeries): FamilyResult;
 export type { ChartMark };
+/** Slope: each category's value in the first series (left) joined to the second (right), labelled at both ends. */
+export declare function layoutSlope(ctx: LayoutCtx, area: ChartRect, visible: ChartSeries[]): FamilyResult;
+/**
+ * Likert: one diverging bar per category (a question), the series (answers) from most negative
+ * to most positive, as shares of the question's total. Negative answers run left of the centre
+ * line, positive ones right; with an odd number of answers the middle one straddles the centre
+ * (`likertNeutral: 'split'`) or is drawn in its own column (`separate`).
+ */
+export declare function layoutLikert(ctx: LayoutCtx, area: ChartRect, visible: ChartSeries[]): FamilyResult;
+/** Parliament: the first series as seats in a hemicycle (rows of dots), one colour per category, with the majority line and the total. */
+export declare function layoutParliament(ctx: LayoutCtx, area: ChartRect, series: ChartSeries): FamilyResult;
+/**
+ * Treemap of `spec.tree`: each group a rectangle sized by its total, its children squarified
+ * inside under a header with its name, down to the leaves. Everything in a top-level group is
+ * drawn in its colour (leaves in lighter and darker shades) and selects that category.
+ */
+export declare function layoutTreemapTree(ctx: LayoutCtx, area: ChartRect, series: ChartSeries | undefined): FamilyResult;
+/**
+ * Sunburst: `spec.tree` as rings from the centre out, each node an arc sized by its total
+ * inside its parent's arc (without a tree, the first series as one ring). Labels go on arcs
+ * wide enough for them; the total and `sunburstLabel` sit in the centre.
+ */
+export declare function layoutSunburst(ctx: LayoutCtx, area: ChartRect, series: ChartSeries | undefined): FamilyResult;

package/dist/chart/layout-families.d.ts

@@ -15,3 +15,26 @@ export declare function layoutFunnel(ctx: LayoutCtx, area: ChartRect, series: Ch
 /** Treemap: the first series' positive values as nested rectangles (squarified), labelled where they fit. */
 export declare function layoutTreemap(ctx: LayoutCtx, area: ChartRect, series: ChartSeries): FamilyResult;
 export type { ChartMark };
+/** Slope: each category's value in the first series (left) joined to the second (right), labelled at both ends. */
+export declare function layoutSlope(ctx: LayoutCtx, area: ChartRect, visible: ChartSeries[]): FamilyResult;
+/**
+ * Likert: one diverging bar per category (a question), the series (answers) from most negative
+ * to most positive, as shares of the question's total. Negative answers run left of the centre
+ * line, positive ones right; with an odd number of answers the middle one straddles the centre
+ * (`likertNeutral: 'split'`) or is drawn in its own column (`separate`).
+ */
+export declare function layoutLikert(ctx: LayoutCtx, area: ChartRect, visible: ChartSeries[]): FamilyResult;
+/** Parliament: the first series as seats in a hemicycle (rows of dots), one colour per category, with the majority line and the total. */
+export declare function layoutParliament(ctx: LayoutCtx, area: ChartRect, series: ChartSeries): FamilyResult;
+/**
+ * Treemap of `spec.tree`: each group a rectangle sized by its total, its children squarified
+ * inside under a header with its name, down to the leaves. Everything in a top-level group is
+ * drawn in its colour (leaves in lighter and darker shades) and selects that category.
+ */
+export declare function layoutTreemapTree(ctx: LayoutCtx, area: ChartRect, series: ChartSeries | undefined): FamilyResult;
+/**
+ * Sunburst: `spec.tree` as rings from the centre out, each node an arc sized by its total
+ * inside its parent's arc (without a tree, the first series as one ring). Labels go on arcs
+ * wide enough for them; the total and `sunburstLabel` sit in the centre.
+ */
+export declare function layoutSunburst(ctx: LayoutCtx, area: ChartRect, series: ChartSeries | undefined): FamilyResult;

package/dist/chart/mermaid.d.cts

@@ -12,7 +12,8 @@ export interface ChartMermaidOptions {
 export 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
+ * scatters drawn as lines; slopes and Likert charts as lines and bars), `pie` for pies, donuts,
+ * funnels, treemaps and parliaments, `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.

package/dist/chart/mermaid.d.ts

@@ -12,7 +12,8 @@ export interface ChartMermaidOptions {
 export 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
+ * scatters drawn as lines; slopes and Likert charts as lines and bars), `pie` for pies, donuts,
+ * funnels, treemaps and parliaments, `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.

package/dist/chart/schemas.d.cts

@@ -7,6 +7,19 @@ export declare const HEIGHT: JsonSchema;
 export declare const FORMAT: JsonSchema;
 export declare const AXIS: (what: string) => JsonSchema;
 export declare const TRENDLINE_PROPS: Record<string, JsonSchema>;
+/** A reference line's fields; `value` is required when adding. */
+export declare const REFERENCE_LINE_PROPS: Record<string, JsonSchema>;
+/** A reference band's fields; `from` and `to` are required when adding. */
+export declare const REFERENCE_BAND_PROPS: Record<string, JsonSchema>;
+export declare const REFERENCE_LINE_PATCH: Record<string, JsonSchema>;
+export declare const REFERENCE_BAND_PATCH: Record<string, JsonSchema>;
+export declare const REFERENCE_INDEX: (what: string) => JsonSchema;
+/** A tree node, recursive through `#/$defs/chartTreeNode` (tool schemas that use it carry `TREE_DEFS`). */
+export declare const TREE_NODE: JsonSchema;
+export declare const TREE_DEFS: {
+    chartTreeNode: JsonSchema;
+};
+export declare const TREE_PATH: JsonSchema;
 export declare const ERROR_BARS: (what: string) => JsonSchema;
 export declare const SERIES_PROPS: Record<string, JsonSchema>;
 export declare const CHART_UPDATE_PROPERTIES: Record<string, JsonSchema>;

package/dist/chart/schemas.d.ts

@@ -7,6 +7,19 @@ export declare const HEIGHT: JsonSchema;
 export declare const FORMAT: JsonSchema;
 export declare const AXIS: (what: string) => JsonSchema;
 export declare const TRENDLINE_PROPS: Record<string, JsonSchema>;
+/** A reference line's fields; `value` is required when adding. */
+export declare const REFERENCE_LINE_PROPS: Record<string, JsonSchema>;
+/** A reference band's fields; `from` and `to` are required when adding. */
+export declare const REFERENCE_BAND_PROPS: Record<string, JsonSchema>;
+export declare const REFERENCE_LINE_PATCH: Record<string, JsonSchema>;
+export declare const REFERENCE_BAND_PATCH: Record<string, JsonSchema>;
+export declare const REFERENCE_INDEX: (what: string) => JsonSchema;
+/** A tree node, recursive through `#/$defs/chartTreeNode` (tool schemas that use it carry `TREE_DEFS`). */
+export declare const TREE_NODE: JsonSchema;
+export declare const TREE_DEFS: {
+    chartTreeNode: JsonSchema;
+};
+export declare const TREE_PATH: JsonSchema;
 export declare const ERROR_BARS: (what: string) => JsonSchema;
 export declare const SERIES_PROPS: Record<string, JsonSchema>;
 export declare const CHART_UPDATE_PROPERTIES: Record<string, JsonSchema>;

package/dist/chart/spec.d.cts

@@ -1,4 +1,4 @@
-import type { ChartAxis, ChartCurve, ChartErrorBars, ChartIssue, ChartLabelPosition, ChartLegendPosition, ChartMarker, ChartNumberFormat, ChartOrientation, ChartRadarGraticule, ChartSeries, ChartSeriesType, ChartSpec, ChartStacking, ChartTheme, ChartTrendline, ChartTrendlineType, ChartType, ChartValue } from './types.cjs';
+import type { ChartAxis, ChartCurve, ChartErrorBars, ChartIssue, ChartLabelPosition, ChartLegendPosition, ChartLikertNeutral, ChartLikertSort, ChartMarker, ChartNumberFormat, ChartOrientation, ChartRadarGraticule, ChartReferenceAxis, ChartReferenceBand, ChartReferenceLine, ChartSeries, ChartSeriesType, ChartSpec, ChartStacking, ChartTheme, ChartTrendline, ChartTrendlineType, ChartType, ChartValue } from './types.cjs';
 export declare const CHART_TYPES: readonly ChartType[];
 export declare const CHART_MARKERS: readonly ChartMarker[];
 export declare const CHART_TRENDLINE_TYPES: readonly ChartTrendlineType[];
@@ -9,13 +9,16 @@ export declare const CHART_SERIES_TYPES: readonly ChartSeriesType[];
 export declare const CHART_STACKINGS: readonly ChartStacking[];
 export declare const CHART_CURVES: readonly ChartCurve[];
 export declare const CHART_RADAR_GRATICULES: readonly ChartRadarGraticule[];
+export declare const CHART_LIKERT_NEUTRALS: readonly ChartLikertNeutral[];
+export declare const CHART_LIKERT_SORTS: readonly ChartLikertSort[];
+export declare const CHART_REFERENCE_AXES: readonly ChartReferenceAxis[];
 export declare const CHART_ORIENTATIONS: readonly ChartOrientation[];
 export declare const CHART_LEGEND_POSITIONS: readonly ChartLegendPosition[];
 export declare const CHART_NUMBER_STYLES: readonly NonNullable<ChartNumberFormat['style']>[];
 /** Labels for pickers, shared by the React and Svelte components. */
 export declare const CHART_TYPE_LABELS: Readonly<Record<ChartType, string>>;
 /** How a chart type is laid out. */
-export type ChartFamily = 'cartesian' | 'xy' | 'pie' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap';
+export type ChartFamily = 'cartesian' | 'xy' | 'pie' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst';
 /** A colour-blind-friendly categorical palette (Okabe–Ito order, tuned for light and dark backgrounds). */
 export declare const DEFAULT_CHART_PALETTE: readonly string[];
 export declare const DEFAULT_CHART_THEME: ChartTheme;
@@ -33,15 +36,33 @@ export declare function isXyChart(spec: Pick<ChartSpec, 'type' | 'series'>): boo
 export declare function chartFamily(spec: Pick<ChartSpec, 'type' | 'series'>): ChartFamily;
 /** Chart types whose legend lists categories (one colour per category) rather than series. */
 export declare function chartColorsByCategory(type: ChartType): boolean;
+/** Whether this chart colours by category: a pie-like type, or `varyColors` on a one-series chart. */
+export declare function chartSpecColorsByCategory(spec: Pick<ChartSpec, 'type' | 'series'> & {
+    varyColors?: boolean;
+}): boolean;
 export declare function defaultChartAxis(value: boolean): ChartAxis;
 /** A complete spec with every default filled in. */
 export declare function createChartSpec(partial?: Partial<ChartSpec>): ChartSpec;
 /** The colour a series is drawn with. */
-export declare function chartSeriesColor(spec: Pick<ChartSpec, 'palette' | 'series'>, seriesIndex: number): string;
+export declare function chartSeriesColor(spec: Pick<ChartSpec, 'palette' | 'series'> & {
+    type?: ChartType;
+}, seriesIndex: number): string;
+/**
+ * The colour of answer `index` of `count` on a Likert chart: oranges for the negative half
+ * (darkest first), grey for a middle answer, purples for the positive half (darkest last).
+ */
+export declare function chartLikertColor(count: number, index: number): string;
 /** The colour a pie slice is drawn with (by category). */
 export declare function chartSliceColor(spec: Pick<ChartSpec, 'palette'>, index: number): string;
-/** The colour of one bar or point: its override, else the series colour. */
-export declare function chartPointColor(spec: Pick<ChartSpec, 'palette' | 'series'>, seriesIndex: number, index: number): string;
+/** Whether `varyColors` applies: a bar, line, area or scatter chart with one visible series. */
+export declare function chartVariesColors(spec: Pick<ChartSpec, 'type' | 'series'> & {
+    varyColors?: boolean;
+}): boolean;
+/** The colour of one bar or point: its override, else the palette colour of its category (`varyColors`), else the series colour. */
+export declare function chartPointColor(spec: Pick<ChartSpec, 'palette' | 'series'> & {
+    type?: ChartType;
+    varyColors?: boolean;
+}, seriesIndex: number, index: number): string;
 /** How a series is drawn in a cartesian chart. */
 export declare function chartSeriesType(spec: Pick<ChartSpec, 'type'>, series: ChartSeries): ChartSeriesType;
 /** An id not used by any series (`series-1`, `series-2`, …). */
@@ -54,6 +75,10 @@ export declare function parseChartValue(input: unknown): ChartValue | undefined;
 export declare function normalizeChartAxis(value: unknown, fallback: ChartAxis, path: string, issues?: ChartIssue[]): ChartAxis;
 /** Values as numbers or nulls; bad entries become null and are reported. */
 export declare function normalizeChartValues(value: unknown, length: number | undefined, path: string, issues?: ChartIssue[]): ChartValue[];
+/** Checks one reference line; `null` (reported) when it has no usable value. */
+export declare function normalizeChartReferenceLine(value: unknown, path: string, issues?: ChartIssue[]): ChartReferenceLine | null;
+/** Checks one reference band; `null` (reported) when its ends are not numbers. Ends are put in order. */
+export declare function normalizeChartReferenceBand(value: unknown, path: string, issues?: ChartIssue[]): ChartReferenceBand | null;
 /** Checks one set of error bars; `null` (reported) when it is unusable. Custom amounts are padded to `length`. */
 export declare function normalizeChartErrorBars(value: unknown, length: number, path: string, issues?: ChartIssue[]): ChartErrorBars | null;
 /** Checks one trendline; `null` (reported) when it is unusable. */

package/dist/chart/spec.d.ts

@@ -1,4 +1,4 @@
-import type { ChartAxis, ChartCurve, ChartErrorBars, ChartIssue, ChartLabelPosition, ChartLegendPosition, ChartMarker, ChartNumberFormat, ChartOrientation, ChartRadarGraticule, ChartSeries, ChartSeriesType, ChartSpec, ChartStacking, ChartTheme, ChartTrendline, ChartTrendlineType, ChartType, ChartValue } from './types.js';
+import type { ChartAxis, ChartCurve, ChartErrorBars, ChartIssue, ChartLabelPosition, ChartLegendPosition, ChartLikertNeutral, ChartLikertSort, ChartMarker, ChartNumberFormat, ChartOrientation, ChartRadarGraticule, ChartReferenceAxis, ChartReferenceBand, ChartReferenceLine, ChartSeries, ChartSeriesType, ChartSpec, ChartStacking, ChartTheme, ChartTrendline, ChartTrendlineType, ChartType, ChartValue } from './types.js';
 export declare const CHART_TYPES: readonly ChartType[];
 export declare const CHART_MARKERS: readonly ChartMarker[];
 export declare const CHART_TRENDLINE_TYPES: readonly ChartTrendlineType[];
@@ -9,13 +9,16 @@ export declare const CHART_SERIES_TYPES: readonly ChartSeriesType[];
 export declare const CHART_STACKINGS: readonly ChartStacking[];
 export declare const CHART_CURVES: readonly ChartCurve[];
 export declare const CHART_RADAR_GRATICULES: readonly ChartRadarGraticule[];
+export declare const CHART_LIKERT_NEUTRALS: readonly ChartLikertNeutral[];
+export declare const CHART_LIKERT_SORTS: readonly ChartLikertSort[];
+export declare const CHART_REFERENCE_AXES: readonly ChartReferenceAxis[];
 export declare const CHART_ORIENTATIONS: readonly ChartOrientation[];
 export declare const CHART_LEGEND_POSITIONS: readonly ChartLegendPosition[];
 export declare const CHART_NUMBER_STYLES: readonly NonNullable<ChartNumberFormat['style']>[];
 /** Labels for pickers, shared by the React and Svelte components. */
 export declare const CHART_TYPE_LABELS: Readonly<Record<ChartType, string>>;
 /** How a chart type is laid out. */
-export type ChartFamily = 'cartesian' | 'xy' | 'pie' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap';
+export type ChartFamily = 'cartesian' | 'xy' | 'pie' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst';
 /** A colour-blind-friendly categorical palette (Okabe–Ito order, tuned for light and dark backgrounds). */
 export declare const DEFAULT_CHART_PALETTE: readonly string[];
 export declare const DEFAULT_CHART_THEME: ChartTheme;
@@ -33,15 +36,33 @@ export declare function isXyChart(spec: Pick<ChartSpec, 'type' | 'series'>): boo
 export declare function chartFamily(spec: Pick<ChartSpec, 'type' | 'series'>): ChartFamily;
 /** Chart types whose legend lists categories (one colour per category) rather than series. */
 export declare function chartColorsByCategory(type: ChartType): boolean;
+/** Whether this chart colours by category: a pie-like type, or `varyColors` on a one-series chart. */
+export declare function chartSpecColorsByCategory(spec: Pick<ChartSpec, 'type' | 'series'> & {
+    varyColors?: boolean;
+}): boolean;
 export declare function defaultChartAxis(value: boolean): ChartAxis;
 /** A complete spec with every default filled in. */
 export declare function createChartSpec(partial?: Partial<ChartSpec>): ChartSpec;
 /** The colour a series is drawn with. */
-export declare function chartSeriesColor(spec: Pick<ChartSpec, 'palette' | 'series'>, seriesIndex: number): string;
+export declare function chartSeriesColor(spec: Pick<ChartSpec, 'palette' | 'series'> & {
+    type?: ChartType;
+}, seriesIndex: number): string;
+/**
+ * The colour of answer `index` of `count` on a Likert chart: oranges for the negative half
+ * (darkest first), grey for a middle answer, purples for the positive half (darkest last).
+ */
+export declare function chartLikertColor(count: number, index: number): string;
 /** The colour a pie slice is drawn with (by category). */
 export declare function chartSliceColor(spec: Pick<ChartSpec, 'palette'>, index: number): string;
-/** The colour of one bar or point: its override, else the series colour. */
-export declare function chartPointColor(spec: Pick<ChartSpec, 'palette' | 'series'>, seriesIndex: number, index: number): string;
+/** Whether `varyColors` applies: a bar, line, area or scatter chart with one visible series. */
+export declare function chartVariesColors(spec: Pick<ChartSpec, 'type' | 'series'> & {
+    varyColors?: boolean;
+}): boolean;
+/** The colour of one bar or point: its override, else the palette colour of its category (`varyColors`), else the series colour. */
+export declare function chartPointColor(spec: Pick<ChartSpec, 'palette' | 'series'> & {
+    type?: ChartType;
+    varyColors?: boolean;
+}, seriesIndex: number, index: number): string;
 /** How a series is drawn in a cartesian chart. */
 export declare function chartSeriesType(spec: Pick<ChartSpec, 'type'>, series: ChartSeries): ChartSeriesType;
 /** An id not used by any series (`series-1`, `series-2`, …). */
@@ -54,6 +75,10 @@ export declare function parseChartValue(input: unknown): ChartValue | undefined;
 export declare function normalizeChartAxis(value: unknown, fallback: ChartAxis, path: string, issues?: ChartIssue[]): ChartAxis;
 /** Values as numbers or nulls; bad entries become null and are reported. */
 export declare function normalizeChartValues(value: unknown, length: number | undefined, path: string, issues?: ChartIssue[]): ChartValue[];
+/** Checks one reference line; `null` (reported) when it has no usable value. */
+export declare function normalizeChartReferenceLine(value: unknown, path: string, issues?: ChartIssue[]): ChartReferenceLine | null;
+/** Checks one reference band; `null` (reported) when its ends are not numbers. Ends are put in order. */
+export declare function normalizeChartReferenceBand(value: unknown, path: string, issues?: ChartIssue[]): ChartReferenceBand | null;
 /** Checks one set of error bars; `null` (reported) when it is unusable. Custom amounts are padded to `length`. */
 export declare function normalizeChartErrorBars(value: unknown, length: number, path: string, issues?: ChartIssue[]): ChartErrorBars | null;
 /** Checks one trendline; `null` (reported) when it is unusable. */

package/dist/chart/stats.d.cts

@@ -1,4 +1,4 @@
-import type { ChartRect, ChartValue } from './types.cjs';
+import type { ChartRect, ChartReferenceBand, ChartReferenceLine, ChartSpec, ChartValue } from './types.cjs';
 export interface ChartHistogramBin {
     /** Lower edge (exclusive, except for the first bin). */
     from: number;
@@ -14,6 +14,14 @@ export interface ChartHistogramBin {
 export 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)`). */
 export declare function chartQuantile(sorted: readonly number[], q: number): number;
+/**
+ * Starting points for a new reference line and band, from the visible values on the primary
+ * axis: a line at their average and a band over their middle half (first to third quartile).
+ */
+export declare function suggestChartReferences(spec: Pick<ChartSpec, 'series'>): {
+    line: ChartReferenceLine;
+    band: ChartReferenceBand;
+};
 export interface ChartBoxStats {
     min: number;
     max: number;

package/dist/chart/stats.d.ts

@@ -1,4 +1,4 @@
-import type { ChartRect, ChartValue } from './types.js';
+import type { ChartRect, ChartReferenceBand, ChartReferenceLine, ChartSpec, ChartValue } from './types.js';
 export interface ChartHistogramBin {
     /** Lower edge (exclusive, except for the first bin). */
     from: number;
@@ -14,6 +14,14 @@ export interface ChartHistogramBin {
 export 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)`). */
 export declare function chartQuantile(sorted: readonly number[], q: number): number;
+/**
+ * Starting points for a new reference line and band, from the visible values on the primary
+ * axis: a line at their average and a band over their middle half (first to third quartile).
+ */
+export declare function suggestChartReferences(spec: Pick<ChartSpec, 'series'>): {
+    line: ChartReferenceLine;
+    band: ChartReferenceBand;
+};
 export interface ChartBoxStats {
     min: number;
     max: number;

package/dist/chart/tools.d.cts

@@ -54,7 +54,7 @@ export declare const RENDER_CHART_INSTRUCTIONS = "Draws the chart without changi
  * 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,
+ * are always there; writes (data, series, categories, presentation, trendlines, reference lines and bands, callouts, highlight, 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.
  */

package/dist/chart/tools.d.ts

@@ -54,7 +54,7 @@ export declare const RENDER_CHART_INSTRUCTIONS = "Draws the chart without changi
  * 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,
+ * are always there; writes (data, series, categories, presentation, trendlines, reference lines and bands, callouts, highlight, 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.
  */

package/dist/chart/tree.d.cts

@@ -0,0 +1,62 @@
+import type { ChartIssue, ChartTreeNode } from './types.cjs';
+/** Deepest tree the editor keeps (a sunburst draws one ring per level). */
+export declare const MAX_CHART_TREE_DEPTH = 6;
+/** Most nodes a tree may have. */
+export declare const MAX_CHART_TREE_NODES = 5000;
+/**
+ * Checks a tree: every node has a name unique among its siblings, leaves have a value of 0 or
+ * more, groups have children. Problems are reported with the node's path and the node is
+ * dropped (or its value set to 0), so the rest of the tree is kept.
+ */
+export declare function normalizeChartTree(value: unknown, issues?: ChartIssue[], path?: string): ChartTreeNode[];
+/** The value of a node: its own, or the sum of its leaves. */
+export declare function chartTreeTotal(node: ChartTreeNode): number;
+/** Levels in the tree (1 for a flat list of leaves, 0 for none). */
+export declare function chartTreeDepth(tree: readonly ChartTreeNode[]): number;
+/** The node at a path of names from the top, or undefined. */
+export declare function findChartTreeNode(tree: readonly ChartTreeNode[], path: readonly string[]): ChartTreeNode | undefined;
+/** One leaf as a row: the names from the top down to it, and its value. */
+export interface ChartTreeRow {
+    path: string[];
+    value: number;
+}
+/** Every leaf of the tree as a row, in order (the tree as a table: group, …, name, value). */
+export declare function chartTreeToRows(tree: readonly ChartTreeNode[]): ChartTreeRow[];
+/**
+ * Builds a tree from rows of names and a value: rows that share leading names share those
+ * groups, in the order they first appear. Empty names end a path. A name that is both a leaf
+ * and a group, or a repeated path, is reported; the first wins.
+ */
+export declare function chartTreeFromRows(rows: readonly {
+    path: readonly unknown[];
+    value: unknown;
+}[], issues?: ChartIssue[]): ChartTreeNode[];
+/**
+ * Reads a table as a tree: every column but the last holds names (group, subgroup, …, item),
+ * the last holds the value. Blank names repeat the name above (as spreadsheets lay out groups).
+ * With `header` (default `auto`: when the first row's last cell is not a number) the first row
+ * is skipped.
+ */
+export declare function chartTreeFromTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: {
+    header?: boolean | 'auto';
+}, issues?: ChartIssue[]): ChartTreeNode[];
+/** A flat tree (one leaf per category) from labels and values, for starting to group a table. */
+export declare function chartTreeFromSeries(categories: readonly string[], values: readonly (number | null)[]): ChartTreeNode[];
+/** A deep copy. */
+export declare function cloneChartTree(tree: readonly ChartTreeNode[]): ChartTreeNode[];
+/** Column headings for a tree table `depth` levels deep: Group, Level 2, …, Item. */
+export declare function chartTreeColumnLabels(depth: number): string[];
+/** Rows with the name at `level` of row `row` set (shorter paths are padded with blanks; a blank name ends the path there). */
+export declare function setChartTreeRowName(rows: readonly ChartTreeRow[], row: number, level: number, name: string): {
+    path: string[];
+    value: unknown;
+}[];
+/** Rows with row `row`'s value set (text is parsed by `setTreeRows`). */
+export declare function setChartTreeRowValue(rows: readonly ChartTreeRow[], row: number, value: unknown): {
+    path: string[];
+    value: unknown;
+}[];
+/** Rows with a new item after the last row, in the same group, named "Item n" (unique there), value 0. */
+export declare function addChartTreeRow(rows: readonly ChartTreeRow[]): ChartTreeRow[];
+/** Rows without row `row`. */
+export declare function removeChartTreeRow(rows: readonly ChartTreeRow[], row: number): ChartTreeRow[];

package/dist/chart/tree.d.ts

@@ -0,0 +1,62 @@
+import type { ChartIssue, ChartTreeNode } from './types.js';
+/** Deepest tree the editor keeps (a sunburst draws one ring per level). */
+export declare const MAX_CHART_TREE_DEPTH = 6;
+/** Most nodes a tree may have. */
+export declare const MAX_CHART_TREE_NODES = 5000;
+/**
+ * Checks a tree: every node has a name unique among its siblings, leaves have a value of 0 or
+ * more, groups have children. Problems are reported with the node's path and the node is
+ * dropped (or its value set to 0), so the rest of the tree is kept.
+ */
+export declare function normalizeChartTree(value: unknown, issues?: ChartIssue[], path?: string): ChartTreeNode[];
+/** The value of a node: its own, or the sum of its leaves. */
+export declare function chartTreeTotal(node: ChartTreeNode): number;
+/** Levels in the tree (1 for a flat list of leaves, 0 for none). */
+export declare function chartTreeDepth(tree: readonly ChartTreeNode[]): number;
+/** The node at a path of names from the top, or undefined. */
+export declare function findChartTreeNode(tree: readonly ChartTreeNode[], path: readonly string[]): ChartTreeNode | undefined;
+/** One leaf as a row: the names from the top down to it, and its value. */
+export interface ChartTreeRow {
+    path: string[];
+    value: number;
+}
+/** Every leaf of the tree as a row, in order (the tree as a table: group, …, name, value). */
+export declare function chartTreeToRows(tree: readonly ChartTreeNode[]): ChartTreeRow[];
+/**
+ * Builds a tree from rows of names and a value: rows that share leading names share those
+ * groups, in the order they first appear. Empty names end a path. A name that is both a leaf
+ * and a group, or a repeated path, is reported; the first wins.
+ */
+export declare function chartTreeFromRows(rows: readonly {
+    path: readonly unknown[];
+    value: unknown;
+}[], issues?: ChartIssue[]): ChartTreeNode[];
+/**
+ * Reads a table as a tree: every column but the last holds names (group, subgroup, …, item),
+ * the last holds the value. Blank names repeat the name above (as spreadsheets lay out groups).
+ * With `header` (default `auto`: when the first row's last cell is not a number) the first row
+ * is skipped.
+ */
+export declare function chartTreeFromTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: {
+    header?: boolean | 'auto';
+}, issues?: ChartIssue[]): ChartTreeNode[];
+/** A flat tree (one leaf per category) from labels and values, for starting to group a table. */
+export declare function chartTreeFromSeries(categories: readonly string[], values: readonly (number | null)[]): ChartTreeNode[];
+/** A deep copy. */
+export declare function cloneChartTree(tree: readonly ChartTreeNode[]): ChartTreeNode[];
+/** Column headings for a tree table `depth` levels deep: Group, Level 2, …, Item. */
+export declare function chartTreeColumnLabels(depth: number): string[];
+/** Rows with the name at `level` of row `row` set (shorter paths are padded with blanks; a blank name ends the path there). */
+export declare function setChartTreeRowName(rows: readonly ChartTreeRow[], row: number, level: number, name: string): {
+    path: string[];
+    value: unknown;
+}[];
+/** Rows with row `row`'s value set (text is parsed by `setTreeRows`). */
+export declare function setChartTreeRowValue(rows: readonly ChartTreeRow[], row: number, value: unknown): {
+    path: string[];
+    value: unknown;
+}[];
+/** Rows with a new item after the last row, in the same group, named "Item n" (unique there), value 0. */
+export declare function addChartTreeRow(rows: readonly ChartTreeRow[]): ChartTreeRow[];
+/** Rows without row `row`. */
+export declare function removeChartTreeRow(rows: readonly ChartTreeRow[], row: number): ChartTreeRow[];