hdoc-tools 0.63.0 → 0.65.0

package/ui/js/hdoc-edit-inline.js

@@ -0,0 +1,1649 @@
+//-- LOCAL PREVIEW PATCH — hdoc-tools only, NOT part of the live-site viewer.
+//-- Do not copy this file to esp-docs-service htdocs, and keep it (plus its
+//-- loader entry in js/bootstrap.js) when re-syncing ui/ from the live site.
+//--
+//-- Inline edit mode for `hdoc serve`. Probes /_edit/mode; when the server
+//-- confirms edit mode (loopback callers only — LAN viewers stay read-only),
+//-- right-clicking page content offers "Edit this
+//-- in the page editor" (Shift+right-click keeps the browser's own menu).
+//-- The action opens a slide-over panel hosting a CodeMirror 6 editor (the
+//-- same stack `hdoc edit` uses: line numbers, fold gutter, markdown
+//-- highlighting — bundled as js/hdoc-edit-cm.js, lazy-loaded only in edit
+//-- mode) with the page's raw markdown:
+//--   - edits live-preview into the page through the server's shared render
+//--     pipeline (POST /_edit/preview), so preview == published output
+//--   - Save writes the file back (PUT /_edit/source) with an etag conflict
+//--     check, then re-renders the page from disk
+//--   - the editor follows the page viewport (heading-anchored scroll sync),
+//--     and right-clicking content jumps the editor to that block
+//-- Relies on viewer globals loaded before this file: contentContainer(),
+//-- postProcessBookContentRender(), loadContentUrl(), view.docApp.
+
+(() => {
+	"use strict";
+
+	let panel = null;
+	let cm = null; //-- CodeMirror EditorView
+	let cm_ready = null; //-- promise: bundle loaded
+	let ed_disabled = true;
+	let status_el = null;
+	let save_btn = null;
+	let open_path = "";
+	let open_file_rel = ""; //-- source-relative path of the open md file
+	let etag = "";
+	let saved_content = "";
+	let preview_timer = null;
+	let previewed = false;
+	//-- the file's line-ending style: the editor buffer is LF-normalized, so
+	//-- Save re-applies the original EOLs or a CRLF file would come back as a
+	//-- whole-file line-ending diff.
+	let eol = "\n";
+	//-- CM compartments so wrap / read-only can be reconfigured live
+	let wrap_comp = null;
+	let ro_comp = null;
+
+	const logical_path = () =>
+		decodeURIComponent(window.location.pathname)
+			.replace(/^\/+/, "")
+			.replace(/\/+$/, "");
+
+	const api = async (method, url, body) => {
+		const r = await fetch(url, {
+			method,
+			headers: body ? { "content-type": "application/json" } : undefined,
+			body: body ? JSON.stringify(body) : undefined,
+		});
+		let json = null;
+		try {
+			json = await r.json();
+		} catch {
+			/* non-JSON response */
+		}
+		return { ok: r.ok, status: r.status, json };
+	};
+
+	//-- persisted prefs (word wrap, panel width). Storage can throw (blocked
+	//-- site data) — fall back to defaults.
+	const pref = (k) => {
+		try {
+			return localStorage.getItem(k);
+		} catch {
+			return null;
+		}
+	};
+	const set_pref = (k, v) => {
+		try {
+			localStorage.setItem(k, v);
+		} catch {
+			/* ignore */
+		}
+	};
+
+	//-- --- editor adapter ---------------------------------------------------
+
+	const ed_value = () => (cm ? cm.state.doc.toString() : "");
+
+	//-- suppress the change listener during programmatic loads, or setting the
+	//-- buffer would flag "Unsaved changes" and fire a pointless preview
+	let ed_loading = false;
+	const ed_set_value = (text) => {
+		ed_loading = true;
+		try {
+			cm.dispatch({
+				changes: { from: 0, to: cm.state.doc.length, insert: text },
+				//-- keep the load OUT of the undo history — otherwise an undo
+				//-- with no edits made reverts to the empty initial doc
+				annotations: window.HdocCM.Transaction.addToHistory.of(false),
+			});
+		} finally {
+			ed_loading = false;
+		}
+	};
+
+	const ed_set_disabled = (disabled) => {
+		ed_disabled = disabled;
+		if (!cm) return;
+		cm.dispatch({
+			effects: ro_comp.reconfigure([
+				window.HdocCM.EditorState.readOnly.of(disabled),
+				window.HdocCM.EditorView.editable.of(!disabled),
+			]),
+		});
+	};
+
+	const ed_pos_at_line = (line) => {
+		const doc = cm.state.doc;
+		return doc.line(Math.max(1, Math.min(line + 1, doc.lines))).from;
+	};
+
+	const set_caret_at_line = (line, col) => {
+		const doc = cm.state.doc;
+		const l = doc.line(Math.max(1, Math.min(line + 1, doc.lines)));
+		cm.dispatch({
+			selection: { anchor: l.from + Math.min(col || 0, l.length) },
+		});
+	};
+
+	//-- --- images: insert / upload -----------------------------------------
+	//-- Image references use the same form `hdoc edit` inserts (and books
+	//-- already use): ![alt](/_books/<source-relative-path>).
+
+	const IMG_RE = /\.(png|jpe?g|gif|svg|webp|bmp|ico|avif)$/i;
+
+	const image_md = (rel) => {
+		const alt = (rel.split("/").pop() || "").replace(/\.[^.]+$/, "");
+		return `![${alt}](/_books/${rel})`;
+	};
+
+	//-- insert text at a position (default: the caret), placing the caret
+	//-- after it. Runs the normal change listener, so live preview follows.
+	const ed_insert_at = (text, pos) => {
+		if (!cm || ed_disabled) return false;
+		const at = typeof pos === "number" ? pos : cm.state.selection.main.head;
+		cm.dispatch({
+			changes: { from: at, insert: text },
+			selection: { anchor: at + text.length },
+		});
+		cm.focus();
+		return true;
+	};
+
+	//-- Book conventions want kebab-ish lowercase image names
+	//-- (^[a-z]+[_\-a-z0-9]+[a-z0-9]$ plus extension) — normalize what we can.
+	const sanitize_img_name = (name) => {
+		const dot = name.lastIndexOf(".");
+		const ext = dot >= 0 ? name.slice(dot).toLowerCase() : "";
+		const stem = (dot >= 0 ? name.slice(0, dot) : name)
+			.toLowerCase()
+			.replace(/\s+/g, "-")
+			.replace(/[^a-z0-9._-]/g, "");
+		return stem ? stem + ext : "";
+	};
+
+	//-- images uploaded via the editor land in the page's sibling images/
+	//-- folder (the convention real books follow: <section>/images/<name>)
+	const page_images_dir = () => {
+		const segs = open_path.split("/");
+		const dir = segs.length > 1 ? segs.slice(0, -1).join("/") : segs[0];
+		return `${dir}/images`;
+	};
+
+	const upload_image = async (file, name) => {
+		const rel = `${page_images_dir()}/${name}`;
+		const r = await fetch(`/_edit/upload?path=${encodeURIComponent(rel)}`, {
+			method: "PUT",
+			headers: { "content-type": file.type || "application/octet-stream" },
+			body: file,
+		});
+		let json = null;
+		try {
+			json = await r.json();
+		} catch {
+			/* non-JSON response */
+		}
+		if (!r.ok || !json || !json.ok) {
+			throw new Error((json && json.error) || "Upload failed");
+		}
+		return json.file;
+	};
+
+	//-- Upload OS-dropped/pasted image files and insert their references at
+	//-- pos. Returns false when nothing in the list is an image.
+	const handle_image_files = async (files, pos) => {
+		const imgs = Array.from(files).filter(
+			(f) => (f.type || "").startsWith("image/") || IMG_RE.test(f.name),
+		);
+		if (!imgs.length) return false;
+		set_status(`Uploading ${imgs.length} image${imgs.length > 1 ? "s" : ""}…`);
+		try {
+			const parts = [];
+			for (const f of imgs) {
+				let name = sanitize_img_name(f.name || "");
+				//-- clipboard pastes arrive as a generic "image.png" — stamp
+				//-- them so repeated pastes never overwrite each other
+				if (!name || /^image\.[a-z0-9]+$/.test(name)) {
+					const ext = (f.type.split("/")[1] || "png").replace(/[^a-z0-9]/g, "");
+					name = `pasted-${new Date()
+						.toISOString()
+						.replace(/[-:T]/g, "")
+						.slice(0, 14)}.${ext || "png"}`;
+				}
+				parts.push(image_md(await upload_image(f, name)));
+			}
+			ed_insert_at(parts.join("\n"), pos);
+			set_status(
+				`Uploaded to ${page_images_dir()}/ — reference${parts.length > 1 ? "s" : ""} inserted`,
+			);
+		} catch (e) {
+			set_status(String((e && e.message) || e), true);
+		}
+		return true;
+	};
+
+	//-- CodeMirror DOM handlers: accept image drags from the Files tab
+	//-- (custom type, same one `hdoc edit` uses) and OS image files
+	//-- (dropped or pasted) — upload the latter, then insert references.
+	const build_image_dnd_ext = () => {
+		const CM = window.HdocCM;
+		return CM.EditorView.domEventHandlers({
+			dragover(event) {
+				const t = event.dataTransfer && event.dataTransfer.types;
+				if (
+					t &&
+					(t.includes("application/x-hdoc-image") || t.includes("Files"))
+				) {
+					event.preventDefault();
+					event.dataTransfer.dropEffect = "copy";
+				}
+			},
+			drop(event, view) {
+				const dt = event.dataTransfer;
+				if (!dt) return false;
+				const pos =
+					view.posAtCoords({ x: event.clientX, y: event.clientY }) ??
+					view.state.selection.main.head;
+				if (dt.types.includes("application/x-hdoc-image")) {
+					event.preventDefault();
+					const rel = dt.getData("application/x-hdoc-image");
+					if (rel) ed_insert_at(image_md(rel), pos);
+					return true;
+				}
+				if (dt.files && dt.files.length) {
+					event.preventDefault();
+					handle_image_files(dt.files, pos);
+					return true;
+				}
+				return false;
+			},
+			paste(event, view) {
+				const files = event.clipboardData && event.clipboardData.files;
+				if (!files || !files.length) return false;
+				const has_img = Array.from(files).some(
+					(f) => (f.type || "").startsWith("image/") || IMG_RE.test(f.name),
+				);
+				if (!has_img) return false;
+				event.preventDefault();
+				handle_image_files(files, view.state.selection.main.head);
+				return true;
+			},
+		});
+	};
+
+	//-- --- editor context menu: insert snippets ----------------------------
+	//-- Right-click inside the CodeMirror panel offers HDocBook building
+	//-- blocks: a starter table, the admonition boxes the build supports
+	//-- (::: note|tip|info|important|caution|warning) and links (to a book
+	//-- page via the Files/Contents picker, or external). Shift+right-click
+	//-- keeps the browser menu, same convention as the page-content menu.
+
+	let ed_ctx = null;
+	const close_ed_ctx = () => {
+		if (ed_ctx) {
+			ed_ctx.remove();
+			ed_ctx = null;
+		}
+	};
+
+	//-- insert a block snippet at the caret, padded onto its own lines, and
+	//-- select [sel_from, sel_to) within the snippet for immediate typing
+	const insert_snippet_block = (text, sel_from, sel_to) => {
+		if (!cm || ed_disabled) return;
+		const r = cm.state.selection.main;
+		const line = cm.state.doc.lineAt(r.from);
+		//-- tables/fences/boxes need a blank line above them to parse: on an
+		//-- empty line ensure the previous line is blank too, anywhere else
+		//-- start a fresh paragraph
+		let prefix = "\n\n";
+		if (r.from === line.from && line.length === 0) {
+			const prev_blank =
+				line.number === 1 ||
+				cm.state.doc.line(line.number - 1).length === 0;
+			prefix = prev_blank ? "" : "\n";
+		}
+		const insert = `${prefix}${text}\n`;
+		const changes = { from: r.from, to: r.to, insert };
+		const base = r.from + prefix.length;
+		cm.dispatch({
+			changes,
+			selection:
+				typeof sel_from === "number"
+					? { anchor: base + sel_from, head: base + (sel_to ?? sel_from) }
+					: { anchor: r.from + insert.length },
+		});
+		cm.focus();
+	};
+
+	const insert_table = () => {
+		const t = [
+			"| Column 1 | Column 2 | Column 3 |",
+			"|----------|----------|----------|",
+			"| Value    | Value    | Value    |",
+			"| Value    | Value    | Value    |",
+		].join("\n");
+		//-- select the first header cell text
+		insert_snippet_block(t, 2, 10);
+	};
+
+	const insert_box = (kind) => {
+		if (!cm || ed_disabled) return;
+		const r = cm.state.selection.main;
+		const body =
+			r.from !== r.to
+				? cm.state.doc.sliceString(r.from, r.to)
+				: "Your text here.";
+		const t = `::: ${kind}\n${body}\n:::`;
+		const body_off = `::: ${kind}\n`.length;
+		insert_snippet_block(t, body_off, body_off + body.length);
+	};
+
+	//-- inline link: wraps the selection as the label, else leaves a
+	//-- placeholder label; the part most likely to need editing is selected
+	const insert_link_md = (url, select_url) => {
+		if (!cm || ed_disabled) return;
+		const r = cm.state.selection.main;
+		const has_sel = r.from !== r.to;
+		const label = has_sel
+			? cm.state.doc.sliceString(r.from, r.to)
+			: "link text";
+		const md = `[${label}](${url})`;
+		let sel;
+		if (select_url || has_sel) {
+			//-- select the url
+			sel = {
+				anchor: r.from + label.length + 3,
+				head: r.from + label.length + 3 + url.length,
+			};
+		} else {
+			//-- select the placeholder label
+			sel = { anchor: r.from + 1, head: r.from + 1 + label.length };
+		}
+		cm.dispatch({ changes: { from: r.from, to: r.to, insert: md }, selection: sel });
+		cm.focus();
+	};
+
+	const insert_link_page = async () => {
+		if (!(window.HdocEditBook && window.HdocEditBook.pickPage)) {
+			insert_link_md("/", true);
+			return;
+		}
+		const link = await window.HdocEditBook.pickPage();
+		if (!link) {
+			if (cm) cm.focus();
+			return;
+		}
+		insert_link_md(`/${String(link).replace(/^\/+/, "")}`, false);
+	};
+
+	//-- fenced code block with a language, body selected for typing over
+	const insert_code = (lang) => {
+		if (!cm || ed_disabled) return;
+		const r = cm.state.selection.main;
+		const body =
+			r.from !== r.to ? cm.state.doc.sliceString(r.from, r.to) : "code";
+		const fence = lang === "plain" ? "```" : `\`\`\`${lang}`;
+		const t = `${fence}\n${body}\n\`\`\``;
+		const body_off = fence.length + 1;
+		insert_snippet_block(t, body_off, body_off + body.length);
+	};
+
+	//-- AI assist over the selection: streams the edited Markdown from the
+	//-- server (/_edit/assist → Anthropic) and replaces the selection when
+	//-- complete. The buffer is locked while the request runs so the anchor
+	//-- offsets stay valid; a single undo restores the original.
+	let ai_busy = false;
+	const ai_assist = async (action, instruction) => {
+		if (!cm || ed_disabled || ai_busy) return;
+		const r = cm.state.selection.main;
+		if (r.from === r.to) return;
+		const original = cm.state.doc.sliceString(r.from, r.to);
+		ai_busy = true;
+		ed_set_disabled(true);
+		set_status("AI: editing selection…");
+		try {
+			const resp = await fetch("/_edit/assist", {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ text: original, action, instruction }),
+			});
+			if (!resp.ok) {
+				let msg = `AI request failed (HTTP ${resp.status})`;
+				try {
+					const j = await resp.json();
+					if (j && j.error) msg = j.error;
+				} catch {
+					/* not JSON */
+				}
+				set_status(msg, true);
+				return;
+			}
+			const reader = resp.body.getReader();
+			const decoder = new TextDecoder();
+			let out = "";
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				out += decoder.decode(value, { stream: true });
+				set_status(`AI: editing selection… ${out.length} chars`);
+			}
+			if (!panel || !cm) return; //-- closed mid-request
+			//-- models tend to add a trailing newline the original didn't have
+			if (!original.endsWith("\n")) out = out.replace(/\n+$/, "");
+			cm.dispatch({
+				changes: { from: r.from, to: r.to, insert: out },
+				selection: { anchor: r.from, head: r.from + out.length },
+			});
+			set_status("AI edit applied — Ctrl+Z reverts it.");
+		} catch (e) {
+			set_status(`AI request failed: ${String((e && e.message) || e)}`, true);
+		} finally {
+			ai_busy = false;
+			if (panel && cm) {
+				ed_set_disabled(false);
+				cm.focus();
+			}
+		}
+	};
+
+	const ai_custom = () => {
+		const instruction = window.prompt(
+			"What should the AI do with the selected text?",
+			"",
+		);
+		if (instruction === null) {
+			if (cm) cm.focus();
+			return;
+		}
+		ai_assist("custom", instruction);
+	};
+
+	const BOX_KINDS = ["note", "tip", "info", "important", "caution", "warning"];
+	//-- highlight.js languages seen in books, plus mermaid (client-rendered)
+	const CODE_LANGS = [
+		"plain",
+		"bash",
+		"powershell",
+		"javascript",
+		"typescript",
+		"json",
+		"xml",
+		"html",
+		"css",
+		"sql",
+		"python",
+		"csharp",
+		"java",
+		"go",
+		"yaml",
+		"mermaid",
+	];
+
+	//-- generic little menu at (x, y); populate(add, sep) fills it
+	const show_ed_menu = (x, y, populate) => {
+		close_ed_ctx();
+		close_ctx_menu();
+		ed_ctx = document.createElement("div");
+		ed_ctx.className = "hb-edit-ctx";
+		const add = (label, icon, fn) => {
+			const b = document.createElement("button");
+			b.type = "button";
+			b.className = "hb-edit-ctx-item";
+			b.innerHTML = `<i class="bi ${icon}" aria-hidden="true"></i> ${label}`;
+			b.addEventListener("click", (e) => {
+				e.stopPropagation();
+				close_ed_ctx();
+				fn(x, y);
+			});
+			ed_ctx.appendChild(b);
+		};
+		const sep = () => {
+			const s = document.createElement("div");
+			s.className = "hb-edit-ctx-sep";
+			ed_ctx.appendChild(s);
+		};
+		populate(add, sep);
+		document.body.appendChild(ed_ctx);
+		ed_ctx.style.left = `${Math.min(x, window.innerWidth - ed_ctx.offsetWidth - 8)}px`;
+		ed_ctx.style.top = `${Math.min(y, window.innerHeight - ed_ctx.offsetHeight - 8)}px`;
+	};
+
+	//-- second stage: language list for the code block
+	const show_lang_menu = (x, y) => {
+		show_ed_menu(x, y, (add) => {
+			for (const lang of CODE_LANGS) {
+				add(lang, "bi-code", () => insert_code(lang));
+			}
+		});
+	};
+
+	const on_editor_ctx = (ev) => {
+		if (ev.shiftKey || !cm || ed_disabled) return;
+		ev.preventDefault();
+		ev.stopPropagation();
+		//-- move the caret to the click point unless it's inside the selection
+		const pos = cm.posAtCoords({ x: ev.clientX, y: ev.clientY });
+		const r = cm.state.selection.main;
+		if (pos !== null && (pos < r.from || pos > r.to)) {
+			cm.dispatch({ selection: { anchor: pos } });
+		}
+
+		show_ed_menu(ev.clientX, ev.clientY, (add, sep) => {
+			add("Insert table", "bi-table", insert_table);
+			add("Insert code block…", "bi-code-square", show_lang_menu);
+			sep();
+			for (const kind of BOX_KINDS) {
+				add(`Insert ${kind} box`, "bi-chat-square-text", () =>
+					insert_box(kind),
+				);
+			}
+			sep();
+			add("Insert link to page…", "bi-file-earmark-text", insert_link_page);
+			add("Insert external link", "bi-link-45deg", () =>
+				insert_link_md("https://example.com", true),
+			);
+			//-- AI actions operate on the selection (re-read: the right-click
+			//-- may have just moved the caret and collapsed it)
+			const sel = cm.state.selection.main;
+			if (sel.from !== sel.to && !ai_busy) {
+				sep();
+				add("AI: Rewrite selection", "bi-stars", () => ai_assist("rewrite"));
+				add("AI: Fix grammar", "bi-stars", () => ai_assist("grammar"));
+				add("AI: Make concise", "bi-stars", () => ai_assist("tighten"));
+				add("AI: Custom…", "bi-stars", ai_custom);
+			}
+		});
+	};
+
+	//-- --- jump flash ------------------------------------------------------
+	//-- Every editor jump (open-sync, right-click) flashes the target line so
+	//-- the eye lands on the right spot: a line decoration with a CSS fade
+	//-- animation, removed once the fade completes.
+	let hl_effect = null;
+	let hl_field = null;
+	let hl_timer = null;
+
+	const build_highlight_ext = () => {
+		const CM = window.HdocCM;
+		hl_effect = CM.StateEffect.define();
+		const hl_deco = CM.Decoration.line({ class: "hb-edit-hl-line" });
+		hl_field = CM.StateField.define({
+			create: () => CM.Decoration.none,
+			update(deco, tr) {
+				deco = deco.map(tr.changes);
+				for (const e of tr.effects) {
+					if (e.is(hl_effect)) {
+						deco =
+							e.value === null
+								? CM.Decoration.none
+								: CM.Decoration.set([hl_deco.range(e.value)]);
+					}
+				}
+				return deco;
+			},
+			provide: (f) => CM.EditorView.decorations.from(f),
+		});
+		return hl_field;
+	};
+
+	const flash_line = (line) => {
+		if (!cm) return;
+		const doc = cm.state.doc;
+		const from = doc.line(Math.max(1, Math.min(line + 1, doc.lines))).from;
+		//-- retrigger cleanly if a flash is already running
+		if (hl_timer) clearTimeout(hl_timer);
+		cm.dispatch({ effects: hl_effect.of(null) });
+		cm.dispatch({ effects: hl_effect.of(from) });
+		hl_timer = setTimeout(() => {
+			hl_timer = null;
+			if (cm) cm.dispatch({ effects: hl_effect.of(null) });
+		}, 2600);
+	};
+
+	const scroll_editor_to_line = (line) => {
+		cm.dispatch({
+			effects: window.HdocCM.EditorView.scrollIntoView(
+				ed_pos_at_line(line),
+				{ y: "start", yMargin: 40 },
+			),
+		});
+	};
+
+	//-- --- viewport → editor scroll sync ---------------------------------
+	//-- The page and the markdown have no shared coordinate system (variables
+	//-- and includes expand, HTML wraps), but headings survive rendering
+	//-- almost verbatim, so they make reliable sync anchors: find the nearest
+	//-- heading above the viewport top, locate the same heading line in the
+	//-- markdown, scroll the editor to it.
+
+	const norm_text = (s) =>
+		String(s || "")
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, " ")
+			.trim();
+
+	//-- ATX heading lines in the buffer (fenced code blocks skipped), as
+	//-- { line, text } with text normalized for comparison.
+	const md_heading_lines = () => {
+		const lines = ed_value().split("\n");
+		const out = [];
+		let in_fence = false;
+		for (let i = 0; i < lines.length; i++) {
+			if (/^\s*(```|~~~)/.test(lines[i])) {
+				in_fence = !in_fence;
+				continue;
+			}
+			if (in_fence) continue;
+			const m = lines[i].match(/^#{1,6}\s+(.*)$/);
+			if (m) {
+				out.push({ line: i, text: norm_text(m[1].replace(/\s*#+\s*$/, "")) });
+			}
+		}
+		return out;
+	};
+
+	let last_typed = 0;
+
+	//-- set_caret: also move the caret to the matched line (used on open, so
+	//-- focus lands on the right line instead of line 0).
+	const sync_editor_scroll = (set_caret) => {
+		if (!panel || !cm || ed_disabled) return;
+		//-- never fight the author: no sync within 2s of them typing
+		if (!set_caret && Date.now() - last_typed < 2000) return;
+		const root = document.querySelector(".injected-document-content");
+		if (!root) return;
+		const headings = Array.from(
+			root.querySelectorAll("h1,h2,h3,h4,h5,h6"),
+		);
+		//-- nearest heading at/above the viewport top, where "top" extends a
+		//-- band into the top third of the viewport: a heading sitting just
+		//-- below the toolbar (anchor scroll-margin parks them ~200px down)
+		//-- reads as the current section, not the previous one
+		const band = Math.max(120, window.innerHeight * 0.33);
+		let current = null;
+		for (const h of headings) {
+			if (h.getBoundingClientRect().top <= band) current = h;
+			else break;
+		}
+		if (!current) {
+			//-- above the first heading (page intro) → top of the source
+			if (set_caret) set_caret_at_line(0);
+			scroll_editor_to_line(0);
+			return;
+		}
+		const line = md_line_for_heading(current, headings);
+		if (line === null) return;
+		if (set_caret) {
+			set_caret_at_line(line);
+		}
+		scroll_editor_to_line(line);
+		if (set_caret) flash_line(line);
+	};
+
+	//-- markdown line index for a rendered heading element, or null when it
+	//-- can't be matched. Same heading text can repeat — match Nth occurrence.
+	const md_line_for_heading = (heading_el, headings) => {
+		const target = norm_text(heading_el.textContent);
+		if (!target) return null;
+		let occurrence = 0;
+		for (const h of headings) {
+			if (h === heading_el) break;
+			if (norm_text(h.textContent) === target) occurrence++;
+		}
+		const candidates = md_heading_lines().filter((h) => h.text === target);
+		if (!candidates.length) return null;
+		return candidates[Math.min(occurrence, candidates.length - 1)].line;
+	};
+
+	let scroll_sync_timer = null;
+	const on_page_scroll = (ev) => {
+		//-- ignore scrolls originating inside the panel (the editor's own
+		//-- scroller included — capture listener sees all)
+		if (
+			panel &&
+			ev.target instanceof Node &&
+			panel.contains(ev.target)
+		) {
+			return;
+		}
+		if (scroll_sync_timer) clearTimeout(scroll_sync_timer);
+		scroll_sync_timer = setTimeout(sync_editor_scroll, 150);
+	};
+
+	//-- --- right-click → edit at this point --------------------------------
+	//-- Right-clicking page content offers "Edit this in the page editor":
+	//-- opens the panel (if closed) and places the caret at the markdown line
+	//-- for the clicked block. The block is located by anchoring on the
+	//-- nearest heading above it, then scoring the section's markdown lines
+	//-- by word overlap with the block's text.
+
+	let ctx_menu = null;
+	const close_ctx_menu = () => {
+		if (ctx_menu) {
+			ctx_menu.remove();
+			ctx_menu = null;
+		}
+	};
+
+	//-- The words immediately BEFORE the caret position under a point in the
+	//-- rendered text (up to 3). Used to place the editor cursor at the same
+	//-- spot within the matched markdown line, not just at its start.
+	const click_words_at_point = (x, y) => {
+		let node = null;
+		let offset = 0;
+		if (document.caretPositionFromPoint) {
+			const p = document.caretPositionFromPoint(x, y);
+			if (p) {
+				node = p.offsetNode;
+				offset = p.offset;
+			}
+		} else if (document.caretRangeFromPoint) {
+			//-- deprecated, but the only option on older WebKit
+			const r = document.caretRangeFromPoint(x, y);
+			if (r) {
+				node = r.startContainer;
+				offset = r.startOffset;
+			}
+		}
+		if (!node || node.nodeType !== Node.TEXT_NODE) return null;
+		const words = node.textContent
+			.slice(0, offset)
+			.toLowerCase()
+			.split(/[^a-z0-9]+/)
+			.filter(Boolean)
+			.slice(-3);
+		return words.length ? words : null;
+	};
+
+	//-- best-matching markdown line for a rendered block within [start, end)
+	const find_block_line = (block_el, start, end, lines) => {
+		const words = norm_text(block_el.textContent)
+			.split(" ")
+			.filter(Boolean)
+			.slice(0, 12);
+		if (!words.length) return start;
+		let best = start;
+		let best_score = 0;
+		for (let i = start; i < end; i++) {
+			const ln = norm_text(lines[i]);
+			if (!ln) continue;
+			let score = 0;
+			for (const w of words) {
+				if (ln.includes(w)) score++;
+			}
+			if (score > best_score) {
+				best_score = score;
+				best = i;
+			}
+		}
+		return best;
+	};
+
+	const edit_at_block = async (block, click_words) => {
+		if (!panel) await open_panel();
+		if (!panel || !cm || ed_disabled) return;
+		const root = document.querySelector(".injected-document-content");
+		if (!root) return;
+		const headings = Array.from(
+			root.querySelectorAll("h1,h2,h3,h4,h5,h6"),
+		);
+		//-- nearest heading at/above the clicked block, in document order
+		let current = null;
+		for (const h of headings) {
+			if (
+				h === block ||
+				h.compareDocumentPosition(block) & Node.DOCUMENT_POSITION_FOLLOWING
+			) {
+				current = h;
+			} else break;
+		}
+		const lines = ed_value().split("\n");
+		let start = 0;
+		let end = lines.length;
+		const md_hs = md_heading_lines();
+		if (current) {
+			const heading_line = md_line_for_heading(current, headings);
+			if (heading_line !== null) {
+				start = heading_line;
+				const next = md_hs.find((h) => h.line > heading_line);
+				if (next) end = next.line;
+			}
+		} else if (md_hs.length) {
+			//-- block sits in the page intro, above the first heading
+			end = md_hs[0].line;
+		}
+		let line =
+			current && block === current
+				? start
+				: find_block_line(block, start, end, lines);
+		//-- refine to the exact spot: find the words that preceded the click
+		//-- inside the matched line (markdown punctuation like ** or ` can sit
+		//-- between them), and put the caret right after them. Longest word
+		//-- suffix wins; the block-matched line is tried first, then the rest
+		//-- of the section (covers multi-line blocks like fenced code).
+		let col = 0;
+		if (click_words && click_words.length) {
+			const esc = (w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+			const order = [line];
+			for (let i = start; i < end; i++) {
+				if (i !== line) order.push(i);
+			}
+			outer: for (let n = click_words.length; n >= 1; n--) {
+				const re = new RegExp(
+					click_words.slice(-n).map(esc).join("[^a-zA-Z0-9]+"),
+					"i",
+				);
+				for (const li of order) {
+					const m = re.exec(lines[li]);
+					if (m) {
+						line = li;
+						col = m.index + m[0].length;
+						break outer;
+					}
+				}
+			}
+		}
+		set_caret_at_line(line, col);
+		cm.focus();
+		scroll_editor_to_line(line);
+		flash_line(line);
+	};
+
+	const on_context_menu = (ev) => {
+		//-- Shift+right-click = the browser's native menu (the same convention
+		//-- Firefox implements natively for pages with contextmenu handlers)
+		if (ev.shiftKey) return;
+		const root = document.querySelector(".injected-document-content");
+		if (!root || !root.contains(ev.target)) return;
+		ev.preventDefault();
+		close_ctx_menu();
+		const block =
+			ev.target.closest(
+				"p,li,td,th,pre,blockquote,h1,h2,h3,h4,h5,h6",
+			) || ev.target;
+		//-- capture NOW, before the menu is in the DOM under the pointer
+		const click_words = click_words_at_point(ev.clientX, ev.clientY);
+		ctx_menu = document.createElement("div");
+		ctx_menu.className = "hb-edit-ctx";
+		const item = document.createElement("button");
+		item.type = "button";
+		item.className = "hb-edit-ctx-item";
+		item.innerHTML =
+			'<i class="bi bi-pencil-fill" aria-hidden="true"></i> Edit this in the page editor';
+		item.addEventListener("click", (e) => {
+			e.stopPropagation();
+			close_ctx_menu();
+			edit_at_block(block, click_words);
+		});
+		ctx_menu.appendChild(item);
+		document.body.appendChild(ctx_menu);
+		ctx_menu.style.left = `${Math.min(ev.clientX, window.innerWidth - ctx_menu.offsetWidth - 8)}px`;
+		ctx_menu.style.top = `${Math.min(ev.clientY, window.innerHeight - ctx_menu.offsetHeight - 8)}px`;
+	};
+
+	//-- --- close on SPA navigation ----------------------------------------
+	//-- Left-nav clicks swap the page under the panel (pushState) — without
+	//-- this the editor stays open holding the PREVIOUS page's source. Clean
+	//-- buffer closes silently; a dirty buffer prompts, and if the author
+	//-- keeps it open the status bar flags what it still holds.
+	const on_nav_change = () => {
+		if (!panel || !cm) return;
+		const now = logical_path();
+		if (now === open_path) return;
+		//-- the new page is already rendered — never "restore" the old one
+		previewed = false;
+		const held = open_path;
+		close_panel();
+		if (panel) {
+			set_status(
+				`Page changed — this editor still holds ${held}. Save your changes or close.`,
+				true,
+			);
+		}
+	};
+
+	const set_status = (msg, is_err) => {
+		if (!status_el) return;
+		status_el.textContent = msg || "";
+		status_el.classList.toggle("hb-edit-status-err", !!is_err);
+	};
+
+	//-- Replacing the page body resets the window scroll to the top — brutal
+	//-- when previewing edits deep in long content. Capture the position
+	//-- BEFORE the swap; the returned restorer re-applies it immediately,
+	//-- again on the next frame (post-process reflow) and once more shortly
+	//-- after (late async layout: mermaid rendering, image loads).
+	const capture_page_scroll = () => {
+		//-- the viewer scrolls the #DocContent container, not the window
+		const el =
+			document.getElementById("DocContent") ||
+			document.scrollingElement ||
+			document.documentElement;
+		const y = el.scrollTop;
+		const x = el.scrollLeft;
+		return () => {
+			const restore = () => {
+				el.scrollTop = y;
+				el.scrollLeft = x;
+			};
+			restore();
+			requestAnimationFrame(restore);
+			setTimeout(restore, 300);
+		};
+	};
+
+	//-- Re-render the page body from a server-rendered fragment, then run the
+	//-- viewer's standard post-render pass (TOC, code badges, mermaid, vue
+	//-- components) so the preview behaves like a real page load.
+	const inject_fragment = (html) => {
+		const body = contentContainer();
+		if (!body) return;
+		const restore_scroll = capture_page_scroll();
+		body.innerHTML = html;
+		try {
+			//-- deep-clone to a PLAIN object: docApp.frontmatterData is a Vue
+			//-- reactive proxy, and postProcess postMessage()s it to any parent
+			//-- frame - structured clone throws DataCloneError on a proxy.
+			let fm = {};
+			try {
+				fm = JSON.parse(
+					JSON.stringify(
+						(window.view && view.docApp.frontmatterData) || {},
+					),
+				);
+			} catch {
+				/* keep {} */
+			}
+			postProcessBookContentRender(open_path, fm, `_books/${open_path}`);
+		} catch (e) {
+			console.warn("[hdoc edit] preview post-process failed", e);
+		}
+		restore_scroll();
+	};
+
+	//-- Diagnostics come from two producers — the server lint (dialect +
+	//-- link problems, riding the preview round trip) and the typo worker
+	//-- (nspell, below). Each stores its set; push_diags merges them, letting
+	//-- server findings win where ranges overlap (colour = dialect error AND
+	//-- an en-US typo — one squiggle is enough).
+	let server_diags = [];
+	let typo_diags = [];
+
+	const push_diags = () => {
+		if (!cm || !window.HdocCM.setDiagnostics) return;
+		const len = cm.state.doc.length;
+		const clamp = (list) =>
+			list.filter((d) => d.from >= 0 && d.from < len && d.to <= len);
+		const server = clamp(server_diags);
+		const typos = clamp(typo_diags).filter(
+			(t) => !server.some((s) => t.from < s.to && s.from < t.to),
+		);
+		cm.dispatch(
+			window.HdocCM.setDiagnostics(
+				cm.state,
+				[...server, ...typos].sort((a, b) => a.from - b.from),
+			),
+		);
+	};
+
+	//-- shared "add to the book dictionary" action: persists into
+	//-- hdocbook-project.json (honored by inline lint AND `hdoc validate`),
+	//-- teaches the typo worker, and refreshes both producers
+	const add_to_dictionary = (word) => {
+		api("POST", "/_edit/dictionary", { word }).then((r) => {
+			if (!r.ok) {
+				set_status(
+					(r.json && r.json.error) || "Failed to update the dictionary",
+					true,
+				);
+				return;
+			}
+			dict_words = (r.json && r.json.words) || dict_words;
+			if (spell_worker) spell_worker.postMessage({ type: "add", word });
+			set_status(`Added "${word}" to the book dictionary`);
+			render_preview();
+			schedule_spell(0);
+		});
+	};
+
+	//-- apply server lint findings; dialect findings carry the US spelling
+	//-- as a one-click fix plus the dictionary action.
+	const apply_findings = (findings) => {
+		if (!cm) return;
+		server_diags = (findings || []).map((f) => {
+			const actions = [];
+			if (f.fix) {
+				actions.push({
+					name: `Replace with "${f.fix}"`,
+					apply(view, from, to) {
+						view.dispatch({ changes: { from, to, insert: f.fix } });
+					},
+				});
+			}
+			if (f.word) {
+				actions.push({
+					name: "Add to dictionary",
+					apply() {
+						add_to_dictionary(f.word);
+					},
+				});
+			}
+			return {
+				from: f.from,
+				to: f.to,
+				severity: f.severity === "warning" ? "warning" : "error",
+				message: f.message,
+				actions: actions.length ? actions : undefined,
+			};
+		});
+		push_diags();
+	};
+
+	//-- --- typo spellcheck (nspell in a worker, en-US) ----------------------
+	//-- Same worker logic as `hdoc edit` (editor/spell-standalone.mjs →
+	//-- js/hdoc-edit-spell.js); dictionary fetched from /dict. Typos are
+	//-- warnings (dialect/link findings stay errors) with up to three
+	//-- suggestions and the dictionary action.
+	let spell_worker = null;
+	let spell_timer = null;
+	let spell_seq = 0;
+	let dict_words = [];
+
+	const start_spell = () => {
+		if (spell_worker) return;
+		try {
+			spell_worker = new Worker("js/hdoc-edit-spell.js");
+		} catch {
+			return; //-- worker bundle missing — typo check just stays off
+		}
+		spell_worker.onmessage = (e) => {
+			const msg = e.data || {};
+			if (msg.type !== "result" || !cm) return;
+			if (msg.id !== spell_seq) return; //-- stale run
+			typo_diags = (msg.findings || []).map((f) => {
+				const actions = f.suggestions.slice(0, 3).map((s) => ({
+					name: `"${s}"`,
+					apply(view, from, to) {
+						view.dispatch({ changes: { from, to, insert: s } });
+					},
+				}));
+				actions.push({
+					name: "Add to dictionary",
+					apply() {
+						add_to_dictionary(f.word);
+					},
+				});
+				return {
+					from: f.from,
+					to: f.to,
+					severity: "warning",
+					message: `Unknown word: ${f.word}`,
+					actions,
+				};
+			});
+			push_diags();
+		};
+		spell_worker.onerror = () => {
+			try {
+				spell_worker.terminate();
+			} catch {
+				/* ignore */
+			}
+			spell_worker = null;
+		};
+		//-- the book's custom dictionary seeds the speller
+		api("GET", "/_edit/dictionary").then((r) => {
+			if (r.ok && r.json && Array.isArray(r.json.words)) {
+				dict_words = r.json.words;
+			}
+			schedule_spell(0);
+		});
+	};
+
+	const schedule_spell = (delay = 700) => {
+		if (!spell_worker) return;
+		if (spell_timer) clearTimeout(spell_timer);
+		spell_timer = setTimeout(() => {
+			spell_timer = null;
+			if (!cm || ed_disabled) return;
+			spell_seq++;
+			spell_worker.postMessage({
+				type: "check",
+				id: spell_seq,
+				text: ed_value(),
+				customWords: dict_words,
+			});
+		}, delay);
+	};
+
+	const render_preview = async () => {
+		preview_timer = null;
+		const sent = ed_value();
+		const r = await api("POST", "/_edit/preview", {
+			path: open_path,
+			content: sent,
+		});
+		if (!r.ok || !r.json || typeof r.json.html !== "string") {
+			set_status((r.json && r.json.error) || "Preview failed", true);
+			return;
+		}
+		//-- stale response (buffer moved on while the render ran): the next
+		//-- debounced pass is already scheduled — drop this one
+		if (!cm || ed_value() !== sent) return;
+		apply_findings(r.json.findings);
+		//-- a buffer identical to the saved file needs no injection (this is
+		//-- the lint-only pass that runs on open) and must not flag the page
+		//-- as previewing unsaved content
+		if (sent === saved_content) return;
+		previewed = true;
+		inject_fragment(r.json.html);
+	};
+
+	const schedule_preview = () => {
+		last_typed = Date.now();
+		if (preview_timer) clearTimeout(preview_timer);
+		preview_timer = setTimeout(render_preview, 600);
+		set_status(ed_value() === saved_content ? "" : "Unsaved changes");
+	};
+
+	const save = async () => {
+		if (!panel || ed_disabled) return;
+		set_status("Saving…");
+		const value = ed_value();
+		const out = eol === "\r\n" ? value.replace(/\r?\n/g, "\r\n") : value;
+		const r = await api(
+			"PUT",
+			`/_edit/source?path=${encodeURIComponent(open_path)}`,
+			{ content: out, baseEtag: etag },
+		);
+		if (r.status === 409) {
+			set_status(
+				"Conflict: this file changed on disk since it was opened. Copy your changes, close the panel and re-open it to pick up the latest version.",
+				true,
+			);
+			return;
+		}
+		if (!r.ok || !r.json) {
+			set_status((r.json && r.json.error) || "Save failed", true);
+			return;
+		}
+		etag = r.json.etag;
+		saved_content = value;
+		previewed = false;
+		set_status(`Saved ${r.json.file}`);
+		//-- re-render from disk so the page shows exactly what was persisted,
+		//-- holding the reader's scroll position through the reload
+		const restore_scroll = capture_page_scroll();
+		try {
+			await loadContentUrl(open_path);
+			restore_scroll();
+		} catch {
+			window.location.reload();
+		}
+	};
+
+	const close_panel = () => {
+		if (!panel) return;
+		if (
+			cm &&
+			!ed_disabled &&
+			ed_value() !== saved_content &&
+			!window.confirm("Discard unsaved changes?")
+		) {
+			return;
+		}
+		if (preview_timer) clearTimeout(preview_timer);
+		preview_timer = null;
+		if (spell_timer) clearTimeout(spell_timer);
+		spell_timer = null;
+		if (scroll_sync_timer) clearTimeout(scroll_sync_timer);
+		scroll_sync_timer = null;
+		if (hl_timer) clearTimeout(hl_timer);
+		hl_timer = null;
+		document.removeEventListener("scroll", on_page_scroll, true);
+		if (cm) {
+			cm.destroy();
+			cm = null;
+		}
+		panel.remove();
+		panel = null;
+		status_el = null;
+		save_btn = null;
+		ed_disabled = true;
+		document.body.classList.remove("hb-edit-open");
+		//-- if the page body is showing an unsaved preview, restore it from
+		//-- disk — holding the reader's scroll position through the reload
+		if (previewed) {
+			previewed = false;
+			const restore_scroll = capture_page_scroll();
+			loadContentUrl(open_path).then(restore_scroll, () => {
+				window.location.reload();
+			});
+		}
+	};
+
+	const build_panel = () => {
+		panel = document.createElement("aside");
+		panel.className = "hb-edit-panel";
+		panel.innerHTML = `
+			<div class="hb-edit-resizer" title="Drag to resize"></div>
+			<div class="hb-edit-head">
+				<span class="hb-edit-title">Edit page</span>
+				<span>
+					<button type="button" class="hb-edit-wrap" title="Toggle word wrap" aria-label="Toggle word wrap"><i class="bi bi-text-wrap" aria-hidden="true"></i></button>
+					<button type="button" class="hb-edit-x" title="Close (Esc)" aria-label="Close editor">&times;</button>
+				</span>
+			</div>
+			<div class="hb-edit-cm" aria-label="Page markdown source"></div>
+			<div class="hb-edit-status" role="status"></div>
+			<div class="hb-edit-foot">
+				<button type="button" class="hb-edit-save">Save</button>
+				<button type="button" class="hb-edit-cancel">Close</button>
+			</div>`;
+		document.body.appendChild(panel);
+		document.body.classList.add("hb-edit-open");
+
+		status_el = panel.querySelector(".hb-edit-status");
+		save_btn = panel.querySelector(".hb-edit-save");
+
+		const saved_width = Number.parseInt(pref("hdoc-edit-width"), 10);
+		if (saved_width) {
+			panel.style.width = `${Math.min(saved_width, window.innerWidth * 0.92)}px`;
+		}
+		const resizer = panel.querySelector(".hb-edit-resizer");
+		resizer.addEventListener("pointerdown", (ev) => {
+			ev.preventDefault();
+			resizer.setPointerCapture(ev.pointerId);
+			const on_move = (mv) => {
+				const w = Math.min(
+					Math.max(window.innerWidth - mv.clientX, 360),
+					window.innerWidth * 0.92,
+				);
+				panel.style.width = `${w}px`;
+			};
+			const on_up = () => {
+				resizer.removeEventListener("pointermove", on_move);
+				resizer.removeEventListener("pointerup", on_up);
+				set_pref("hdoc-edit-width", String(Math.round(panel.offsetWidth)));
+			};
+			resizer.addEventListener("pointermove", on_move);
+			resizer.addEventListener("pointerup", on_up);
+		});
+
+		save_btn.addEventListener("click", save);
+		panel.querySelector(".hb-edit-cancel").addEventListener("click", close_panel);
+		panel.querySelector(".hb-edit-x").addEventListener("click", close_panel);
+		panel.addEventListener("keydown", (ev) => {
+			if (ev.key === "Escape") {
+				ev.stopPropagation();
+				close_panel();
+			} else if ((ev.ctrlKey || ev.metaKey) && ev.key.toLowerCase() === "s") {
+				ev.preventDefault();
+				save();
+			}
+		});
+	};
+
+	//-- Create the CodeMirror view inside the panel — same stack `hdoc edit`
+	//-- uses (basicSetup: line numbers, fold gutter, history, search;
+	//-- markdown language), plus a theme matching the panel's light/dark look.
+	const build_editor = () => {
+		const CM = window.HdocCM;
+		wrap_comp = new CM.Compartment();
+		ro_comp = new CM.Compartment();
+
+		const dark = document.documentElement.classList.contains("dark");
+		const theme = CM.EditorView.theme(
+			{
+				"&": {
+					height: "100%",
+					fontSize: "13px",
+					backgroundColor: "transparent",
+					color: "inherit",
+				},
+				".cm-scroller": {
+					fontFamily: 'Consolas, "SFMono-Regular", Menlo, monospace',
+					lineHeight: "1.55",
+					overflow: "auto",
+				},
+				".cm-gutters": {
+					backgroundColor: "transparent",
+					borderRight: dark
+						? "1px solid rgba(255,255,255,.08)"
+						: "1px solid rgba(0,0,0,.08)",
+					color: dark ? "#6c757d" : "#adb5bd",
+				},
+				".cm-activeLine": {
+					backgroundColor: dark
+						? "rgba(255,255,255,.04)"
+						: "rgba(0,0,0,.03)",
+				},
+				".cm-activeLineGutter": {
+					backgroundColor: dark
+						? "rgba(255,255,255,.06)"
+						: "rgba(0,0,0,.05)",
+				},
+				"&.cm-focused": { outline: "none" },
+				".cm-cursor": { borderLeftColor: dark ? "#dee2e6" : "#212529" },
+				".cm-selectionBackground, &.cm-focused .cm-selectionBackground": {
+					backgroundColor: dark
+						? "rgba(100,150,255,.25)"
+						: "rgba(100,150,255,.22)",
+				},
+			},
+			{ dark },
+		);
+
+		//-- CM's default syntax colors are designed for a light background —
+		//-- markdown link URLs in particular are near-unreadable on dark. Give
+		//-- dark mode its own palette (light keeps the CM defaults).
+		const t = CM.tags;
+		const dark_syntax = CM.syntaxHighlighting(
+			CM.HighlightStyle.define([
+				{ tag: [t.link, t.url], color: "#6ea8fe" },
+				{ tag: t.heading, color: "#ffd777", fontWeight: "bold" },
+				{ tag: t.strong, fontWeight: "bold" },
+				{ tag: t.emphasis, fontStyle: "italic" },
+				{ tag: t.monospace, color: "#98c379" },
+				{ tag: t.quote, color: "#8fbc8f" },
+				{ tag: [t.meta, t.processingInstruction, t.comment], color: "#8a939c" },
+				{ tag: t.strikethrough, textDecoration: "line-through" },
+			]),
+		);
+
+		const wrap_on = pref("hdoc-edit-wrap") !== "0";
+		cm = new CM.EditorView({
+			state: CM.EditorState.create({
+				doc: "",
+				extensions: [
+					CM.basicSetup,
+					CM.markdown(),
+					theme,
+					...(dark ? [dark_syntax] : []),
+					build_highlight_ext(),
+					build_image_dnd_ext(),
+					//-- guarded: an older cached bundle may lack the lint exports
+					...(CM.lintGutter ? [CM.lintGutter()] : []),
+					wrap_comp.of(wrap_on ? CM.EditorView.lineWrapping : []),
+					ro_comp.of([
+						CM.EditorState.readOnly.of(true),
+						CM.EditorView.editable.of(false),
+					]),
+					CM.EditorView.updateListener.of((u) => {
+						if (u.docChanged && !ed_loading) {
+							schedule_preview();
+							schedule_spell();
+						}
+					}),
+				],
+			}),
+			parent: panel.querySelector(".hb-edit-cm"),
+		});
+
+		//-- right-click inside the editor → insert-snippet menu
+		panel
+			.querySelector(".hb-edit-cm")
+			.addEventListener("contextmenu", on_editor_ctx);
+
+		const wrap_btn = panel.querySelector(".hb-edit-wrap");
+		wrap_btn.classList.toggle("hb-edit-wrap-on", wrap_on);
+		wrap_btn.addEventListener("click", () => {
+			const on = !wrap_btn.classList.contains("hb-edit-wrap-on");
+			cm.dispatch({
+				effects: wrap_comp.reconfigure(
+					on ? CM.EditorView.lineWrapping : [],
+				),
+			});
+			wrap_btn.classList.toggle("hb-edit-wrap-on", on);
+			set_pref("hdoc-edit-wrap", on ? "1" : "0");
+			cm.focus();
+		});
+	};
+
+	const open_panel = async () => {
+		if (panel) {
+			close_panel();
+			return;
+		}
+		open_path = logical_path();
+		previewed = false;
+		build_panel();
+		save_btn.disabled = true;
+		set_status("Loading…");
+		try {
+			await cm_ready;
+		} catch {
+			set_status(
+				"Editor failed to load (js/hdoc-edit-cm.js missing — rebuild it from editor/cm-standalone.mjs)",
+				true,
+			);
+			return;
+		}
+		if (!panel) return; //-- closed while loading
+		build_editor();
+		const r = await api(
+			"GET",
+			`/_edit/source?path=${encodeURIComponent(open_path)}`,
+		);
+		if (!panel) return; //-- closed while loading
+		if (!r.ok || !r.json) {
+			set_status(
+				(r.json && r.json.error) || "No markdown source found for this page",
+				true,
+			);
+			return;
+		}
+		eol = r.json.content.includes("\r\n") ? "\r\n" : "\n";
+		open_file_rel = r.json.file || "";
+		server_diags = [];
+		typo_diags = [];
+		ed_set_disabled(false);
+		//-- LF-normalize for the buffer; Save re-applies the original EOLs
+		ed_set_value(r.json.content.replace(/\r\n/g, "\n"));
+		saved_content = ed_value();
+		etag = r.json.etag;
+		save_btn.disabled = false;
+		set_status(`Editing ${r.json.file}`);
+		//-- open the editor at the content the reader is currently looking at
+		//-- (caret placed on the matched line so focus lands there too), and
+		//-- keep following while the page (not the editor) scrolls
+		sync_editor_scroll(true);
+		cm.focus();
+		document.addEventListener("scroll", on_page_scroll, true);
+		//-- initial lint + typo passes (buffer == disk, nothing is injected)
+		render_preview();
+		start_spell();
+		schedule_spell(0);
+	};
+
+	const inject_styles = () => {
+		const css = `
+.hb-edit-panel {
+	position: fixed; top: 0; right: 0; bottom: 0; z-index: 3001;
+	width: min(680px, 92vw); display: flex; flex-direction: column;
+	background: #ffffff; color: #212529;
+	border-left: 1px solid rgba(0,0,0,.15);
+	box-shadow: -8px 0 28px rgba(0,0,0,.22);
+	font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+html.dark .hb-edit-panel { background: #1b1e21; color: #dee2e6; border-left-color: rgba(255,255,255,.12); }
+.hb-edit-head {
+	display: flex; align-items: center; justify-content: space-between;
+	padding: 10px 14px; border-bottom: 1px solid rgba(0,0,0,.1); font-weight: 600;
+}
+html.dark .hb-edit-head { border-bottom-color: rgba(255,255,255,.1); }
+.hb-edit-x {
+	border: none; background: none; font-size: 22px; cursor: pointer;
+	color: inherit; padding: 0 4px; line-height: 1;
+}
+.hb-edit-cm { flex: 1 1 auto; overflow: hidden; }
+.hb-edit-cm .cm-editor { height: 100%; }
+.hb-edit-hl-line { animation: hb-edit-hl-fade 2.5s ease-out forwards; }
+@keyframes hb-edit-hl-fade {
+	0%, 25% { background-color: rgba(255, 190, 60, .55); }
+	100% { background-color: transparent; }
+}
+html.dark .hb-edit-hl-line { animation-name: hb-edit-hl-fade-dark; }
+@keyframes hb-edit-hl-fade-dark {
+	0%, 25% { background-color: rgba(255, 190, 60, .30); }
+	100% { background-color: transparent; }
+}
+.hb-edit-resizer {
+	position: absolute; left: -3px; top: 0; bottom: 0; width: 8px;
+	cursor: ew-resize; touch-action: none; z-index: 1;
+}
+.hb-edit-resizer:hover { background: rgba(128,128,128,.25); }
+.hb-edit-wrap {
+	border: none; background: none; cursor: pointer; color: inherit;
+	font-size: 16px; padding: 0 8px; opacity: .45; vertical-align: 1px;
+}
+.hb-edit-wrap.hb-edit-wrap-on { opacity: 1; color: #b8860b; }
+html.dark .hb-edit-wrap.hb-edit-wrap-on { color: #ffd777; }
+.hb-edit-status {
+	padding: 6px 14px; font-size: 12px; min-height: 26px; opacity: .85;
+	border-top: 1px solid rgba(0,0,0,.08);
+}
+html.dark .hb-edit-status { border-top-color: rgba(255,255,255,.08); }
+.hb-edit-status-err { color: #c62828; opacity: 1; }
+html.dark .hb-edit-status-err { color: #ff8a80; }
+.hb-edit-foot {
+	display: flex; gap: 8px; padding: 10px 14px 14px;
+}
+.hb-edit-foot button {
+	padding: 6px 18px; border-radius: 6px; cursor: pointer; font-size: 14px;
+	border: 1px solid rgba(0,0,0,.2); background: none; color: inherit;
+}
+html.dark .hb-edit-foot button { border-color: rgba(255,255,255,.25); }
+.hb-edit-save { background: #ffd777 !important; color: #6b4400 !important; border-color: transparent !important; font-weight: 600; }
+html.dark .hb-edit-save { background: #7a5200 !important; color: #ffe2a0 !important; }
+.hb-edit-save:disabled { opacity: .5; cursor: default; }
+.hb-edit-ctx {
+	position: fixed; z-index: 3002; padding: 4px;
+	background: #ffffff; border: 1px solid rgba(0,0,0,.15); border-radius: 8px;
+	box-shadow: 0 6px 20px rgba(0,0,0,.2);
+	font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+	max-height: 70vh; overflow-y: auto;
+}
+.hb-edit-ctx-sep { height: 1px; margin: 4px 8px; background: rgba(0,0,0,.1); }
+html.dark .hb-edit-ctx-sep { background: rgba(255,255,255,.12); }
+html.dark .hb-edit-ctx { background: #23272b; border-color: rgba(255,255,255,.15); }
+.hb-edit-ctx-item {
+	display: block; width: 100%; text-align: left; white-space: nowrap;
+	border: none; background: none; color: #212529; cursor: pointer;
+	padding: 7px 12px; border-radius: 6px; font-size: 13px;
+}
+html.dark .hb-edit-ctx-item { color: #dee2e6; }
+.hb-edit-ctx-item:hover { background: rgba(0,0,0,.06); }
+html.dark .hb-edit-ctx-item:hover { background: rgba(255,255,255,.08); }
+.hb-edit-ctx-item .bi { color: #b8860b; margin-right: 6px; }
+html.dark .hb-edit-ctx-item .bi { color: #ffd777; }
+`;
+		const style = document.createElement("style");
+		style.textContent = css;
+		document.head.appendChild(style);
+	};
+
+	//-- Lazy-load the CodeMirror bundle — only edit mode pays its weight.
+	const load_cm_bundle = () =>
+		new Promise((resolve, reject) => {
+			if (window.HdocCM) return resolve();
+			const script = document.createElement("script");
+			script.src = "js/hdoc-edit-cm.js";
+			script.onload = () =>
+				window.HdocCM ? resolve() : reject(new Error("bundle bad"));
+			script.onerror = () => reject(new Error("bundle load failed"));
+			document.head.appendChild(script);
+		});
+
+	const init = async () => {
+		let enabled = false;
+		try {
+			const r = await fetch("/_edit/mode", {
+				headers: { accept: "application/json" },
+			});
+			const ct = r.headers.get("content-type") || "";
+			if (r.ok && ct.includes("json")) {
+				enabled = (await r.json()).enabled === true;
+			}
+		} catch {
+			/* not in edit mode / not hdoc serve */
+		}
+		if (!enabled) return;
+		//-- tiny API for the Edit Mode suite (js/hdoc-edit-book.js): open the
+		//-- page editor programmatically (Files tab, Edit Mode toggle).
+		//-- open_panel() TOGGLES, so open()/close() gate on panel state.
+		window.HdocEditInline = {
+			open: () => {
+				if (!panel) open_panel();
+			},
+			close: () => {
+				if (panel) close_panel();
+			},
+			isOpen: () => !!panel,
+			//-- insert text at the caret of the open editor (Files tab's
+			//-- "Insert into open page"); false when no editable buffer
+			insert: (text) => ed_insert_at(String(text)),
+		};
+		cm_ready = load_cm_bundle();
+		cm_ready.catch(() => {}); //-- surfaced in open_panel, not unhandled
+		inject_styles();
+		//-- right-click menu on page content (active whether or not the panel
+		//-- is open — it opens the panel on demand)
+		document.addEventListener("contextmenu", on_context_menu);
+		document.addEventListener("click", () => {
+			close_ctx_menu();
+			close_ed_ctx();
+		});
+		document.addEventListener("keydown", (ev) => {
+			if (ev.key === "Escape") {
+				close_ctx_menu();
+				close_ed_ctx();
+			}
+		});
+		//-- external file changes (pushed over SSE by js/hdoc-edit-book.js
+		//-- while Edit Mode is on): if the OPEN file changed on disk, refresh
+		//-- a clean buffer in place; warn on a dirty one (its etag will 409
+		//-- rather than clobber the external edit)
+		window.addEventListener("hdoc-ext-change", async (ev) => {
+			const d = (ev && ev.detail) || {};
+			if (!panel || !cm || ed_disabled) return;
+			if (!open_file_rel || d.path !== open_file_rel) return;
+			if (!d.exists) {
+				set_status("This file was deleted on disk.", true);
+				return;
+			}
+			if (ed_value() !== saved_content) {
+				set_status(
+					"This file changed on disk while you have unsaved changes — saving now will report a conflict.",
+					true,
+				);
+				return;
+			}
+			const r = await api(
+				"GET",
+				`/_edit/source?path=${encodeURIComponent(open_path)}`,
+			);
+			if (!panel || !r.ok || !r.json) return;
+			eol = r.json.content.includes("\r\n") ? "\r\n" : "\n";
+			ed_set_value(r.json.content.replace(/\r\n/g, "\n"));
+			saved_content = ed_value();
+			etag = r.json.etag;
+			set_status("Reloaded — this file changed on disk.");
+			//-- refresh the rendered page too, holding scroll
+			const restore_scroll = capture_page_scroll();
+			loadContentUrl(open_path).then(restore_scroll, () => {});
+		});
+
+		//-- SPA navigation detection: back/forward plus the history writes the
+		//-- viewer makes on nav-link clicks
+		window.addEventListener("popstate", () => setTimeout(on_nav_change, 0));
+		for (const fn of ["pushState", "replaceState"]) {
+			const orig = history[fn].bind(history);
+			history[fn] = (...args) => {
+				const r = orig(...args);
+				setTimeout(on_nav_change, 0);
+				return r;
+			};
+		}
+	};
+
+	init();
+})();