dflow-sdd-ddd 0.12.0 → 0.13.0

package/lib/render.js

@@ -0,0 +1,1263 @@
+// dflow render — specs Markdown -> human-readable static HTML (PROPOSAL-073).
+//
+// Markdown stays the AI-facing source of truth; this command projects it into
+// a mirrored .html tree plus a root index.html file-tree for human reading.
+// Every run is a full rebuild (the index tree and in-tree autolinks depend on
+// the whole file set, so partial rebuilds would leave stale links).
+//
+// Rendering parity baseline: the retired dev prototype
+// (prototypes/md-html/render_html.py at its 2026-07-09 converged shape),
+// user-acceptance-tested per feature: all-table cardification, frontmatter
+// title card + status pill, phase badges / fill-timing chips, gherkin keyword
+// highlighting, .md link rewriting with GFM-style heading ids (CJK-safe), and
+// in-tree autolinking of inline-code .md mentions.
+//
+// marked ships as ESM-only and `require(esm)` is not on by default until Node
+// 22.12 (engines allows >=22.0.0), so this CommonJS module MUST load it via
+// dynamic import('marked') — never via a require() call.
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const DEFAULT_SRC = 'dflow/specs';
+const DEFAULT_OUT = 'dflow-specs-html';
+const DEFAULT_TITLE = 'dflow specs';
+
+// Ownership + stale-cleanup ledger for the output directory. The manifest
+// lists every file the previous run generated (mirror .html tree + root
+// index.html; never the manifest itself). Its presence marks the directory as
+// render-owned; its file list is the ONLY set stale cleanup may ever delete.
+const MANIFEST_NAME = '.dflow-render-manifest.json';
+const MANIFEST_TMP_NAME = `${MANIFEST_NAME}.tmp`;
+const MANIFEST_VERSION = 1;
+// Per-file ownership proof, embedded in every rendered page. The manifest
+// alone is a weak proof for mutations — it is an ordinary JSON file that can
+// be copied or hand-written into a directory full of foreign files (cold-eye
+// gate G3 F1) — so deletes and overwrites additionally require this marker
+// in the target file itself. Keep the text stable across versions: outputs
+// of older dflow renders must stay recognized by newer ones.
+const GENERATED_MARK = '<!-- generated by dflow render -->';
+
+const PHASE_MARK_STYLE = {
+  ADDED: ['ok', '新增'],
+  MODIFIED: ['warn', '修改'],
+  REMOVED: ['del', '移除'],
+  RENAMED: ['info', '改名']
+};
+
+const STATUS_PILL = {
+  'in-progress': 'warn',
+  completed: 'ok',
+  done: 'ok',
+  open: 'info',
+  draft: 'neutral'
+};
+
+const GHERKIN_KEYWORDS = /^(\s*)(Scenario(?: Outline)?:|Background:|Examples:|Given|When|Then|And|But)(?=[ \t]|$)/gm;
+
+// All multi-column tables render as cards (user decision 2026-07-09 after two
+// prototype demo rounds; no per-table heuristic). Degenerate single-column
+// tables keep the plain-table rendering. Columns named here are per-record
+// classifiers -> prominent chips under the card title.
+const CAT_HEADERS = new Set([
+  'root entity', 'bounded context', 'aggregate', '所屬 aggregate',
+  'status', 'subdomain type', 'layer', 'severity', 'owner / team', 'producer'
+]);
+
+const CSS = `
+:root {
+  --bg:#f6f8f9; --surface:#ffffff; --frame:#eef2f4; --deep:#e7edef;
+  --ink:#1c2733; --soft:#5a6b79; --faint:#8a99a6; --line:#dbe4e9;
+  --accent:#0e6e63; --accent-soft:#e0f0ed; --accent-line:#b8dcd6;
+  --ok-fg:#1e6b34; --ok-bg:#e2f2e6; --ok-line:#bfe0c7;
+  --warn-fg:#8a5600; --warn-bg:#f7ecd7; --warn-line:#e8d5ac;
+  --del-fg:#9c3838; --del-bg:#f9e9e9; --del-line:#e8c4c4;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg:#10161c; --surface:#171f27; --frame:#0c1217; --deep:#0a0f14;
+    --ink:#d9e2ea; --soft:#93a4b1; --faint:#6b7c89; --line:#2a3641;
+    --accent:#4cc2b4; --accent-soft:#11302c; --accent-line:#1e4f48;
+    --ok-fg:#7bd397; --ok-bg:#142d1b; --ok-line:#235c33;
+    --warn-fg:#e2b269; --warn-bg:#2f2510; --warn-line:#59461d;
+    --del-fg:#e08f8f; --del-bg:#331a1a; --del-line:#5c2727;
+  }
+}
+* { box-sizing: border-box; }
+body {
+  background: var(--bg); color: var(--ink); margin: 0;
+  font-family: "Segoe UI","Noto Sans TC","Microsoft JhengHei","PingFang TC",
+    "Helvetica Neue",Arial,sans-serif;
+  font-size: 15.5px; line-height: 1.78; padding: 2.5rem 1.25rem 4rem;
+}
+main { max-width: 54rem; margin: 0 auto; }
+a { color: var(--accent); }
+code, pre { font-family: "Cascadia Code","Cascadia Mono",Consolas,monospace; }
+code {
+  background: var(--frame); border: 1px solid var(--line);
+  border-radius: 4px; padding: 0.05em 0.35em; font-size: 0.86em;
+}
+pre {
+  background: var(--deep); border: 1px solid var(--line); border-radius: 8px;
+  padding: 0.85rem 1.1rem; overflow-x: auto; font-size: 12.8px; line-height: 1.85;
+}
+pre code { background: none; border: none; padding: 0; font-size: inherit; }
+h1 { font-size: 25px; line-height: 1.35; margin: 0.2rem 0 1rem; }
+h2 {
+  font-size: 19px; margin: 2.2rem 0 0.6rem; padding-top: 1.2rem;
+  border-top: 1px solid var(--line);
+}
+h3 { font-size: 16.5px; margin: 1.6rem 0 0.4rem; }
+h4 { font-size: 15px; margin: 1.2rem 0 0.3rem; }
+blockquote {
+  margin: 0.8rem 0; padding: 0.55rem 1rem;
+  background: var(--accent-soft); border-left: 3px solid var(--accent);
+  border-radius: 0 8px 8px 0; color: var(--soft); font-size: 14px;
+}
+blockquote p { margin: 0.2rem 0; }
+hr { border: none; border-top: 1px solid var(--line); margin: 2rem 0; }
+.tblwrap { overflow-x: auto; }
+table { border-collapse: collapse; width: 100%; font-size: 14px; margin: 0.6rem 0 1rem; }
+th {
+  text-align: left; font-size: 11.5px; letter-spacing: 0.07em;
+  text-transform: uppercase; color: var(--soft); font-weight: 600;
+  padding: 0.45rem 0.9rem 0.45rem 0; border-bottom: 1.5px solid var(--line);
+  white-space: nowrap;
+}
+td { padding: 0.55rem 0.9rem 0.55rem 0; border-bottom: 1px solid var(--line); vertical-align: top; }
+tr:last-child td { border-bottom: none; }
+.badge {
+  display: inline-block; font-size: 11.5px; font-weight: 600; line-height: 1;
+  padding: 3px 9px; border-radius: 999px; border: 1px solid; white-space: nowrap;
+  vertical-align: 0.15em;
+}
+.badge.ok { color: var(--ok-fg); background: var(--ok-bg); border-color: var(--ok-line); }
+.badge.warn { color: var(--warn-fg); background: var(--warn-bg); border-color: var(--warn-line); }
+.badge.del { color: var(--del-fg); background: var(--del-bg); border-color: var(--del-line); }
+.badge.info, .badge.neutral { color: var(--accent); background: var(--accent-soft); border-color: var(--accent-line); }
+.chip {
+  display: inline-block; font-size: 11px; font-weight: 600; color: var(--soft);
+  background: var(--frame); border: 1px solid var(--line); border-radius: 999px;
+  padding: 2px 8px; vertical-align: 0.2em;
+}
+.cb {
+  display: inline-block; width: 14px; height: 14px; border-radius: 4px;
+  border: 1.5px solid var(--faint); vertical-align: -0.12em; margin-right: 0.15em;
+}
+.cb.on { background: var(--accent); border-color: var(--accent); position: relative; }
+.cb.on::after {
+  content: ""; position: absolute; left: 4px; top: 1px; width: 3px; height: 7px;
+  border: solid var(--bg); border-width: 0 2px 2px 0; transform: rotate(45deg);
+}
+.kw { color: var(--accent); font-weight: 700; }
+.cards {
+  display: grid; grid-template-columns: repeat(auto-fill, minmax(330px, 1fr));
+  gap: 0.9rem; align-items: start; margin: 0.8rem 0 1.4rem;
+}
+.card {
+  background: var(--surface); border: 1px solid var(--line);
+  border-radius: 10px; overflow: hidden;
+}
+.card-title {
+  background: var(--accent-soft); color: var(--accent);
+  border-bottom: 1px solid var(--accent-line);
+  font-size: 15px; font-weight: 700; padding: 0.55rem 0.95rem;
+}
+.card-chips { display: flex; flex-wrap: wrap; gap: 0.35rem; padding: 0.55rem 0.95rem 0; }
+.chip.cat {
+  color: var(--accent); background: transparent; border-color: var(--accent-line);
+  font-size: 11.5px; vertical-align: baseline;
+}
+.card-fields { padding: 0.15rem 0 0.55rem; }
+.fld { padding: 0.45rem 0.95rem 0.05rem; }
+.fld-k {
+  display: block; font-size: 11px; letter-spacing: 0.07em;
+  text-transform: uppercase; color: var(--accent); font-weight: 650;
+  margin-bottom: 0.05rem;
+}
+.fld-v { font-size: 14px; line-height: 1.7; overflow-wrap: anywhere; }
+.crumb { font-size: 12px; color: var(--faint); font-family: Consolas, monospace; margin: 0 0 1rem; }
+.crumb a { color: var(--faint); }
+.meta-card {
+  background: var(--frame); border: 1px solid var(--line); border-radius: 10px;
+  padding: 1rem 1.2rem; margin: 0 0 1.6rem;
+}
+.meta-title { display: flex; flex-wrap: wrap; align-items: center; gap: 0.7rem;
+  font-size: 18px; font-weight: 650; margin: 0 0 0.5rem; }
+.meta-grid { display: flex; flex-wrap: wrap; gap: 0.3rem 1.4rem; font-size: 12.8px; color: var(--soft); }
+.meta-grid .k { color: var(--faint); margin-right: 0.35em; }
+.foot {
+  margin-top: 3rem; padding-top: 0.9rem; border-top: 1px solid var(--line);
+  color: var(--faint); font-size: 12px; font-family: Consolas, monospace;
+}
+ul.tree, ul.tree ul { list-style: none; padding-left: 1.1rem; line-height: 2; }
+ul.tree { padding-left: 0; }
+ul.tree .dir { color: var(--faint); font-weight: 600; font-size: 13.5px; }
+ul.tree a { text-decoration: none; font-family: Consolas, monospace; font-size: 13.5px; }
+ul.tree a:hover { text-decoration: underline; }
+`;
+
+// ------------------------------------------------------------------ file IO
+// Windows MAX_PATH is 260 chars; dflow spec directories (SPEC-YYYYMMDD-NNN-slug)
+// plus long spec filenames overflow it easily. path.toNamespacedPath() opts
+// absolute paths into \\?\ extended-length form on win32 (no-op elsewhere).
+
+function ioPath(p) {
+  return path.toNamespacedPath(p);
+}
+
+async function readText(p) {
+  return fs.readFile(ioPath(p), 'utf8');
+}
+
+// First `bytes` of a file as utf8. The ownership-proof check only needs the
+// head (GENERATED_MARK sits on line 2 of every rendered page), and a forged
+// manifest may list an arbitrarily large foreign file — never slurp it whole.
+async function readHead(p, bytes) {
+  const handle = await fs.open(ioPath(p), 'r');
+  try {
+    const buf = Buffer.alloc(bytes);
+    const { bytesRead } = await handle.read(buf, 0, bytes, 0);
+    return buf.toString('utf8', 0, bytesRead);
+  } finally {
+    await handle.close();
+  }
+}
+
+async function writeText(p, text) {
+  await fs.mkdir(ioPath(path.dirname(p)), { recursive: true });
+  await fs.writeFile(ioPath(p), text, 'utf8');
+}
+
+// -------------------------------------------------------------- html helpers
+
+function escapeHtml(text) {
+  return String(text)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+// Only used on our own rendered fragments (for slugs and card classification),
+// so covering numeric references plus the five entities escapeHtml/marked emit
+// is sufficient — this is not a general-purpose HTML entity decoder.
+function unescapeHtml(text) {
+  return String(text)
+    .replace(/&#(\d+);/g, (m, dec) => String.fromCodePoint(Number(dec)))
+    .replace(/&#[xX]([0-9a-fA-F]+);/g, (m, hex) => String.fromCodePoint(parseInt(hex, 16)))
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
+function stripTags(fragment) {
+  return unescapeHtml(String(fragment).replace(/<[^>]+>/g, '')).trim();
+}
+
+// ------------------------------------------------------------ preprocessing
+
+// Parse a leading flat `key: value` frontmatter block, if present.
+function splitFrontmatter(text) {
+  if (!text.startsWith('---')) {
+    return { meta: {}, body: text };
+  }
+  const lines = text.split('\n');
+  const meta = {};
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === '---') {
+      return { meta, body: lines.slice(i + 1).join('\n') };
+    }
+    const colon = line.indexOf(':');
+    if (colon !== -1 && !line.trimStart().startsWith('#')) {
+      const key = line.slice(0, colon).trim();
+      const value = line.slice(colon + 1).replace(/\s+#.*$/, '').trim();
+      meta[key] = value;
+    }
+  }
+  return { meta: {}, body: text }; // no closing fence -> treat as content
+}
+
+// Rewrite AI-facing markers into human-facing spans before conversion.
+// (Task-list checkboxes need no preprocessing here: marked's GFM parser
+// tokenizes them natively and the checkbox renderer below restyles them.)
+function preprocess(mdText) {
+  // structural section markers: drop
+  let text = mdText.replace(/<!--\s*dflow:section[^>]*-->\s*\n?/g, '');
+
+  // phase change markers -> badges
+  text = text.replace(
+    /<!--\s*phase-(\d+)\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s*-->/g,
+    (match, phase, kind) => {
+      const [cls, zh] = PHASE_MARK_STYLE[kind];
+      return `<span class="badge ${cls}">phase-${phase} ${zh}</span>`;
+    }
+  );
+
+  // heading fill-timing comments -> chips
+  text = text.replace(
+    /^(#{1,6} .*?)\s*<!--\s*Fill timing:\s*(.*?)\s*-->/gm,
+    (match, headingText, timing) => `${headingText} <span class="chip">${escapeHtml(timing)}</span>`
+  );
+
+  return text;
+}
+
+// ------------------------------------------------------------ marked renderer
+
+const CHIP_SPAN = /<span class="chip[^"]*">[\s\S]*?<\/span>/g;
+const ANY_TAG = /<[^>]+>/g;
+
+// GitHub-style heading slug so `#anchor` links resolve in the HTML. CJK trap:
+// JavaScript \w is ASCII-only (unlike Python \w), so the character class must
+// use Unicode properties — [\p{L}\p{N}_\- ] with the u flag — or every 中文
+// heading would slug to the empty string.
+function headingSlug(innerHtml, seen) {
+  const text = String(innerHtml).replace(CHIP_SPAN, '').replace(ANY_TAG, '');
+  let slug = unescapeHtml(text).trim().toLowerCase();
+  slug = slug.replace(/[^\p{L}\p{N}_\- ]/gu, '');
+  slug = slug.replace(/ +/g, '-');
+  if (!slug) {
+    return null;
+  }
+  const n = seen.get(slug) || 0;
+  seen.set(slug, n + 1);
+  return n ? `${slug}-${n}` : slug;
+}
+
+function plainTableHtml(headerCells, rows) {
+  const head = headerCells.map((cell) => `<th>${cell}</th>`).join('');
+  const body = rows
+    .map((row) => `<tr>${row.map((cell) => `<td>${cell}</td>`).join('')}</tr>`)
+    .join('\n');
+  return `<div class="tblwrap"><table>\n<thead>\n<tr>${head}</tr>\n</thead>\n<tbody>\n${body}\n</tbody>\n</table></div>\n`;
+}
+
+// Card anatomy (prototype-converged shape): first column -> accent title bar;
+// classifier columns (CAT_HEADERS) -> chips under the title (status reuses the
+// pill styling); remaining columns -> stacked label+value fields, with in-cell
+// <br> line breaks preserved verbatim. Empty cells are omitted. Degenerate
+// single-column tables keep the plain-table rendering.
+function cardsHtml(headerCells, rows) {
+  const cards = rows.map((cells) => {
+    const plains = cells.map(stripTags);
+    const title = plains[0] ? cells[0] : '（未命名）';
+    const chips = [];
+    const fields = [];
+    for (let i = 1; i < headerCells.length; i++) {
+      const cell = cells[i] ?? '';
+      const text = plains[i] ?? '';
+      if (!text) {
+        continue;
+      }
+      const headerKey = stripTags(headerCells[i]).toLowerCase();
+      if (CAT_HEADERS.has(headerKey) && [...text].length <= 40) {
+        if (headerKey === 'status') {
+          const pill = STATUS_PILL[text] || 'neutral';
+          chips.push(`<span class="badge ${pill}">${cell}</span>`);
+        } else {
+          chips.push(`<span class="chip cat">${headerCells[i]}: ${cell}</span>`);
+        }
+      } else {
+        fields.push(
+          `<div class="fld"><span class="fld-k">${headerCells[i]}</span>` +
+          `<div class="fld-v">${cell}</div></div>`
+        );
+      }
+    }
+    const chipsHtml = chips.length ? `<div class="card-chips">${chips.join('')}</div>` : '';
+    return `<article class="card"><div class="card-title">${title}</div>` +
+      `${chipsHtml}<div class="card-fields">${fields.join('')}</div></article>`;
+  });
+  return `<div class="cards">${cards.join('')}</div>\n`;
+}
+
+// Per-file renderer overrides. `seen` carries the per-document heading slug
+// dedup state, so a fresh renderer is built for every file.
+function buildRenderer(seen) {
+  return {
+    heading(token) {
+      const inner = this.parser.parseInline(token.tokens);
+      const slug = headingSlug(inner, seen);
+      const id = slug ? ` id="${slug}"` : '';
+      return `<h${token.depth}${id}>${inner}</h${token.depth}>\n`;
+    },
+
+    // Point relative .md links at the mirrored .html files (anchors kept).
+    // Only scheme-less hrefs are candidates: a scheme-qualified link
+    // (https:, mailto:, file:, …) is not a mirrored tree file, and the
+    // proposal scopes rewriting to relative .md links (cold-eye gate G7).
+    link(token) {
+      const inner = this.parser.parseInline(token.tokens);
+      let href = token.href || '';
+      if (!/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(href) && !href.startsWith('#')) {
+        href = href.replace(/^(.*?)\.md(#.*)?$/, (m, base, anchor) => `${base}.html${anchor || ''}`);
+      }
+      const title = token.title ? ` title="${escapeHtml(token.title)}"` : '';
+      return `<a href="${escapeHtml(href)}"${title}>${inner}</a>`;
+    },
+
+    // Fenced code; gherkin/feature blocks get keyword highlighting.
+    code(token) {
+      const lang = String(token.lang || '').trim().split(/\s+/)[0];
+      let escaped = escapeHtml(token.text);
+      if (lang === 'gherkin' || lang === 'feature') {
+        escaped = escaped.replace(GHERKIN_KEYWORDS, '$1<span class="kw">$2</span>');
+      }
+      const cls = lang ? ` class="language-${escapeHtml(lang)}"` : '';
+      return `<pre><code${cls}>${escaped}\n</code></pre>\n`;
+    },
+
+    // Task-list checkboxes -> styled spans (same look as the prototype; the
+    // trailing space restores the gap marked v18 no longer inserts itself).
+    checkbox(token) {
+      return `<span class="cb${token.checked ? ' on' : ''}"></span> `;
+    },
+
+    // All multi-column tables render as one card per row; single-column
+    // (degenerate) and body-less tables keep plain-table rendering, wrapped
+    // for horizontal overflow.
+    table(token) {
+      const headerCells = token.header.map((cell) => this.parser.parseInline(cell.tokens));
+      const rows = token.rows.map((row) => row.map((cell) => this.parser.parseInline(cell.tokens)));
+      if (headerCells.length < 2 || rows.length === 0) {
+        return plainTableHtml(headerCells, rows);
+      }
+      return cardsHtml(headerCells, rows);
+    }
+  };
+}
+
+// ----------------------------------------------------------- postprocessing
+
+const CODE_MENTION = /<code>([^<>]+?\.md(?:#[^<>]*)?)<\/code>/g;
+
+function splitOnce(text, sep) {
+  const i = text.indexOf(sep);
+  return i === -1 ? [text, ''] : [text.slice(0, i), text.slice(i + 1)];
+}
+
+// Pure posix relpath (no cwd involvement, unlike path.posix.relative).
+function posixRelative(fromDir, toPath) {
+  const from = fromDir === '.' || fromDir === '' ? [] : fromDir.split('/');
+  const to = toPath.split('/');
+  let common = 0;
+  while (common < from.length && common < to.length && from[common] === to[common]) {
+    common += 1;
+  }
+  const up = new Array(from.length - common).fill('..');
+  return [...up, ...to.slice(common)].join('/') || '.';
+}
+
+// Link inline-code mentions of .md files to their rendered pages.
+//
+// Only mentions that resolve inside the rendered tree become links; anything
+// else (external files, ambiguous bare names) is left untouched. Mentions
+// inside <pre> blocks (directory trees, command examples) and existing <a>
+// links are skipped. Accepted forms: tree-relative or `dflow/specs/`-prefixed
+// paths, page-relative paths, and bare filenames (same directory first, then
+// a unique match anywhere in the tree).
+function autolinkCodeMentions(htmlText, relPosix, tree, basenames) {
+  const dir = path.posix.dirname(relPosix);
+  const curDir = dir === '.' ? '' : dir;
+
+  function resolveMention(pathPart) {
+    let p = unescapeHtml(pathPart);
+    if (p.startsWith('./')) {
+      p = p.slice(2);
+    }
+    const candidates = [];
+    if (p.includes('/')) {
+      for (const prefix of ['dflow/specs/', 'specs/']) {
+        if (p.startsWith(prefix)) {
+          candidates.push(p.slice(prefix.length));
+        }
+      }
+      candidates.push(p);
+      candidates.push(curDir ? path.posix.join(curDir, p) : p);
+    } else {
+      candidates.push(curDir ? path.posix.join(curDir, p) : p);
+      const hits = basenames.get(p) || [];
+      if (hits.length === 1) {
+        candidates.push(hits[0]);
+      }
+    }
+    for (const candidate of candidates) {
+      const normalized = path.posix.normalize(candidate);
+      if (tree.has(normalized)) {
+        return normalized;
+      }
+    }
+    return null;
+  }
+
+  const parts = htmlText.split(/(<pre>[\s\S]*?<\/pre>|<a\b[^>]*>[\s\S]*?<\/a>)/);
+  return parts
+    .map((part) => {
+      if (part.startsWith('<pre') || part.startsWith('<a')) {
+        return part;
+      }
+      return part.replace(CODE_MENTION, (mention, inner) => {
+        const [mentionPath, anchor] = splitOnce(inner, '#');
+        const target = resolveMention(mentionPath);
+        if (target === null) {
+          return mention;
+        }
+        let href = posixRelative(curDir || '.', `${target.slice(0, -'.md'.length)}.html`);
+        if (anchor) {
+          href += `#${anchor}`;
+        }
+        return `<a href="${escapeHtml(href)}">${mention}</a>`;
+      });
+    })
+    .join('');
+}
+
+function metaCardHtml(meta, fallbackTitle) {
+  const keys = Object.keys(meta);
+  if (keys.length === 0) {
+    return '';
+  }
+  const title = meta.title !== undefined ? meta.title : fallbackTitle;
+  const status = meta.status || '';
+  const pill = status
+    ? `<span class="badge ${STATUS_PILL[status] || 'neutral'}">${escapeHtml(status)}</span>`
+    : '';
+  const rows = keys
+    .filter((key) => key !== 'title' && key !== 'status' && meta[key])
+    .map((key) => `<span><span class="k">${escapeHtml(key)}</span>${escapeHtml(meta[key])}</span>`)
+    .join('');
+  return (
+    '<div class="meta-card">' +
+    `<p class="meta-title">${escapeHtml(title)} ${pill}</p>` +
+    `<div class="meta-grid">${rows}</div></div>`
+  );
+}
+
+// ----------------------------------------------------------------- rendering
+
+function pageHtml({ title, crumb, metaCard, body, footer }) {
+  return `<!DOCTYPE html>
+${GENERATED_MARK}
+<html lang="zh-Hant">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<style>${CSS}</style>
+</head>
+<body>
+<main>
+<p class="crumb">${crumb}</p>
+${metaCard}
+${body}
+<p class="foot">${footer}</p>
+</main>
+</body>
+</html>
+`;
+}
+
+async function renderFile({ MarkedCtor, srcRoot, outRoot, relPosix, stamp, tree, basenames }) {
+  const relHtml = `${relPosix.slice(0, -'.md'.length)}.html`;
+  const mdPath = path.join(srcRoot, ...relPosix.split('/'));
+  const outPath = path.join(outRoot, ...relHtml.split('/'));
+
+  const { meta, body } = splitFrontmatter(await readText(mdPath));
+  const seen = new Map();
+  const marked = new MarkedCtor({ gfm: true, renderer: buildRenderer(seen) });
+  let bodyHtml = marked.parse(preprocess(body));
+  bodyHtml = autolinkCodeMentions(bodyHtml, relPosix, tree, basenames);
+
+  const parts = relPosix.split('/');
+  const stem = parts[parts.length - 1].slice(0, -'.md'.length);
+  const indexHref = '../'.repeat(parts.length - 1) + 'index.html';
+  const crumb = `<a href="${indexHref}">specs</a> / ` + parts.map(escapeHtml).join(' / ');
+  const footer = `由 ${escapeHtml(relPosix)} 生成 · ${stamp} · 來源檔較新時請重新執行 dflow render`;
+
+  await writeText(outPath, pageHtml({
+    title: escapeHtml(meta.title !== undefined ? meta.title : stem),
+    crumb,
+    metaCard: metaCardHtml(meta, stem),
+    body: bodyHtml,
+    footer
+  }));
+  return relHtml;
+}
+
+// Nested <ul> file tree with links to the mirrored .html files.
+function buildTreeHtml(relFiles) {
+  const root = { dirs: new Map(), files: [] };
+  for (const rel of [...relFiles].sort()) {
+    const parts = rel.split('/');
+    let node = root;
+    for (const part of parts.slice(0, -1)) {
+      if (!node.dirs.has(part)) {
+        node.dirs.set(part, { dirs: new Map(), files: [] });
+      }
+      node = node.dirs.get(part);
+    }
+    node.files.push(rel);
+  }
+
+  function emit(node) {
+    let out = '<ul class="tree">';
+    for (const name of [...node.dirs.keys()].sort()) {
+      out += `<li><span class="dir">${escapeHtml(name)}/</span>${emit(node.dirs.get(name))}</li>`;
+    }
+    for (const rel of node.files) {
+      const href = `${rel.slice(0, -'.md'.length)}.html`;
+      const name = rel.split('/').pop();
+      out += `<li><a href="${escapeHtml(href)}">${escapeHtml(name)}</a></li>`;
+    }
+    return `${out}</ul>`;
+  }
+
+  return emit(root);
+}
+
+async function renderIndex({ outRoot, relFiles, title, stamp }) {
+  const body = `<h1>${escapeHtml(title)}</h1>${buildTreeHtml(relFiles)}`;
+  const footer = `共 ${relFiles.length} 份文件 · ${stamp} · 來源檔較新時請重新執行 dflow render`;
+  await writeText(path.join(outRoot, 'index.html'), pageHtml({
+    title: escapeHtml(title),
+    crumb: 'specs /',
+    metaCard: '',
+    body,
+    footer
+  }));
+  return 'index.html';
+}
+
+// ----------------------------------------------------- output-dir ownership
+
+// Validate a parsed-or-raw manifest. Returns { ok: true, files } or
+// { ok: false, reason }. Anything that fails here means "refuse to run and
+// delete nothing" — presence alone never grants ownership.
+function parseManifest(rawText) {
+  let data;
+  try {
+    data = JSON.parse(rawText);
+  } catch (error) {
+    return { ok: false, reason: 'not valid JSON' };
+  }
+  if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+    return { ok: false, reason: 'not a JSON object' };
+  }
+  if (!('dflow-render' in data)) {
+    return { ok: false, reason: 'missing "dflow-render" schema version field' };
+  }
+  if (data['dflow-render'] !== MANIFEST_VERSION) {
+    return { ok: false, reason: `unsupported "dflow-render" schema version: ${JSON.stringify(data['dflow-render'])}` };
+  }
+  if (!Array.isArray(data.files)) {
+    return { ok: false, reason: '"files" is not an array' };
+  }
+  for (const entry of data.files) {
+    if (typeof entry !== 'string' || entry === '') {
+      return { ok: false, reason: '"files" contains a non-string or empty entry' };
+    }
+    if (entry.includes('\\') || /^[A-Za-z]:/.test(entry) || entry.startsWith('/')) {
+      return { ok: false, reason: `"files" entry is not a relative posix path: ${entry}` };
+    }
+    const segments = entry.split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+      return { ok: false, reason: `"files" entry escapes the output directory: ${entry}` };
+    }
+  }
+  return { ok: true, files: data.files };
+}
+
+// Stale = previous ledger minus this run's outputs. Comparison is
+// case-insensitive: on case-insensitive filesystems (Windows, default macOS) a
+// case-only rename would otherwise delete the freshly written file through its
+// old-case name. On case-sensitive filesystems this can leave a stale
+// odd-case file behind — accepted residual, never-misdelete beats never-leak.
+// The manifest itself (and its tmp name) is never a deletion candidate.
+function staleEntries(oldFiles, newFiles) {
+  const current = new Set(newFiles.map((file) => file.toLowerCase()));
+  return oldFiles.filter(
+    (file) =>
+      file !== MANIFEST_NAME &&
+      file !== MANIFEST_TMP_NAME &&
+      !current.has(file.toLowerCase())
+  );
+}
+
+// Atomic manifest write (tmp + rename): a crash mid-write must never leave a
+// torn manifest, or the next run would refuse the directory it owns.
+async function writeManifest(outRoot, files) {
+  const body = `${JSON.stringify({ 'dflow-render': MANIFEST_VERSION, files }, null, 2)}\n`;
+  const tmpPath = path.join(outRoot, MANIFEST_TMP_NAME);
+  await fs.writeFile(ioPath(tmpPath), body, 'utf8');
+  await fs.rename(ioPath(tmpPath), ioPath(path.join(outRoot, MANIFEST_NAME)));
+}
+
+// Physical path for the overlap guard: resolve symlinks/junctions in the
+// deepest EXISTING ancestor (--out may not exist yet), then re-append the
+// not-yet-existing tail. Without this the guard is lexical only, and a
+// junction --out physically inside --src would pass it (impl review R1 F1).
+// Deliberately not ioPath()-wrapped: realpath must return the plain form the
+// guard compares, and these are user-supplied roots, not deep tree paths.
+async function realpathDeep(p) {
+  let base = p;
+  const tail = [];
+  for (;;) {
+    try {
+      const real = await fs.realpath(base);
+      return tail.length ? path.join(real, ...tail.reverse()) : real;
+    } catch (error) {
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') {
+        throw error;
+      }
+      const parent = path.dirname(base);
+      if (parent === base) {
+        return p; // nothing on this root exists — fall back to the lexical path
+      }
+      tail.push(path.basename(base));
+      base = parent;
+    }
+  }
+}
+
+// True when `parent` contains (or equals) `child`. path.relative handles
+// case-insensitive drives on win32.
+function pathContains(parent, child) {
+  const rel = path.relative(parent, child);
+  if (rel === '') {
+    return true;
+  }
+  if (path.isAbsolute(rel)) {
+    return false;
+  }
+  return rel.split(path.sep)[0] !== '..';
+}
+
+// Source→output projection collisions (cold-eye gate G3 F2): distinct
+// sources can map to one output path (a.md vs A.md under the case-insensitive
+// comparison the ledger already uses; a root index.md vs the generated file
+// tree), and a source directory literally named *.html can need the same
+// path a sibling source file produces. A root source directory named after
+// the manifest (or its tmp name) needs that reserved path as a directory,
+// which the ownership stamp and the end-of-run manifest write need as a file
+// (the source-side door of cold-eye gate G5 F1). Undetected, the run dies on
+// a raw EISDIR/ENOTDIR mid-write — after the ownership stamp — so this is
+// checked before any output mutation. Returns null, or a human-readable
+// description of the first collision found.
+function findProjectionCollision(relFiles) {
+  const toOut = (rel) => `${rel.slice(0, -'.md'.length)}.html`;
+  for (const rel of relFiles) {
+    // The ledger stores out-relative posix paths and parseManifest rejects
+    // anything else. A source name a POSIX filesystem allows but the schema
+    // cannot represent (a backslash inside a segment, a drive-letter-like
+    // prefix) would be written into this run's own manifest and lock the
+    // directory out at the next run's parse (cold-eye gate G7) — refuse
+    // before mutating anything instead.
+    if (rel.includes('\\') || /^[A-Za-z]:/.test(rel)) {
+      return `source path ${rel} cannot be represented in the render manifest`;
+    }
+  }
+  const byOut = new Map([['index.html', 'the generated file tree']]);
+  for (const rel of relFiles) {
+    const out = toOut(rel);
+    const prior = byOut.get(out.toLowerCase());
+    if (prior) {
+      return `${rel} and ${prior} would both produce ${out}`;
+    }
+    byOut.set(out.toLowerCase(), rel);
+  }
+  const neededDirs = new Map();
+  for (const rel of relFiles) {
+    const parts = toOut(rel).split('/');
+    for (let i = 1; i < parts.length; i++) {
+      const prefix = parts.slice(0, i).join('/');
+      if (!neededDirs.has(prefix.toLowerCase())) {
+        neededDirs.set(prefix.toLowerCase(), { prefix, source: rel });
+      }
+    }
+  }
+  const indexDir = neededDirs.get('index.html');
+  if (indexDir) {
+    return `${indexDir.source} needs ${indexDir.prefix}/ as a directory, but render generates index.html there`;
+  }
+  for (const reserved of [MANIFEST_NAME, MANIFEST_TMP_NAME]) {
+    const hit = neededDirs.get(reserved);
+    if (hit) {
+      return `${hit.source} needs ${hit.prefix}/ as a directory, but render reserves that name for its ownership manifest`;
+    }
+  }
+  for (const rel of relFiles) {
+    const out = toOut(rel);
+    const hit = neededDirs.get(out.toLowerCase());
+    if (hit) {
+      return `${rel} would produce ${out} as a file, but ${hit.source} needs ${hit.prefix}/ as a directory`;
+    }
+  }
+  return null;
+}
+
+// The owned output tree must contain only what render itself could have
+// created — real directories and regular files with a single name — before
+// render touches it. Writes, stale unlinks, and prunes below outRoot all
+// follow symlinks/junctions in the path (and fs.writeFile follows a link in
+// the final component), so a link planted inside the owned tree would
+// redirect them outside --out even though the root was realpath'd (cold-eye
+// gate G1 F1). A hardlinked regular file is the same escape without a link
+// dirent: it reports as an ordinary file, but the full-rebuild rewrite
+// truncates the shared inode, changing the file's other name outside --out
+// (cold-eye gate G2 F1). A real directory squatting on the reserved
+// manifest-tmp name at the tree root is the one all-regular-entries shape
+// render still cannot survive: it passes the type whitelist, but the
+// end-of-run manifest write opens that exact path as a file and would die
+// EISDIR only after outputs were written and stale files deleted (cold-eye
+// gate G5 F1) — so it is refused here, before any mutation. render never
+// creates any of these, nor special files, so all of them are foreign:
+// report and refuse rather than write or delete through them. Dirents
+// classify junctions as symlinks, and links are never recursed into, so a
+// link cycle cannot hang the walk. Returns { rel, what } for the first
+// unsafe entry (out-relative posix path + refusal phrase), or null for a
+// tree that is safe to rebuild.
+async function findUnsafeEntry(root) {
+  async function walk(dir, relParts) {
+    const entries = await fs.readdir(ioPath(dir), { withFileTypes: true });
+    for (const entry of entries) {
+      const rel = [...relParts, entry.name].join('/');
+      if (entry.isSymbolicLink()) {
+        return { rel, what: 'a symlink or junction' };
+      }
+      // Reserved-name comparison is case-insensitive like every ledger
+      // comparison: on case-insensitive filesystems a case variant collides
+      // with the same end-of-run write.
+      if (relParts.length === 0 && entry.isDirectory() && entry.name.toLowerCase() === MANIFEST_TMP_NAME) {
+        return { rel, what: 'a directory at the reserved manifest-tmp name' };
+      }
+      if (entry.isDirectory()) {
+        const found = await walk(path.join(dir, entry.name), [...relParts, entry.name]);
+        if (found) {
+          return found;
+        }
+      } else if (entry.isFile()) {
+        const stats = await fs.lstat(ioPath(path.join(dir, entry.name)));
+        if (stats.nlink > 1) {
+          return { rel, what: 'a regular file with multiple hard links' };
+        }
+      } else {
+        return { rel, what: 'not a regular file or directory' };
+      }
+    }
+    return null;
+  }
+  return walk(root, []);
+}
+
+// Mutation proof (cold-eye gate G3 F1): a valid manifest plus a link-free
+// tree still does not prove any particular file is render's own work — the
+// manifest is copyable and can list files render never wrote. Every existing
+// regular file at a path this run will write (planned mirror outputs) or may
+// delete (ledger entries) must carry GENERATED_MARK in its head, or the run
+// refuses before mutating anything. The in-content marker survives an
+// interrupted run whose deferred ledger rewrite never happened, so crash
+// convergence stays possible while foreign or hand-replaced files fail
+// closed. Directory/file mismatches at planned paths are refused here too —
+// they would otherwise die as a raw EISDIR/ENOTDIR mid-write, after
+// ownership state changed (the output-side sibling of G3 F2). Runs after
+// findUnsafeEntry, so every path probed here is a real file or directory.
+// Returns { rel, problem } for the first unproven target, or null.
+async function findUnprovenTarget({ outRoot, plannedRels, listedRels }) {
+  async function lstatRel(rel) {
+    try {
+      return await fs.lstat(ioPath(path.join(outRoot, ...rel.split('/'))));
+    } catch (error) {
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') {
+        throw error;
+      }
+      return null;
+    }
+  }
+  async function bearsMark(rel) {
+    const head = await readHead(path.join(outRoot, ...rel.split('/')), 4096);
+    return head.includes(GENERATED_MARK);
+  }
+
+  const neededDirs = new Set();
+  for (const rel of plannedRels) {
+    const parts = rel.split('/');
+    for (let i = 1; i < parts.length; i++) {
+      neededDirs.add(parts.slice(0, i).join('/'));
+    }
+  }
+  for (const rel of neededDirs) {
+    const stats = await lstatRel(rel);
+    if (stats && !stats.isDirectory()) {
+      return { rel, problem: 'is a file, but this run needs it as a directory' };
+    }
+  }
+
+  const proven = new Set();
+  for (const rel of plannedRels) {
+    const stats = await lstatRel(rel);
+    if (stats === null) {
+      continue;
+    }
+    if (stats.isDirectory()) {
+      return { rel, problem: 'is a directory, but this run writes a file there' };
+    }
+    if (!(await bearsMark(rel))) {
+      return { rel, problem: 'was not generated by dflow render' };
+    }
+    proven.add(rel.toLowerCase());
+  }
+
+  for (const rel of listedRels) {
+    if (proven.has(rel.toLowerCase())) {
+      continue;
+    }
+    const stats = await lstatRel(rel);
+    if (stats === null) {
+      continue;
+    }
+    if (stats.isDirectory()) {
+      return { rel, problem: 'is listed in the manifest but is a directory' };
+    }
+    if (!(await bearsMark(rel))) {
+      return { rel, problem: 'is listed in the manifest but was not generated by dflow render' };
+    }
+  }
+  return null;
+}
+
+async function collectMdFiles(srcRoot) {
+  const files = [];
+  async function walk(dir, relParts) {
+    const entries = await fs.readdir(ioPath(dir), { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        await walk(path.join(dir, entry.name), [...relParts, entry.name]);
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        files.push([...relParts, entry.name].join('/'));
+      }
+    }
+  }
+  await walk(srcRoot, []);
+  return files.sort();
+}
+
+// After stale deletion, prune directories that became empty (deepest first)
+// — but only parents of files THIS run actually unlinked. Those directories
+// held a marker-proven render output until a moment ago, so an empty
+// leftover is render's own mirror structure. A stale ledger entry whose file
+// was already gone proves nothing about the directory chain above it: the
+// ledger lists files, not directories, and an empty directory there may be
+// foreign (e.g. user-recreated at an old mirror path) — pruning on the
+// ENOENT path would delete a directory render cannot prove it made
+// (cold-eye gate G6 F1). fs.rmdir refuses non-empty directories, so this
+// can never remove a directory that still holds anything.
+async function pruneEmptyDirs(outRoot, unlinkedRels) {
+  const dirs = new Set();
+  for (const rel of unlinkedRels) {
+    let dir = path.posix.dirname(rel);
+    while (dir && dir !== '.') {
+      dirs.add(dir);
+      dir = path.posix.dirname(dir);
+    }
+  }
+  const deepestFirst = [...dirs].sort((a, b) => b.split('/').length - a.split('/').length);
+  for (const rel of deepestFirst) {
+    try {
+      await fs.rmdir(ioPath(path.join(outRoot, ...rel.split('/'))));
+    } catch (error) {
+      // Not empty or already gone — either way, leave it.
+    }
+  }
+}
+
+// ------------------------------------------------------------------ CLI face
+
+function parseRenderArgs(args) {
+  const options = { src: DEFAULT_SRC, out: DEFAULT_OUT, title: DEFAULT_TITLE };
+  const valueFlags = { '--src': 'src', '--out': 'out', '--title': 'title' };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const eq = arg.indexOf('=');
+    const name = eq === -1 ? arg : arg.slice(0, eq);
+    if (!Object.prototype.hasOwnProperty.call(valueFlags, name)) {
+      throw new Error(`Unsupported render option: ${arg}`);
+    }
+    let value;
+    if (eq !== -1) {
+      value = arg.slice(eq + 1);
+    } else {
+      i += 1;
+      value = i < args.length ? args[i] : '';
+    }
+    if (!value) {
+      throw new Error(`Missing value for render option: ${name}`);
+    }
+    options[valueFlags[name]] = value;
+  }
+  return options;
+}
+
+async function runRender({ cwd, args = [], stdout, stderr }) {
+  let options;
+  try {
+    options = parseRenderArgs(args);
+  } catch (error) {
+    stderr.write(`${error.message}\n`);
+    return 1;
+  }
+
+  let srcRoot = path.resolve(cwd, options.src);
+
+  let srcStat = null;
+  try {
+    srcStat = await fs.stat(ioPath(srcRoot));
+  } catch (error) {
+    if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') {
+      throw error;
+    }
+  }
+  if (!srcStat || !srcStat.isDirectory()) {
+    stderr.write(`src not found: ${srcRoot}\n`);
+    return 1;
+  }
+
+  // Physical paths from here on: both the overlap guard and every later write
+  // / cleanup must see through symlinks and junctions, or a linked --out
+  // pointing inside --src would bypass the guard (impl review R1 F1).
+  srcRoot = await realpathDeep(srcRoot);
+  const outRoot = await realpathDeep(path.resolve(cwd, options.out));
+
+  // Overlap guard, both directions: --out inside --src would pollute the specs
+  // tree (and get rescanned as source next run); --src inside --out would put
+  // the source tree inside the directory render owns and cleans.
+  if (pathContains(srcRoot, outRoot)) {
+    stderr.write(`--out must not be inside --src (or equal to it): ${outRoot}\n`);
+    return 1;
+  }
+  if (pathContains(outRoot, srcRoot)) {
+    stderr.write(`--src must not be inside --out: ${srcRoot}\n`);
+    return 1;
+  }
+
+  // Collect and sanity-check the source projection before touching --out at
+  // all: a colliding projection must refuse cleanly here, not die on a raw
+  // fs error mid-write after the ownership stamp (cold-eye gate G3 F2).
+  const relMdFiles = await collectMdFiles(srcRoot);
+  const collision = findProjectionCollision(relMdFiles);
+  if (collision) {
+    stderr.write(
+      `refusing to run: ${collision}; nothing was written.\n` +
+      'Rename the colliding source files, or render a narrower --src.\n'
+    );
+    return 1;
+  }
+
+  // Output-directory ownership (crash-safe order):
+  //   (0) first run (missing/empty --out): stamp ownership with a files:[]
+  //       manifest BEFORE writing anything else;
+  //   (1) render and write every output of this run;
+  //   (2) delete stale files (previous manifest minus this run — only files
+  //       the ledger listed, never anything else);
+  //   (3) rewrite the full manifest last.
+  // A crash at any point leaves a manifest in place (initial stamp or the
+  // previous complete one), so the next run recognizes its own directory and
+  // converges by re-rendering everything.
+  let previousFiles = [];
+  let outEntries = null;
+  try {
+    outEntries = await fs.readdir(ioPath(outRoot));
+  } catch (error) {
+    if (error.code === 'ENOTDIR') {
+      stderr.write(`out is not a directory (a file is in the way): ${outRoot}\n`);
+      return 1;
+    }
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+
+  if (outEntries === null) {
+    try {
+      await fs.mkdir(ioPath(outRoot), { recursive: true });
+    } catch (error) {
+      // Windows reports ENOENT (not POSIX's ENOTDIR) from the readdir above
+      // when an ancestor of --out is a file, so that case first surfaces here
+      // as mkdir ENOTDIR; EEXIST covers outRoot itself having become a file
+      // since the readdir (impl review R2 F1).
+      if (error.code !== 'ENOTDIR' && error.code !== 'EEXIST') {
+        throw error;
+      }
+      stderr.write(`out is not a directory (a file is in the way): ${outRoot}\n`);
+      return 1;
+    }
+    await writeManifest(outRoot, []);
+  } else {
+    // A leftover manifest tmp (crash residue of writeManifest's
+    // write-tmp-then-rename) never counts toward "someone else's directory",
+    // but the reserved NAME alone is no ownership proof (cold-eye gate G4
+    // F1): in a directory with no manifest, the tmp must prove itself — a
+    // single-name regular file whose content parses as a valid manifest — or
+    // the run refuses without touching it. It is never deleted up front in
+    // any branch; the end-of-run writeManifest overwrites the reserved name
+    // in place, and the unsafe-entry scan below vets a leftover tmp in an
+    // owned directory first — link / hardlink / special-file shapes and a
+    // directory squatting on the reserved name (cold-eye gate G5 F1) are all
+    // refused there before anything is written or deleted.
+    const meaningful = outEntries.filter((name) => name !== MANIFEST_TMP_NAME);
+    if (meaningful.length === 0) {
+      if (outEntries.includes(MANIFEST_TMP_NAME)) {
+        const tmpPath = path.join(outRoot, MANIFEST_TMP_NAME);
+        let tmpStats = null;
+        try {
+          tmpStats = await fs.lstat(ioPath(tmpPath));
+        } catch (error) {
+          if (error.code !== 'ENOENT') {
+            throw error;
+          }
+        }
+        // Size cap before reading: a genuine stamp residue is a small JSON
+        // file; never slurp an arbitrarily large foreign file to disprove it.
+        const provenOurs =
+          tmpStats !== null &&
+          tmpStats.isFile() &&
+          tmpStats.nlink === 1 &&
+          tmpStats.size <= 64 * 1024 * 1024 &&
+          parseManifest(await readText(tmpPath)).ok;
+        if (tmpStats !== null && !provenOurs) {
+          stderr.write(
+            `refusing to run: ${MANIFEST_TMP_NAME} in ${outRoot} cannot be proven to be dflow render's own crash residue; your files were not touched.\n` +
+            'Remove it yourself, or pick a different --out.\n'
+          );
+          return 1;
+        }
+      }
+      await writeManifest(outRoot, []);
+    } else if (!meaningful.includes(MANIFEST_NAME)) {
+      stderr.write(
+        `refusing to write into non-empty directory without ${MANIFEST_NAME}: ${outRoot}\n` +
+        'dflow render owns its output directory; pick a new or empty --out.\n'
+      );
+      return 1;
+    } else {
+      // lstat before reading: a directory (or link) squatting on the exact
+      // manifest name would otherwise surface as a raw EISDIR from the read
+      // — and a planted link would be read through before the tree scan
+      // below could refuse it.
+      const manifestStats = await fs.lstat(ioPath(path.join(outRoot, MANIFEST_NAME)));
+      if (!manifestStats.isFile()) {
+        stderr.write(
+          `refusing to run: ${MANIFEST_NAME} in ${outRoot} is not a regular file; no files were deleted.\n` +
+          'Remove the output directory yourself, or pick a different --out.\n'
+        );
+        return 1;
+      }
+      const parsed = parseManifest(await readText(path.join(outRoot, MANIFEST_NAME)));
+      if (!parsed.ok) {
+        stderr.write(
+          `refusing to run: ${MANIFEST_NAME} in ${outRoot} is invalid (${parsed.reason}); no files were deleted.\n` +
+          'Remove the output directory yourself, or pick a different --out.\n'
+        );
+        return 1;
+      }
+      previousFiles = parsed.files;
+    }
+  }
+
+  // Ownership alone is not enough: every write and delete below outRoot
+  // follows links in the path, and rewriting a hardlinked file writes its
+  // shared inode — the accepted tree must hold nothing render could not have
+  // created itself.
+  const unsafe = await findUnsafeEntry(outRoot);
+  if (unsafe) {
+    stderr.write(
+      `refusing to run: ${unsafe.rel} inside the output directory is ${unsafe.what}; your files were not touched.\n` +
+      'dflow render only creates regular files and directories, and will not write or delete through anything else — remove it, or pick a different --out.\n'
+    );
+    return 1;
+  }
+
+  // Ownership (manifest) + entry types (scan) still do not prove a given
+  // file is render's own work; the generated marker inside the file does.
+  const plannedRels = [...relMdFiles.map((rel) => `${rel.slice(0, -'.md'.length)}.html`), 'index.html'];
+  const unproven = await findUnprovenTarget({ outRoot, plannedRels, listedRels: previousFiles });
+  if (unproven) {
+    stderr.write(
+      `refusing to run: ${unproven.rel} in the output directory ${unproven.problem}; your files were not touched.\n` +
+      'Remove it (and any manifest entry naming it), or pick a different --out.\n'
+    );
+    return 1;
+  }
+
+  const tree = new Set(relMdFiles);
+  const basenames = new Map();
+  for (const rel of relMdFiles) {
+    const name = rel.split('/').pop();
+    if (!basenames.has(name)) {
+      basenames.set(name, []);
+    }
+    basenames.get(name).push(rel);
+  }
+
+  // marked is ESM-only: dynamic import is the one loading path that works on
+  // every Node >=22.0.0 from CommonJS. Do not convert this to a require() call.
+  const { Marked } = await import('marked');
+
+  const stamp = nowStamp();
+  const written = [];
+  for (const relPosix of relMdFiles) {
+    written.push(await renderFile({ MarkedCtor: Marked, srcRoot, outRoot, relPosix, stamp, tree, basenames }));
+  }
+  written.push(await renderIndex({ outRoot, relFiles: relMdFiles, title: options.title, stamp }));
+
+  const stale = staleEntries(previousFiles, written);
+  const unlinked = [];
+  for (const rel of stale) {
+    try {
+      await fs.unlink(ioPath(path.join(outRoot, ...rel.split('/'))));
+      unlinked.push(rel);
+    } catch (error) {
+      // ENOENT: already gone. ENOTDIR: the listed path's parent chain no
+      // longer holds directories, so no file of ours can exist there.
+      // Either way this run deleted nothing, so the entry earns no
+      // empty-parent pruning below.
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') {
+        throw error;
+      }
+    }
+  }
+  await pruneEmptyDirs(outRoot, unlinked);
+
+  await writeManifest(outRoot, written);
+
+  stdout.write(`rendered ${relMdFiles.length} md files -> ${outRoot}\n`);
+  stdout.write(`open: ${path.join(outRoot, 'index.html')}\n`);
+  return 0;
+}
+
+function nowStamp() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+module.exports = {
+  runRender,
+  // Exported for tests: the data-safety core (manifest schema refusals, the
+  // never-delete-unlisted stale diff, the unsafe-entry output scan, the
+  // marker-based mutation proof, projection-collision detection) and the
+  // overlap guard are tested directly in addition to the end-to-end CLI tests.
+  parseManifest,
+  staleEntries,
+  pathContains,
+  findUnsafeEntry,
+  findUnprovenTarget,
+  findProjectionCollision,
+  GENERATED_MARK,
+  splitFrontmatter,
+  headingSlug
+};