hdoc-tools 0.52.0 → 0.52.1

package/hdoc-edit.js

@@ -0,0 +1,1449 @@
+// `hdoc edit` — the structure/content editor server (Phase 1 stub).
+//
+// This is the write-capable sibling of `hdoc serve`. It reuses the SAME
+// /_books/* content + render pipeline (via hdoc-content-routes.js) so the
+// editor's live preview is byte-identical to published output, and it serves
+// a SEPARATE UI surface from editor/ (React + Vite, built to editor/dist).
+//
+// Key differences from `hdoc serve`:
+//   - binds 127.0.0.1 only (it has write access; must not be reachable on the LAN)
+//   - serves the editor SPA, not the Vue viewer in ui/
+//   - will host write routes (/api/toc, /api/page/:id, /api/move) in later phases
+//
+// This stub mounts (1) the shared preview routes and (2) a placeholder editor
+// UI, proving the server shape before the React toolchain is introduced.
+
+(() => {
+	const express = require("express");
+	const fs = require("node:fs");
+	const path = require("node:path");
+	const crypto = require("node:crypto");
+	const os = require("node:os");
+	const { execFile } = require("node:child_process");
+	const hdoc = require(path.join(__dirname, "hdoc-module.js"));
+
+	const sha1 = (data) =>
+		crypto.createHash("sha1").update(Buffer.from(data)).digest("hex");
+	const { create_content_handler } = require(
+		path.join(__dirname, "hdoc-content-routes.js"),
+	);
+	const { TocModel } = require(path.join(__dirname, "hdoc-toc.js"));
+	const { dialect_findings } = require(path.join(__dirname, "hdoc-spell.js"));
+
+	let port = 3000;
+
+	// editor_path is the directory containing the editor SPA. For the stub this
+	// is editor/ (a hand-written placeholder index.html). Once the React app is
+	// scaffolded, point this at editor/dist (the Vite build output).
+	exports.run = async (editor_path, source_path) => {
+		for (let x = 0; x < process.argv.length; x++) {
+			// First two arguments are command, and script
+			if (x === 0 || x === 1) continue;
+
+			if (process.argv[x].toLowerCase() === "-port") {
+				x++;
+				if (x < process.argv.length) {
+					port = process.argv[x];
+				}
+			}
+		}
+
+		console.log("Hornbill HDocBook Editor Server", "\r\n");
+		console.log("  Editor UI Path:", editor_path);
+		console.log("   Document Path:", source_path, "\r\n");
+		console.log("     Server Port:", port);
+
+		const app = express();
+
+		// --- Active workspace (book) ---
+		// The book context is MUTABLE so the editor can switch which local clone
+		// it edits at runtime (the GitHub-Desktop "Open" flow). Every route below
+		// references these `let`s by name, so reassigning them in open_workspace()
+		// re-points the whole editor at a new book with no per-route changes.
+		let hdocbook_project;
+		let docId;
+		let nav_inline = {};
+		let hdocbook_config;
+		let content;
+		let toc;
+		let project_path;
+		let watcher = null;
+
+		// --- live filesystem sync (auto-save friendly) ---
+		// Connected SSE clients + a record of files WE just wrote, so the watcher
+		// can ignore our own writes and only push genuine external changes.
+		const sse_clients = new Set();
+		const recent_writes = new Map(); // absPath -> { hash, time }
+
+		const note_write = (abs, data) => {
+			recent_writes.set(abs, { hash: sha1(data), time: Date.now() });
+			// prune old entries
+			const cutoff = Date.now() - 10000;
+			for (const [k, v] of recent_writes) {
+				if (v.time < cutoff) recent_writes.delete(k);
+			}
+		};
+
+		const broadcast = (evt) => {
+			const data = `data: ${JSON.stringify(evt)}\n\n`;
+			for (const c of sse_clients) {
+				try {
+					c.write(data);
+				} catch {
+					/* client gone */
+				}
+			}
+		};
+
+		const handle_fs_change = (rel) => {
+			const abs = path.join(source_path, rel);
+			let exists = false;
+			let buf = null;
+			try {
+				if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+					exists = true;
+					buf = fs.readFileSync(abs);
+				}
+			} catch {
+				/* transient */
+			}
+			// Ignore our own writes (content matches what we just wrote).
+			if (exists && buf) {
+				const note = recent_writes.get(abs);
+				if (note && note.hash === sha1(buf) && Date.now() - note.time < 5000) {
+					return;
+				}
+			}
+			// External structure edit → resync the in-memory model.
+			if (toc && abs === toc.hdocbook_path) {
+				if (exists) {
+					try {
+						toc.reload();
+					} catch (e) {
+						console.error("TOC reload failed:", e.message);
+					}
+				}
+				broadcast({ type: "structure" });
+				return;
+			}
+			broadcast({ type: "fs", path: rel, exists });
+		};
+
+		// (Re)start the recursive file watcher for the current book, closing any
+		// previous one. fs.watch recursive works on Windows/macOS (Linux: chokidar).
+		const watch_debounce = new Map();
+		const start_watch = () => {
+			if (watcher) {
+				try {
+					watcher.close();
+				} catch {
+					/* ignore */
+				}
+				watcher = null;
+			}
+			watch_debounce.clear();
+			const watch_root = path.join(source_path, docId);
+			try {
+				watcher = fs.watch(watch_root, { recursive: true }, (_event, filename) => {
+					if (!filename) return;
+					const rel = `${docId}/${String(filename).split(path.sep).join("/")}`;
+					clearTimeout(watch_debounce.get(rel));
+					watch_debounce.set(
+						rel,
+						setTimeout(() => {
+							watch_debounce.delete(rel);
+							handle_fs_change(rel);
+						}, 120),
+					);
+				});
+				console.log("Watching for external changes:", watch_root);
+			} catch (e) {
+				console.error("File watching unavailable:", e.message);
+			}
+		};
+
+		// Point the editor at a book (a directory containing hdocbook-project.json).
+		// Reassigns the workspace `let`s, rebuilds the content handler + TOC model,
+		// and re-starts the watcher. Throws if the path isn't a valid HDocBook.
+		// Files are read fresh (not require()) so re-opening picks up disk changes.
+		const open_workspace = (sp) => {
+			const proj_path = path.join(sp, "hdocbook-project.json");
+			if (!fs.existsSync(proj_path)) {
+				throw new Error("Not an HDocBook (no hdocbook-project.json)");
+			}
+			const proj = JSON.parse(fs.readFileSync(proj_path, "utf8"));
+			const id = proj.docId;
+			if (!id) throw new Error("hdocbook-project.json has no docId");
+			const cfg = JSON.parse(
+				fs.readFileSync(path.join(sp, id, "hdocbook.json"), "utf8"),
+			);
+
+			// Inline-help nav fragment, surfaced via /_books/library.json.
+			let inline = {};
+			const inline_path = path.join(sp, id, "_inline");
+			if (fs.existsSync(inline_path)) {
+				inline = { text: "Inline Help Items", expand: true, inline: true, items: [] };
+				for (const file of fs.readdirSync(inline_path)) {
+					inline.items.push({
+						text: file.replace(path.extname(file), ""),
+						link: `${id}/_inline/${file.replace(path.extname(file), "")}`,
+					});
+				}
+			}
+
+			source_path = sp;
+			hdocbook_project = proj;
+			docId = id;
+			hdocbook_config = cfg;
+			nav_inline = inline;
+			project_path = proj_path;
+			content = create_content_handler({
+				source_path,
+				docId,
+				hdocbook_config,
+				hdocbook_project,
+				nav_inline,
+			});
+			toc = new TocModel(source_path, docId);
+			toc.on_persist = note_write; // suppress our own hdocbook.json writes
+			start_watch();
+			console.log("Active workspace:", source_path, `(docId: ${docId})`);
+		};
+
+		// Open the launch path if it's a valid book; otherwise start with NO book
+		// open (VS Code-style welcome — the user opens a book from the editor's
+		// Repositories panel). The server stays up either way.
+		try {
+			open_workspace(source_path);
+		} catch {
+			console.log(
+				"No HDocBook at the launch path — starting with no book open.",
+			);
+		}
+
+		// Book-dependent routes 409 cleanly when no book is open, rather than
+		// throwing on a null TOC / content handler.
+		const BOOK_REQUIRED =
+			/^\/(?:_books|api\/(?:toc|page|pagefile|preview|files|pages|upload|spellcheck|dictionary))(?:\/|$)/;
+		app.use((req, res, next) => {
+			if (!toc && BOOK_REQUIRED.test(req.path)) {
+				return res.status(409).json({ error: "No book open" });
+			}
+			next();
+		});
+
+		// (1) Shared preview pipeline — identical to `hdoc serve`. Delegated to the
+		// CURRENT workspace's content handler so it follows workspace switches.
+		app.get("/_books/library.json", (req, res) =>
+			content.handle_library_request(req, res),
+		);
+		app.get("/_books/*splat", (req, res) => content.handle_books_request(req, res));
+
+		// Serve the published viewer's theme assets (theme-default CSS + highlight.js)
+		// under /_ui so the editor's live preview can render with the EXACT same
+		// styling as `hdoc serve`. Not book-bound. Same files the production viewer
+		// (ui/index.html) loads — no copies, so the preview can never drift.
+		app.use("/_ui", express.static(path.join(__dirname, "ui")));
+
+		// Parse JSON bodies for the /api/* write routes (markdown can be large).
+		app.use(express.json({ limit: "5mb" }));
+
+		// Server-Sent Events stream of filesystem changes.
+		app.get("/api/events", (req, res) => {
+			res.writeHead(200, {
+				"Content-Type": "text/event-stream",
+				"Cache-Control": "no-cache",
+				Connection: "keep-alive",
+			});
+			res.write(": connected\n\n");
+			sse_clients.add(res);
+			const hb = setInterval(() => {
+				try {
+					res.write(": hb\n\n");
+				} catch {
+					/* ignore */
+				}
+			}, 25000);
+			req.on("close", () => {
+				clearInterval(hb);
+				sse_clients.delete(res);
+			});
+		});
+
+		// Current active workspace (book) — { open:false } when none is open.
+		app.get("/api/workspace", (req, res) => {
+			if (!toc) return res.json({ open: false });
+			res.json({
+				open: true,
+				path: source_path,
+				docId,
+				title: (hdocbook_config && hdocbook_config.title) || docId,
+			});
+		});
+
+		// Open a local book (the GitHub-Desktop "Open" flow). Re-points the whole
+		// server and tells connected clients to reload.
+		app.post("/api/workspace/open", (req, res) => {
+			const body = req.body || {};
+			const sp = String(body.path || "");
+			if (!sp) return res.status(400).json({ error: "Missing path" });
+			try {
+				open_workspace(sp);
+			} catch (e) {
+				return res.status(400).json({ error: String((e && e.message) || e) });
+			}
+			broadcast({ type: "workspace" });
+			res.json({
+				ok: true,
+				open: true,
+				path: source_path,
+				docId,
+				title: (hdocbook_config && hdocbook_config.title) || docId,
+			});
+		});
+
+		// Close the current book → back to the no-book welcome state.
+		app.post("/api/workspace/close", (req, res) => {
+			if (watcher) {
+				try {
+					watcher.close();
+				} catch {
+					/* ignore */
+				}
+				watcher = null;
+			}
+			source_path = undefined;
+			hdocbook_project = undefined;
+			docId = undefined;
+			hdocbook_config = undefined;
+			content = undefined;
+			toc = undefined;
+			project_path = undefined;
+			nav_inline = {};
+			console.log("Closed workspace (no book open).");
+			broadcast({ type: "workspace" });
+			res.json({ open: false });
+		});
+
+		app.get("/api/toc", (req, res) => {
+			try {
+				res.json(toc.to_dto());
+			} catch (e) {
+				console.error("Failed to build TOC:", e);
+				res.status(500).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// Load a page's raw markdown source (for editing — NOT rendered/expanded).
+		app.get("/api/page/:id", (req, res) => {
+			const resolved = toc.resolve_file(req.params.id);
+			if (!resolved) return res.status(404).json({ error: "Unknown node id" });
+			if (!resolved.abs) {
+				return res
+					.status(400)
+					.json({ error: "Node is not an editable page (no link)" });
+			}
+			if (!resolved.exists) {
+				return res
+					.status(404)
+					.json({ error: "Page file not found", file: resolved.file });
+			}
+			try {
+				const content_txt = fs.readFileSync(resolved.abs, "utf8");
+				res.json({
+					id: resolved.node.id,
+					link: resolved.link,
+					file: resolved.file,
+					content: content_txt,
+				});
+			} catch (e) {
+				res.status(500).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// Render an editor buffer to HTML via the SAME pipeline as published output
+		// (preview == published). Anchored at the node's file so includes resolve.
+		app.post("/api/preview", async (req, res) => {
+			const body = req.body || {};
+			if (typeof body.content !== "string") {
+				return res.status(400).json({ error: "Missing content" });
+			}
+			let file_path = path.join(source_path, docId, "_preview.md");
+			if (typeof body.file === "string" && body.file) {
+				try {
+					file_path = toc._safe_rel(body.file, { dir: false }).abs;
+				} catch {
+					/* fall back to default anchor */
+				}
+			} else if (body.id) {
+				const resolved = toc.resolve_file(body.id);
+				if (resolved && resolved.abs) file_path = resolved.abs;
+			}
+			try {
+				const result = await content.render_markdown(file_path, body.content);
+				res.json(result);
+			} catch (e) {
+				console.error("Preview render failed:", e);
+				res.status(500).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// Save a page's markdown source back to disk. The path is resolved from the
+		// trusted TOC model (by id), never from a client-supplied path.
+		app.put("/api/page/:id", (req, res) => {
+			const resolved = toc.resolve_file(req.params.id);
+			if (!resolved) return res.status(404).json({ error: "Unknown node id" });
+			if (!resolved.abs) {
+				return res
+					.status(400)
+					.json({ error: "Node is not an editable page (no link)" });
+			}
+			const body = req.body || {};
+			if (typeof body.content !== "string") {
+				return res.status(400).json({ error: "Missing content" });
+			}
+			try {
+				fs.mkdirSync(path.dirname(resolved.abs), { recursive: true });
+				fs.writeFileSync(resolved.abs, body.content, "utf8");
+				res.json({
+					ok: true,
+					file: resolved.file,
+					bytes: Buffer.byteLength(body.content, "utf8"),
+				});
+			} catch (e) {
+				res.status(500).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// Structural edits (Phase 1b: nav-only). Each applies the change, persists
+		// hdocbook.json (stamping opaque ids on first save), and returns the fresh
+		// tree so the client can re-render with recomputed 1.2.3 numbering.
+		app.post("/api/toc/move", (req, res) => {
+			const body = req.body || {};
+			if (!body.id) return res.status(400).json({ error: "Missing id" });
+			try {
+				toc.move(body.id, body.parentId ?? null, body.index);
+				res.json(toc.to_dto());
+			} catch (e) {
+				res.status(400).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		app.post("/api/toc/rename", (req, res) => {
+			const body = req.body || {};
+			if (!body.id) return res.status(400).json({ error: "Missing id" });
+			if (typeof body.text !== "string") {
+				return res.status(400).json({ error: "Missing text" });
+			}
+			try {
+				toc.rename(body.id, body.text);
+				res.json(toc.to_dto());
+			} catch (e) {
+				res.status(400).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		app.post("/api/toc/draft", (req, res) => {
+			const body = req.body || {};
+			if (!body.id) return res.status(400).json({ error: "Missing id" });
+			try {
+				toc.set_draft(body.id, !!body.draft);
+				res.json(toc.to_dto());
+			} catch (e) {
+				res.status(400).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// Create a nav leaf linking to an existing page.
+		app.post("/api/toc/create", (req, res) => {
+			const body = req.body || {};
+			if (typeof body.link !== "string" || !body.link) {
+				return res.status(400).json({ error: "Missing link" });
+			}
+			try {
+				toc.create_leaf(body.parentId ?? null, body.index, body.text ?? "", body.link);
+				res.json(toc.to_dto());
+			} catch (e) {
+				res.status(400).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// Create an empty nav section (container branch).
+		app.post("/api/toc/add-section", (req, res) => {
+			const body = req.body || {};
+			try {
+				toc.add_section(body.parentId ?? null, body.index, body.text ?? "");
+				res.json(toc.to_dto());
+			} catch (e) {
+				res.status(400).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// Remove a nav node (unlink). With { deleteFile: true } also delete its
+		// backing page file. Returns { tree, fileDeleted }.
+		app.delete("/api/toc/:id", (req, res) => {
+			const body = req.body || {};
+			try {
+				const node = toc.remove_node(req.params.id);
+				let fileDeleted = false;
+				if (body.deleteFile && typeof node.link === "string" && node.link) {
+					const r = toc._resolve_file(node.link);
+					if (r.file && r.fileExists) {
+						toc.delete_file(r.file);
+						fileDeleted = true;
+					}
+				}
+				res.json({ tree: toc.to_dto(), fileDeleted });
+			} catch (e) {
+				res.status(400).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// --- pages on disk (decoupled from nav; "_" folders excluded) ---
+
+		app.get("/api/files", (req, res) => {
+			try {
+				res.json(toc.list_files());
+			} catch (e) {
+				res.status(500).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// Upload an image/asset (raw bytes) to a path inside the book.
+		app.put(
+			"/api/upload",
+			express.raw({ type: () => true, limit: "25mb" }),
+			(req, res) => {
+				try {
+					const { abs, rel } = toc.resolve_upload(String(req.query.path || ""));
+					if (!Buffer.isBuffer(req.body) || req.body.length === 0) {
+						return res.status(400).json({ error: "Empty upload body" });
+					}
+					fs.mkdirSync(path.dirname(abs), { recursive: true });
+					fs.writeFileSync(abs, req.body);
+					note_write(abs, req.body);
+					res.json({ ok: true, file: rel, bytes: req.body.length });
+				} catch (e) {
+					res.status(400).json({ error: String((e && e.message) || e) });
+				}
+			},
+		);
+
+		// --- spell check (dialect) + shared custom dictionary ---
+		// The custom dictionary lives in hdocbook-project.json under
+		// validation.spellcheckDictionary, so `hdoc validate` honours it too.
+		// (project_path is a workspace `let` set by open_workspace so it follows
+		// workspace switches.)
+
+		const read_dictionary = () => {
+			try {
+				const proj = JSON.parse(fs.readFileSync(project_path, "utf8"));
+				const list = proj.validation && proj.validation.spellcheckDictionary;
+				return Array.isArray(list) ? list : [];
+			} catch {
+				return [];
+			}
+		};
+
+		const add_dictionary_word = (word) => {
+			const raw = fs.readFileSync(project_path, "utf8");
+			const m = raw.match(/\n(\t+| +)\S/);
+			const indent = m ? (m[1].includes("\t") ? "\t" : m[1].length) : 2;
+			const proj = JSON.parse(raw);
+			if (!proj.validation) proj.validation = {};
+			if (!Array.isArray(proj.validation.spellcheckDictionary)) {
+				proj.validation.spellcheckDictionary = [];
+			}
+			const w = String(word).trim();
+			const list = proj.validation.spellcheckDictionary;
+			if (w && !list.some((x) => x.toLowerCase() === w.toLowerCase())) {
+				list.push(w);
+				list.sort((a, b) => a.localeCompare(b));
+			}
+			fs.writeFileSync(
+				project_path,
+				JSON.stringify(proj, null, indent) + (raw.endsWith("\n") ? "\n" : ""),
+				"utf8",
+			);
+			return list;
+		};
+
+		app.post("/api/spellcheck", (req, res) => {
+			const body = req.body || {};
+			if (typeof body.content !== "string") {
+				return res.status(400).json({ error: "Missing content" });
+			}
+			try {
+				const dialect = dialect_findings(body.content, read_dictionary());
+				res.json({ dialect });
+			} catch (e) {
+				res.status(500).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		app.get("/api/dictionary", (req, res) => {
+			res.json({ words: read_dictionary() });
+		});
+
+		app.post("/api/dictionary", (req, res) => {
+			const body = req.body || {};
+			if (typeof body.word !== "string" || !body.word.trim()) {
+				return res.status(400).json({ error: "Missing word" });
+			}
+			try {
+				res.json({ words: add_dictionary_word(body.word) });
+			} catch (e) {
+				res.status(400).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// --- AI writing assistance (Anthropic Messages API via native fetch) ---
+		//
+		// Calls Claude server-side so the API key never reaches the browser, and
+		// streams the edited Markdown straight back to the editor as it is
+		// generated. Deliberately uses global fetch (Node 18+) rather than the
+		// Anthropic SDK, so this adds ZERO npm dependencies and never touches the
+		// fragile root npm-shrinkwrap.json.
+		//
+		// Model + limits are configurable in hdocbook-project.json under "ai":
+		//   { "ai": { "model": "claude-sonnet-4-6", "maxTokens": 4096 } }
+		// Sonnet 4.6 is the default — strong on prose at a good price; set it to
+		// claude-haiku-4-5 for faster/cheaper edits or claude-opus-4-8 for the
+		// highest quality. The API key is read from the ANTHROPIC_API_KEY env var.
+		const ai_cfg =
+			hdocbook_project && hdocbook_project.ai && typeof hdocbook_project.ai === "object"
+				? hdocbook_project.ai
+				: {};
+		const AI_MODEL =
+			typeof ai_cfg.model === "string" && ai_cfg.model
+				? ai_cfg.model
+				: "claude-sonnet-4-6";
+		const AI_MAX_TOKENS = Number.isFinite(ai_cfg.maxTokens)
+			? ai_cfg.maxTokens
+			: 4096;
+		const AI_ENDPOINT = "https://api.anthropic.com/v1/messages";
+
+		// Stable system prompt — cached server-side (cache_control) so repeated
+		// edits in a session reuse it. House style mirrors the spell-checker's
+		// US/International English convention.
+		const AI_SYSTEM = [
+			"You are a writing assistant embedded in the Hornbill HDocBook editor.",
+			"You help authors edit technical documentation written in Markdown.",
+			"",
+			"House style:",
+			"- Use US / International English spelling and vocabulary.",
+			"- Be clear, concise and direct; prefer active voice and present tense.",
+			"- Preserve the author's meaning and intent. Never invent facts, features or details.",
+			"",
+			"Markdown and HDocBook rules:",
+			"- Preserve all Markdown structure: headings, lists, tables, links, images, code fences and inline `code`.",
+			"- Never change the contents of fenced code blocks or inline code spans.",
+			"- Preserve HDocBook markup verbatim, including [[INCLUDE ...]], [[File:...]] and wiki-style directives.",
+			"- Do not change link or image URLs.",
+			"",
+			"Output rules:",
+			"- Return only the edited Markdown for the supplied text — no preamble, explanation, commentary or surrounding code fence.",
+		].join("\n");
+
+		const AI_ACTIONS = {
+			rewrite:
+				"Rewrite the supplied text to improve clarity, flow and readability while preserving its meaning and all Markdown structure.",
+			grammar:
+				"Correct only grammar, spelling and punctuation in the supplied text. Make the minimum changes necessary; do not otherwise rephrase or restructure it.",
+			tighten:
+				"Make the supplied text more concise and direct without losing information. Remove redundancy and wordiness.",
+		};
+
+		app.post("/api/assist", async (req, res) => {
+			const apiKey = process.env.ANTHROPIC_API_KEY;
+			if (!apiKey) {
+				return res.status(503).json({
+					error:
+						"ANTHROPIC_API_KEY is not set. Set it in the environment running `hdoc edit` to enable AI writing assistance.",
+				});
+			}
+			if (typeof fetch !== "function") {
+				return res.status(500).json({
+					error: "Global fetch is unavailable — Node 18+ is required for AI assistance.",
+				});
+			}
+
+			const body = req.body || {};
+			const text = typeof body.text === "string" ? body.text : "";
+			const action = typeof body.action === "string" ? body.action : "rewrite";
+			const instruction =
+				typeof body.instruction === "string" ? body.instruction.trim() : "";
+
+			if (!text.trim()) {
+				return res.status(400).json({ error: "No text to edit" });
+			}
+
+			const task =
+				action === "custom"
+					? instruction || "Improve the supplied text."
+					: AI_ACTIONS[action] || AI_ACTIONS.rewrite;
+
+			let system = AI_SYSTEM;
+			const dict = read_dictionary();
+			if (dict.length) {
+				system +=
+					"\n\nThe following are correctly-spelled domain terms; keep them as-is: " +
+					dict.join(", ") +
+					".";
+			}
+
+			const user_text = `Task: ${task}\n\nHere is the Markdown to edit:\n\n<text>\n${text}\n</text>\n\nReturn only the edited Markdown.`;
+
+			let upstream;
+			try {
+				upstream = await fetch(AI_ENDPOINT, {
+					method: "POST",
+					headers: {
+						"content-type": "application/json",
+						"x-api-key": apiKey,
+						"anthropic-version": "2023-06-01",
+					},
+					body: JSON.stringify({
+						model: AI_MODEL,
+						max_tokens: AI_MAX_TOKENS,
+						stream: true,
+						system: [
+							{
+								type: "text",
+								text: system,
+								cache_control: { type: "ephemeral" },
+							},
+						],
+						messages: [{ role: "user", content: user_text }],
+					}),
+				});
+			} catch (e) {
+				return res.status(502).json({
+					error: "Failed to reach the Anthropic API: " + String((e && e.message) || e),
+				});
+			}
+
+			if (!upstream.ok || !upstream.body) {
+				let detail = "Anthropic API error (HTTP " + upstream.status + ")";
+				try {
+					const err = await upstream.json();
+					if (err && err.error && err.error.message) detail = err.error.message;
+				} catch {
+					/* non-JSON error body */
+				}
+				return res
+					.status(upstream.status === 401 ? 401 : 502)
+					.json({ error: detail });
+			}
+
+			// Stream text deltas straight to the editor as plain text.
+			res.writeHead(200, {
+				"Content-Type": "text/plain; charset=utf-8",
+				"Cache-Control": "no-cache",
+			});
+
+			const reader = upstream.body.getReader();
+			const decoder = new TextDecoder();
+			let buf = "";
+			try {
+				for (;;) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					buf += decoder.decode(value, { stream: true });
+					// Anthropic streams SSE: one JSON object per `data:` line.
+					let nl;
+					while ((nl = buf.indexOf("\n")) >= 0) {
+						const line = buf.slice(0, nl).trim();
+						buf = buf.slice(nl + 1);
+						if (!line.startsWith("data:")) continue;
+						const payload = line.slice(5).trim();
+						if (!payload) continue;
+						try {
+							const evt = JSON.parse(payload);
+							if (
+								evt.type === "content_block_delta" &&
+								evt.delta &&
+								evt.delta.type === "text_delta"
+							) {
+								res.write(evt.delta.text);
+							}
+						} catch {
+							/* partial frame split across chunks — ignore */
+						}
+					}
+				}
+			} catch (e) {
+				console.error("AI assist stream error:", (e && e.message) || e);
+			}
+			res.end();
+		});
+
+		// --- Git connectivity playground (POC) ---
+		//
+		// Proves out the "GitHub as a live backing store" architecture: read repo
+		// metadata, browse/read files, and write a commit — all via the GitHub
+		// REST API over native fetch (no git binary, no local clone, zero new npm
+		// deps). Token comes from the request body (loopback only) or the
+		// GITHUB_TOKEN env var. This is a sandbox to experiment with connectivity
+		// before committing to an architecture; it is NOT wired into the editor's
+		// save path.
+		const GITHUB_API = "https://api.github.com";
+
+		async function github(token, method, url_path, body) {
+			const headers = {
+				accept: "application/vnd.github+json",
+				"x-github-api-version": "2022-11-28",
+				"user-agent": "hdoc-edit-git-playground",
+			};
+			if (token) headers.authorization = "Bearer " + token;
+			if (body) headers["content-type"] = "application/json";
+			const r = await fetch(GITHUB_API + url_path, {
+				method,
+				headers,
+				body: body ? JSON.stringify(body) : undefined,
+			});
+			const text = await r.text();
+			let json = null;
+			try {
+				json = text ? JSON.parse(text) : null;
+			} catch {
+				json = { raw: text };
+			}
+			return {
+				ok: r.ok,
+				status: r.status,
+				json,
+				rate: {
+					remaining: r.headers.get("x-ratelimit-remaining"),
+					limit: r.headers.get("x-ratelimit-limit"),
+				},
+			};
+		}
+
+		const split_repo = (full) => {
+			const parts = String(full || "").trim().split("/");
+			return { owner: parts[0] || "", repo: parts.slice(1).join("/") || "" };
+		};
+		const git_token = (body) =>
+			(body.token && String(body.token).trim()) ||
+			process.env.GITHUB_TOKEN ||
+			"";
+		const git_guard = (req, res) => {
+			if (typeof fetch !== "function") {
+				res.status(500).json({ error: "Global fetch unavailable — Node 18+ required." });
+				return null;
+			}
+			const token = git_token(req.body || {});
+			if (!token) {
+				res.status(400).json({
+					error: "No GitHub token. Paste a personal access token, or set GITHUB_TOKEN in the server environment.",
+				});
+				return null;
+			}
+			return token;
+		};
+
+		// Auth check + optional repo metadata + rate-limit headroom.
+		app.post("/api/git/info", async (req, res) => {
+			const token = git_guard(req, res);
+			if (!token) return;
+			const b = req.body || {};
+			try {
+				const user = await github(token, "GET", "/user");
+				if (!user.ok) {
+					return res.status(user.status).json({
+						error: (user.json && user.json.message) || "GitHub auth failed",
+					});
+				}
+				const out = {
+					user: { login: user.json.login, name: user.json.name },
+					rate: user.rate,
+				};
+				const { owner, repo } = split_repo(b.repo);
+				if (owner && repo) {
+					const r = await github(
+						token,
+						"GET",
+						`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`,
+					);
+					if (r.ok) {
+						out.repo = {
+							full_name: r.json.full_name,
+							private: r.json.private,
+							default_branch: r.json.default_branch,
+							permissions: r.json.permissions,
+						};
+					} else {
+						out.repoError =
+							(r.json && r.json.message) || "HTTP " + r.status;
+					}
+				}
+				res.json(out);
+			} catch (e) {
+				res.status(502).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// Browse a directory or read a file (the "live backing store" read path).
+		app.post("/api/git/contents", async (req, res) => {
+			const token = git_guard(req, res);
+			if (!token) return;
+			const b = req.body || {};
+			const { owner, repo } = split_repo(b.repo);
+			if (!owner || !repo) {
+				return res.status(400).json({ error: "Repository must be in owner/name form" });
+			}
+			const p = String(b.path || "").replace(/^\/+/, "");
+			const ref = b.branch ? `?ref=${encodeURIComponent(b.branch)}` : "";
+			try {
+				const r = await github(
+					token,
+					"GET",
+					`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/contents/${p}${ref}`,
+				);
+				if (!r.ok) {
+					return res
+						.status(r.status)
+						.json({ error: (r.json && r.json.message) || "HTTP " + r.status });
+				}
+				if (Array.isArray(r.json)) {
+					res.json({
+						type: "dir",
+						path: p,
+						entries: r.json
+							.map((e) => ({ name: e.name, path: e.path, kind: e.type, size: e.size }))
+							.sort((a, c) =>
+								a.kind === c.kind
+									? a.name.localeCompare(c.name)
+									: a.kind === "dir"
+										? -1
+										: 1,
+							),
+						rate: r.rate,
+					});
+				} else {
+					const f = r.json;
+					const content =
+						f.encoding === "base64" && f.content
+							? Buffer.from(f.content, "base64").toString("utf8")
+							: null;
+					res.json({
+						type: "file",
+						path: f.path,
+						sha: f.sha,
+						size: f.size,
+						content,
+						rate: r.rate,
+					});
+				}
+			} catch (e) {
+				res.status(502).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// Create/update a file = one commit (the "live backing store" write path).
+		app.post("/api/git/commit", async (req, res) => {
+			const token = git_guard(req, res);
+			if (!token) return;
+			const b = req.body || {};
+			const { owner, repo } = split_repo(b.repo);
+			if (!owner || !repo) {
+				return res.status(400).json({ error: "Repository must be in owner/name form" });
+			}
+			const p = String(b.path || "").replace(/^\/+/, "");
+			if (!p) return res.status(400).json({ error: "Missing file path" });
+			const branch = b.branch ? String(b.branch) : undefined;
+			const message = b.message || "hdoc playground commit";
+			const content_b64 = Buffer.from(String(b.content || ""), "utf8").toString("base64");
+			try {
+				// Optimistic concurrency: include the current blob sha if the file
+				// exists (this is the GitHub equivalent of the editor's etag check).
+				let sha;
+				const existing = await github(
+					token,
+					"GET",
+					`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/contents/${p}${branch ? `?ref=${encodeURIComponent(branch)}` : ""}`,
+				);
+				if (existing.ok && !Array.isArray(existing.json)) sha = existing.json.sha;
+
+				const put_body = { message, content: content_b64 };
+				if (sha) put_body.sha = sha;
+				if (branch) put_body.branch = branch;
+				const r = await github(
+					token,
+					"PUT",
+					`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/contents/${p}`,
+					put_body,
+				);
+				if (!r.ok) {
+					return res
+						.status(r.status)
+						.json({ error: (r.json && r.json.message) || "HTTP " + r.status });
+				}
+				res.json({
+					updated: !!sha,
+					commit: {
+						sha: r.json.commit && r.json.commit.sha,
+						html_url: r.json.commit && r.json.commit.html_url,
+					},
+					path: r.json.content && r.json.content.path,
+					rate: r.rate,
+				});
+			} catch (e) {
+				res.status(502).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// --- GitHub login (Device Flow) + repo browsing (POC) ---
+		//
+		// Device Flow is the right sign-in for a desktop app: no client secret,
+		// no redirect server — the user authorizes a short code on github.com and
+		// we poll for the token. github.com/login/* has no CORS, so it's proxied
+		// here. Needs a GitHub OAuth App (Device Flow enabled) whose client_id is
+		// set via GITHUB_CLIENT_ID (or passed in the request). PAT login still
+		// works without any of this.
+		const GITHUB_OAUTH = "https://github.com";
+
+		// The OAuth App client_id is NOT a secret (Device Flow uses no client
+		// secret), so it's safe to ship in source — exactly how GitHub Desktop
+		// embeds its own. This is the "Hornbill HDocBook Editor" OAuth App under
+		// the Hornbill-Docs org. Override with the GITHUB_CLIENT_ID env var when
+		// testing against a different app.
+		const DEFAULT_GITHUB_CLIENT_ID = "Ov23liYILIXBsc9HoiNm";
+
+		const device_client_id = (b) =>
+			(b.client_id && String(b.client_id).trim()) ||
+			process.env.GITHUB_CLIENT_ID ||
+			DEFAULT_GITHUB_CLIENT_ID;
+
+		const map_repo = (r) => ({
+			full_name: r.full_name,
+			private: r.private,
+			description: r.description,
+			default_branch: r.default_branch,
+			updated_at: r.updated_at,
+			pushed_at: r.pushed_at,
+			html_url: r.html_url,
+			permissions: r.permissions,
+		});
+
+		// Step 1: request a device + user code.
+		app.post("/api/git/device/start", async (req, res) => {
+			if (typeof fetch !== "function") {
+				return res.status(500).json({ error: "Node 18+ required." });
+			}
+			const b = req.body || {};
+			const client_id = device_client_id(b);
+			if (!client_id) {
+				return res.status(400).json({
+					error: "No GITHUB_CLIENT_ID set. Create a GitHub OAuth App with Device Flow enabled, then set GITHUB_CLIENT_ID (or pass client_id).",
+				});
+			}
+			const scope = (b.scope && String(b.scope)) || "repo";
+			try {
+				const r = await fetch(`${GITHUB_OAUTH}/login/device/code`, {
+					method: "POST",
+					headers: { accept: "application/json", "content-type": "application/json" },
+					body: JSON.stringify({ client_id, scope }),
+				});
+				const j = await r.json();
+				if (!r.ok || j.error) {
+					return res
+						.status(400)
+						.json({ error: j.error_description || j.error || "device code request failed" });
+				}
+				res.json({
+					user_code: j.user_code,
+					verification_uri: j.verification_uri,
+					device_code: j.device_code,
+					interval: j.interval,
+					expires_in: j.expires_in,
+				});
+			} catch (e) {
+				res.status(502).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// Step 2: poll for the access token (frontend polls on the given interval).
+		app.post("/api/git/device/poll", async (req, res) => {
+			if (typeof fetch !== "function") {
+				return res.status(500).json({ error: "Node 18+ required." });
+			}
+			const b = req.body || {};
+			const client_id = device_client_id(b);
+			if (!client_id || !b.device_code) {
+				return res.status(400).json({ error: "Missing client_id or device_code" });
+			}
+			try {
+				const r = await fetch(`${GITHUB_OAUTH}/login/oauth/access_token`, {
+					method: "POST",
+					headers: { accept: "application/json", "content-type": "application/json" },
+					body: JSON.stringify({
+						client_id,
+						device_code: b.device_code,
+						grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+					}),
+				});
+				const j = await r.json();
+				if (j.access_token) {
+					return res.json({ access_token: j.access_token, scope: j.scope });
+				}
+				if (j.error === "authorization_pending") return res.json({ pending: true });
+				if (j.error === "slow_down") {
+					return res.json({ pending: true, slow_down: true, interval: j.interval });
+				}
+				res.status(400).json({ error: j.error_description || j.error || "authorization failed" });
+			} catch (e) {
+				res.status(502).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// List the repos the authenticated user can access (paginated, newest first).
+		app.post("/api/git/repos", async (req, res) => {
+			const token = git_guard(req, res);
+			if (!token) return;
+			const b = req.body || {};
+			const page = Math.max(1, parseInt(b.page, 10) || 1);
+			const org = b.org && String(b.org).trim();
+			try {
+				const r = await github(
+					token,
+					"GET",
+					org
+						? `/orgs/${encodeURIComponent(org)}/repos?per_page=30&page=${page}&sort=updated`
+						: `/user/repos?per_page=30&page=${page}&sort=updated&affiliation=owner,collaborator,organization_member`,
+				);
+				if (!r.ok) {
+					return res
+						.status(r.status)
+						.json({ error: (r.json && r.json.message) || "HTTP " + r.status });
+				}
+				res.json({
+					repos: (Array.isArray(r.json) ? r.json : []).map(map_repo),
+					page,
+					hasMore: Array.isArray(r.json) && r.json.length === 30,
+					rate: r.rate,
+				});
+			} catch (e) {
+				res.status(502).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// --- Local clones (GitHub-Desktop-style) ---
+		//
+		// Shells out to the system `git` (no npm dep — we move to bundled dugite
+		// when the app is packaged as Electron). Anchored on GitHub Desktop's
+		// default clone dir (~/Documents/GitHub) so we reuse repos it already
+		// cloned. GIT_TERMINAL_PROMPT=0 makes auth failures fail fast instead of
+		// hanging on a credential prompt.
+		const git_base_dir = () => path.join(os.homedir(), "Documents", "GitHub");
+
+		const git_exec = (args, cwd, timeout = 120000) =>
+			new Promise((resolve) => {
+				execFile(
+					"git",
+					args,
+					{
+						cwd,
+						windowsHide: true,
+						maxBuffer: 16 * 1024 * 1024,
+						timeout,
+						killSignal: "SIGKILL",
+						// Never block on an interactive credential prompt — fail fast
+						// instead. GIT_TERMINAL_PROMPT kills terminal prompts;
+						// GCM_INTERACTIVE=never stops the Windows credential-manager
+						// GUI; GIT_ASKPASS=echo defeats askpass helpers.
+						env: {
+							...process.env,
+							GIT_TERMINAL_PROMPT: "0",
+							GCM_INTERACTIVE: "never",
+							GIT_ASKPASS: "echo",
+						},
+					},
+					(err, stdout, stderr) => {
+						resolve({
+							ok: !err,
+							timedOut: !!(err && err.killed),
+							stdout: String(stdout || ""),
+							stderr: String(stderr || ""),
+						});
+					},
+				);
+			});
+
+		// Read the origin's owner/repo straight from .git/config (a file read — no
+		// `git` subprocess), used to match local clones against GitHub repos.
+		const repo_full_name = (dir) => {
+			try {
+				const cfg = fs.readFileSync(path.join(dir, ".git", "config"), "utf8");
+				const m = cfg.match(/\[remote "origin"\][^[]*?url\s*=\s*(.+)/);
+				if (m) {
+					const mm = m[1].trim().replace(/\.git$/, "").match(/github\.com[/:]([^/]+\/[^/\s]+)$/);
+					if (mm) return mm[1];
+				}
+			} catch {
+				/* no config / unreadable */
+			}
+			return null;
+		};
+
+		// List local clones under the base dir, flagging hdocbooks and reporting
+		// branch + ahead/behind + dirty (GitHub-Desktop's repo list). Process
+		// spawns are the bottleneck on Windows, so origin is read from .git/config
+		// (no spawn) and the one remaining `git status` per repo runs in PARALLEL.
+		app.post("/api/git/local/list", async (req, res) => {
+			const base = git_base_dir();
+			let names = [];
+			try {
+				names = fs
+					.readdirSync(base, { withFileTypes: true })
+					.filter((d) => d.isDirectory())
+					.map((d) => d.name);
+			} catch {
+				return res.json({ base, repos: [], note: "clone directory not found yet" });
+			}
+
+			const candidates = names
+				.map((name) => ({ name, dir: path.join(base, name) }))
+				.filter((c) => fs.existsSync(path.join(c.dir, ".git")));
+
+			const repos = await Promise.all(
+				candidates.map(async (c) => {
+					const status = await git_exec(["status", "--porcelain", "-b"], c.dir, 15000);
+					let branch = "";
+					let ahead = 0;
+					let behind = 0;
+					let dirty = 0;
+					if (status.ok) {
+						for (const line of status.stdout.split("\n")) {
+							if (line.startsWith("## ")) {
+								branch = line.slice(3).split("...")[0].trim();
+								const a = line.match(/ahead (\d+)/);
+								const b = line.match(/behind (\d+)/);
+								if (a) ahead = parseInt(a[1], 10) || 0;
+								if (b) behind = parseInt(b[1], 10) || 0;
+							} else if (line.trim()) {
+								dirty++;
+							}
+						}
+					}
+					return {
+						name: c.name,
+						path: c.dir,
+						isHdoc: fs.existsSync(path.join(c.dir, "hdocbook-project.json")),
+						full_name: repo_full_name(c.dir),
+						branch,
+						ahead,
+						behind,
+						dirty,
+					};
+				}),
+			);
+
+			repos.sort((a, b) => a.name.localeCompare(b.name));
+			res.json({ base, repos });
+		});
+
+		// Sync a local clone: fast-forward pull, authenticated with the token so
+		// it never blocks on the OS credential manager, with a hard timeout.
+		app.post("/api/git/local/sync", async (req, res) => {
+			const b = req.body || {};
+			const dir = String(b.path || "");
+			if (!dir || !fs.existsSync(path.join(dir, ".git"))) {
+				return res.status(400).json({ error: "Not a local git repository" });
+			}
+			const token = (b.token && String(b.token).trim()) || process.env.GITHUB_TOKEN || "";
+
+			// Current branch + origin (local, fast).
+			const head = await git_exec(["rev-parse", "--abbrev-ref", "HEAD"], dir, 15000);
+			const branch = head.ok ? head.stdout.trim() : "";
+			const origin = await git_exec(["remote", "get-url", "origin"], dir, 15000);
+			const m = origin.ok
+				? origin.stdout.trim().replace(/\.git$/, "").match(/github\.com[/:]([^/]+)\/([^/]+)$/)
+				: null;
+
+			// Prefer a token-authenticated pull (no credential-manager dependency).
+			let pull;
+			if (token && m && branch) {
+				const authed = `https://x-access-token:${token}@github.com/${m[1]}/${m[2]}.git`;
+				pull = await git_exec(["pull", "--ff-only", authed, branch], dir, 60000);
+			} else {
+				pull = await git_exec(["pull", "--ff-only"], dir, 60000);
+			}
+
+			const status = await git_exec(["status", "--porcelain", "-b"], dir, 15000);
+			let ahead = 0;
+			let behind = 0;
+			let dirty = 0;
+			if (status.ok) {
+				for (const line of status.stdout.split("\n")) {
+					if (line.startsWith("## ")) {
+						const a = line.match(/ahead (\d+)/);
+						const bh = line.match(/behind (\d+)/);
+						if (a) ahead = parseInt(a[1], 10) || 0;
+						if (bh) behind = parseInt(bh[1], 10) || 0;
+					} else if (line.trim()) dirty++;
+				}
+			}
+
+			const strip = (s) => (token ? String(s).split(token).join("***") : String(s));
+			const out = pull.stdout + pull.stderr;
+			let message;
+			if (pull.timedOut) {
+				message = "Timed out — check your network or sign in again.";
+			} else if (!pull.ok) {
+				message = strip((pull.stderr || pull.stdout || "Sync failed").trim().split("\n")[0]);
+			} else if (/already up to date/i.test(out)) {
+				message = "Already up to date";
+			} else {
+				const stat = (out.match(/\d+ files? changed[^\n]*/) || [])[0];
+				message = "Updated" + (stat ? ` — ${stat}` : "");
+			}
+			res.json({ ok: pull.ok && !pull.timedOut, message, ahead, behind, dirty });
+		});
+
+		// Clone a repo into the base dir (reuses the device-flow/PAT token for the
+		// transfer, then strips it from the stored remote so it isn't persisted).
+		app.post("/api/git/local/clone", async (req, res) => {
+			const token = git_guard(req, res);
+			if (!token) return;
+			const b = req.body || {};
+			const { owner, repo } = split_repo(b.repo);
+			if (!owner || !repo) {
+				return res.status(400).json({ error: "Repository must be in owner/name form" });
+			}
+			const base = git_base_dir();
+			try {
+				fs.mkdirSync(base, { recursive: true });
+			} catch {
+				/* ignore */
+			}
+			const dest = path.join(base, repo);
+			if (fs.existsSync(dest)) {
+				return res.status(409).json({ error: "Already cloned locally", path: dest });
+			}
+			const auth_url = `https://x-access-token:${token}@github.com/${owner}/${repo}.git`;
+			const clean_url = `https://github.com/${owner}/${repo}.git`;
+			const r = await git_exec(["clone", auth_url, dest], base);
+			if (!r.ok) {
+				return res.status(502).json({
+					error: (r.stderr || r.stdout || "clone failed").split(token).join("***"),
+				});
+			}
+			// Don't leave the token in .git/config — reset to the clean URL.
+			await git_exec(["remote", "set-url", "origin", clean_url], dest);
+			res.json({ ok: true, path: dest, name: repo });
+		});
+
+		app.post("/api/pages", (req, res) => {
+			const body = req.body || {};
+			try {
+				const content = typeof body.content === "string" ? body.content : "";
+				const created = toc.create_file(body.path, content);
+				note_write(path.join(source_path, created), content);
+				res.json({ created, ...toc.list_files() });
+			} catch (e) {
+				res.status(400).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		app.post("/api/pages/folder", (req, res) => {
+			const body = req.body || {};
+			try {
+				const created = toc.create_folder(body.path);
+				res.json({ created, ...toc.list_files() });
+			} catch (e) {
+				res.status(400).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		app.delete("/api/pages", (req, res) => {
+			const body = req.body || {};
+			try {
+				const deleted = toc.delete_file(body.path);
+				res.json({ deleted, ...toc.list_files() });
+			} catch (e) {
+				res.status(400).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// Page content addressed by file path (works for orphan pages too).
+		app.get("/api/pagefile", (req, res) => {
+			try {
+				const { abs, rel } = toc._safe_rel(String(req.query.path || ""), {
+					dir: false,
+				});
+				if (!fs.existsSync(abs)) {
+					return res.status(404).json({ error: "File not found", file: rel });
+				}
+				const content_txt = fs.readFileSync(abs, "utf8");
+				res.json({ file: rel, content: content_txt, etag: sha1(content_txt) });
+			} catch (e) {
+				res.status(400).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		app.put("/api/pagefile", (req, res) => {
+			const body = req.body || {};
+			if (typeof body.content !== "string") {
+				return res.status(400).json({ error: "Missing content" });
+			}
+			try {
+				const { abs, rel } = toc._safe_rel(String(req.query.path || ""), {
+					dir: false,
+				});
+				// Optimistic concurrency: refuse to overwrite an external change.
+				if (body.baseEtag && fs.existsSync(abs)) {
+					const current = fs.readFileSync(abs, "utf8");
+					if (sha1(current) !== body.baseEtag) {
+						return res
+							.status(409)
+							.json({ error: "conflict", current, etag: sha1(current) });
+					}
+				}
+				fs.mkdirSync(path.dirname(abs), { recursive: true });
+				fs.writeFileSync(abs, body.content, "utf8");
+				note_write(abs, body.content);
+				res.json({
+					ok: true,
+					file: rel,
+					bytes: Buffer.byteLength(body.content, "utf8"),
+					etag: sha1(body.content),
+				});
+			} catch (e) {
+				res.status(400).json({ error: String((e && e.message) || e) });
+			}
+		});
+
+		// (3) Editor SPA. Serve static assets verbatim (no variable expansion —
+		// these are app assets, not book content), then fall back to index.html
+		// so client-side routing works.
+		app.use(express.static(editor_path, { index: false }));
+
+		app.get("/{*splat}", (req, res) => {
+			const index_file = path.join(editor_path, "index.html");
+			if (fs.existsSync(index_file)) {
+				res.setHeader("Content-Type", "text/html");
+				res.sendFile(index_file);
+				return;
+			}
+			// The editor UI hasn't been built yet (no editor/dist). Guide the user
+			// rather than returning a bare 404.
+			res.status(503);
+			res.setHeader("Content-Type", "text/html");
+			res.send(
+				"<h1>Editor UI not built</h1>" +
+					"<p>Run the Vite build to generate <code>editor/dist</code>:</p>" +
+					"<pre>cd editor &amp;&amp; npm run build</pre>" +
+					"<p>For UI development with hot reload, run <code>npm run dev</code> in <code>editor/</code> instead (it proxies to this server).</p>",
+			);
+		});
+
+		// Bind to loopback only: this server can write to the book source.
+		const server = app.listen(port, "127.0.0.1", () => {
+			const port = server.address().port;
+			console.log("Editor listening at http://127.0.0.1:%s", port);
+			console.log(`Document source path is: ${source_path}`);
+		});
+	};
+})();