pentimento 0.3.0

package/dist/render.js

@@ -0,0 +1,433 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import MarkdownIt from 'markdown-it';
+import { parse as parseYaml } from 'yaml';
+import { loadDoc, readMeta, readRevision, slugify, splitRaw } from './core.js';
+import { renderDiffHtml } from './semdiff.js';
+const ASSETS = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../assets');
+const md = new MarkdownIt({ html: true, linkify: false, typographer: false });
+// reader comments are untrusted (they arrive over HTTP via the viewer) — html:false makes
+// markdown-it escape raw HTML and reject javascript: links, unlike the regex sanitize()
+const mdUntrusted = new MarkdownIt({ html: false, linkify: false, typographer: false });
+// every table scrolls inside its own container; the page never scrolls sideways
+md.renderer.rules.table_open = () => '<div class="tablewrap"><table>\n';
+md.renderer.rules.table_close = () => '</table></div>\n';
+const defaultFence = md.renderer.rules.fence;
+md.renderer.rules.fence = (tokens, idx, options, env, self) => {
+    const rendered = defaultFence(tokens, idx, options, env, self);
+    return rendered.replace(/^<pre>/, '<pre class="block">');
+};
+const escapeHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/** Strip active content from agent-supplied HTML/SVG (defense in depth; not a full sanitizer). */
+const sanitize = (html) => html
+    .replace(/<\s*(script|iframe|object|embed|foreignObject)\b[\s\S]*?<\s*\/\s*\1\s*>/gi, '')
+    .replace(/<\s*(script|iframe|object|embed|foreignObject)\b[^>]*\/?>/gi, '')
+    .replace(/\son[a-z]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, '')
+    .replace(/(href|src|xlink:href)\s*=\s*(["'])\s*javascript:[^"']*\2/gi, '$1=$2#$2');
+const plainText = (s) => s.replace(/[`*_]/g, '');
+const parseAttrs = (s) => {
+    const attrs = {};
+    const re = /([\w-]+)=(?:"([^"]*)"|(\S+))/g;
+    let m;
+    while ((m = re.exec(s)))
+        attrs[m[1]] = m[2] ?? m[3];
+    return attrs;
+};
+const CALLOUT_LABELS = {
+    decision: 'Decision', info: 'Info', warn: 'Warning', risk: 'Risk',
+};
+const renderCallout = (content, attrs, kind) => {
+    const label = CALLOUT_LABELS[kind] ?? 'Note';
+    const id = attrs.id ? ` id="${escapeHtml(attrs.id)}"` : '';
+    return `<div class="callout ${kind}"${id}><span class="label">${label}</span>${md.render(content)}</div>`;
+};
+const renderVerdict = (content) => {
+    const cells = content
+        .split('\n')
+        .map((l) => /^-\s+(.+?)\s+::\s+(.+)$/.exec(l.trim()))
+        .filter((m) => m !== null)
+        .map(([, q, a]) => `<div><span class="q">${md.renderInline(q)}</span><span class="a">${md.renderInline(a)}</span></div>`);
+    return `<div class="verdict">${cells.join('')}</div>`;
+};
+const SEV_CLASS = { CRIT: 'c', HIGH: 'h', MED: 'm', LOW: 'm' };
+const renderFindings = (content) => {
+    const open = [];
+    const collapsed = [];
+    let collapseLabel = null;
+    for (const line of content.split('\n')) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        const c = /^@collapse\s+(.+)$/.exec(t);
+        if (c) {
+            collapseLabel = c[1];
+            continue;
+        }
+        const m = /^-\s+(CRIT|HIGH|MED|LOW)\s+::\s+(.+)$/.exec(t);
+        if (!m)
+            continue;
+        const html = `<div class="finding"><span class="sev ${SEV_CLASS[m[1]]}">${m[1]}</span><div>${md.renderInline(m[2])}</div></div>`;
+        (collapseLabel ? collapsed : open).push(html);
+    }
+    const details = collapseLabel
+        ? `<details><summary>${escapeHtml(collapseLabel)}</summary>${collapsed.join('\n')}</details>`
+        : '';
+    return `<div>${open.join('\n')}</div>${details}`;
+};
+const renderTimeline = (content) => {
+    const items = [];
+    let current = [];
+    for (const line of content.split('\n')) {
+        if (/^\d+\.\s+/.test(line.trim()) && current.length) {
+            items.push(current.join(' '));
+            current = [];
+        }
+        if (line.trim())
+            current.push(line.trim().replace(/^\d+\.\s+/, ''));
+    }
+    if (current.length)
+        items.push(current.join(' '));
+    const lis = items.map((item, i) => {
+        const m = /^\*\*(.+?)\*\*(?:\s+\[(next|later|done)\])?(?:\s+—\s+([\s\S]+))?$/.exec(item);
+        const title = m ? md.renderInline(m[1]) : md.renderInline(item);
+        const pill = m?.[2] ? ` <span class="pill${m[2] === 'next' ? '' : ` ${m[2]}`}">${m[2]}</span>` : '';
+        const desc = m?.[3] ? `<p>${md.renderInline(m[3])}</p>` : '';
+        return `<li><span class="ph">${i + 1}</span><div><h3>${title}${pill}</h3>${desc}</div></li>`;
+    });
+    return `<ol class="timeline">${lis.join('\n')}</ol>`;
+};
+/** Content is a unified diff (optionally fenced); rendered as responsive side-by-side panes. */
+const renderDiff = (content, attrs) => {
+    let lines = content.split('\n');
+    if (lines[0]?.startsWith('```'))
+        lines = lines.slice(1, lines.lastIndexOf('```'));
+    const before = [];
+    const after = [];
+    for (const line of lines) {
+        if (line.startsWith('-'))
+            before.push(`<span class="del">${escapeHtml(line.slice(1))}</span>`);
+        else if (line.startsWith('+'))
+            after.push(`<span class="add">${escapeHtml(line.slice(1))}</span>`);
+        else {
+            const ctx = `<span>${escapeHtml(line.replace(/^ /, ''))}</span>`;
+            before.push(ctx);
+            after.push(ctx);
+        }
+    }
+    const head = attrs.head ? `<div class="diff-head">${escapeHtml(attrs.head)}</div>` : '';
+    return `<div class="diff">${head}<div class="diff-cols">` +
+        `<div class="diff-pane"><div class="pane-label">Before</div><pre>${before.join('')}</pre></div>` +
+        `<div class="diff-pane"><div class="pane-label">After</div><pre>${after.join('')}</pre></div>` +
+        `</div></div>`;
+};
+const renderFigure = (content, attrs) => {
+    const aria = attrs.aria ? ` role="img" aria-label="${escapeHtml(attrs.aria)}"` : '';
+    return `<div class="diagram"${aria}>${sanitize(content)}</div>`;
+};
+const HANDLERS = {
+    callout: renderCallout,
+    verdict: renderVerdict,
+    findings: renderFindings,
+    timeline: renderTimeline,
+    diff: renderDiff,
+    figure: renderFigure,
+    compare: (content) => md.render(content),
+    files: (content) => md.render(content),
+};
+const HEADING_META_RE = /\s*<!--\s*([^>]*?)\s*-->\s*$/;
+const parseHeadingMeta = (comment) => {
+    const out = {};
+    for (const part of comment.split(';')) {
+        const m = /^\s*(id|eyebrow)\s*:\s*(.+?)\s*$/.exec(part);
+        if (m)
+            out[m[1]] = m[2];
+    }
+    return out;
+};
+const prepare = (body) => {
+    const swapped = body.replace(/\{dot:([\w-]+)\}/g, '<span class="dot dot-$1"></span>');
+    const lines = swapped.split('\n');
+    const blocks = [];
+    const headings = [];
+    let title = '';
+    const standfirstLines = [];
+    const out = [];
+    let inFence = false;
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (/^```/.test(line.trim()))
+            inFence = !inFence;
+        if (!inFence) {
+            if (!title && /^#\s+/.test(line)) {
+                title = line.replace(/^#\s+/, '').trim();
+                i++;
+                while (i < lines.length && (lines[i].trim() === '' || lines[i].startsWith('>'))) {
+                    if (lines[i].startsWith('>'))
+                        standfirstLines.push(lines[i].replace(/^>\s?/, ''));
+                    i++;
+                }
+                continue;
+            }
+            const open = /^:::\s*([\w-]+)\s*(.*)$/.exec(line);
+            if (open && HANDLERS[open[1]]) {
+                const contentLines = [];
+                i++;
+                let innerFence = false;
+                while (i < lines.length) {
+                    if (/^```/.test(lines[i].trim()))
+                        innerFence = !innerFence;
+                    if (!innerFence && /^:::\s*$/.test(lines[i]))
+                        break;
+                    contentLines.push(lines[i]);
+                    i++;
+                }
+                i++; // consume closing :::
+                // a leading bare word is the variant (e.g. `::: callout decision`), the rest is k=v attrs
+                let rest = open[2];
+                let variant = open[1];
+                const vm = /^([\w-]+)\b\s*/.exec(rest);
+                if (vm && !rest.startsWith(`${vm[1]}=`)) {
+                    variant = vm[1];
+                    rest = rest.slice(vm[0].length);
+                }
+                blocks.push(HANDLERS[open[1]](contentLines.join('\n').trim(), parseAttrs(rest), variant));
+                out.push('', `<!--PENTIMENTO-BLOCK-${blocks.length - 1}-->`, '');
+                continue;
+            }
+            const h = /^(#{2,3})\s+(.+)$/.exec(line);
+            if (h) {
+                let text = h[2];
+                let meta = {};
+                const c = HEADING_META_RE.exec(text);
+                if (c) {
+                    meta = parseHeadingMeta(c[1]);
+                    text = text.replace(HEADING_META_RE, '');
+                }
+                const info = {
+                    level: h[1].length,
+                    title: text.trim(),
+                    id: meta.id ?? slugify(text),
+                    eyebrow: meta.eyebrow,
+                };
+                headings.push(info);
+                out.push(`<!--PENTIMENTO-H-${headings.length - 1}-->`);
+                i++;
+                continue;
+            }
+        }
+        out.push(line);
+        i++;
+    }
+    // split into sections at h2 markers
+    const sections = [];
+    const preamble = [];
+    let bucket = preamble;
+    for (const line of out) {
+        const hm = /^<!--PENTIMENTO-H-(\d+)-->$/.exec(line);
+        if (hm && headings[Number(hm[1])].level === 2) {
+            sections.push({ heading: headings[Number(hm[1])], bodyLines: [] });
+            bucket = sections[sections.length - 1].bodyLines;
+            continue;
+        }
+        bucket.push(line);
+    }
+    return { title, standfirst: standfirstLines.join(' ').trim(), sections, preamble, blocks, headings };
+};
+const anchor = (id) => `<a class="anch" href="#${id}" aria-label="Link to this section">#</a>`;
+const renderSectionBody = (prepared, bodyLines) => {
+    let html = md.render(bodyLines.join('\n'));
+    html = html.replace(/<!--PENTIMENTO-H-(\d+)-->/g, (_, n) => {
+        const h = prepared.headings[Number(n)];
+        return `<h3 id="${h.id}">${md.renderInline(h.title)}${anchor(h.id)}</h3>`;
+    });
+    html = html.replace(/<!--PENTIMENTO-BLOCK-(\d+)-->/g, (_, n) => prepared.blocks[Number(n)]);
+    return sanitize(html);
+};
+const ARCHETYPES = {
+    implementation: 'Implementation plan',
+    brainstorm: 'Brainstorm / exploration',
+    audit: 'Audit / review',
+    'design-doc': 'Design doc · PRD',
+};
+const PALETTES = [
+    ['verdigris', 'Verdigris'],
+    ['mist', 'Mist'],
+    ['iris', 'Iris'],
+];
+const DEFAULT_PALETTE = 'iris';
+const chrome = (doc, meta, prepared, opts) => {
+    const css = fs.readFileSync(path.join(ASSETS, 'theme.css'), 'utf8');
+    const js = fs.readFileSync(path.join(ASSETS, 'chrome.js'), 'utf8');
+    const archetype = String(doc.frontmatter['Archetype'] ?? 'design-doc');
+    const badge = ARCHETYPES[archetype] ?? archetype;
+    const rev = String(doc.frontmatter['Current Revision'] ?? '—');
+    const latest = meta.revisions[meta.revisions.length - 1];
+    const date = latest ? latest.created_at.slice(0, 10) : '';
+    const pathLabel = doc.canonicalPath.split(path.sep).slice(-3).join('/');
+    const historyRel = String(doc.frontmatter['History Folder'] ?? `.history/${doc.name}`);
+    const fmPalette = String(doc.frontmatter['Palette'] ?? '');
+    const defaultPalette = PALETTES.some(([k]) => k === fmPalette) ? fmPalette : DEFAULT_PALETTE;
+    const paletteBtns = PALETTES.map(([key, label]) => `<button class="pbtn" type="button" data-p="${key}" aria-pressed="${key === defaultPalette}">` +
+        `<span class="dot dot-${key}"></span>${label}</button>`).join('\n      ');
+    const inline = (s) => sanitize(md.renderInline(s));
+    const evolution = [...meta.revisions].reverse().slice(0, 4).map((r) => `<div class="evolution"><span class="rev">${escapeHtml(r.id)}</span>` +
+        `<span class="what"><strong>${inline(r.summary)}</strong>` +
+        `${r.why ? ` — ${inline(r.why)}` : ''}</span></div>`).join('\n  ');
+    const openComments = meta.comments.filter((c) => c.status === 'open');
+    const commentsPanel = openComments.length
+        ? `\n  <details class="comments" open><summary>${openComments.length} open comment${openComments.length > 1 ? 's' : ''}</summary>${openComments.map((c) => `<div class="vcomment" data-cid="${escapeHtml(c.id)}">` +
+            `${c.anchor ? `<a class="vc-anchor" href="${escapeHtml(c.anchor)}">${escapeHtml(c.anchor)}</a> ` : ''}` +
+            `${c.quote ? `<blockquote>${escapeHtml(c.quote)}</blockquote>` : ''}` +
+            `<p>${mdUntrusted.renderInline(c.text)}</p>` +
+            `<span class="vc-meta">${escapeHtml(c.author)} · ${escapeHtml(String(c.created_at).slice(0, 10))}</span></div>`).join('')}</details>`
+        : '';
+    // what changed since the previous revision — so a reader never has to ask the agent
+    let changes = '';
+    if (meta.revisions.length >= 2) {
+        const prev = meta.revisions[meta.revisions.length - 2];
+        const latest = meta.revisions[meta.revisions.length - 1];
+        const prevFile = path.join(doc.historyDir, `${prev.id}.md`);
+        if (fs.existsSync(prevFile)) {
+            const prevBody = splitRaw(fs.readFileSync(prevFile, 'utf8')).body;
+            changes = `\n  <details class="changes"><summary>What changed in ${escapeHtml(latest.id)} (vs ${escapeHtml(prev.id)})</summary><div class="rdiff">${renderDiffHtml(prevBody, doc.body)}</div></details>`;
+        }
+    }
+    const toc = prepared.sections.map((s, i) => `<li><a href="#${s.heading.id}"><span class="n">${String(i + 1).padStart(2, '0')}</span>` +
+        `${escapeHtml(plainText(s.heading.title))}</a></li>`).join('\n      ');
+    const sections = prepared.sections.map((s) => {
+        const eyebrow = s.heading.eyebrow ? `<span class="eyebrow">${escapeHtml(s.heading.eyebrow)}</span>\n  ` : '';
+        return `<section>\n  ${eyebrow}<h2 id="${s.heading.id}">${md.renderInline(s.heading.title)}${anchor(s.heading.id)}</h2>\n` +
+            renderSectionBody(prepared, s.bodyLines) + '\n</section>';
+    }).join('\n\n');
+    const preambleHtml = prepared.preamble.join('\n').trim()
+        ? renderSectionBody(prepared, prepared.preamble)
+        : '';
+    const title = escapeHtml(plainText(prepared.title));
+    // set the palette before first paint; localStorage (user's explicit pick) wins over the doc default
+    const paletteInit = `<script>(()=>{let p=null;try{p=localStorage.getItem('pentimento-palette')}catch(e){}p=p||'${defaultPalette}';if(p!=='verdigris')document.documentElement.dataset.palette=p})()</script>`;
+    const body = `${paletteInit}
+
+<div class="wrap">
+<header class="doc">
+  <div class="meta-row">
+    <span class="badge badge-${escapeHtml(archetype)}">${escapeHtml(badge)}</span>
+    <span class="chip">${escapeHtml(rev)}</span>
+    ${date ? `<span class="chip">${escapeHtml(date)}</span>\n    ` : ''}<span class="chip">${escapeHtml(pathLabel)}</span>
+    <div class="palettes" role="group" aria-label="Color theme">
+      ${paletteBtns}
+    </div>
+  </div>
+  <h1>${inline(prepared.title)}</h1>
+  ${prepared.standfirst ? `<p class="standfirst">${inline(prepared.standfirst)}</p>` : ''}
+  ${evolution}${changes}${commentsPanel}
+</header>
+
+<details class="toc" open>
+  <summary>Contents</summary>
+  <nav aria-label="Contents">
+    <ol>
+      ${toc}
+    </ol>
+  </nav>
+</details>
+
+<main>
+${preambleHtml}
+${sections}
+</main>
+
+<footer class="doc">
+  Source: <code>${escapeHtml(pathLabel)}</code> · history: <code>${escapeHtml(historyRel)}/</code> (${escapeHtml(rev)}) · Rendered by <code>pentimento render</code>.
+</footer>
+</div>
+<script>
+${js}</script>
+`;
+    if (opts.artifact)
+        return `<title>${title}</title>\n<style>\n${css}</style>\n\n${body}`;
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<style>
+${css}</style>
+</head>
+<body>
+${body}</body>
+</html>
+`;
+};
+export const render = (docPath, opts = {}) => {
+    const doc = loadDoc(docPath);
+    const meta = readMeta(doc.historyDir);
+    return chrome(doc, meta, prepare(doc.body), opts);
+};
+export const renderToFile = (docPath, outPath, opts = {}) => {
+    const doc = loadDoc(docPath);
+    const out = outPath
+        ? path.resolve(outPath)
+        : path.join(path.dirname(doc.canonicalPath), `${doc.name.toLowerCase()}.html`);
+    fs.writeFileSync(out, render(docPath, opts), 'utf8');
+    return out;
+};
+/** Render the document as it stood at a given revision (evolution strip trimmed to that point). */
+export const renderRevisionHtml = (docPath, rev, opts = {}) => {
+    const doc = loadDoc(docPath);
+    const raw = readRevision(docPath, rev);
+    const { frontmatterRaw, body } = splitRaw(raw);
+    let frontmatter = { ...doc.frontmatter, 'Current Revision': rev };
+    if (frontmatterRaw) {
+        try {
+            frontmatter = { ...(parseYaml(frontmatterRaw) ?? {}), 'Current Revision': rev };
+        }
+        catch { /* fall back to the canonical's frontmatter */ }
+    }
+    const meta = readMeta(doc.historyDir);
+    const idx = meta.revisions.findIndex((r) => r.id === rev);
+    const trimmed = {
+        revisions: idx >= 0 ? meta.revisions.slice(0, idx + 1) : meta.revisions,
+        comments: meta.comments,
+    };
+    const revDoc = { ...doc, raw, body, frontmatter };
+    return chrome(revDoc, trimmed, prepare(body), opts);
+};
+/** Standalone page showing the changes between two revisions ('canonical' = current file). */
+export const renderDiffPage = (docPath, a, b) => {
+    const doc = loadDoc(docPath);
+    const css = fs.readFileSync(path.join(ASSETS, 'theme.css'), 'utf8');
+    const bodyOf = (rev) => rev === 'canonical' ? doc.body : splitRaw(readRevision(docPath, rev)).body;
+    const rdiff = renderDiffHtml(bodyOf(a), bodyOf(b));
+    const title = `${doc.name}: ${a} → ${b}`;
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>
+${css}</style>
+</head>
+<body>
+<div class="wrap">
+<header class="doc">
+  <div class="meta-row">
+    <span class="badge">Changes</span>
+    <span class="chip">${escapeHtml(a)} → ${escapeHtml(b)}</span>
+    <span class="chip">${escapeHtml(doc.name)}</span>
+  </div>
+  <h1>${escapeHtml(doc.name)}</h1>
+  <p class="standfirst">What changed between ${escapeHtml(a)} and ${escapeHtml(b)}.</p>
+</header>
+<main>
+<div class="rdiff" style="margin-top:2rem">${rdiff}</div>
+</main>
+<footer class="doc">Rendered by <code>pentimento diff --html</code>.</footer>
+</div>
+</body>
+</html>
+`;
+};

package/dist/semdiff.js

@@ -0,0 +1,125 @@
+import { diffArrays, diffWords } from 'diff';
+const escapeHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/** Split a markdown body into diffable blocks; fences and ::: containers stay atomic. */
+export const splitBlocks = (body) => {
+    const lines = body.split('\n');
+    const blocks = [];
+    let cur = [];
+    let inFence = false;
+    let inContainer = false;
+    const flush = () => {
+        const t = cur.join('\n').trim();
+        if (t)
+            blocks.push(t);
+        cur = [];
+    };
+    for (const line of lines) {
+        const t = line.trim();
+        if (/^```/.test(t)) {
+            inFence = !inFence;
+            cur.push(line);
+            if (!inFence && !inContainer)
+                flush();
+            continue;
+        }
+        if (!inFence) {
+            if (!inContainer && /^:::\s*\w/.test(t)) {
+                flush();
+                inContainer = true;
+                cur.push(line);
+                continue;
+            }
+            if (inContainer && /^:::$/.test(t)) {
+                cur.push(line);
+                inContainer = false;
+                flush();
+                continue;
+            }
+            if (!inContainer && t === '') {
+                flush();
+                continue;
+            }
+        }
+        cur.push(line);
+    }
+    flush();
+    return blocks;
+};
+export const diffBlocks = (oldBody, newBody) => {
+    const parts = diffArrays(splitBlocks(oldBody), splitBlocks(newBody));
+    const out = [];
+    let i = 0;
+    while (i < parts.length) {
+        const p = parts[i];
+        const next = parts[i + 1];
+        if (p.removed && next?.added) {
+            // a replace hunk: pair blocks positionally for word-level diffing
+            const paired = Math.min(p.value.length, next.value.length);
+            for (let k = 0; k < paired; k++)
+                out.push({ type: 'change', old: p.value[k], new: next.value[k] });
+            for (let k = paired; k < p.value.length; k++)
+                out.push({ type: 'del', old: p.value[k] });
+            for (let k = paired; k < next.value.length; k++)
+                out.push({ type: 'add', new: next.value[k] });
+            i += 2;
+        }
+        else if (p.removed) {
+            p.value.forEach((v) => out.push({ type: 'del', old: v }));
+            i++;
+        }
+        else if (p.added) {
+            p.value.forEach((v) => out.push({ type: 'add', new: v }));
+            i++;
+        }
+        else {
+            p.value.forEach((v) => out.push({ type: 'same', old: v, new: v }));
+            i++;
+        }
+    }
+    return out;
+};
+const isCodey = (s) => /^(```|:::|\||<)/.test(s.trimStart());
+const wordDiffHtml = (oldS, newS) => diffWords(oldS, newS)
+    .map((p) => (p.added ? `<ins>${escapeHtml(p.value)}</ins>` : p.removed ? `<del>${escapeHtml(p.value)}</del>` : escapeHtml(p.value)))
+    .join('');
+/**
+ * Reader-facing revision diff: changed blocks with word-level ins/del marks,
+ * unchanged runs collapsed, the nearest heading shown as context before each change.
+ */
+export const renderDiffHtml = (oldBody, newBody) => {
+    const parts = diffBlocks(oldBody, newBody);
+    const out = [];
+    let skip = 0;
+    let pendingCtx = null;
+    const flushSkip = () => {
+        if (skip) {
+            out.push(`<div class="rdiff-skip">⋯ ${skip} unchanged block${skip > 1 ? 's' : ''}</div>`);
+            skip = 0;
+        }
+    };
+    for (const p of parts) {
+        if (p.type === 'same') {
+            skip++;
+            if (/^#{1,3}\s/.test(p.new))
+                pendingCtx = p.new.split('\n')[0].replace(/<!--.*?-->/g, '').trim();
+            continue;
+        }
+        flushSkip();
+        if (pendingCtx) {
+            out.push(`<div class="rdiff-ctx">${escapeHtml(pendingCtx)}</div>`);
+            pendingCtx = null;
+        }
+        const cls = `rdiff-block${isCodey(p.new ?? p.old ?? '') ? ' codey' : ''}`;
+        if (p.type === 'change')
+            out.push(`<div class="${cls}">${wordDiffHtml(p.old, p.new)}</div>`);
+        else if (p.type === 'add')
+            out.push(`<div class="${cls}"><ins>${escapeHtml(p.new)}</ins></div>`);
+        else
+            out.push(`<div class="${cls}"><del>${escapeHtml(p.old)}</del></div>`);
+    }
+    flushSkip();
+    if (!out.some((h) => h.includes('rdiff-block'))) {
+        return '<div class="rdiff-skip">No content changes in the body (frontmatter or metadata only).</div>';
+    }
+    return out.join('\n');
+};

package/dist/verify.js

@@ -0,0 +1,120 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadDoc, parseRevId, readMeta, revId, splitRaw } from './core.js';
+const SKIP_DIRS = new Set(['.git', 'node_modules', '.history', 'dist', '.obsidian']);
+export const findPentimentoDocs = (root) => {
+    const out = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable directory — skip
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.'))
+                    walk(path.join(dir, entry.name));
+                continue;
+            }
+            if (!entry.name.endsWith('.md'))
+                continue;
+            const p = path.join(dir, entry.name);
+            try {
+                const head = fs.readFileSync(p, 'utf8').slice(0, 2000);
+                if (/^(?:Pentimento|Vellum):\s*true$/m.test(head))
+                    out.push(p);
+            }
+            catch {
+                // broken symlink or unreadable file — not a Pentimento doc
+            }
+        }
+    };
+    walk(root);
+    return out.sort();
+};
+/** Consistency check: canonical frontmatter, history files, and meta.yml must agree. */
+export const verifyDoc = (docPath) => {
+    const issues = [];
+    const err = (message) => issues.push({ level: 'error', message });
+    const warn = (message) => issues.push({ level: 'warn', message });
+    const info = (message) => issues.push({ level: 'info', message });
+    let doc;
+    try {
+        doc = loadDoc(docPath);
+    }
+    catch (e) {
+        err(e instanceof Error ? e.message : String(e));
+        return issues;
+    }
+    if (doc.frontmatter['Pentimento'] !== true && doc.frontmatter['Vellum'] !== true) {
+        info('not a Pentimento document (no `Pentimento: true` frontmatter) — nothing to verify');
+        return issues;
+    }
+    if (doc.historyDir.includes('{{')) {
+        info('template file (placeholder in History Folder) — skipped');
+        return issues;
+    }
+    let current = 0;
+    try {
+        current = parseRevId(doc.frontmatter['Current Revision']);
+    }
+    catch (e) {
+        err(e instanceof Error ? e.message : String(e));
+    }
+    if (!fs.existsSync(doc.historyDir)) {
+        err(`history folder missing: ${doc.historyDir}`);
+        return issues;
+    }
+    let meta;
+    try {
+        meta = readMeta(doc.historyDir);
+    }
+    catch (e) {
+        err(e instanceof Error ? e.message : String(e));
+        return issues;
+    }
+    const files = fs
+        .readdirSync(doc.historyDir)
+        .filter((f) => /^r\d{3,}\.md$/.test(f))
+        .map((f) => f.replace(/\.md$/, ''))
+        .sort();
+    const metaIds = meta.revisions.map((r) => r.id);
+    if (new Set(metaIds).size !== metaIds.length)
+        err('duplicate revision ids in meta.yml');
+    for (const id of metaIds) {
+        if (!files.includes(id))
+            err(`meta.yml lists ${id} but ${id}.md does not exist`);
+    }
+    for (const f of files) {
+        if (!metaIds.includes(f))
+            warn(`${f}.md exists but meta.yml has no entry for it`);
+    }
+    for (let i = 0; i < metaIds.length; i++) {
+        if (metaIds[i] !== revId(i + 1)) {
+            warn(`revision ids are not sequential from r001 (found ${metaIds[i]} at position ${i + 1})`);
+            break;
+        }
+    }
+    const last = metaIds[metaIds.length - 1];
+    if (current > 0 && last && revId(current) !== last) {
+        err(`canonical says Current Revision ${revId(current)} but the latest meta revision is ${last}`);
+    }
+    if (current > 0 && !files.includes(revId(current))) {
+        err(`Current Revision ${revId(current)} has no snapshot file`);
+    }
+    for (const f of files) {
+        const content = fs.readFileSync(path.join(doc.historyDir, `${f}.md`), 'utf8');
+        if (splitRaw(content).body.trim().length < 40) {
+            warn(`${f}.md looks like a stub (${content.length} bytes), not a real snapshot`);
+        }
+    }
+    if (last && files.includes(last)) {
+        const lastBody = splitRaw(fs.readFileSync(path.join(doc.historyDir, `${last}.md`), 'utf8')).body;
+        if (lastBody.trim() !== doc.body.trim()) {
+            info(`canonical has changes not yet snapshotted (differs from ${last})`);
+        }
+    }
+    return issues;
+};