sci2-ts 0.0.0-stage → 0.2.2

package/tools/res.js

@@ -0,0 +1,48 @@
+/**
+ * Resource CLI.
+ *   pnpm res list [type]              JSONL of every resource (optionally one type)
+ *   pnpm res extract <type> <number>  write decompressed bytes to out/<type>.<number>.bin
+ *   pnpm res disasm <script>          print a script's disassembly
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { ResourceManager, ResourceType, ScriptWorld, disassemble, formatDisassembly, resourceTypeName } from "../packages/sci/src/index.js";
+import { nodeFiles } from "./node-files.js";
+const typeByName = (name) => {
+    const t = Object.entries(ResourceType).find(([k]) => k.toLowerCase() === name.toLowerCase());
+    if (!t)
+        throw new Error(`Unknown resource type "${name}"`);
+    return t[1];
+};
+process.stdout.on("error", (e) => e.code === "EPIPE" && process.exit(0));
+const [cmd, ...args] = process.argv.slice(2);
+const rm = await ResourceManager.open(nodeFiles(process.env.SCI_GAME ?? "original"));
+switch (cmd) {
+    case "list": {
+        const type = args[0] ? typeByName(args[0]) : undefined;
+        for (const r of rm.list(type)) {
+            console.log(JSON.stringify({ type: resourceTypeName[r.type], number: r.number, source: r.source }));
+        }
+        break;
+    }
+    case "extract": {
+        const [typeName, num] = args;
+        if (!typeName || !num)
+            throw new Error("usage: extract <type> <number>");
+        const res = await rm.load({ type: typeByName(typeName), number: Number(num) });
+        await mkdir("out", { recursive: true });
+        const path = `out/${typeName.toLowerCase()}.${num}.bin`;
+        await writeFile(path, res.data);
+        console.log(JSON.stringify({ path, bytes: res.data.length }));
+        break;
+    }
+    case "disasm": {
+        const world = await ScriptWorld.open(rm);
+        await world.loadAllClasses();
+        const script = await world.script(Number(args[0]));
+        console.log(formatDisassembly(script, disassemble(script, world.context())));
+        break;
+    }
+    default:
+        console.error("usage: pnpm res <list [type] | extract <type> <number> | disasm <script>>");
+        process.exit(1);
+}

package/tools/res.ts

@@ -0,0 +1,50 @@
+/**
+ * Resource CLI.
+ *   pnpm res list [type]              JSONL of every resource (optionally one type)
+ *   pnpm res extract <type> <number>  write decompressed bytes to out/<type>.<number>.bin
+ *   pnpm res disasm <script>          print a script's disassembly
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { ResourceManager, ResourceType, ScriptWorld, disassemble, formatDisassembly, resourceTypeName } from "../packages/sci/src/index.ts";
+import { nodeFiles } from "./node-files.ts";
+
+const typeByName = (name: string): ResourceType => {
+  const t = Object.entries(ResourceType).find(([k]) => k.toLowerCase() === name.toLowerCase());
+  if (!t) throw new Error(`Unknown resource type "${name}"`);
+  return t[1];
+};
+
+process.stdout.on("error", (e: NodeJS.ErrnoException) => e.code === "EPIPE" && process.exit(0));
+
+const [cmd, ...args] = process.argv.slice(2);
+const rm = await ResourceManager.open(nodeFiles(process.env.SCI_GAME ?? "original"));
+
+switch (cmd) {
+  case "list": {
+    const type = args[0] ? typeByName(args[0]) : undefined;
+    for (const r of rm.list(type)) {
+      console.log(JSON.stringify({ type: resourceTypeName[r.type], number: r.number, source: r.source }));
+    }
+    break;
+  }
+  case "extract": {
+    const [typeName, num] = args;
+    if (!typeName || !num) throw new Error("usage: extract <type> <number>");
+    const res = await rm.load({ type: typeByName(typeName), number: Number(num) });
+    await mkdir("out", { recursive: true });
+    const path = `out/${typeName.toLowerCase()}.${num}.bin`;
+    await writeFile(path, res.data);
+    console.log(JSON.stringify({ path, bytes: res.data.length }));
+    break;
+  }
+  case "disasm": {
+    const world = await ScriptWorld.open(rm);
+    await world.loadAllClasses();
+    const script = await world.script(Number(args[0]));
+    console.log(formatDisassembly(script, disassemble(script, world.context())));
+    break;
+  }
+  default:
+    console.error("usage: pnpm res <list [type] | extract <type> <number> | disasm <script>>");
+    process.exit(1);
+}

package/tools/scenario.d.ts

@@ -0,0 +1 @@
+export {};

package/tools/scenario.js

@@ -0,0 +1,74 @@
+/**
+ * Scripted headless session: boots, then replays clicks at given frames.
+ *   pnpm tsx tools/scenario.ts <frames> [frame:x,y ...] [--png-every N] [--out dir]
+ *   frame:type=Text   types Text followed by Enter at that frame
+ *   frame:move=x,y    moves the mouse without clicking (e.g. to open the icon bar)
+ * Example: pnpm tsx tools/scenario.ts 2400 1401:160,60 1800:100,110 2000:type=Hero
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { EventType, ResourceManager, Vm, allKernels, formatValue, graphics, input } from "../packages/sci/src/index.js";
+import { nodeFiles } from "./node-files.js";
+import { framePng } from "./png.js";
+const argv = process.argv.slice(2);
+const total = Number(argv[0]);
+const opt = (name) => (argv.includes(name) ? argv[argv.indexOf(name) + 1] : undefined);
+const pngEvery = Number(opt("--png-every") ?? 0);
+const outDir = opt("--out") ?? "out/scenario";
+const clicks = new Map(argv.filter((a) => /^\d+:\d+,\d+$/.test(a)).map((a) => {
+    const [f, xy] = a.split(":");
+    const [x, y] = xy.split(",").map(Number);
+    return [Number(f), { x: x, y: y }];
+}));
+const typing = new Map(argv.filter((a) => /^\d+:type=/.test(a)).map((a) => {
+    const i = a.indexOf(":type=");
+    return [Number(a.slice(0, i)), a.slice(i + 6)];
+}));
+const moves = new Map(argv.filter((a) => /^\d+:move=\d+,\d+$/.test(a)).map((a) => {
+    const [f, xy] = a.split(":move=");
+    const [x, y] = xy.split(",").map(Number);
+    return [Number(f), { x: x, y: y }];
+}));
+const rm = await ResourceManager.open(nodeFiles("original"));
+await rm.preload();
+const vm = new Vm(rm);
+vm.registerKernels(allKernels);
+const g = graphics(vm);
+vm.clock = () => (g.frames * 1000) / 60;
+if (pngEvery)
+    mkdirSync(outDir, { recursive: true });
+g.onFrame = (f) => {
+    if (pngEvery && (g.frames % pngEvery === 0 || clicks.has(g.frames - 1) || typing.has(g.frames - 1)))
+        writeFileSync(`${outDir}/${String(g.frames).padStart(5, "0")}.png`, framePng(f));
+};
+const trace = argv.includes("--trace") ? (opt("--trace-from") ? Number(opt("--trace-from")) : 0) : Infinity;
+vm.onKernelCall = (name, args, r) => {
+    if (g.frames >= trace && !["GetEvent", "FrameOut", "GetTime", "ListEachElementDo", "EmptyList", "FirstNode", "NextNode", "NodeValue", "Clone", "DisposeClone", "GameIsRestarting"].includes(name))
+        console.log(`  [${g.frames}] ${name}(${args.map((a) => vm.memory.object(a)?.name ?? formatValue(a)).join(", ")}) → ${formatValue(r)}`);
+};
+vm.start(vm.exportAddress(0, 0), "play");
+const inp = input(vm);
+try {
+    while (g.frames < total && vm.running) {
+        const move = moves.get(g.frames);
+        if (move)
+            (inp.x = move.x), (inp.y = move.y);
+        const click = clicks.get(g.frames);
+        if (click) {
+            inp.x = click.x;
+            inp.y = click.y;
+            inp.push({ type: EventType.MouseDown, message: 0 });
+            inp.push({ type: EventType.MouseUp, message: 0 });
+        }
+        const text = typing.get(g.frames);
+        if (text !== undefined) {
+            for (const ch of text)
+                inp.push({ type: EventType.KeyDown, message: ch.charCodeAt(0) });
+            inp.push({ type: EventType.KeyDown, message: 13 });
+        }
+        vm.run();
+    }
+}
+catch (e) {
+    console.log(`ERROR at frame ${g.frames}: ${e.message}\n${vm.backtrace().map((l) => `  at ${l}`).join("\n")}`);
+}
+console.log(`frames ${g.frames}, missing kernels:`, Object.fromEntries(vm.missingKernels));

package/tools/scenario.ts

@@ -0,0 +1,80 @@
+/**
+ * Scripted headless session: boots, then replays clicks at given frames.
+ *   pnpm tsx tools/scenario.ts <frames> [frame:x,y ...] [--png-every N] [--out dir]
+ *   frame:type=Text   types Text followed by Enter at that frame
+ *   frame:move=x,y    moves the mouse without clicking (e.g. to open the icon bar)
+ * Example: pnpm tsx tools/scenario.ts 2400 1401:160,60 1800:100,110 2000:type=Hero
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { EventType, ResourceManager, Vm, allKernels, formatValue, graphics, input } from "../packages/sci/src/index.ts";
+import { nodeFiles } from "./node-files.ts";
+import { framePng } from "./png.ts";
+
+const argv = process.argv.slice(2);
+const total = Number(argv[0]);
+const opt = (name: string) => (argv.includes(name) ? argv[argv.indexOf(name) + 1] : undefined);
+const pngEvery = Number(opt("--png-every") ?? 0);
+const outDir = opt("--out") ?? "out/scenario";
+const clicks = new Map(
+  argv.filter((a) => /^\d+:\d+,\d+$/.test(a)).map((a) => {
+    const [f, xy] = a.split(":");
+    const [x, y] = xy!.split(",").map(Number);
+    return [Number(f), { x: x!, y: y! }] as const;
+  }),
+);
+
+const typing = new Map(
+  argv.filter((a) => /^\d+:type=/.test(a)).map((a) => {
+    const i = a.indexOf(":type=");
+    return [Number(a.slice(0, i)), a.slice(i + 6)] as const;
+  }),
+);
+
+const moves = new Map(
+  argv.filter((a) => /^\d+:move=\d+,\d+$/.test(a)).map((a) => {
+    const [f, xy] = a.split(":move=");
+    const [x, y] = xy!.split(",").map(Number);
+    return [Number(f), { x: x!, y: y! }] as const;
+  }),
+);
+
+const rm = await ResourceManager.open(nodeFiles("original"));
+await rm.preload();
+const vm = new Vm(rm);
+vm.registerKernels(allKernels);
+const g = graphics(vm);
+vm.clock = () => (g.frames * 1000) / 60;
+if (pngEvery) mkdirSync(outDir, { recursive: true });
+g.onFrame = (f) => {
+  if (pngEvery && (g.frames % pngEvery === 0 || clicks.has(g.frames - 1) || typing.has(g.frames - 1))) writeFileSync(`${outDir}/${String(g.frames).padStart(5, "0")}.png`, framePng(f));
+};
+const trace = argv.includes("--trace") ? (opt("--trace-from") ? Number(opt("--trace-from")) : 0) : Infinity;
+vm.onKernelCall = (name, args, r) => {
+  if (g.frames >= trace && !["GetEvent", "FrameOut", "GetTime", "ListEachElementDo", "EmptyList", "FirstNode", "NextNode", "NodeValue", "Clone", "DisposeClone", "GameIsRestarting"].includes(name))
+    console.log(`  [${g.frames}] ${name}(${args.map((a) => vm.memory.object(a)?.name ?? formatValue(a)).join(", ")}) → ${formatValue(r)}`);
+};
+
+vm.start(vm.exportAddress(0, 0), "play");
+const inp = input(vm);
+try {
+  while (g.frames < total && vm.running) {
+    const move = moves.get(g.frames);
+    if (move) (inp.x = move.x), (inp.y = move.y);
+    const click = clicks.get(g.frames);
+    if (click) {
+      inp.x = click.x;
+      inp.y = click.y;
+      inp.push({ type: EventType.MouseDown, message: 0 });
+      inp.push({ type: EventType.MouseUp, message: 0 });
+    }
+    const text = typing.get(g.frames);
+    if (text !== undefined) {
+      for (const ch of text) inp.push({ type: EventType.KeyDown, message: ch.charCodeAt(0) });
+      inp.push({ type: EventType.KeyDown, message: 13 });
+    }
+    vm.run();
+  }
+} catch (e) {
+  console.log(`ERROR at frame ${g.frames}: ${(e as Error).message}\n${vm.backtrace().map((l) => `  at ${l}`).join("\n")}`);
+}
+console.log(`frames ${g.frames}, missing kernels:`, Object.fromEntries(vm.missingKernels));

package/tools/site/build.d.ts

@@ -0,0 +1,8 @@
+export declare function buildSite(gameDir: string, outDir: string, options?: {
+    docs?: string;
+    name?: string;
+}): Promise<{
+    pages: number;
+    game: string;
+    soundFont: boolean;
+}>;

package/tools/site/build.js

@@ -0,0 +1,110 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { writeResourceArchive } from "../../packages/sci/src/index.js";
+import { buildGame } from "../game/build.js";
+import { markdown } from "./markdown.js";
+/**
+ * A static site, to publish anywhere (GitHub Pages, any web server):
+ *
+ *   index.html, CONTRIBUTING.html, ...   the Markdown of this repository (or a game's), as pages
+ *   docs/...                             docs/**.md as pages, and their screenshots
+ *   play/play.html                       the player, with the game in play/game/
+ *
+ * The SoundFont for music is copied from assets/soundfonts/ if it's there (it isn't part
+ * of the repository); without it, games play silently.
+ */
+const ROOT = resolve(import.meta.dirname, "../..");
+const VIEWER = join(ROOT, "apps/viewer");
+const SOUNDFONT = join(ROOT, "assets/soundfonts/GeneralUser-GS.sf2");
+export async function buildSite(gameDir, outDir, options = {}) {
+    const out = resolve(outDir);
+    // Whose Markdown becomes the pages: this repository's, or the game's own.
+    const docs = resolve(options.docs ?? ROOT);
+    const name = options.name ?? "sci-ts";
+    rmSync(out, { recursive: true, force: true });
+    const game = await buildGame(gameDir);
+    // The player: built by Vite with relative paths, then the game beside it.
+    const { build } = await import("vite");
+    const play = join(out, "play");
+    await build({
+        root: VIEWER,
+        configFile: join(VIEWER, "vite.config.ts"),
+        base: "./",
+        logLevel: "warn",
+        build: { outDir: play, emptyOutDir: true, rollupOptions: { input: { play: join(VIEWER, "play.html") } } },
+    });
+    const { map, volume } = writeResourceArchive(game.resources);
+    const files = { "RESOURCE.MAP": map, "RESOURCE.000": volume, ...game.files };
+    mkdirSync(join(play, "game"), { recursive: true });
+    for (const [name, data] of Object.entries(files))
+        writeFileSync(join(play, "game", name), data);
+    // What the player lists in place of the dev server's directory listings.
+    writeFileSync(join(play, "game/files.json"), JSON.stringify({ "": Object.keys(files) }));
+    const soundFont = existsSync(SOUNDFONT);
+    if (soundFont)
+        cpSync(SOUNDFONT, join(play, "soundfonts", basename(SOUNDFONT)));
+    // The pages.
+    const sources = [
+        ...["README.md", "CONTRIBUTING.md", "CHANGELOG.md"].filter((f) => existsSync(join(docs, f))),
+        ...walk(docs, "docs").filter((f) => f.endsWith(".md")),
+    ];
+    const nav = [
+        ["index.html", name],
+        ["play/play.html", "Play"],
+        ...sources.filter((f) => f.startsWith("docs/") && dirname(f) === "docs").map((f) => [f.replace(/\.md$/, ".html"), titleOf(docs, f)]),
+    ];
+    for (const f of sources) {
+        const page = f === "README.md" ? "index.html" : f.replace(/\.md$/, ".html").replace(/(^|\/)README\.html$/, "$1index.html");
+        const { html, title } = markdown(readFileSync(join(docs, f), "utf8"));
+        const up = "../".repeat(page.split("/").length - 1);
+        const links = nav.map(([href, label]) => `<a href="${up}${href}"${href === page ? ' aria-current="page"' : ""}>${label}</a>`).join("");
+        mkdirSync(dirname(join(out, page)), { recursive: true });
+        writeFileSync(join(out, page), template(title || basename(f), name, links, html));
+    }
+    if (existsSync(join(docs, "docs/screenshots")))
+        cpSync(join(docs, "docs/screenshots"), join(out, "docs/screenshots"), { recursive: true });
+    if (existsSync(join(docs, "LICENSE")))
+        cpSync(join(docs, "LICENSE"), join(out, "LICENSE"));
+    return { pages: sources.length, game: relative(ROOT, resolve(gameDir)), soundFont };
+}
+function walk(root, dir) {
+    const abs = join(root, dir);
+    if (!existsSync(abs))
+        return [];
+    return readdirSync(abs).sort().flatMap((name) => (statSync(join(abs, name)).isDirectory() ? walk(root, `${dir}/${name}`) : [`${dir}/${name}`]));
+}
+const titleOf = (root, f) => markdown(readFileSync(join(root, f), "utf8")).title || basename(f, ".md");
+function template(title, site, nav, body) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title.replace(/</g, "&lt;")} · ${site}</title>
+<style>
+  :root { color-scheme: light dark; --fg: #1d1d1f; --bg: #fbfbf8; --muted: #6b6b6b; --line: #ddd; --code: #f0efe9; --link: #2a5db0; }
+  @media (prefers-color-scheme: dark) { :root { --fg: #e6e6e3; --bg: #18181a; --muted: #9a9a9a; --line: #333; --code: #242428; --link: #8ab4f8; } }
+  body { margin: 0; background: var(--bg); color: var(--fg); font: 16px/1.55 system-ui, sans-serif; }
+  nav { display: flex; flex-wrap: wrap; gap: 4px 16px; padding: 12px 16px; border-bottom: 1px solid var(--line); font-size: 14px; }
+  nav a { color: var(--muted); text-decoration: none; }
+  nav a[aria-current] { color: var(--fg); font-weight: 600; }
+  main { max-width: 760px; margin: 0 auto; padding: 16px 16px 64px; }
+  a { color: var(--link); }
+  img { max-width: 100%; image-rendering: pixelated; }
+  pre { background: var(--code); padding: 12px; overflow-x: auto; border-radius: 4px; font-size: 13px; }
+  code { background: var(--code); padding: 1px 4px; border-radius: 3px; font-size: 0.9em; }
+  pre code { background: none; padding: 0; }
+  table { border-collapse: collapse; display: block; overflow-x: auto; font-size: 14px; }
+  th, td { border: 1px solid var(--line); padding: 4px 8px; text-align: left; vertical-align: top; }
+  blockquote { margin: 0; padding: 0 16px; border-left: 3px solid var(--line); color: var(--muted); }
+</style>
+</head>
+<body>
+<nav>${nav}</nav>
+<main>
+${body}
+</main>
+</body>
+</html>
+`;
+}

package/tools/site/build.ts

@@ -0,0 +1,116 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { writeResourceArchive } from "../../packages/sci/src/index.ts";
+import { buildGame } from "../game/build.ts";
+import { markdown } from "./markdown.ts";
+
+/**
+ * A static site, to publish anywhere (GitHub Pages, any web server):
+ *
+ *   index.html, CONTRIBUTING.html, ...   the Markdown of this repository (or a game's), as pages
+ *   docs/...                             docs/**.md as pages, and their screenshots
+ *   play/play.html                       the player, with the game in play/game/
+ *
+ * The SoundFont for music is copied from assets/soundfonts/ if it's there (it isn't part
+ * of the repository); without it, games play silently.
+ */
+const ROOT = resolve(import.meta.dirname, "../..");
+const VIEWER = join(ROOT, "apps/viewer");
+const SOUNDFONT = join(ROOT, "assets/soundfonts/GeneralUser-GS.sf2");
+
+export async function buildSite(
+  gameDir: string,
+  outDir: string,
+  options: { docs?: string; name?: string } = {},
+): Promise<{ pages: number; game: string; soundFont: boolean }> {
+  const out = resolve(outDir);
+  // Whose Markdown becomes the pages: this repository's, or the game's own.
+  const docs = resolve(options.docs ?? ROOT);
+  const name = options.name ?? "sci-ts";
+  rmSync(out, { recursive: true, force: true });
+  const game = await buildGame(gameDir);
+
+  // The player: built by Vite with relative paths, then the game beside it.
+  const { build } = await import("vite");
+  const play = join(out, "play");
+  await build({
+    root: VIEWER,
+    configFile: join(VIEWER, "vite.config.ts"),
+    base: "./",
+    logLevel: "warn",
+    build: { outDir: play, emptyOutDir: true, rollupOptions: { input: { play: join(VIEWER, "play.html") } } },
+  });
+  const { map, volume } = writeResourceArchive(game.resources);
+  const files: Record<string, Uint8Array> = { "RESOURCE.MAP": map, "RESOURCE.000": volume, ...game.files };
+  mkdirSync(join(play, "game"), { recursive: true });
+  for (const [name, data] of Object.entries(files)) writeFileSync(join(play, "game", name), data);
+  // What the player lists in place of the dev server's directory listings.
+  writeFileSync(join(play, "game/files.json"), JSON.stringify({ "": Object.keys(files) }));
+  const soundFont = existsSync(SOUNDFONT);
+  if (soundFont) cpSync(SOUNDFONT, join(play, "soundfonts", basename(SOUNDFONT)));
+
+  // The pages.
+  const sources = [
+    ...["README.md", "CONTRIBUTING.md", "CHANGELOG.md"].filter((f) => existsSync(join(docs, f))),
+    ...walk(docs, "docs").filter((f) => f.endsWith(".md")),
+  ];
+  const nav = [
+    ["index.html", name],
+    ["play/play.html", "Play"],
+    ...sources.filter((f) => f.startsWith("docs/") && dirname(f) === "docs").map((f) => [f.replace(/\.md$/, ".html"), titleOf(docs, f)]),
+  ];
+  for (const f of sources) {
+    const page = f === "README.md" ? "index.html" : f.replace(/\.md$/, ".html").replace(/(^|\/)README\.html$/, "$1index.html");
+    const { html, title } = markdown(readFileSync(join(docs, f), "utf8"));
+    const up = "../".repeat(page.split("/").length - 1);
+    const links = nav.map(([href, label]) => `<a href="${up}${href}"${href === page ? ' aria-current="page"' : ""}>${label}</a>`).join("");
+    mkdirSync(dirname(join(out, page)), { recursive: true });
+    writeFileSync(join(out, page), template(title || basename(f), name, links, html));
+  }
+  if (existsSync(join(docs, "docs/screenshots"))) cpSync(join(docs, "docs/screenshots"), join(out, "docs/screenshots"), { recursive: true });
+  if (existsSync(join(docs, "LICENSE"))) cpSync(join(docs, "LICENSE"), join(out, "LICENSE"));
+  return { pages: sources.length, game: relative(ROOT, resolve(gameDir)), soundFont };
+}
+
+function walk(root: string, dir: string): string[] {
+  const abs = join(root, dir);
+  if (!existsSync(abs)) return [];
+  return readdirSync(abs).sort().flatMap((name) => (statSync(join(abs, name)).isDirectory() ? walk(root, `${dir}/${name}`) : [`${dir}/${name}`]));
+}
+
+const titleOf = (root: string, f: string) => markdown(readFileSync(join(root, f), "utf8")).title || basename(f, ".md");
+
+function template(title: string, site: string, nav: string, body: string): string {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title.replace(/</g, "&lt;")} · ${site}</title>
+<style>
+  :root { color-scheme: light dark; --fg: #1d1d1f; --bg: #fbfbf8; --muted: #6b6b6b; --line: #ddd; --code: #f0efe9; --link: #2a5db0; }
+  @media (prefers-color-scheme: dark) { :root { --fg: #e6e6e3; --bg: #18181a; --muted: #9a9a9a; --line: #333; --code: #242428; --link: #8ab4f8; } }
+  body { margin: 0; background: var(--bg); color: var(--fg); font: 16px/1.55 system-ui, sans-serif; }
+  nav { display: flex; flex-wrap: wrap; gap: 4px 16px; padding: 12px 16px; border-bottom: 1px solid var(--line); font-size: 14px; }
+  nav a { color: var(--muted); text-decoration: none; }
+  nav a[aria-current] { color: var(--fg); font-weight: 600; }
+  main { max-width: 760px; margin: 0 auto; padding: 16px 16px 64px; }
+  a { color: var(--link); }
+  img { max-width: 100%; image-rendering: pixelated; }
+  pre { background: var(--code); padding: 12px; overflow-x: auto; border-radius: 4px; font-size: 13px; }
+  code { background: var(--code); padding: 1px 4px; border-radius: 3px; font-size: 0.9em; }
+  pre code { background: none; padding: 0; }
+  table { border-collapse: collapse; display: block; overflow-x: auto; font-size: 14px; }
+  th, td { border: 1px solid var(--line); padding: 4px 8px; text-align: left; vertical-align: top; }
+  blockquote { margin: 0; padding: 0 16px; border-left: 3px solid var(--line); color: var(--muted); }
+</style>
+</head>
+<body>
+<nav>${nav}</nav>
+<main>
+${body}
+</main>
+</body>
+</html>
+`;
+}

package/tools/site/markdown.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Markdown to HTML, for the docs pages of a built site: the parts the docs use (headings,
+ * paragraphs, lists, tables, fenced code, quotes; code, links, images, bold and italic
+ * inline). Links to .md files become links to the .html pages made from them.
+ */
+export declare const slug: (text: string) => string;
+export declare function inline(text: string): string;
+export declare function markdown(source: string): {
+    html: string;
+    title: string;
+};

package/tools/site/markdown.js

@@ -0,0 +1,88 @@
+/**
+ * Markdown to HTML, for the docs pages of a built site: the parts the docs use (headings,
+ * paragraphs, lists, tables, fenced code, quotes; code, links, images, bold and italic
+ * inline). Links to .md files become links to the .html pages made from them.
+ */
+const escape = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+export const slug = (text) => text.toLowerCase().replace(/<[^>]+>/g, "").replace(/[^\w\s-]/g, "").trim().replace(/\s+/g, "-");
+const pageLink = (href) => /^[a-z]+:/i.test(href) || href.startsWith("#") ? href : href.replace(/(^|\/)README\.md(?=#|$)/, "$1index.md").replace(/\.md(?=#|$)/, ".html");
+export function inline(text) {
+    const code = [];
+    let s = text.replace(/`([^`]+)`/g, (_, c) => `\u0000${code.push(`<code>${escape(c)}</code>`) - 1}\u0000`);
+    s = escape(s);
+    s = s.replace(/!\[([^\]]*)\]\(([^)\s]+)\)/g, (_, alt, src) => `<img src="${src}" alt="${alt}">`);
+    s = s.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_, label, href) => `<a href="${pageLink(href)}">${label}</a>`);
+    s = s.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+    s = s.replace(/(^|[\s(])\*([^*\s][^*]*)\*/g, "$1<em>$2</em>");
+    return s.replace(/\u0000(\d+)\u0000/g, (_, i) => code[Number(i)]);
+}
+export function markdown(source) {
+    const lines = source.replace(/\r\n/g, "\n").split("\n");
+    const out = [];
+    let title = "";
+    let i = 0;
+    const cells = (row) => row.trim().replace(/^\||\|$/g, "").split(/(?<!\\)\|/).map((c) => inline(c.trim().replace(/\\\|/g, "|")));
+    while (i < lines.length) {
+        const line = lines[i];
+        if (!line.trim()) {
+            i++;
+            continue;
+        }
+        const fence = /^```(\w*)/.exec(line);
+        if (fence) {
+            const body = [];
+            for (i++; i < lines.length && !lines[i].startsWith("```"); i++)
+                body.push(lines[i]);
+            i++;
+            out.push(`<pre><code${fence[1] ? ` class="language-${fence[1]}"` : ""}>${escape(body.join("\n"))}</code></pre>`);
+            continue;
+        }
+        const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+        if (heading) {
+            const text = inline(heading[2]);
+            if (!title && heading[1].length === 1)
+                title = heading[2].replace(/[*`]/g, "");
+            out.push(`<h${heading[1].length} id="${slug(text)}">${text}</h${heading[1].length}>`);
+            i++;
+            continue;
+        }
+        if (line.startsWith("|") && /^\|?\s*:?-+/.test(lines[i + 1] ?? "")) {
+            const head = cells(line);
+            const rows = [];
+            for (i += 2; i < lines.length && lines[i].startsWith("|"); i++)
+                rows.push(cells(lines[i]));
+            out.push(`<table><thead><tr>${head.map((c) => `<th>${c}</th>`).join("")}</tr></thead><tbody>${rows.map((r) => `<tr>${r.map((c) => `<td>${c}</td>`).join("")}</tr>`).join("")}</tbody></table>`);
+            continue;
+        }
+        if (line.startsWith(">")) {
+            const body = [];
+            for (; i < lines.length && lines[i].startsWith(">"); i++)
+                body.push(lines[i].replace(/^>\s?/, ""));
+            out.push(`<blockquote>${markdown(body.join("\n")).html}</blockquote>`);
+            continue;
+        }
+        const item = /^(\s*)([-*]|\d+\.)\s+/;
+        if (item.test(line)) {
+            const ordered = /^\s*\d+\./.test(line);
+            const items = [];
+            for (; i < lines.length; i++) {
+                const l = lines[i];
+                if (item.test(l))
+                    items.push(l.replace(item, ""));
+                else if (l.trim() && /^\s{2,}/.test(l) && items.length)
+                    items[items.length - 1] += ` ${l.trim()}`;
+                else
+                    break;
+            }
+            const tag = ordered ? "ol" : "ul";
+            out.push(`<${tag}>${items.map((t) => `<li>${inline(t)}</li>`).join("")}</${tag}>`);
+            continue;
+        }
+        // A paragraph: lines up to a blank one or the start of another block (always at least one).
+        const para = [lines[i++].trim()];
+        for (; i < lines.length && lines[i].trim() && !/^(#{1,6}\s|```|\||>|\s*([-*]|\d+\.)\s)/.test(lines[i]); i++)
+            para.push(lines[i].trim());
+        out.push(`<p>${inline(para.join(" "))}</p>`);
+    }
+    return { html: out.join("\n"), title };
+}