hdoc-tools 0.64.0 → 0.65.0

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

@@ -29,6 +29,7 @@
 	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;
@@ -123,6 +124,435 @@
 		});
 	};
 
+	//-- --- 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
@@ -529,16 +959,180 @@
 		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: ed_value(),
+			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);
 	};
@@ -598,6 +1192,8 @@
 		}
 		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);
@@ -763,19 +1359,30 @@
 					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();
+						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", () => {
@@ -825,6 +1432,9 @@
 			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"));
@@ -838,6 +1448,10 @@
 		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 = () => {
@@ -906,7 +1520,10 @@ html.dark .hb-edit-save { background: #7a5200 !important; color: #ffe2a0 !import
 	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;
@@ -950,16 +1567,71 @@ html.dark .hb-edit-ctx-item .bi { color: #ffd777; }
 			/* 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);
+		document.addEventListener("click", () => {
+			close_ctx_menu();
+			close_ed_ctx();
+		});
 		document.addEventListener("keydown", (ev) => {
-			if (ev.key === "Escape") close_ctx_menu();
+			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));