@posuta/posuta 0.0.0-stage → 0.1.0

package/src/dom-server.js

@@ -0,0 +1,4 @@
+import { parseHTML } from "linkedom";
+/** A DOM for Observable Plot at build time. */
+export const dom = () => parseHTML("<!doctype html><html><body></body></html>").document;
+export { default as katex } from "katex";

package/src/figure/Caption.astro

@@ -0,0 +1,6 @@
+---
+// <Figure.Caption>: the caption. `as` renders another element (default figcaption).
+interface Props { as?: string; class?: string; [attr: string]: unknown }
+const { as: Tag = "figcaption", class: cls, ...rest } = Astro.props;
+---
+<Tag class:list={["posuta-caption", cls]} {...rest}><slot /></Tag>

package/src/figure/Media.astro

@@ -0,0 +1,27 @@
+---
+// <Figure.Media>: an image, an SVG or a video. `alt` is required.
+//   src={plot} (import plot from "./plot.svg")   inlined SVG: the poster's fonts, vector in print;
+//                                its own class kept, $…$ in its text rendered with KaTeX
+//   src={photo} or "/photo.jpg"  <img> at its original resolution
+//   src="/clip.mp4" poster="/clip.jpg"   a video on screen; in print, the poster frame as an image
+// class goes on the media element (and on the print frame of a video); other attributes on the
+// video or image, e.g. autoplay muted loop.
+import { inlineSvg } from "../svg.js";
+interface Props { src: any; alt: string; poster?: any; class?: string; [attr: string]: unknown }
+const { src, alt, poster, class: cls, ...rest } = Astro.props;
+if (!alt) throw new Error("posuta <Figure.Media>: `alt` is required (what it shows, for screen readers)");
+const Svg = typeof src === "function" ? src : null; // Astro turns imported .svg files into components
+const url = (s: any) => (typeof s === "string" ? s : s?.src);
+const video = !Svg && /\.(mp4|webm|mov|m4v|ogv)(\?|#|$)/i.test(url(src) ?? "");
+if (video && !poster) throw new Error("posuta <Figure.Media>: a video needs `poster`, the frame that prints");
+const classes = ["posuta-media", cls];
+// posuta's Vite plugin tags imported SVGs with their file (index.js); without it, Astro's component.
+const svg = Svg?.posutaFile && inlineSvg(Svg.posutaFile, { class: classes.filter(Boolean).join(" "), role: "img", "aria-label": alt, ...rest });
+---
+{svg ? <Fragment set:html={svg} />
+  : Svg ? <Svg class:list={classes} role="img" aria-label={alt} {...rest} />
+  : video ? (
+    <video class:list={classes} src={url(src)} poster={url(poster)} aria-label={alt} controls playsinline preload="metadata" data-print="hide" {...rest} />
+    <img class:list={classes} src={url(poster)} alt={alt} width={poster?.width} height={poster?.height} data-print="only" />
+  )
+  : <img class:list={classes} src={url(src)} alt={alt} width={src?.width} height={src?.height} {...rest} />}

package/src/figure/Root.astro

@@ -0,0 +1,7 @@
+---
+// <Figure.Root>: the figure element. Put Figure.Media, Figure.Caption and anything else inside,
+// in any order. `as` renders another element (default figure).
+interface Props { as?: string; class?: string; [attr: string]: unknown }
+const { as: Tag = "figure", class: cls, ...rest } = Astro.props;
+---
+<Tag class:list={["posuta-figure", cls]} {...rest}><slot /></Tag>

package/src/figure/index.js

@@ -0,0 +1,9 @@
+// Figure and its parts: <Figure src alt caption /> for the usual case, or build your own:
+//   <Figure.Root><Figure.Caption>…</Figure.Caption><a href="…"><Figure.Media src alt /></a></Figure.Root>
+import Figure from "../Figure.astro";
+import Caption from "./Caption.astro";
+import Media from "./Media.astro";
+import Root from "./Root.astro";
+
+export default Object.assign(Figure, { Root, Media, Caption });
+export { Root, Media, Caption };

package/src/index.js

@@ -0,0 +1,59 @@
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { unified } from "@astrojs/markdown-remark";
+import mdx from "@astrojs/mdx";
+import rehypeKatex from "rehype-katex";
+import remarkMath from "remark-math";
+import remarkAutoImport from "./remark-auto-import.js";
+import remarkCite from "./remark-cite.js";
+
+/**
+ * posuta's Astro integration: one line in astro.config, and posters are MDX pages with math,
+ * citations, and components available without import lines.
+ * @param {{ theme?: string, citationStyle?: string, remarkPlugins?: any[], rehypePlugins?: any[] }} [options]
+ *   theme: a CSS file or package of :root tokens, e.g. "@my-lab/posuta-theme"
+ *   citationStyle: vancouver (default), apa, harvard1, or a .csl file relative to the project root
+ *   remarkPlugins, rehypePlugins: yours, run after posuta's (e.g. rehype-mermaid for diagrams)
+ * @returns {import("astro").AstroIntegration}
+ */
+export default function posuta({ theme, citationStyle = "vancouver", remarkPlugins = [], rehypePlugins = [] } = {}) {
+  return {
+    name: "posuta",
+    hooks: {
+      "astro:config:setup": ({ config, updateConfig, injectScript, logger }) => {
+        // posuta's CSS is layered (posuta.base, posuta.theme), so these unlayered tokens win whatever the order.
+        if (theme) injectScript("page-ssr", `import ${JSON.stringify(theme)};`);
+        globalThis.__posutaRoot = fileURLToPath(config.root); // data/ lives here (see data.js)
+        const has = (name) => config.integrations.some((i) => i.name === name);
+        const integrations = [];
+        if (!has("@astrojs/mdx")) integrations.push(mdx());
+        const markdown = {};
+        if (config.markdown.processor?.name !== "satteri") logger.warn("markdown.processor is set; add remark-math, rehype-katex and posuta's remark-cite and remark-auto-import to it yourself");
+        else {
+          const components = fileURLToPath(new URL("components/", config.srcDir));
+          const style = citationStyle.endsWith(".csl") ? fileURLToPath(new URL(citationStyle, config.root)) : citationStyle;
+          markdown.processor = unified({
+            remarkPlugins: [remarkMath, [remarkCite, { style }], [remarkAutoImport, { components }], ...remarkPlugins],
+            rehypePlugins: [rehypeKatex, ...rehypePlugins],
+          });
+        }
+        // base.css loads KaTeX's fonts from posuta's own node_modules, which can sit outside the
+        // project (a linked posuta); added after resolve so Vite keeps its default allow list.
+        const katex = dirname(createRequire(import.meta.url).resolve("katex/package.json"));
+        const allowKatex = { name: "posuta:allow-katex", configResolved: (c) => { c.server.fs.allow.push(katex); } };
+        // Imported .svg files are Astro components that hide their markup; tag each with its file
+        // so Figure.Media can inline it with its own class kept and $…$ rendered.
+        const svgFile = {
+          name: "posuta:svg-file", enforce: "post",
+          transform(code, id) {
+            if (!id.endsWith(".svg") || !code.includes("export default createSvgComponent(")) return;
+            return code.replace("export default createSvgComponent(", "const svg = createSvgComponent(") +
+              `\nexport default Object.defineProperty(svg, "posutaFile", { value: ${JSON.stringify(id)} });`;
+          },
+        };
+        updateConfig({ integrations, markdown, vite: { plugins: [allowKatex, svgFile] } });
+      },
+    },
+  };
+}

package/src/md.js

@@ -0,0 +1,29 @@
+// Inline Markdown in frontmatter text (a lede, a stat label) → HTML: emphasis, links, `code`,
+// $…$ maths, and [@key] citations numbered as on the page (pass frontmatter.references).
+//   <p class="lede" set:html={await md(lede, frontmatter.references)} />
+import { createMarkdownProcessor } from "@astrojs/markdown-remark";
+import rehypeKatex from "rehype-katex";
+import remarkMath from "remark-math";
+import { CITE } from "./remark-cite.js";
+
+let processor;
+
+/**
+ * @param {string | undefined} text
+ * @param {{ key: string, n: number }[]} [references] frontmatter.references
+ */
+export async function md(text, references = []) {
+  if (text == null) return "";
+  const n = new Map(references.map((r) => [r.key, r.n]));
+  const src = String(text).replace(CITE, (_, keys) => {
+    const links = keys.split(";").map((k) => k.trim().slice(1)).map((key) => {
+      if (!n.has(key)) throw new Error(`posuta md: [@${key}] is not on frontmatter.references (is \`bibliography\` set?)`);
+      return `<a href="#ref-${key}">${n.get(key)}</a>`;
+    });
+    return `<span class="posuta-cite">[${links.join(", ")}]</span>`;
+  });
+  processor ??= createMarkdownProcessor({ remarkPlugins: [remarkMath], rehypePlugins: [rehypeKatex], syntaxHighlight: false });
+  const { code } = await (await processor).render(src);
+  // One paragraph comes back without its <p>, to go inside the author's own element.
+  return code.trim().replace(/^<p>((?:(?!<p>)[\s\S])*)<\/p>$/, "$1");
+}

package/src/overflow.js

@@ -0,0 +1,36 @@
+// The overflow check, run in the page: posuta pdf passes it to page.evaluate, the dev print
+// preview imports it. Self-contained (no outer variables) so it survives serialisation.
+
+/**
+ * Measure the laid-out canvas against its padding edge. Returns null without a .posuta-canvas,
+ * else a message per overflowing block (the innermost: an element led by h1–h4 or with
+ * data-name), or for the canvas itself when no block is to blame. Empty when it fits.
+ * @param {boolean} [mark] also set data-posuta-overflow on the blocks named
+ */
+export function overflow(mark = false) {
+  const canvas = document.querySelector(".posuta-canvas");
+  if (!canvas) return null;
+  const pad = getComputedStyle(canvas);
+  const box = canvas.getBoundingClientRect();
+  const limit = { bottom: box.bottom - parseFloat(pad.paddingBottom), right: box.right - parseFloat(pad.paddingRight) };
+  const toMm = (v) => Math.round((v * 25.4) / 96);
+  const lead = (el) => (el.firstElementChild?.matches("h1, h2, h3, h4") ? el.firstElementChild : null);
+  const blocks = [...canvas.querySelectorAll("*")].filter((el) => el.dataset.name || lead(el));
+  const over = [];
+  for (const el of blocks) {
+    const r = el.getBoundingClientRect();
+    const name = el.dataset.name || lead(el).textContent.trim();
+    const wide = Math.max(r.right - limit.right, el.scrollWidth - el.clientWidth);
+    if (r.bottom > limit.bottom + 1) over.push({ el, msg: `"${name}" runs ${toMm(r.bottom - limit.bottom)} mm past the bottom` });
+    else if (wide > 1) over.push({ el, msg: `"${name}" is ${toMm(wide)} mm too wide` });
+  }
+  // Name the innermost block, not the column or section around it.
+  const inner = over.filter((o) => !over.some((p) => p !== o && o.el.contains(p.el)));
+  if (mark) inner.forEach((o) => o.el.setAttribute("data-posuta-overflow", ""));
+  if (inner.length) return inner.map((o) => o.msg);
+  // Nothing named overflows: check the canvas itself (its scroll size includes its end padding).
+  const down = canvas.scrollHeight - canvas.clientHeight, wide = canvas.scrollWidth - canvas.clientWidth;
+  if (down > 1) return [`the poster runs ${toMm(down)} mm past the bottom`];
+  if (wide > 1) return [`the poster is ${toMm(wide)} mm too wide`];
+  return [];
+}

package/src/plot.js

@@ -0,0 +1,141 @@
+// Observable Plot → SVG markup, with posuta's defaults (theme font, transparent background) and
+// $…$ in any text rendered with KaTeX.
+import * as Plot from "@observablehq/plot";
+import { dom, katex as buildKatex } from "#dom";
+import { MATH, esc, tex } from "./tex.js";
+
+let katex = buildKatex; // null in the browser until plotLive needs it
+const SVG = "http://www.w3.org/2000/svg";
+const inherited = (el, name) => el.closest(`[${name}]`)?.getAttribute(name);
+
+/**
+ * Replace text holding $…$ with KaTeX, in place: SVG text becomes a foreignObject at the same
+ * spot and alignment; HTML text (legends) gets the markup directly. Returns how many it changed.
+ */
+export function mathify(root, k) {
+  let n = 0;
+  for (const t of [...root.querySelectorAll("text")]) {
+    if (!MATH.test(t.textContent)) continue;
+    // shortcut: a multi-line label (several tspans) becomes one line; split it into two labels if needed.
+    const anchor = inherited(t, "text-anchor") ?? "start";
+    // Plot nudges text with dy, or with an em-valued y; both mean vertical alignment here.
+    const yEm = /em$/.test(t.getAttribute("y") ?? "") ? parseFloat(t.getAttribute("y")) : 0;
+    const dy = parseFloat(inherited(t, "dy") ?? "0") + yEm;
+    const tx = { start: "0", middle: "-50%", end: "-100%" }[anchor] ?? "0";
+    const ty = dy > 0.6 ? "0" : dy > 0.1 ? "-50%" : "-80%"; // Plot's dy: .71em hangs, .32em centres, 0 sits on the baseline
+    const fill = inherited(t, "fill");
+    const fo = t.ownerDocument.createElementNS(SVG, "foreignObject");
+    for (const a of ["x", "y", "transform"]) if (t.getAttribute(a) && !/em$/.test(t.getAttribute(a))) fo.setAttribute(a, t.getAttribute(a));
+    fo.setAttribute("width", "1");
+    fo.setAttribute("height", "1");
+    fo.setAttribute("overflow", "visible");
+    const color = fill && fill !== "currentColor" ? `color:${fill};` : "";
+    fo.innerHTML = `<div xmlns="http://www.w3.org/1999/xhtml" class="posuta-tex" style="${color}transform:translate(${tx},${ty})">${tex(t.textContent, k)}</div>`;
+    t.replaceWith(fo);
+    n++;
+  }
+  for (const el of [root, ...root.querySelectorAll("*")]) {
+    if (el.closest("svg")) continue;
+    for (const node of [...el.childNodes]) {
+      if (node.nodeType !== 3 || !MATH.test(node.textContent)) continue;
+      const span = el.ownerDocument.createElement("span");
+      span.innerHTML = tex(node.textContent, k);
+      node.replaceWith(span);
+      n++;
+    }
+  }
+  return n;
+}
+
+/** Plot options with the theme defaults filled in. */
+export function withDefaults(options) {
+  return {
+    ...options,
+    style: { background: "transparent", fontFamily: "var(--font-body)", ...options.style },
+  };
+}
+
+/** Render to an element. At build time math is rendered too; in the browser use plotLive. */
+export function plot(options) {
+  const el = Plot.plot({ ...withDefaults(options), document: dom() });
+  if (katex) mathify(el, katex);
+  return el;
+}
+
+/** Render in the browser, loading KaTeX the first time a chart has $…$ in it. */
+export async function plotLive(options) {
+  const el = plot(options);
+  if (!katex && MATH.test(el.textContent)) {
+    katex = (await import("katex")).default;
+    mathify(el, katex);
+  }
+  return el;
+}
+
+/** Render to markup; works at build time, with no browser. */
+export const renderPlot = (options) => plot(options).outerHTML;
+
+export { Plot };
+
+/** The first mark with x and y channels, and its channel fields: what the pointer follows. */
+function pointerOf(options) {
+  const mark = (options.marks ?? []).flat(Infinity).find((m) => m?.channels?.x && m.channels.y && m.data);
+  if (!mark) return null;
+  const ch = Object.fromEntries(["stroke", "fill", "z", "x", "y"] // series first, as in Plot's own tip
+    .filter((k) => mark.channels[k]).map((k) => [k, mark.channels[k].value]));
+  return { mark, ch };
+}
+
+/**
+ * Add a crosshair and a highlighted point that follow the pointer. They draw nothing until the
+ * pointer moves, so print and no-JS output are unchanged. The tooltip itself is HTML (attachTip),
+ * because Plot's own tip is SVG text and cannot hold maths.
+ */
+export function withPointer(options) {
+  const p = pointerOf(options);
+  if (!p) return options;
+  const { x, y, stroke, fill } = p.ch;
+  const { fx, fy } = p.mark; // facet channels, so the pointer stays in the facet it points at
+  return {
+    ...options,
+    marks: [...options.marks, Plot.crosshair(p.mark.data, { x, y, fx, fy }),
+      Plot.dot(p.mark.data, Plot.pointer({ x, y, fx, fy, fill: stroke ?? fill ?? "currentColor", r: 4, className: "posuta-pointer" }))],
+  };
+}
+
+/** Tooltip rows for a datum: [label, value] pairs, labels from the scales, with $math$ kept. */
+export function tipRows(options, d) {
+  const p = pointerOf(options);
+  if (!p) return [];
+  const get = (f) => (typeof f === "function" ? f(d) : typeof f === "string" ? d[f] : undefined);
+  const label = (k, f) => (k === "x" || k === "y" ? options[k]?.label : options.color?.label) ?? (typeof f === "string" ? f : k);
+  const fmt = (v) => (typeof v === "number" && !Number.isInteger(v) ? String(+v.toPrecision(4)) : String(v));
+  const seen = new Set();
+  return Object.entries(p.ch).flatMap(([k, f]) => {
+    if (seen.has(f) || get(f) === undefined) return [];
+    seen.add(f);
+    return [[label(k, f).replace(/^[↑↓←→]\s*|\s*[↑↓←→]$/g, ""), fmt(get(f))]];
+  });
+}
+
+/** Show an HTML tooltip, with maths, over a live chart drawn with withPointer. */
+export function attachTip(el, options, box) {
+  const tip = Object.assign(document.createElement("div"), { className: "posuta-tip", hidden: true });
+  box.append(tip);
+  const html = (s) => (katex ? tex(s, katex) : esc(s));
+  el.addEventListener("input", () => {
+    const d = el.value;
+    if (!d) { tip.hidden = true; return; }
+    tip.innerHTML = tipRows(options, d).map(([l, v]) => `<div><b>${html(l)}</b> ${html(v)}</div>`).join("");
+    // The tip goes on the pointer dot, in whatever facet it is. The crosshair can fire input
+    // before the dot is redrawn, so place it a frame later.
+    requestAnimationFrame(() => {
+      const dot = el.querySelector(".posuta-pointer circle");
+      if (!dot || el.value !== d) return;
+      const r = dot.getBoundingClientRect(), b = box.getBoundingClientRect();
+      tip.style.left = `${r.left + r.width / 2 - b.left}px`;
+      tip.style.top = `${r.top + r.height / 2 - b.top}px`;
+      tip.hidden = false;
+    });
+  });
+}

package/src/preview.js

@@ -0,0 +1,60 @@
+// Print preview in the browser (astro dev, any page URL + ?print): the print CSS applies on
+// screen, the canvas is laid out at the paper size, checked for overflow like posuta pdf, and
+// scaled to fit the window. Overflowing blocks get a red outline; a banner lists them.
+// shortcut: media queries on width alone (no print/screen) still follow the window, not the paper.
+import { overflow } from "./overflow.js";
+
+const done = new WeakSet();
+
+/** Flip the media rules: print ones apply, screen ones don't, and colours are light, as in the PDF. */
+function flip(rules) {
+  for (const r of rules) {
+    if (r.media && r.type === CSSRule.MEDIA_RULE && !done.has(r)) {
+      done.add(r);
+      r.media.mediaText = r.media.mediaText
+        .replace(/\b(print|screen)\b/g, (m) => (m === "print" ? "all" : "print")) // "print" never matches on screen
+        .replace(/\(\s*prefers-color-scheme\s*:\s*dark\s*\)/g, "(max-width: 0px)")
+        .replace(/\(\s*prefers-color-scheme\s*:\s*light\s*\)/g, "(min-width: 0px)");
+    }
+    if (r.styleSheet) flip(safe(r.styleSheet)); // @import
+    if (r.cssRules) flip(r.cssRules); // @layer, @supports, nested @media
+  }
+}
+const safe = (sheet) => { try { return sheet.cssRules; } catch { return []; } }; // cross-origin sheets can't be read
+
+let banner;
+function apply() {
+  for (const s of document.styleSheets) flip(safe(s));
+  const canvas = document.querySelector(".posuta-canvas");
+  if (!canvas) return;
+  canvas.style.transform = "";
+  document.querySelectorAll("[data-posuta-overflow]").forEach((el) => el.removeAttribute("data-posuta-overflow"));
+  const problems = overflow(true);
+  const css = getComputedStyle(document.documentElement);
+  const size = `${css.getPropertyValue("--paper-w").trim()} × ${css.getPropertyValue("--paper-h").trim()}`;
+  banner ??= document.body.appendChild(Object.assign(document.createElement("div"), { className: "posuta-preview-banner" }));
+  banner.dataset.ok = String(!problems.length);
+  banner.textContent = problems.length ? `Does not fit on ${size}:\n${problems.join("\n")}` : `Print preview: fits on ${size}`;
+  fit();
+}
+
+function fit() {
+  const canvas = document.querySelector(".posuta-canvas");
+  if (!canvas) return;
+  const s = Math.min(innerWidth / canvas.offsetWidth, innerHeight / canvas.offsetHeight, 1);
+  canvas.style.transformOrigin = "0 0";
+  canvas.style.transform = `scale(${s})`;
+}
+
+export function preview() {
+  document.head.appendChild(document.createElement("style")).textContent =
+    "html,body{overflow:hidden}[data-posuta-overflow]{outline:4px solid #e00;outline-offset:-2px}" +
+    ".posuta-preview-banner{position:fixed;right:8px;bottom:8px;z-index:2147483647;max-width:40em;padding:6px 10px;" +
+    "font:13px/1.4 system-ui,sans-serif;white-space:pre-line;color:#fff;background:#c00;border-radius:4px}" +
+    ".posuta-preview-banner[data-ok=true]{background:#286}";
+  const run = () => document.fonts.ready.then(apply);
+  run();
+  addEventListener("load", run);
+  addEventListener("resize", fit);
+  import.meta.hot?.on("vite:afterUpdate", run);
+}

package/src/print.js

@@ -0,0 +1,48 @@
+// Paper sizes and the print scale. Plain JS so the layout (at build) and the CLI share it.
+
+/** Portrait sizes in mm. */
+export const PAPER = {
+  A0: [841, 1189], A1: [594, 841], A2: [420, 594], A3: [297, 420],
+  "24x36in": [609.6, 914.4], "36x48in": [914.4, 1219.2], "42x56in": [1066.8, 1422.4], "48x72in": [1219.2, 1828.8],
+};
+const UNIT = { mm: 1, cm: 10, in: 25.4 };
+const A0_AREA = 841 * 1189;
+
+function mm(v) {
+  const m = /^\s*([\d.]+)\s*(mm|cm|in)\s*$/.exec(String(v));
+  if (!m) throw new Error(`posuta: print size "${v}" needs a number and a unit (mm, cm or in)`);
+  return +m[1] * UNIT[m[2]];
+}
+
+/**
+ * Frontmatter `print` → paper in mm, the type scale, and `text`, the author's own factor on it.
+ * Accepts "A1", "A1 landscape", { size, orientation } or { width: "900mm", height: "36in" };
+ * the object forms take `scale` too, e.g. { size: "A0", scale: 0.8 } for smaller text.
+ */
+export function paper(print = "A0") {
+  const p = typeof print === "string" ? { size: print.split(/[\s:]+/)[0], orientation: print.split(/[\s:]+/)[1] } : print;
+  let w, h;
+  if (p.width != null || p.height != null) {
+    if (p.width == null || p.height == null) throw new Error("posuta: a custom print size needs both width and height");
+    [w, h] = [mm(p.width), mm(p.height)];
+  } else {
+    const size = PAPER[p.size ?? "A0"];
+    if (!size) throw new Error(`posuta: unknown print size "${p.size}"; use one of ${Object.keys(PAPER).join(", ")} or { width, height }`);
+    [w, h] = size;
+  }
+  if (p.orientation && !["portrait", "landscape"].includes(p.orientation)) {
+    throw new Error(`posuta: orientation must be portrait or landscape, not "${p.orientation}"`);
+  }
+  if ((p.orientation === "landscape" && w < h) || (p.orientation === "portrait" && w > h)) [w, h] = [h, w];
+  const text = p.scale ?? 1;
+  if (!(typeof text === "number" && text > 0)) throw new Error(`posuta: print scale must be a number above 0, not "${p.scale}"`);
+  // Type follows the paper's area, so a sheet reads the same in either orientation.
+  return { width: w, height: h, scale: Math.sqrt((w * h) / A0_AREA), text };
+}
+
+/** The CSS that sets the page box and the scale; the theme reads the custom properties. */
+export function printCss(print) {
+  const { width, height, scale, text } = paper(print);
+  return `@page{size:${width}mm ${height}mm;margin:0}` +
+    `:root{--paper-w:${width}mm;--paper-h:${height}mm;--print-scale:${scale.toFixed(4)};--print-text:${text}}`;
+}

package/src/qr.js

@@ -0,0 +1,5 @@
+// QR codes as inline SVG, for hand-built markup; <QR> wraps this.
+import QRCode from "qrcode";
+
+/** An SVG QR code for `url`, black on transparent, no quiet zone. */
+export const qrSvg = (url) => QRCode.toString(url, { type: "svg", margin: 0, errorCorrectionLevel: "M" });

package/src/references/Item.astro

@@ -0,0 +1,14 @@
+---
+// <References.Item entry={e} />: one cited entry, e from frontmatter.references
+// ({ key, n, text, doi }). Its id is the target of the [n] links in the text. With children, they
+// replace the default content (the formatted reference, URLs in it linked, and its DOI link).
+interface Props {
+  entry: { key: string; n: number; text: string; doi?: string };
+  as?: string; class?: string; [attr: string]: unknown;
+}
+import { urlParts } from "../remark-cite.js";
+const { entry, as: Tag = "li", class: cls, ...rest } = Astro.props;
+---
+<Tag id={`ref-${entry.key}`} class:list={["posuta-ref", cls]} {...rest}>{Astro.slots.has("default") ? <slot /> : <>
+  {urlParts(entry.text).map((p, i) => (i % 2 ? <a href={p}>{p}</a> : p))}{entry.doi && <> <a href={`https://doi.org/${entry.doi}`}>doi:{entry.doi}</a></>}
+</>}</Tag>

package/src/references/Root.astro

@@ -0,0 +1,7 @@
+---
+// <References.Root>: the reference list element. Put References.Item inside, one per entry of
+// frontmatter.references. `as` renders another element (default ol).
+interface Props { as?: string; class?: string; [attr: string]: unknown }
+const { as: Tag = "ol", class: cls, ...rest } = Astro.props;
+---
+<Tag class:list={["posuta-refs", cls]} {...rest}><slot /></Tag>

package/src/references/index.js

@@ -0,0 +1,8 @@
+// The reference list as parts. <References /> (handled by the citation plugin) covers the usual
+// case; to lay the list out yourself, map the entries cited on the page:
+//   <References.Root>{frontmatter.references.map((e) => <References.Item entry={e} />)}</References.Root>
+import Item from "./Item.astro";
+import Root from "./Root.astro";
+
+export default { Root, Item };
+export { Root, Item };

package/src/remark-auto-import.js

@@ -0,0 +1,79 @@
+// MDX without import lines: <Chart>, <Row>, <Section>… are imported for you.
+// Each capitalised JSX name a page uses (or the first part of a dotted one, <Figure.Caption>), but does not import or define itself, is looked up in the
+// poster's src/components/ (file name = component name), then in posuta's own components.
+// An explicit import always wins.
+import { existsSync, readdirSync } from "node:fs";
+import { join, parse } from "node:path";
+
+/** posuta's components, by name. */
+export const POSUTA = {
+  ...Object.fromEntries(["Canvas", "QR", "Row", "Col", "Grid", "Cell", "Chart", "Equation"].map((n) => [n, `@posuta/posuta/${n}.astro`])),
+  Figure: "@posuta/posuta/Figure", // with its parts: Figure.Root, Figure.Media, Figure.Caption
+  References: "@posuta/posuta/References", // parts only: <References /> itself is replaced by remark-cite
+};
+const EXT = [".astro", ".tsx", ".jsx"]; // first wins when two files share a name
+
+/** The poster's own components: { Name: absolute path }, top level of src/components only. */
+function local(dir) {
+  if (!existsSync(dir)) return {};
+  const found = {};
+  for (const f of readdirSync(dir)) {
+    const { name, ext } = parse(f);
+    if (!/^[A-Z]/.test(name) || !EXT.includes(ext)) continue;
+    if (!found[name] || EXT.indexOf(ext) < EXT.indexOf(parse(found[name]).ext)) found[name] = join(dir, f);
+  }
+  return found;
+}
+
+/** Names a page binds itself: imports and exported declarations. */
+function defined(tree) {
+  const names = new Set();
+  for (const node of tree.children) {
+    if (node.type !== "mdxjsEsm") continue;
+    for (const st of node.data?.estree?.body ?? []) {
+      if (st.type === "ImportDeclaration") st.specifiers.forEach((s) => names.add(s.local.name));
+      const d = st.type === "ExportNamedDeclaration" ? st.declaration : null;
+      if (d?.id) names.add(d.id.name);
+      d?.declarations?.forEach((v) => v.id?.name && names.add(v.id.name));
+    }
+  }
+  return names;
+}
+
+function used(node, names = new Set()) {
+  // <Figure.Caption> needs Figure.
+  const name = /^([A-Z]\w*)(\.\w+)*$/.exec(node.name ?? "")?.[1];
+  if ((node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") && name) names.add(name);
+  node.children?.forEach((c) => used(c, names));
+  return names;
+}
+
+const importNode = (name, source) => ({
+  type: "mdxjsEsm",
+  value: `import ${name} from ${JSON.stringify(source)};`,
+  data: {
+    estree: {
+      type: "Program", sourceType: "module",
+      body: [{
+        type: "ImportDeclaration",
+        specifiers: [{ type: "ImportDefaultSpecifier", local: { type: "Identifier", name } }],
+        source: { type: "Literal", value: source, raw: JSON.stringify(source) },
+      }],
+    },
+  },
+});
+
+/** @param {{ components: string }} options components: absolute path of the poster's src/components */
+export default function remarkAutoImport({ components }) {
+  return (tree) => {
+    const own = local(components); // read per page, so a new component is picked up on the next edit
+    const have = defined(tree);
+    const add = [];
+    for (const name of used(tree)) {
+      if (have.has(name)) continue;
+      const source = own[name] ?? POSUTA[name];
+      if (source) add.push(importNode(name, source));
+    }
+    tree.children.unshift(...add);
+  };
+}