@erdemtuna/doc-review 0.7.0

package/src/cli.js

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { canonicalTarget, ensureStateDir, SERVER_PROTOCOL, serverPath, statePath, targetKey } from "./paths.js";
+import { readServerLock } from "./server-lock.js";
+import { installSkills, shellQuote } from "./setup.js";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(fs.readFileSync(path.join(here, "..", "package.json"), "utf8"));
+
+const HELP = `doc-review ${pkg.version}
+
+  doc-review <file-or-localhost-url> Open a file or localhost page for review
+  doc-review poll <target>          Wait for feedback, print it as JSON (for agents)
+      --ack <batch_id>             Acknowledge that exact delivered batch, then keep waiting
+      --timeout <secs>             Exit with {"status":"timeout"} if nothing arrives
+  doc-review status <target>        Report whether feedback is waiting, without blocking
+  doc-review setup                  Teach Claude Code / Codex how to use doc-review
+  doc-review setup --global         ...for every project, not just this one
+
+Everything runs locally. No account, no cloud, no database.
+`;
+
+// --------------------------------------------------------------- server glue
+
+function readServerRecord() {
+  try {
+    return JSON.parse(fs.readFileSync(serverPath(), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function request(server, options, body) {
+  const port = typeof server === "number" ? server : server.port;
+  const token = typeof server === "number" ? "" : server.token || "";
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      {
+        host: "127.0.0.1",
+        port,
+        ...options,
+        headers: { ...(token ? { "x-doc-review-token": token } : {}), ...(options.headers || {}) },
+      },
+      (res) => {
+        let raw = "";
+        res.setEncoding("utf8");
+        res.on("data", (chunk) => {
+          raw += chunk;
+        });
+        res.on("end", () => resolve({ status: res.statusCode, raw }));
+      }
+    );
+    req.on("error", reject);
+    if (options.timeout) req.setTimeout(options.timeout, () => req.destroy(new Error("timeout")));
+    if (body) req.write(JSON.stringify(body));
+    req.end();
+  });
+}
+
+async function alive(server) {
+  try {
+    const lock = readServerLock();
+    if (lock?.pid !== server.pid || lock?.instance_id !== server.instance_id) return false;
+    const res = await request(server, { method: "GET", path: "/health", timeout: 1200 });
+    if (res.status !== 200) return false;
+    const health = JSON.parse(res.raw);
+    return (
+      health.protocol === SERVER_PROTOCOL &&
+      health.pid === server.pid &&
+      health.instance_id === server.instance_id
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function ensureServer() {
+  ensureStateDir();
+  for (let launch = 0; launch < 3; launch += 1) {
+    const saved = readServerRecord();
+    if (saved?.protocol === SERVER_PROTOCOL && saved.port && saved.instance_id && (await alive(saved))) return saved;
+
+    const child = spawn(process.execPath, [path.join(here, "server-entry.js")], {
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+
+    for (let attempt = 0; attempt < 60; attempt += 1) {
+      await new Promise((r) => setTimeout(r, 100));
+      const record = readServerRecord();
+      // Same protocol gate as above: a still-running server from an older
+      // version answers /health too, and must not be adopted here.
+      if (record?.protocol === SERVER_PROTOCOL && record.port && record.instance_id && (await alive(record))) return record;
+      if (child.exitCode !== null && !readServerLock()) break;
+    }
+  }
+  throw new Error("Could not start the local doc-review server.");
+}
+
+function openBrowser(url) {
+  const command =
+    process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+  const child = spawn(command[0], command[1], { detached: true, stdio: "ignore" });
+  // A missing opener (headless Linux without xdg-open) surfaces as an async
+  // 'error' event, not a throw. Printing the URL below is the fallback.
+  child.on("error", () => {});
+  child.unref();
+}
+
+// ------------------------------------------------------------------ commands
+
+async function openCommand(input) {
+  const target = canonicalTarget(input);
+  if (target.kind === "file" && !fs.existsSync(target.value)) {
+    console.error(`File not found: ${target.value}`);
+    process.exit(1);
+  }
+  const server = await ensureServer();
+  const res = await request(server, { method: "POST", path: "/api/session", headers: { "content-type": "application/json" } }, { target: target.value });
+  const body = JSON.parse(res.raw);
+  if (res.status !== 200) {
+    console.error(body.error || "Could not open that file.");
+    process.exit(1);
+  }
+  const url = `http://127.0.0.1:${server.port}${body.path}`;
+  openBrowser(url);
+  console.log(`Reviewing ${target.kind === "url" ? target.value : path.basename(target.value)}`);
+  console.log(url);
+  console.log(`\nWaiting for feedback? Run:\n  doc-review poll ${shellQuote(target.value)}`);
+}
+
+/**
+ * One long-poll attempt. Resolves { kind: "data", raw } when the server
+ * answers, or { kind: "timeout" } when the caller's deadline passes first.
+ */
+function pollOnce(server, target, ackId, timeoutMs) {
+  const query = `target=${encodeURIComponent(target)}${ackId ? `&ack=${encodeURIComponent(ackId)}` : ""}`;
+  return new Promise((resolve, reject) => {
+    let done = false;
+    const settle = (fn, value) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      fn(value);
+    };
+    const req = http.request(
+      {
+        host: "127.0.0.1",
+        port: server.port,
+        method: "GET",
+        path: `/api/poll?${query}`,
+        headers: { "x-doc-review-token": server.token || "" },
+      },
+      (res) => {
+        let raw = "";
+        res.setEncoding("utf8");
+        res.on("data", (chunk) => {
+          raw += chunk;
+        });
+        res.on("end", () => settle(resolve, { kind: "data", raw: raw.trim() }));
+      }
+    );
+    const timer = timeoutMs
+      ? setTimeout(() => {
+          settle(resolve, { kind: "timeout" });
+          req.destroy();
+        }, timeoutMs)
+      : null;
+    req.on("error", (err) => settle(reject, err));
+    req.end();
+  });
+}
+
+/**
+ * The consumer is an agent reading a pipe. process.exit() does not wait for
+ * pending stdout writes, so a large payload could arrive truncated — always
+ * wait for the write to hand off before returning.
+ */
+function writeStdout(text) {
+  return new Promise((resolve) => process.stdout.write(text, resolve));
+}
+
+function printTimeout(waitedSecs) {
+  const payload = {
+    status: "timeout",
+    waited_seconds: waitedSecs,
+    next_step:
+      "No feedback yet. Run the same poll command again to keep waiting, or `doc-review status <target>` to check without blocking.",
+  };
+  return writeStdout(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+async function pollCommand(input, { ackId = "", timeoutSecs = 0 } = {}) {
+  const target = canonicalTarget(input).value;
+  let server = await ensureServer();
+
+  const label = /^https?:\/\//i.test(target) ? target : path.basename(target);
+  process.stderr.write(`Waiting for feedback on ${label} — comment in the browser, then hit Send.\n`);
+
+  const deadline = timeoutSecs ? Date.now() + timeoutSecs * 1000 : null;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const remaining = deadline ? deadline - Date.now() : 0;
+    if (deadline && remaining <= 0) return printTimeout(timeoutSecs);
+    let result;
+    try {
+      result = await pollOnce(server, target, ackId && attempt === 0 ? ackId : "", remaining);
+    } catch (err) {
+      process.stderr.write(`Lost the connection (${err.message}); retrying.\n`);
+      server = await ensureServer();
+      continue;
+    }
+    if (result.kind === "timeout") return printTimeout(timeoutSecs);
+    if (!result.raw) {
+      server = await ensureServer();
+      continue;
+    }
+    try {
+      const batch = JSON.parse(result.raw);
+      await writeStdout(`${JSON.stringify(batch, null, 2)}\n`);
+      return;
+    } catch {
+      process.stderr.write("Unexpected response from the doc-review server; retrying.\n");
+    }
+  }
+  process.stderr.write("Gave up waiting for feedback.\n");
+  process.exit(1);
+}
+
+/**
+ * Instant answer, no blocking. Asks the running server when there is one;
+ * otherwise reads the persisted state directly, so a dead server still
+ * reports feedback that is waiting for a fresh poll.
+ */
+async function statusCommand(input) {
+  const target = canonicalTarget(input).value;
+  const saved = readServerRecord();
+  if (saved?.protocol === SERVER_PROTOCOL && saved.port && saved.instance_id && (await alive(saved))) {
+    const res = await request(saved, { method: "GET", path: `/api/status?target=${encodeURIComponent(target)}` });
+    if (res.status === 200) {
+      process.stdout.write(`${JSON.stringify(JSON.parse(res.raw), null, 2)}\n`);
+      return;
+    }
+  }
+
+  let data = { pages: {}, batches: {} };
+  try {
+    data = JSON.parse(fs.readFileSync(statePath(), "utf8"));
+  } catch {
+    // No state yet: everything below reads as empty.
+  }
+  const key = targetKey(target);
+  const pending = (data.batches || {})[key];
+  const page = (data.pages || {})[key];
+  const payload = {
+    status: pending ? "feedback-waiting" : "idle",
+    feedback_waiting: !!pending,
+    agent_listening: false,
+    server_running: false,
+    unsent: {
+      comments: page ? page.comments.length : 0,
+      edits: page ? page.edits.length : 0,
+    },
+  };
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+// ---------------------------------------------------------------------- main
+
+const argv = process.argv.slice(2);
+
+if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h" || argv[0] === "help") {
+  console.log(HELP);
+  process.exit(0);
+}
+
+if (argv[0] === "--version" || argv[0] === "-v") {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+process.on("SIGINT", () => {
+  process.stderr.write("\nStopped waiting. Your feedback is safe — run the same command again to pick it up.\n");
+  process.exit(130);
+});
+
+function parsePollArgs(rest) {
+  const parsed = { file: "", ackId: "", timeoutSecs: 0 };
+  let sawTimeout = false;
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === "--ack") {
+      const value = rest[(i += 1)];
+      if (!value || value.startsWith("-")) {
+        throw new Error("--ack requires the batch_id from the feedback response, e.g. --ack b_123");
+      }
+      parsed.ackId = value;
+    }
+    else if (arg.startsWith("--ack=")) {
+      throw new Error("Use --ack <batch_id> with the batch ID as a separate argument.");
+    }
+    else if (arg === "--timeout") {
+      sawTimeout = true;
+      parsed.timeoutSecs = Number(rest[(i += 1)]);
+    } else if (arg.startsWith("--timeout=")) {
+      sawTimeout = true;
+      parsed.timeoutSecs = Number(arg.slice("--timeout=".length));
+    } else if (!arg.startsWith("-") && !parsed.file) parsed.file = arg;
+    else throw new Error(`Unknown poll argument: ${arg}`);
+  }
+  // A malformed value must fail loudly — NaN or 0 silently waiting forever is
+  // the exact hang the flag exists to prevent.
+  if (sawTimeout && (!Number.isFinite(parsed.timeoutSecs) || parsed.timeoutSecs <= 0)) {
+    throw new Error("--timeout wants a number of seconds, e.g. --timeout 300");
+  }
+  return parsed;
+}
+
+try {
+  if (argv[0] === "poll") {
+    const { file, ackId, timeoutSecs } = parsePollArgs(argv.slice(1));
+    if (!file) throw new Error("Usage: doc-review poll <file-or-localhost-url> [--ack <batch_id>] [--timeout <secs>]");
+    await pollCommand(file, { ackId, timeoutSecs });
+  } else if (argv[0] === "status") {
+    const file = argv.find((a, i) => i > 0 && !a.startsWith("-"));
+    if (!file) throw new Error("Usage: doc-review status <file-or-localhost-url>");
+    await statusCommand(file);
+  } else if (argv[0] === "setup") {
+    const isGlobal = argv.includes("--global") || argv.includes("-g");
+    installSkills(process.cwd(), { global: isGlobal }).forEach((line) => console.log(line));
+  } else {
+    await openCommand(argv[0]);
+  }
+} catch (err) {
+  console.error(err.message || String(err));
+  process.exit(1);
+}

package/src/click-target.js

@@ -0,0 +1,26 @@
+export function navigationHref(target) {
+  const link = target?.closest?.("a[href]");
+  if (link) return link.getAttribute("href") || "";
+  const control = target?.closest?.("[data-href]");
+  return control ? control.getAttribute("data-href") || "" : "";
+}
+
+/**
+ * Decide what a modified click on a "#…" link should do. Setting the real
+ * hash is what makes CSS :target routing (single-file "pages") show the
+ * section — a bare scrollIntoView can't reach a display:none target and
+ * never fires :target. Only when the hash is already current does scrolling
+ * become the right move, since re-setting an identical hash is a no-op.
+ */
+export function hashClickAction(href, currentHash) {
+  const decode = (value) => {
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value;
+    }
+  };
+  const id = decode(href.slice(1));
+  if (decode((currentHash || "").slice(1)) === id) return { kind: "scroll", id };
+  return { kind: "navigate", hash: href };
+}

package/src/editing.js

@@ -0,0 +1,99 @@
+/**
+ * Pure editing helpers, shared by the in-page SDK and Node tests.
+ *
+ * Everything here is deliberately DOM-free: the SDK feeds in strings and
+ * computed-style snapshots, and gets back decisions it can apply.
+ */
+
+/**
+ * The list command for a marker typed at the start of a line, or null.
+ * `lead` is everything between the start of the block and the caret, so a
+ * marker typed mid-sentence never converts.
+ */
+export function listCommandFor(lead) {
+  const marker = String(lead || "").replace(/\u00a0/g, " ").trim();
+  if (/^[-*]$/.test(marker)) return "insertUnorderedList";
+  if (/^\d{1,3}[.)]$/.test(marker)) return "insertOrderedList";
+  return null;
+}
+
+/**
+ * Style properties a fresh list needs when the page's CSS reset hides it.
+ * Tailwind preflight and similar resets set `list-style: none` and zero the
+ * indent, so a just-created list looks like nothing happened. Returns only
+ * the properties that are actually broken, so styled pages stay untouched.
+ */
+export function listStyleFixup(tagName, computed) {
+  const patch = {};
+  if (computed.listStyleType === "none") {
+    patch.listStyleType = /^ol$/i.test(tagName) ? "decimal" : "disc";
+  }
+  const inset = (parseFloat(computed.paddingLeft) || 0) + (parseFloat(computed.marginLeft) || 0);
+  if (inset < 16) patch.paddingLeft = "1.5em";
+  return patch;
+}
+
+/**
+ * Style a fresh link needs when the page can't distinguish it from prose.
+ * Reset stylesheets (`a { color: inherit; text-decoration: inherit }`) make a
+ * just-created link invisible; underline it only when neither color nor
+ * decoration sets it apart.
+ */
+export function linkStyleFixup(anchorComputed, parentComputed) {
+  const decorated = String(anchorComputed.textDecorationLine || "").includes("underline");
+  const recolored = !!parentComputed && anchorComputed.color !== parentComputed.color;
+  return decorated || recolored ? {} : { textDecoration: "underline" };
+}
+
+/**
+ * A typed link, made openable and safe. Bare domains get https://, in-page
+ * and relative references pass through, and anything with an executable or
+ * unknown scheme (javascript:, data:, …) is rejected outright.
+ */
+export function normalizeHref(raw) {
+  const href = String(raw || "").replace(/[\u0000-\u001f\u007f]/g, "").trim();
+  if (!href) return "";
+  let candidate = href;
+  if (!/^(https?:|mailto:|tel:|#|\/|\.)/i.test(href)) {
+    const head = href.split(/[/?#]/)[0];
+    if (/^([\w-]+\.)+[\w-]+(:\d+)?$/.test(head) || /^localhost(:\d+)?$/i.test(head)) {
+      // A bare domain — "example.com", "localhost:3000/wiki" — gets a scheme.
+      candidate = `https://${href}`;
+    } else if (/^[a-z][a-z0-9+.-]*:/i.test(href)) {
+      return "";
+    }
+  }
+  try {
+    const parsed = new URL(candidate, "https://relative.invalid");
+    if (!/^(https?:|mailto:|tel:)$/i.test(parsed.protocol)) return "";
+  } catch {
+    return "";
+  }
+  return candidate;
+}
+
+/**
+ * Classify an authored navigation target. Relative references stay under
+ * controlled source-relative navigation; only explicitly safe external
+ * schemes leave the review.
+ */
+export function classifyHref(raw) {
+  const href = String(raw || "").replace(/[\u0000-\u001f\u007f]/g, "").trim();
+  if (!href) return "invalid";
+  if (href.startsWith("#")) return "hash";
+  if (/^\/\//.test(href) || /^https?:/i.test(href) || /^(?:mailto|tel):/i.test(href)) return "external";
+  if (/^[a-z][a-z0-9+.-]*:/i.test(href)) return "invalid";
+  return "navigate";
+}
+
+export function externalHref(raw, baseHref = "https://relative.invalid/") {
+  const href = String(raw || "").replace(/[\u0000-\u001f\u007f]/g, "").trim();
+  if (classifyHref(href) !== "external") return "";
+  if (/^(?:mailto|tel):/i.test(href)) return href;
+  try {
+    const parsed = new URL(href, baseHref);
+    return /^https?:$/i.test(parsed.protocol) ? parsed.href : "";
+  } catch {
+    return "";
+  }
+}

package/src/frame-channel.js

@@ -0,0 +1,44 @@
+let channel = null;
+
+export function initializeChannel(capability, generation, pageKey) {
+  if (channel) throw new Error("Doc Review frame channel is already initialized.");
+  channel = {
+    capability: String(capability),
+    generation: Number(generation),
+    pageKey: String(pageKey),
+  };
+}
+
+export function initializeChannelFromDocument() {
+  const script = document.querySelector("script[data-eh-sdk][data-eh-bootstrap]");
+  if (!script) throw new Error("Doc Review frame bootstrap is missing.");
+  const capability = script.nonce;
+  const generation = Number(script.dataset.generation);
+  const pageKey = String(script.dataset.pageKey || "");
+  script.remove();
+  if (!capability || !Number.isSafeInteger(generation) || !pageKey) {
+    throw new Error("Doc Review frame bootstrap is invalid.");
+  }
+  initializeChannel(capability, generation, pageKey);
+}
+
+export function frameMessage(type, payload = {}) {
+  if (!channel) throw new Error("Doc Review frame channel is not initialized.");
+  return {
+    ...payload,
+    type,
+    capability: channel.capability,
+    generation: channel.generation,
+    pageKey: channel.pageKey,
+  };
+}
+
+export function matchesFrameMessage(message) {
+  return !!(
+    channel &&
+    message &&
+    message.capability === channel.capability &&
+    message.generation === channel.generation &&
+    message.pageKey === channel.pageKey
+  );
+}

package/src/frame-policy.js

@@ -0,0 +1,16 @@
+const BASE_SANDBOX = "allow-scripts allow-forms allow-modals";
+const LOCALHOST_SANDBOX = `${BASE_SANDBOX} allow-popups allow-downloads allow-same-origin`;
+
+/**
+ * Localhost apps need their real origin so their routing and JavaScript work.
+ * Files and rendered Markdown do not: An opaque iframe origin prevents them
+ * from reading sibling files served by the artifact route.
+ */
+export function framePolicy(page, artifactOrigin) {
+  const keepsOrigin = page?.kind === "url";
+  return {
+    sandbox: keepsOrigin ? LOCALHOST_SANDBOX : BASE_SANDBOX,
+    incomingOrigin: keepsOrigin ? artifactOrigin : "null",
+    targetOrigin: keepsOrigin ? artifactOrigin : "*",
+  };
+}

package/src/html-transform.js

@@ -0,0 +1,62 @@
+// Match only the tag itself: injection adds no whitespace, so stripping must
+// not eat any either, or open→save would not round-trip byte-identically.
+const SDK_TAG_RE = /<script[^>]*\bdata-eh-sdk\b[^>]*\bdata-eh-bootstrap\b[^>]*><\/script>/gi;
+const SDK_BASE_RE = /<base[^>]*\bdata-eh-sdk\b[^>]*>/gi;
+const SDK_ROUTE_RE = /<script[^>]*\bdata-eh-route\b[^>]*>[\s\S]*?<\/script>/gi;
+const ASSET_TAG_RE = /<(script|link|img|source|video|audio|iframe|embed|object)\b[^>]*>/gi;
+const ASSET_ATTR_RE = /(\s)(src|href|poster|data)=(['"])(.*?)\3/gi;
+
+function absolutizeAssets(html, baseHref) {
+  return String(html).replace(ASSET_TAG_RE, (tag) =>
+    tag.replace(ASSET_ATTR_RE, (attribute, space, name, quote, value) => {
+      if (!value || /^(?:data|blob|javascript):/i.test(value) || value.startsWith("#")) return attribute;
+      const absolute = new URL(value, baseHref).href;
+      return `${space}${name}=${quote}${absolute}${quote}`;
+    })
+  );
+}
+
+/**
+ * Add the review bootstrap tags. Everything else about the artifact is left
+ * byte-identical, so the saved file renders the same standalone.
+ */
+export function injectSdk(
+  html,
+  key,
+  { src = "/sdk.js", baseHref = "", nonce = "", generation = 0, pageKey = key } = {}
+) {
+  const clean = stripSdk(html);
+  const escapedSrc = String(src).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+  const escapedNonce = String(nonce).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+  const escapedPageKey = String(pageKey).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+  const nonceAttr = escapedNonce ? ` nonce="${escapedNonce}"` : "";
+  const tag =
+    `<script data-eh-sdk data-eh-bootstrap type="module"${nonceAttr}` +
+    ` data-generation="${Number(generation)}" data-page-key="${escapedPageKey}" src="${escapedSrc}"></script>`;
+  let prepared = clean;
+  if (baseHref) {
+    const url = new URL(baseHref);
+    const route = JSON.stringify(`${url.pathname}${url.search}${url.hash}`).replace(/</g, "\\u003c");
+    const restoreRoute = `<script data-eh-route>history.replaceState(null,"",location.origin+${route})</script>`;
+    prepared = absolutizeAssets(prepared, baseHref);
+    prepared = /<head(?:\s[^>]*)?>/i.test(prepared)
+      ? prepared.replace(/<head(\s[^>]*)?>/i, (head) => `${head}${restoreRoute}`)
+      : `${restoreRoute}${prepared}`;
+  }
+  // Put the trusted module before authored markup can enter an unclosed
+  // script/style/textarea raw-text context. Removing this exact tag restores
+  // every authored byte.
+  const doctype = /^(\uFEFF?\s*(?:<!--[\s\S]*?-->\s*)*<!doctype[^>]*>)/i.exec(prepared);
+  const at = doctype ? doctype[0].length : 0;
+  return `${prepared.slice(0, at)}${tag}${prepared.slice(at)}`;
+}
+
+/** Remove any injected tag, so a file saved with one never keeps it. */
+export function stripSdk(html) {
+  return String(html).replace(SDK_TAG_RE, "").replace(SDK_BASE_RE, "").replace(SDK_ROUTE_RE, "");
+}
+
+export function hasSdk(html) {
+  SDK_TAG_RE.lastIndex = 0;
+  return SDK_TAG_RE.test(String(html));
+}

package/src/markdown.js

@@ -0,0 +1,87 @@
+import path from "node:path";
+import { marked, Renderer } from "marked";
+
+export const isMarkdown = (file) => /\.(md|markdown)$/i.test(file);
+
+/**
+ * Readable defaults for rendered Markdown. This HTML is a viewing surface
+ * only — it is never written back to disk, so the styling can be opinionated.
+ */
+const STYLE = `
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; background: #fdfcfa; color: #1b1a16;
+    font: 16px/1.65 -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+    -webkit-font-smoothing: antialiased;
+  }
+  main { max-width: 72ch; margin: 0 auto; padding: 48px 28px 96px; }
+  h1, h2, h3, h4 { line-height: 1.25; margin: 1.6em 0 .5em; }
+  h1 { font-size: 2em; margin-top: .4em; }
+  h2 { font-size: 1.45em; border-bottom: 1px solid #eceae3; padding-bottom: .25em; }
+  h3 { font-size: 1.15em; }
+  p, ul, ol { margin: .75em 0; }
+  li { margin: .3em 0; }
+  a { color: #295fcc; }
+  code {
+    background: #f2f0ea; border-radius: 4px; padding: .12em .35em;
+    font: .88em/1.5 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  }
+  pre { background: #f2f0ea; border-radius: 8px; padding: 14px 16px; overflow-x: auto; }
+  pre code { background: none; padding: 0; }
+  blockquote { margin: 1em 0; padding: .1em 1em; border-left: 3px solid #d8d5cb; color: #6b6862; }
+  table { border-collapse: collapse; margin: 1em 0; width: 100%; }
+  th, td { border: 1px solid #e4e2db; padding: 7px 11px; text-align: left; }
+  th { background: #f7f5f0; }
+  img { max-width: 100%; height: auto; }
+  hr { border: none; border-top: 1px solid #eceae3; margin: 2.2em 0; }
+`;
+
+const escapeHtml = (value) =>
+  String(value)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+
+function safeUrl(value, { image = false } = {}) {
+  const url = String(value || "").trim();
+  const probe = url.replace(/[\u0000-\u0020\u007f]+/g, "");
+  const match = /^([a-z][a-z0-9+.-]*):/i.exec(probe);
+  if (!match) return url;
+  const scheme = match[1].toLowerCase();
+  if (scheme === "http" || scheme === "https") return url;
+  if (!image && scheme === "mailto") return url;
+  if (image && /^data:image\/(?:avif|gif|jpe?g|png|webp);base64,/i.test(probe)) return url;
+  return null;
+}
+
+// Markdown can contain arbitrary HTML. Show that source as text so event
+// handlers, embeds, SVG, and future browser features can never become active.
+const INERT_RENDERER = new Renderer();
+INERT_RENDERER.html = ({ text }) => escapeHtml(text);
+INERT_RENDERER.link = function (token) {
+  const href = safeUrl(token.href);
+  if (!href) return this.parser.parseInline(token.tokens);
+  return Renderer.prototype.link.call(this, { ...token, href });
+};
+INERT_RENDERER.image = function (token) {
+  const href = safeUrl(token.href, { image: true });
+  if (!href) return escapeHtml(token.text || "");
+  return Renderer.prototype.image.call(this, { ...token, href });
+};
+
+/** Render a Markdown file into a standalone review page. */
+export function renderMarkdownPage(mdText, file) {
+  const body = marked.parse(mdText, { gfm: true, async: false, renderer: INERT_RENDERER });
+  const title = path.basename(file);
+  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, "&amp;").replace(/</g, "&lt;")}</title>
+<style>${STYLE}</style>
+</head>
+<body><main>${body}</main></body>
+</html>
+`;
+}