plotto 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The plotto authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,224 @@
-# Temporary Holding Version
+# plotto
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+plotto makes grammar-of-graphics plots for notebooks, web pages, slides and reports. You write a plot in Python or in JavaScript with the same methods. One renderer draws it, so the notebook view, the interactive view and the saved file look the same.
+
+**Gallery:** [gallery link](https://theoradusz.github.io/plotto/), with pages for the basics, the plot types, the colors, the scales and legends, a step-by-step grammar tutorial and the API reference. `SPEC.md` is the contract: the spec format, the rules, the layers, the scales and the behavior.
+
+<p>
+<img src="docs/img/lines.png" width="49%"> <img src="docs/img/stacked_bars.png" width="49%">
+<img src="docs/img/histogram.png" width="49%"> <img src="docs/img/diverging.png" width="49%">
+<img src="docs/img/facets.png" width="49%"> <img src="docs/img/smooth_1.png" width="49%">
+</p>
+
+```python
+from plotto import plot
+
+p = (
+    plot(df, x="time", y="value", color="sensor")
+    .line()
+    .hline(y=0.75, color="red", dash="dashed")
+    .facet("indicator", free="y")
+    .y(limits=[0, None])
+    .labels(title="Water quality", x=None)
+)
+p                                   # drawn at the cell width, with copy and download buttons
+p.interactive()                     # the same plot with zoom, pan, hover and legend toggle
+p.theme("wota")                     # another style
+p.color(palette="aizome")           # another palette
+p.save("fig.png")                   # PNG; .svg for vector files
+p.theme("wota", format="slide").save("slide.png")   # 1280 × 720 px, large text
+```
+
+```js
+import { plot, draw } from "plotto";
+draw(plot(rows, { x: "time", y: "value", color: "sensor" }).line().facet("indicator", { free: "y" }), el, { interactive: true });
+```
+
+## How it works
+
+1. The builder writes a JSON spec: the data columns, the layers, the scales, the facets, the labels and the theme.
+2. `src/figure.js` computes the statistics, the scales and the layout. Then it draws the title, strips and legend, and Observable Plot draws each panel.
+3. In the browser, a zoom, a legend click or a resize draws the figure again with the same code. The look does not change.
+4. For files, Python sends the spec to one Node process (`src/render.mjs`). The process draws the SVG with jsdom and the PNG with resvg.
+
+| Part | Files |
+|---|---|
+| Grammar and themes | `grammar.json` (layers, channels, options), `theme.json` (styles, formats) |
+| JS builder and renderer | `src/`. Each file has one job, stated in its header comment. |
+| Python builder and outputs | `python/plotto/` |
+| Examples | `examples/` |
+| Tests | `tests/`, `python/tests/` |
+
+## Install
+
+| Where | Install | Import |
+|---|---|---|
+| Python, notebooks | `pip install python-plotto` | `from plotto import plot` |
+| Web pages, React | `npm install plotto` | `import { plot, draw } from "plotto"`; `import { Plot } from "plotto/react"` |
+
+- Python 3.12 or later. A notebook plot needs no Node.
+- `save()` (PNG and SVG files) and the static copy in notebook outputs need Node.js 20 or later. On the first use, plotto downloads its renderer with `npx` (the npm package of the same version) and keeps it in the npm cache.
+- The `wota` style uses the M PLUS 1p font. Install the font to use that style.
+
+### Development
+
+1. Clone the repo and run `npm install`.
+2. Run `pip install -e "python[test]"` in a virtual environment. In a checkout, the package uses `grammar.json`, `theme.json` and `src/` of the repo directly.
+
+## Use
+
+### Data
+
+- Use long format: one row per observation, one column per variable.
+- Python takes a pandas DataFrame or a list of dicts. JavaScript takes an array of row objects.
+- A time-zone-aware datetime column shows its local clock time.
+- To set the order of categories, use a pandas categorical column or `x(limits=[...])`.
+
+### Axes and colors
+
+| Need | Call |
+|---|---|
+| Axis range | `x(limits=[0, 10])`; `y(limits=[0, None])` keeps the data bound on the `None` side |
+| Category order | `x(limits=["low", "mid", "high"])` |
+| Log axis, time labels | `y(type="log")`; `x(format="%a %H:%M")` |
+| Category colors | `color(palette="sakura")`, or `color(values={"a": "red", "b": "#123456"})` |
+| Number colors | `color(scheme="ai")`; diverging: `color(scheme="aiaka", mid=0)` |
+
+Palettes: `pastel` (the default style), `sakura`, `aizome`, `momiji` (inspired by traditional Japanese colors), `wota`, `tableau`. Schemes: `ai`, `sakura`, `matcha`, `yuhi`, `sumi`, `aiaka` (diverging), and every d3 scheme (`viridis`, `magma`, …).
+
+### Info table
+
+Put facts about the data or the experiment in a table instead of a long subtitle:
+
+```python
+p.info({"data point": 15, "location": "hayama", "experiment": "cleaning with chlorine"})
+p.info(entries, position="bottom")   # "right" (default) or "bottom"
+```
+
+The table is a card on the right of the plot, or below it. A plot narrower than 560 px puts it below. `SPEC.md` §7 has the rules.
+
+### Notebook
+
+- A plot shows at the width of the cell. The text keeps its size, and the height follows the aspect ratio of the format.
+- `.interactive()` adds zoom, pan, hover and the legend toggle.
+- The hover follows the plot type:
+  - lines and areas: every series at the nearest x, or only the series under the pointer when there are more than 6;
+  - bars: the stack and its total;
+  - box: the quartiles;
+  - tile: the cell value;
+  - points: the nearest point.
+- A click pins the hover label; the next click (or Esc) releases it. A drag starts after 5 px of movement; a double-click resets the view.
+- A legend click hides or shows a series. Two quick clicks on the same entry (within 300 ms) show only that series.
+- The toolbar shows at the top right when the pointer is on the plot:
+  - copy as PNG;
+  - download as PNG or SVG;
+  - in interactive mode, also zoom box, pan, zoom in, zoom out and reset.
+- The output loads d3 and Observable Plot from `cdn.jsdelivr.net`. GitHub, nbviewer, or a page without network access shows the static SVG in the output.
+- Each output holds the data of the plot and the plotto script (about 60 kB). A plot with 20 000 points adds about 2 MB to the notebook.
+
+### Web pages and React
+
+- `draw(spec, element, { interactive })` draws into an element at its width, and draws again when the width changes. It returns `{ destroy }`.
+- In React, use `import { Plot } from "plotto/react"`, then `<Plot spec={plot(rows, {...}).line()} interactive />`.
+
+### Slides and reports
+
+| Target | Use |
+|---|---|
+| Google Slides | PNG: `p.save("fig.png")`. Google Slides does not accept SVG. |
+| PowerPoint, Keynote, documents | SVG: `p.save("fig.svg")`. The SVG uses the installed fonts. |
+| A slide layout | `p.theme(style, format="slide")`: 1280 × 720 px with large text |
+| A report column | `p.theme(style, format="report")`: 640 × 400 px |
+| A given size | `p.save("fig.png", width=1600)` lays the plot out again at 1600 px. |
+| From the notebook | Use the copy button, which copies the current view as PNG. |
+
+## Examples
+
+| File | Content |
+|---|---|
+| `examples/gallery.py` | 28 examples on 4 pages (basics, plot types, colors, scales and legends), which use every feature. The data is made-up, except for two files of real measurements. |
+| `examples/grammar.py` | The grammar tutorial: 14 steps, each with its text, code and result. |
+| `examples/reference.py` | The API reference. The layer methods come from `grammar.json`. |
+| `examples/build_site.py` | Builds the site in `docs/`: one HTML page per gallery page, `grammar.html` and `reference.html` (each with the plotto script inline), and `img/` (the PNG and SVG of each gallery plot). GitHub Pages serves `docs/`. |
+| `examples/showcase.ipynb` | The examples in a notebook. |
+| `examples/web/` | Examples in JavaScript. Run `python3 -m http.server` in the repo, then open `http://localhost:8000/examples/web/`. |
+
+To publish the gallery:
+
+1. Run `python examples/build_site.py`.
+2. Commit `docs/`.
+3. On GitHub, set Settings → Pages → Source to "Deploy from a branch", with branch `main` and folder `/docs`.
+| `examples/data/` | The datasets. `examples/make_datasets.py` makes the made-up ones. |
+
+## Tests
+
+| Command | What it verifies |
+|---|---|
+| `npm test` | Each layer and style (SVG snapshots in `tests/snapshots/`), stacks, bins, smooth fits, domains, facets, legends, reflow, errors |
+| `npm run browser-test` | In headless Chrome: the browser SVG equals the Node SVG. Zoom, Home, the toolbar, hover, legend clicks and their timing, reflow and the static mode work. |
+| `pytest python/tests` | The Python and JS builders make the same spec; data conversion; SVG and PNG files; notebook output |
+| `ruff check . && black --check .` | Python lint |
+
+If a change of the look is intentional, run `UPDATE_SNAPSHOTS=1 npm test` and review the SVG diff.
+
+## Maintenance
+
+To add a layer type:
+
+1. Add the layer to `grammar.json`: channels, options and required channels.
+2. Add one entry to `LAYERS` in `src/layers.js`.
+3. For a statistic, add the computation to `src/stats.js` and a case to `makeView` and `hoverOf` in `src/views.js`.
+4. Add the method to `src/builder.js` and `python/plotto/plot.py`.
+5. Add a case to `tests/render.test.js` and to `tests/fixtures/parity.json`.
+6. Add a row to the layer table in `SPEC.md`.
+
+To change a style, a format, a palette or a scheme, edit `theme.json`. A scheme is a list of colors from light to dark; plotto interpolates it in Lab space. To use a new font, add it to `scripts/font_metrics.py`, run the script, and set `font` and `metrics` of the style.
+
+## Release
+
+A tag `vX.Y.Z` publishes `python-plotto` to PyPI and `plotto` to npm (`.github/workflows/release.yml`).
+
+One-time setup:
+
+1. On pypi.org, create an account. Under "Publishing", add a pending trusted publisher: project `python-plotto`, owner `theoradusz`, repository `plotto`, workflow `release.yml`, environment `pypi`.
+2. On GitHub, create the environment `pypi` (Settings → Environments).
+3. On npmjs.com, create an account (with two-factor authentication). Publish the first version from your computer, in the repo:
+
+   ```
+   npm login
+   npm test
+   npm publish --access public
+   ```
+
+4. On npmjs.com, open the package `plotto` → Settings → Trusted publishing → GitHub Actions: repository `theoradusz/plotto`, workflow `release.yml`. Later versions then publish from GitHub with no token. The workflow skips a version that is already on npm.
+
+Each release:
+
+`main` takes changes only through a reviewed pull request, so a release has two steps.
+
+1. On `main`, with no uncommitted changes and the Python environment of the repo active, prepare the release:
+
+   ```
+   scripts/release.sh 0.3.0
+   ```
+
+   The script:
+   - checks that `main` is up to date with `origin/main` and that the version is new and higher;
+   - runs `npm test`, `npm run browser-test`, `pytest python/tests`, `ruff` and `black`;
+   - on a new branch `release/v0.3.0`, sets the version in `package.json`, `package-lock.json` and `python/plotto/__init__.py`, and builds the site in `docs/`;
+   - commits "release 0.3.0", pushes the branch and opens the pull request page.
+2. Create the pull request, then have it reviewed and merged.
+3. Tag the merged `main`:
+
+   ```
+   scripts/release.sh tag
+   ```
+
+   The script pulls `main` and reads the version. It asks before it tags and pushes `v0.3.0`, then deletes the release branch.
+4. The pushed tag starts the release in the Actions tab. The packages are then at pypi.org/project/python-plotto and npmjs.com/package/plotto.
+
+To upgrade Observable Plot or d3:
+
+1. Change the exact version in `package.json`.
+2. Run `npm install`.
+3. Run the tests. A snapshot difference shows a change of the look.

package/grammar.json

@@ -0,0 +1,53 @@
+{
+  "options": {
+    "size": "number",
+    "alpha": "number",
+    "dash": ["solid", "dashed", "dotted", "dashdot"],
+    "jitter": "number",
+    "summary": ["mean", "median", "min", "max", "sum"],
+    "slope": "number",
+    "intercept": "number",
+    "position": ["stack", "dodge", "overlay"],
+    "bins": "number",
+    "density": "boolean",
+    "method": ["lm", "loess"],
+    "span": "number",
+    "band": "boolean"
+  },
+  "layers": {
+    "line": { "channels": ["x", "y", "color", "group", "tooltip"], "options": ["size", "alpha", "dash", "summary"], "requires": ["x", "y"] },
+    "path": { "channels": ["x", "y", "color", "group", "tooltip"], "options": ["size", "alpha", "dash"], "requires": ["x", "y"] },
+    "step": { "channels": ["x", "y", "color", "group", "tooltip"], "options": ["size", "alpha", "dash"], "requires": ["x", "y"] },
+    "point": { "channels": ["x", "y", "color", "tooltip"], "options": ["size", "alpha", "jitter", "summary"], "requires": ["x", "y"] },
+    "bar": { "channels": ["x", "y", "color", "tooltip"], "options": ["alpha", "position"], "requires": ["x", "y"] },
+    "hist": { "channels": ["x", "color"], "options": ["alpha", "bins", "density", "position"], "requires": ["x"] },
+    "density": { "channels": ["x", "color"], "options": ["size", "alpha", "dash"], "requires": ["x"] },
+    "area": { "channels": ["x", "y", "color", "group"], "options": ["alpha", "position"], "requires": ["x", "y"] },
+    "ribbon": { "channels": ["x", "ymin", "ymax", "color", "group"], "options": ["alpha"], "requires": ["x", "ymin", "ymax"] },
+    "smooth": { "channels": ["x", "y", "color"], "options": ["size", "alpha", "dash", "method", "span", "band"], "requires": ["x", "y"] },
+    "hline": { "channels": ["y", "color"], "options": ["size", "alpha", "dash"], "requires": ["y"], "inherit": false },
+    "vline": { "channels": ["x", "color"], "options": ["size", "alpha", "dash"], "requires": ["x"], "inherit": false },
+    "abline": { "channels": ["color"], "options": ["slope", "intercept", "size", "alpha", "dash"], "requires": [], "inherit": false },
+    "segment": { "channels": ["x", "y", "xend", "yend", "color"], "options": ["size", "alpha", "dash"], "requires": ["x", "y", "xend", "yend"] },
+    "rect": { "channels": ["xmin", "xmax", "ymin", "ymax", "color", "tooltip"], "options": ["alpha"], "requires": ["xmin", "xmax", "ymin", "ymax"] },
+    "band": { "channels": ["xmin", "xmax", "ymin", "ymax", "color"], "options": ["alpha"], "requires": [], "inherit": false },
+    "tile": { "channels": ["x", "y", "color", "tooltip"], "options": ["alpha"], "requires": ["x", "y", "color"] },
+    "text": { "channels": ["x", "y", "label", "color"], "options": ["size", "alpha"], "requires": ["x", "y", "label"] },
+    "errorbar": { "channels": ["x", "ymin", "ymax", "color"], "options": ["size", "alpha"], "requires": ["x", "ymin", "ymax"] },
+    "box": { "channels": ["x", "y", "color"], "options": ["alpha"], "requires": ["x", "y"] }
+  },
+  "scales": {
+    "x": ["type", "limits", "format"],
+    "y": ["type", "limits", "format"],
+    "color": ["values", "palette", "scheme", "limits", "mid", "clamp"]
+  },
+  "scaleTypes": ["linear", "log", "time", "category"],
+  "facet": ["free", "ncol"],
+  "grid": ["free"],
+  "free": ["x", "y", "both"],
+  "labels": ["title", "subtitle", "x", "y", "color", "caption"],
+  "theme": ["format", "width", "height", "size", "legend"],
+  "legend": ["right", "bottom", "none"],
+  "info": ["position"],
+  "infoPosition": ["right", "bottom"]
+}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "plotto",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Grammar-of-graphics plots for notebooks, web pages and slides with one renderer.",
+  "license": "MIT",
+  "homepage": "https://theoradusz.github.io/plotto/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theoradusz/plotto.git"
+  },
+  "keywords": [
+    "plot",
+    "chart",
+    "grammar-of-graphics",
+    "ggplot",
+    "observable-plot",
+    "svg",
+    "react"
+  ],
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./react": "./src/Plot.js",
+    "./render": "./src/render.mjs",
+    "./theme.json": "./theme.json",
+    "./grammar.json": "./grammar.json"
+  },
+  "bin": {
+    "plotto-render": "src/render.mjs"
+  },
+  "files": [
+    "src/",
+    "grammar.json",
+    "theme.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "browser-test": "node tests/browser.mjs",
+    "build:python": "node scripts/build_assets.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "@observablehq/plot": "0.6.17",
+    "d3": "7.9.0",
+    "@resvg/resvg-js": "2.6.2",
+    "jsdom": "26.1.0"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.2"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/Plot.js

@@ -0,0 +1,12 @@
+// React wrapper: <Plot spec={plot(rows, {...}).line()} interactive />. draw() follows the container width.
+import { createElement, useEffect, useRef } from "react";
+import { draw } from "./interact.js";
+
+export function Plot({ spec, interactive = false, className, style }) {
+  const ref = useRef(null);
+  useEffect(() => {
+    const ctl = draw(spec, ref.current, { interactive });
+    return () => ctl.destroy();
+  }, [spec, interactive]);
+  return createElement("div", { ref, className, style });
+}

package/src/browser.js

@@ -0,0 +1,6 @@
+// Entry of the notebook bundle (render.mjs bundle()): puts the API on window.plotto.
+import { plot } from "./builder.js";
+import { toSVG } from "./figure.js";
+import { draw } from "./interact.js";
+
+globalThis.plotto = { plot, draw, toSVG };

package/src/builder.js

@@ -0,0 +1,198 @@
+// Chainable plot builder. Each method returns a new builder and never changes the old one.
+// .spec() returns the JSON spec (SPEC.md). python/plotto/plot.py has the same methods and rules.
+import GRAMMAR from "../grammar.json" with { type: "json" };
+import THEMES from "../theme.json" with { type: "json" };
+
+
+const LAYERS = GRAMMAR.layers;
+const PLOT_CHANNELS = [...new Set(Object.values(LAYERS).flatMap((l) => l.channels))];
+
+export function plot(rows, mapping = {}) {
+  const data = [toTable(rows, "plot()")];
+  for (const [ch, col] of Object.entries(mapping)) {
+    if (!PLOT_CHANNELS.includes(ch)) fail("plot()", "channel", ch, PLOT_CHANNELS);
+    needColumn(data[0], col, "plot()");
+  }
+  return new Builder({ data, mapping, layers: [], facet: null, scales: {}, labels: {}, info: null, theme: { style: "pastel" } });
+}
+
+class Builder {
+  #s;
+  constructor(state) {
+    this.#s = state;
+  }
+
+  #with(changes) {
+    return new Builder({ ...this.#s, ...changes });
+  }
+
+  #layer(type, options = {}) {
+    const def = LAYERS[type];
+    const where = `${type}()`;
+    let { data, ...rest } = options;
+    let tables = this.#s.data;
+    let index = 0;
+    if (data !== undefined) {
+      tables = [...tables, toTable(data, where)];
+      index = tables.length - 1;
+    }
+    const columns = tables[index].columns;
+    const layer = { type, mapping: {}, set: {} };
+    if (index) layer.data = index;
+    for (const [key, value] of Object.entries(rest)) {
+      if (def.channels.includes(key) && typeof value === "string" && value in columns) layer.mapping[key] = value;
+      else if (def.channels.includes(key) || def.options.includes(key)) layer.set[key] = constant(key, value, where, columns);
+      else fail(where, "option", key, ["data", ...def.channels, ...def.options]);
+    }
+    return this.#with({ data: tables, layers: [...this.#s.layers, layer] });
+  }
+
+  line(options) { return this.#layer("line", options); }
+  step(options) { return this.#layer("step", options); }
+  bar(options) { return this.#layer("bar", options); }
+  hist(options) { return this.#layer("hist", options); }
+  density(options) { return this.#layer("density", options); }
+  area(options) { return this.#layer("area", options); }
+  ribbon(options) { return this.#layer("ribbon", options); }
+  smooth(options) { return this.#layer("smooth", options); }
+  path(options) { return this.#layer("path", options); }
+  point(options) { return this.#layer("point", options); }
+  hline(options) { return this.#layer("hline", options); }
+  vline(options) { return this.#layer("vline", options); }
+  abline(options) { return this.#layer("abline", options); }
+  segment(options) { return this.#layer("segment", options); }
+  rect(options) { return this.#layer("rect", options); }
+  band(options) { return this.#layer("band", options); }
+  tile(options) { return this.#layer("tile", options); }
+  text(options) { return this.#layer("text", options); }
+  errorbar(options) { return this.#layer("errorbar", options); }
+  box(options) { return this.#layer("box", options); }
+
+  facet(by, options = {}) {
+    needColumn(this.#s.data[0], by, "facet()");
+    checkKeys(options, GRAMMAR.facet, "facet()");
+    checkFree(options.free, "facet()");
+    return this.#with({ facet: { wrap: by, free: options.free ?? null, ncol: options.ncol ?? null } });
+  }
+
+  grid({ rows = null, cols = null, ...options } = {}) {
+    if (rows === null && cols === null) throw new Error("grid(): set rows, cols or both");
+    for (const col of [rows, cols]) if (col !== null) needColumn(this.#s.data[0], col, "grid()");
+    checkKeys(options, GRAMMAR.grid, "grid()");
+    checkFree(options.free, "grid()");
+    return this.#with({ facet: { rows, cols, free: options.free ?? null } });
+  }
+
+  x(options) { return this.#scale("x", options); }
+  y(options) { return this.#scale("y", options); }
+  color(options) { return this.#scale("color", options); }
+
+  #scale(name, options = {}) {
+    const where = `${name}()`;
+    checkKeys(options, GRAMMAR.scales[name], where);
+    if (options.type !== undefined && !GRAMMAR.scaleTypes.includes(options.type)) fail(where, "type", options.type, GRAMMAR.scaleTypes);
+    if (options.palette !== undefined && !Array.isArray(options.palette) && !(options.palette in THEMES.palettes)) fail(where, "palette", options.palette, Object.keys(THEMES.palettes));
+    if (options.mid !== undefined && typeof options.mid !== "number") throw new Error(`${where}: mid must be a number`);
+    const scale = { ...options };
+    if (scale.limits) {
+      if (!Array.isArray(scale.limits)) throw new Error(`${where}: limits must be a list, for example [0, 10] or [0, null]`);
+      scale.limits = scale.limits.map((v) => (v === null || v === undefined ? null : toValue(v)));
+    }
+    return this.#with({ scales: { ...this.#s.scales, [name]: scale } });
+  }
+
+  labels(options = {}) {
+    checkKeys(options, GRAMMAR.labels, "labels()");
+    return this.#with({ labels: { ...this.#s.labels, ...options } });
+  }
+
+  // A key/value table about the data or the experiment: info({ location: "hayama" }, { position: "right" }). null removes it.
+  info(entries, options = {}) {
+    checkKeys(options, GRAMMAR.info, "info()");
+    const position = options.position ?? "right";
+    if (!GRAMMAR.infoPosition.includes(position)) fail("info()", "position", position, GRAMMAR.infoPosition);
+    if (entries === null || entries === undefined) return this.#with({ info: null });
+    const pairs = Array.isArray(entries) ? entries : typeof entries === "object" ? Object.entries(entries) : null;
+    if (!pairs) throw new Error("info(): entries must be an object or a list of [key, value] pairs");
+    return this.#with({ info: { entries: pairs.map((pair) => infoEntry(pair)), position } });
+  }
+
+  theme(style = "pastel", options = {}) {
+    checkKeys(options, GRAMMAR.theme, "theme()");
+    if (!(style in THEMES.styles)) fail("theme()", "style", style, Object.keys(THEMES.styles));
+    if (options.format !== undefined && !(options.format in THEMES.formats)) fail("theme()", "format", options.format, Object.keys(THEMES.formats));
+    if (options.legend !== undefined && !GRAMMAR.legend.includes(options.legend)) fail("theme()", "legend", options.legend, GRAMMAR.legend);
+    return this.#with({ theme: { style, ...options } });
+  }
+
+  // The JSON spec. Each table keeps only the columns that a mapping or a facet uses.
+  spec() {
+    const s = this.#s;
+    const used = s.data.map(() => new Set());
+    for (const col of Object.values(s.mapping)) used.forEach((set, i) => col in s.data[i].columns && set.add(col));
+    for (const layer of s.layers) for (const col of Object.values(layer.mapping)) used[layer.data ?? 0].add(col);
+    for (const col of [s.facet?.wrap, s.facet?.rows, s.facet?.cols]) {
+      if (col) used.forEach((set, i) => col in s.data[i].columns && set.add(col));
+    }
+    const data = s.data.map((t, i) => ({ columns: Object.fromEntries([...used[i]].map((c) => [c, t.columns[c]])) }));
+    return { version: 1, data, mapping: s.mapping, layers: s.layers, facet: s.facet, scales: s.scales, labels: s.labels, ...(s.info ? { info: s.info } : {}), theme: s.theme };
+  }
+}
+
+// Rows (array of objects) to columnar data with one type per column: number, time or string.
+function toTable(rows, where) {
+  if (!Array.isArray(rows)) throw new Error(`${where}: data must be an array of row objects`);
+  const names = [...new Set(rows.flatMap(Object.keys))];
+  const columns = {};
+  for (const name of names) {
+    const raw = rows.map((r) => r[name] ?? null);
+    const first = raw.find((v) => v !== null && !Number.isNaN(v));
+    const type = first instanceof Date ? "time" : typeof first === "number" ? "number" : "string";
+    const values = raw.map((v) => (v === null || Number.isNaN(v) ? null : type === "string" ? String(v) : toValue(v)));
+    columns[name] = { type, values };
+  }
+  return { columns };
+}
+
+// Dates become wall-clock epoch ms (the time that the clock shows); floats keep 6 significant digits.
+function toValue(v) {
+  if (v instanceof Date) return v.getTime() - v.getTimezoneOffset() * 60000;
+  if (typeof v === "number" && !Number.isInteger(v)) return Number(v.toPrecision(6));
+  return v;
+}
+
+function constant(key, value, where, columns) {
+  const kind = GRAMMAR.options[key];
+  if (key === "tooltip" || key === "group") throw new Error(`${where}: ${key} must be a column. Columns: ${Object.keys(columns).join(", ")}`);
+  if (Array.isArray(kind) && !kind.includes(value)) fail(where, key, value, kind);
+  if (kind === "number" && typeof value !== "number") throw new Error(`${where}: ${key} must be a number`);
+  if (kind === "boolean" && typeof value !== "boolean") throw new Error(`${where}: ${key} must be true or false`);
+  if (key === "color" || key === "label") return value; // spec.js validates the color against the theme
+  if (typeof value === "string" && !kind) throw new Error(`${where}: "${value}" is not a column. Columns: ${Object.keys(columns).join(", ")}`);
+  return toValue(value);
+}
+
+// One [key, value] entry of info(). Numbers keep 6 significant digits; the renderer writes the value as text.
+function infoEntry(pair) {
+  if (!Array.isArray(pair) || pair.length !== 2 || typeof pair[0] !== "string") throw new Error("info(): each entry must be a [key, value] pair with a string key");
+  const [key, value] = pair;
+  if (value === null || value === undefined || (typeof value === "number" && Number.isNaN(value))) return [key, null];
+  if (!["string", "number", "boolean"].includes(typeof value)) throw new Error(`info(): the value of "${key}" must be a string, a number, a boolean or null. Format other values as a string`);
+  return [key, toValue(value)];
+}
+
+function needColumn(table, col, where) {
+  if (!(col in table.columns)) throw new Error(`${where}: "${col}" is not a column. Columns: ${Object.keys(table.columns).join(", ")}`);
+}
+
+function checkKeys(options, valid, where) {
+  for (const key of Object.keys(options)) if (!valid.includes(key)) fail(where, "option", key, valid);
+}
+
+function checkFree(free, where) {
+  if (free != null && !GRAMMAR.free.includes(free)) fail(where, "free", free, GRAMMAR.free);
+}
+
+function fail(where, what, value, valid) {
+  throw new Error(`${where}: unknown ${what} "${value}". Valid: ${valid.join(", ")}`);
+}

package/src/copy.js

@@ -0,0 +1,56 @@
+// Copy and download the figure as PNG or SVG. The image is the current view, without the hover marks.
+// The SVG loads from a data URL: some hosts (VS Code notebooks) block blob: images.
+const SCALE = 2; // PNG px per figure px
+
+// Copies a PNG to the clipboard; if the browser refuses, downloads it. Returns "Copied" or "Downloaded".
+export async function copyPNG(svg) {
+  const png = rasterize(svg);
+  try {
+    await navigator.clipboard.write([new ClipboardItem({ "image/png": png.then(toBlob) })]);
+    return "Copied";
+  } catch {
+    save((await png).toDataURL("image/png"), "plot.png");
+    return "Downloaded";
+  }
+}
+
+export async function downloadPNG(svg) {
+  save((await rasterize(svg)).toDataURL("image/png"), "plot.png");
+}
+
+export function downloadSVG(svg) {
+  save(dataURL(svg), "plot.svg");
+}
+
+async function rasterize(svg) {
+  const img = new Image();
+  img.src = dataURL(svg);
+  await img.decode();
+  const { width, height } = svg.viewBox.baseVal;
+  const canvas = document.createElement("canvas");
+  canvas.width = width * SCALE;
+  canvas.height = height * SCALE;
+  canvas.getContext("2d").drawImage(img, 0, 0, canvas.width, canvas.height);
+  return canvas;
+}
+
+function dataURL(svg) {
+  const clone = svg.cloneNode(true);
+  clone.querySelector(".pt-overlay")?.remove();
+  const { width, height } = svg.viewBox.baseVal;
+  clone.setAttribute("width", width);
+  clone.setAttribute("height", height);
+  const bytes = new TextEncoder().encode(new XMLSerializer().serializeToString(clone));
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return `data:image/svg+xml;base64,${btoa(binary)}`;
+}
+
+const toBlob = (canvas) => new Promise((resolve) => canvas.toBlob(resolve, "image/png"));
+
+function save(href, name) {
+  const a = document.createElement("a");
+  a.href = href;
+  a.download = name;
+  a.click();
+}