projview 0.6.0 → 0.8.0

package/public/live.js

@@ -4,6 +4,7 @@ import { $ } from './dom.js';
 import { state } from './store.js';
 import { loadTree } from './tree.js';
 import { openFile } from './viewer.js';
+import { refreshComments } from './comments.js';
 
 const versionEl = $('version');
 
@@ -14,6 +15,10 @@ export function connectEvents() {
     if (path === state.currentPath) { pulse(); openFile(path); }
   });
   es.addEventListener('tree', async () => { pulse(); await loadTree(); });
+  es.addEventListener('comments', (e) => {
+    const { file } = JSON.parse(e.data || '{}');
+    if (!file || file === state.currentPath) refreshComments();
+  });
 }
 
 // brief flash of the version line as live-reload feedback

package/public/main.js

@@ -10,6 +10,7 @@ import './links.js';
 import './toc.js';
 import './mermaid.js';
 import './search.js';
+import './comments.js';
 
 // browser back / forward
 window.addEventListener('hashchange', () => {

package/public/store.js

@@ -4,5 +4,6 @@ export const state = {
   currentPath: null,        // path of the file currently shown
   expanded: new Set(),      // dir paths the user has opened
   treeData: [],             // last tree payload from the server
-  rootName: 'projview'      // indexed root's display name
+  rootName: 'projview',     // indexed root's display name
+  writable: false           // can this client create/edit comments? (loopback only)
 };

package/public/style.css

@@ -530,3 +530,107 @@ mark.search-hit {
 ::-webkit-scrollbar-thumb { background: var(--surface1); border-radius: 20px; border: 2px solid var(--mantle); }
 ::-webkit-scrollbar-thumb:hover { background: var(--surface2); }
 ::-webkit-scrollbar-track { background: transparent; }
+
+/* ---------------- comments ---------------- */
+
+::highlight(pv-comment) { background-color: color-mix(in srgb, var(--mauve) 26%, transparent); border-radius: 3px; }
+::highlight(pv-comment-active) { background-color: color-mix(in srgb, var(--peach) 42%, transparent); }
+
+.cmt-fab {
+  position: fixed; bottom: 22px; right: 22px; z-index: 30;
+  width: 52px; height: 52px; border-radius: 50%;
+  border: 2px solid var(--surface1); background: var(--mauve); color: var(--crust);
+  font-size: 21px; cursor: pointer; box-shadow: var(--shadow);
+  display: flex; align-items: center; justify-content: center;
+  transition: transform 0.15s ease, background 0.15s ease;
+}
+.cmt-fab:hover { transform: translateY(-2px); }
+.cmt-fab.open { background: var(--lavender); }
+.cmt-fab[hidden] { display: none; }
+.cmt-badge {
+  position: absolute; top: -4px; right: -4px;
+  min-width: 20px; height: 20px; padding: 0 5px; border-radius: 10px;
+  background: var(--red); color: var(--crust);
+  font-size: 11px; font-weight: 800; line-height: 20px; border: 2px solid var(--base);
+}
+
+.cmt-drawer {
+  position: fixed; top: 0; right: 0; z-index: 29;
+  width: 360px; max-width: 90vw; height: 100vh;
+  background: var(--mantle); border-left: 2px solid var(--surface0);
+  box-shadow: -8px 0 28px rgba(0, 0, 0, 0.4);
+  display: flex; flex-direction: column;
+}
+.cmt-drawer[hidden] { display: none; }
+.cmt-drawer-head {
+  display: flex; align-items: center; justify-content: space-between; gap: 8px;
+  padding: 16px 16px 12px; border-bottom: 2px solid var(--surface0);
+}
+.cmt-drawer-head strong { color: var(--mauve); }
+.cmt-file { color: var(--overlay); font-size: 12px; }
+.cmt-head-btns { display: flex; gap: 6px; }
+.cmt-add-file, .cmt-close {
+  background: var(--surface0); border: none; color: var(--subtext);
+  border-radius: 8px; padding: 5px 9px; cursor: pointer; font: inherit; font-size: 12px;
+}
+.cmt-add-file:hover { background: var(--surface1); color: var(--green); }
+.cmt-close:hover { background: var(--surface1); color: var(--text); }
+
+.cmt-composer-slot:not(:empty) { padding: 12px; border-bottom: 1px solid var(--surface0); }
+.cmt-composer { display: flex; flex-direction: column; gap: 8px; }
+.cmt-composer textarea {
+  width: 100%; resize: vertical; background: var(--base); color: var(--text);
+  border: 2px solid var(--surface1); border-radius: var(--radius-sm);
+  padding: 8px 10px; font: inherit; font-size: 13px;
+}
+.cmt-composer textarea:focus { outline: none; border-color: var(--mauve); }
+.cmt-composer-actions { display: flex; gap: 8px; }
+.cmt-btn {
+  border: 2px solid var(--surface1); background: var(--surface0); color: var(--subtext);
+  border-radius: 8px; padding: 5px 12px; cursor: pointer; font: inherit; font-size: 12.5px;
+}
+.cmt-btn:hover { color: var(--text); }
+.cmt-btn.primary { background: var(--mauve); border-color: var(--mauve); color: var(--crust); font-weight: 700; }
+.cmt-btn.primary:hover { background: var(--lavender); border-color: var(--lavender); }
+
+.cmt-list { flex: 1; overflow-y: auto; padding: 10px 12px 24px; display: flex; flex-direction: column; gap: 10px; }
+.cmt-empty { text-align: center; color: var(--overlay); padding: 36px 10px; font-size: 13px; line-height: 1.9; }
+.cmt-card {
+  background: var(--base); border: 2px solid var(--surface0); border-radius: var(--radius-sm);
+  padding: 10px 12px; cursor: pointer; transition: border-color 0.12s ease;
+}
+.cmt-card:hover { border-color: var(--surface2); }
+.cmt-card.active { border-color: var(--peach); }
+.cmt-card.resolved { opacity: 0.6; }
+.cmt-card.resolved .cmt-body { text-decoration: line-through; text-decoration-color: var(--overlay); }
+.cmt-card.orphan { border-style: dashed; }
+.cmt-meta { display: flex; justify-content: space-between; align-items: baseline; font-size: 11.5px; margin-bottom: 6px; }
+.cmt-author { color: var(--blue); font-weight: 700; }
+.cmt-time { color: var(--overlay); }
+.cmt-anchor-chip {
+  display: block; background: var(--surface0); color: var(--subtext);
+  font-size: 11px; border-radius: 6px; padding: 3px 8px; margin-bottom: 7px;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.cmt-anchor-chip.orphan { color: var(--peach); }
+.cmt-body { font-size: 13px; color: var(--text); word-break: break-word; }
+.cmt-actions { display: flex; gap: 14px; margin-top: 9px; }
+.cmt-link { background: none; border: none; color: var(--overlay); cursor: pointer; font: inherit; font-size: 11.5px; padding: 0; }
+.cmt-link:hover { color: var(--lavender); }
+.cmt-link.danger:hover { color: var(--red); }
+
+.cmt-selchip {
+  position: fixed; z-index: 40; background: var(--mauve); color: var(--crust);
+  border: none; border-radius: 8px; padding: 5px 10px;
+  font: inherit; font-size: 12px; font-weight: 700; cursor: pointer; box-shadow: var(--shadow-sm);
+}
+.cmt-selchip:hover { background: var(--lavender); }
+
+.markdown-body h1, .markdown-body h2, .markdown-body h3 { position: relative; }
+.cmt-head-add {
+  border: none; background: none; cursor: pointer; font-size: 0.62em;
+  opacity: 0; margin-left: 8px; vertical-align: middle; transition: opacity 0.12s ease;
+}
+.cmt-head-add::before { content: '💬'; }
+h1:hover > .cmt-head-add, h2:hover > .cmt-head-add, h3:hover > .cmt-head-add { opacity: 0.5; }
+.cmt-head-add:hover { opacity: 1 !important; }

package/public/tree.js

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

package/public/viewer.js

@@ -7,6 +7,7 @@ import { renderBreadcrumb } from './breadcrumb.js';
 import { runMermaid } from './mermaid.js';
 import { buildToc } from './toc.js';
 import { toast } from './toast.js';
+import { onFileRendered } from './comments.js';
 
 const contentEl = $('content');
 const viewerEl = $('viewer');
@@ -31,6 +32,7 @@ export async function openFile(p, fragment, highlight) {
   contentEl.innerHTML = html;
   await runMermaid();
   buildToc();
+  onFileRendered(p);   // load + anchor + paint comments for this file
   if (fragment) scrollToFragment(fragment);
   else if (highlight) highlightInContent(highlight);
   else viewerEl.scrollTop = 0;
@@ -81,5 +83,6 @@ function showNotFound(p) {
     `<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();
+  onFileRendered(null);   // no file -> hide the comments affordances
   toast(`not found: ${p}`);
 }

package/src/server.js

@@ -8,7 +8,7 @@ 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 } from './store.js';
+import { createStore, gitOrOsUser } from './store.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PUBLIC_DIR = path.join(__dirname, '..', 'public');
@@ -47,8 +47,33 @@ function resolveInRoot(root, relPath) {
   return abs;
 }
 
+// Comment writes are allowed only when bound to loopback. A non-loopback bind
+// (e.g. 0.0.0.0 on the launchpad / in Docker) is treated as exposed -> read-only.
+export function isLoopbackHost(host) {
+  return ['127.0.0.1', '::1', 'localhost', ''].includes(host);
+}
+
+// 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) {
+  return new Promise((resolve) => {
+    let data = '';
+    let size = 0;
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > limit) { req.destroy(); resolve(null); return; }
+      data += chunk;
+    });
+    req.on('end', () => { try { resolve(JSON.parse(data || '{}')); } catch { resolve(null); } });
+    req.on('error', () => resolve(null));
+  });
+}
+
 export async function startServer(root, { port = 4321, host = '127.0.0.1', store: storeConfig } = {}) {
   const sseClients = new Set();
+  const allowWrites = isLoopbackHost(host);   // comments are read-only on an exposed host
+  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
 
   function broadcast(event, payload) {
     const frame = `event: ${event}\ndata: ${JSON.stringify(payload || {})}\n\n`;
@@ -74,13 +99,16 @@ 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 });
+      sendJson(res, { root: path.basename(root) || root, tree: buildTree(root), version: VERSION, writable: allowWrites });
       return;
     }
 
     // --- search (fuzzy filenames + full-text contents) ---
     if (pathname === '/api/search') {
-      sendJson(res, search(url.searchParams.get('q') || ''));
+      const q = url.searchParams.get('q') || '';
+      const results = search(q);
+      if (q.trim()) { try { await store.recordEvent({ type: 'search', query: q.trim(), count: results.files.length + results.content.length }); } catch { /* usage is best-effort */ } }
+      sendJson(res, results);
       return;
     }
 
@@ -94,6 +122,7 @@ export async function startServer(root, { port = 4321, host = '127.0.0.1', store
       }
       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) });
       } catch {
         sendJson(res, { error: 'not found' }, 404);
@@ -101,6 +130,54 @@ export async function startServer(root, { port = 4321, host = '127.0.0.1', store
       return;
     }
 
+    // --- comments: list (GET) + create (POST) ---
+    if (pathname === '/api/comments') {
+      if (req.method === 'POST') {
+        if (!allowWrites) return denyWrite(res);
+        const body = await readBody(req);
+        if (!body || !body.file || !body.body) { sendJson(res, { error: 'file and body are required' }, 400); return; }
+        const c = await store.addComment({ file: body.file, body: body.body, anchor: body.anchor, author: body.author || localAuthor });
+        broadcast('comments', { file: c.file });
+        sendJson(res, c, 201);
+        return;
+      }
+      sendJson(res, await store.listComments(url.searchParams.get('file') || undefined));
+      return;
+    }
+
+    // --- a single comment by id: resolve/edit (PATCH) + delete (DELETE) ---
+    if (pathname.startsWith('/api/comments/')) {
+      const id = decodeURIComponent(pathname.slice('/api/comments/'.length));
+      if (req.method === 'PATCH') {
+        if (!allowWrites) return denyWrite(res);
+        const body = await readBody(req);
+        if (!body) { sendJson(res, { error: 'invalid body' }, 400); return; }
+        const patch = {};
+        if (typeof body.resolved === 'boolean') patch.resolved = body.resolved;
+        if (typeof body.body === 'string') patch.body = body.body;
+        const c = await store.updateComment(id, patch);
+        if (!c) { sendJson(res, { error: 'not found' }, 404); return; }
+        broadcast('comments', { file: c.file });
+        sendJson(res, c);
+        return;
+      }
+      if (req.method === 'DELETE') {
+        if (!allowWrites) return denyWrite(res);
+        if (!(await store.deleteComment(id))) { sendJson(res, { error: 'not found' }, 404); return; }
+        broadcast('comments', {});
+        sendJson(res, { deleted: id });
+        return;
+      }
+      sendJson(res, { error: 'use PATCH or DELETE' }, 405);
+      return;
+    }
+
+    // --- usage stats ---
+    if (pathname === '/api/usage') {
+      sendJson(res, await store.usageStats());
+      return;
+    }
+
     // --- static SPA assets (incl. /vendor/*) ---
     const assetName = pathname === '/' ? 'index.html' : pathname.slice(1);
     const assetPath = resolveInRoot(PUBLIC_DIR, assetName);
@@ -152,6 +229,7 @@ export async function startServer(root, { port = 4321, host = '127.0.0.1', store
     server,
     port: listenPort,
     close,
+    writable: allowWrites,
     storeInfo: { describe: store.describe(), warm: indexInfo.warm, reindexed: indexInfo.reindexed, total: indexInfo.total }
   };
 }

package/src/store.js

@@ -1,20 +1,31 @@
-/* pluggable persistence for the index.
+/* pluggable persistence for the index, comments + usage.
  *
- * A Store persists indexed entries so a re-spawn can warm-start. Backends:
- *   memory    - no persistence (ephemeral default; nothing written)
+ * A Store persists three things so a re-spawn can warm-start and so comments /
+ * usage survive a session:
+ *   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? }
+ *
+ * Backends:
+ *   memory    - no disk persistence (ephemeral default; lives only this session)
  *   superlite - a JSON file
  *   lite      - sqlite via node:sqlite (built-in)
  *   custom    - a connection URL: sqlite://<file> or postgres://<...> (lazy `pg`)
  *
- * An entry is { path, name, ext, mtime, content }. Everything above the store
- * stays storage-agnostic - search still runs in memory over loaded entries.
+ * A comment's `anchor` is one of:
+ *   { type: 'file' }                                  whole document
+ *   { type: 'heading', id }                           a section (stable pv- id)
+ *   { type: 'text', exact, prefix, suffix, section }  a quoted range (re-anchored
+ *                                                      client-side; see 3c)
+ * Everything above the store stays storage-agnostic.
  */
 
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
-import { createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
 
 // node:sqlite is flagged "experimental" and emits a noisy warning on use; we
 // opted into it deliberately, so quiet just that one notice (others pass through).
@@ -33,6 +44,48 @@ const keyFor = (root) => createHash('sha256').update(path.resolve(root)).digest(
 const ensureDir = (d) => fs.mkdirSync(d, { recursive: true });
 const redact = (url) => url.replace(/\/\/[^@/]*@/, '//***@');   // hide creds in logs
 
+// Best-effort identity for comment authorship: git user.name, else OS username.
+export function gitOrOsUser() {
+  try { const n = execSync('git config user.name', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim(); if (n) return n; } catch { /* no git / no user.name */ }
+  try { return os.userInfo().username || null; } catch { return null; }
+}
+
+// Normalize loose input into a full comment / event record (defaults + ids).
+const newComment = (c) => ({
+  id: c.id || randomUUID(),
+  file: c.file,
+  anchor: c.anchor || { type: 'file' },
+  body: c.body,
+  author: c.author ?? null,
+  createdAt: c.createdAt || Date.now(),
+  resolved: !!c.resolved
+});
+const newEvent = (e) => ({
+  id: randomUUID(),
+  ts: e.ts || Date.now(),
+  type: e.type,
+  file: e.file ?? null,
+  query: e.query ?? null,
+  count: e.count ?? null
+});
+
+// Aggregate raw events into something a human / agent can read at a glance.
+function summarizeEvents(events) {
+  const byType = {};
+  const fileCounts = {};
+  const searches = [];
+  for (const e of events) {
+    byType[e.type] = (byType[e.type] || 0) + 1;
+    if (e.file) fileCounts[e.file] = (fileCounts[e.file] || 0) + 1;
+    if (e.type === 'search' && e.query) searches.push(e.query);
+  }
+  const topFiles = Object.entries(fileCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10)
+    .map(([file, count]) => ({ file, count }));
+  return { total: events.length, byType, topFiles, recentSearches: searches.slice(-10).reverse() };
+}
+
 function readConfigFile() {
   try { return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')); } catch { return {}; }
 }
@@ -65,21 +118,77 @@ export function createStore(config, root) {
   }
 }
 
+// True when a store keeps comments/usage across restarts. The CLI/server warn
+// when it's false so a comment isn't silently lost on exit.
+export function isPersistent(config) {
+  const cfg = config || { kind: 'memory' };
+  if (cfg.kind === 'memory') return false;
+  if (cfg.kind === 'custom') return true;             // the user's own DB
+  return !!cfg.persist;                                // superlite/lite: only with --persist
+}
+
 function fileFor(root, persist, ext) {
   const dir = persist ? CACHE_DIR : EPHEMERAL_DIR;
   ensureDir(dir);
   return path.join(dir, `${keyFor(root)}.${ext}`);
 }
 
+/* ---------- shared in-memory comment/event layer (memory + superlite) ---------- */
+
+// 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 () => {}) {
+  const comments = new Map();   // id -> comment
+  const events = [];            // append-only (stable ref - never reassigned)
+  return {
+    comments,
+    events,
+    async addComment(c) {
+      const comment = newComment(c);
+      comments.set(comment.id, comment);
+      await flush();
+      return comment;
+    },
+    async listComments(file) {
+      const all = [...comments.values()].sort((a, b) => a.createdAt - b.createdAt);
+      return file ? all.filter((c) => c.file === file) : all;
+    },
+    async updateComment(id, patch) {
+      const c = comments.get(id);
+      if (!c) return null;
+      Object.assign(c, patch, { id: c.id });   // id is immutable
+      await flush();
+      return c;
+    },
+    async deleteComment(id) {
+      const ok = comments.delete(id);
+      await flush();
+      return ok;
+    },
+    async recordEvent(e) {
+      events.push(newEvent(e));
+      await flush();
+    },
+    async usageStats() { return summarizeEvents(events); }
+  };
+}
+
 /* ---------- backends ---------- */
 
 function memoryStore() {
+  const docs = inMemoryDocs();
   return {
     kind: 'memory',
     async load() { return null; },
     async save() {},
     async update() {},
     async remove() {},
+    addComment: docs.addComment,
+    listComments: docs.listComments,
+    updateComment: docs.updateComment,
+    deleteComment: docs.deleteComment,
+    recordEvent: docs.recordEvent,
+    usageStats: docs.usageStats,
     async close() {},
     describe() { return 'in-memory (ephemeral - nothing persisted)'; }
   };
@@ -87,29 +196,38 @@ function memoryStore() {
 
 function superliteStore(root, persist) {
   const file = fileFor(root, persist, 'json');
-  let map = null;   // path -> entry, lazily loaded
+  const entries = new Map();   // path -> entry
+  let loaded = false;
+  const flush = () => fsp.writeFile(file, JSON.stringify({
+    builtAt: Date.now(),
+    entries: [...entries.values()],
+    comments: [...docs.comments.values()],
+    events: docs.events
+  }));
+  const docs = inMemoryDocs(() => (loaded ? flush() : Promise.resolve()));
   const ensure = async () => {
-    if (map) return map;
+    if (loaded) return;
     try {
       const d = JSON.parse(await fsp.readFile(file, 'utf8'));
-      map = new Map((d.entries || []).map((e) => [e.path, e]));
-    } catch { map = new Map(); }
-    return map;
+      for (const e of d.entries || []) entries.set(e.path, e);
+      for (const c of d.comments || []) docs.comments.set(c.id, c);
+      for (const ev of d.events || []) docs.events.push(ev);
+    } catch { /* fresh */ }
+    loaded = true;
   };
-  const flush = () => fsp.writeFile(file, JSON.stringify({ builtAt: Date.now(), entries: [...map.values()] }));
   return {
     kind: 'superlite',
     file,
-    async load() {
-      const m = await ensure();
-      return m.size ? { entries: [...m.values()] } : null;
-    },
-    async save(entries) {
-      map = new Map(entries.map((e) => [e.path, e]));
-      await flush();
-    },
-    async update(entry) { (await ensure()).set(entry.path, entry); await flush(); },
-    async remove(p) { (await ensure()).delete(p); await flush(); },
+    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(); },
+    async remove(p) { await ensure(); entries.delete(p); await flush(); },
+    async addComment(c) { await ensure(); return docs.addComment(c); },
+    async listComments(f) { await ensure(); return docs.listComments(f); },
+    async updateComment(id, patch) { await ensure(); return docs.updateComment(id, patch); },
+    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 close({ keep } = {}) {
       if (!persist && !keep) { try { await fsp.unlink(file); } catch { /* gone */ } }
     },
@@ -120,13 +238,22 @@ function superliteStore(root, persist) {
 // sqlite-backed store at an explicit file. cleanup=true removes the file on close.
 function sqliteAt(file, { cleanup }) {
   let db = null;
+  const toComment = (r) => ({
+    id: r.id, file: r.file, anchor: JSON.parse(r.anchor || '{"type":"file"}'),
+    body: r.body, author: r.author, createdAt: r.createdAt, resolved: !!r.resolved
+  });
   const open = async () => {
     if (db) return db;
     const { DatabaseSync } = await import('node:sqlite');
     db = new DatabaseSync(file);
     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)');
     return db;
   };
+  const writeComment = (d, c) => d
+    .prepare('INSERT OR REPLACE INTO comments (id, file, anchor, body, author, createdAt, resolved) VALUES (?, ?, ?, ?, ?, ?, ?)')
+    .run(c.id, c.file, JSON.stringify(c.anchor), c.body, c.author, c.createdAt, c.resolved ? 1 : 0);
   return {
     kind: 'lite',
     file,
@@ -152,6 +279,41 @@ function sqliteAt(file, { cleanup }) {
       const d = await open();
       d.prepare('DELETE FROM files WHERE path = ?').run(p);
     },
+    async addComment(c) {
+      const d = await open();
+      const comment = newComment(c);
+      writeComment(d, comment);
+      return comment;
+    },
+    async listComments(file) {
+      const d = await open();
+      const rows = file
+        ? d.prepare('SELECT * FROM comments WHERE file = ? ORDER BY createdAt').all(file)
+        : d.prepare('SELECT * FROM comments ORDER BY createdAt').all();
+      return rows.map(toComment);
+    },
+    async updateComment(id, patch) {
+      const d = await open();
+      const row = d.prepare('SELECT * FROM comments WHERE id = ?').get(id);
+      if (!row) return null;
+      const c = { ...toComment(row), ...patch, id };
+      writeComment(d, c);
+      return c;
+    },
+    async deleteComment(id) {
+      const d = await open();
+      return d.prepare('DELETE FROM comments WHERE id = ?').run(id).changes > 0;
+    },
+    async recordEvent(e) {
+      const d = await open();
+      const ev = newEvent(e);
+      d.prepare('INSERT INTO events (id, ts, type, file, query, count) VALUES (?, ?, ?, ?, ?, ?)')
+        .run(ev.id, ev.ts, ev.type, ev.file, ev.query, ev.count);
+    },
+    async usageStats() {
+      const d = await open();
+      return summarizeEvents(d.prepare('SELECT type, file, query FROM events').all());
+    },
     async close({ keep } = {}) {
       if (db) { db.close(); db = null; }
       if (cleanup && !keep) { try { await fsp.unlink(file); } catch { /* gone */ } }
@@ -176,6 +338,11 @@ function customStore(url) {
 
 function postgresStore(url) {
   let client = null;
+  const toComment = (r) => ({
+    id: r.id, file: r.file,
+    anchor: typeof r.anchor === 'string' ? JSON.parse(r.anchor) : (r.anchor || { type: 'file' }),
+    body: r.body, author: r.author, createdAt: Number(r.createdat), resolved: !!r.resolved
+  });
   const open = async () => {
     if (client) return client;
     let pg;
@@ -183,11 +350,16 @@ function postgresStore(url) {
     catch { throw new Error('the postgres store needs the "pg" package - run: npm i pg'); }
     client = new pg.Client({ connectionString: url });
     await client.connect();
-    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_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)');
     return client;
   };
+  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',
+    [c.id, c.file, JSON.stringify(c.anchor), c.body, c.author, c.createdAt, c.resolved]
+  );
   return {
     kind: 'custom',
     async load() {
@@ -220,7 +392,43 @@ function postgresStore(url) {
       const c = await open();
       await c.query('DELETE FROM projview_files WHERE path = $1', [p]);
     },
-    async close() { if (client) { await client.end(); client = null; } },   // never drop the user's table
+    async addComment(c) {
+      await open();
+      const comment = newComment(c);
+      await writeComment(comment);
+      return comment;
+    },
+    async listComments(file) {
+      const c = await open();
+      const { rows } = file
+        ? await c.query('SELECT * FROM projview_comments WHERE file = $1 ORDER BY createdat', [file])
+        : await c.query('SELECT * FROM projview_comments ORDER BY createdat');
+      return rows.map(toComment);
+    },
+    async updateComment(id, patch) {
+      const c = await open();
+      const { rows } = await c.query('SELECT * FROM projview_comments WHERE id = $1', [id]);
+      if (!rows.length) return null;
+      const merged = { ...toComment(rows[0]), ...patch, id };
+      await writeComment(merged);
+      return merged;
+    },
+    async deleteComment(id) {
+      const c = await open();
+      return (await c.query('DELETE FROM projview_comments WHERE id = $1', [id])).rowCount > 0;
+    },
+    async recordEvent(e) {
+      const c = await open();
+      const ev = newEvent(e);
+      await c.query('INSERT INTO projview_events (id, ts, type, file, query, count) VALUES ($1, $2, $3, $4, $5, $6)',
+        [ev.id, ev.ts, ev.type, ev.file, ev.query, ev.count]);
+    },
+    async usageStats() {
+      const c = await open();
+      const { rows } = await c.query('SELECT type, file, query FROM projview_events');
+      return summarizeEvents(rows);
+    },
+    async close() { if (client) { await client.end(); client = null; } },   // never drop the user's tables
     describe() { return `custom/postgres ${redact(url)}`; }
   };
 }