@pixerate/editor 0.164.0 → 0.166.0

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

@@ -38,3 +38,17 @@ export declare function layoutTreemapTree(ctx: LayoutCtx, area: ChartRect, serie
  * wide enough for them; the total and `sunburstLabel` sit in the centre.
  */
 export declare function layoutSunburst(ctx: LayoutCtx, area: ChartRect, series: ChartSeries | undefined): FamilyResult;
+/**
+ * Sankey: `spec.links` as flows between columns of nodes. A node's column is the longest chain
+ * of flows into it, and nodes nothing flows out of line up in the last column. Node heights and
+ * flow widths share one scale (the tightest column fills the height); flows leave and arrive
+ * in the order of the nodes at their other end, so they cross as little as the order allows.
+ */
+export declare function layoutSankey(ctx: LayoutCtx, area: ChartRect, series: ChartSeries | undefined): FamilyResult;
+/**
+ * Bar race: the top `raceTopN` names at one moment (`frame`, a fractional category index;
+ * default the last time point) as ranked horizontal bars. Values ease between time points and
+ * places slide from one ranking to the next, so drawing frame after frame (or blending scenes,
+ * which match bars by series) animates the race. The time point is written large in a corner.
+ */
+export declare function layoutBarRace(ctx: LayoutCtx, area: ChartRect, frame: number | null | undefined): FamilyResult;

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

@@ -38,3 +38,17 @@ export declare function layoutTreemapTree(ctx: LayoutCtx, area: ChartRect, serie
  * wide enough for them; the total and `sunburstLabel` sit in the centre.
  */
 export declare function layoutSunburst(ctx: LayoutCtx, area: ChartRect, series: ChartSeries | undefined): FamilyResult;
+/**
+ * Sankey: `spec.links` as flows between columns of nodes. A node's column is the longest chain
+ * of flows into it, and nodes nothing flows out of line up in the last column. Node heights and
+ * flow widths share one scale (the tightest column fills the height); flows leave and arrive
+ * in the order of the nodes at their other end, so they cross as little as the order allows.
+ */
+export declare function layoutSankey(ctx: LayoutCtx, area: ChartRect, series: ChartSeries | undefined): FamilyResult;
+/**
+ * Bar race: the top `raceTopN` names at one moment (`frame`, a fractional category index;
+ * default the last time point) as ranked horizontal bars. Values ease between time points and
+ * places slide from one ranking to the next, so drawing frame after frame (or blending scenes,
+ * which match bars by series) animates the race. The time point is written large in a corner.
+ */
+export declare function layoutBarRace(ctx: LayoutCtx, area: ChartRect, frame: number | null | undefined): FamilyResult;

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

@@ -34,6 +34,11 @@ export interface ChartLayoutOptions {
         seriesId: string;
         index: number;
     } | null;
+    /**
+     * Bar race: the moment to draw, as a category index that may be fractional (2.5 is halfway
+     * between the third and fourth time points). Default: the last time point.
+     */
+    raceFrame?: number | null;
 }
 /** A DOM-free text width estimate (average glyph ≈ 0.56 em, bold ≈ 0.6 em). */
 export declare const estimateChartTextWidth: ChartTextMeasure;

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

@@ -34,6 +34,11 @@ export interface ChartLayoutOptions {
         seriesId: string;
         index: number;
     } | null;
+    /**
+     * Bar race: the moment to draw, as a category index that may be fractional (2.5 is halfway
+     * between the third and fourth time points). Default: the last time point.
+     */
+    raceFrame?: number | null;
 }
 /** A DOM-free text width estimate (average glyph ≈ 0.56 em, bold ≈ 0.6 em). */
 export declare const estimateChartTextWidth: ChartTextMeasure;

package/dist/chart/links.d.cts

@@ -0,0 +1,34 @@
+import type { ChartIssue, ChartLink } from './types.cjs';
+/** Most flows a chart may have. */
+export declare const MAX_CHART_LINKS = 2000;
+/**
+ * Checks flows: each has a source and a target (different names) and a value above 0, a pair
+ * appears once, and flows only go forwards (a flow that would close a loop is dropped, since a
+ * Sankey diagram cannot draw one). Problems are reported with the flow's index.
+ */
+export declare function normalizeChartLinks(value: unknown, issues?: ChartIssue[], path?: string): ChartLink[];
+/**
+ * The nodes of a set of flows, in `order` first (names no flow uses are reported and dropped),
+ * then any others as the flows first name them.
+ */
+export declare function chartSankeyNodes(links: readonly ChartLink[], order?: readonly string[], issues?: ChartIssue[]): string[];
+/** How much flows through each node: the larger of what comes in and what goes out. */
+export declare function chartSankeyNodeValues(links: readonly ChartLink[], nodes: readonly string[]): number[];
+/**
+ * Reads flows from a table of source, target and value columns. With `header` (default
+ * `auto`: when the first row's third cell is not a number) the first row is skipped.
+ */
+export declare function chartLinksFromTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: {
+    header?: boolean | 'auto';
+}): {
+    source: unknown;
+    target: unknown;
+    value: unknown;
+}[];
+/** Flows with one field of flow `index` set to `text` (for the data grids; `setLinks` checks the result). */
+export declare function setChartLinkField(links: readonly ChartLink[], index: number, field: 'source' | 'target' | 'value', text: string): Record<string, unknown>[];
+/**
+ * Flows with a new one at the end: from the last flow's target (or "Start") to a new node
+ * named "Step n", carrying the last flow's value (or 1).
+ */
+export declare function addChartLink(links: readonly ChartLink[]): ChartLink[];

package/dist/chart/links.d.ts

@@ -0,0 +1,34 @@
+import type { ChartIssue, ChartLink } from './types.js';
+/** Most flows a chart may have. */
+export declare const MAX_CHART_LINKS = 2000;
+/**
+ * Checks flows: each has a source and a target (different names) and a value above 0, a pair
+ * appears once, and flows only go forwards (a flow that would close a loop is dropped, since a
+ * Sankey diagram cannot draw one). Problems are reported with the flow's index.
+ */
+export declare function normalizeChartLinks(value: unknown, issues?: ChartIssue[], path?: string): ChartLink[];
+/**
+ * The nodes of a set of flows, in `order` first (names no flow uses are reported and dropped),
+ * then any others as the flows first name them.
+ */
+export declare function chartSankeyNodes(links: readonly ChartLink[], order?: readonly string[], issues?: ChartIssue[]): string[];
+/** How much flows through each node: the larger of what comes in and what goes out. */
+export declare function chartSankeyNodeValues(links: readonly ChartLink[], nodes: readonly string[]): number[];
+/**
+ * Reads flows from a table of source, target and value columns. With `header` (default
+ * `auto`: when the first row's third cell is not a number) the first row is skipped.
+ */
+export declare function chartLinksFromTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: {
+    header?: boolean | 'auto';
+}): {
+    source: unknown;
+    target: unknown;
+    value: unknown;
+}[];
+/** Flows with one field of flow `index` set to `text` (for the data grids; `setLinks` checks the result). */
+export declare function setChartLinkField(links: readonly ChartLink[], index: number, field: 'source' | 'target' | 'value', text: string): Record<string, unknown>[];
+/**
+ * Flows with a new one at the end: from the last flow's target (or "Start") to a new node
+ * named "Step n", carrying the last flow's value (or 1).
+ */
+export declare function addChartLink(links: readonly ChartLink[]): ChartLink[];

package/dist/chart/mermaid.d.cts

@@ -1,7 +1,7 @@
 import type { ChartIssue, ChartSpec } from './types.cjs';
 /** The comment line that carries what Mermaid cannot express. Every Mermaid tool ignores `%%` comments. */
 export declare const CHART_MERMAID_META_PREFIX = "%% @pixerate ";
-export type ChartMermaidFamily = 'xychart' | 'pie' | 'radar';
+export type ChartMermaidFamily = 'xychart' | 'pie' | 'radar' | 'sankey' | 'treemap';
 export interface ChartMermaidOptions {
     /** Write the `%% @pixerate {…}` line so the chart round-trips exactly (default `true`). */
     meta?: boolean;
@@ -9,12 +9,15 @@ export interface ChartMermaidOptions {
     indent?: string;
 }
 /** The Mermaid family a chart is written as. */
-export declare function chartMermaidFamily(spec: Pick<ChartSpec, 'type' | 'series'>): ChartMermaidFamily;
+export declare function chartMermaidFamily(spec: Pick<ChartSpec, 'type' | 'series'> & {
+    links?: ChartSpec['links'];
+}): ChartMermaidFamily;
 /**
  * Writes a chart as Mermaid: `xychart-beta` for bar, line, area and scatter charts (areas and
  * 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
+ * funnels and parliaments, `radar-beta` for radars, `sankey-beta` for Sankey diagrams with
+ * flows, and `treemap-beta` for treemaps and sunbursts (their groups, or one item per category).
+ * Sankey titles go in frontmatter, which `sankey-beta` needs. 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.
  */
@@ -34,7 +37,7 @@ export interface ChartMermaidResult {
     hasMeta: boolean;
 }
 /**
- * Reads Mermaid `xychart-beta`, `pie` or `radar-beta` text as a chart. Never throws: lines it
+ * Reads Mermaid `xychart-beta`, `pie`, `radar-beta`, `sankey-beta` or `treemap-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.
  */
@@ -47,6 +50,6 @@ export interface FoundChartMermaid {
 }
 /**
  * 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.
+ * fences) whose header is xychart-beta, pie, radar-beta, sankey-beta or treemap-beta, else the whole text when it is one.
  */
 export declare function findMermaidCharts(text: string): FoundChartMermaid[];

package/dist/chart/mermaid.d.ts

@@ -1,7 +1,7 @@
 import type { ChartIssue, ChartSpec } from './types.js';
 /** The comment line that carries what Mermaid cannot express. Every Mermaid tool ignores `%%` comments. */
 export declare const CHART_MERMAID_META_PREFIX = "%% @pixerate ";
-export type ChartMermaidFamily = 'xychart' | 'pie' | 'radar';
+export type ChartMermaidFamily = 'xychart' | 'pie' | 'radar' | 'sankey' | 'treemap';
 export interface ChartMermaidOptions {
     /** Write the `%% @pixerate {…}` line so the chart round-trips exactly (default `true`). */
     meta?: boolean;
@@ -9,12 +9,15 @@ export interface ChartMermaidOptions {
     indent?: string;
 }
 /** The Mermaid family a chart is written as. */
-export declare function chartMermaidFamily(spec: Pick<ChartSpec, 'type' | 'series'>): ChartMermaidFamily;
+export declare function chartMermaidFamily(spec: Pick<ChartSpec, 'type' | 'series'> & {
+    links?: ChartSpec['links'];
+}): ChartMermaidFamily;
 /**
  * Writes a chart as Mermaid: `xychart-beta` for bar, line, area and scatter charts (areas and
  * 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
+ * funnels and parliaments, `radar-beta` for radars, `sankey-beta` for Sankey diagrams with
+ * flows, and `treemap-beta` for treemaps and sunbursts (their groups, or one item per category).
+ * Sankey titles go in frontmatter, which `sankey-beta` needs. 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.
  */
@@ -34,7 +37,7 @@ export interface ChartMermaidResult {
     hasMeta: boolean;
 }
 /**
- * Reads Mermaid `xychart-beta`, `pie` or `radar-beta` text as a chart. Never throws: lines it
+ * Reads Mermaid `xychart-beta`, `pie`, `radar-beta`, `sankey-beta` or `treemap-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.
  */
@@ -47,6 +50,6 @@ export interface FoundChartMermaid {
 }
 /**
  * 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.
+ * fences) whose header is xychart-beta, pie, radar-beta, sankey-beta or treemap-beta, else the whole text when it is one.
  */
 export declare function findMermaidCharts(text: string): FoundChartMermaid[];

package/dist/chart/race.d.cts

@@ -0,0 +1,26 @@
+import type { ChartSeries, ChartSpec } from './types.cjs';
+/** A series' value at time point `index`: its own, else the last value before it (0 before the first). */
+export declare function chartRaceValueAt(series: Pick<ChartSeries, 'values'>, index: number): number;
+/** The moment `frame` stands for: the time points either side and how far between them (0–1). */
+export declare function chartRaceMoment(count: number, frame: number | null | undefined): {
+    from: number;
+    to: number;
+    t: number;
+    at: number;
+};
+export interface ChartRaceEntry {
+    seriesId: string;
+    name: string;
+    /** The value at the moment (between time points, eased from one to the next). */
+    value: number;
+    /** 0-based place at the moment, fractional while two names swap. */
+    position: number;
+    /** 0-based place at the nearest time point. */
+    rank: number;
+}
+/**
+ * Every visible series at a moment, best first: its value between the two time points and its
+ * position, which slides from its rank at one time point to its rank at the next so bars swap
+ * smoothly. Ties keep the series order.
+ */
+export declare function chartRaceRanking(spec: Pick<ChartSpec, 'series' | 'categories'>, frame: number | null | undefined): ChartRaceEntry[];

package/dist/chart/race.d.ts

@@ -0,0 +1,26 @@
+import type { ChartSeries, ChartSpec } from './types.js';
+/** A series' value at time point `index`: its own, else the last value before it (0 before the first). */
+export declare function chartRaceValueAt(series: Pick<ChartSeries, 'values'>, index: number): number;
+/** The moment `frame` stands for: the time points either side and how far between them (0–1). */
+export declare function chartRaceMoment(count: number, frame: number | null | undefined): {
+    from: number;
+    to: number;
+    t: number;
+    at: number;
+};
+export interface ChartRaceEntry {
+    seriesId: string;
+    name: string;
+    /** The value at the moment (between time points, eased from one to the next). */
+    value: number;
+    /** 0-based place at the moment, fractional while two names swap. */
+    position: number;
+    /** 0-based place at the nearest time point. */
+    rank: number;
+}
+/**
+ * Every visible series at a moment, best first: its value between the two time points and its
+ * position, which slides from its rank at one time point to its rank at the next so bars swap
+ * smoothly. Ties keep the series order.
+ */
+export declare function chartRaceRanking(spec: Pick<ChartSpec, 'series' | 'categories'>, frame: number | null | undefined): ChartRaceEntry[];

package/dist/chart/schemas.d.cts

@@ -20,6 +20,11 @@ export declare const TREE_DEFS: {
     chartTreeNode: JsonSchema;
 };
 export declare const TREE_PATH: JsonSchema;
+/** One Sankey flow's fields; source, target and value are required when adding. */
+export declare const LINK_PROPS: Record<string, JsonSchema>;
+/** A moment of a bar race: a time point by label, or a category index (fractional between time points). */
+export declare const RACE_TIME: JsonSchema;
+export declare const LINK_INDEX: 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

@@ -20,6 +20,11 @@ export declare const TREE_DEFS: {
     chartTreeNode: JsonSchema;
 };
 export declare const TREE_PATH: JsonSchema;
+/** One Sankey flow's fields; source, target and value are required when adding. */
+export declare const LINK_PROPS: Record<string, JsonSchema>;
+/** A moment of a bar race: a time point by label, or a category index (fractional between time points). */
+export declare const RACE_TIME: JsonSchema;
+export declare const LINK_INDEX: 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, ChartLikertNeutral, ChartLikertSort, ChartMarker, ChartNumberFormat, ChartOrientation, ChartRadarGraticule, ChartReferenceAxis, ChartReferenceBand, ChartReferenceLine, 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, ChartSankeyLinkColor, 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[];
@@ -11,6 +11,7 @@ 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_SANKEY_LINK_COLORS: readonly ChartSankeyLinkColor[];
 export declare const CHART_REFERENCE_AXES: readonly ChartReferenceAxis[];
 export declare const CHART_ORIENTATIONS: readonly ChartOrientation[];
 export declare const CHART_LEGEND_POSITIONS: readonly ChartLegendPosition[];
@@ -18,7 +19,7 @@ export declare const CHART_NUMBER_STYLES: readonly NonNullable<ChartNumberFormat
 /** 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' | 'slope' | 'likert' | 'parliament' | 'sunburst';
+export type ChartFamily = 'cartesian' | 'xy' | 'pie' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey' | 'barrace';
 /** 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;

package/dist/chart/spec.d.ts

@@ -1,4 +1,4 @@
-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';
+import type { ChartAxis, ChartCurve, ChartErrorBars, ChartIssue, ChartLabelPosition, ChartLegendPosition, ChartLikertNeutral, ChartLikertSort, ChartMarker, ChartNumberFormat, ChartOrientation, ChartRadarGraticule, ChartReferenceAxis, ChartReferenceBand, ChartReferenceLine, ChartSankeyLinkColor, 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[];
@@ -11,6 +11,7 @@ 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_SANKEY_LINK_COLORS: readonly ChartSankeyLinkColor[];
 export declare const CHART_REFERENCE_AXES: readonly ChartReferenceAxis[];
 export declare const CHART_ORIENTATIONS: readonly ChartOrientation[];
 export declare const CHART_LEGEND_POSITIONS: readonly ChartLegendPosition[];
@@ -18,7 +19,7 @@ export declare const CHART_NUMBER_STYLES: readonly NonNullable<ChartNumberFormat
 /** 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' | 'slope' | 'likert' | 'parliament' | 'sunburst';
+export type ChartFamily = 'cartesian' | 'xy' | 'pie' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey' | 'barrace';
 /** 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;

package/dist/chart/style.d.cts

@@ -0,0 +1,33 @@
+/**
+ * House style for charts: the `chart.json` profile (palette, allowed colour schemes and
+ * layouts, theme, defaults for new charts), its checks, and `check_chart_style`.
+ */
+import type { AgentToolProvider } from '../tools/registry.cjs';
+import type { StyleDomain, StyleResolver } from '../tools/style.cjs';
+import type { ChartSpec } from './types.cjs';
+import type { ChartController } from './controller.cjs';
+/** A chart's `chart.json` house-style profile, after `$token` references are resolved. */
+export interface ChartStyleProfile {
+    /** Series colours in order: the house palette. */
+    palette?: string[];
+    /** `CHART_COLOR_SCHEMES` ids allowed besides the palette. */
+    colorSchemes?: string[];
+    /** `CHART_LAYOUT_PRESETS` ids allowed. */
+    layouts?: string[];
+    /** Colours and type to draw charts with (the `theme` option of the chart renderers). */
+    theme?: Partial<Record<'background' | 'surface' | 'text' | 'mutedText' | 'grid' | 'axis' | 'positive' | 'negative' | 'fontFamily', string> & Record<'fontSize' | 'titleSize', number>>;
+    /** Spec values new charts start from. */
+    defaults?: Partial<Pick<ChartSpec, 'dataLabels' | 'points' | 'curve' | 'stacking' | 'orientation' | 'labelPosition'>>;
+}
+/** The chart house-style domain: register it with `createStyleResolver({ domains })`. */
+export declare const chartStyleDomain: StyleDomain<ChartSpec>;
+/** The spec patch that starts a chart in the house style: the palette and the defaults. */
+export declare function chartStylePatch(profile: Readonly<Record<string, unknown>>): Partial<ChartSpec>;
+export interface ChartStyleToolProviderOptions {
+    /** Provider id (unique per registry). Default `chart-style`. */
+    id?: string;
+    /** Tool-name prefix; defaults to `chart`, so `check_chart_style` joins the chart toolset. */
+    namespace?: string;
+}
+/** `check_chart_style`: runs the chart house-style checks against a chart. */
+export declare function createChartStyleToolProvider(controller: ChartController, styles: StyleResolver, options?: ChartStyleToolProviderOptions): AgentToolProvider;

package/dist/chart/style.d.ts

@@ -0,0 +1,33 @@
+/**
+ * House style for charts: the `chart.json` profile (palette, allowed colour schemes and
+ * layouts, theme, defaults for new charts), its checks, and `check_chart_style`.
+ */
+import type { AgentToolProvider } from '../tools/registry.js';
+import type { StyleDomain, StyleResolver } from '../tools/style.js';
+import type { ChartSpec } from './types.js';
+import type { ChartController } from './controller.js';
+/** A chart's `chart.json` house-style profile, after `$token` references are resolved. */
+export interface ChartStyleProfile {
+    /** Series colours in order: the house palette. */
+    palette?: string[];
+    /** `CHART_COLOR_SCHEMES` ids allowed besides the palette. */
+    colorSchemes?: string[];
+    /** `CHART_LAYOUT_PRESETS` ids allowed. */
+    layouts?: string[];
+    /** Colours and type to draw charts with (the `theme` option of the chart renderers). */
+    theme?: Partial<Record<'background' | 'surface' | 'text' | 'mutedText' | 'grid' | 'axis' | 'positive' | 'negative' | 'fontFamily', string> & Record<'fontSize' | 'titleSize', number>>;
+    /** Spec values new charts start from. */
+    defaults?: Partial<Pick<ChartSpec, 'dataLabels' | 'points' | 'curve' | 'stacking' | 'orientation' | 'labelPosition'>>;
+}
+/** The chart house-style domain: register it with `createStyleResolver({ domains })`. */
+export declare const chartStyleDomain: StyleDomain<ChartSpec>;
+/** The spec patch that starts a chart in the house style: the palette and the defaults. */
+export declare function chartStylePatch(profile: Readonly<Record<string, unknown>>): Partial<ChartSpec>;
+export interface ChartStyleToolProviderOptions {
+    /** Provider id (unique per registry). Default `chart-style`. */
+    id?: string;
+    /** Tool-name prefix; defaults to `chart`, so `check_chart_style` joins the chart toolset. */
+    namespace?: string;
+}
+/** `check_chart_style`: runs the chart house-style checks against a chart. */
+export declare function createChartStyleToolProvider(controller: ChartController, styles: StyleResolver, options?: ChartStyleToolProviderOptions): AgentToolProvider;

package/dist/chart/types.d.cts

@@ -16,8 +16,11 @@
  * - `parliament` draws the first series as seats in a hemicycle, one colour per category.
  * - `sunburst` draws `tree` as rings from the centre out (or, without a tree, the first series
  *   as one ring); a `treemap` with a `tree` nests each group's rectangles inside it.
+ * - `sankey` draws `links` as flows between columns of nodes.
+ * - `barrace` reads each category as a time point and each series as a name, and draws the
+ *   top `raceTopN` names at one moment as ranked horizontal bars (an animated ranking).
  */
-export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst';
+export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey' | 'barrace';
 /** How a series is drawn in a cartesian chart. */
 export type ChartSeriesType = 'bar' | 'line' | 'area' | 'scatter';
 /** One data value; `null` is a gap (missing value). */
@@ -122,6 +125,17 @@ export interface ChartTreeNode {
     /** CSS colour (default: the palette colour of its top-level group, lighter further in). */
     color?: string;
 }
+/** One flow of a Sankey diagram, from one named node to another. */
+export interface ChartLink {
+    source: string;
+    target: string;
+    /** Above 0. */
+    value: number;
+    /** CSS colour (default: by `sankeyLinkColor`). */
+    color?: string;
+}
+/** What colours each flow of a Sankey diagram: its source node, its target node, or grey. */
+export type ChartSankeyLinkColor = 'source' | 'target' | 'gray';
 /** Which axis a reference line or band is measured on: the value axis, the secondary value axis, or the numeric x axis of a scatter or bubble chart. */
 export type ChartReferenceAxis = 'y' | 'y2' | 'x';
 /** A line across the plot at one value: a target, a floor, an average. */
@@ -277,6 +291,18 @@ export interface ChartSpec {
     tree: ChartTreeNode[];
     /** Sunburst: the caption under the total in the centre ("" for none). */
     sunburstLabel: string;
+    /**
+     * Flows between named nodes (Sankey diagrams). When set they are the chart's data: the
+     * categories are the nodes (in `sankeyNodes` order) and the first series holds how much flows
+     * through each (the larger of in and out), so other types draw those amounts.
+     */
+    links: ChartLink[];
+    /** Sankey: the order nodes are listed and stacked in (default: as the links first name them). */
+    sankeyNodes: string[];
+    /** Sankey: what colours each flow. */
+    sankeyLinkColor: ChartSankeyLinkColor;
+    /** Bar race: how many bars each moment shows, 1–30. */
+    raceTopN: number;
 }
 /** What a click selects. */
 export type ChartSelection = {
@@ -332,7 +358,7 @@ export interface ChartRect {
     height: number;
 }
 /** What a mark is, for styling and tests. */
-export type ChartMarkRole = 'background' | 'title' | 'subtitle' | 'grid' | 'axis' | 'tick' | 'tick-label' | 'axis-title' | 'bar' | 'line' | 'area' | 'point' | 'slice' | 'cell' | 'box' | 'whisker' | 'outlier' | 'connector' | 'trendline' | 'trendline-label' | 'error-bar' | 'data-label' | 'legend-swatch' | 'legend-label' | 'drag-readout' | 'reference-line' | 'reference-band' | 'reference-label' | 'callout' | 'note' | 'selection' | 'empty';
+export type ChartMarkRole = 'background' | 'title' | 'subtitle' | 'grid' | 'axis' | 'tick' | 'tick-label' | 'axis-title' | 'bar' | 'line' | 'area' | 'point' | 'slice' | 'cell' | 'box' | 'whisker' | 'outlier' | 'connector' | 'trendline' | 'trendline-label' | 'error-bar' | 'data-label' | 'legend-swatch' | 'legend-label' | 'drag-readout' | 'reference-line' | 'reference-band' | 'reference-label' | 'callout' | 'node' | 'race-time' | 'link' | 'note' | 'selection' | 'empty';
 interface ChartMarkBase {
     /** Unique within the scene (a stable key for frameworks). */
     key: string;

package/dist/chart/types.d.ts

@@ -16,8 +16,11 @@
  * - `parliament` draws the first series as seats in a hemicycle, one colour per category.
  * - `sunburst` draws `tree` as rings from the centre out (or, without a tree, the first series
  *   as one ring); a `treemap` with a `tree` nests each group's rectangles inside it.
+ * - `sankey` draws `links` as flows between columns of nodes.
+ * - `barrace` reads each category as a time point and each series as a name, and draws the
+ *   top `raceTopN` names at one moment as ranked horizontal bars (an animated ranking).
  */
-export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst';
+export type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'bubble' | 'pie' | 'donut' | 'radar' | 'waterfall' | 'histogram' | 'box' | 'funnel' | 'treemap' | 'slope' | 'likert' | 'parliament' | 'sunburst' | 'sankey' | 'barrace';
 /** How a series is drawn in a cartesian chart. */
 export type ChartSeriesType = 'bar' | 'line' | 'area' | 'scatter';
 /** One data value; `null` is a gap (missing value). */
@@ -122,6 +125,17 @@ export interface ChartTreeNode {
     /** CSS colour (default: the palette colour of its top-level group, lighter further in). */
     color?: string;
 }
+/** One flow of a Sankey diagram, from one named node to another. */
+export interface ChartLink {
+    source: string;
+    target: string;
+    /** Above 0. */
+    value: number;
+    /** CSS colour (default: by `sankeyLinkColor`). */
+    color?: string;
+}
+/** What colours each flow of a Sankey diagram: its source node, its target node, or grey. */
+export type ChartSankeyLinkColor = 'source' | 'target' | 'gray';
 /** Which axis a reference line or band is measured on: the value axis, the secondary value axis, or the numeric x axis of a scatter or bubble chart. */
 export type ChartReferenceAxis = 'y' | 'y2' | 'x';
 /** A line across the plot at one value: a target, a floor, an average. */
@@ -277,6 +291,18 @@ export interface ChartSpec {
     tree: ChartTreeNode[];
     /** Sunburst: the caption under the total in the centre ("" for none). */
     sunburstLabel: string;
+    /**
+     * Flows between named nodes (Sankey diagrams). When set they are the chart's data: the
+     * categories are the nodes (in `sankeyNodes` order) and the first series holds how much flows
+     * through each (the larger of in and out), so other types draw those amounts.
+     */
+    links: ChartLink[];
+    /** Sankey: the order nodes are listed and stacked in (default: as the links first name them). */
+    sankeyNodes: string[];
+    /** Sankey: what colours each flow. */
+    sankeyLinkColor: ChartSankeyLinkColor;
+    /** Bar race: how many bars each moment shows, 1–30. */
+    raceTopN: number;
 }
 /** What a click selects. */
 export type ChartSelection = {
@@ -332,7 +358,7 @@ export interface ChartRect {
     height: number;
 }
 /** What a mark is, for styling and tests. */
-export type ChartMarkRole = 'background' | 'title' | 'subtitle' | 'grid' | 'axis' | 'tick' | 'tick-label' | 'axis-title' | 'bar' | 'line' | 'area' | 'point' | 'slice' | 'cell' | 'box' | 'whisker' | 'outlier' | 'connector' | 'trendline' | 'trendline-label' | 'error-bar' | 'data-label' | 'legend-swatch' | 'legend-label' | 'drag-readout' | 'reference-line' | 'reference-band' | 'reference-label' | 'callout' | 'note' | 'selection' | 'empty';
+export type ChartMarkRole = 'background' | 'title' | 'subtitle' | 'grid' | 'axis' | 'tick' | 'tick-label' | 'axis-title' | 'bar' | 'line' | 'area' | 'point' | 'slice' | 'cell' | 'box' | 'whisker' | 'outlier' | 'connector' | 'trendline' | 'trendline-label' | 'error-bar' | 'data-label' | 'legend-swatch' | 'legend-label' | 'drag-readout' | 'reference-line' | 'reference-band' | 'reference-label' | 'callout' | 'node' | 'race-time' | 'link' | 'note' | 'selection' | 'empty';
 interface ChartMarkBase {
     /** Unique within the scene (a stable key for frameworks). */
     key: string;