pocketspec 0.1.0

package/CLAUDE.md

@@ -0,0 +1,75 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+pocketspec serves local markdown folders over the LAN so you can read docs/specs on your phone, tap a paragraph to comment, and have an AI agent read those comments back to revise the docs. It's a single-purpose tool: zero npm dependencies, Node stdlib server, vanilla-JS SPA client.
+
+## Commands
+
+```bash
+node server.js ~/docs              # serve a folder (same as `npx pocketspec ~/docs`)
+node server.js ~/a ~/b             # serve multiple folders (ephemeral roots)
+node server.js                     # serve folders registered via `add` (from config.json)
+node server.js --help
+
+node server.js add ~/docs "Name"   # register a persistent root
+node server.js list                # list registered roots
+
+node server.js ~/docs --port 8080  # starting port (falls back to next free port, 10 tries)
+node server.js ~/docs --read-only  # disable all writes (edit + comments)
+node server.js ~/docs --password P # HTTP Basic Auth; prefer POCKETSPEC_PASSWORD env var
+```
+
+There is no build, lint, or test setup — it's plain Node + static files. Run the server and open the printed Network URL to verify changes.
+
+## Architecture
+
+Two files hold essentially everything:
+
+- **`server.js`** — the entire backend. A single `http.createServer` handler routes by `pathname`. No framework, no router lib.
+- **`public/app.js`** — the entire frontend SPA. Hash-based routing, renders markdown client-side via the vendored `public/marked.min.js`.
+
+### Roots model
+
+A "root" is one served folder, addressed by integer index. Roots come from one of two sources, resolved per request by `currentRoots()`:
+
+- **Ephemeral**: folder paths passed on the CLI → `RUNTIME_ROOTS` (not persisted).
+- **Persistent**: `config.json` `{ roots: [{name, path}] }`, managed by the `add`/`list` subcommands. `config.json` is gitignored (it holds personal paths).
+
+If any folder args are given they fully override config; otherwise config is used.
+
+### API (all under `/api/`)
+
+- `GET /api/roots` — list roots `{id, name, path}`
+- `GET /api/meta` — `{ readOnly }`
+- `GET /api/list?root=&path=` — folder listing (`{dirs, files}`)
+- `GET /api/doc?root=&path=` — raw markdown text
+- `GET /api/raw?root=&path=` — images/assets referenced by docs
+- `GET/POST/DELETE /api/comments?root=&path=[&id=]` — read/add/delete comments
+- `POST /api/save?root=&path=` — overwrite a `.md` file (`{content}`)
+
+Everything else falls through to static files in `public/`, then to `index.html` (SPA fallback).
+
+### Security invariants (do not regress these)
+
+- **Path traversal**: every file access goes through `resolveInRoot(rootIndex, relPath)`, which resolves against the root's realpath and rejects anything not inside it — checked both before and after `realpathSync` (symlink escape). New file-serving endpoints MUST use it.
+- **Read-only**: when `READ_ONLY`, any non-GET on `/api/comments` and `/api/save` returns 403.
+- **Auth**: `checkAuth` gates *every* request (constant-time compare, username ignored). It's the first thing in the handler.
+- The server binds `0.0.0.0` by design (LAN access) — there is no auth by default. This is intentional; the README documents the trust-the-network / Tailscale model.
+
+### Comment anchoring
+
+Comments live in a sidecar `file.md.comments` JSON file next to the doc (`commentsPathFor` = append `.comments`). Each comment: `{id, text, anchor, ts}` where `anchor` is `{index, snippet}` or `null` (general comment).
+
+The client re-anchors on render (`resolveAnchor` in app.js): it matches a comment to a block first by `index`, falling back to matching the 80-char `snippet`. If the passage was edited away and neither matches, the comment becomes an **orphan** and is shown under "General comments" rather than lost. Blocks are tagged with `data-bi` (block index) at render time; the snippet is `blockSnippet` (trimmed `textContent`, first 80 chars). Keep these two definitions of snippet (client `SNIPPET_LEN`/`blockSnippet` and server-stored snippet) consistent.
+
+### Client routing
+
+Hash routes (`#/`, `#/0`, `#/0/sub/dir`, `#/0/sub/x.md`) drive everything, so the phone back button works. PWA-enabled via `manifest.json` + icons.
+
+## Conventions
+
+- Everything in the repo is English — UI, CLI, server strings, comments, commit messages. Keep it that way; no Portuguese.
+- No dependencies. `marked` is vendored, not installed. Don't add an npm dependency without strong reason.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Monteiro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# pocketspec
+
+**Leave your AI agent writing docs and specs — read them on your phone from anywhere, comment by tapping a paragraph, and let the agent read your comments back.**
+
+Point your AI agent (Claude, Cursor, whatever) at a folder, let it write specs while you do something else, and follow along from your phone over your local network. Spot a vague paragraph? Tap it and comment. The comment lands in a `.comments` file next to the doc — which the agent reads back to revise. The AI doc review loop, on the go.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lucassmatos/pocketspec/main/docs/demo.gif" alt="pocketspec demo: read a spec on your phone, tap a paragraph to comment, and the agent reads the comment back" width="320">
+</p>
+
+## Quick start
+
+```bash
+npx pocketspec ~/path/to/docs
+```
+
+Starts a server on your local network and prints the address (e.g. `http://192.168.1.x:4321`) to open on your phone. Multiple folders:
+
+```bash
+npx pocketspec ~/project-a/docs ~/project-b/specs
+```
+
+No install — `npx` fetches and runs it.
+
+## The comment loop
+
+- **Comment a passage:** tap any paragraph/block → a comment box opens → it shows up below the block with a bar marking the passage.
+- **General comment:** the floating 💬 button.
+- **Edit the doc:** the ✏️ button at the top opens the raw markdown; saving writes to the file.
+- Comments live in a sidecar `file.md.comments` (JSON) next to the `.md`. Easy for an agent to read: each comment stores the anchored passage, the text, and a timestamp. If the passage is later edited, the comment isn't lost — it moves to "General comments" with a reference to the original text.
+
+## Options
+
+```bash
+npx pocketspec ~/docs --port 8080     # starting port (tries the next free one if taken)
+npx pocketspec ~/docs --read-only     # read-only: no editing, no commenting
+```
+
+Persistent folders (instead of passing paths every time):
+
+```bash
+npx pocketspec add ~/docs "My project"   # register
+npx pocketspec list                       # list
+npx pocketspec                            # serve the registered ones
+```
+
+## Security — read this
+
+pocketspec has **no authentication** and, by default, exposes write endpoints (edit file, comment) on your local network. That's by design: the point is reading from your phone on the same Wi-Fi.
+
+- **Use it only on a trusted network** (your home, not a coffee-shop Wi-Fi).
+- Want read-only, no write risk? Use `--read-only`.
+- **Want access from outside your network?** Do NOT expose this to the open internet. Use a peer-to-peer VPN like [Tailscale](https://tailscale.com): install it on your laptop and phone, then reach it via the Tailscale IP from anywhere — with nothing publicly exposed.
+
+## How it works
+
+- Zero npm dependencies. Node stdlib on the server; [`marked`](https://github.com/markedjs/marked) (MIT) vendored in `public/marked.min.js` rendering in the browser, so it works even with no internet on your phone.
+- Lists only folders and `.md` files (dotfiles ignored). Images referenced by docs are served via `/api/raw`.
+- Hash-based navigation (`#/0/folder/doc.md`), so your phone's back button works. PWA: you can "Add to Home Screen" and it opens as an app.
+- Path-traversal protection: it never serves anything outside the folders you pass.
+
+## Run from source (dev)
+
+```bash
+node server.js ~/docs            # same as npx, from the clone
+node server.js --help
+```
+
+## License
+
+MIT. `marked` is also MIT (its license is kept in the vendored file).

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pocketspec",
+  "version": "0.1.0",
+  "description": "Read your markdown docs on your phone over the local network, comment by tapping a paragraph, and let your AI agent read the comments back.",
+  "bin": {
+    "pocketspec": "server.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucassmatos/pocketspec.git"
+  },
+  "homepage": "https://github.com/lucassmatos/pocketspec#readme",
+  "bugs": {
+    "url": "https://github.com/lucassmatos/pocketspec/issues"
+  },
+  "author": "Lucas Monteiro",
+  "files": [
+    "server.js",
+    "public/",
+    "CLAUDE.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "keywords": [
+    "markdown",
+    "docs",
+    "mobile",
+    "lan",
+    "ai",
+    "claude",
+    "comments",
+    "review",
+    "specs"
+  ]
+}

package/public/app.js

@@ -0,0 +1,488 @@
+'use strict';
+
+const contentEl = document.getElementById('content');
+const breadcrumbEl = document.getElementById('breadcrumb');
+const actionsEl = document.getElementById('actions');
+
+// Routes (hash-based, so the browser back button works):
+//   #/            → list of registered roots
+//   #/0           → root 0, top folder
+//   #/0/sub/dir   → folder inside root 0
+//   #/0/sub/x.md  → rendered document
+
+function parseHash() {
+  const hash = decodeURIComponent(location.hash.replace(/^#\/?/, ''));
+  if (!hash) return { root: null, path: '' };
+  const [rootStr, ...rest] = hash.split('/');
+  return { root: Number(rootStr), path: rest.join('/') };
+}
+
+function hashFor(root, relPath) {
+  const suffix = relPath ? '/' + relPath.split('/').map(encodeURIComponent).join('/') : '';
+  return `#/${root}${suffix}`;
+}
+
+async function fetchJson(url, options) {
+  const res = await fetch(url, options);
+  if (!res.ok) throw new Error(await res.text());
+  return res.json();
+}
+
+let rootsCache = null;
+async function getRoots() {
+  if (!rootsCache) rootsCache = await fetchJson('/api/roots');
+  return rootsCache;
+}
+
+// Server tells us whether writes are allowed (--read-only). Cached once.
+let metaCache = null;
+async function getMeta() {
+  if (!metaCache) {
+    try { metaCache = await fetchJson('/api/meta'); }
+    catch { metaCache = { readOnly: false }; }
+  }
+  return metaCache;
+}
+
+// current doc view state (used by comment + edit handlers)
+let current = { root: null, path: '' };
+
+// ---------- breadcrumb ----------
+
+function renderBreadcrumb(rootName, root, relPath, isDoc) {
+  breadcrumbEl.innerHTML = '';
+  const add = (label, href) => {
+    if (breadcrumbEl.childNodes.length) {
+      const sep = document.createElement('span');
+      sep.className = 'sep';
+      sep.textContent = '›';
+      breadcrumbEl.appendChild(sep);
+    }
+    if (href !== null) {
+      const a = document.createElement('a');
+      a.href = href;
+      a.textContent = label;
+      breadcrumbEl.appendChild(a);
+    } else {
+      const span = document.createElement('span');
+      span.className = 'current';
+      span.textContent = label;
+      breadcrumbEl.appendChild(span);
+    }
+  };
+
+  add('🏠', '#/');
+  if (root === null) return;
+
+  const parts = relPath ? relPath.split('/') : [];
+  const last = parts.length - 1;
+  add(rootName, parts.length ? hashFor(root, '') : null);
+  parts.forEach((part, i) => {
+    const label = isDoc && i === last ? part.replace(/\.md$/i, '') : part;
+    add(label, i === last ? null : hashFor(root, parts.slice(0, i + 1).join('/')));
+  });
+  // keep the tail of a long path visible
+  breadcrumbEl.scrollLeft = breadcrumbEl.scrollWidth;
+}
+
+// ---------- listing views ----------
+
+function listItem(href, icon, label, meta) {
+  const li = document.createElement('li');
+  const a = document.createElement('a');
+  a.href = href;
+  a.innerHTML = `<span class="icon">${icon}</span><span class="label"></span>` +
+    (meta ? `<span class="meta">${meta}</span>` : '');
+  a.querySelector('.label').textContent = label;
+  li.appendChild(a);
+  return li;
+}
+
+async function renderHome() {
+  const roots = await getRoots();
+  renderBreadcrumb(null, null, '', false);
+  contentEl.innerHTML = '<h1 class="page-title">Documents</h1>';
+  if (!roots.length) {
+    contentEl.insertAdjacentHTML('beforeend',
+      '<p class="empty">No folders yet.<br>Use <code>pocketspec add &lt;folder&gt;</code></p>');
+    return;
+  }
+  const ul = document.createElement('ul');
+  ul.className = 'listing';
+  for (const root of roots) {
+    ul.appendChild(listItem(hashFor(root.id, ''), '📚', root.name, ''));
+  }
+  contentEl.appendChild(ul);
+}
+
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+async function renderFolder(root, relPath) {
+  const roots = await getRoots();
+  const rootInfo = roots.find((r) => r.id === root);
+  if (!rootInfo) throw new Error('root not found');
+  const data = await fetchJson(`/api/list?root=${root}&path=${encodeURIComponent(relPath)}`);
+  renderBreadcrumb(rootInfo.name, root, relPath, false);
+  contentEl.innerHTML = '';
+
+  if (!data.dirs.length && !data.files.length) {
+    contentEl.innerHTML = '<p class="empty">Empty folder (no .md files)</p>';
+    return;
+  }
+  const ul = document.createElement('ul');
+  ul.className = 'listing';
+  const join = (name) => (relPath ? relPath + '/' + name : name);
+  for (const dir of data.dirs) {
+    ul.appendChild(listItem(hashFor(root, join(dir)), '📁', dir, ''));
+  }
+  for (const file of data.files) {
+    ul.appendChild(listItem(hashFor(root, join(file.name)), '📄',
+      file.name.replace(/\.md$/i, ''), formatSize(file.size)));
+  }
+  contentEl.appendChild(ul);
+}
+
+// ---------- document view ----------
+
+async function renderDoc(root, relPath) {
+  const roots = await getRoots();
+  const rootInfo = roots.find((r) => r.id === root);
+  if (!rootInfo) throw new Error('root not found');
+  const res = await fetch(`/api/doc?root=${root}&path=${encodeURIComponent(relPath)}`);
+  if (!res.ok) throw new Error(await res.text());
+  const md = await res.text();
+  renderBreadcrumb(rootInfo.name, root, relPath, true);
+  current = { root, path: relPath };
+
+  const doc = document.createElement('article');
+  doc.className = 'doc';
+  doc.innerHTML = marked.parse(md);
+
+  // Rewrite relative links: .md links navigate in-app, other assets go through /api/raw
+  const docDir = relPath.split('/').slice(0, -1).join('/');
+  const resolveRel = (href) => {
+    const stack = docDir ? docDir.split('/') : [];
+    for (const part of href.split('/')) {
+      if (part === '' || part === '.') continue;
+      else if (part === '..') stack.pop();
+      else stack.push(part);
+    }
+    return stack.join('/');
+  };
+  const isExternal = (href) => /^([a-z]+:|\/|#)/i.test(href);
+
+  for (const a of doc.querySelectorAll('a[href]')) {
+    const href = a.getAttribute('href');
+    if (isExternal(href)) continue;
+    const [target, anchor] = href.split('#');
+    if (/\.md$/i.test(target)) {
+      a.href = hashFor(root, resolveRel(target)) + (anchor ? '#' + anchor : '');
+    } else if (target) {
+      a.href = `/api/raw?root=${root}&path=${encodeURIComponent(resolveRel(target))}`;
+    }
+  }
+  for (const img of doc.querySelectorAll('img[src]')) {
+    const src = img.getAttribute('src');
+    if (isExternal(src)) continue;
+    img.src = `/api/raw?root=${root}&path=${encodeURIComponent(resolveRel(src))}`;
+  }
+
+  const meta = await getMeta();
+
+  // each top-level element is a commentable block (tap to comment, unless read-only)
+  [...doc.children].forEach((el, i) => el.setAttribute('data-bi', i));
+  if (!meta.readOnly) doc.addEventListener('click', onBlockTap);
+
+  contentEl.innerHTML = '';
+  contentEl.appendChild(doc);
+
+  const general = document.createElement('section');
+  general.id = 'general-comments';
+  contentEl.appendChild(general);
+
+  renderActions(!meta.readOnly);
+  if (!meta.readOnly) ensureFab();
+  await refreshComments();
+  window.scrollTo(0, 0);
+}
+
+// ---------- comments ----------
+
+const SNIPPET_LEN = 80;
+const blockSnippet = (el) => el.textContent.trim().slice(0, SNIPPET_LEN);
+
+function commentsUrl(extra) {
+  return `/api/comments?root=${current.root}&path=${encodeURIComponent(current.path)}` + (extra || '');
+}
+
+function resolveAnchor(blocks, anchor) {
+  if (!anchor) return null;
+  const byIndex = blocks[anchor.index];
+  if (byIndex && blockSnippet(byIndex) === anchor.snippet) return byIndex;
+  return blocks.find((b) => blockSnippet(b) === anchor.snippet) || null;
+}
+
+function formatTime(ts) {
+  const d = new Date(ts);
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${pad(d.getDate())}/${pad(d.getMonth() + 1)} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+function commentBubble(comment, note) {
+  const div = document.createElement('div');
+  div.className = 'comment-bubble';
+  const body = document.createElement('div');
+  body.className = 'comment-text';
+  body.textContent = comment.text;
+  const meta = document.createElement('div');
+  meta.className = 'comment-meta';
+  meta.textContent = '💬 ' + formatTime(comment.ts) + (note ? ` · ${note}` : '');
+  if (!(metaCache && metaCache.readOnly)) {
+    const del = document.createElement('button');
+    del.className = 'comment-delete';
+    del.textContent = '✕';
+    del.addEventListener('click', async () => {
+      if (!confirm('Delete this comment?')) return;
+      await fetchJson(commentsUrl(`&id=${comment.id}`), { method: 'DELETE' });
+      await refreshComments();
+    });
+    meta.appendChild(del);
+  }
+  div.appendChild(body);
+  div.appendChild(meta);
+  return div;
+}
+
+async function refreshComments() {
+  const doc = contentEl.querySelector('article.doc');
+  const general = document.getElementById('general-comments');
+  if (!doc || !general) return;
+
+  const data = await fetchJson(commentsUrl());
+  doc.querySelectorAll('.comment-thread').forEach((el) => el.remove());
+  doc.querySelectorAll('.has-comments').forEach((el) => el.classList.remove('has-comments'));
+  general.innerHTML = '';
+
+  const blocks = [...doc.children].filter((el) => el.hasAttribute('data-bi'));
+  const orphans = [];
+  const generals = [];
+
+  for (const comment of data.comments) {
+    const block = resolveAnchor(blocks, comment.anchor);
+    if (!comment.anchor) generals.push(comment);
+    else if (!block) orphans.push(comment);
+    else {
+      let thread = block.nextElementSibling;
+      if (!thread || !thread.classList.contains('comment-thread')) {
+        thread = document.createElement('div');
+        thread.className = 'comment-thread';
+        block.after(thread);
+      }
+      block.classList.add('has-comments');
+      thread.appendChild(commentBubble(comment));
+    }
+  }
+
+  if (generals.length || orphans.length) {
+    const h = document.createElement('h2');
+    h.className = 'general-comments-title';
+    h.textContent = 'General comments';
+    general.appendChild(h);
+    for (const c of generals) general.appendChild(commentBubble(c));
+    for (const c of orphans) {
+      general.appendChild(commentBubble(c, `on: “${c.anchor.snippet.slice(0, 40)}…”`));
+    }
+  }
+}
+
+// ---------- comment sheet ----------
+
+let sheet = null;
+let pendingAnchor = null;
+let selectedBlock = null;
+
+// In iOS standalone (home-screen) mode, programmatic focus() marks the field
+// as focused WITHOUT showing the keyboard — and a later tap on the already-
+// focused field won't re-trigger focus, so the keyboard never appears.
+// Let the user's own tap do the focusing there.
+const isStandalone = window.navigator.standalone === true ||
+  window.matchMedia('(display-mode: standalone)').matches;
+
+// Keep the sheet above the iOS keyboard (fixed elements anchor to the layout
+// viewport, which the keyboard does not always resize).
+function adjustSheetForKeyboard() {
+  if (!sheet || sheet.hidden) return;
+  const vv = window.visualViewport;
+  const offset = vv ? Math.max(0, window.innerHeight - vv.height - vv.offsetTop) : 0;
+  sheet.style.transform = offset > 0 ? `translateY(-${offset}px)` : '';
+}
+if (window.visualViewport) {
+  window.visualViewport.addEventListener('resize', adjustSheetForKeyboard);
+  window.visualViewport.addEventListener('scroll', adjustSheetForKeyboard);
+}
+
+function ensureSheet() {
+  if (sheet) return sheet;
+  sheet = document.createElement('div');
+  sheet.id = 'sheet';
+  sheet.hidden = true;
+  sheet.innerHTML = `
+    <div class="sheet-context" id="sheet-context"></div>
+    <textarea id="sheet-text" rows="3" placeholder="Write your comment…"></textarea>
+    <div class="sheet-buttons">
+      <button class="btn" id="sheet-cancel">Cancel</button>
+      <button class="btn primary" id="sheet-send">Comment</button>
+    </div>`;
+  document.body.appendChild(sheet);
+  sheet.querySelector('#sheet-cancel').addEventListener('click', closeSheet);
+  sheet.querySelector('#sheet-send').addEventListener('click', async () => {
+    const textarea = sheet.querySelector('#sheet-text');
+    const text = textarea.value.trim();
+    if (!text) return;
+    await fetchJson(commentsUrl(), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ text, anchor: pendingAnchor }),
+    });
+    textarea.value = '';
+    closeSheet();
+    await refreshComments();
+  });
+  return sheet;
+}
+
+function openSheet(anchor, contextLabel) {
+  ensureSheet();
+  pendingAnchor = anchor;
+  sheet.querySelector('#sheet-context').textContent = contextLabel;
+  sheet.hidden = false;
+  if (!isStandalone) sheet.querySelector('#sheet-text').focus();
+}
+
+function closeSheet() {
+  if (sheet) {
+    sheet.querySelector('#sheet-text').blur();
+    sheet.style.transform = '';
+    sheet.hidden = true;
+  }
+  pendingAnchor = null;
+  if (selectedBlock) {
+    selectedBlock.classList.remove('block-selected');
+    selectedBlock = null;
+  }
+}
+
+function onBlockTap(e) {
+  if (e.target.closest('a, .comment-thread, input, button')) return;
+  const block = e.target.closest('[data-bi]');
+  if (!block) return;
+  if (selectedBlock) selectedBlock.classList.remove('block-selected');
+  selectedBlock = block;
+  block.classList.add('block-selected');
+  const snippet = blockSnippet(block);
+  openSheet(
+    { index: Number(block.getAttribute('data-bi')), snippet },
+    `Commenting on: “${snippet.slice(0, 60)}${snippet.length > 60 ? '…' : ''}”`,
+  );
+}
+
+// ---------- floating button + topbar actions ----------
+
+let fab = null;
+function ensureFab() {
+  if (fab) { fab.hidden = false; return; }
+  fab = document.createElement('button');
+  fab.id = 'fab';
+  fab.title = 'General comment';
+  fab.textContent = '💬';
+  fab.addEventListener('click', () => openSheet(null, 'General comment on the document'));
+  document.body.appendChild(fab);
+}
+
+function hideDocChrome() {
+  if (fab) fab.hidden = true;
+  closeSheet();
+  actionsEl.innerHTML = '';
+}
+
+function renderActions(isDoc) {
+  actionsEl.innerHTML = '';
+  if (!isDoc) return;
+  const edit = document.createElement('button');
+  edit.className = 'topbtn';
+  edit.title = 'Edit document';
+  edit.textContent = '✏️';
+  edit.addEventListener('click', openEditor);
+  actionsEl.appendChild(edit);
+}
+
+// ---------- editor ----------
+
+async function openEditor() {
+  const { root, path: relPath } = current;
+  const res = await fetch(`/api/doc?root=${root}&path=${encodeURIComponent(relPath)}`);
+  if (!res.ok) { alert(await res.text()); return; }
+  const md = await res.text();
+
+  hideDocChrome();
+  contentEl.innerHTML = '';
+
+  const textarea = document.createElement('textarea');
+  textarea.id = 'editor';
+  textarea.value = md;
+
+  // buttons live in the sticky topbar so they never scroll out of view
+  const cancel = document.createElement('button');
+  cancel.className = 'btn';
+  cancel.textContent = 'Cancel';
+  cancel.addEventListener('click', route);
+  const save = document.createElement('button');
+  save.className = 'btn primary';
+  save.textContent = 'Save';
+  save.addEventListener('click', async () => {
+    save.disabled = true;
+    save.textContent = 'Saving…';
+    try {
+      await fetchJson(`/api/save?root=${root}&path=${encodeURIComponent(relPath)}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ content: textarea.value }),
+      });
+      await route();
+    } catch (err) {
+      alert('Error saving: ' + err.message);
+      save.disabled = false;
+      save.textContent = 'Save';
+    }
+  });
+  actionsEl.appendChild(cancel);
+  actionsEl.appendChild(save);
+
+  contentEl.appendChild(textarea);
+}
+
+// ---------- router ----------
+
+async function route() {
+  const { root, path: relPath } = parseHash();
+  const isDoc = root !== null && !Number.isNaN(root) && /\.md$/i.test(relPath);
+  if (!isDoc) hideDocChrome();
+  try {
+    if (root === null || Number.isNaN(root)) await renderHome();
+    else if (isDoc) await renderDoc(root, relPath);
+    else await renderFolder(root, relPath);
+  } catch (err) {
+    contentEl.innerHTML = '';
+    const p = document.createElement('p');
+    p.className = 'error';
+    p.textContent = 'Error: ' + err.message;
+    contentEl.appendChild(p);
+  }
+}
+
+window.addEventListener('hashchange', route);
+route();