hdoc-tools 0.63.0 → 0.64.0

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

@@ -0,0 +1,977 @@
+//-- 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 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) },
+		});
+	};
+
+	//-- --- 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();
+	};
+
+	const render_preview = async () => {
+		preview_timer = null;
+		const r = await api("POST", "/_edit/preview", {
+			path: open_path,
+			content: ed_value(),
+		});
+		if (!r.ok || !r.json || typeof r.json.html !== "string") {
+			set_status((r.json && r.json.error) || "Preview failed", true);
+			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 (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(),
+					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();
+					}),
+				],
+			}),
+			parent: panel.querySelector(".hb-edit-cm"),
+		});
+
+		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";
+		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);
+	};
+
+	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;
+}
+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;
+		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);
+		document.addEventListener("keydown", (ev) => {
+			if (ev.key === "Escape") close_ctx_menu();
+		});
+		//-- 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();
+})();