projview 0.7.0 → 0.8.1

package/README.md

@@ -34,6 +34,9 @@ and exit (no server, no browser), so an agent or script can query your docs:
 ```bash
 projview search "<query>" [path]   # ranked: filename matches + in-content hits w/ line snippets
 projview tree [path]               # the file tree as JSON
+projview comment add <file> "…"    # leave a comment (--heading <id> to anchor a section)
+projview comments [file]           # list comments as JSON
+projview usage [path]              # views + searches recorded by the viewer
 projview search "mermaid" --demo   # quick test on the bundled docs
 ```
 
@@ -53,9 +56,19 @@ projview search "mermaid" --demo   # quick test on the bundled docs
 | index | builds an in-memory tree (nothing written to disk by default) |
 | serve | spawns a localhost site + opens your browser |
 | live | edits to files reload in the browser automatically |
+| comment | leave notes on a file, a section, or a text selection (browser or CLI) |
 
 > ephemeral by default - ctrl-c and it's gone. opt into persistence below.
 
+## comments
+
+Leave notes on a whole file, a heading/section, or a selected passage - from the
+viewer (the 💬 button, bottom-right) or via the CLI / HTTP API. Text comments
+**re-anchor** as the doc changes and only flag themselves *orphaned* if the quoted
+text truly disappears. Comments persist when you opt into a store
+(`--persist` / `--store-url`); writes are **localhost-only** (an exposed instance
+is read-only).
+
 ## persistence (opt-in)
 
 By default the index is in-memory and nothing is written to disk. Opt in for a

package/bin/projview.js

@@ -1,13 +1,12 @@
 #!/usr/bin/env node
 import path from 'node:path';
-import os from 'node:os';
-import { spawn, execSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 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, isPersistent } 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
@@ -87,14 +86,7 @@ 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.
-function resolveAuthor(explicit) {
-  if (explicit) return explicit;
-  try {
-    const name = execSync('git config user.name', { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
-    if (name) return name;
-  } catch { /* no git / no user.name */ }
-  try { return os.userInfo().username || null; } catch { return null; }
-}
+const resolveAuthor = (explicit) => explicit || gitOrOsUser();
 
 // projview comment <add|resolve|reopen|rm> ...   (writes ride the store)
 async function cmdComment(args) {
@@ -222,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

@@ -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, 45 tests)
+npm test                     # run the test suite (node:test, 49 tests)
 ```
 
 See the [project README](README.md) for the architecture and the

package/docs/reference/api.md

@@ -12,15 +12,36 @@ state it records is its own usage events (views / searches) into the store.
 
 ### GET /api/tree
 
-Returns the in-memory file tree as JSON.
+Returns the in-memory file tree as JSON, plus the `version` and a `writable`
+flag (false when projview is exposed on a non-loopback host).
 
 ### GET /api/file
 
 Renders a single file to HTML on demand. Query param `p` is the relative path.
+Records a `view` usage event.
 
 ### GET /api/events
 
-Server-sent events stream for live reload.
+Server-sent events stream: `change` / `tree` for live reload, `comments` when a
+comment is created/edited/deleted.
+
+### GET /api/comments
+
+Lists comments as JSON. Optional `?file=<path>` filters to a single file.
+
+### POST /api/comments
+
+Creates a comment from `{ file, body, anchor?, author? }`. **Loopback only** -
+returns `403` when bound to a non-loopback host. Author defaults to the server's
+git/OS user when omitted.
+
+### PATCH /api/comments/:id · DELETE /api/comments/:id
+
+Resolve/edit (`{ resolved?, body? }`) or delete a comment. Loopback only.
+
+### GET /api/usage
+
+Aggregated usage: `{ total, byType, topFiles[], recentSearches[] }`.
 
 ## machine interface (CLI)
 
@@ -115,6 +136,13 @@ On-demand fetch + render, in-app link routing, anchor jumps.
 
 A chokidar watcher broadcasts change/tree events over SSE.
 
+### comments
+
+A drawer (the 💬 button, bottom-right) lists comments for the open file. Add one
+by selecting text, hovering a heading, or "+ note". Text anchors re-anchor on
+each render and paint via the CSS Custom Highlight API; create/resolve/delete
+controls hide when the server isn't writable.
+
 ## stores (persistence)
 
 The index - plus **comments** and **usage events** - is in-memory by default

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projview",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "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`;
+}

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,7 +99,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 });
+      sendJson(res, { root: path.basename(root) || root, tree: buildTree(root), version: VERSION, writable: allowWrites });
       return;
     }
 
@@ -105,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);
@@ -156,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

@@ -24,6 +24,7 @@ import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
+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
@@ -43,6 +44,12 @@ 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(),