@nynb/sandpaper 0.1.0

package/src/claude.js

@@ -0,0 +1,226 @@
+// claude.js — the bridge to Claude Code.
+// Spawns `claude -p` in stream-json mode against the document's folder, maps the
+// event stream to a small set of UI status states, and persists the session id so
+// every turn resumes the same conversation (context survives across turns).
+import { spawn } from 'node:child_process';
+import { dirname, basename, join } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+
+// Appended per turn instead of a repo-wide CLAUDE.md, so the contract is scoped to
+// the editing job and doesn't pollute the project's own Claude guidance.
+const CONTRACT = [
+  'You are the editing engine behind Sandpaper. A human is refining a single,',
+  'self-contained HTML document live in their browser.',
+  '- Edit the target HTML file in place with the Edit tool. Keep it valid and self-contained.',
+  '- Make the SMALLEST change that satisfies the request. Never regenerate unrelated parts.',
+  '- Preserve every existing data-cid attribute exactly; give new block elements unique ones.',
+  '- When told a specific element (by data-cid or CSS selector), change ONLY that element.',
+  "- Preserve the document's structure, style, and voice unless asked to change them.",
+].join('\n');
+
+const SESSION_TOOLS = ['Read', 'Edit', 'Write', 'MultiEdit'];
+
+// ---- pure helpers (unit-tested in test/parse-test.js) ----
+
+// Returns a session id if this event carries one (the init system event), else null.
+export function getSessionId(ev) {
+  return ev && ev.type === 'system' && ev.subtype === 'init' && ev.session_id
+    ? ev.session_id
+    : null;
+}
+
+// Summarize an Edit/Write/MultiEdit tool_use block (taken from a COMPLETE assistant
+// message, where `input` is fully formed — never from partial input_json_delta) into a
+// typed `edit` frame for the conversation surface's "what changed" card.
+function summarizeEdit(block, docName) {
+  const input = block.input || {};
+  const name = block.name;
+  let hunks;
+  if (name === 'MultiEdit' && Array.isArray(input.edits)) {
+    hunks = input.edits.map((e) => ({ oldText: e.old_string || '', newText: e.new_string || '' }));
+  } else if (name === 'Write') {
+    hunks = [{ oldText: '', newText: input.content || '' }];
+  } else {
+    hunks = [{ oldText: input.old_string || '', newText: input.new_string || '' }];
+  }
+  let added = 0, removed = 0;
+  const cids = new Set();
+  for (const h of hunks) {
+    if (h.oldText) removed += h.oldText.split('\n').length;
+    if (h.newText) added += h.newText.split('\n').length;
+    for (const t of [h.oldText, h.newText]) {
+      for (const m of String(t).matchAll(/data-cid="([^"]+)"/g)) cids.add(m[1]);
+    }
+  }
+  const file = input.file_path ? basename(input.file_path) : docName;
+  return { type: 'edit', tool: name, file, hunks, added, removed, cids: [...cids] };
+}
+
+// Map one stream-json event to an ARRAY of typed frames for the conversation surface:
+//   {type:'status', …}          → drives the 7-state chip (unchanged behaviour)
+//   {type:'assistant_delta', …} → streamed reply text / thinking (previously DROPPED — the bug)
+//   {type:'edit', …}            → a per-edit change summary
+// Returns [] for events that carry nothing renderable.
+export function mapEvents(ev, docName) {
+  if (!ev || !ev.type) return [];
+
+  if (ev.type === 'system' && ev.subtype === 'init') {
+    return [{ type: 'status', state: 'init', label: 'starting…' }];
+  }
+
+  if (ev.type === 'stream_event' && ev.event) {
+    const e = ev.event;
+    if (e.type === 'message_start') {
+      return [{ type: 'status', state: 'thinking', label: 'thinking…' }];
+    }
+    if (e.type === 'content_block_start' && e.content_block && e.content_block.type === 'tool_use') {
+      const tool = e.content_block.name || 'tool';
+      const editing = tool === 'Edit' || tool === 'Write' || tool === 'MultiEdit';
+      return [editing
+        ? { type: 'status', state: 'editing', label: `editing ${docName}` }
+        : { type: 'status', state: 'tool_using', label: `${tool.toLowerCase()}…` }];
+    }
+    if (e.type === 'content_block_delta' && e.delta) {
+      if (e.delta.type === 'text_delta' && e.delta.text) {
+        return [{ type: 'assistant_delta', kind: 'text', text: e.delta.text }];
+      }
+      if (e.delta.type === 'thinking_delta' && e.delta.thinking) {
+        return [{ type: 'assistant_delta', kind: 'thinking', text: e.delta.thinking }];
+      }
+    }
+    return [];
+  }
+
+  // A COMPLETE assistant message: pull edit summaries from it (text was already streamed
+  // via deltas, so we do NOT re-emit it here — that would double-render).
+  if (ev.type === 'assistant' && ev.message && Array.isArray(ev.message.content)) {
+    const edits = [];
+    for (const block of ev.message.content) {
+      if (block.type === 'tool_use' && (block.name === 'Edit' || block.name === 'Write' || block.name === 'MultiEdit')) {
+        edits.push(summarizeEdit(block, docName));
+      }
+    }
+    return edits;
+  }
+
+  if (ev.type === 'result') {
+    if (ev.is_error || (ev.subtype && ev.subtype !== 'success')) {
+      return [{ type: 'status', state: 'error', label: 'turn failed', detail: String(ev.result || '').slice(0, 200) }];
+    }
+    // The toolbar derives "Replied" vs "Saved" from whether any edit frame arrived this turn,
+    // so the chip stays neutral here — no more hardcoded "Saved" on pure-discussion turns.
+    const cost = typeof ev.total_cost_usd === 'number' ? ev.total_cost_usd : null;
+    return [{ type: 'status', state: 'done', label: 'done', cost, done: true }];
+  }
+
+  return [];
+}
+
+// ---- session persistence ----
+
+function sessionPath(docDir) { return join(docDir, '.sandpaper', 'session.json'); }
+
+function loadSession(docDir) {
+  try { return JSON.parse(readFileSync(sessionPath(docDir), 'utf8')).sessionId || null; }
+  catch { return null; }
+}
+
+function saveSession(docDir, id) {
+  const dir = join(docDir, '.sandpaper');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(sessionPath(docDir), JSON.stringify({ sessionId: id }, null, 2));
+}
+
+// ---- environment hygiene (mirrors amux _on_claude_plan / _claude_oneshot env scrub) ----
+
+// True if the user is signed into a Claude subscription (Pro/Max) rather than API billing.
+function onClaudePlan() {
+  try { return !!JSON.parse(readFileSync(join(homedir(), '.claude.json'), 'utf8')).oauthAccount; }
+  catch { return false; }
+}
+
+// The child is a fresh, top-level `claude` run — not nested inside whatever process spawned
+// us. Strip the markers that would make it think it's running inside Claude Code, and on a
+// subscription drop any exported ANTHROPIC_API_KEY so turns bill the plan, not the API.
+function childEnv() {
+  const env = { ...process.env };
+  delete env.CLAUDECODE;
+  delete env.CLAUDE_CODE_ENTRYPOINT;
+  if (onClaudePlan()) delete env.ANTHROPIC_API_KEY;
+  return env;
+}
+
+// ---- the turn ----
+
+// Run one refinement turn. `onStatus({state,label,detail?,done?})` is called as the
+// stream advances. Returns the child process (or null if spawn failed synchronously).
+export function runTurn(docPath, prompt, onStatus) {
+  const docDir = dirname(docPath);
+  const docName = basename(docPath);
+  const prior = loadSession(docDir);
+
+  const args = [
+    '-p', prompt,
+    '--output-format', 'stream-json', '--verbose', '--include-partial-messages',
+    '--permission-mode', 'acceptEdits',
+    '--allowedTools', SESSION_TOOLS.join(','),
+    '--append-system-prompt', CONTRACT,
+  ];
+  if (prior) args.push('--resume', prior);
+
+  let child;
+  try {
+    // cwd = the document's folder: this is what makes --resume's directory-scoped
+    // session lookup reliable, and keeps Claude's relative paths anchored to the doc.
+    // stdin 'ignore' so a non-interactive `-p` run can never block waiting on input.
+    child = spawn('claude', args, { cwd: docDir, env: childEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (err) {
+    onStatus({ type: 'status', state: 'error', label: 'Could not start claude', detail: err.message });
+    return null;
+  }
+
+  onStatus({ type: 'status', state: 'init', label: 'starting…' });
+
+  let buf = '';
+  let errored = false;
+
+  const processLine = (raw) => {
+    const line = raw.trim();
+    if (!line) return;
+    let ev;
+    try { ev = JSON.parse(line); } catch { return; } // ignore non-JSON noise
+    const id = getSessionId(ev);
+    if (id) saveSession(docDir, id);
+    for (const frame of mapEvents(ev, docName)) onStatus(frame);
+  };
+
+  child.stdout.on('data', (chunk) => {
+    buf += chunk.toString();
+    let nl;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      processLine(buf.slice(0, nl));
+      buf = buf.slice(nl + 1);
+    }
+  });
+  // Flush a final line that arrives without a trailing newline (else the `result`
+  // event — cost + "Saved" confirmation — can be silently dropped on abrupt exit).
+  child.stdout.on('end', () => { processLine(buf); buf = ''; });
+
+  let stderr = '';
+  child.stderr.on('data', (d) => { stderr += d.toString(); });
+  child.on('error', (err) => {
+    errored = true;
+    onStatus({ type: 'status', state: 'error', label: 'claude not found — is it installed?', detail: err.message });
+  });
+  child.on('close', (code) => {
+    if (errored) return; // 'error' already surfaced the real failure — don't overwrite it with idle
+    if (code && code !== 0) {
+      onStatus({ type: 'status', state: 'error', label: `claude exited (${code})`, detail: stderr.slice(0, 300) });
+    } else {
+      onStatus({ type: 'status', state: 'idle', label: 'idle' });
+    }
+  });
+
+  return child;
+}

package/src/edit.js

@@ -0,0 +1,113 @@
+// edit.js — direct (no-AI) in-place edits.
+// The browser manipulates the rendered DOM of one element; these functions splice that change
+// back into the SOURCE FILE around it, leaving the rest of the file byte-for-byte intact.
+// Pure + dependency-free (Sandpaper ships zero runtime deps) so it can be unit-tested in isolation.
+//
+// All operations locate an element by its data-cid="…" attribute. The tricky parts, all handled in
+// locate(): the literal string can appear in prose/comments (skip those), the element can contain
+// NESTED same-name tags (count depth), and void/self-closing elements have no body (reject).
+
+const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr']);
+
+// Find the element carrying data-cid="<cid>" and return ALL its byte boundaries, or null:
+//   { tag, openStart, innerStart, innerEnd, closeEnd }
+//   openStart  — the '<' of the opening tag
+//   innerStart — first byte after the opening tag's '>'
+//   innerEnd   — the '<' of the matching close tag
+//   closeEnd   — first byte after the matching '</tag>'
+function locate(html, cid) {
+  const marker = 'data-cid="' + cid + '"';
+  let at = html.indexOf(marker);
+  while (at >= 0) {
+    const lt = html.lastIndexOf('<', at);
+    // genuine attribute ⇒ still INSIDE an opening tag: no '>' sits between '<' and the marker.
+    if (lt >= 0 && html.lastIndexOf('>', at) < lt) {
+      const name = /^<([a-zA-Z][\w:-]*)/.exec(html.slice(lt));
+      if (name) {
+        const tag = name[1];
+        const openEnd = html.indexOf('>', at);
+        if (openEnd >= 0 && html[openEnd - 1] !== '/' && !VOID.has(tag.toLowerCase())) {
+          const tok = new RegExp('<' + tag + '(?=[\\s/>])|</' + tag + '\\s*>', 'gi');
+          tok.lastIndex = openEnd + 1;
+          let depth = 1, m;
+          while ((m = tok.exec(html))) {
+            if (m[0][1] === '/') {
+              if (--depth === 0) {
+                return { tag, openStart: lt, innerStart: openEnd + 1, innerEnd: m.index, closeEnd: tok.lastIndex };
+              }
+            } else depth++;
+          }
+        }
+      }
+    }
+    at = html.indexOf(marker, at + marker.length); // this occurrence wasn't usable — try the next
+  }
+  return null;
+}
+
+// Range of the element's INNER content (between the tags).
+export function innerRange(html, cid) {
+  const r = locate(html, cid);
+  return r ? { tag: r.tag, start: r.innerStart, end: r.innerEnd } : null;
+}
+
+// Range of the WHOLE element (tags included).
+export function outerRange(html, cid) {
+  const r = locate(html, cid);
+  return r ? { tag: r.tag, start: r.openStart, end: r.closeEnd } : null;
+}
+
+// Replace the element's inner content. Returns the new file string, or null if not located.
+export function replaceInner(html, cid, inner) {
+  const r = locate(html, cid);
+  return r ? html.slice(0, r.innerStart) + inner + html.slice(r.innerEnd) : null;
+}
+
+// True if the bytes from a line start up to `pos` are only spaces/tabs (i.e. `pos` begins a line).
+function leadingIndent(html, pos) {
+  const ls = html.lastIndexOf('\n', pos - 1) + 1; // 0 if no preceding newline
+  const lead = html.slice(ls, pos);
+  return /^[ \t]*$/.test(lead) ? { lineStart: ls, indent: lead } : null;
+}
+
+// Remove the element entirely. Returns { html, removed } (removed = the element's outer HTML) or null.
+// If the element sits alone on its line, the line's leading whitespace + the preceding newline go too,
+// so no blank gap is left behind.
+export function removeElement(html, cid) {
+  const r = outerRange(html, cid);
+  if (!r) return null;
+  const removed = html.slice(r.start, r.end);
+  let from = r.start, to = r.end;
+  const li = leadingIndent(html, r.start);
+  if (li) {
+    if (li.lineStart > 0) from = li.lineStart - 1;      // consume the newline that ended the previous line
+    else if (html[to] === '\n') to++;                   // at file start: there is none — consume the trailing one
+  }
+  return { html: html.slice(0, from) + html.slice(to), removed };
+}
+
+// Move the element to sit `mode` ('before' | 'after') the element with cid=target. Returns { html } or null.
+// The moved element's own bytes are preserved verbatim; only the indentation around the two seams changes.
+export function moveElement(html, cid, target, mode) {
+  if (!target || target === cid || (mode !== 'before' && mode !== 'after')) return null;
+  const r = outerRange(html, cid);
+  if (!r) return null;
+  const element = html.slice(r.start, r.end);
+  // lift the element out, taking its own line's leading whitespace + the preceding newline with it
+  let from = r.start;
+  const li = leadingIndent(html, r.start);
+  if (li) from = li.lineStart === 0 ? 0 : li.lineStart - 1;
+  const without = html.slice(0, from) + html.slice(r.end);
+  // locate the target in the reduced document (target must still exist — not a descendant of the moved node)
+  const t = outerRange(without, target);
+  if (!t) return null;
+  const tli = leadingIndent(without, t.start);
+  const indent = tli ? tli.indent : '';
+  // only break onto a new line when the target is block-indented; inline targets stay inline.
+  if (mode === 'before') {
+    const at = tli ? tli.lineStart : t.start;
+    return { html: without.slice(0, at) + indent + element + (indent ? '\n' : '') + without.slice(at) };
+  }
+  return { html: without.slice(0, t.end) + (indent ? '\n' + indent : '') + element + without.slice(t.end) };
+}

package/src/server.js

@@ -0,0 +1,327 @@
+// server.js — the local bridge server.
+// Serves a document OR a whole folder (e.g. the project brain), injecting the on-page
+// toolbar at response time only, relaying page → Claude turns, streaming status over SSE,
+// and live-reloading the affected page when its file changes.
+import { createServer } from 'node:http';
+import { readFile, writeFile, readFileSync, writeFileSync, watch, copyFileSync, mkdirSync, existsSync, realpathSync } from 'node:fs';
+import { join, dirname, basename, extname, normalize, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID, createHash } from 'node:crypto';
+import { runTurn } from './claude.js';
+import { replaceInner, removeElement, moveElement } from './edit.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PUBLIC = join(HERE, '..', 'public');
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.css': 'text/css',
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+  '.svg': 'image/svg+xml', '.webp': 'image/webp', '.json': 'application/json',
+};
+
+// `target` is a file (single-doc mode) or a directory (folder/brain mode, opts.brain=true).
+export function startServer(target, port, opts = {}) {
+  const isDir = !!opts.brain;
+  const root = isDir ? target : dirname(target);        // the directory we serve from
+  const defaultDoc = isDir ? 'index.html' : basename(target); // what "/" resolves to
+  const clients = new Set();
+  const turnSnapshots = new Map(); // turnId -> the page file it snapshotted (so undo restores the right file)
+  let activeTurn = null;
+  let activeTurnPage = null;  // the URL path the active turn is editing (for the reload frame)
+  let reloadPending = false;  // a file change happened mid-turn; reload once it ends
+  let suppressReloadUntil = 0; // a direct in-place edit we just wrote — the browser already shows it
+
+  // One-level undo for direct (no-AI) edits: snapshot a page just before we mutate it.
+  const directSnapDir = join(root, '.sandpaper', 'snapshots', 'direct');
+  const directSnaps = new Map(); // pageFile -> its pre-edit snapshot file (recorded only after a successful write)
+  const takeDirectSnap = (pageFile) => { // copy the current file aside; return the snapshot path, or null
+    try {
+      if (!existsSync(directSnapDir)) mkdirSync(directSnapDir, { recursive: true });
+      const rel = pageFile.startsWith(root + sep) ? pageFile.slice(root.length + 1) : basename(pageFile);
+      const snap = join(directSnapDir, createHash('sha1').update(rel).digest('hex').slice(0, 16) + '.html');
+      copyFileSync(pageFile, snap);
+      return snap;
+    } catch { return null; } // best-effort; never block the edit
+  };
+
+  // Apply a direct (no-AI) edit ATOMICALLY: sync read → compute → write, with no await points in between
+  // (so two rapid edits can't interleave). compute(src) -> new HTML string, or null if not located.
+  // Refuses to write while an AI turn is editing the same page (it would clobber Claude's in-progress edit).
+  const applyDirect = (pageFile, compute) => {
+    if (activeTurn && (!isDir || resolveUnder(activeTurnPage) === pageFile)) return { code: 409, body: '{"error":"an AI turn is editing this page"}' };
+    let src;
+    try { src = readFileSync(pageFile, 'utf8'); } catch { return { code: 404, body: '{"error":"unreadable"}' }; }
+    const out = compute(src);
+    if (out == null) return { code: 409, body: '{"error":"element not found"}' };
+    if (out === src) return { code: 200, body: '{"ok":true,"noop":true}' };
+    const snap = takeDirectSnap(pageFile);            // snapshot the pre-edit file
+    try { writeFileSync(pageFile, out); } catch { return { code: 500, body: '{"error":"write failed"}' }; }
+    if (snap) directSnaps.set(pageFile, snap);        // record undo ONLY after the write succeeds
+    suppressReloadUntil = Date.now() + 800;           // the browser already shows the change
+    return { code: 200, body: '{"ok":true}' };
+  };
+
+  const broadcast = (obj) => {
+    const frame = `data: ${JSON.stringify(obj)}\n\n`;
+    for (const res of clients) {
+      try { res.write(frame); } catch { clients.delete(res); }
+    }
+  };
+
+  const injectToolbar = (html) => {
+    const tag =
+      '\n<link rel="stylesheet" href="/__sandpaper/toolbar.css">' +
+      '\n<script type="module" src="/__sandpaper/toolbar.js"></script>\n';
+    return html.includes('</body>') ? html.replace('</body>', tag + '</body>') : html + tag;
+  };
+
+  const serveFile = (file, res) => {
+    readFile(file, (err, data) => {
+      if (err) { res.writeHead(404); return res.end('not found'); }
+      res.writeHead(200, { 'Content-Type': MIME[extname(file)] || 'application/octet-stream' });
+      res.end(data);
+    });
+  };
+
+  // Resolve a URL path to an absolute file UNDER root, or null if it escapes (traversal guard).
+  const resolveUnder = (reqPath) => {
+    const rel = (reqPath === '/' || reqPath === '') ? defaultDoc : reqPath.replace(/^\/+/, '');
+    if (rel === '.git' || rel.startsWith('.git/')) return null; // never serve VCS internals
+    const file = normalize(join(root, rel));
+    if (file !== root && !file.startsWith(root + sep)) return null; // lexical traversal guard
+    // also resolve symlinks: a link inside root pointing outside must not escape.
+    try { const real = realpathSync(file); if (real !== root && !real.startsWith(root + sep)) return null; }
+    catch { /* path not yet on disk — the lexical guard already passed */ }
+    return file;
+  };
+
+  const server = createServer((req, res) => {
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    let path;
+    try { path = decodeURIComponent(url.pathname); }
+    catch { res.writeHead(400); return res.end('bad request'); }
+
+    // Root convenience: serving a repo whose brain lives in brain/ — send "/" to the cover so
+    // localhost:<port> just works, no need to know the /brain/index.html path.
+    if (isDir && (path === '/' || path === '') && !existsSync(join(root, 'index.html')) && existsSync(join(root, 'brain', 'index.html'))) {
+      res.writeHead(302, { Location: '/brain/index.html' });
+      return res.end();
+    }
+
+    // --- SSE status/reload channel ---
+    if (path === '/__sandpaper/events') {
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+      res.write(`data: ${JSON.stringify({ type: 'status', state: 'idle', label: 'idle' })}\n\n`);
+      clients.add(res);
+      req.on('close', () => clients.delete(res));
+      return;
+    }
+
+    // --- a refinement turn (page-aware) ---
+    if (path === '/__sandpaper/turn' && req.method === 'POST') {
+      if (activeTurn) {
+        res.writeHead(409, { 'Content-Type': 'application/json' });
+        return res.end('{"error":"a turn is already in progress"}');
+      }
+      let body = '';
+      req.on('data', (d) => { body += d; if (body.length > 1e6) req.destroy(); });
+      req.on('end', () => {
+        let payload = {};
+        try { payload = JSON.parse(body || '{}'); } catch {}
+        // Never trust the client page: re-resolve it under root and require an existing .html.
+        const turnPage = typeof payload.page === 'string' ? payload.page : '/';
+        const pageFile = resolveUnder(turnPage);
+        if (!pageFile || extname(pageFile) !== '.html' || !existsSync(pageFile)) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          return res.end('{"error":"unknown page"}');
+        }
+        const turnId = randomUUID();
+        snapshot(pageFile, root, turnId);
+        turnSnapshots.set(turnId, pageFile);
+        activeTurnPage = turnPage;
+        activeTurn = runTurn(pageFile, buildPrompt(payload, basename(pageFile)), (frame) => {
+          frame.turnId = turnId;
+          frame.page = activeTurnPage; // page-scope every frame so other-page windows ignore this turn
+          broadcast(frame);
+          const ended = frame.type === 'status' && (frame.done || frame.state === 'idle' || frame.state === 'error');
+          if (ended) {
+            activeTurn = null;
+            if (reloadPending) {
+              reloadPending = false;
+              broadcast(isDir ? { type: 'reload', page: activeTurnPage } : { type: 'reload' });
+            }
+            activeTurnPage = null;
+          }
+        });
+        res.writeHead(202, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, turnId }));
+      });
+      return;
+    }
+
+    // --- undo a turn's edits (restore its pre-turn snapshot to the page it edited) ---
+    if (path === '/__sandpaper/undo' && req.method === 'POST') {
+      let body = '';
+      req.on('data', (d) => { body += d; if (body.length > 1e5) req.destroy(); });
+      req.on('end', () => {
+        let p = {}; try { p = JSON.parse(body || '{}'); } catch {}
+        const snap = snapshotPath(root, p.turnId);
+        const pageFile = turnSnapshots.get(p.turnId); // the file THIS turn snapshotted — not the client's claim
+        if (snap && existsSync(snap) && pageFile && extname(pageFile) === '.html') {
+          try {
+            copyFileSync(snap, pageFile); // → watcher → reload
+            turnSnapshots.delete(p.turnId);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            return res.end('{"ok":true}');
+          } catch {}
+        }
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end('{"error":"no snapshot for that turn"}');
+      });
+      return;
+    }
+
+    // --- a direct (no-AI) in-place edit: the browser edited one element; persist it to the file ---
+    // The browser owns the new content; we splice ONLY that element's inner HTML back into the
+    // source by data-cid, leaving the rest of the file untouched. No Claude, no turn, no snapshot.
+    if (path === '/__sandpaper/write' && req.method === 'POST') {
+      let body = '';
+      req.on('data', (d) => { body += d; if (body.length > 2e6) req.destroy(); });
+      req.on('end', () => {
+        let p = {}; try { p = JSON.parse(body || '{}'); } catch {}
+        const pageFile = resolveUnder(typeof p.page === 'string' ? p.page : '/');
+        const cid = typeof p.cid === 'string' ? p.cid : '';
+        if (!pageFile || extname(pageFile) !== '.html' || !existsSync(pageFile) ||
+            !/^[\w:-]{1,64}$/.test(cid) || typeof p.html !== 'string') {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          return res.end('{"error":"bad write request"}');
+        }
+        const r = applyDirect(pageFile, (src) => replaceInner(src, cid, p.html));
+        res.writeHead(r.code, { 'Content-Type': 'application/json' });
+        res.end(r.body);
+      });
+      return;
+    }
+
+    // --- a direct (no-AI) STRUCTURAL edit: delete or move an element by data-cid (the "Hands") ---
+    if (path === '/__sandpaper/dom' && req.method === 'POST') {
+      let body = '';
+      req.on('data', (d) => { body += d; if (body.length > 1e5) req.destroy(); });
+      req.on('end', () => {
+        let p = {}; try { p = JSON.parse(body || '{}'); } catch {}
+        const okCid = (c) => typeof c === 'string' && /^[\w:-]{1,64}$/.test(c);
+        const pageFile = resolveUnder(typeof p.page === 'string' ? p.page : '/');
+        if (!pageFile || extname(pageFile) !== '.html' || !existsSync(pageFile) || !okCid(p.cid) ||
+            (p.op !== 'delete' && p.op !== 'move') || (p.op === 'move' && !okCid(p.target))) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          return res.end('{"error":"bad dom request"}');
+        }
+        const mode = p.mode === 'after' ? 'after' : 'before';
+        const r = applyDirect(pageFile, (src) => {
+          const out = p.op === 'delete' ? removeElement(src, p.cid) : moveElement(src, p.cid, p.target, mode);
+          return out ? out.html : null;
+        });
+        res.writeHead(r.code, { 'Content-Type': 'application/json' });
+        res.end(r.body);
+      });
+      return;
+    }
+
+    // --- undo the LAST direct edit on a page (restore its pre-edit snapshot) ---
+    if (path === '/__sandpaper/undo-direct' && req.method === 'POST') {
+      let body = '';
+      req.on('data', (d) => { body += d; if (body.length > 1e4) req.destroy(); });
+      req.on('end', () => {
+        let p = {}; try { p = JSON.parse(body || '{}'); } catch {}
+        const pageFile = resolveUnder(typeof p.page === 'string' ? p.page : '/');
+        const snap = pageFile && directSnaps.get(pageFile);
+        if (snap && existsSync(snap)) {
+          try {
+            suppressReloadUntil = 0;          // we WANT the restore to reload the page
+            copyFileSync(snap, pageFile);     // → watcher → reload
+            directSnaps.delete(pageFile);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            return res.end('{"ok":true}');
+          } catch { /* fall through to 404 */ }
+        }
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end('{"error":"nothing to undo"}');
+      });
+      return;
+    }
+
+    // --- toolbar assets (dev chrome, served from the package; never written to disk) ---
+    if (path.startsWith('/__sandpaper/') && (path.endsWith('.js') || path.endsWith('.css'))) {
+      return serveFile(join(PUBLIC, basename(path)), res); // toolbar.js / toolbar.css / sp-markdown.js
+    }
+
+    // --- any file under root: .html gets the toolbar injected, everything else served raw ---
+    const file = resolveUnder(path);
+    if (!file) { res.writeHead(404); return res.end('not found'); }
+    if (extname(file) === '.html') {
+      return readFile(file, 'utf8', (err, html) => {
+        if (err) { res.writeHead(404); return res.end('not found'); }
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(injectToolbar(html));
+      });
+    }
+    return serveFile(file, res);
+  });
+
+  // Watch the served tree; reload the page whose .html changed.
+  let debounce = null;
+  watch(root, { persistent: true, recursive: isDir }, (_evt, fname) => {
+    if (!fname) { if (isDir) return; fname = defaultDoc; } // null filename: only act in single-doc mode
+    const rel = fname.split(sep).join('/');
+    if (rel.startsWith('.sandpaper')) return;             // our own snapshots/session
+    if (!rel.endsWith('.html')) return;                   // only reload on document changes
+    if (!isDir && basename(rel) !== defaultDoc) return;   // single-doc mode: just the doc
+    const page = (isDir && rel === defaultDoc) ? '/' : '/' + rel; // map the root doc back to '/' like the URL
+    clearTimeout(debounce);
+    debounce = setTimeout(() => {
+      // A direct in-place edit we just wrote: the editing browser already shows it — don't reload.
+      if (Date.now() < suppressReloadUntil) return;
+      // Defer ONLY the active turn's own edit (so its reply isn't cut mid-stream); reload any
+      // other (external) change immediately.
+      if (activeTurn && (!isDir || page === activeTurnPage)) { reloadPending = true; return; }
+      broadcast(isDir ? { type: 'reload', page } : { type: 'reload' });
+    }, 120);
+  });
+
+  // Listen on `port`, or the next free port if it's taken — so several repos' Sandpapers
+  // can run at once without colliding on 4848. Resolves with the URL of the port we landed on.
+  return new Promise((resolve, reject) => {
+    let p = port, tries = 0;
+    server.on('error', (e) => {
+      if (e.code === 'EADDRINUSE' && tries++ < 50) { p++; setTimeout(() => server.listen(p, '127.0.0.1'), 0); }
+      else reject(e);
+    });
+    server.on('listening', () => resolve(`http://127.0.0.1:${p}/`));
+    server.listen(p, '127.0.0.1');
+  });
+}
+
+// Pre-turn snapshot of the edited page, so a turn's edits can be undone and recovered.
+function snapshotPath(root, turnId) {
+  const safe = String(turnId || '').replace(/[^a-fA-F0-9-]/g, ''); // turnId is a uuid; reject anything else
+  return safe ? join(root, '.sandpaper', 'snapshots', safe + '.html') : null;
+}
+function snapshot(pageFile, root, turnId) {
+  try {
+    const dir = join(root, '.sandpaper', 'snapshots');
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    copyFileSync(pageFile, snapshotPath(root, turnId));
+  } catch { /* best-effort; never block a turn */ }
+}
+
+// Turn a toolbar payload into a scoped prompt for Claude.
+function buildPrompt(payload, docName) {
+  const { prompt = '', cid, selector, snippet } = payload;
+  if (cid || selector) {
+    const where = cid ? `the element with data-cid="${cid}"` : `the element matching CSS selector \`${selector}\``;
+    const ctx = snippet ? `\nFor reference, its current content begins: "${snippet}"` : '';
+    return `In ${docName}, edit ONLY ${where}.${ctx}\n\nRequested change: ${prompt}\n\n` +
+      'Make the smallest edit that satisfies this and leave the rest of the document unchanged.';
+  }
+  return `In ${docName}: ${prompt}\n\nMake the smallest edit that satisfies this; do not regenerate unrelated parts of the document.`;
+}