@loadmap/export 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaime Rojas
+
+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,19 @@
-# Temporary Holding Version
+# @loadmap/export
 
-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.
+PNG, SVG, GIF, WebM and MP4 of a [loadmap](https://jaim3r0jas.github.io/loadmap/), made frame by frame on a fixed
+clock: the same options give the same file, byte for byte.
+
+```ts
+import { download, recordVideo } from '@loadmap/export'
+
+const gif = await recordVideo(handle, {
+  format: 'gif',
+  seconds: 6,
+  caption: true,
+  script: [{ at: 2, set: { load: 30 } }],
+})
+download(gif, 'shop.gif')
+```
+
+`handle` is the `ref` of a `<Loadmap>`. `expose(handle)` lets `loadmap record` (from `@loadmap/cli`) drive the page
+from the command line. MIT.

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+import { Values } from "@loadmap/core";
+import { LoadmapHandle } from "@loadmap/react";
+/** A title line above the board and the verdict below it, so a frame says what it shows without the page. */
+interface Caption {
+  /** Default: the model's title. */
+  title?: string;
+  /** Said below the board instead of the verdict: a story step's text. */
+  text?: string;
+  /** Before the scenario and the load: "2 of 3". */
+  step?: string;
+}
+/**
+ * The board as an SVG file: the structure as drawn, the dots where they are now, and with `caption` the title line
+ * and the verdict. Text goes in as text nodes, never as markup, so a label cannot break the file.
+ */
+export declare function exportSvg(handle: LoadmapHandle, o?: {
+  caption?: boolean | Caption;
+}): Promise<string>;
+export interface ScriptStep {
+  /** Seconds into the recording. */
+  at: number;
+  /** A scenario's values, by its label; `set` goes on top. The load stays. */
+  scenario?: string;
+  set?: Partial<Values<any>>;
+  /** A story step, by index: its values and the box it points at, instead of `scenario` and `set`. */
+  step?: number;
+}
+export interface FrameOptions {
+  /** Pixels per scene unit. Default 2 for stills, 1 for video. */
+  scale?: number;
+  /** A fixed frame size: the board is scaled to fit and centred. A video keeps its first frame's size. */
+  size?: {
+    width: number;
+    height: number;
+  };
+  /** The title, scenario and load above the board and the verdict below it, so the frame stands alone. */
+  caption?: boolean | Caption;
+}
+export interface RecordOptions extends FrameOptions {
+  /** Required without `story`. */
+  seconds?: number;
+  /**
+   * Plays the model's story: each step for its seconds, its text below the board when there is a caption. Takes the
+   * place of `script` and `seconds`.
+   */
+  story?: boolean;
+  /** Default 30 for video, 15 for GIF. A GIF takes at most 50: its frame delays are whole hundredths. */
+  fps?: number;
+  format?: 'webm' | 'mp4' | 'gif';
+  /** Value changes during the recording, e.g. the load rising from 1× to 40×. */
+  script?: readonly ScriptStep[];
+  /** The sim starts over with this seed, so two recordings match frame for frame. Default 1. */
+  seed?: number;
+  /** Seconds of sim run before the first frame, so queues and dots are already flowing. Default 2. */
+  warmup?: number;
+  /** Called with every composed frame, e.g. to hash it. */
+  onFrame?: (index: number, frame: HTMLCanvasElement) => void | Promise<void>;
+}
+/** The board as one image: the SVG rasterised with its theme colours resolved, the dots painted on top. */
+export declare function composeFrame(handle: LoadmapHandle, o?: FrameOptions, into?: HTMLCanvasElement): Promise<HTMLCanvasElement>;
+/** A PNG of the board as it is now. */
+export declare function exportPng(handle: LoadmapHandle, o?: FrameOptions): Promise<Blob>;
+/**
+ * A video or GIF of a scenario, made frame by frame on a fixed clock: the live animation is paused, the sim advances
+ * exactly 1/fps per frame, and each frame is encoded at its own timestamp. Nothing depends on how fast the machine
+ * is, so the same options give the same frames. The values the script changed are put back afterwards.
+ */
+export declare function recordVideo(handle: LoadmapHandle, o: RecordOptions): Promise<Blob>;
+export interface StillOptions extends FrameOptions {
+  /** A scenario's values, by label; `set` goes on top. */
+  scenario?: string;
+  set?: Partial<Values<any>>;
+  seed?: number;
+  /** Seconds of sim run before the picture. Default 4. */
+  warmup?: number;
+}
+/** A PNG of the board after `set` and a warm-up on a fixed clock: the same options give the same picture. */
+export declare function recordStill(handle: LoadmapHandle, o?: StillOptions): Promise<Blob>;
+/**
+ * A poster: the board after a warm-up, with the title, the verdict, where each component runs out and the scenarios
+ * compared, as one PNG. The same options give the same bytes. `scale` is pixels per CSS pixel (default 2).
+ */
+export declare function recordPoster(handle: LoadmapHandle, o?: Omit<StillOptions, 'size' | 'caption'>): Promise<Blob>;
+declare global {
+  var __loadmap: Record<string, PageRecorder> | undefined;
+}
+/** What `expose` puts on the page for `loadmap record`: results come back base64-encoded. */
+export interface PageRecorder {
+  record(o: RecordOptions): Promise<string>;
+  still(o: StillOptions): Promise<string>;
+  poster(o: StillOptions): Promise<string>;
+  /** The SVG's text, not base64. */
+  svg(o: StillOptions): Promise<string>;
+}
+/**
+ * Lets `loadmap record` drive this loadmap: puts a recorder on `globalThis.__loadmap[name]`.
+ * Returns a function that takes it off again.
+ */
+export declare function expose(handle: LoadmapHandle, name?: string): () => void;
+/** Saves a blob through the browser's download. */
+export declare function download(blob: Blob, name: string): void;
+export type { Caption };

package/dist/index.js

@@ -0,0 +1,632 @@
+import { GIFEncoder, applyPalette, quantize } from "gifenc";
+import { BufferTarget, CanvasSource, Mp4OutputFormat, Output, QUALITY_HIGH, WebMOutputFormat, canEncodeVideo } from "mediabunny";
+import { compare, parseAsOf } from "@loadmap/core";
+import { fmt, monthOf, multiple, multiples, pct } from "@loadmap/core/format";
+// src/media.ts
+const captionOf = (c) => c === true ? {} : c ? c : null;
+/** The caption's bands for a frame this wide: fixed heights (three verdict lines), so a video keeps its size. */
+function bands(width) {
+	const u = Math.max(1, width / 900);
+	return {
+		u,
+		top: Math.round(44 * u),
+		bottom: Math.round(84 * u)
+	};
+}
+/** The theme as the page computed it: canvas and serialised SVG cannot read CSS variables. */
+function tokens(el) {
+	const cs = getComputedStyle(el);
+	const t = (k, fallback) => cs.getPropertyValue(`--lm-${k}`).trim() || fallback;
+	return {
+		font: cs.fontFamily || "sans-serif",
+		mono: t("mono", "monospace"),
+		bg: t("bg", "#eef2f5"),
+		surface: t("surface", "#ffffff"),
+		fg: t("fg", "#17212b"),
+		muted: t("muted", "#5d6d7c"),
+		line: t("line", "#c6d0da"),
+		ok: t("ok", "#2a7f5a"),
+		warn: t("warn", "#b86e00"),
+		drop: t("drop", "#b7392e"),
+		series: [
+			1,
+			2,
+			3,
+			4
+		].map((i) => t(`s${i}`, "#5d6d7c"))
+	};
+}
+const tierColor = (k, tier) => tier === "over" ? k.drop : tier === "warn" ? k.warn : k.ok;
+/** What the caption says: the title, the scenario and load, and the verdict. */
+function captionText(handle, c) {
+	const { model, ev } = handle.engine;
+	const scenario = model.scenarioOf(ev.values);
+	return {
+		title: c.title ?? model.title ?? "",
+		where: [
+			c.step,
+			scenario?.label,
+			`${fmt(ev.values.load)}× today`
+		].filter(Boolean).join(" · "),
+		verdict: c.text ?? ev.verdict.text,
+		tier: ev.verdict.tier
+	};
+}
+/** Lines of at most `width`, broken at spaces; past `max` lines the last ends in "…". */
+function wrap(measure, text, width, max = Infinity) {
+	const lines = [];
+	let line = "";
+	for (const word of text.split(/\s+/).filter(Boolean)) {
+		const next = line ? `${line} ${word}` : word;
+		if (!line || measure(next) <= width) line = next;
+		else {
+			lines.push(line);
+			line = word;
+		}
+	}
+	if (line) lines.push(line);
+	if (lines.length <= max) return lines;
+	const keep = lines.slice(0, max);
+	let last = keep[max - 1];
+	while (last && measure(`${last}…`) > width) last = last.slice(0, -1);
+	keep[max - 1] = `${last.trimEnd()}…`;
+	return keep;
+}
+/** Draws the caption's bands onto a frame of `w` × `h`. */
+function drawCaption(ctx, handle, c, w, h) {
+	const k = tokens(handle.board().svg);
+	const { u, top, bottom } = bands(w);
+	const t = captionText(handle, c);
+	const pad = 14 * u;
+	ctx.save();
+	ctx.setTransform(1, 0, 0, 1, 0, 0);
+	ctx.fillStyle = k.line;
+	ctx.fillRect(0, top - u, w, u);
+	ctx.fillRect(0, h - bottom, w, u);
+	ctx.textBaseline = "middle";
+	ctx.font = `500 ${13 * u}px ${k.font}`;
+	ctx.fillStyle = k.muted;
+	ctx.textAlign = "right";
+	ctx.fillText(t.where, w - pad, top / 2);
+	const whereW = ctx.measureText(t.where).width;
+	ctx.font = `600 ${16 * u}px ${k.font}`;
+	ctx.fillStyle = k.fg;
+	ctx.textAlign = "left";
+	ctx.fillText(t.title, pad, top / 2, Math.max(0, w - 3 * pad - whereW));
+	ctx.fillStyle = tierColor(k, t.tier);
+	ctx.fillRect(pad, h - bottom + 12 * u, 4 * u, bottom - 24 * u);
+	ctx.font = `400 ${14 * u}px ${k.font}`;
+	ctx.fillStyle = k.fg;
+	ctx.textBaseline = "top";
+	wrap((s) => ctx.measureText(s).width, t.verdict, w - 2 * pad - 14 * u, 3).forEach((l, i) => {
+		ctx.fillText(l, pad + 14 * u, h - bottom + (14 + i * 20) * u);
+	});
+	ctx.restore();
+}
+const PAINT = [
+	"fill",
+	"stroke",
+	"color"
+];
+/**
+* A copy of the board's SVG that needs no page: every colour that comes from a theme token is written in as the value
+* the page computed, and the font, size and namespace are set on the root.
+*/
+function standalone(svg, w, h) {
+	const copy = svg.cloneNode(true);
+	const src = [svg, ...svg.querySelectorAll("*")];
+	const dst = [copy, ...copy.querySelectorAll("*")];
+	src.forEach((el, i) => {
+		const cs = getComputedStyle(el);
+		const out = dst[i];
+		for (const p of PAINT) {
+			const a = out.getAttribute(p);
+			if (a && (a.includes("var(") || a === "currentColor")) out.setAttribute(p, cs.getPropertyValue(p));
+		}
+		if (out.style?.color) out.style.color = cs.color;
+		for (const a of [
+			"tabindex",
+			"aria-describedby",
+			"class"
+		]) out.removeAttribute(a);
+	});
+	const root = getComputedStyle(svg);
+	copy.setAttribute("font-family", root.fontFamily);
+	copy.setAttribute("color", root.color);
+	copy.setAttribute("width", String(w));
+	copy.setAttribute("height", String(h));
+	copy.setAttribute("xmlns", "http://www.w3.org/2000/svg");
+	return copy;
+}
+const NS = "http://www.w3.org/2000/svg";
+function el(name, attrs, text) {
+	const e = document.createElementNS(NS, name);
+	for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, String(v));
+	if (text != null) e.textContent = text;
+	return e;
+}
+/**
+* The board as an SVG file: the structure as drawn, the dots where they are now, and with `caption` the title line
+* and the verdict. Text goes in as text nodes, never as markup, so a label cannot break the file.
+*/
+async function exportSvg(handle, o = {}) {
+	await handle.ready();
+	const b = handle.board();
+	const { width: sw, height: sh } = b.scene;
+	const board = standalone(b.svg, sw, sh);
+	const dots = el("g", {});
+	for (const d of handle.engine.dots()) dots.appendChild(el("circle", {
+		cx: d.x.toFixed(2),
+		cy: d.y.toFixed(2),
+		r: d.r,
+		fill: d.color,
+		...d.alpha < 1 ? { "fill-opacity": d.alpha.toFixed(3) } : {}
+	}));
+	board.appendChild(dots);
+	const cap = captionOf(o.caption);
+	if (!cap) return new XMLSerializer().serializeToString(board);
+	const k = tokens(b.svg);
+	const { top, bottom } = bands(sw);
+	const h = sh + top + bottom;
+	const t = captionText(handle, cap);
+	const out = el("svg", {
+		xmlns: NS,
+		width: sw,
+		height: h,
+		viewBox: `0 0 ${sw} ${h}`,
+		"font-family": k.font
+	});
+	out.appendChild(el("rect", {
+		width: sw,
+		height: h,
+		fill: k.surface
+	}));
+	out.appendChild(el("text", {
+		x: 14,
+		y: top / 2 + 5,
+		"font-size": 16,
+		"font-weight": 600,
+		fill: k.fg
+	}, t.title));
+	out.appendChild(el("text", {
+		x: sw - 14,
+		y: top / 2 + 5,
+		"font-size": 13,
+		"text-anchor": "end",
+		fill: k.muted
+	}, t.where));
+	out.appendChild(el("rect", {
+		x: 0,
+		y: top - 1,
+		width: sw,
+		height: 1,
+		fill: k.line
+	}));
+	board.setAttribute("y", String(top));
+	out.appendChild(board);
+	out.appendChild(el("rect", {
+		x: 0,
+		y: top + sh,
+		width: sw,
+		height: 1,
+		fill: k.line
+	}));
+	out.appendChild(el("rect", {
+		x: 14,
+		y: top + sh + 12,
+		width: 4,
+		height: bottom - 24,
+		fill: tierColor(k, t.tier)
+	}));
+	const ctx = document.createElement("canvas").getContext("2d");
+	ctx.font = `400 14px ${k.font}`;
+	wrap((s) => ctx.measureText(s).width, t.verdict, sw - 42, 3).forEach((line, i) => {
+		out.appendChild(el("text", {
+			x: 28,
+			y: top + sh + 28 + i * 20,
+			"font-size": 14,
+			fill: k.fg
+		}, line));
+	});
+	return new XMLSerializer().serializeToString(out);
+}
+/**
+* One picture that answers the question on its own: the title, the scenario and load, the board, the verdict, where
+* each component runs out (with dates, given growth), the scenarios compared, and which capacities are estimates.
+* `scale` is pixels per CSS pixel (default 2).
+*/
+/** The poster's width and the board's place in it, in CSS pixels: one source for the board image and the drawing. */
+function posterLayout(scene) {
+	const W = Math.max(720, Math.min(1400, scene.width + 48));
+	const pad = 24;
+	const inner = W - 48;
+	return {
+		W,
+		pad,
+		inner,
+		boardH: scene.height * inner / scene.width
+	};
+}
+async function drawPoster(handle, image, scale = 2) {
+	const b = handle.board();
+	const { model, ev } = handle.engine;
+	const k = tokens(b.svg);
+	const { W, pad, inner, boardH } = posterLayout(b.scene);
+	const date = (x) => {
+		const d = model.dateAt(x);
+		return d ? ` (${monthOf(d, true)})` : "";
+	};
+	const at = (r, x) => r ? `${multiples(r, model.searchMax, true)}${date(r.low)}` : `${multiple(x, model.searchMax)}${date(x)}`;
+	const t = captionText(handle, {});
+	const g = model.growth;
+	const sub = [t.where, g && `load grows ${fmt(g.rate * 100)} % a ${g.per} from ${monthOf(parseAsOf(g.asOf))}`].filter(Boolean).join(" · ");
+	const rows = model.scenarios.length > 1 ? compare(model, ev.values.load) : null;
+	const estimates = ev.assumptions.flatMap((a) => a.kind === "capacity" && a.capacity.provenance === "estimated" ? [a.name] : []);
+	const measure = document.createElement("canvas").getContext("2d");
+	const font = (weight, size, mono = false) => `${weight} ${size}px ${mono ? k.mono : k.font}`;
+	const lines = (text, f, width) => {
+		measure.font = f;
+		return wrap((s) => measure.measureText(s).width, text, width);
+	};
+	const verdict = lines(t.verdict, font(400, 15), inner - 20);
+	const hint = ev.measure ? lines(ev.measure.text, font(400, 13), inner - 20) : [];
+	const compared = rows ? lines(rows.text, font(400, 14), inner) : [];
+	const blocks = [];
+	const text = (ctx, s, x, y, f, color, align = "left") => {
+		ctx.font = f;
+		ctx.fillStyle = color;
+		ctx.textAlign = align;
+		ctx.fillText(s, x, y);
+	};
+	const heading = (s) => blocks.push([30, (ctx, y) => text(ctx, s.toUpperCase(), pad, y + 20, font(600, 11), k.muted)]);
+	blocks.push([34, (ctx, y) => text(ctx, t.title, pad, y + 26, font(600, 22), k.fg)]);
+	blocks.push([26, (ctx, y) => text(ctx, sub, pad, y + 16, font(400, 13), k.muted)]);
+	blocks.push([boardH + 16, (ctx, y) => {
+		ctx.fillStyle = k.line;
+		ctx.fillRect(pad - 1, y + 7, inner + 2, boardH + 2);
+		ctx.drawImage(image, pad, y + 8, inner, boardH);
+	}]);
+	blocks.push([verdict.length * 22 + 20, (ctx, y) => {
+		ctx.fillStyle = tierColor(k, t.tier);
+		ctx.fillRect(pad, y + 6, 4, verdict.length * 22 + 8);
+		verdict.forEach((l, i) => {
+			text(ctx, l, pad + 16, y + 24 + i * 22, font(400, 15), k.fg);
+		});
+	}]);
+	if (hint.length) blocks.push([hint.length * 18 + 6, (ctx, y) => {
+		hint.forEach((l, i) => {
+			text(ctx, l, pad + 16, y + 14 + i * 18, font(400, 13), k.muted);
+		});
+	}]);
+	heading("Where it runs out, in order");
+	const top = Math.max(1.5, model.thresholds.full * 1.5);
+	blocks.push([16, (ctx, y) => {
+		const th = model.thresholds;
+		text(ctx, "0", pad, y + 10, font(400, 11, true), k.muted);
+		text(ctx, `${pct(th.target)} target`, pad + inner * th.target / top, y + 10, font(400, 11, true), k.muted, "center");
+		text(ctx, pct(th.full), pad + inner * th.full / top, y + 10, font(400, 11, true), k.muted, "center");
+		text(ctx, pct(top), W - pad, y + 10, font(400, 11, true), k.muted, "right");
+	}]);
+	for (const c of ev.ranked) blocks.push([46, (ctx, y) => {
+		const first = c === ev.firstLimit ? " · first limit" : "";
+		text(ctx, `${c.name}${first}`, pad, y + 16, font(600, 14), k.fg);
+		const right = c.util == null ? "switched off" : `${pct(c.util)} now · ${pct(model.thresholds.target)} at ${at(c.targetRange, c.target)} · ${pct(model.thresholds.full)} at ${at(c.fullRange, c.full)}`;
+		text(ctx, right, W - pad, y + 16, font(400, 12, true), k.muted, "right");
+		ctx.fillStyle = k.bg;
+		ctx.fillRect(pad, y + 24, inner, 10);
+		ctx.fillStyle = c.state === "over" ? k.drop : c.state === "warn" ? k.warn : k.ok;
+		ctx.fillRect(pad, y + 24, inner * Math.min(top, c.util ?? 0) / top, 10);
+		ctx.fillStyle = k.fg;
+		for (const th of [model.thresholds.target, model.thresholds.full]) ctx.fillRect(pad + inner * th / top, y + 22, 1, 14);
+	}]);
+	if (rows) {
+		heading("Scenarios compared");
+		blocks.push([compared.length * 20 + 6, (ctx, y) => {
+			compared.forEach((l, i) => {
+				text(ctx, l, pad, y + 15 + i * 20, font(400, 14), k.fg);
+			});
+		}]);
+		rows.rows.forEach((r, i) => {
+			blocks.push([26, (ctx, y) => {
+				ctx.fillStyle = k.series[i] ?? k.muted;
+				ctx.beginPath();
+				ctx.arc(pad + 5, y + 13, 5, 0, Math.PI * 2);
+				ctx.fill();
+				text(ctx, r.label, pad + 18, y + 18, font(600, 14), k.fg);
+				const what = `first limit ${r.firstLimit?.name ?? "—"} · ${pct(model.thresholds.target)} at ${at(r.targetRange, r.target)} · runs out at ${at(r.fullRange, r.full)}`;
+				text(ctx, what, W - pad, y + 18, font(400, 12, true), k.muted, "right");
+			}]);
+		});
+	}
+	if (estimates.length) blocks.push([30, (ctx, y) => text(ctx, `Estimated capacities: ${estimates.join(", ")}.`, pad, y + 22, font(400, 12), k.muted)]);
+	const H = Math.ceil(blocks.reduce((a, [h]) => a + h, 0) + 2 * pad);
+	const canvas = document.createElement("canvas");
+	canvas.width = Math.round(W * scale);
+	canvas.height = Math.round(H * scale);
+	const ctx = canvas.getContext("2d");
+	ctx.scale(scale, scale);
+	ctx.fillStyle = k.surface;
+	ctx.fillRect(0, 0, W, H);
+	ctx.textBaseline = "alphabetic";
+	let y = pad;
+	for (const [h, draw] of blocks) {
+		draw(ctx, y);
+		y += h;
+	}
+	return canvas;
+}
+// src/index.ts
+/** A script step: a story step, or values. */
+function apply(handle, s) {
+	if (s.step == null) return handle.setValues(valuesOf(handle, s));
+	if (!handle.engine.model.story[s.step]) throw new Error(`loadmap: the story has no step ${s.step + 1}`);
+	handle.setStoryStep(s.step);
+}
+/** What a script step or a still sets: a scenario's values, then `set`. An unknown scenario names the known ones. */
+function valuesOf(handle, o) {
+	if (o.scenario == null) return { ...o.set };
+	const model = handle.engine.model;
+	const s = model.scenarios.find((x) => x.label === o.scenario);
+	if (!s) {
+		const known = model.scenarios.map((x) => `"${x.label}"`).join(", ");
+		throw new Error(`loadmap: no scenario "${o.scenario}"; ${known ? `the model has ${known}` : "the model has none"}`);
+	}
+	return {
+		...s.values,
+		...o.set
+	};
+}
+/** The board as one image: the SVG rasterised with its theme colours resolved, the dots painted on top. */
+async function composeFrame(handle, o = {}, into) {
+	await handle.ready();
+	const b = handle.board();
+	const cap = captionOf(o.caption);
+	const w = o.size?.width ?? even(b.scene.width * (o.scale ?? 2));
+	const band = cap ? bands(w) : {
+		top: 0,
+		bottom: 0
+	};
+	const h = o.size?.height ?? even(b.scene.height * (o.scale ?? 2) + band.top + band.bottom);
+	const room = h - band.top - band.bottom;
+	const scale = Math.min(w / b.scene.width, room / b.scene.height);
+	const dw = b.scene.width * scale;
+	const dh = b.scene.height * scale;
+	const c = into ?? document.createElement("canvas");
+	if (c.width !== w || c.height !== h) {
+		c.width = w;
+		c.height = h;
+	}
+	const ctx = c.getContext("2d");
+	ctx.setTransform(1, 0, 0, 1, 0, 0);
+	ctx.fillStyle = getComputedStyle(b.svg).getPropertyValue("--lm-surface").trim() || "#fff";
+	ctx.fillRect(0, 0, w, h);
+	const img = await rasterise(b.svg, Math.round(dw), Math.round(dh));
+	ctx.translate((w - dw) / 2, band.top + (room - dh) / 2);
+	ctx.drawImage(img, 0, 0, dw, dh);
+	handle.engine.paintParticles(ctx, scale);
+	if (cap) drawCaption(ctx, handle, cap, w, h);
+	return c;
+}
+/** A PNG of the board as it is now. */
+async function exportPng(handle, o = {}) {
+	return toPng(await composeFrame(handle, o));
+}
+/**
+* A video or GIF of a scenario, made frame by frame on a fixed clock: the live animation is paused, the sim advances
+* exactly 1/fps per frame, and each frame is encoded at its own timestamp. Nothing depends on how fast the machine
+* is, so the same options give the same frames. The values the script changed are put back afterwards.
+*/
+async function recordVideo(handle, o) {
+	const format = o.format ?? "webm";
+	const fps = o.fps ?? (format === "gif" ? 15 : 30);
+	const story = o.story ? handle.engine.model.story : null;
+	if (story && !story.length) throw new Error("loadmap: the model has no story");
+	const starts = story?.map((_, i) => story.slice(0, i).reduce((t, s) => t + s.seconds, 0));
+	const seconds = story ? story.reduce((t, s) => t + s.seconds, 0) : o.seconds;
+	if (!(fps > 0) || !(seconds != null && seconds > 0)) throw new Error("loadmap: seconds and fps must be positive");
+	if (format === "gif" && fps > 50) throw new Error("loadmap: a GIF plays at most 50 frames a second");
+	const script = story ? starts.map((at, step) => ({
+		at,
+		step
+	})) : [...o.script ?? []].sort((a, b) => a.at - b.at);
+	const cap = captionOf(o.caption);
+	/** The caption for the step shown: its text instead of the verdict. */
+	const captionNow = () => {
+		const i = handle.storyStep();
+		const st = story && i != null ? story[i] : void 0;
+		return cap && st ? {
+			...cap,
+			text: st.text,
+			step: `${i + 1} of ${story.length}`
+		} : o.caption;
+	};
+	await handle.ready();
+	const before = handle.values();
+	const beforeStep = handle.storyStep();
+	handle.pause();
+	try {
+		for (const s of script.filter((s) => s.at <= 0)) apply(handle, s);
+		await warmUp(handle, o.seed ?? 1, o.warmup ?? 2, fps);
+		const canvas = document.createElement("canvas");
+		if (format === "gif") canvas.getContext("2d", { willReadFrequently: true });
+		await composeFrame(handle, {
+			scale: o.scale ?? 1,
+			caption: captionNow()
+		}, canvas);
+		const sink = format === "gif" ? gifSink(canvas, fps) : await videoSink(canvas, format, fps);
+		const frames = Math.round(seconds * fps);
+		let next = script.findIndex((s) => s.at > 0);
+		for (let i = 0; i < frames; i++) {
+			const t = i / fps;
+			while (next >= 0 && next < script.length && script[next].at <= t) {
+				apply(handle, script[next]);
+				next++;
+			}
+			await handle.ready();
+			handle.step(1 / fps);
+			await composeFrame(handle, {
+				size: {
+					width: canvas.width,
+					height: canvas.height
+				},
+				caption: captionNow()
+			}, canvas);
+			await o.onFrame?.(i, canvas);
+			await sink.add(t);
+		}
+		return await sink.finish();
+	} finally {
+		if (handle.storyStep() !== beforeStep) handle.setStoryStep(beforeStep);
+		handle.setValues(before);
+		handle.resume();
+	}
+}
+/** A PNG of the board after `set` and a warm-up on a fixed clock: the same options give the same picture. */
+async function recordStill(handle, o = {}) {
+	return settled(handle, o, () => exportPng(handle, o));
+}
+/**
+* A poster: the board after a warm-up, with the title, the verdict, where each component runs out and the scenarios
+* compared, as one PNG. The same options give the same bytes. `scale` is pixels per CSS pixel (default 2).
+*/
+async function recordPoster(handle, o = {}) {
+	return settled(handle, o, async () => {
+		const scale = o.scale ?? 2;
+		const { inner, boardH } = posterLayout(handle.board().scene);
+		return toPng(await drawPoster(handle, await composeFrame(handle, { size: {
+			width: even(inner * scale),
+			height: even(boardH * scale)
+		} }), scale));
+	});
+}
+/** Sets the values, warms the sim up on a fixed clock, makes the picture, and puts the values back. */
+async function settled(handle, o, make) {
+	await handle.ready();
+	const before = handle.values();
+	handle.pause();
+	try {
+		if (o.set || o.scenario != null) handle.setValues(valuesOf(handle, o));
+		await warmUp(handle, o.seed ?? 1, o.warmup ?? 4, 30);
+		return await make();
+	} finally {
+		handle.setValues(before);
+		handle.resume();
+	}
+}
+function toPng(c) {
+	return new Promise((resolve, reject) => c.toBlob((b) => b ? resolve(b) : reject(/* @__PURE__ */ new Error("loadmap: PNG failed")), "image/png"));
+}
+/**
+* Lets `loadmap record` drive this loadmap: puts a recorder on `globalThis.__loadmap[name]`.
+* Returns a function that takes it off again.
+*/
+function expose(handle, name = "default") {
+	const recorder = {
+		record: async (o) => base64(await recordVideo(handle, o)),
+		still: async (o) => base64(await recordStill(handle, o)),
+		poster: async (o) => base64(await recordPoster(handle, o)),
+		svg: (o) => settled(handle, o, () => exportSvg(handle, o))
+	};
+	globalThis.__loadmap ??= {};
+	globalThis.__loadmap[name] = recorder;
+	return () => {
+		if (globalThis.__loadmap?.[name] === recorder) delete globalThis.__loadmap[name];
+	};
+}
+async function warmUp(handle, seed, seconds, fps) {
+	await handle.ready();
+	handle.reset(seed);
+	for (let i = 0, n = Math.round(seconds * fps); i < n; i++) handle.step(1 / fps);
+}
+async function videoSink(canvas, format, fps) {
+	const codec = await pickCodec(format, canvas.width, canvas.height);
+	const output = new Output({
+		format: format === "mp4" ? new Mp4OutputFormat({ fastStart: "in-memory" }) : new WebMOutputFormat(),
+		target: new BufferTarget()
+	});
+	const source = new CanvasSource(canvas, {
+		codec,
+		bitrate: QUALITY_HIGH,
+		keyFrameInterval: 2
+	});
+	output.addVideoTrack(source, { frameRate: fps });
+	await output.start();
+	return {
+		add: (t) => source.add(t, 1 / fps),
+		finish: async () => {
+			source.close();
+			await output.finalize();
+			const buf = output.target.buffer;
+			return new Blob([buf], { type: format === "mp4" ? "video/mp4" : "video/webm" });
+		}
+	};
+}
+/** A GIF with a palette per frame, so flow colours stay true; pure JavaScript, so its bytes are reproducible. */
+function gifSink(canvas, fps) {
+	const gif = GIFEncoder();
+	const ctx = canvas.getContext("2d");
+	const cs = (i) => Math.round(100 * i / fps);
+	let i = 0;
+	return {
+		add: async () => {
+			const { data, width, height } = ctx.getImageData(0, 0, canvas.width, canvas.height);
+			const palette = quantize(data, 256);
+			const delay = 10 * (cs(i + 1) - cs(i));
+			i++;
+			gif.writeFrame(applyPalette(data, palette), width, height, {
+				palette,
+				delay,
+				repeat: 0
+			});
+		},
+		finish: async () => {
+			gif.finish();
+			return new Blob([gif.bytes()], { type: "image/gif" });
+		}
+	};
+}
+async function base64(b) {
+	const bytes = new Uint8Array(await b.arrayBuffer());
+	let s = "";
+	for (let i = 0; i < bytes.length; i += 32768) s += String.fromCharCode(...bytes.subarray(i, i + 32768));
+	return btoa(s);
+}
+/** Saves a blob through the browser's download. */
+function download(blob, name) {
+	const a = document.createElement("a");
+	a.href = URL.createObjectURL(blob);
+	a.download = name;
+	a.click();
+	setTimeout(() => URL.revokeObjectURL(a.href), 1e4);
+}
+const even = (x) => Math.max(2, Math.round(x / 2) * 2);
+async function pickCodec(format, width, height) {
+	const options = format === "mp4" ? [
+		"avc",
+		"vp9",
+		"av1"
+	] : [
+		"vp9",
+		"vp8",
+		"av1"
+	];
+	for (const c of options) if (await canEncodeVideo(c, {
+		width,
+		height
+	})) return c;
+	throw new Error(`loadmap: this browser cannot encode ${format} video`);
+}
+/** An SVG drawn as an image cannot see the page's CSS: it is drawn from a copy with the theme written in. */
+async function rasterise(svg, w, h) {
+	const copy = standalone(svg, w, h);
+	const url = URL.createObjectURL(new Blob([new XMLSerializer().serializeToString(copy)], { type: "image/svg+xml" }));
+	try {
+		const img = new Image();
+		img.src = url;
+		await img.decode();
+		return img;
+	} finally {
+		URL.revokeObjectURL(url);
+	}
+}
+export { composeFrame, download, exportPng, exportSvg, expose, recordPoster, recordStill, recordVideo };

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@loadmap/export",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "PNG, GIF, WebM and MP4 of a loadmap, recorded on a fixed clock so the same options give the same file.",
+  "keywords": [
+    "loadmap",
+    "gif",
+    "video",
+    "export"
+  ],
+  "license": "MIT",
+  "author": "Jaime Rojas",
+  "homepage": "https://jaim3r0jas.github.io/loadmap/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jaim3r0jas/loadmap.git",
+    "directory": "packages/export"
+  },
+  "bugs": "https://github.com/jaim3r0jas/loadmap/issues",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@loadmap/core": "0.1.1",
+    "@loadmap/react": "0.1.1",
+    "gifenc": "^1.0.3",
+    "mediabunny": "^1.65.0"
+  },
+  "peerDependencies": {},
+  "scripts": {
+    "build": "tsdown"
+  }
 }