projview 1.1.1 → 1.2.0

package/public/theme.js

@@ -0,0 +1,52 @@
+/* light / dark theme: the user's choice (system / light / dark) resolved to
+ * data-theme="light|dark" on <html>, which the CSS keys off. The inline script
+ * in index.html applies the same resolution before first paint. */
+
+import { $ } from './dom.js';
+
+const KEY = 'pv-theme';   // also read by the pre-paint script in index.html - keep in step
+const PREFS = ['system', 'light', 'dark'];
+const osLight = matchMedia('(prefers-color-scheme: light)');
+const listeners = new Set();
+const btn = $('theme-toggle');
+
+const ICONS = {
+  system: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="4" width="18" height="12" rx="2"/><path d="M8 20h8M12 16v4"/></svg>',
+  light: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/></svg>',
+  dark: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z"/></svg>'
+};
+
+function readPref() {
+  try { const p = localStorage.getItem(KEY); return PREFS.includes(p) ? p : 'system'; } catch { return 'system'; }
+}
+function writePref(p) {
+  try { localStorage.setItem(KEY, p); } catch { /* private window etc. - choice lasts this page only */ }
+}
+
+let pref = readPref();
+
+export const currentTheme = () => document.documentElement.dataset.theme === 'light' ? 'light' : 'dark';
+
+// Diagrams are baked SVG, so their owners re-render when the theme flips.
+export function onThemeChange(fn) { listeners.add(fn); }
+
+function apply() {
+  const before = currentTheme();
+  const theme = pref === 'system' ? (osLight.matches ? 'light' : 'dark') : pref;
+  document.documentElement.dataset.theme = theme;
+  btn.innerHTML = ICONS[pref];
+  btn.title = `theme: ${pref} (click to change)`;
+  btn.setAttribute('aria-label', `theme: ${pref}`);
+  if (theme !== before) for (const fn of listeners) fn(theme);
+}
+
+btn.addEventListener('click', () => {
+  pref = PREFS[(PREFS.indexOf(pref) + 1) % PREFS.length];
+  writePref(pref);
+  apply();
+});
+osLight.addEventListener('change', () => { if (pref === 'system') apply(); });
+// another projview tab changed the theme: follow it
+window.addEventListener('storage', (e) => { if (e.key === KEY) { pref = readPref(); apply(); } });
+
+apply();

package/public/toc.js

@@ -15,7 +15,8 @@ function setActive(current) {
 }
 
 export function buildToc() {
-  const headings = [...contentEl.querySelectorAll('h1, h2, h3')].filter((h) => h.id);
+  // rendered headings, or raw-view source lines tagged as headings (data-toc)
+  const headings = [...contentEl.querySelectorAll('h1, h2, h3, [data-toc]')].filter((h) => h.id);
   tocEntries = [];
   if (!headings.length) {
     document.body.classList.add('toc-empty');
@@ -26,8 +27,8 @@ export function buildToc() {
   const frag = document.createDocumentFragment();
   for (const h of headings) {
     const link = document.createElement('button');
-    link.className = `toc-item lvl-${h.tagName.toLowerCase()}`;
-    link.textContent = h.textContent;
+    link.className = `toc-item lvl-${h.dataset.toc || h.tagName.toLowerCase()}`;
+    link.textContent = h.dataset.tocLabel || h.textContent;
     const entry = { id: h.id, el: h, link };
     link.addEventListener('click', () => {
       scrollToFragment(h.id);
@@ -57,5 +58,12 @@ viewerEl.addEventListener('scroll', () => {
   spyRaf = requestAnimationFrame(() => { spyRaf = 0; updateScrollSpy(); });
 });
 
-$('toc-collapse').addEventListener('click', () => document.body.classList.add('toc-collapsed'));
-$('toc-reopen').addEventListener('click', () => document.body.classList.remove('toc-collapsed'));
+// wide: collapse / reopen the side panel. narrow: open / close it as an overlay.
+$('toc-collapse').addEventListener('click', () => {
+  document.body.classList.add('toc-collapsed');
+  document.body.classList.remove('toc-open');
+});
+$('toc-reopen').addEventListener('click', () => {
+  document.body.classList.remove('toc-collapsed');
+  document.body.classList.add('toc-open');
+});

package/public/tree.js

@@ -12,10 +12,11 @@ let fileCount = 0;
 
 export async function loadTree() {
   const res = await fetch('/api/tree');
-  const { root, tree, version, writable } = await res.json();
+  const { root, tree, version, writable, persistent } = await res.json();
   state.treeData = tree;
   state.rootName = root;
   state.writable = !!writable;
+  state.persistent = !!persistent;
   document.title = `${root} · projview`;
   if (version) versionEl.textContent = `version ${version}`;
   renderTree();

package/public/viewer.js

@@ -8,19 +8,28 @@ import { runMermaid } from './mermaid.js';
 import { buildToc } from './toc.js';
 import { toast } from './toast.js';
 import { onFileRendered } from './comments.js';
+import { isEditing, confirmLeave, onFileShown, hasRawView } from './editor.js';
+import { leaveHistory } from './history.js';
 
 const contentEl = $('content');
 const viewerEl = $('viewer');
 
 export async function openFile(p, fragment, highlight) {
+  // leaving an editor with unsaved changes needs a yes; on no, put the URL back
+  if (isEditing() && !confirmLeave()) {
+    location.hash = encodeURIComponent(state.currentPath);
+    return;
+  }
+  leaveHistory();
   state.currentPath = p;
   location.hash = encodeURIComponent(p);
   revealInTree(p);
   renderBreadcrumb(p);
 
+  const raw = state.view === 'raw' && hasRawView(p);
   let res;
   try {
-    res = await fetch(`/api/file?p=${encodeURIComponent(p)}`);
+    res = await fetch(`/api/file?p=${encodeURIComponent(p)}${raw ? '&view=raw' : ''}`);
   } catch {
     res = null;
   }
@@ -32,7 +41,9 @@ export async function openFile(p, fragment, highlight) {
   contentEl.innerHTML = html;
   await runMermaid();
   buildToc();
-  onFileRendered(p);   // load + anchor + paint comments for this file
+  // comments quote the rendered text, so they live in the rendered view only
+  onFileRendered(raw ? null : p);
+  onFileShown(p);      // rendered / raw / edit switcher
   if (fragment) scrollToFragment(fragment);
   else if (highlight) highlightInContent(highlight);
   else viewerEl.scrollTop = 0;
@@ -79,7 +90,7 @@ function highlightInContent(term) {
 
 function showNotFound(p) {
   contentEl.innerHTML =
-    `<div class="empty-state"><div class="empty-emoji">🤷</div>` +
+    `<div class="empty-state">` +
     `<p>can't find <code>${esc(p)}</code></p>` +
     `<p class="muted">the link may be broken, or the file was renamed / removed</p></div>`;
   buildToc();

package/src/render.js

@@ -171,7 +171,8 @@ export const LINE_LIMIT = 50_000;
 
 // A code view with line numbers and indent guides. Each line carries its
 // indent depth (--i) so CSS can draw one guide per level (--step columns apart).
-function renderCodeView(code, lang, note = '') {
+// lineAttrs: optional Map of line index -> extra attributes for that line's span.
+function renderCodeView(code, lang, note = '', lineAttrs = null) {
   let rawLines = code.replace(/\r\n?/g, '\n').replace(/\n$/, '').split('\n');
   if (rawLines.length > LINE_LIMIT) {
     note += notice(`showing the first ${LINE_LIMIT.toLocaleString('en')} of ${rawLines.length.toLocaleString('en')} lines`);
@@ -194,7 +195,7 @@ function renderCodeView(code, lang, note = '') {
   }
 
   const body = lines
-    .map((l, i) => `<span class="cl" style="--i:${indents[i]}"><span class="lc">${l}</span></span>`)
+    .map((l, i) => `<span class="cl" style="--i:${indents[i]}"${lineAttrs?.get(i) || ''}><span class="lc">${l}</span></span>`)
     .join('');
   return `${note}<pre class="hljs code-view" data-lang="${lang}" style="--step:${step}"><code>${body}</code></pre>\n`;
 }
@@ -227,6 +228,27 @@ export function renderYaml(content) {
   return renderCodeView(content, 'yaml');
 }
 
+// The "raw" view of a markdown / mermaid file: its source in the code view
+// (highlighted, numbered, with indent guides), exactly as written.
+const SOURCE_LANG = { '.md': 'markdown', '.mmd': 'plaintext' };
+export function renderSource(ext, content) {
+  return renderCodeView(content, SOURCE_LANG[ext] || 'plaintext', '', ext === '.md' ? headingLines(content) : null);
+}
+
+// h1-h3 source lines of a markdown file, tagged with the same ids the rendered
+// view gives its headings - so the outline and #fragment links work in raw too.
+function headingLines(content) {
+  const attrs = new Map();
+  const tokens = md.parse(content, {});   // core rules run here, heading_anchors included
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t.type !== 'heading_open' || !t.map || !['h1', 'h2', 'h3'].includes(t.tag)) continue;
+    const label = escapeHtml(tokens[i + 1]?.content || '').replace(/"/g, '&quot;');
+    attrs.set(t.map[0], ` id="${t.attrGet('id')}" data-toc="${t.tag}" data-toc-label="${label}"`);
+  }
+  return attrs;
+}
+
 export function renderFile(ext, content) {
   if (ext === '.mmd') return renderMermaid(content);
   if (ext === '.json') return renderJson(content);

package/src/search.js

@@ -17,10 +17,20 @@ function flattenFiles(nodes, acc = []) {
   return acc;
 }
 
-function addToIndex(rel, content) {
+function addToIndex(rel, source, mtime = null) {
   // index JSON as displayed (re-indented) so snippet line numbers match the viewer
-  if (rel.toLowerCase().endsWith('.json')) content = jsonDisplayText(content).text;
-  index.set(rel, { path: rel, name: rel.split('/').pop(), content, lower: content.toLowerCase() });
+  const content = rel.toLowerCase().endsWith('.json') ? jsonDisplayText(source).text : source;
+  index.set(rel, {
+    path: rel, name: rel.split('/').pop(), content, lower: content.toLowerCase(), mtime,
+    raw: content === source ? undefined : source   // kept only when it differs, for versions
+  });
+}
+
+// The file's text as last indexed - i.e. before the change being handled now.
+// The server turns it into a version when the file changes. null if never indexed.
+export function indexedSource(rel) {
+  const item = index.get(rel);
+  return item ? { content: item.raw ?? item.content, mtime: item.mtime } : null;
 }
 
 // Build the index for `root`. With a persisted store, loads the cached entries
@@ -51,7 +61,7 @@ export async function buildIndex(root, store) {
     return { path: f.path, name: f.name, ext: f.ext, mtime, content };
   }));
 
-  for (const e of entries) addToIndex(e.path, e.content);
+  for (const e of entries) addToIndex(e.path, e.content, e.mtime);
   await store.save(entries);
   return { store, total: entries.length, reindexed, warm: !!cached };
 }
@@ -62,7 +72,7 @@ export async function updateFile(rel) {
   const abs = path.join(theRoot, rel);
   try {
     const [content, stat] = await Promise.all([fsp.readFile(abs, 'utf8'), fsp.stat(abs)]);
-    addToIndex(rel, content);
+    addToIndex(rel, content, stat.mtimeMs);
     return { path: rel, name: rel.split('/').pop(), ext: path.extname(rel).toLowerCase(), mtime: stat.mtimeMs, content };
   } catch { return null; }
 }

package/src/server.js

@@ -6,9 +6,9 @@ import { fileURLToPath } from 'node:url';
 import chokidar from 'chokidar';
 
 import { buildTree, isHiddenPath, isIgnoredDir, isPreviewable } from './walk.js';
-import { renderFile } from './render.js';
-import { buildIndex, updateFile, removeFile, search } from './search.js';
-import { createStore, gitOrOsUser } from './store.js';
+import { renderFile, renderSource } from './render.js';
+import { buildIndex, updateFile, removeFile, search, indexedSource } from './search.js';
+import { createStore, gitOrOsUser, isPersistent, VERSION_LIMIT } from './store.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PUBLIC_DIR = path.join(__dirname, '..', 'public');
@@ -16,6 +16,9 @@ const VERSION = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.j
 // vendored client libs (mermaid bundle, hljs theme) live in public/vendor/ and
 // are served by the static handler below - no node_modules resolution needed.
 
+// Earlier versions above this size aren't kept (generated bundles, data dumps).
+const VERSION_MAX_BYTES = 5_000_000;
+
 const MIME = {
   '.html': 'text/html; charset=utf-8',
   '.js': 'text/javascript; charset=utf-8',
@@ -53,6 +56,13 @@ export function isLoopbackHost(host) {
   return ['127.0.0.1', '::1', 'localhost', ''].includes(host);
 }
 
+// The Host header of a request that may write. A DNS-rebinding page reaches a
+// loopback port under its own domain, so the bind address alone isn't enough.
+export function isLoopbackHostHeader(hostHeader) {
+  const name = (hostHeader || '').replace(/:\d+$/, '').replace(/^\[(.*)\]$/, '$1').toLowerCase();
+  return ['127.0.0.1', '::1', 'localhost'].includes(name) || name.endsWith('.localhost');
+}
+
 // Read + JSON-parse a request body, capped to guard against abuse.
 // Resolves null on parse error or oversize (handler treats that as a 400).
 function readBody(req, limit = 1_000_000) {
@@ -75,6 +85,20 @@ export async function startServer(root, { port = 4321, host = '127.0.0.1', store
   const denyWrite = (res) => sendJson(res, { error: 'read-only: projview is exposed on a non-loopback host' }, 403);
   const localAuthor = gitOrOsUser();          // default author for UI-created comments
 
+  // A client path that may be read (or, behind the write guards, saved): inside
+  // root, a previewable type, and not under a dir the tree hides. Else null.
+  // Checked on the real path too, so a symlink named notes.md can't reach a file
+  // outside the root (e.g. ~/.zshrc) - for reads, and above all for saves.
+  const realRoot = fs.realpathSync(root);
+  const editablePath = async (rel) => {
+    const abs = resolveInRoot(root, rel || '');
+    if (!abs || !isPreviewable(abs) || isHiddenPath(path.relative(root, abs))) return null;
+    let real;
+    try { real = await fsp.realpath(abs); } catch { return abs; }   // missing: the caller answers 404
+    if (!resolveInRoot(realRoot, path.relative(realRoot, real))) return null;
+    return abs;
+  };
+
   function broadcast(event, payload) {
     const frame = `event: ${event}\ndata: ${JSON.stringify(payload || {})}\n\n`;
     for (const res of sseClients) res.write(frame);
@@ -99,7 +123,7 @@ export async function startServer(root, { port = 4321, host = '127.0.0.1', store
 
     // --- file tree ---
     if (pathname === '/api/tree') {
-      sendJson(res, { root: path.basename(root) || root, tree: buildTree(root), version: VERSION, writable: allowWrites });
+      sendJson(res, { root: path.basename(root) || root, tree: buildTree(root), version: VERSION, writable: allowWrites, persistent: isPersistent(storeConfig) });
       return;
     }
 
@@ -115,21 +139,83 @@ export async function startServer(root, { port = 4321, host = '127.0.0.1', store
     // --- rendered file contents ---
     if (pathname === '/api/file') {
       const rel = url.searchParams.get('p') || '';
-      const abs = resolveInRoot(root, rel);
-      if (!abs || !isPreviewable(abs) || isHiddenPath(path.relative(root, abs))) {
+      const abs = await editablePath(rel);
+      if (!abs) {
         sendJson(res, { error: 'invalid path' }, 400);
         return;
       }
       try {
         const content = await fsp.readFile(abs, 'utf8');
         try { await store.recordEvent({ type: 'view', file: rel }); } catch { /* usage is best-effort */ }
-        sendJson(res, { path: rel, ext: path.extname(abs).toLowerCase(), html: renderFile(path.extname(abs).toLowerCase(), content) });
+        const ext = path.extname(abs).toLowerCase();
+        const raw = url.searchParams.get('view') === 'raw';   // md / mmd source instead of the render
+        sendJson(res, { path: rel, ext, html: raw ? renderSource(ext, content) : renderFile(ext, content) });
       } catch {
         sendJson(res, { error: 'not found' }, 404);
       }
       return;
     }
 
+    // --- live preview: render unsaved editor text (never touches disk) ---
+    if (pathname === '/api/preview' && req.method === 'POST') {
+      const body = await readBody(req, 10_000_000);
+      if (!body || typeof body.path !== 'string' || typeof body.content !== 'string' || !isPreviewable(body.path)) {
+        sendJson(res, { error: 'path and content are required' }, 400);
+        return;
+      }
+      sendJson(res, { html: renderFile(path.extname(body.path).toLowerCase(), body.content) });
+      return;
+    }
+
+    // --- raw source: read (GET) + save (PUT) for the in-browser editor ---
+    if (pathname === '/api/source') {
+      if (req.method === 'PUT') {
+        if (!allowWrites) return denyWrite(res);
+        // a DNS-rebound page would arrive with its own Host; only a local name may write
+        if (!isLoopbackHostHeader(req.headers.host)) { sendJson(res, { error: 'writes need a localhost Host header' }, 403); return; }
+        const body = await readBody(req, 10_000_000);
+        if (!body || typeof body.path !== 'string' || typeof body.content !== 'string') { sendJson(res, { error: 'path and content are required' }, 400); return; }
+        const abs = await editablePath(body.path);
+        if (!abs) { sendJson(res, { error: 'invalid path' }, 400); return; }
+        let stat;
+        try { stat = await fsp.stat(abs); } catch { sendJson(res, { error: 'not found' }, 404); return; }
+        // optimistic concurrency: refuse to clobber a file that changed since it was opened
+        if (!body.force && body.mtime !== stat.mtimeMs) { sendJson(res, { error: 'changed on disk', mtime: stat.mtimeMs }, 409); return; }
+        try {
+          await fsp.writeFile(abs, body.content, 'utf8');
+          sendJson(res, { path: body.path, mtime: (await fsp.stat(abs)).mtimeMs });
+        } catch (err) {
+          sendJson(res, { error: `could not save: ${err.code || err.message}` }, 500);
+        }
+        return;
+      }
+      const rel = url.searchParams.get('p') || '';
+      const abs = await editablePath(rel);
+      if (!abs) { sendJson(res, { error: 'invalid path' }, 400); return; }
+      try {
+        const [content, stat] = await Promise.all([fsp.readFile(abs, 'utf8'), fsp.stat(abs)]);
+        sendJson(res, { path: rel, content, mtime: stat.mtimeMs });
+      } catch {
+        sendJson(res, { error: 'not found' }, 404);
+      }
+      return;
+    }
+
+    // --- earlier versions of a file: list (newest first) + fetch one ---
+    // read-only everywhere; restoring goes through PUT /api/source and its guards
+    if (pathname === '/api/versions') {
+      const rel = url.searchParams.get('p') || '';
+      if (!(await editablePath(rel))) { sendJson(res, { error: 'invalid path' }, 400); return; }
+      sendJson(res, { path: rel, limit: VERSION_LIMIT, versions: await store.listVersions(rel) });
+      return;
+    }
+    if (pathname.startsWith('/api/versions/')) {
+      const v = await store.getVersion(decodeURIComponent(pathname.slice('/api/versions/'.length)));
+      if (!v) { sendJson(res, { error: 'not found' }, 404); return; }
+      sendJson(res, v);
+      return;
+    }
+
     // --- comments: list (GET) + create (POST) ---
     if (pathname === '/api/comments') {
       if (req.method === 'POST') {
@@ -191,30 +277,55 @@ export async function startServer(root, { port = 4321, host = '127.0.0.1', store
 
   // --- file watcher -> live reload ---
   const store = createStore(storeConfig, root);
-  const indexInfo = await buildIndex(root, store);   // load-or-build the search index
 
   // file watcher -> keep the in-memory index, the persisted store, AND the
-  // browser in sync as files change during a session
+  // browser in sync as files change during a session. Started before the index
+  // build so its initial scan (the slow part on big trees) overlaps it.
   const watcher = chokidar.watch(root, {
     ignoreInitial: true,
     ignored: (p) => p.split(path.sep).some(isIgnoredDir)
   });
+  // resolves once the scan is done; changes before then aren't seen. Not awaited
+  // here so startup stays fast - tests (and anything that must not miss an
+  // early change) wait on it via the returned `watching`.
+  const watching = new Promise((resolve) => watcher.once('ready', resolve));
+  const indexInfo = await buildIndex(root, store);   // load-or-build the search index
   const rel = (p) => path.relative(root, p).split(path.sep).join('/');
+  // keep text a change replaced (or a delete removed) as a version - any source
+  // counts: projview's editor, an IDE, git, agents
+  const keepVersion = async (file, before) => {
+    if (!before || Buffer.byteLength(before.content) > VERSION_MAX_BYTES) return;
+    try { await store.addVersion({ file, content: before.content, mtime: before.mtime }); } catch { /* versions are best-effort */ }
+  };
   const touch = async (p, event) => {
-    if (!isPreviewable(p)) return;
+    // same rule as the API: previewable, not hidden, real path inside the root
+    // (a symlink to an outside file is neither indexed nor versioned)
+    if (!(await editablePath(rel(p)))) return;
+    const before = indexedSource(rel(p));     // the text this change replaces
     const entry = await updateFile(rel(p));   // refresh in-memory index, get the entry
     if (entry) await store.update(entry);     // mirror the change into the store
+    if (entry && before && before.content !== entry.content) await keepVersion(rel(p), before);
     broadcast(event, { path: rel(p) });
   };
+  const unlink = async (p) => {
+    if (!isPreviewable(p)) return;
+    await keepVersion(rel(p), indexedSource(rel(p)));   // a delete is a change too
+    removeFile(rel(p));
+    await store.remove(rel(p));
+    broadcast('tree');
+  };
+  // one file's events run in order: concurrent handlers would read the same
+  // "before" text, losing the in-between version of two quick changes
+  const queues = new Map();
+  const serial = (fn) => (p, ...args) => {
+    const next = (queues.get(p) || Promise.resolve()).then(() => fn(p, ...args)).catch(() => {});
+    queues.set(p, next);
+    next.then(() => { if (queues.get(p) === next) queues.delete(p); });
+  };
   watcher
-    .on('change', (p) => touch(p, 'change'))
-    .on('add', (p) => touch(p, 'tree'))
-    .on('unlink', async (p) => {
-      if (!isPreviewable(p)) return;
-      removeFile(rel(p));
-      await store.remove(rel(p));
-      broadcast('tree');
-    })
+    .on('change', serial((p) => touch(p, 'change')))
+    .on('add', serial((p) => touch(p, 'tree')))
+    .on('unlink', serial(unlink))
     .on('addDir', () => broadcast('tree'))
     .on('unlinkDir', () => broadcast('tree'));
   const listenPort = await listenWithRetry(server, port, host);
@@ -229,6 +340,7 @@ export async function startServer(root, { port = 4321, host = '127.0.0.1', store
     server,
     port: listenPort,
     close,
+    watching,
     writable: allowWrites,
     storeInfo: { describe: store.describe(), warm: indexInfo.warm, reindexed: indexInfo.reindexed, total: indexInfo.total }
   };

package/src/store.js

@@ -5,6 +5,8 @@
  *   entries  - indexed files { path, name, ext, mtime, content }
  *   comments - notes on a file or a portion of it (see anchor model below)
  *   events   - usage signals { ts, type, file?, query?, count? }
+ *   versions - earlier text of a file { id, file, mtime, replacedAt, content },
+ *              newest VERSION_LIMIT kept per file (older ones are pruned)
  *
  * Backends:
  *   memory    - no disk persistence (ephemeral default; lives only this session)
@@ -69,6 +71,17 @@ const newEvent = (e) => ({
   count: e.count ?? null
 });
 
+// How many earlier versions of each file are kept.
+export const VERSION_LIMIT = 5;
+const newVersion = (v) => ({
+  id: randomUUID(),
+  file: v.file,
+  mtime: v.mtime ?? null,          // when this text was written (its file mtime)
+  replacedAt: v.replacedAt || Date.now(),
+  content: v.content
+});
+const versionMeta = ({ id, file, mtime, replacedAt, content }) => ({ id, file, mtime, replacedAt, size: Buffer.byteLength(content) });
+
 // Aggregate raw events into something a human / agent can read at a glance.
 function summarizeEvents(events) {
   const byType = {};
@@ -137,12 +150,30 @@ function fileFor(root, persist, ext) {
 
 // Holds comments + events in memory; calls flush() after each mutation so a
 // disk-backed wrapper (superlite) can persist. memory passes a no-op flush.
-function inMemoryDocs(flush = async () => {}) {
+// Versions get their own flush: they're large, and shouldn't be rewritten on
+// every page view or search event.
+function inMemoryDocs(flush = async () => {}, flushVersions = flush) {
   const comments = new Map();   // id -> comment
   const events = [];            // append-only (stable ref - never reassigned)
+  const versions = [];          // oldest first (stable ref - pruned in place)
   return {
     comments,
     events,
+    versions,
+    async addVersion(v) {
+      const version = newVersion(v);
+      versions.push(version);
+      const mine = versions.filter((x) => x.file === version.file);
+      for (const old of mine.slice(0, Math.max(0, mine.length - VERSION_LIMIT))) versions.splice(versions.indexOf(old), 1);
+      await flushVersions();
+      return versionMeta(version);
+    },
+    async listVersions(file) {
+      return versions.filter((x) => x.file === file).reverse().map(versionMeta);
+    },
+    async getVersion(id) {
+      return versions.find((x) => x.id === id) || null;
+    },
     async addComment(c) {
       const comment = newComment(c);
       comments.set(comment.id, comment);
@@ -189,6 +220,9 @@ function memoryStore() {
     deleteComment: docs.deleteComment,
     recordEvent: docs.recordEvent,
     usageStats: docs.usageStats,
+    addVersion: docs.addVersion,
+    listVersions: docs.listVersions,
+    getVersion: docs.getVersion,
     async close() {},
     describe() { return 'in-memory (ephemeral - nothing persisted)'; }
   };
@@ -196,6 +230,7 @@ function memoryStore() {
 
 function superliteStore(root, persist) {
   const file = fileFor(root, persist, 'json');
+  const versionsFile = file.replace(/\.json$/, '.versions.json');   // big, so written only when versions change
   const entries = new Map();   // path -> entry
   let loaded = false;
   const flush = () => fsp.writeFile(file, JSON.stringify({
@@ -204,7 +239,8 @@ function superliteStore(root, persist) {
     comments: [...docs.comments.values()],
     events: docs.events
   }));
-  const docs = inMemoryDocs(() => (loaded ? flush() : Promise.resolve()));
+  const flushVersions = () => fsp.writeFile(versionsFile, JSON.stringify(docs.versions));
+  const docs = inMemoryDocs(() => (loaded ? flush() : Promise.resolve()), () => (loaded ? flushVersions() : Promise.resolve()));
   const ensure = async () => {
     if (loaded) return;
     try {
@@ -213,11 +249,15 @@ function superliteStore(root, persist) {
       for (const c of d.comments || []) docs.comments.set(c.id, c);
       for (const ev of d.events || []) docs.events.push(ev);
     } catch { /* fresh */ }
+    try {
+      for (const v of JSON.parse(await fsp.readFile(versionsFile, 'utf8'))) docs.versions.push(v);
+    } catch { /* no history yet */ }
     loaded = true;
   };
   return {
     kind: 'superlite',
     file,
+    versionsFile,
     async load() { await ensure(); return entries.size ? { entries: [...entries.values()] } : null; },
     async save(es) { await ensure(); entries.clear(); for (const e of es) entries.set(e.path, e); await flush(); },
     async update(entry) { await ensure(); entries.set(entry.path, entry); await flush(); },
@@ -228,8 +268,13 @@ function superliteStore(root, persist) {
     async deleteComment(id) { await ensure(); return docs.deleteComment(id); },
     async recordEvent(e) { await ensure(); return docs.recordEvent(e); },
     async usageStats() { await ensure(); return docs.usageStats(); },
+    async addVersion(v) { await ensure(); return docs.addVersion(v); },
+    async listVersions(f) { await ensure(); return docs.listVersions(f); },
+    async getVersion(id) { await ensure(); return docs.getVersion(id); },
     async close({ keep } = {}) {
-      if (!persist && !keep) { try { await fsp.unlink(file); } catch { /* gone */ } }
+      if (!persist && !keep) {
+        for (const f of [file, versionsFile]) { try { await fsp.unlink(f); } catch { /* gone */ } }
+      }
     },
     describe() { return `superlite/json (${persist ? 'persisted' : 'ephemeral'}) ${file}`; }
   };
@@ -249,6 +294,7 @@ function sqliteAt(file, { cleanup }) {
     db.exec('CREATE TABLE IF NOT EXISTS files (path TEXT PRIMARY KEY, name TEXT, ext TEXT, mtime REAL, content TEXT)');
     db.exec('CREATE TABLE IF NOT EXISTS comments (id TEXT PRIMARY KEY, file TEXT, anchor TEXT, body TEXT, author TEXT, createdAt REAL, resolved INTEGER)');
     db.exec('CREATE TABLE IF NOT EXISTS events (id TEXT PRIMARY KEY, ts REAL, type TEXT, file TEXT, query TEXT, count INTEGER)');
+    db.exec('CREATE TABLE IF NOT EXISTS versions (id TEXT PRIMARY KEY, file TEXT, mtime REAL, replacedAt REAL, content TEXT)');
     return db;
   };
   const writeComment = (d, c) => d
@@ -314,6 +360,23 @@ function sqliteAt(file, { cleanup }) {
       const d = await open();
       return summarizeEvents(d.prepare('SELECT type, file, query FROM events').all());
     },
+    async addVersion(v) {
+      const d = await open();
+      const version = newVersion(v);
+      d.prepare('INSERT INTO versions (id, file, mtime, replacedAt, content) VALUES (?, ?, ?, ?, ?)')
+        .run(version.id, version.file, version.mtime, version.replacedAt, version.content);
+      d.prepare('DELETE FROM versions WHERE file = ? AND id NOT IN (SELECT id FROM versions WHERE file = ? ORDER BY replacedAt DESC LIMIT ?)')
+        .run(version.file, version.file, VERSION_LIMIT);
+      return versionMeta(version);
+    },
+    async listVersions(file) {
+      const d = await open();
+      return d.prepare('SELECT * FROM versions WHERE file = ? ORDER BY replacedAt DESC').all(file).map(versionMeta);
+    },
+    async getVersion(id) {
+      const d = await open();
+      return d.prepare('SELECT * FROM versions WHERE id = ?').get(id) || null;
+    },
     async close({ keep } = {}) {
       if (db) { db.close(); db = null; }
       if (cleanup && !keep) { try { await fsp.unlink(file); } catch { /* gone */ } }
@@ -353,8 +416,11 @@ function postgresStore(url) {
     await client.query('CREATE TABLE IF NOT EXISTS projview_files (path TEXT PRIMARY KEY, name TEXT, ext TEXT, mtime DOUBLE PRECISION, content TEXT)');
     await client.query('CREATE TABLE IF NOT EXISTS projview_comments (id TEXT PRIMARY KEY, file TEXT, anchor TEXT, body TEXT, author TEXT, createdat DOUBLE PRECISION, resolved BOOLEAN)');
     await client.query('CREATE TABLE IF NOT EXISTS projview_events (id TEXT PRIMARY KEY, ts DOUBLE PRECISION, type TEXT, file TEXT, query TEXT, count INTEGER)');
+    await client.query('CREATE TABLE IF NOT EXISTS projview_versions (id TEXT PRIMARY KEY, file TEXT, mtime DOUBLE PRECISION, replacedat DOUBLE PRECISION, content TEXT)');
     return client;
   };
+  // postgres folds unquoted identifiers to lower case
+  const toVersion = (r) => ({ id: r.id, file: r.file, mtime: r.mtime == null ? null : Number(r.mtime), replacedAt: Number(r.replacedat), content: r.content });
   const writeComment = (c) => client.query(
     'INSERT INTO projview_comments (id, file, anchor, body, author, createdat, resolved) VALUES ($1, $2, $3, $4, $5, $6, $7)' +
       ' ON CONFLICT (id) DO UPDATE SET file = $2, anchor = $3, body = $4, author = $5, createdat = $6, resolved = $7',
@@ -428,6 +494,25 @@ function postgresStore(url) {
       const { rows } = await c.query('SELECT type, file, query FROM projview_events');
       return summarizeEvents(rows);
     },
+    async addVersion(v) {
+      const c = await open();
+      const version = newVersion(v);
+      await c.query('INSERT INTO projview_versions (id, file, mtime, replacedat, content) VALUES ($1, $2, $3, $4, $5)',
+        [version.id, version.file, version.mtime, version.replacedAt, version.content]);
+      await c.query('DELETE FROM projview_versions WHERE file = $1 AND id NOT IN (SELECT id FROM projview_versions WHERE file = $1 ORDER BY replacedat DESC LIMIT $2)',
+        [version.file, VERSION_LIMIT]);
+      return versionMeta(version);
+    },
+    async listVersions(file) {
+      const c = await open();
+      const { rows } = await c.query('SELECT * FROM projview_versions WHERE file = $1 ORDER BY replacedat DESC', [file]);
+      return rows.map((r) => versionMeta(toVersion(r)));
+    },
+    async getVersion(id) {
+      const c = await open();
+      const { rows } = await c.query('SELECT * FROM projview_versions WHERE id = $1', [id]);
+      return rows.length ? toVersion(rows[0]) : null;
+    },
     async close() { if (client) { await client.end(); client = null; } },   // never drop the user's tables
     describe() { return `custom/postgres ${redact(url)}`; }
   };