@posuta/posuta 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alvaro Gaona
+
+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,6 @@
-# Temporary Holding Version
+# posuta
 
-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.
+Research posters for the web and for print, built with Astro. Write MDX, deploy a static page
+and export a vector PDF at any paper size. Start a poster with `pnpm create posuta`.
+
+Read the docs at https://github.com/alvgaona/posuta.

package/bin/posuta.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// posuta pdf: export a built poster (dist/) to a one-page vector PDF at the paper size, plus
+// og.png, the preview image for social sharing, and with --handout, handout.pdf: the same page
+// shrunk onto A4, for readers to take away.
+//
+//   posuta pdf [--dist dist] [--page /] [--out dist/poster.pdf] [--print "A1 landscape"] [--base /repo/] [--no-png] [--handout]
+//   posuta install            download the browser posuta pdf uses (Playwright's Chromium)
+//
+// Fails if content runs past the printed canvas, naming the innermost block that does: an element
+// led by a heading (h1–h4) or with a data-name attribute.
+import { spawnSync } from "node:child_process";
+import { createReadStream, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { mkdir } from "node:fs/promises";
+import { createServer } from "node:http";
+import { dirname, extname, join, resolve, sep } from "node:path";
+import { parseArgs } from "node:util";
+import { chromium } from "playwright";
+import { overflow } from "../src/overflow.js";
+import { printCss } from "../src/print.js";
+
+const usage = `usage: posuta pdf [--dist dist] [--page /] [--out <dist>/<page>/poster.pdf] [--print "A1 landscape"] [--base /] [--no-png] [--handout]
+       posuta install [--with-deps]`;
+const [cmd, ...rest] = process.argv.slice(2);
+if (cmd === "install") {
+  const cli = join(dirname(createRequire(import.meta.url).resolve("playwright/package.json")), "cli.js");
+  const r = spawnSync(process.execPath, [cli, "install", "--only-shell", "chromium", ...rest], { stdio: "inherit" });
+  process.exit(r.status ?? 1);
+}
+if (cmd !== "pdf") { console.error(usage); process.exit(cmd ? 1 : 0); }
+const { values: opt } = parseArgs({
+  args: rest,
+  allowNegative: true,
+  options: {
+    png: { type: "boolean", default: true },
+    handout: { type: "boolean", default: false },
+    dist: { type: "string", default: "dist" },
+    page: { type: "string", default: "/" },
+    out: { type: "string" },
+    print: { type: "string" },
+    base: { type: "string", default: process.env.BASE_PATH ?? "/" },
+  },
+});
+const dist = resolve(opt.dist);
+const pageDir = join(dist, opt.page); // og.png goes next to the page, where its og:image tag points
+const out = resolve(opt.out ?? join(pageDir, "poster.pdf"));
+const base = ("/" + opt.base + "/").replace(/\/+/g, "/");
+
+const TYPES = { ".html": "text/html", ".css": "text/css", ".js": "text/javascript", ".mjs": "text/javascript",
+  ".svg": "image/svg+xml", ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp",
+  ".woff2": "font/woff2", ".woff": "font/woff", ".json": "application/json" };
+
+// A static server for dist/, so absolute asset paths (/_astro/…) resolve as on the real host.
+const server = createServer((req, res) => {
+  let path = decodeURIComponent(new URL(req.url, "http://x").pathname);
+  if (path.startsWith(base)) path = "/" + path.slice(base.length);
+  let file = join(dist, path);
+  if (!file.startsWith(dist + sep) && file !== dist) { res.writeHead(403).end(); return; }
+  try {
+    if (statSync(file).isDirectory()) file = join(file, "index.html");
+    statSync(file);
+  } catch { res.writeHead(404).end(); return; }
+  res.writeHead(200, { "content-type": TYPES[extname(file)] ?? "application/octet-stream" });
+  createReadStream(file).pipe(res);
+});
+await new Promise((r) => server.listen(0, "127.0.0.1", r));
+const url = `http://127.0.0.1:${server.address().port}${base}${opt.page.replace(/^\//, "")}`;
+
+const browser = await chromium.launch();
+try {
+  const page = await browser.newPage();
+  await page.emulateMedia({ media: "print", colorScheme: "light" });
+  const res = await page.goto(url, { waitUntil: "networkidle" });
+  if (!res?.ok()) throw new Error(`could not open ${url} (${res?.status()}); did you run astro build?`);
+  if (opt.print) await page.addStyleTag({ content: `@media print{${printCss(opt.print)}}` });
+
+  // Lay the page out at the paper size before measuring.
+  const size = await page.evaluate(() => {
+    const s = getComputedStyle(document.documentElement);
+    return { w: s.getPropertyValue("--paper-w"), h: s.getPropertyValue("--paper-h") };
+  });
+  const mm = (v) => parseFloat(v);
+  if (!size.w) throw new Error(`${url} has no print size (--paper-w): wrap it in <Canvas>, or pass --print`);
+  const px = (v) => Math.round((mm(v) * 96) / 25.4);
+  await page.setViewportSize({ width: px(size.w), height: px(size.h) });
+  await page.evaluate(() => document.fonts.ready);
+
+  const found = await page.evaluate(overflow);
+  if (!found) throw new Error(`${url} is not a posuta page: wrap it in <Canvas>`);
+  if (found.length) {
+    throw new Error(`content does not fit on the ${size.w} × ${size.h} canvas:\n  ${found.join("\n  ")}\n` +
+      "Shorten it, change the column spans, or pick a larger print size.");
+  }
+
+  await mkdir(dirname(out), { recursive: true });
+  // tagged: readable by screen readers and text extraction; outline: the headings as bookmarks.
+  await page.pdf({ path: out, preferCSSPageSize: true, printBackground: true, tagged: true, outline: true });
+  console.log(`${out}: ${size.w} × ${size.h}`);
+
+  if (opt.handout) {
+    // shortcut: A4 only; add a paper option if a conference wants US letter.
+    const [w, h] = mm(size.w) <= mm(size.h) ? [210, 297] : [297, 210];
+    // Chromium shrinks the poster's page box (@page size) onto the sheet and centres it.
+    const handout = join(dirname(out), "handout.pdf");
+    await page.pdf({ path: handout, width: `${w}mm`, height: `${h}mm`, margin: { top: 0, right: 0, bottom: 0, left: 0 },
+      pageRanges: "1", printBackground: true, tagged: true, outline: true });
+    console.log(`${handout}: A4`);
+  }
+
+  if (opt.png) {
+    // The screen layout's first 1200 × 630 px: the size link previews use.
+    const png = join(pageDir, "og.png");
+    await page.emulateMedia({ media: "screen" });
+    await page.setViewportSize({ width: 1200, height: 630 });
+    await page.screenshot({ path: png });
+    console.log(png);
+  }
+} catch (e) {
+  console.error(`posuta pdf: ${e.message}`);
+  process.exitCode = 1;
+} finally {
+  await browser.close();
+  server.close();
+}

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "@posuta/posuta",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Research posters for the web and for print, built with Astro",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./print": "./src/print.js",
+    "./data": "./src/data.js",
+    "./plot": "./src/plot.js",
+    "./posuta.mplstyle": "./posuta.mplstyle",
+    "./Row.astro": "./src/Row.astro",
+    "./Col.astro": "./src/Col.astro",
+    "./Grid.astro": "./src/Grid.astro",
+    "./Cell.astro": "./src/Cell.astro",
+    "./Chart.astro": "./src/Chart.astro",
+    "./Figure.astro": "./src/Figure.astro",
+    "./Figure": "./src/figure/index.js",
+    "./Equation.astro": "./src/Equation.astro",
+    "./base.css": "./src/base.css",
+    "./Canvas.astro": "./src/Canvas.astro",
+    "./QR.astro": "./src/QR.astro",
+    "./qr": "./src/qr.js",
+    "./tex": "./src/tex.js",
+    "./cite": "./src/remark-cite.js",
+    "./md": "./src/md.js",
+    "./bibtex": "./src/bibtex.js",
+    "./References": "./src/references/index.js"
+  },
+  "peerDependencies": {
+    "astro": "^7.4.0"
+  },
+  "dependencies": {
+    "@astrojs/markdown-remark": "^7.3.6",
+    "@astrojs/mdx": "^8.1.3",
+    "@citation-js/core": "^0.9.0",
+    "@citation-js/plugin-bibtex": "^0.9.0",
+    "@citation-js/plugin-csl": "^0.9.0",
+    "@observablehq/plot": "^0.6.19",
+    "d3-dsv": "^3.0.2",
+    "katex": "^0.16.47",
+    "linkedom": "^0.18.15",
+    "playwright": "^1.65.0",
+    "qrcode": "^1.5.4",
+    "rehype-katex": "^7.0.1",
+    "remark-math": "^6.0.0"
+  },
+  "bin": {
+    "posuta": "./bin/posuta.mjs"
+  },
+  "imports": {
+    "#dom": {
+      "browser": "./src/dom-browser.js",
+      "default": "./src/dom-server.js"
+    }
+  },
+  "files": [
+    "src",
+    "bin",
+    "posuta.mplstyle"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alvgaona/posuta.git",
+    "directory": "packages/posuta"
+  },
+  "keywords": [
+    "astro-integration",
+    "withastro",
+    "astro",
+    "poster",
+    "research-poster",
+    "scientific-poster",
+    "academic",
+    "research",
+    "mdx",
+    "print",
+    "pdf",
+    "observable-plot",
+    "katex"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\""
+  }
 }

package/posuta.mplstyle

@@ -0,0 +1,24 @@
+# matplotlib style that matches posuta's default theme.
+#   import matplotlib.pyplot as plt; plt.style.use("node_modules/@posuta/posuta/posuta.mplstyle")
+#   plt.savefig("figures/plot.svg")   # then <Figure src={...} /> in the poster
+svg.fonttype: none          # keep text as text, so it uses the poster's fonts
+font.family: IBM Plex Sans, sans-serif
+font.size: 11
+text.color: 282a30
+axes.labelcolor: 282a30
+axes.edgecolor: 6f6e77
+axes.linewidth: 0.8
+axes.spines.top: False
+axes.spines.right: False
+axes.grid: True
+grid.color: e9e8ea
+grid.linewidth: 0.8
+axes.prop_cycle: cycler('color', ['1348dc', 'c2410c', '0f766e', '7c3aed', 'a16207', '6f6e77'])
+xtick.color: 6f6e77
+ytick.color: 6f6e77
+legend.frameon: False
+lines.linewidth: 1.8
+figure.facecolor: none
+axes.facecolor: none
+savefig.facecolor: none
+savefig.bbox: tight

package/src/Canvas.astro

@@ -0,0 +1,62 @@
+---
+// The page every poster is drawn on: <html>, <head> and one canvas element, nothing visual.
+//
+//   <Canvas title="…" description="…" print="A1 landscape" theme="dark">
+//     <link slot="head" rel="icon" href="…" />
+//     …your poster…
+//   </Canvas>
+//
+// It sets the print page and type scale (base.css + `print`), link-preview tags, and theme
+// tokens or a fixed colour scheme. posuta pdf measures the canvas (.posuta-canvas) for overflow;
+// in astro dev, ?print on the URL previews the printed page and the same check.
+import "./base.css";
+import { printCss } from "./print.js";
+
+type Print = string | { size?: string; orientation?: "portrait" | "landscape"; width?: string; height?: string; scale?: number };
+interface Props {
+  title: string;
+  /** For search results and link previews. */
+  description?: string;
+  /** Paper: "A0", "A1 landscape", { width: "900mm", height: "36in" }… Default A0 portrait.
+      `scale` multiplies the printed type size: { size: "A0", scale: 0.8 }. */
+  print?: Print;
+  /** "light" or "dark" to fix the colour scheme, or tokens such as { accent: "#0a7" }. */
+  theme?: "light" | "dark" | Record<string, string>;
+  lang?: string;
+  class?: string;
+  [attr: string]: unknown;
+}
+const { title, description, print, theme, lang = "en", class: cls, ...rest } = Astro.props;
+const pageUrl = Astro.site ? new URL(Astro.url.pathname, Astro.site).href : undefined;
+const scheme = typeof theme === "string" ? theme : undefined;
+// Declared first, so it holds whatever order the stylesheets load in. theme/base/components/
+// utilities are Tailwind v4's layers; they are empty without it.
+const LAYERS = "@layer theme, base, posuta.base, posuta.theme, components, utilities;";
+const tokens = theme && typeof theme === "object"
+  ? `:root{${Object.entries(theme).map(([k, v]) => `--${k.replace(/^--/, "")}:${v}`).join(";")}}` : "";
+---
+<!doctype html>
+<html lang={lang} data-theme={scheme}>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{title}</title>
+  {description && <meta name="description" content={description}>}
+  <meta property="og:title" content={title}>
+  {description && <meta property="og:description" content={description}>}
+  {pageUrl && <meta property="og:url" content={pageUrl}>}
+  {pageUrl && <meta property="og:image" content={new URL("og.png", pageUrl).href}>}
+  <meta name="twitter:card" content="summary_large_image">
+  <!-- Layer order: resets (Tailwind's base), then posuta, then utilities. Unlayered CSS beats all. -->
+  <style is:inline set:html={`${LAYERS}@media print{${printCss(print)}}${tokens}`} />
+  <slot name="head" />
+</head>
+<body>
+  <div class:list={["posuta-canvas", cls]} {...rest}><slot /></div>
+  {import.meta.env.DEV && <script>
+    // astro dev: add ?print to the URL to see the page as it will print, overflow marked.
+    // The DEV check here too, so the build drops preview.js instead of emitting it unused.
+    if (import.meta.env.DEV && new URLSearchParams(location.search).has("print")) import("./preview.js").then((m) => m.preview());
+  </script>}
+</body>
+</html>

package/src/Cell.astro

@@ -0,0 +1,6 @@
+---
+// A cell in <Grid>. `span`: columns it covers (default 1); `rows`: rows it covers (default 1).
+interface Props { span?: number; rows?: number; class?: string; [attr: string]: unknown }
+const { span = 1, rows = 1, class: cls, style, ...rest } = Astro.props;
+---
+<div class:list={["posuta-cell", cls]} style={[`--span:${span};--rows:${rows}`, style].filter(Boolean).join(";")} {...rest}><slot /></div>

package/src/Chart.astro

@@ -0,0 +1,65 @@
+---
+// An Observable Plot chart, drawn to SVG at build time (prints as vectors, works without JS).
+//
+//   <Chart data="step.csv" plot="step" alt="…" />          charts/step.js: export default (d, Plot, state) => options
+//   <Chart … interactive />                                   tooltip and crosshair in the browser
+//   <Chart … slider={{ name: "t", min: 0, max: 5, step: 0.1, value: 1, label: "Time" }} />
+//
+// `plot` may also be an inline function, (d, Plot) => options, for a static chart.
+// The slider's `value` is the state the chart prints in: the build-time drawing is what prints,
+// whatever the slider or a script shows on screen.
+import * as Plot from "@observablehq/plot";
+import { load } from "./data.js";
+import { renderPlot } from "./plot.js";
+
+type ChartFn = (data: any[], plot: typeof Plot, state: Record<string, number>) => Plot.PlotOptions;
+interface Slider { name: string; min: number; max: number; step?: number; value: number; label?: string }
+interface Props {
+  /** A file under data/, or the rows themselves. */
+  data?: string | object[];
+  /** A chart file name in charts/ (without .js), or an inline function for a static chart. */
+  plot: string | ChartFn;
+  /** What the chart shows, for screen readers. Required. */
+  alt: string;
+  caption?: string;
+  /** Thin series longer than this (rows). */
+  max?: number;
+  /** Tooltip and crosshair in the browser. */
+  interactive?: boolean;
+  /** A range input that feeds `state[name]` to the chart function. */
+  slider?: Slider;
+  class?: string;
+  /** Any other attribute goes on the <figure>. */
+  [attr: string]: unknown;
+}
+const { data = [], plot, alt, caption, max, interactive = false, slider, class: cls, ...rest } = Astro.props;
+if (!alt) throw new Error("posuta <Chart>: `alt` is required (what the chart shows, for screen readers)");
+const live = interactive || !!slider;
+if (live && typeof plot !== "string") {
+  throw new Error('posuta <Chart>: an interactive chart or one with a slider needs its chart in a file: plot="name" for charts/name.js');
+}
+let chart: ChartFn;
+if (typeof plot === "string") {
+  const files = import.meta.glob<{ default: ChartFn }>("/charts/*.js");
+  const file = files[`/charts/${plot}.js`];
+  if (!file) throw new Error(`posuta <Chart>: no charts/${plot}.js (found: ${Object.keys(files).join(", ") || "none"})`);
+  chart = (await file()).default;
+} else chart = plot;
+const rows = typeof data === "string" ? await load(data, { max }) : data;
+const state = slider ? { [slider.name]: slider.value } : {};
+const svg = renderPlot({ ariaLabel: alt, ...chart(rows, Plot, state) });
+---
+<figure class:list={["posuta-figure posuta-chart", cls]} {...rest} data-chart={live ? plot : undefined} data-alt={live ? alt : undefined}
+  data-interactive={interactive || undefined} data-slider={slider && JSON.stringify(slider)}>
+  {slider && (
+    <label class="posuta-slider" data-print="hide" hidden>
+      <span>{slider.label ?? slider.name}</span>
+      <input type="range" min={slider.min} max={slider.max} step={slider.step ?? 1} value={slider.value} />
+      <output>{slider.value}</output>
+    </label>
+  )}
+  <div class="posuta-plot"><Fragment set:html={svg} /></div>
+  {live && <script type="application/json" set:html={JSON.stringify(rows)} />}
+  {caption && <figcaption>{caption}</figcaption>}
+</figure>
+{live && <script>import "./chart-client.js";</script>}

package/src/Col.astro

@@ -0,0 +1,6 @@
+---
+// A column inside <Row>. `span` is its width relative to its siblings (default 1).
+interface Props { span?: number; class?: string; [attr: string]: unknown }
+const { span = 1, class: cls, style, ...rest } = Astro.props;
+---
+<div class:list={["posuta-col", cls]} style={[`--span:${span}`, style].filter(Boolean).join(";")} {...rest}><slot /></div>

package/src/Equation.astro

@@ -0,0 +1,9 @@
+---
+// A display equation, rendered with KaTeX at build time: <Equation tex="E = mc^2" n={1} />
+// (Inline math is plain $…$ in the text.)
+import katex from "katex";
+interface Props { tex: string; n?: number | string; class?: string; [attr: string]: unknown }
+const { tex, n, class: cls, ...rest } = Astro.props;
+const html = katex.renderToString(tex, { displayMode: true, throwOnError: true, strict: "error" });
+---
+<div class:list={["posuta-eq", cls]} {...rest}><Fragment set:html={html} />{n != null && <span class="posuta-eq-n">({n})</span>}</div>

package/src/Figure.astro

@@ -0,0 +1,14 @@
+---
+// An image, an SVG or a video, with a caption: <Figure src={plot} alt="…" caption="…" />.
+// Built from Figure.Root, Figure.Media and Figure.Caption; use those to arrange it your way.
+// `poster` (a still frame) is required for a video. Other attributes go on the <figure>.
+import Caption from "./figure/Caption.astro";
+import Media from "./figure/Media.astro";
+import Root from "./figure/Root.astro";
+interface Props { src: any; alt: string; caption?: string; poster?: any; class?: string; [attr: string]: unknown }
+const { src, alt, caption, poster, ...rest } = Astro.props;
+---
+<Root {...rest}>
+  <Media src={src} alt={alt} poster={poster} />
+  {caption && <Caption>{caption}</Caption>}
+</Root>

package/src/Grid.astro

@@ -0,0 +1,8 @@
+---
+// A grid of cells: <Grid cols={3}><Cell>…</Cell><Cell span={2} rows={2}>…</Cell></Grid>.
+// Unlike Row/Col, cells line up across rows and can span rows. On screen it narrows to two
+// columns, then one; in print it keeps the grid as written.
+interface Props { cols?: number; class?: string; [attr: string]: unknown }
+const { cols = 3, class: cls, style, ...rest } = Astro.props;
+---
+<div class:list={["posuta-grid", cls]} style={[`--cols:${cols}`, style].filter(Boolean).join(";")} {...rest}><slot /></div>

package/src/QR.astro

@@ -0,0 +1,13 @@
+---
+// A QR code as inline SVG: <QR /> points at this page when `site` is set, or <QR url="…" />.
+// Renders nothing when there is no URL. Hook: svg.posuta-qr. Unstyled: size it with CSS.
+import { qrSvg } from "./qr.js";
+interface Props { url?: string; class?: string; [attr: string]: unknown }
+const { url, class: cls, ...rest } = Astro.props;
+const target = url ?? (Astro.site ? new URL(Astro.url.pathname, Astro.site).href : undefined);
+const attrs = Object.entries(rest).map(([k, v]) => ` ${k}="${String(v).replace(/"/g, "&quot;")}"`).join("");
+const svg = target
+  ? (await qrSvg(target)).replace("<svg ", `<svg class="${["posuta-qr", cls].filter(Boolean).join(" ")}" role="img" aria-label="QR code: ${target}"${attrs} `)
+  : "";
+---
+<Fragment set:html={svg} />

package/src/Row.astro

@@ -0,0 +1,7 @@
+---
+// A row of columns: <Row><Col>…</Col><Col span={2}>…</Col></Row>.
+// On screen it reflows by width (three → two → one); in print it keeps the columns as written.
+// Any other attribute (class, id, style, data-*) goes on the element.
+const { class: cls, ...rest } = Astro.props;
+---
+<div class:list={["posuta-row", cls]} {...rest}><slot /></div>

package/src/base.css

@@ -0,0 +1,62 @@
+/* posuta base: only what the components need to work. No colours, fonts, borders or spacing;
+   the look is yours (the template's is in its src/styles/theme.css). Everything is in @layer posuta.base, so any CSS you
+   write outside a layer wins without !important. */
+@layer posuta.base, posuta.theme;
+@import "katex/dist/katex.min.css" layer(posuta.base);
+
+@layer posuta.base {
+/* The print canvas: one page at the paper size (--paper-w/-h come from <Canvas>'s print CSS). */
+.posuta-canvas { box-sizing: border-box; }
+@media print {
+  /* The type scale: body text is 24 pt at A0, follows the paper's area, never below 12 pt, then
+     times the author's print scale (--print-text). Size everything in rem and the whole poster
+     scales with the paper. */
+  :root { font-size: calc(max(calc(24pt * var(--print-scale, 1)), 12pt) * var(--print-text, 1)); -webkit-print-color-adjust: exact; print-color-adjust: exact; }
+  body { margin: 0; }
+  .posuta-canvas { width: var(--paper-w); height: var(--paper-h); max-width: none; overflow: hidden; }
+}
+
+/* Rows and columns: weights from --span; on screen they wrap three → two → one, in print they
+   keep the columns as written. --posuta-gap sets the space between columns. */
+.posuta-row { display: flex; gap: 0 var(--posuta-gap, 2rem); align-items: flex-start; }
+.posuta-col { flex: var(--span, 1) 1 0; min-width: 0; }
+@media screen and (max-width: 1100px) {
+  .posuta-row { flex-wrap: wrap; }
+  .posuta-col { flex: 1 1 calc(50% - var(--posuta-gap, 2rem) / 2); }
+}
+@media screen and (max-width: 700px) { .posuta-col { flex-basis: 100%; } }
+
+/* Grids: --cols columns; a cell covers --span columns and --rows rows. On screen they narrow to
+   two columns, then one, like rows; in print they keep the grid as written. */
+.posuta-grid { display: grid; grid-template-columns: repeat(var(--cols, 3), minmax(0, 1fr)); gap: 0 var(--posuta-gap, 2rem); align-items: start; }
+.posuta-cell { grid-column: span var(--span, 1); grid-row: span var(--rows, 1); min-width: 0; }
+@media screen and (max-width: 1100px) {
+  .posuta-grid { grid-template-columns: repeat(min(var(--cols, 3), 2), minmax(0, 1fr)); }
+  .posuta-cell { grid-column: span min(var(--span, 1), 2); grid-row: auto; }
+}
+@media screen and (max-width: 700px) {
+  .posuta-grid { grid-template-columns: minmax(0, 1fr); }
+  .posuta-cell { grid-column: auto; }
+}
+
+/* Screen-only and print-only content. */
+@media screen { [data-print="only"] { display: none !important; } }
+@media print { [data-print="hide"] { display: none !important; } }
+
+/* Figures and charts scale to their container; KaTeX's own SVGs (\sqrt) keep their size. */
+.posuta-media, .posuta-figure svg[viewBox]:not(.katex svg), .posuta-plot svg[viewBox]:not(.katex svg) {
+  display: block; width: 100%; height: auto; max-width: 100%;
+}
+/* Plot ships an unlayered <style> forcing system-ui; a layered !important is what beats it. */
+.posuta-figure [class*="plot-"] { font-family: inherit !important; }
+
+/* Live charts: the tooltip sits above the point and never takes the pointer. */
+.posuta-plot { position: relative; }
+.posuta-tip { position: absolute; z-index: 1; pointer-events: none; white-space: nowrap; transform: translate(-50%, calc(-100% - 12px)); }
+.posuta-tip[hidden] { display: none; }
+
+/* KaTeX inside SVG text (charts) and display equations with a number. */
+.posuta-tex { display: inline-block; width: max-content; white-space: nowrap; line-height: 1; }
+.posuta-eq { display: flex; align-items: center; overflow-x: auto; overflow-y: hidden; }
+.posuta-eq .katex-display { flex: 1; }
+}

package/src/bibtex.js

@@ -0,0 +1,24 @@
+// A BibTeX entry for the poster itself, so the web page can be cited.
+//   bibtex({ title, authors: ["Ada Lovelace", "Babbage, Charles"], event: "ICRA 2026", year: 2026, doi, url })
+
+const esc = (s) => String(s).replace(/[&%#_$]/g, "\\$&");
+const last = (name) => (name.includes(",") ? name.split(",")[0] : name.trim().split(/\s+/).at(-1));
+const ascii = (s) => s.normalize("NFD").replace(/[^A-Za-z0-9]/g, "").toLowerCase();
+
+/**
+ * @param {{ title: string, authors: string[], year: number | string, event?: string, doi?: string, url?: string, key?: string }} c
+ *   authors as "First Last" or "Last, First"; event: where it was presented
+ */
+export function bibtex({ title, authors, year, event, doi, url, key }) {
+  if (!title || !authors?.length || !year) throw new Error("posuta bibtex: needs title, authors and year");
+  key ??= ascii(last(authors[0])) + year + ascii(title.split(/\s+/).find((w) => w.length > 3) ?? "");
+  const fields = [
+    ["author", authors.map(esc).join(" and ")],
+    ["title", `{${esc(title)}}`], // double braces keep its capitals
+    ["howpublished", event ? `Poster, ${esc(event)}` : "Poster"],
+    ["year", year],
+    doi && ["doi", doi],
+    url && ["url", url],
+  ].filter(Boolean);
+  return `@misc{${key},\n${fields.map(([k, v]) => `  ${k.padEnd(12)} = {${v}}`).join(",\n")}\n}`;
+}

package/src/chart-client.js

@@ -0,0 +1,46 @@
+// Live charts: redraw each <Chart plot="name" interactive|slider> in the browser, from the same
+// chart file in charts/ and the rows embedded at build time. Loaded only on pages that have one.
+const charts = import.meta.glob("/charts/*.js");
+
+async function hydrate(fig) {
+  const load = charts[`/charts/${fig.dataset.chart}.js`];
+  if (!load) throw new Error(`posuta: charts/${fig.dataset.chart}.js is missing from the build`);
+  // Plot downloads only once a live chart scrolls into view.
+  const [{ Plot, plotLive, withPointer, attachTip }, { default: chart }] = await Promise.all([import("./plot.js"), load()]);
+  const rows = JSON.parse(fig.querySelector("script[type='application/json']").textContent);
+  const slider = fig.dataset.slider && JSON.parse(fig.dataset.slider);
+  const input = fig.querySelector(".posuta-slider input");
+  const out = fig.querySelector(".posuta-slider output");
+  const box = fig.querySelector(".posuta-plot");
+  // The build-time drawing stays as the print frame, whatever the slider or a script shows on screen.
+  const still = box.cloneNode(true);
+  still.dataset.print = "only";
+  box.dataset.print = "hide";
+  box.after(still);
+  let latest = 0;
+  const render = async () => {
+    const n = ++latest;
+    const state = slider ? { [slider.name]: +input.value } : {};
+    if (out) out.value = input.value;
+    let options = { ariaLabel: fig.dataset.alt, ...chart(rows, Plot, state) };
+    if (fig.hasAttribute("data-interactive")) options = withPointer(options);
+    const el = await plotLive(options);
+    if (n !== latest) return; // a newer slider position finished first
+    box.replaceChildren(el);
+    if (fig.hasAttribute("data-interactive")) attachTip(el, options, box);
+  };
+  if (input) {
+    input.closest(".posuta-slider").hidden = false;
+    input.addEventListener("input", render);
+  }
+  await render();
+}
+
+// Watch the plot box, not the figure: a figure with display: contents has no box to intersect.
+const seen = new IntersectionObserver((entries) => {
+  for (const e of entries) if (e.isIntersecting) {
+    seen.unobserve(e.target);
+    hydrate(e.target.closest(".posuta-chart")).catch((err) => console.error(err));
+  }
+});
+document.querySelectorAll(".posuta-chart[data-chart] > .posuta-plot").forEach((b) => seen.observe(b));

package/src/data.js

@@ -0,0 +1,28 @@
+// Data files for charts: CSV or JSON from the project's data/ folder, read at build.
+import { readFile } from "node:fs/promises";
+import { extname, isAbsolute, join } from "node:path";
+import { autoType, csvParse } from "d3-dsv";
+
+/**
+ * Load `data/<file>` as an array of rows. Series longer than `max` rows are thinned.
+ * @param {string} file path under data/ (or absolute)
+ * @param {{ max?: number }} [opts]
+ */
+export async function load(file, { max = 2000 } = {}) {
+  const root = globalThis.__posutaRoot ?? process.cwd(); // set by the integration
+  const path = isAbsolute(file) ? file : join(root, "data", file);
+  const ext = extname(path).toLowerCase();
+  let rows;
+  if (ext === ".csv") rows = csvParse(await readFile(path, "utf8"), autoType);
+  else if (ext === ".json") rows = JSON.parse(await readFile(path, "utf8"));
+  else throw new Error(`posuta: cannot load ${file}; use .csv or .json`);
+  if (!Array.isArray(rows)) throw new Error(`posuta: ${file} must hold an array of rows`);
+  return downsample(rows, max);
+}
+
+// shortcut: keeps every k-th row (plus the last), which can drop narrow peaks; switch to LTTB if a plot needs them.
+export function downsample(rows, max) {
+  if (!max || rows.length <= max) return rows;
+  const k = (rows.length - 1) / (max - 1);
+  return Array.from({ length: max }, (_, i) => rows[Math.round(i * k)]);
+}

package/src/dom-browser.js

@@ -0,0 +1,4 @@
+/** In the browser Plot draws into the page's own document. */
+export const dom = () => document;
+/** KaTeX loads on demand in the browser (see plotLive), so pages without chart math skip it. */
+export const katex = null;