inkplot-scratch 0.0.0-stage → 1.0.0-beta.1

package/skill/inkplot/topics/statistics.md

@@ -0,0 +1,365 @@
+# inkplot topic: statistics
+
+For: histograms, heat maps, density, box plots, trendlines (linear, polynomial, sinusoidal, loess), error bars and bands.
+
+Read `SKILL.md` first (rules, template, and the attributes of `Chart`, `CartesianPlane`, `Axis`, `LinearScale`, `DomainSeries`, `FlatDataSource`, `ObjectDataSource`, `LinePath`, `LinearCurve`). This file has the rest of what this topic needs: examples, notes, and the attributes of its elements. Everything here is exported from `'inkplot'`.
+
+## Examples
+
+
+A transform sits between the series and its source and replaces the points. Each of these is one structure: source inside transform inside series, then renderers.
+
+```ts check title="Histogram"
+import {
+  Axis,
+  BarPath,
+  CartesianPlane,
+  Chart,
+  Density,
+  DomainSeries,
+  LinearScale,
+  ObjectDataSource,
+  lightTheme,
+} from 'inkplot';
+
+const rows = Array.from({ length: 300 }, (_, i) => ({ v: 50 + 12 * Math.sin(i * 12.9898) }));
+
+export const chart = new Chart(
+  { theme: lightTheme },
+  new CartesianPlane(
+    {},
+    new Axis({ orientation: 'bottom', title: 'Value' }, new LinearScale()),
+    new Axis({ orientation: 'left', title: 'Count', include: [0] }, new LinearScale()),
+    new DomainSeries(
+      { name: 'Count' },
+      new Density({ width: 4 }, new ObjectDataSource({ source: rows, domain: 'v', value: 'v' })),
+      new BarPath({ width: 0.95 }),
+    ),
+  ),
+);
+```
+
+A histogram's value axis is fitted to the bin centres, so the bottom axis starts a little inside the first bin: set `min: 0` on it to start at 0 (or at any value you want). The count axis ends at the tallest bar; add `nice` to it for some headroom.
+
+Bars cannot `bind`, so to colour some bins differently (say, those above a threshold) draw two series from filtered rows with the same `Density` `width`, `origin` and `extent`, and a different `fill` on each `BarPath`. JSX spreads (`<Density {...bins}>`) are fine. `BarPath width={0.95}` is the fraction of each bin a bar fills (the rest is the gap); `include: [0]` keeps zero on the count axis (axes otherwise fit the data). `Density` (one dimension, `by` defaults to `['domain']`) outputs one point per bin: domain is the bin centre, value is `count`. `width` is the bin size in data units; `bins: n` fixes the count instead. Empty bins are kept as zeros. The source's `domain` and `value` can name the same column; only `domain` is counted. For each bin's share of the total use `stat: 'fraction'` (0 to 1; the other values are `'count'`, `'sum'`, `'mean'`, `'density'`), and show it as a percent with `<Axis format={(v) => `${Math.round(v * 100)}%`}>`.
+
+```ts check title="Heat map from raw points"
+import {
+  Axis,
+  CartesianPlane,
+  Chart,
+  ColorAxis,
+  ColorKey,
+  Density,
+  HeatMap,
+  LinearScale,
+  ObjectDataSource,
+  XYSeries,
+  lightTheme,
+} from 'inkplot';
+
+const pts = Array.from({ length: 2000 }, (_, i) => ({ x: Math.sin(i * 12.9898) * 3, y: Math.cos(i * 78.233) * 2 }));
+
+export const chart = new Chart(
+  { theme: lightTheme },
+  new CartesianPlane(
+    {},
+    new Axis({ orientation: 'bottom', title: 'x' }, new LinearScale()),
+    new Axis({ orientation: 'left', title: 'y' }, new LinearScale()),
+    new XYSeries(
+      { name: 'Points', x: 'domain' },
+      new Density(
+        { by: ['domain', 'value'], width: 0.5 },
+        new ObjectDataSource({ source: pts, domain: 'x', value: 'y' }),
+      ),
+      new HeatMap({ cellWidth: 0.5, bind: { fill: { axis: 'heat', channel: 'count' } } }),
+    ),
+  ),
+  new ColorAxis({ id: 'heat', ramp: 'viridis', title: 'Points' }, new LinearScale()),
+  new ColorKey({ dimension: 'heat', side: 'right' }),
+);
+```
+
+Two dimensions: `by: ['domain', 'value']` (domain is x, value is y, or any channel name). The output has `domain` (x of the cell centre), `value` (y), `count`, `sum`, `mean`, `fraction`, `density`, `width` and `height`. `x: 'domain'` is what lets an `XYSeries` use the `Density` output. Colour by `bind: { fill: { axis: 'heat', channel: 'count' } }` (the channel is any output name below: `count`, `sum`, `mean`, `fraction`, `density`); the ramp names (`'viridis'`, `'magma'`, `'turbo'`, `'blues'`, `'greys'`, `'diverging'`) are set on the `ColorAxis` (see `markers-color`). The axes reach the outer edges of the outer cells. `cellWidth` alone draws square cells; set `cellHeight` too for rectangles. They must match the bin `width` (a number for both, or `[w, h]` such as `width: [2, 1]` with `cellWidth: 2, cellHeight: 1`). Cells with no points are left out in two dimensions (`empty: 'omit'` is the default there; one-dimensional bins keep zeros).
+
+```ts check title="Box plot from samples, with outliers"
+import {
+  Axis,
+  BandScale,
+  BoxPath,
+  BoxStats,
+  CartesianPlane,
+  Chart,
+  DomainSeries,
+  DotMarker,
+  LinearScale,
+  ObjectDataSource,
+  lightTheme,
+} from 'inkplot';
+
+const samples = Array.from({ length: 120 }, (_, i) => ({
+  g: i % 3,
+  v: 10 + (i % 3) * 3 + 4 * Math.sin(i * 12.9898) + (i === 7 ? 25 : 0),
+}));
+const source = () => new ObjectDataSource({ source: samples, domain: 'g', value: 'v' });
+
+export const chart = new Chart(
+  { theme: lightTheme },
+  new CartesianPlane(
+    {},
+    new Axis({ orientation: 'bottom' }, new BandScale({ categories: ['A', 'B', 'C'] })),
+    new Axis({ orientation: 'left', title: 'Measurement' }, new LinearScale()),
+    new DomainSeries({ name: 'Spread' }, new BoxStats({}, source()), new BoxPath()),
+    new DomainSeries(
+      { name: 'Outliers' },
+      new BoxStats({ output: 'outliers' }, source()),
+      new DotMarker({ size: 3 }),
+    ),
+  ),
+);
+```
+
+
+The shared source is a function because one element has one parent (rule 14). `BoxStats` takes raw samples (any order) and groups them by `domain` (0, 1, 2… on a `BandScale`). Its output channels are `min q1 median q3 max mean sd sem n`; the point's value is the median. `BoxPath` reads `min q1 q3 max` by those names, and the median is the point's value. Its attributes `low q1 median q3 high` only matter to rename channels, for example when you already have the numbers: `new ObjectDataSource({ source: rows, domain: 'g', value: 'med', channels: { min: 'lo', q1: 'q1', q3: 'q3', max: 'hi' } })` then `new BoxPath()` with no `BoxStats`.
+
+From numbers you already have (no samples), give the median as `value` (it must be the median column) and the other four as channels, then `BoxPath` alone. Always declare `min`, `q1`, `q3` and `max` in `channels` (even when the columns are already called that), or the chart throws `the data has no channel "min"`:
+
+```ts check title="Box plot from numbers you already have"
+import {
+  Axis,
+  BandScale,
+  BoxPath,
+  CartesianPlane,
+  Chart,
+  DomainSeries,
+  LinearScale,
+  ObjectDataSource,
+  lightTheme,
+} from 'inkplot';
+
+const rows = [
+  { i: 0, min: 12, q1: 20, median: 26, q3: 34, max: 61 },
+  { i: 1, min: 18, q1: 30, median: 41, q3: 55, max: 90 },
+];
+
+export const chart = new Chart(
+  { theme: lightTheme },
+  new CartesianPlane(
+    {},
+    new Axis({ orientation: 'bottom' }, new BandScale({ categories: ['API', 'Web'] })),
+    new Axis({ orientation: 'left', title: 'Response (ms)' }, new LinearScale()),
+    new DomainSeries(
+      { name: 'Latency' },
+      new ObjectDataSource({
+        source: rows,
+        domain: 'i',
+        value: 'median',
+        channels: { min: 'min', q1: 'q1', q3: 'q3', max: 'max' },
+      }),
+      new BoxPath(),
+    ),
+  ),
+);
+```
+
+
+```ts check title="Scatter with a trendline"
+import {
+  Axis,
+  CartesianPlane,
+  Chart,
+  CircleMarker,
+  DomainSeries,
+  LinearCurve,
+  LinearScale,
+  LinePath,
+  LinearTrend,
+  Legend,
+  ObjectDataSource,
+  XYSeries,
+  lightTheme,
+} from 'inkplot';
+
+const rows = Array.from({ length: 80 }, (_, i) => ({ x: i / 4, y: 3 + 0.8 * (i / 4) + 2 * Math.sin(i * 12.9898) }));
+
+export const chart = new Chart(
+  { theme: lightTheme },
+  new CartesianPlane(
+    {},
+    new Axis({ orientation: 'bottom' }, new LinearScale()),
+    new Axis({ orientation: 'left' }, new LinearScale()),
+    new XYSeries(
+      { name: 'Data', x: 'x' },
+      new ObjectDataSource({ source: rows, domain: 'x', value: 'y', channels: { x: 'x' } }),
+      new CircleMarker({ size: 4 }),
+    ),
+    new DomainSeries(
+      { name: 'Trend' },
+      new LinearTrend(
+        { extend: 0.05 },
+        new ObjectDataSource({ source: rows, domain: 'x', value: 'y', isSorted: true }),
+      ),
+      new LinePath({}, new LinearCurve()),
+    ),
+  ),
+  new Legend({ side: 'bottom' }),
+);
+```
+
+A trendline is its own `DomainSeries` (a line over the same data) beside the scatter; its source needs `domain` and `value` and `isSorted` if sorted. It outputs a smooth line, one point per pixel, with `extend` 0 (the line stops at the data) unless you set it. Choose its colour with `stroke` on the `LinePath`. Other fits: `PolynomialTrend degree`, `SinusoidalTrend period?`, `LoessTrend smoothness` (0 joins the points, 1 is the straight line). `extend: 0.1` runs the line 10% of the span past each end.
+
+
+| To… | Use |
+|---|---|
+| Error bars / a band | A channel of the data (`channels: { sd: 'sd' }`) and `new ErrorBars({ error: 'sd' })` or `new ErrorBand({ error: 'hi', negativeError: 'lo' })` in the series; `mode: 'relative'` for fractions |
+| Chart data as a table | `readTable(node)` (a source, transform, trendline or `series.data`): typed-array columns and `rows()` |
+
+## Attributes of this topic's elements
+
+An attribute followed by `(required)` must be given. Every element also takes `id`, `meta`, `visible` and `style`.
+
+<!-- api:start -->
+### BoxPath
+
+Box and whisker from min, q1, median, q3, max channels.
+
+**In** a series · **Holds** none
+
+| Attribute | Type | |
+|---|---|---|
+| `low` | `string` | The channel of the lower whisker's end. Default 'min'. |
+| `q1` | `string` | The channel of the first quartile (the foot of the box). Default 'q1'. |
+| `median` | `string` | The channel of the median. Default: the series' own value, which is what a data source's `value` names. |
+| `q3` | `string` | The channel of the third quartile (the top of the box). Default 'q3'. |
+| `high` | `string` | The channel of the upper whisker's end. Default 'max'. |
+| `capWidth` | `number` | Width of the cap on each whisker, as a fraction of the box's width; 0 for none. Default 0.5. |
+
+### BoxStats
+
+Samples in; per group min q1 median q3 max mean sd sem n out (or the outliers).
+
+**In** a series · **Holds** 1 data
+
+| Attribute | Type | |
+|---|---|---|
+| `output` | `'summary' \| 'outliers'` | 'summary' (the default): a point for each group. 'outliers': a point for each sample beyond the whiskers. |
+| `fence` | `number \| 'minmax'` | How far the whiskers may reach past the box, in interquartile ranges (default 1.5), or 'minmax' for the whole range. |
+| `method` | `'inclusive' \| 'exclusive'` | How a quartile is found between samples. Default 'inclusive'. |
+| `value` | `'median' \| 'mean'` | Which statistic is the point's value: 'median' (the default; what a box is drawn round) or 'mean' (what error bars from `sd` or `sem` are drawn round). |
+
+### Density
+
+Bins points over any number of dimensions: count, sum, mean, fraction, density per bin (a histogram with BarPath).
+
+**In** a series · **Holds** 1 data
+
+| Attribute | Type | |
+|---|---|---|
+| `by` | `readonly string[]` | The dimensions to bin: 'domain', 'value' or channel names. Default ['domain']. |
+| `weight` | `string` | What each point counts for: a channel name or 'value'. Default: 1 for each point. |
+| `stat` | `Stat` | The value of a one-dimensional output: 'count', 'sum', 'mean', 'fraction' (the share of the total, 0 to 1) or 'density'. Default 'count', or 'sum' with a `weight`. |
+| `width` | `number \| readonly number[]` | Bin size in each dimension's units: one number for all, or one for each dimension. |
+| `bins` | `number \| readonly number[]` | Number of bins in each dimension, spread evenly over its extent (by default the data's own range). |
+| `origin` | `number \| readonly number[]` | Where a bin edge falls when `width` is used, in each dimension: edges are at `origin` plus whole widths. Default 0. |
+| `extent` | `Extent \| readonly (Extent \| null)[]` | The span to bin over in each dimension, as `{ min, max }` (one for all, or an array with one for each); points outside are left out. Default: the data's extent. |
+| `maxBins` | `number` | Most bins along a dimension when the size is chosen by the rule. Default 200. |
+| `empty` | `'keep' \| 'omit'` | 'keep' bins with no points as zeros, 'omit' leaves them out. Default 'keep' for one dimension, 'omit' for more. |
+
+### HeatMap
+
+A rectangle at each point, coloured by a channel; with `Density`, a heat map.
+
+**In** a series · **Holds** none
+
+| Attribute | Type | |
+|---|---|---|
+| `cellWidth` | `number` | The size of a cell along the first axis, in data units. Default: the `widthChannel`. |
+| `cellHeight` | `number` | The size along the second axis. Default: the `heightChannel`, or `cellWidth` when only that is given (square cells). |
+| `widthChannel` | `string` | The channel with each cell's width. Default 'width'. |
+| `heightChannel` | `string` | The channel with each cell's height. Default 'height'. |
+| `stroke` | `string` | Outline colour (a CSS colour). Default: from the theme. |
+| `strokeWidth` | `number` | Outline width in pixels. Default: from the theme. |
+| `fill` | `string` | Fill colour (a CSS colour; 'none' for no fill). Default: from the theme. |
+| `opacity` | `number` | Opacity from 0 to 1. Default 1. |
+| `bind` | `Bindings<Bindable>` | Attributes fed from data instead of fixed. |
+| `maxNodes` | `number` | Most paths this renderer may create. Default 1000. |
+
+### LinearTrend
+
+The least-squares line through its source, sampled across the domain.
+
+**In** a series · **Holds** 1 data
+
+| Attribute | Type | |
+|---|---|---|
+| `x` | `string` | A channel of the source to fit against instead of its domain. |
+| `extend` | `number \| readonly [number, number]` | How far past the data the line goes at each end, as a fraction of the data's span: one number, or `[before, after]`. Default 0. |
+| `count` | `number` | Samples, evenly spaced over the whole span, always. |
+
+### PolynomialTrend
+
+A polynomial fitted to its source (`degree`).
+
+**In** a series · **Holds** 1 data
+
+| Attribute | Type | |
+|---|---|---|
+| `degree` | `number` | The highest power, 1 to 12. Default 2. |
+| `x` | `string` | A channel of the source to fit against instead of its domain. |
+| `extend` | `number \| readonly [number, number]` | How far past the data the line goes at each end, as a fraction of the data's span: one number, or `[before, after]`. Default 0. |
+| `count` | `number` | Samples, evenly spaced over the whole span, always. |
+
+### SinusoidalTrend
+
+A constant plus a sine wave fitted to its source, of a given `period` or the best one.
+
+**In** a series · **Holds** 1 data
+
+| Attribute | Type | |
+|---|---|---|
+| `period` | `number` | The period in the domain's units. |
+| `x` | `string` | A channel of the source to fit against instead of its domain. |
+| `extend` | `number \| readonly [number, number]` | How far past the data the line goes at each end, as a fraction of the data's span: one number, or `[before, after]`. Default 0. |
+| `count` | `number` | Samples, evenly spaced over the whole span, always. |
+
+### LoessTrend
+
+Local linear regression: `smoothness` 0 joins the points, 1 is the line.
+
+**In** a series · **Holds** 1 data
+
+| Attribute | Type | |
+|---|---|---|
+| `smoothness` | `number` | 0 to 1: 0 joins the points, 1 is the least-squares line, and between them the line is smoother the larger it is. Default 0.5. |
+| `kernel` | `'tricube' \| 'gaussian'` | How a point's weight falls with its distance. Default 'tricube'. |
+| `x` | `string` | A channel of the source to fit against instead of its domain. |
+| `extend` | `number \| readonly [number, number]` | How far past the data the line goes at each end, as a fraction of the data's span: one number, or `[before, after]`. Default 0. |
+| `count` | `number` | Samples, evenly spaced over the whole span, always. |
+
+### ErrorBars
+
+Whiskers with caps from an error channel (error, optional negativeError; absolute or relative).
+
+**In** a series · **Holds** none
+
+| Attribute | Type | |
+|---|---|---|
+| `capWidth` | `number` | Width in pixels of the cap at each end of a whisker; 0 for none. Default 8. |
+| `error` (required) | `string` | The channel with how far above the value each point may be. |
+| `negativeError` | `string` | The channel with how far below. Default: the same as `error`. |
+| `mode` | `'absolute' \| 'relative'` | What the numbers mean: units of the value (default), or a fraction of it. |
+| `along` | `'value' \| 'domain'` | Which way the error runs. Default 'value'. |
+
+### ErrorBand
+
+The region between value minus and plus an error channel.
+
+**In** a series · **Holds** none
+
+| Attribute | Type | |
+|---|---|---|
+| `error` (required) | `string` | The channel with how far above the value each point may be. |
+| `negativeError` | `string` | The channel with how far below. Default: the same as `error`. |
+| `mode` | `'absolute' \| 'relative'` | What the numbers mean: units of the value (default), or a fraction of it. |
+| `along` | `'value' \| 'domain'` | Which way the error runs. Default 'value'. |
+<!-- api:end -->

package/skill/inkplot/topics/styling-output.md

@@ -0,0 +1,75 @@
+# inkplot topic: themes, styling, React, export
+
+For: dark and custom themes, styling parts, React, a PNG, chart as JSON, your own element types.
+
+Read `SKILL.md` first (rules, template, and the attributes of `Chart`, `CartesianPlane`, `Axis`, `LinearScale`, `DomainSeries`, `FlatDataSource`, `ObjectDataSource`, `LinePath`, `LinearCurve`). This file has the rest of what this topic needs: examples, notes, and the attributes of its elements. Everything here is exported from `'inkplot'`.
+
+## Dark theme, and styling
+
+
+```ts check title="Theme and style" dark
+import {
+  Axis,
+  CartesianPlane,
+  Chart,
+  DomainSeries,
+  FlatDataSource,
+  LinePath,
+  LinearCurve,
+  LinearScale,
+  darkTheme,
+  extendTheme,
+} from 'inkplot';
+
+const brand = extendTheme(darkTheme, { palette: ['#ff6b9d', '#6bcbff'], text: { family: 'Georgia, serif' } });
+
+export const chart = new Chart(
+  { theme: brand, style: { gridline: { dash: '2 3' } } },
+  new CartesianPlane(
+    {},
+    new Axis({ orientation: 'bottom', style: { tickLabel: { size: 13 } } }, new LinearScale()),
+    new Axis({ orientation: 'left' }, new LinearScale()),
+    new DomainSeries(
+      { name: 'A' },
+      new FlatDataSource({ data: [3, 5, 4, 8], regularDomain: { start: 0, step: 1 } }),
+      new LinePath({ strokeWidth: 3 }, new LinearCurve()),
+    ),
+  ),
+);
+```
+
+## In React
+
+
+Import the components from `inkplot/react`: one per built-in class, same names. For your own class, `reactWrapper(MyClass)`. The root renders a `<div>`; give it a height. Functions in props should be memoized.
+
+```tsx check title="React" jsx=react
+import { lightTheme } from 'inkplot';
+import { Axis, CartesianPlane, Chart, DomainSeries, FlatDataSource, LinePath, LinearCurve, LinearScale } from 'inkplot/react';
+
+export function Trend({ values }: { values: number[] }) {
+  return (
+    <Chart theme={lightTheme} hostProps={{ style: { height: 300 } }}>
+      <CartesianPlane>
+        <Axis orientation="bottom"><LinearScale /></Axis>
+        <Axis orientation="left"><LinearScale /></Axis>
+        <DomainSeries name="Trend">
+          <FlatDataSource data={values} regularDomain={{ start: 0, step: 1 }} />
+          <LinePath><LinearCurve /></LinePath>
+        </DomainSeries>
+      </CartesianPlane>
+    </Chart>
+  );
+}
+```
+
+## Notes
+
+| To… | Use |
+|---|---|
+| A PNG | Browser: `await toPng(chart, { scale: 2, background: '#fff' })` (a `Blob`). Server: `toSvgString` then a WASM renderer with a font (`@resvg/resvg-wasm`; recipe "Make a PNG on a server") |
+| Chart as JSON | `toJSON(chart, registry, { refs })`, `fromJSON(json, registry, { refs })` |
+| Custom element that listens to the pointer, keys or focus | declare `static takesInput = inputOf` (from `inkplot`) on the class, or the chart never routes input to it |
+| Show gridlines or a frame | `new CartesianPlane({ gridlines: false, frame: true }, …)` |
+| Accessible name | `meta: { title }`, `meta: { description }` on the `Chart`; `new ChartSummary()` for an automatic one |
+

package/skill/inkplot/topics/troubleshooting.md

@@ -0,0 +1,24 @@
+# inkplot topic: troubleshooting
+
+For: an error message, or a chart that draws nothing or draws wrongly. Find the symptom, apply the fix.
+
+| Symptom | Cause and fix |
+|---|---|
+| Error `X: child 0 should be Scale, but is …` | Children in the wrong order. `Axis`: scale. `DomainSeries`: data, then renderers. |
+| Error `X: has no child 0 (it needs …)` | A required child is missing: scale on an `Axis`, data on a series, curve on a `LinePath`. |
+| Error `a series needs one horizontal and one vertical axis` | Missing or mismatched axes. `bottom` + `left` for `CartesianPlane`; `angle` + `radius` for polar and radar. |
+| Error `the data has no channel "x"` | Add it: `channels: { x: 'x' }` on an `ObjectDataSource`. |
+| Error `no element with id "x"` | The `id` is missing or misspelt on the axis or series that is referred to. |
+| Error `LinePath bindings is not implemented yet` | Only markers can `bind`. |
+| Error `add a PointerListener before PanZoom` / `add a BoxZoom before PanZoom` / `add a Brush before PanZoom` | Put the `PointerListener`, `BoxZoom` or `Brush` first. |
+| Error `a Decimator cannot carry channels` | No bound channels through a `Decimator`. |
+| Nothing is drawn (browser) | The container has no height; the chart was not attached (`chart.attach(new DOMPlatform(el))`); no `theme`. |
+| Nothing is drawn (`toSvgString`) | No renderer on the series; empty data; `visible: false`. |
+| Axis starts somewhere odd | Axes fit the data and tidy the ends: set `min`/`max`, or `include: [0]`. |
+| A line jumps backwards | `isSorted` set on unsorted data: remove it. |
+| Series missing from legend or tooltip | It has no `name`. |
+| Tooltip or crosshair missing | `Cursor` must be a child of the **chart**, holding `ChartTooltip`/`Crosshair`. |
+| Dates wrong or in 1970 | Values must be milliseconds since 1970. Time zone defaults to UTC: set `timeZone`. |
+| Chart does not update | You mutated an object: set a new one with `setAttribute`. For an in-place array edit call `source.invalidate()`. |
+| A colour is only roughly right | Bound colours are stepped; `merge: false` on the marker for small data. |
+

package/src/app.ts

@@ -0,0 +1,100 @@
+/**
+ * The page the `--html` output opens: every figure of a module, live, with the usual controls. Bundled with the
+ * module itself (see cli.ts), so one file holds the app, the charts and their data.
+ */
+import { DOMPlatform, svgToPng } from 'inkplot';
+import { hintFor, makeInteractive } from './interact.ts';
+import { type Facts, type Figure, checkText, factsOf, figuresOf, svgOf } from './figures.ts';
+
+const h = <K extends keyof HTMLElementTagNameMap>(tag: K, props: Partial<HTMLElementTagNameMap[K]> & { class?: string } = {}, ...kids: (Node | string)[]) => {
+  const { class: cls, ...rest } = props;
+  const el = Object.assign(document.createElement(tag), rest);
+  if (cls) el.className = cls;
+  el.append(...kids);
+  return el;
+};
+
+/** An element the page template is known to have. */
+const byId = (id: string): HTMLElement => document.getElementById(id) ?? (() => { throw new Error(`the page has no #${id}`); })();
+
+const download = (blob: Blob, name: string) => {
+  const url = URL.createObjectURL(blob);
+  const a = h('a', { href: url, download: name });
+  document.body.append(a);
+  a.click();
+  a.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 10_000);
+};
+
+export function mount(module: Record<string, unknown>, title: string, options: { interactive?: boolean } = {}): void {
+  document.title = title;
+  const root = byId('figures'), note = byId('note');
+  byId('title').textContent = title;
+  let toastTimer = 0;
+  const say = (text: string) => {
+    note.textContent = text;
+    note.classList.add('on');
+    clearTimeout(toastTimer);
+    toastTimer = window.setTimeout(() => note.classList.remove('on'), 2500);
+  };
+
+  let figures: Figure[];
+  try { figures = figuresOf(module); } catch (e) { root.append(h('pre', { class: 'error' }, e instanceof Error ? e.message : String(e))); return; }
+
+  const svgs = new Map<string, string>(), pngs = new Map<string, Promise<Blob>>(), allFacts: Facts[] = [];
+  /** The figure's exported SVG, written when its section is built, before anything can ask for it. */
+  const svgText = (f: Figure) => svgs.get(f.id) ?? '';
+  const png = (f: Figure, scale = 2) => {
+    const key = `${f.id}@${scale}`;
+    let made = pngs.get(key);
+    if (!made) pngs.set(key, made = svgToPng(svgText(f), { scale, background: '#ffffff' }));
+    return made;
+  };
+  // The clipboard wants a user gesture and, for images, a secure page; a file:// page often has neither, so every copy falls back to a download and says so.
+  const copy = async (what: 'SVG' | 'PNG', f: Figure) => {
+    try {
+      if (what === 'SVG') await navigator.clipboard.writeText(svgText(f));
+      else await navigator.clipboard.write([new ClipboardItem({ 'image/png': png(f) })]);
+      say(`Copied ${f.title} as ${what}`);
+    } catch {
+      if (what === 'SVG') download(new Blob([svgText(f)], { type: 'image/svg+xml' }), `${f.id}.svg`);
+      else download(await png(f), `${f.id}.png`);
+      say(`The browser blocked the clipboard, so ${f.title} was downloaded as ${what} instead`);
+    }
+  };
+
+  for (const f of figures) {
+    // The export is rendered before the chart goes on the page, at the chart's own size: what is copied is the chart as written, not as zoomed.
+    svgs.set(f.id, svgOf(f));
+    const facts = factsOf(f);
+    allFacts.push(facts);
+    // After the export render above, so the file and the copy never carry them.
+    let added: string[] = [];
+    if (options.interactive !== false && f.interactive) try { added = makeInteractive(f.chart); } catch { added = []; }
+    const host = h('div', { class: 'plot' });
+    // A chart that sets its own size is drawn at exactly that size, so its box is that size (a bigger box would leave blank margin);
+    // one that does not fills the page up to the default width.
+    host.style.aspectRatio = `${facts.width} / ${facts.height}`;
+    if (f.chart.attrs.width !== undefined || f.chart.attrs.height !== undefined) host.style.width = `${facts.width}px`;
+    host.style.maxWidth = `${f.chart.attrs.width !== undefined ? facts.width : Math.max(facts.width, 640)}px`;
+    const stats = h('pre', { class: 'stats' }, checkText(facts).split('\n').slice(1).join('\n').replace(/^ {2}/gm, ''));
+    stats.hidden = true;
+    const button = (label: string, run: () => unknown, hint: string) => h('button', { type: 'button', textContent: label, title: hint, onclick: () => void run() });
+    const section = h('section', { class: 'figure', id: f.id },
+      h('header', {}, h('h2', {}, f.title), h('div', { class: 'buttons' },
+        button('Copy SVG', () => copy('SVG', f), 'Copy the chart as SVG markup'),
+        button('Copy PNG', () => copy('PNG', f), 'Copy the chart as a 2x PNG image'),
+        button('SVG ↓', () => download(new Blob([svgText(f)], { type: 'image/svg+xml' }), `${f.id}.svg`), 'Download as an SVG file'),
+        button('PNG ↓', async () => download(await png(f), `${f.id}.png`), 'Download as a 2x PNG file'),
+        ...(added.length ? [button('Reset view', () => f.chart.resetViews(), 'Back to the whole chart')] : []),
+        button('Stats', () => { stats.hidden = !stats.hidden; }, 'Show what the chart holds: series, point counts, axis ranges'))),
+      ...(f.caption ? [h('p', { class: 'caption' }, f.caption)] : []),
+      ...(hintFor(added) ? [h('p', { class: 'hint' }, hintFor(added))] : []), host, stats,
+      ...facts.problems.map((p) => h('p', { class: 'warning' }, `⚠ ${p}`)));
+    section.dataset.interactive = added.join(' ');
+    root.append(section);
+    try { f.chart.attach(new DOMPlatform(host)); } catch (e) { host.replaceWith(h('pre', { class: 'error' }, `This chart could not be drawn live: ${e instanceof Error ? e.message : String(e)}\nThe copy and download buttons still work.`)); }
+  }
+  byId('all-svg').onclick = () => figures.forEach((f, i) => setTimeout(() => download(new Blob([svgText(f)], { type: 'image/svg+xml' }), `${f.id}.svg`), i * 150));
+  byId('all-png').onclick = () => figures.forEach((f, i) => setTimeout(async () => download(await png(f), `${f.id}.png`), i * 150));
+}