projview 1.0.0 → 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

@@ -1,7 +1,7 @@
 /* left-nav file tree: render, expand/collapse, reveal */
 
 import { $, esc, cssEsc } from './dom.js';
-import { SVG_FOLDER, fileIcon } from './icons.js';
+import { SVG_FOLDER, fileIcon, fileKind } from './icons.js';
 import { state } from './store.js';
 import { openFile } from './viewer.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();
@@ -70,7 +71,7 @@ function renderFileRow(node) {
   row.dataset.path = node.path;
   row.innerHTML =
     `<span class="twist"></span>` +
-    `<span class="ico ico-${node.ext === '.mmd' ? 'mmd' : 'md'}">${fileIcon(node.ext)}</span>` +
+    `<span class="ico ico-${fileKind(node.name)}">${fileIcon(node.name)}</span>` +
     `<span class="label">${esc(node.name)}</span>`;
   row.addEventListener('click', () => openFile(node.path));
   return row;

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

@@ -92,6 +92,166 @@ export function renderMermaid(content) {
   return `<div class="mermaid">${escapeHtml(content)}</div>\n`;
 }
 
+// Re-indent JSON by walking its tokens rather than parse -> stringify, so the
+// original literals survive untouched (big ints, 1.0, duplicate keys, key order).
+// Assumes the input is already valid JSON (callers check with JSON.parse first).
+export function formatJson(src, indent = 2) {
+  const pad = (n) => '\n' + ' '.repeat(n * indent);
+  let out = '';
+  let depth = 0;
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i];
+    if (c === '"') {
+      let j = i + 1;
+      while (j < src.length && src[j] !== '"') j += src[j] === '\\' ? 2 : 1;
+      out += src.slice(i, j + 1);
+      i = j;
+    } else if (c === '{' || c === '[') {
+      // keep empty containers compact: {} / []
+      let j = i + 1;
+      while (/\s/.test(src[j] || '')) j++;
+      if (src[j] === (c === '{' ? '}' : ']')) { out += c + src[j]; i = j; continue; }
+      out += c + pad(++depth);
+    } else if (c === '}' || c === ']') {
+      out += pad(--depth) + c;
+    } else if (c === ',') {
+      out += ',' + pad(depth);
+    } else if (c === ':') {
+      out += ': ';
+    } else if (!/\s/.test(c)) {
+      out += c;
+    }
+  }
+  return out;
+}
+
+// Split highlight.js output into lines, closing + reopening any <span> that
+// crosses a newline so each line is self-contained HTML.
+function splitHighlightedLines(html) {
+  const lines = [];
+  const open = [];
+  let cur = '';
+  for (const m of html.matchAll(/<span[^>]*>|<\/span>|\n|[^<\n]+/g)) {
+    const tok = m[0];
+    if (tok === '\n') {
+      lines.push(cur + '</span>'.repeat(open.length));
+      cur = open.join('');
+    } else {
+      if (tok.startsWith('<span')) open.push(tok);
+      else if (tok === '</span>') open.pop();
+      cur += tok;
+    }
+  }
+  lines.push(cur + '</span>'.repeat(open.length));
+  return lines;
+}
+
+const leadingIndent = (line) => line.match(/^[ \t]*/)[0].replace(/\t/g, '  ').length;
+
+// The file's indent unit: the most common step between a line and a deeper next
+// line. A mode, not a gcd, so one oddly indented line can't skew it. Default 2.
+function indentStep(indents) {
+  const counts = new Map();
+  let prev = 0;
+  for (const n of indents) {
+    if (n === -1) continue;
+    const d = n - prev;
+    if (d >= 2 && d <= 8) counts.set(d, (counts.get(d) || 0) + 1);
+    prev = n;
+  }
+  let best = 2, bestCount = 0;
+  for (const [d, c] of counts) if (c > bestCount || (c === bestCount && d < best)) { best = d; bestCount = c; }
+  return best;
+}
+
+// Big files skip syntax highlighting - hljs gets slow and nobody reads 2MB of JSON by colour.
+const HIGHLIGHT_LIMIT = 2_000_000;
+// Past this many lines only the head is rendered - the DOM, not the server, is the limit.
+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).
+// 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`);
+    rawLines = rawLines.slice(0, LINE_LIMIT);
+  }
+  const raw = rawLines.join('\n');
+  const html = raw.length <= HIGHLIGHT_LIMIT && hljs.getLanguage(lang)
+    ? hljs.highlight(raw, { language: lang, ignoreIllegals: true }).value
+    : escapeHtml(raw);
+  const lines = splitHighlightedLines(html);
+
+  // blank lines borrow the shallower neighbour's indent so guides don't break
+  const indents = rawLines.map((l) => (l.trim() ? leadingIndent(l) : -1));
+  const step = indentStep(indents);
+  const next = new Array(indents.length);
+  for (let i = indents.length - 1, n = 0; i >= 0; i--) next[i] = n = indents[i] === -1 ? n : indents[i];
+  for (let i = 0, prev = 0; i < indents.length; i++) {
+    if (indents[i] === -1) indents[i] = Math.min(prev, next[i]);
+    else prev = indents[i];
+  }
+
+  const body = lines
+    .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`;
+}
+
+const notice = (msg) => `<div class="data-notice">${escapeHtml(msg)}</div>\n`;
+
+// The text a JSON file is displayed as: re-indented when valid, as written when
+// not (e.g. JSONC). Shared with the search index so snippet line numbers match
+// the viewer's. A leading BOM is dropped - JSON.parse rejects it.
+export function jsonDisplayText(content) {
+  const src = content.replace(/^\uFEFF/, '');
+  if (!src.trim()) return { text: '' };
+  try {
+    JSON.parse(src);
+  } catch (err) {
+    return { text: src, error: err.message };
+  }
+  return { text: formatJson(src) };
+}
+
+// JSON: pretty-printed when valid; shown as-is (with a note) when it isn't.
+export function renderJson(content) {
+  const { text, error } = jsonDisplayText(content);
+  return renderCodeView(text, 'json', error ? notice(`not strict JSON, shown as-is - ${error}`) : '');
+}
+
+// YAML: indentation is meaning, so it's shown exactly as written (highlighted,
+// with guides) rather than re-serialised - which would also choke on Helm templates.
+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) {
-  return ext === '.mmd' ? renderMermaid(content) : renderMarkdown(content);
+  if (ext === '.mmd') return renderMermaid(content);
+  if (ext === '.json') return renderJson(content);
+  if (ext === '.yml' || ext === '.yaml') return renderYaml(content);
+  return renderMarkdown(content);
 }

package/src/search.js

@@ -1,6 +1,7 @@
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { buildTree } from './walk.js';
+import { jsonDisplayText } from './render.js';
 import { createStore } from './store.js';
 
 // In-memory index: relPath -> { path, name, content, lower }. Search always runs
@@ -16,8 +17,20 @@ function flattenFiles(nodes, acc = []) {
   return acc;
 }
 
-function addToIndex(rel, content) {
-  index.set(rel, { path: rel, name: rel.split('/').pop(), content, lower: content.toLowerCase() });
+function addToIndex(rel, source, mtime = null) {
+  // index JSON as displayed (re-indented) so snippet line numbers match the viewer
+  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
@@ -48,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 };
 }
@@ -59,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

@@ -5,10 +5,10 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import chokidar from 'chokidar';
 
-import { buildTree, 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 { buildTree, isHiddenPath, isIgnoredDir, isPreviewable } from './walk.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)) {
+      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 }
   };