projview 0.6.0 → 0.8.0

package/bin/projview.js

@@ -2,11 +2,11 @@
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { readFileSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { startServer } from '../src/server.js';
 import { buildTree, countFiles } from '../src/walk.js';
 import { buildIndex, search } from '../src/search.js';
-import { resolveStoreConfig, createStore } from '../src/store.js';
+import { resolveStoreConfig, createStore, isPersistent, gitOrOsUser } from '../src/store.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const DEMO_DIR = path.join(__dirname, '..', 'docs');   // bundled sample docs
@@ -50,6 +50,8 @@ function parseSubArgs(args) {
     else if (a === '--store-url') o.storeUrl = args[++i];
     else if (a === '--persist') o.persist = true;
     else if (a === '--demo') o.demo = true;
+    else if (a === '--heading') o.heading = args[++i];
+    else if (a === '--author') o.author = args[++i];
     else if (a.startsWith('-')) { /* ignore unknown flag in a subcommand */ }
     else o.positional.push(a);
   }
@@ -80,6 +82,77 @@ function cmdTree(args) {
   process.stdout.write(JSON.stringify({ root: path.basename(root) || root, files: countFiles(tree), tree }, null, 2) + '\n');
 }
 
+const print = (obj) => process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+
+// Resolve the comment author: explicit flag > git user.name > OS username.
+// Agents pass --author (e.g. "claude") so AI-authored comments are distinguishable.
+const resolveAuthor = (explicit) => explicit || gitOrOsUser();
+
+// projview comment <add|resolve|reopen|rm> ...   (writes ride the store)
+async function cmdComment(args) {
+  const sub = args[0];
+  const o = parseSubArgs(args.slice(1));
+  const cfg = resolveStoreConfig(o);
+  const root = o.demo ? DEMO_DIR : process.cwd();
+  const store = createStore(cfg, root);
+  try {
+    if (sub === 'add') {
+      const [file, body] = o.positional;
+      if (!file || !body) {
+        console.error('usage: projview comment add <file> "<body>" [--heading <id>] [--author <name>] [--persist | --store-url <url>]');
+        process.exit(1);
+      }
+      if (!isPersistent(cfg)) {
+        console.error('⚠ no persistent store - this comment will NOT be saved on exit. Re-run with --persist or --store-url <url>.');
+      }
+      if (!existsSync(path.resolve(root, file))) {
+        console.error(`note: "${file}" not found under ${root} - saving the comment anyway.`);
+      }
+      const anchor = o.heading ? { type: 'heading', id: o.heading } : { type: 'file' };
+      print(await store.addComment({ file, body, anchor, author: resolveAuthor(o.author) }));
+      return;
+    }
+    if (sub === 'resolve' || sub === 'reopen') {
+      const id = o.positional[0];
+      if (!id) { console.error(`usage: projview comment ${sub} <id> [--persist | --store-url <url>]`); process.exit(1); }
+      const c = await store.updateComment(id, { resolved: sub === 'resolve' });
+      if (!c) { console.error(`no comment with id ${id} in this store`); process.exit(1); }
+      print(c);
+      return;
+    }
+    if (sub === 'rm' || sub === 'delete') {
+      const id = o.positional[0];
+      if (!id) { console.error('usage: projview comment rm <id> [--persist | --store-url <url>]'); process.exit(1); }
+      if (!(await store.deleteComment(id))) { console.error(`no comment with id ${id} in this store`); process.exit(1); }
+      print({ deleted: id });
+      return;
+    }
+    console.error('usage: projview comment <add|resolve|reopen|rm> ...');
+    process.exit(1);
+  } finally {
+    await store.close();
+  }
+}
+
+// projview comments [file]   -> list comments (all, or for one file) as JSON
+async function cmdComments(args) {
+  const o = parseSubArgs(args);
+  const root = o.demo ? DEMO_DIR : process.cwd();
+  const store = createStore(resolveStoreConfig(o), root);
+  const list = await store.listComments(o.positional[0]);
+  await store.close();
+  print(list);
+}
+
+// projview usage [path]   -> aggregated usage stats (views / searches) as JSON
+async function cmdUsage(args) {
+  const o = parseSubArgs(args);
+  const store = createStore(resolveStoreConfig(o), subRoot(o, 0));
+  const stats = await store.usageStats();
+  await store.close();
+  print(stats);
+}
+
 function openBrowser(url) {
   const cmd = process.platform === 'darwin' ? 'open'
     : process.platform === 'win32' ? 'cmd' : 'xdg-open';
@@ -92,9 +165,13 @@ function openBrowser(url) {
 const HELP = `projview - ephemeral previewer for markdown + mermaid
 
 usage:
-  projview [path] [options]            start the viewer (default)
-  projview search <query> [path]       print ranked search results as JSON
-  projview tree [path]                 print the file tree as JSON
+  projview [path] [options]                start the viewer (default)
+  projview search <query> [path]           print ranked search results as JSON
+  projview tree [path]                     print the file tree as JSON
+  projview comment add <file> "<text>"     leave a comment (--heading <id> for a section)
+  projview comments [file]                 list comments as JSON
+  projview comment resolve|reopen|rm <id>  resolve, reopen, or delete a comment
+  projview usage [path]                    print usage stats (views / searches) as JSON
 
   (subcommands print to stdout and exit - no server. --demo works with them too,
    e.g. projview search "websockets" --demo)
@@ -109,11 +186,14 @@ options:
       --persist       keep the index in ~/.projview/cache and reuse it next run
       --store <kind>  store backend: memory | superlite | lite  (default: memory)
       --store-url <url>  custom store: sqlite://<file> or postgres://<...>  (or set DATABASE_URL)
+      --heading <id>  (comment add) anchor the comment to a heading/section id
+      --author <name> (comment add) author to record (default: git/OS user)
   -v, --version       print the version and exit
   -h, --help          show this help
 
 ephemeral by default - nothing is persisted unless you opt in with --persist /
---store / --store-url. ctrl-c removes any ephemeral store.`;
+--store / --store-url. ctrl-c removes any ephemeral store. Comments + usage need a
+persistent store to survive (you'll be warned when adding a comment without one).`;
 
 async function main() {
   const argv = process.argv.slice(2);
@@ -121,6 +201,9 @@ async function main() {
   // machine subcommands -> JSON to stdout, then exit (no server)
   if (argv[0] === 'search') return cmdSearch(argv.slice(1));
   if (argv[0] === 'tree') return cmdTree(argv.slice(1));
+  if (argv[0] === 'comment') return cmdComment(argv.slice(1));
+  if (argv[0] === 'comments') return cmdComments(argv.slice(1));
+  if (argv[0] === 'usage') return cmdUsage(argv.slice(1));
 
   const opts = parseArgs(argv);
   if (opts.help) { console.log(HELP); return; }
@@ -131,13 +214,14 @@ async function main() {
   }
 
   const storeConfig = resolveStoreConfig(opts);
-  const { port, close, storeInfo } = await startServer(opts.root, { port: opts.port, host: opts.host, store: storeConfig });
+  const { port, close, storeInfo, writable } = await startServer(opts.root, { port: opts.port, host: opts.host, store: storeConfig });
   const url = `http://${opts.host}:${port}`;
 
   console.log(`\n  projview  ->  ${url}`);
   console.log(`  indexing  ->  ${opts.root}`);
   console.log(`  store     ->  ${storeInfo.describe}`);
   if (storeInfo.warm) console.log(`  warm      ->  reused cache, reindexed ${storeInfo.reindexed}/${storeInfo.total} changed`);
+  if (!writable) console.log(`  comments  ->  read-only (exposed on ${opts.host})`);
   console.log(`  (ctrl-c to stop)\n`);
 
   if (opts.open) openBrowser(url);

package/docs/how-to-set-up.md

@@ -11,7 +11,7 @@ previewer for markdown + mermaid files.
 
 | need | version |
 | --- | --- |
-| Node.js | **18+** |
+| Node.js | **22+** (the `lite` sqlite store uses the built-in `node:sqlite`) |
 | npm | ships with Node |
 
 No build step. By default indexing is in-memory and nothing is written to disk -
@@ -67,7 +67,7 @@ npm install
 npm run demo                 # preview the bundled docs/  (alias for --demo)
 npm start                    # index the current directory
 node bin/projview.js ./docs  # or call the CLI directly
-npm test                     # run the test suite (node:test, 29 tests)
+npm test                     # run the test suite (node:test, 45 tests)
 ```
 
 See the [project README](README.md) for the architecture and the
@@ -82,10 +82,15 @@ See the [project README](README.md) for the architecture and the
 | `projview [path]` | start the viewer (default) |
 | `projview search <query> [path]` | print ranked search results as JSON, then exit |
 | `projview tree [path]` | print the file tree as JSON, then exit |
+| `projview comment add <file> "<body>"` | leave a comment (`--heading <id>` for a section) |
+| `projview comments [file]` | list comments as JSON |
+| `projview comment resolve\|reopen\|rm <id>` | resolve, reopen, or delete a comment |
+| `projview usage [path]` | print usage stats (views / searches) as JSON |
 
-The `search` and `tree` subcommands are projview's **machine interface** - JSON on
-stdout, no server, no browser - built for agents and scripts. See
-[ai-tests/search.md](ai-tests/search.md) for a worked test.
+The subcommands are projview's **machine interface** - JSON on stdout, no server,
+no browser - built for agents and scripts. `search`/`tree` are read-only;
+`comment` writes ride a persistent store (you're warned if you comment without
+one). See [ai-tests/search.md](ai-tests/search.md) for a worked test.
 
 **Options**
 
@@ -98,6 +103,8 @@ stdout, no server, no browser - built for agents and scripts. See
 | `--persist` | keep the index in `~/.projview/cache` and reuse it next run |
 | `--store <kind>` | store backend: `memory` \| `superlite` \| `lite` (default: `memory`; `lite` when `--persist`) |
 | `--store-url <url>` | use a custom store: `sqlite://<file>` or `postgres://<...>` |
+| `--heading <id>` | (`comment add`) anchor the comment to a heading/section id |
+| `--author <name>` | (`comment add`) author to record (default: git/OS user) |
 | `-v`, `--version` | print the version and exit |
 | `-h`, `--help` | show help |
 
@@ -113,8 +120,9 @@ stdout, no server, no browser - built for agents and scripts. See
 
 ## persistence & stores
 
-By default projview is **ephemeral** - the index lives in memory and nothing is
-written to disk. Opt in to persistence when you want a faster warm start or a
+By default projview is **ephemeral** - the index (plus any comments and usage
+events) lives in memory and nothing is written to disk. Opt in to persistence
+when you want a faster warm start, comments that survive a restart, or a
 queryable store an AI can read:
 
 | backend | what | how |

package/docs/reference/api.md

@@ -5,7 +5,8 @@ and scroll-spy (the active section should track as you scroll).
 
 ## overview
 
-projview exposes a tiny HTTP surface. Everything is read-only and in-memory.
+projview exposes a tiny HTTP surface. It never writes your files - the only
+state it records is its own usage events (views / searches) into the store.
 
 ## endpoints
 
@@ -37,6 +38,35 @@ line-numbered snippets. See [the AI search test](../ai-tests/search.md).
 `projview tree [path]` returns `{ root, files, tree[] }` - the same structure
 `/api/tree` serves.
 
+### projview comment
+
+Leave / manage comments (they ride a persistent store - use `--persist` or
+`--store-url`, else you'll be warned the comment won't survive exit):
+
+| command | meaning |
+| --- | --- |
+| `projview comment add <file> "<body>"` | add a comment (whole file) |
+| `projview comment add <file> "<body>" --heading <id>` | anchor it to a section |
+| `projview comment resolve\|reopen <id>` | toggle resolved |
+| `projview comment rm <id>` | delete it |
+
+`--author <name>` overrides the recorded author (default: git/OS user). Agents
+pass e.g. `--author claude` so AI-authored comments are distinguishable. A
+comment is `{ id, file, anchor, body, author, createdAt, resolved }`; the
+`anchor` is `{type:'file'}`, `{type:'heading', id}`, or a `{type:'text', exact,
+prefix, suffix, section}` quote selector (text anchors come from the viewer).
+
+### projview comments
+
+`projview comments [file]` lists comments as JSON - all of them, or just one
+file's.
+
+### projview usage
+
+`projview usage [path]` returns `{ total, byType, topFiles[], recentSearches[] }`.
+The viewer records a `view` per file opened and a `search` per query, so usage
+accumulates over a session (persisted only with a persistent store).
+
 ## the walker
 
 ### ignored directories
@@ -87,8 +117,9 @@ A chokidar watcher broadcasts change/tree events over SSE.
 
 ## stores (persistence)
 
-The index is in-memory by default (ephemeral). Opt into a pluggable store with
-`--persist` / `--store` / `--store-url`:
+The index - plus **comments** and **usage events** - is in-memory by default
+(ephemeral). Opt into a pluggable store with `--persist` / `--store` /
+`--store-url` so comments and usage survive a restart:
 
 ### backends
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projview",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Ephemeral local previewer for markdown + mermaid files in any directory",
   "type": "module",
   "bin": {

package/public/comments.js

@@ -0,0 +1,400 @@
+/* comments: a right-side drawer + inline anchoring.
+ *
+ * Anchors come in three flavours (see src/store.js): whole-file, a heading
+ * (section), or a text quote. Text quotes are re-anchored on every render via a
+ * {exact, prefix, suffix} selector - if the text moved we re-find it, if it
+ * vanished the comment is flagged "orphaned" (never lost). Highlights paint with
+ * the CSS Custom Highlight API (no DOM mutation), so the TOC / search / mermaid
+ * are untouched. Writes are hidden when the server says it isn't writable. */
+
+import { $, esc } from './dom.js';
+import { state } from './store.js';
+import { toast } from './toast.js';
+
+const contentEl = $('content');
+const viewerEl = $('viewer');
+const HL = typeof CSS !== 'undefined' && CSS.highlights;   // Custom Highlight API?
+
+let current = [];          // comments for the current file
+const ranges = new Map();  // id -> resolved Range (text anchors only)
+let activeId = null;
+let pending = null;        // { anchor, quote } while composing a new comment
+
+/* ---------------- scaffold (built once) ---------------- */
+
+const cre = (tag, cls, html) => {
+  const e = document.createElement(tag);
+  if (cls) e.className = cls;
+  if (html != null) e.innerHTML = html;
+  return e;
+};
+
+const fab = cre('button', 'cmt-fab', '💬<span class="cmt-badge" hidden>0</span>');
+fab.title = 'comments';
+fab.hidden = true;
+
+const drawer = cre('aside', 'cmt-drawer');
+drawer.hidden = true;
+drawer.innerHTML =
+  `<header class="cmt-drawer-head">
+     <div><strong>comments</strong> <span class="cmt-file"></span></div>
+     <div class="cmt-head-btns">
+       <button class="cmt-add-file" title="note on the whole file">+ note</button>
+       <button class="cmt-close" title="close">✕</button>
+     </div>
+   </header>
+   <div class="cmt-composer-slot"></div>
+   <div class="cmt-list"></div>`;
+
+const chip = cre('button', 'cmt-selchip', '💬 comment');
+chip.hidden = true;
+
+document.body.append(fab, drawer, chip);
+
+const listEl = drawer.querySelector('.cmt-list');
+const composerSlot = drawer.querySelector('.cmt-composer-slot');
+const fileEl = drawer.querySelector('.cmt-file');
+const addFileBtn = drawer.querySelector('.cmt-add-file');
+
+fab.addEventListener('click', () => toggleDrawer());
+drawer.querySelector('.cmt-close').addEventListener('click', () => toggleDrawer(false));
+addFileBtn.addEventListener('click', () => startCompose({ type: 'file' }, null));
+
+/* ---------------- public entry points ---------------- */
+
+// Called by the viewer after a file renders: load + anchor + paint + list.
+export async function onFileRendered(path) {
+  pending = null;
+  activeId = null;
+  if (!path) { fab.hidden = true; clearPaint(); return; }
+  await loadComments(path);
+  fileEl.textContent = path.split('/').pop();
+  reanchor();
+  renderComposer();
+  renderList();
+  addHeadingAffordances();
+  fab.hidden = false;
+}
+
+// Called on an SSE 'comments' event: refresh data + markers without touching the
+// document render or an open composer.
+export async function refreshComments() {
+  if (!state.currentPath) return;
+  await loadComments(state.currentPath);
+  reanchor();
+  renderList();
+}
+
+/* ---------------- data ---------------- */
+
+async function loadComments(path) {
+  try {
+    const res = await fetch(`/api/comments?file=${encodeURIComponent(path)}`);
+    current = res.ok ? await res.json() : [];
+  } catch { current = []; }
+  updateBadge();
+}
+
+async function api(method, url, body) {
+  const res = await fetch(url, {
+    method,
+    headers: body ? { 'content-type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined
+  });
+  if (!res.ok) { toast(res.status === 403 ? 'comments are read-only here' : 'comment failed'); return null; }
+  return res.json();
+}
+
+async function submitCompose(body) {
+  if (!body.trim() || !pending) return;
+  const created = await api('POST', '/api/comments', { file: state.currentPath, body: body.trim(), anchor: pending.anchor });
+  if (!created) return;
+  pending = null;
+  await refreshComments();
+  renderComposer();
+  openComment(created.id);
+}
+
+async function setResolved(id, resolved) {
+  const c = await api('PATCH', `/api/comments/${encodeURIComponent(id)}`, { resolved });
+  if (c) await refreshComments();
+}
+
+async function remove(id) {
+  const r = await api('DELETE', `/api/comments/${encodeURIComponent(id)}`);
+  if (r) { if (activeId === id) activeId = null; await refreshComments(); }
+}
+
+/* ---------------- re-anchoring engine ---------------- */
+
+// Flat text of the content + a map from string offset -> text node.
+function segments() {
+  const segs = [];
+  let text = '';
+  const walker = document.createTreeWalker(contentEl, NodeFilter.SHOW_TEXT);
+  let node;
+  while ((node = walker.nextNode())) {
+    segs.push({ node, start: text.length });
+    text += node.nodeValue;
+  }
+  return { text, segs };
+}
+
+function pointAt(segs, offset) {
+  for (const s of segs) {
+    if (offset <= s.start + s.node.nodeValue.length) return { node: s.node, offset: Math.max(0, offset - s.start) };
+  }
+  const last = segs[segs.length - 1];
+  return last ? { node: last.node, offset: last.node.nodeValue.length } : null;
+}
+
+const commonPrefix = (a, b) => { let i = 0; while (i < a.length && i < b.length && a[i] === b[i]) i++; return i; };
+const commonSuffix = (a, b) => { let i = 0; while (i < a.length && i < b.length && a[a.length - 1 - i] === b[b.length - 1 - i]) i++; return i; };
+
+// Resolve a {exact, prefix, suffix} quote selector to a Range, disambiguating
+// repeats by surrounding context. Returns null if `exact` isn't present.
+function resolveText(anchor, ctx) {
+  const { text } = ctx;
+  const exact = anchor.exact || '';
+  if (!exact) return null;
+  let best = -1, bestScore = -1;
+  let idx = text.indexOf(exact);
+  while (idx !== -1) {
+    const before = text.slice(Math.max(0, idx - (anchor.prefix?.length || 0)), idx);
+    const after = text.slice(idx + exact.length, idx + exact.length + (anchor.suffix?.length || 0));
+    const score = commonSuffix(before, anchor.prefix || '') + commonPrefix(after, anchor.suffix || '');
+    if (score > bestScore) { bestScore = score; best = idx; }
+    idx = text.indexOf(exact, idx + 1);
+  }
+  if (best === -1) return null;
+  const a = pointAt(ctx.segs, best);
+  const b = pointAt(ctx.segs, best + exact.length);
+  if (!a || !b) return null;
+  const range = document.createRange();
+  try { range.setStart(a.node, a.offset); range.setEnd(b.node, b.offset); } catch { return null; }
+  return range;
+}
+
+function reanchor() {
+  ranges.clear();
+  const ctx = segments();
+  for (const c of current) {
+    c._orphan = false;
+    if (c.anchor?.type === 'text') {
+      const r = resolveText(c.anchor, ctx);
+      if (r) ranges.set(c.id, r); else c._orphan = true;
+    }
+  }
+  paint();
+}
+
+function paint() {
+  if (!HL) return;
+  CSS.highlights.set('pv-comment', new Highlight(...[...ranges.values()]));
+  const act = activeId && ranges.get(activeId);
+  CSS.highlights.set('pv-comment-active', act ? new Highlight(act) : new Highlight());
+}
+function clearPaint() { if (HL) { CSS.highlights.delete('pv-comment'); CSS.highlights.delete('pv-comment-active'); } ranges.clear(); }
+
+/* ---------------- inline affordances ---------------- */
+
+// Click inside the content: if it lands on a highlighted quote, open that comment.
+contentEl.addEventListener('click', (e) => {
+  if (!ranges.size || !document.caretRangeFromPoint) return;
+  const caret = document.caretRangeFromPoint(e.clientX, e.clientY);
+  if (!caret) return;
+  for (const [id, r] of ranges) {
+    try { if (r.isPointInRange(caret.startContainer, caret.startOffset)) { openComment(id); return; } } catch { /* different root */ }
+  }
+});
+
+// A hover "💬" at the end of every heading -> comment on that section.
+function addHeadingAffordances() {
+  if (!state.writable) return;
+  for (const h of contentEl.querySelectorAll('h1, h2, h3')) {
+    if (!h.id || h.querySelector('.cmt-head-add')) continue;
+    const label = h.textContent;
+    const b = cre('button', 'cmt-head-add');           // text comes from CSS (keeps h.textContent clean)
+    b.title = 'comment on this section';
+    b.addEventListener('click', (ev) => { ev.stopPropagation(); startCompose({ type: 'heading', id: h.id }, label); });
+    h.appendChild(b);
+  }
+}
+
+// Text selection -> a floating "comment" chip near the selection.
+viewerEl.addEventListener('mouseup', () => {
+  if (!state.writable) { chip.hidden = true; return; }
+  const sel = window.getSelection();
+  if (!sel || sel.isCollapsed || !sel.toString().trim()) { chip.hidden = true; return; }
+  const range = sel.getRangeAt(0);
+  if (!contentEl.contains(range.commonAncestorContainer)) { chip.hidden = true; return; }
+  const rect = range.getBoundingClientRect();
+  chip.style.top = `${Math.max(8, rect.top - 40)}px`;
+  chip.style.left = `${rect.left}px`;
+  chip.hidden = false;
+});
+chip.addEventListener('mousedown', (e) => e.preventDefault());   // don't clear the selection
+chip.addEventListener('click', () => {
+  const anchor = captureTextAnchor();
+  chip.hidden = true;
+  if (anchor) startCompose(anchor, anchor.exact);
+  else toast('select some text first');
+});
+document.addEventListener('mousedown', (e) => { if (e.target !== chip && !chip.hidden) chip.hidden = true; });
+
+function captureTextAnchor() {
+  const sel = window.getSelection();
+  if (!sel || sel.isCollapsed) return null;
+  const range = sel.getRangeAt(0);
+  if (!contentEl.contains(range.commonAncestorContainer)) return null;
+  const exact = sel.toString();
+  const flat = contentEl.textContent;
+  const pre = document.createRange();
+  pre.setStart(contentEl, 0);
+  pre.setEnd(range.startContainer, range.startOffset);
+  const startOff = pre.toString().length;
+  const endOff = startOff + exact.length;
+  return {
+    type: 'text',
+    exact,
+    prefix: flat.slice(Math.max(0, startOff - 32), startOff),
+    suffix: flat.slice(endOff, endOff + 32),
+    section: nearestHeadingId(range)
+  };
+}
+
+function nearestHeadingId(range) {
+  const top = range.getBoundingClientRect().top;
+  let id = null;
+  for (const h of contentEl.querySelectorAll('h1, h2, h3')) {
+    if (!h.id) continue;
+    if (h.getBoundingClientRect().top <= top) id = h.id; else break;
+  }
+  return id;
+}
+
+/* ---------------- composer + list ---------------- */
+
+function startCompose(anchor, quote) {
+  if (!state.writable) { toast('comments are read-only here'); return; }
+  pending = { anchor, quote };
+  toggleDrawer(true);
+  renderComposer();
+  const ta = composerSlot.querySelector('textarea');
+  if (ta) ta.focus();
+}
+
+function renderComposer() {
+  composerSlot.replaceChildren();
+  if (!pending || !state.writable) return;
+  const box = cre('div', 'cmt-composer');
+  box.append(cre('div', 'cmt-anchor-chip', anchorLabel(pending.anchor, pending.quote)));
+  const ta = cre('textarea');
+  ta.placeholder = 'add a comment…';
+  ta.rows = 3;
+  const actions = cre('div', 'cmt-composer-actions');
+  const save = cre('button', 'cmt-btn primary', 'comment');
+  const cancel = cre('button', 'cmt-btn', 'cancel');
+  save.addEventListener('click', () => submitCompose(ta.value));
+  cancel.addEventListener('click', () => { pending = null; renderComposer(); });
+  ta.addEventListener('keydown', (e) => { if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) submitCompose(ta.value); });
+  actions.append(save, cancel);
+  box.append(ta, actions);
+  composerSlot.append(box);
+}
+
+function renderList() {
+  listEl.replaceChildren();
+  if (!current.length) {
+    listEl.append(cre('div', 'cmt-empty', '💭<br>no comments yet' + (state.writable ? '<br><small>select text, hover a heading, or “+ note”</small>' : '')));
+    return;
+  }
+  for (const c of current) {
+    const card = cre('div', 'cmt-card' + (c.resolved ? ' resolved' : '') + (c._orphan ? ' orphan' : '') + (c.id === activeId ? ' active' : ''));
+    card.dataset.id = c.id;
+    const meta = cre('div', 'cmt-meta',
+      `<span class="cmt-author">${esc(c.author || 'anon')}</span><span class="cmt-time">${ago(c.createdAt)}</span>`);
+    const chipEl = cre('div', 'cmt-anchor-chip' + (c._orphan ? ' orphan' : ''), anchorLabel(c.anchor) + (c._orphan ? ' · not found' : ''));
+    const bodyEl = cre('div', 'cmt-body', esc(c.body).replace(/\n/g, '<br>'));
+    card.append(meta, chipEl, bodyEl);
+    if (state.writable) {
+      const actions = cre('div', 'cmt-actions');
+      const res = cre('button', 'cmt-link', c.resolved ? 'reopen' : 'resolve');
+      const del = cre('button', 'cmt-link danger', 'delete');
+      res.addEventListener('click', (e) => { e.stopPropagation(); setResolved(c.id, !c.resolved); });
+      del.addEventListener('click', (e) => { e.stopPropagation(); remove(c.id); });
+      actions.append(res, del);
+      card.append(actions);
+    }
+    card.addEventListener('click', () => openComment(c.id));
+    listEl.append(card);
+  }
+}
+
+/* ---------------- navigation ---------------- */
+
+function openComment(id) {
+  activeId = id;
+  toggleDrawer(true);
+  paint();
+  renderList();
+  const card = listEl.querySelector(`.cmt-card[data-id="${CSS.escape(id)}"]`);
+  if (card) card.scrollIntoView({ block: 'nearest' });
+  const c = current.find((x) => x.id === id);
+  if (c) jumpToAnchor(c);
+}
+
+function jumpToAnchor(c) {
+  const a = c.anchor || {};
+  if (a.type === 'text') {
+    const r = ranges.get(c.id);
+    if (r) { scrollRangeIntoView(r); return; }
+    if (a.section) { document.getElementById(a.section)?.scrollIntoView({ block: 'start' }); return; }
+    toast('original text not found - comment is orphaned');
+  } else if (a.type === 'heading') {
+    const el = document.getElementById(a.id);
+    if (el) el.scrollIntoView({ block: 'start' }); else toast('section no longer exists');
+  } else {
+    viewerEl.scrollTop = 0;
+  }
+}
+
+function scrollRangeIntoView(range) {
+  const r = range.getBoundingClientRect();
+  const v = viewerEl.getBoundingClientRect();
+  if (r.height || r.width) viewerEl.scrollTop += (r.top - v.top) - 120;
+}
+
+/* ---------------- bits ---------------- */
+
+function toggleDrawer(force) {
+  const open = force === undefined ? drawer.hidden : force;
+  drawer.hidden = !open;
+  fab.classList.toggle('open', open);
+}
+
+function updateBadge() {
+  const open = current.filter((c) => !c.resolved).length;
+  const badge = fab.querySelector('.cmt-badge');
+  badge.textContent = String(open);
+  badge.hidden = open === 0;
+}
+
+function anchorLabel(a, quoteOverride) {
+  if (!a) return 'file';
+  if (a.type === 'file') return '📄 whole file';
+  if (a.type === 'heading') {
+    const el = document.getElementById(a.id);
+    return '§ ' + (quoteOverride || (el ? el.textContent : a.id));
+  }
+  const q = (quoteOverride || a.exact || '').replace(/\s+/g, ' ').trim();
+  return '“' + (q.length > 60 ? q.slice(0, 60) + '…' : q) + '”';
+}
+
+function ago(ts) {
+  const s = Math.max(0, (Date.now() - ts) / 1000);
+  if (s < 60) return 'just now';
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86400)}d ago`;
+}