pathnote 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shinehyeuk
+
+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

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# Pathnote
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+See which files your AI searched, read and wrote, live on a map of your folders.
+
+Pathnote is an MCP server for the folders you choose (notes, an Obsidian vault, project folders) plus a local viewer page. The viewer draws the folders as a tree, with `[[wikilinks]]` between markdown notes. While Claude, Cursor or another MCP client works, it draws the path on top: the files it searched, the folders and files it opened in order, and the files it wrote, linked to the files they came from. Every file the AI creates, edits or moves can be undone from the viewer.
+
+Free, MIT licensed. Runs entirely on your computer; nothing is sent anywhere by Pathnote.
+
+## Try it
+
+You need Node.js 20 or later.
+
+Start with the sample notes so nothing of yours is touched:
+
+```bash
+npx -y pathnote --sample ~/pathnote-sample
+```
+
+### Claude Desktop
+
+Quit Claude Desktop first (⌘Q). It rewrites its config file while running, so edits made with it open can be lost. Then add Pathnote to `mcpServers` in `~/Library/Application Support/Claude/claude_desktop_config.json`. List as many folders as you like:
+
+```json
+{
+  "mcpServers": {
+    "pathnote": {
+      "command": "npx",
+      "args": ["-y", "pathnote", "/Users/you/pathnote-sample", "/Users/you/Projects"]
+    }
+  }
+}
+```
+
+Open Claude Desktop again, open http://127.0.0.1:4747 in your browser, and ask Claude something like:
+
+> Go through the meeting notes and customer interviews and write next quarter's priorities as a new note.
+
+### Claude Code
+
+```bash
+claude mcp add pathnote -- npx -y pathnote ~/pathnote-sample ~/Projects
+```
+
+### Cursor and other MCP clients
+
+Use the same command: `npx -y pathnote <folder> [<folder> ...]`.
+
+## The viewer
+
+- http://127.0.0.1:4747 (the next free port if 4747 is taken; the address is printed to the client's MCP log).
+- Drag to move, scroll to zoom. File names appear as you zoom in.
+- Several AI sessions on the same folders all report to one viewer.
+- To keep the viewer open while clients come and go: `npx pathnote <folders> --viewer`.
+- **Undo** puts a file back the way it was before the AI changed it. If you edited it yourself afterwards, Pathnote leaves it alone and says so.
+- **Clear path** clears the drawing, not your files.
+
+## Tools the AI gets
+
+| Tool | What it does |
+|---|---|
+| `list_files` | The connected folders, or what is inside one folder |
+| `search_files` | Text files and documents matching some words, with a snippet each |
+| `read_file` | A text file as is (up to 2 MB); PDF, Word, PowerPoint, Excel and Hangul (.hwpx) files as their text; pictures (PNG, JPEG, GIF, WebP, HEIC) as images the AI can see (up to 50 MB) |
+| `write_file` | Create a text file or replace its text (undoable). Documents and pictures are never written |
+| `edit_file` | Replace one exact piece of text in a file (undoable) |
+| `move_file` | Move or rename a file or folder of any type, creating missing folders; never overwrites (undoable) |
+
+Each tool takes an optional `reason`, a short sentence the viewer shows next to the step.
+
+## What Pathnote touches
+
+- Only files inside the folders you list. Anything outside them is refused, including through symlinks.
+- Old Hangul `.hwp` files and other binary formats can't be read. Scanned PDFs without a text layer come back empty.
+- Skipped: hidden files and folders, `.git`, `node_modules`, build output, and files that usually hold secrets (`.env`, `*.pem`, `*.p8`, `*.key`, SSH keys, `credentials.json`, `token.json`, `client_secret*.json`, folders named `secrets`). The AI can't read or write them, and the viewer doesn't show them.
+- Whatever the AI reads, including document text and pictures, is sent to the AI service you use, like anything else you share with it.
+- The AI can create and change any other text file in those folders. Connect only folders you are comfortable letting it edit.
+- The text of each file before the AI changed it is kept in `~/.pathnote/` so it can be undone. Delete that folder to clear the history.
+- The viewer only listens on 127.0.0.1 and refuses requests from other websites.
+
+## macOS folder permissions
+
+Desktop, Documents, Downloads and iCloud Drive are protected by macOS. The first time Pathnote reads one, macOS asks whether the app that runs Pathnote (Claude, Terminal, ...) may access it. Until you allow it, the viewer shows that folder as empty and says so. You can change this later in System Settings → Privacy & Security → Files and Folders.
+
+## Development
+
+```bash
+npm install
+npm test
+node bin/pathnote.js examples/sample-vault --viewer
+```

package/bin/pathnote.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// pathnote <folder> [<folder> ...] [--port 4747] [--viewer]
+// pathnote --sample <new folder>   copies the sample notes there, to try Pathnote safely
+//   Started by an MCP client: MCP over stdin/stdout, plus the viewer at http://127.0.0.1:4747
+//   --viewer: only the viewer, for keeping it open while MCP clients come and go
+// stdout belongs to MCP, so every message for people goes to stderr.
+import fs from 'node:fs';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Workspace } from '../src/workspace.js';
+import { History } from '../src/history.js';
+import { Hub } from '../src/hub.js';
+import { createServer } from '../src/mcp.js';
+
+const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url)));
+const args = process.argv.slice(2);
+const flag = name => args.includes(name);
+const opt = name => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+const folders = args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--port');
+const folder = folders[0];
+
+if (flag('--sample')) {
+  if (!folder) { console.error('Usage: pathnote --sample <new folder>'); process.exit(1); }
+  if (fs.existsSync(folder)) { console.error(`Pathnote: "${folder}" already exists. Pick a new folder.`); process.exit(1); }
+  fs.cpSync(new URL('../examples/sample-vault', import.meta.url), folder, { recursive: true });
+  console.error(`Sample notes copied to ${fs.realpathSync(folder)}`);
+  process.exit(0);
+}
+if (!folder || flag('--help')) {
+  console.error(`Pathnote ${pkg.version}\n\nUsage: pathnote <folder> [<folder> ...] [--port 4747] [--viewer]\n       pathnote --sample <new folder>`);
+  process.exit(folder ? 0 : 1);
+}
+for (const f of folders) {
+  if (!fs.existsSync(f) || !fs.statSync(f).isDirectory()) {
+    console.error(`Pathnote: "${f}" is not a folder.`);
+    process.exit(1);
+  }
+}
+
+const ws = new Workspace(folders);
+const history = new History(ws);
+const hub = new Hub(ws, history, Number(opt('--port')) || 4747);
+const url = await hub.start();
+console.error(`Pathnote ${pkg.version}: ${ws.roots.join(', ')}\nViewer: ${url}`);
+ws.warm().catch(() => {});
+
+if (!flag('--viewer')) {
+  await createServer({ ws, history, hub, version: pkg.version }).connect(new StdioServerTransport());
+  // The viewer server would keep the process alive after the MCP client quits
+  process.stdin.on('close', () => process.exit(0));
+}

package/examples/sample-vault/Ideas.md

@@ -0,0 +1,5 @@
+# Ideas
+
+- Keyboard-first capture
+- Weekly digest email
+- Templates gallery

package/examples/sample-vault/Meetings/Oct team meeting.md

@@ -0,0 +1,7 @@
+# Oct team meeting
+
+- Onboarding: still no decision. Several people think setup takes too long.
+- Pricing: proposal to drop the monthly-only plan. Parked until we hear from customers.
+- Action: read through [[Customer interviews]] before the next planning session.
+
+Related: [[Weekly review]], [[Budget plan]]

package/examples/sample-vault/Meetings/Weekly review.md

@@ -0,0 +1,3 @@
+# Weekly review
+
+Shipped the new search. Next week: start on onboarding research with [[Oct team meeting]] notes.

package/examples/sample-vault/Product/Budget plan.md

@@ -0,0 +1,3 @@
+# Budget plan
+
+Q1 budget allows one extra contractor for 8 weeks. See [[Product roadmap]].

package/examples/sample-vault/Product/Product roadmap.md

@@ -0,0 +1,8 @@
+# Product roadmap
+
+Next quarter candidates:
+1. Guided onboarding (first-run checklist, import wizard)
+2. Annual pricing
+3. Team spaces
+
+Inputs: [[Customer interviews]], [[Signup metrics]], [[Competitor comparison]]

package/examples/sample-vault/README.md

@@ -0,0 +1,5 @@
+# Sample vault
+
+Example notes for trying Pathnote safely. Ask your AI something like:
+
+"Go through the meeting notes and customer interviews and write next quarter's priorities as a new note."

package/examples/sample-vault/Research/Competitor comparison.md

@@ -0,0 +1,5 @@
+# Competitor comparison
+
+Two competitors ship an import wizard. Both offer annual plans at about 20% off.
+
+See [[Product roadmap]].

package/examples/sample-vault/Research/Customer interviews.md

@@ -0,0 +1,9 @@
+# Customer interviews
+
+Seven interviews in September.
+
+- 5 of 7 said first-time setup was the hardest part.
+- 3 of 7 asked for an annual plan.
+- 2 of 7 compared us with the tools in [[Competitor comparison]].
+
+Raw quotes are collected in [[User feedback]].

package/examples/sample-vault/Research/Signup metrics.md

@@ -0,0 +1,7 @@
+# Signup metrics
+
+- Visit to signup: 4.1%
+- Signup to first note: 38% (this is where most people leave)
+- First note to week-2 active: 61%
+
+Linked from [[Product roadmap]].

package/examples/sample-vault/Research/User feedback.md

@@ -0,0 +1,7 @@
+# User feedback
+
+> "I gave up on importing my notes the first day."
+> "Once it was set up, I used it every day."
+> "I'd pay yearly if it were cheaper than monthly."
+
+Themes: setup friction, price per year. See [[Signup metrics]] for the drop-off numbers.

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "pathnote",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "See which files your AI searched, read and wrote, live on a map of your folders. MCP server + local viewer.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "obsidian",
+    "markdown",
+    "notes",
+    "claude",
+    "ai",
+    "knowledge-graph"
+  ],
+  "homepage": "https://pathnote.pages.dev",
+  "type": "module",
+  "bin": {
+    "pathnote": "bin/pathnote.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "viewer",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "fflate": "0.8.3",
+    "unpdf": "1.9.1",
+    "zod": "^4.6.7"
+  }
+}

package/src/documents.js

@@ -0,0 +1,98 @@
+// Reads files that aren't plain text: text out of PDF, Word, PowerPoint, Excel and Hangul (.hwpx)
+// files, and pictures as images the AI can look at. Read-only: Pathnote never writes these.
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { unzipSync, strFromU8 } from 'fflate';
+import { getDocumentProxy, extractText } from 'unpdf';
+
+const run = promisify(execFile);
+const DOCS = new Set(['.pdf', '.docx', '.pptx', '.xlsx', '.hwpx']);
+const IMAGES = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.heic': 'image/heic' };
+export const MAX_DOC = 50 * 1024 * 1024;
+const MAX_TEXT = 200_000;
+// Claude accepts images up to about 5 MB once base64-encoded
+const MAX_IMAGE = 3.5 * 1024 * 1024;
+
+export const isDocument = p => DOCS.has(path.extname(p).toLowerCase());
+export const isImage = p => path.extname(p).toLowerCase() in IMAGES;
+
+const decode = s => s
+  .replace(/&#x([0-9a-f]+);/gi, (_, h) => String.fromCodePoint(parseInt(h, 16)))
+  .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(+d))
+  .replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&');
+
+// XML -> text, with a line break wherever the format ends a paragraph
+const xmlText = (xml, paragraph) => decode(xml
+  .replace(new RegExp(`</${paragraph}>`, 'g'), '\n')
+  .replace(/<(w:tab|a:tab|hp:tab)\b[^>]*\/>/g, '\t')
+  .replace(/<[^>]+>/g, ''))
+  .replace(/\n{3,}/g, '\n\n').trim();
+
+// "ppt/slides/slide10.xml" sorts after "slide9.xml"
+const byNumber = (a, b) => (+a.match(/(\d+)\.xml$/)?.[1] || 0) - (+b.match(/(\d+)\.xml$/)?.[1] || 0);
+
+function unzip(buf, keep) {
+  const files = unzipSync(new Uint8Array(buf), { filter: f => keep(f.name) });
+  return Object.fromEntries(Object.entries(files).map(([k, v]) => [k, strFromU8(v)]));
+}
+
+function xlsx(buf) {
+  const z = unzip(buf, n => n === 'xl/sharedStrings.xml' || n === 'xl/workbook.xml' || /^xl\/worksheets\/sheet\d+\.xml$/.test(n));
+  const shared = [...(z['xl/sharedStrings.xml'] || '').matchAll(/<si>([\s\S]*?)<\/si>/g)].map(m => decode(m[1].replace(/<[^>]+>/g, '')));
+  const names = [...(z['xl/workbook.xml'] || '').matchAll(/<sheet [^>]*name="([^"]*)"/g)].map(m => decode(m[1]));
+  return Object.keys(z).filter(k => k.startsWith('xl/worksheets/')).sort(byNumber).map((k, i) => {
+    const rows = [...z[k].matchAll(/<row\b[^>]*>([\s\S]*?)<\/row>/g)].map(r =>
+      [...r[1].matchAll(/<c\b([^>]*?)(?:\/>|>([\s\S]*?)<\/c>)/g)].map(([, attrs, body = '']) => {
+        const v = body.match(/<v>([\s\S]*?)<\/v>/)?.[1];
+        if (/t="s"/.test(attrs)) return shared[+v] ?? '';
+        if (/t="inlineStr"/.test(attrs)) return decode(body.replace(/<[^>]+>/g, ''));
+        return v === undefined ? '' : decode(v);
+      }).join('\t'));
+    return `--- sheet: ${names[i] ?? i + 1} ---\n${rows.join('\n')}`;
+  }).join('\n\n');
+}
+
+// Text of a document. `buf` is the file's bytes.
+export async function documentText(file, buf) {
+  const ext = path.extname(file).toLowerCase();
+  let text;
+  if (ext === '.pdf') {
+    const pdf = await getDocumentProxy(new Uint8Array(buf));
+    const { text: pages } = await extractText(pdf, { mergePages: false });
+    text = pages.map((t, i) => `--- page ${i + 1} ---\n${t.trim()}`).join('\n\n');
+  } else if (ext === '.docx') {
+    text = xmlText(unzip(buf, n => n === 'word/document.xml')['word/document.xml'] || '', 'w:p');
+  } else if (ext === '.pptx') {
+    const z = unzip(buf, n => /^ppt\/slides\/slide\d+\.xml$/.test(n));
+    text = Object.keys(z).sort(byNumber).map((k, i) => `--- slide ${i + 1} ---\n${xmlText(z[k], 'a:p')}`).join('\n\n');
+  } else if (ext === '.xlsx') {
+    text = xlsx(buf);
+  } else if (ext === '.hwpx') {
+    const z = unzip(buf, n => /^Contents\/section\d+\.xml$/.test(n));
+    text = Object.keys(z).sort(byNumber).map(k => xmlText(z[k], 'hp:p')).join('\n\n');
+  } else {
+    throw new Error(`Pathnote can't read ${ext} files.`);
+  }
+  if (!text.trim()) return '(No text found. It may be a scanned document made of images.)';
+  return text.length > MAX_TEXT ? text.slice(0, MAX_TEXT) + `\n\n(cut off at ${MAX_TEXT} characters)` : text;
+}
+
+// An image the AI can look at. HEIC (iPhone photos) and large pictures go through macOS `sips`
+// to become a JPEG small enough to send.
+export async function imageContent(file, buf) {
+  const ext = path.extname(file).toLowerCase();
+  if (ext !== '.heic' && buf.length <= MAX_IMAGE) return { data: buf.toString('base64'), mimeType: IMAGES[ext] };
+  if (process.platform !== 'darwin') throw new Error(`"${file}" is too large to send as an image (over 3.5 MB).`);
+  const out = path.join(await fs.mkdtemp(path.join(os.tmpdir(), 'pathnote-')), 'image.jpg');
+  try {
+    await run('sips', ['-s', 'format', 'jpeg', '-s', 'formatOptions', '80', '-Z', '1600', file, '--out', out]);
+    const small = await fs.readFile(out);
+    if (small.length > MAX_IMAGE) throw new Error(`"${file}" is still too large after shrinking.`);
+    return { data: small.toString('base64'), mimeType: 'image/jpeg' };
+  } finally {
+    await fs.rm(path.dirname(out), { recursive: true, force: true });
+  }
+}

package/src/history.js

@@ -0,0 +1,62 @@
+// Keeps the text a note had before the AI changed it, so each change can be undone.
+// Stored outside the connected folders (~/.pathnote/<id>/history.jsonl) to keep them clean.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+
+export class History {
+  constructor(ws) {
+    this.ws = ws;
+    const id = crypto.createHash('sha1').update(ws.id).digest('hex').slice(0, 12);
+    this.file = path.join(os.homedir(), '.pathnote', id, 'history.jsonl');
+  }
+
+  async all() {
+    try {
+      return (await fs.readFile(this.file, 'utf8')).split('\n').filter(Boolean).map(l => JSON.parse(l));
+    } catch (e) {
+      if (e.code === 'ENOENT') return [];
+      throw e;
+    }
+  }
+
+  async append(entry) {
+    await fs.mkdir(path.dirname(this.file), { recursive: true });
+    await fs.appendFile(this.file, JSON.stringify(entry) + '\n');
+  }
+
+  // Call before changing a file. `before` is null for a file that didn't exist.
+  async record(rel, before, after, kind) {
+    const entry = { id: crypto.randomUUID(), t: Date.now(), path: rel, kind, before, after };
+    await this.append(entry);
+    return entry;
+  }
+
+  async recordMove(from, to) {
+    const entry = { id: crypto.randomUUID(), t: Date.now(), path: to, kind: 'move', from, to };
+    await this.append(entry);
+    return entry;
+  }
+
+  // Put the note back the way it was before change `id`. Refuses if someone edited it since,
+  // so a user's own later edits are never thrown away.
+  async undo(id) {
+    const all = await this.all();
+    const entry = all.find(e => e.id === id);
+    if (!entry) throw new Error('No such change.');
+    if (all.some(e => e.undoes === id)) throw new Error('Already undone.');
+    if (entry.kind === 'move') {
+      // put it back where it was, as long as nothing has taken either place since
+      await this.ws.move(entry.to, entry.from);
+      await this.append({ id: crypto.randomUUID(), t: Date.now(), path: entry.from, kind: 'undo', undoes: id });
+      return entry;
+    }
+    const now = await this.ws.readOrNull(entry.path);
+    if (now !== entry.after) throw new Error(`"${entry.path}" changed after the AI wrote it, so it was left as is.`);
+    if (entry.before === null) await this.ws.remove(entry.path);
+    else await this.ws.write(entry.path, entry.before);
+    await this.append({ id: crypto.randomUUID(), t: Date.now(), path: entry.path, kind: 'undo', undoes: id });
+    return entry;
+  }
+}

package/src/hub.js

@@ -0,0 +1,137 @@
+// Local viewer server: serves the graph page and streams what the AI does to it.
+// Claude Desktop may start several Pathnote processes; the first one for a set of folders owns the
+// viewer port and the others forward their events to it.
+import http from 'node:http';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PAGE = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'viewer', 'index.html');
+const KEEP = 500;
+
+export class Hub {
+  constructor(ws, history, port) {
+    this.ws = ws;
+    this.history = history;
+    this.port = port;
+    this.events = [];
+    this.clients = new Set();
+    this.forwardTo = null; // port of another process that owns the viewer
+    this.boot = Date.now().toString(36); // with seq, lets the page skip events it already has
+    this.seq = 0;
+  }
+
+  // Own a port for these folders, or find the process that already does. Returns the viewer URL.
+  async start() {
+    for (let port = this.port; port < this.port + 10; port++) {
+      const other = await this.info(port);
+      if (other?.id === this.ws.id) { this.forwardTo = port; return `http://127.0.0.1:${port}`; }
+      if (other) continue;
+      try {
+        await this.listen(port);
+        this.port = port;
+        return `http://127.0.0.1:${port}`;
+      } catch (e) {
+        if (e.code !== 'EADDRINUSE') throw e;
+      }
+    }
+    throw new Error(`No free port between ${this.port} and ${this.port + 9}.`);
+  }
+
+  async info(port) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/api/info`, { signal: AbortSignal.timeout(500) });
+      const body = await res.json();
+      return body.app === 'pathnote' ? body : null;
+    } catch {
+      return null;
+    }
+  }
+
+  listen(port) {
+    return new Promise((resolve, reject) => {
+      const server = http.createServer((req, res) => this.handle(req, res).catch(e => send(res, 500, { error: e.message })));
+      server.once('error', reject);
+      server.listen(port, '127.0.0.1', () => { this.server = server; resolve(); });
+    });
+  }
+
+  async emit(event, retried = false) {
+    const e = { t: Date.now(), ...event };
+    if (this.forwardTo) {
+      try {
+        await fetch(`http://127.0.0.1:${this.forwardTo}/api/event`, {
+          method: 'POST', headers: { 'Content-Type': 'application/json', Origin: `http://127.0.0.1:${this.forwardTo}` },
+          body: JSON.stringify(e), signal: AbortSignal.timeout(1000)
+        });
+        return;
+      } catch {
+        // The process that owned the viewer has quit: take the port over and keep showing events
+        this.forwardTo = null;
+        if (retried) return;
+        try { await this.start(); } catch { return; }
+        if (this.forwardTo) return this.emit(event, true);
+      }
+    }
+    this.broadcast(e);
+  }
+
+  broadcast(event) {
+    const e = { ...event, key: `${this.boot}:${++this.seq}` };
+    this.events.push(e);
+    if (this.events.length > KEEP) this.events.shift();
+    for (const res of this.clients) res.write(`data: ${JSON.stringify(e)}\n\n`);
+  }
+
+  // Only pages served from this port may call the API, so other websites can't trigger undo.
+  allowed(req) {
+    const hosts = [`127.0.0.1:${this.port}`, `localhost:${this.port}`];
+    if (!hosts.includes(req.headers.host)) return false;
+    const origin = req.headers.origin;
+    return req.method === 'GET' ? !origin || hosts.some(h => origin === `http://${h}`) : hosts.some(h => origin === `http://${h}`);
+  }
+
+  async handle(req, res) {
+    if (!this.allowed(req)) return send(res, 403, { error: 'forbidden' });
+    const url = new URL(req.url, 'http://x');
+    if (req.method === 'GET' && url.pathname === '/') {
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
+      return res.end(await fs.readFile(PAGE));
+    }
+    if (req.method === 'GET' && url.pathname === '/api/info') return send(res, 200, { app: 'pathnote', id: this.ws.id, roots: this.ws.roots });
+    if (req.method === 'GET' && url.pathname === '/api/graph') return send(res, 200, await this.ws.graph());
+    if (req.method === 'GET' && url.pathname === '/api/events') {
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', Connection: 'keep-alive' });
+      for (const e of this.events) res.write(`data: ${JSON.stringify(e)}\n\n`);
+      this.clients.add(res);
+      req.on('close', () => this.clients.delete(res));
+      return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/event') {
+      this.broadcast(await body(req));
+      return send(res, 200, { ok: true });
+    }
+    if (req.method === 'POST' && url.pathname === '/api/undo') {
+      const { id } = await body(req);
+      try {
+        const entry = await this.history.undo(id);
+        this.broadcast({ t: Date.now(), type: 'undo', path: entry.kind === 'move' ? entry.to : entry.path, changeId: id, created: entry.before === null || entry.kind === 'move', back: entry.kind === 'move' ? entry.from : undefined });
+        return send(res, 200, { ok: true });
+      } catch (e) {
+        return send(res, 409, { error: e.message });
+      }
+    }
+    send(res, 404, { error: 'not found' });
+  }
+}
+
+function send(res, status, data) {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(data));
+}
+
+async function body(req) {
+  let s = '';
+  for await (const chunk of req) { s += chunk; if (s.length > 1e6) throw new Error('too large'); }
+  return JSON.parse(s || '{}');
+}