hdoc-tools 0.63.0 → 0.65.0

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

@@ -0,0 +1,2129 @@
+//-- 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.
+//--
+//-- Edit Mode suite for `hdoc serve` (PoC). Probes /_edit/mode; when the
+//-- server confirms edit mode (loopback callers only), an "Edit mode" toggle
+//-- button is added to the toolbar (next to the AI button). Toggling it on:
+//--   - opens the inline page editor (js/hdoc-edit-inline.js)
+//--   - swaps the left-hand Vue nav for a managed sidebar with two tabs:
+//--       Contents — the book's navigation tree (hdocbook.json), with the
+//--                  same operations as the `hdoc edit` Contents tab:
+//--                  rename, add page/section, delete (± file), draft flag,
+//--                  node properties (text/link/expand/id), and move via
+//--                  drag-drop or menu
+//--       Files    — every file on disk under the book (excluding _ folders),
+//--                  flagged page/image/other and linked/unlinked; open pages
+//--                  in the editor, create pages/folders, delete files
+//-- All writes go to the /_edit/toc and /_edit/files routes served by
+//-- hdoc-serve.js (loopback-gated), backed by the same TocModel that powers
+//-- `hdoc edit`. After every nav change the viewer's own nav data is
+//-- refreshed from disk so leaving Edit Mode shows the updated tree.
+//-- Relies on viewer globals: view.docApp, loadContentUrl(); and on
+//-- window.HdocEditInline exposed by js/hdoc-edit-inline.js.
+
+(() => {
+	"use strict";
+
+	let edit_mode = false;
+	let tab = "contents"; //-- "contents" | "files"
+	let host = null; //-- our sidebar panel element
+	let toc_dto = null; //-- { docId, title, tree }
+	let files_dto = null; //-- { docId, dirs, files }
+	let ctx_menu = null;
+	let drag_id = null;
+	let files_unlinked_only = false; //-- Files tab: show only unlinked pages
+	const nav_problems = new Map(); //-- node id -> [problem strings] (last nav validate)
+	let es = null; //-- EventSource for /_edit/events (open while edit mode is on)
+	let fs_refresh_timer = null;
+	//-- expanded state survives re-renders (not persisted across reloads)
+	const expanded = new Set(); //-- branch node ids
+	const fexpanded = new Set(); //-- folder rel paths
+
+	//-- --- utilities --------------------------------------------------------
+
+	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 };
+	};
+
+	const pref = (k) => {
+		try {
+			return localStorage.getItem(k);
+		} catch {
+			return null;
+		}
+	};
+	const set_pref = (k, v) => {
+		try {
+			localStorage.setItem(k, v);
+		} catch {
+			/* ignore */
+		}
+	};
+
+	const docid = () =>
+		(window.view && view.docApp.book && view.docApp.book.docId) ||
+		decodeURIComponent(window.location.pathname).replace(/^\/+/, "").split("/")[0];
+
+	const logical_path = () =>
+		decodeURIComponent(window.location.pathname)
+			.replace(/^\/+/, "")
+			.replace(/\/+$/, "");
+
+	const esc_html = (s) =>
+		String(s ?? "")
+			.replace(/&/g, "&")
+			.replace(/</g, "&lt;")
+			.replace(/>/g, "&gt;")
+			.replace(/"/g, "&quot;");
+
+	const toast = (msg, is_err) => {
+		const t = document.createElement("div");
+		t.className = `hb-eb-toast${is_err ? " hb-eb-toast-err" : ""}`;
+		t.textContent = msg;
+		document.body.appendChild(t);
+		setTimeout(() => t.remove(), is_err ? 6000 : 2600);
+	};
+
+	//-- navigate the viewer SPA to a book-relative link (no leading slash)
+	const nav_to = (link) => {
+		try {
+			return Promise.resolve(loadContentUrl(link));
+		} catch {
+			window.location.href = `/${link}`;
+			return Promise.resolve();
+		}
+	};
+
+	//-- Open the page editor once the inline patch is ready. On a fresh page
+	//-- load window.HdocEditInline appears only after that script's async
+	//-- /_edit/mode probe resolves, so a direct call can silently no-op —
+	//-- poll briefly instead. Bails out if edit mode is left meanwhile.
+	const open_editor_soon = () => {
+		let tries = 0;
+		const t = setInterval(() => {
+			if (!edit_mode || ++tries > 25) {
+				clearInterval(t);
+				return;
+			}
+			if (window.HdocEditInline) {
+				clearInterval(t);
+				window.HdocEditInline.open();
+			}
+		}, 200);
+	};
+
+	//-- refresh the viewer's own nav model from disk so the Vue nav (shown
+	//-- when Edit Mode is off) reflects structural changes
+	const refresh_vue_nav = async () => {
+		try {
+			const r = await fetch(`/_books/${docid()}/hdocbook.json`);
+			if (!r.ok) return;
+			const book = await r.json();
+			if (
+				window.view &&
+				view.docApp.book &&
+				view.docApp.book.docId &&
+				book.navigation
+			) {
+				view.docApp.book.navigation = book.navigation;
+				view.renderNavigation();
+			}
+		} catch {
+			/* nav refresh is best-effort */
+		}
+	};
+
+	//-- --- context menu -----------------------------------------------------
+
+	const close_ctx = () => {
+		if (ctx_menu) {
+			ctx_menu.remove();
+			ctx_menu = null;
+		}
+	};
+
+	//-- items: [{ label, icon, danger, sep, onClick }]
+	const show_ctx = (x, y, items) => {
+		close_ctx();
+		ctx_menu = document.createElement("div");
+		ctx_menu.className = "hb-eb-ctx";
+		for (const it of items) {
+			if (it.sep) {
+				const s = document.createElement("div");
+				s.className = "hb-eb-ctx-sep";
+				ctx_menu.appendChild(s);
+				continue;
+			}
+			const b = document.createElement("button");
+			b.type = "button";
+			b.className = `hb-eb-ctx-item${it.danger ? " hb-eb-ctx-danger" : ""}`;
+			b.innerHTML = `<i class="bi ${it.icon || "bi-dot"}" aria-hidden="true"></i> ${esc_html(it.label)}`;
+			b.addEventListener("click", (e) => {
+				e.stopPropagation();
+				close_ctx();
+				it.onClick();
+			});
+			ctx_menu.appendChild(b);
+		}
+		document.body.appendChild(ctx_menu);
+		ctx_menu.style.left = `${Math.min(x, window.innerWidth - ctx_menu.offsetWidth - 8)}px`;
+		ctx_menu.style.top = `${Math.min(y, window.innerHeight - ctx_menu.offsetHeight - 8)}px`;
+	};
+
+	//-- --- dialog -----------------------------------------------------------
+	//-- Minimal modal: title, fields, OK/Cancel. Resolves to { name: value }
+	//-- (checkbox -> boolean) or null on cancel/Escape.
+
+	const dialog = ({ title, message, fields = [], okText = "OK", danger }) =>
+		new Promise((resolve) => {
+			const overlay = document.createElement("div");
+			overlay.className = "hb-eb-overlay";
+			const box = document.createElement("div");
+			box.className = "hb-eb-dialog";
+			let inner = `<div class="hb-eb-dialog-title">${esc_html(title)}</div>`;
+			if (message) {
+				inner += `<div class="hb-eb-dialog-msg">${esc_html(message)}</div>`;
+			}
+			for (const f of fields) {
+				if (f.type === "checkbox") {
+					inner += `<label class="hb-eb-dialog-check"><input type="checkbox" name="${esc_html(f.name)}" ${f.value ? "checked" : ""}/> ${esc_html(f.label)}</label>`;
+				} else if (f.type === "heading") {
+					inner += `<div class="hb-eb-dialog-sect">${esc_html(f.label)}</div>`;
+				} else if (f.type === "select") {
+					const opts = (f.options || [])
+						.map(
+							(o) =>
+								`<option value="${esc_html(o.value)}" ${o.value === (f.value ?? "") ? "selected" : ""}>${esc_html(o.label)}</option>`,
+						)
+						.join("");
+					inner += `<label class="hb-eb-dialog-field"><span>${esc_html(f.label)}</span><select name="${esc_html(f.name)}">${opts}</select></label>`;
+				} else {
+					const input = `<input type="text" name="${esc_html(f.name)}" value="${esc_html(f.value ?? "")}" placeholder="${esc_html(f.placeholder ?? "")}" spellcheck="false"/>`;
+					//-- a field with a browse callback gets a picker button
+					inner += `<label class="hb-eb-dialog-field"><span>${esc_html(f.label)}</span>${
+						f.browse
+							? `<span class="hb-eb-dialog-browse-wrap">${input}<button type="button" class="hb-eb-btn hb-eb-btn-sm" data-browse="${esc_html(f.name)}" title="Choose an existing page"><i class="bi bi-folder2-open"></i></button></span>`
+							: input
+					}</label>`;
+				}
+				if (f.hint) {
+					inner += `<div class="hb-eb-dialog-hint">${esc_html(f.hint)}</div>`;
+				}
+			}
+			inner += `<div class="hb-eb-dialog-foot">
+				<button type="button" class="hb-eb-btn ${danger ? "hb-eb-btn-danger" : "hb-eb-btn-primary"}" data-act="ok">${esc_html(okText)}</button>
+				<button type="button" class="hb-eb-btn" data-act="cancel">Cancel</button>
+			</div>`;
+			box.innerHTML = inner;
+			overlay.appendChild(box);
+			document.body.appendChild(overlay);
+
+			const done = (values) => {
+				overlay.remove();
+				resolve(values);
+			};
+			const collect = () => {
+				const out = {};
+				for (const f of fields) {
+					if (f.type === "heading") continue;
+					const el = box.querySelector(`[name="${f.name}"]`);
+					out[f.name] = f.type === "checkbox" ? el.checked : el.value;
+				}
+				return out;
+			};
+			box.querySelector('[data-act="ok"]').addEventListener("click", () =>
+				done(collect()),
+			);
+			for (const bb of box.querySelectorAll("[data-browse]")) {
+				const f = fields.find((x) => x.name === bb.dataset.browse);
+				bb.addEventListener("click", () =>
+					f.browse(box.querySelector(`[name="${f.name}"]`), box),
+				);
+			}
+			box
+				.querySelector('[data-act="cancel"]')
+				.addEventListener("click", () => done(null));
+			overlay.addEventListener("mousedown", (e) => {
+				if (e.target === overlay) done(null);
+			});
+			box.addEventListener("keydown", (e) => {
+				if (e.key === "Escape") done(null);
+				else if (e.key === "Enter" && e.target.tagName === "INPUT") {
+					e.preventDefault();
+					done(collect());
+				}
+			});
+			const first = box.querySelector('input[type="text"]');
+			if (first) {
+				first.focus();
+				first.select();
+			} else {
+				box.querySelector('[data-act="ok"]').focus();
+			}
+		});
+
+	//-- --- TOC (Contents) model helpers ------------------------------------
+
+	//-- id -> { node, parentId, index, siblings } for the current DTO
+	const toc_index = () => {
+		const map = new Map();
+		const walk = (nodes, parentId) => {
+			nodes.forEach((n, i) => {
+				map.set(n.id, { node: n, parentId, index: i, siblings: nodes });
+				if (n.type === "branch") walk(n.children, n.id);
+			});
+		};
+		if (toc_dto) walk(toc_dto.tree, null);
+		return map;
+	};
+
+	const load_toc = async () => {
+		const r = await api("GET", "/_edit/toc");
+		if (!r.ok || !r.json) {
+			toast((r.json && r.json.error) || "Failed to load contents", true);
+			return;
+		}
+		toc_dto = r.json;
+		render();
+	};
+
+	const load_files = async () => {
+		const r = await api("GET", "/_edit/files");
+		if (!r.ok || !r.json) {
+			toast((r.json && r.json.error) || "Failed to load files", true);
+			return;
+		}
+		files_dto = r.json;
+		render();
+	};
+
+	//-- run a TOC mutation; the server answers with the fresh DTO
+	const toc_call = async (url, body, method) => {
+		const r = await api(method || "POST", url, body);
+		if (!r.ok || !r.json) {
+			toast((r.json && r.json.error) || "Operation failed", true);
+			return false;
+		}
+		//-- regular ops answer with the DTO itself; DELETE wraps it as
+		//-- { tree: <dto>, fileDeleted } — the DTO always carries docId
+		toc_dto = r.json.docId ? r.json : r.json.tree;
+		render();
+		refresh_vue_nav();
+		//-- files linked-flags may have changed
+		if (files_dto) load_files();
+		return r.json;
+	};
+
+	//-- --- validation --------------------------------------------------------
+
+	//-- results overlay: sections of [{label, cls, items}]
+	const show_results = ({ title, sections, raw }) => {
+		const overlay = document.createElement("div");
+		overlay.className = "hb-eb-overlay";
+		const box = document.createElement("div");
+		box.className = "hb-eb-dialog hb-eb-results";
+		let inner = `<div class="hb-eb-dialog-title">${esc_html(title)}</div><div class="hb-eb-results-body">`;
+		let any = false;
+		for (const s of sections || []) {
+			if (!s.items || !s.items.length) continue;
+			any = true;
+			inner += `<div class="hb-eb-dialog-sect">${esc_html(s.label)} (${s.items.length})</div><ul class="hb-eb-results-list ${s.cls || ""}">`;
+			for (const it of s.items) inner += `<li>${esc_html(it)}</li>`;
+			inner += "</ul>";
+		}
+		if (raw) {
+			any = true;
+			inner += `<pre class="hb-eb-results-raw">${esc_html(raw)}</pre>`;
+		}
+		if (!any) {
+			inner += '<div class="hb-eb-results-ok"><i class="bi bi-check-circle"></i> No problems found</div>';
+		}
+		inner += `</div><div class="hb-eb-dialog-foot"><button type="button" class="hb-eb-btn" data-act="close">Close</button></div>`;
+		box.innerHTML = inner;
+		overlay.appendChild(box);
+		document.body.appendChild(overlay);
+		const done = () => overlay.remove();
+		box.querySelector('[data-act="close"]').addEventListener("click", done);
+		overlay.addEventListener("mousedown", (e) => {
+			if (e.target === overlay) done();
+		});
+		box.setAttribute("tabindex", "-1");
+		box.addEventListener("keydown", (e) => {
+			if (e.key === "Escape") done();
+		});
+		box.focus();
+	};
+
+	const op_validate_nav = async () => {
+		toast("Validating navigation…");
+		const r = await api("POST", "/_edit/validate/nav", {});
+		if (!r.ok || !r.json) {
+			toast((r.json && r.json.error) || "Validation failed", true);
+			return;
+		}
+		nav_problems.clear();
+		for (const n of r.json.nodes || []) nav_problems.set(n.id, n.problems);
+		render();
+		if (!nav_problems.size) {
+			toast("Navigation OK — no problems found");
+		} else {
+			const count = [...nav_problems.values()].reduce(
+				(a, p) => a + p.length,
+				0,
+			);
+			toast(
+				`${count} problem${count > 1 ? "s" : ""} in ${nav_problems.size} nav item${nav_problems.size > 1 ? "s" : ""} — see the markers in the tree`,
+				true,
+			);
+		}
+	};
+
+	const op_validate_page = async (link, label) => {
+		const clean = String(link).replace(/^\/+/, "");
+		toast(`Validating ${label || clean}…`);
+		const r = await api("POST", "/_edit/validate/page", {
+			path: clean,
+			external: true,
+		});
+		if (!r.ok || !r.json) {
+			toast((r.json && r.json.error) || "Validation failed", true);
+			return;
+		}
+		show_results({
+			title: `Validation — ${r.json.file || clean}`,
+			sections: [
+				{ label: "Errors", cls: "hb-eb-res-err", items: r.json.errors },
+				{ label: "Warnings", cls: "hb-eb-res-warn", items: r.json.warnings },
+				{ label: "Not checked", cls: "hb-eb-res-skip", items: r.json.skipped },
+			],
+		});
+	};
+
+	const op_validate_book = async () => {
+		const v = await dialog({
+			title: "Validate book",
+			message:
+				"Runs the full `hdoc validate` build pipeline over the whole book. This can take a while on a large book.",
+			fields: [
+				{
+					name: "externalLinks",
+					label: "Check external links (slower; skips the validated-links.txt cache misses only)",
+					type: "checkbox",
+					value: true,
+				},
+			],
+			okText: "Run",
+		});
+		if (v === null) return;
+		//-- progress overlay (spinner + elapsed clock) while the child runs
+		const overlay = document.createElement("div");
+		overlay.className = "hb-eb-overlay";
+		overlay.innerHTML = `<div class="hb-eb-dialog hb-eb-busy">
+			<div class="hb-eb-spinner" aria-hidden="true"></div>
+			<div>
+				<div class="hb-eb-dialog-title">Validating book…</div>
+				<div class="hb-eb-dialog-msg">Running <code>hdoc validate</code> — this may take a few minutes.</div>
+				<div class="hb-eb-busy-elapsed" role="status">0:00</div>
+			</div>
+		</div>`;
+		document.body.appendChild(overlay);
+		const started = Date.now();
+		const elapsed_el = overlay.querySelector(".hb-eb-busy-elapsed");
+		const tick = setInterval(() => {
+			const s = Math.floor((Date.now() - started) / 1000);
+			elapsed_el.textContent = `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
+		}, 1000);
+		let r;
+		try {
+			r = await api("POST", "/_edit/validate/book", {
+				externalLinks: !!v.externalLinks,
+			});
+		} finally {
+			clearInterval(tick);
+			overlay.remove();
+		}
+		if (!r.ok || !r.json) {
+			toast((r.json && r.json.error) || "Validation run failed", true);
+			return;
+		}
+		show_results({
+			title: `Book validation — ${r.json.code === 0 ? "PASSED" : "FAILED"} (exit ${r.json.code})`,
+			raw: (r.json.output || "").trim(),
+		});
+	};
+
+	//-- --- TOC operations ---------------------------------------------------
+
+	const op_rename = async (node) => {
+		const v = await dialog({
+			title: "Rename",
+			fields: [{ name: "text", label: "Label", value: node.text }],
+			okText: "Rename",
+		});
+		if (v === null) return;
+		toc_call("/_edit/toc/rename", { id: node.id, text: v.text });
+	};
+
+	//-- --- frontmatter (page header) ---------------------------------------
+	//-- The properties dialog edits the recognized frontmatter keys the
+	//-- viewer/build consume (title, description, layout). Parsing is
+	//-- line-based and only ever touches the managed keys, so any other
+	//-- frontmatter (status, custom keys) survives byte-for-byte.
+
+	const FM_KEYS = ["title", "description", "layout"];
+	const FM_LAYOUTS = [
+		{ value: "", label: "(default — article)" },
+		{ value: "article", label: "article" },
+		{ value: "article-toc", label: "article-toc" },
+		{ value: "article-no-toc", label: "article-no-toc" },
+		{ value: "article-wide", label: "article-wide" },
+	];
+
+	//-- strip YAML quoting from a scalar for display
+	const fm_unquote = (s) => {
+		const t = String(s).trim();
+		if (t.length > 1 && t[0] === "'" && t.endsWith("'")) {
+			return t.slice(1, -1).replace(/''/g, "'");
+		}
+		if (t.length > 1 && t[0] === '"' && t.endsWith('"')) {
+			return t.slice(1, -1).replace(/\\"/g, '"');
+		}
+		return t;
+	};
+
+	//-- quote a value for YAML when it needs it (front-matter parses real YAML)
+	const fm_quote = (s) => {
+		const t = String(s).trim();
+		if (!t) return "''";
+		if (/[:#'"[\]{}|>&*!%@`]|^\s|\s$|^-/.test(t)) {
+			return `'${t.replace(/'/g, "''")}'`;
+		}
+		return t;
+	};
+
+	//-- { values: {key: display value}, present: bool } for the managed keys
+	const fm_read = (content) => {
+		const values = {};
+		for (const k of FM_KEYS) values[k] = "";
+		const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
+		if (!m) return { values, present: false };
+		for (const line of m[1].split(/\r?\n/)) {
+			const lm = line.match(/^([A-Za-z][\w-]*)\s*:\s*(.*)$/);
+			if (lm && FM_KEYS.includes(lm[1])) values[lm[1]] = fm_unquote(lm[2]);
+		}
+		return { values, present: true };
+	};
+
+	//-- apply {key: value} to the content's frontmatter block: replace or
+	//-- append managed lines, drop emptied ones, keep everything else as-is;
+	//-- create the block when absent and something is set
+	const fm_patch = (content, patch) => {
+		const eol = content.includes("\r\n") ? "\r\n" : "\n";
+		const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
+		if (!m) {
+			const lines = FM_KEYS.filter((k) => patch[k]).map(
+				(k) => `${k}: ${fm_quote(patch[k])}`,
+			);
+			if (!lines.length) return content;
+			return `---${eol}${lines.join(eol)}${eol}---${eol}${content}`;
+		}
+		const body = m[1].split(/\r?\n/);
+		const done = new Set();
+		const out = [];
+		for (const line of body) {
+			const lm = line.match(/^([A-Za-z][\w-]*)\s*:/);
+			const key = lm && FM_KEYS.includes(lm[1]) ? lm[1] : null;
+			if (!key) {
+				out.push(line);
+				continue;
+			}
+			done.add(key);
+			if (patch[key]) out.push(`${key}: ${fm_quote(patch[key])}`);
+			//-- empty value → key removed
+		}
+		for (const k of FM_KEYS) {
+			if (!done.has(k) && patch[k]) out.push(`${k}: ${fm_quote(patch[k])}`);
+		}
+		const block = out.length ? `---${eol}${out.join(eol)}${eol}---` : "";
+		const rest = content.slice(m[0].length);
+		if (!block) return rest;
+		return `${block}${eol}${rest}`;
+	};
+
+	const op_props = async (node) => {
+		const is_branch = node.type === "branch";
+		const fields = [{ name: "text", label: "Label", value: node.text }];
+		if (is_branch) {
+			fields.push({
+				name: "expand",
+				label: "Expanded by default",
+				type: "checkbox",
+				value: node.expand === true,
+			});
+		} else {
+			fields.push({
+				name: "link",
+				label: "Link (page path, no extension)",
+				value: node.link || "",
+				browse: browse_page,
+			});
+		}
+		fields.push({
+			name: "newId",
+			label: "Node id",
+			value: node.id,
+			hint: "Letters, numbers, dot, underscore or hyphen. Must be unique.",
+		});
+
+		//-- leaf with a real file: load its frontmatter into the dialog
+		let fm = null;
+		let fm_etag = "";
+		let fm_content = "";
+		if (!is_branch && node.link && node.fileExists) {
+			const clean = node.link.replace(/^\/+/, "");
+			const r = await api(
+				"GET",
+				`/_edit/source?path=${encodeURIComponent(clean)}`,
+			);
+			if (r.ok && r.json && typeof r.json.content === "string") {
+				fm_content = r.json.content;
+				fm_etag = r.json.etag;
+				fm = fm_read(fm_content);
+				fields.push(
+					{ type: "heading", label: "Frontmatter" },
+					{
+						name: "fm_layout",
+						label: "Layout",
+						type: "select",
+						value: fm.values.layout,
+						options: FM_LAYOUTS,
+					},
+					{
+						name: "fm_title",
+						label: "Page title",
+						value: fm.values.title,
+					},
+					{
+						name: "fm_description",
+						label: "Description (search/SEO summary)",
+						value: fm.values.description,
+					},
+				);
+			}
+		}
+
+		const v = await dialog({ title: "Page properties", fields, okText: "Save" });
+		if (v === null) return;
+
+		//-- nav-side changes
+		const body = { id: node.id, text: v.text };
+		if (is_branch) body.expand = !!v.expand;
+		else body.link = v.link;
+		if (v.newId && v.newId !== node.id) body.newId = v.newId;
+		await toc_call("/_edit/toc/update", body);
+
+		//-- frontmatter changes → rewrite the page file (etag-guarded)
+		if (fm) {
+			const patch = {
+				layout: v.fm_layout,
+				title: v.fm_title,
+				description: v.fm_description,
+			};
+			const changed =
+				patch.layout !== fm.values.layout ||
+				patch.title !== fm.values.title ||
+				patch.description !== fm.values.description;
+			if (changed) {
+				const clean = node.link.replace(/^\/+/, "");
+				const next = fm_patch(fm_content, patch);
+				const r = await api(
+					"PUT",
+					`/_edit/source?path=${encodeURIComponent(clean)}`,
+					{ content: next, baseEtag: fm_etag },
+				);
+				if (r.status === 409) {
+					toast(
+						"Frontmatter not saved: the file changed while the dialog was open (unsaved editor changes?)",
+						true,
+					);
+					return;
+				}
+				if (!r.ok) {
+					toast((r.json && r.json.error) || "Frontmatter save failed", true);
+					return;
+				}
+				toast("Frontmatter saved");
+				//-- re-render if it's the page on screen (layout applies live);
+				//-- an open editor still holds the old buffer — its etag check
+				//-- protects against overwriting this change blindly
+				if (clean === logical_path()) nav_to(clean).then(render);
+			}
+		}
+	};
+
+	//-- searchable picker over the book's page files (from /_edit/files);
+	//-- resolves to the page's LINK form (no .md, no /index) or null
+	const pick_page = async () => {
+		const r = await api("GET", "/_edit/files");
+		if (!r.ok || !r.json) {
+			toast((r.json && r.json.error) || "Failed to list pages", true);
+			return null;
+		}
+		const pages = r.json.files.filter((f) => f.kind === "page");
+		return new Promise((resolve) => {
+			const overlay = document.createElement("div");
+			overlay.className = "hb-eb-overlay hb-eb-picker-overlay";
+			const box = document.createElement("div");
+			box.className = "hb-eb-dialog hb-eb-picker";
+			box.innerHTML = `
+				<div class="hb-eb-dialog-title">Choose a page</div>
+				<label class="hb-eb-dialog-field"><input type="text" name="filter" placeholder="Filter…" spellcheck="false" autocomplete="off"/></label>
+				<label class="hb-eb-dialog-check"><input type="checkbox" name="unlinkedOnly"/> Show only unlinked pages</label>
+				<div class="hb-eb-picker-list"></div>
+				<div class="hb-eb-dialog-foot"><button type="button" class="hb-eb-btn" data-act="cancel">Cancel</button></div>`;
+			overlay.appendChild(box);
+			document.body.appendChild(overlay);
+
+			const done = (v) => {
+				overlay.remove();
+				resolve(v);
+			};
+			const list = box.querySelector(".hb-eb-picker-list");
+			const filter_el = box.querySelector('[name="filter"]');
+			const unlinked_el = box.querySelector('[name="unlinkedOnly"]');
+			const render_list = () => {
+				const q = filter_el.value.trim().toLowerCase();
+				list.innerHTML = "";
+				for (const p of pages) {
+					if (unlinked_el.checked && p.linked) continue;
+					if (q && !p.file.toLowerCase().includes(q)) continue;
+					const row = document.createElement("div");
+					row.className = "hb-eb-row";
+					row.innerHTML = `<span class="hb-eb-icon"><i class="bi bi-file-earmark-text"></i></span>`;
+					const label = document.createElement("span");
+					label.className = "hb-eb-label";
+					label.textContent = p.file;
+					row.appendChild(label);
+					if (!p.linked) {
+						const b = document.createElement("span");
+						b.className = "hb-eb-badge hb-eb-badge-orphan";
+						b.textContent = "unlinked";
+						row.appendChild(b);
+					}
+					row.addEventListener("click", () =>
+						done(file_logical(p.file)),
+					);
+					list.appendChild(row);
+				}
+				if (!list.children.length) {
+					list.innerHTML = '<div class="hb-eb-empty">No matching pages</div>';
+				}
+			};
+			filter_el.addEventListener("input", render_list);
+			unlinked_el.addEventListener("change", render_list);
+			box
+				.querySelector('[data-act="cancel"]')
+				.addEventListener("click", () => done(null));
+			overlay.addEventListener("mousedown", (e) => {
+				if (e.target === overlay) done(null);
+			});
+			box.addEventListener("keydown", (e) => {
+				if (e.key === "Escape") {
+					e.stopPropagation();
+					done(null);
+				}
+			});
+			render_list();
+			filter_el.focus();
+		});
+	};
+
+	//-- browse callback shared by the Add page / Properties link fields:
+	//-- picks an existing page and fills the input (and an empty Label
+	//-- field, title-cased from the file stem)
+	const browse_page = async (input, box) => {
+		const link = await pick_page();
+		if (!link) return;
+		input.value = link;
+		const text_el = box.querySelector('[name="text"]');
+		if (text_el && !text_el.value.trim()) {
+			text_el.value = (link.split("/").pop() || "")
+				.split("-")
+				.filter(Boolean)
+				.map((w) => w[0].toUpperCase() + w.slice(1))
+				.join(" ");
+		}
+		input.focus();
+	};
+
+	//-- where: { parentId, index } insertion point
+	const op_add_page = async (where) => {
+		const v = await dialog({
+			title: "Add page",
+			fields: [
+				{ name: "text", label: "Label", value: "" },
+				{
+					name: "link",
+					label: "Page path (no extension)",
+					value: "",
+					placeholder: `${docid()}/section/my-page`,
+					hint: "Kebab-case path inside the book folder. Browse to link an existing page.",
+					browse: browse_page,
+				},
+				{
+					name: "createFile",
+					label: "Create the markdown file if it does not exist",
+					type: "checkbox",
+					value: true,
+				},
+			],
+			okText: "Add",
+		});
+		if (v === null) return;
+		const link = String(v.link || "").replace(/^\/+/, "").replace(/\.md$/i, "");
+		if (!link) {
+			toast("A page path is required", true);
+			return;
+		}
+		const r = await toc_call("/_edit/toc/create", {
+			parentId: where.parentId,
+			index: where.index,
+			text: v.text,
+			link,
+			createFile: !!v.createFile,
+		});
+		//-- expand the parent so the new page is visible
+		if (r && where.parentId) {
+			expanded.add(where.parentId);
+			render();
+		}
+	};
+
+	const op_add_section = async (where) => {
+		const v = await dialog({
+			title: "Add section",
+			fields: [{ name: "text", label: "Label", value: "" }],
+			okText: "Add",
+		});
+		if (v === null) return;
+		const r = await toc_call("/_edit/toc/add-section", {
+			parentId: where.parentId,
+			index: where.index,
+			text: v.text,
+		});
+		//-- expand the parent so the new (empty) section is visible
+		if (r && where.parentId) {
+			expanded.add(where.parentId);
+			render();
+		}
+	};
+
+	const op_delete = async (node) => {
+		const fields = [];
+		if (node.type === "leaf" && node.fileExists) {
+			fields.push({
+				name: "deleteFile",
+				label: `Also delete the page file (${node.file})`,
+				type: "checkbox",
+				value: false,
+			});
+		}
+		const v = await dialog({
+			title: "Remove from contents",
+			message:
+				node.type === "branch"
+					? `Remove section "${node.text}" and everything inside it from the navigation? Page files stay on disk (find them under Files).`
+					: `Remove "${node.text}" from the navigation only — its markdown file stays on disk${node.fileExists ? " unless ticked below" : ""}.`,
+			fields,
+			okText: "Remove",
+			danger: true,
+		});
+		if (v === null) return;
+		const r = await toc_call(
+			`/_edit/toc/${encodeURIComponent(node.id)}`,
+			{ deleteFile: !!v.deleteFile },
+			"DELETE",
+		);
+		if (r && r.fileDeleted) toast(`Deleted ${node.file}`);
+	};
+
+	const op_move_step = (node, dir) => {
+		const idx = toc_index().get(node.id);
+		if (!idx) return;
+		const to = idx.index + dir;
+		if (to < 0 || to >= idx.siblings.length) return;
+		toc_call("/_edit/toc/move", { id: node.id, parentId: idx.parentId, index: to });
+	};
+
+	//-- --- Contents tree rendering -----------------------------------------
+
+	const node_row = (n, depth, idx_map) => {
+		const row = document.createElement("div");
+		row.className = "hb-eb-row";
+		row.dataset.id = n.id;
+		row.draggable = true;
+		row.style.paddingLeft = `${8 + depth * 14}px`;
+
+		const is_branch = n.type === "branch";
+		const open = expanded.has(n.id);
+		const caret = document.createElement("span");
+		caret.className = "hb-eb-caret";
+		caret.innerHTML = is_branch
+			? `<i class="bi ${open ? "bi-chevron-down" : "bi-chevron-right"}"></i>`
+			: "";
+		row.appendChild(caret);
+
+		const icon = document.createElement("span");
+		icon.className = "hb-eb-icon";
+		icon.innerHTML = is_branch
+			? '<i class="bi bi-folder2"></i>'
+			: '<i class="bi bi-file-earmark-text"></i>';
+		row.appendChild(icon);
+
+		const label = document.createElement("span");
+		label.className = "hb-eb-label";
+		label.innerHTML = `<span class="hb-eb-num">${esc_html(n.number)}</span> ${esc_html(n.text || "(untitled)")}`;
+		row.appendChild(label);
+
+		if (n.draft) {
+			const b = document.createElement("span");
+			b.className = "hb-eb-badge hb-eb-badge-draft";
+			b.textContent = "draft";
+			row.appendChild(b);
+		}
+		if (n.type === "leaf" && n.link && !n.fileExists) {
+			const b = document.createElement("span");
+			b.className = "hb-eb-badge hb-eb-badge-missing";
+			b.title = `File not found: ${n.file}`;
+			b.textContent = "missing";
+			row.appendChild(b);
+		}
+		//-- links may carry a leading slash in hdocbook.json — normalize
+		if (
+			n.type === "leaf" &&
+			n.link &&
+			n.link.replace(/^\/+/, "") === logical_path()
+		) {
+			row.classList.add("hb-eb-current");
+		}
+
+		//-- validation marker from the last nav validate
+		const probs = nav_problems.get(n.id);
+		if (probs && probs.length) {
+			const b = document.createElement("span");
+			b.className = "hb-eb-badge hb-eb-badge-problem";
+			b.textContent = String(probs.length);
+			b.title = probs.join("\n");
+			b.addEventListener("click", (e) => {
+				e.stopPropagation();
+				show_results({
+					title: `Navigation problems — ${n.text || n.id}`,
+					sections: [
+						{ label: "Problems", cls: "hb-eb-res-err", items: probs },
+					],
+				});
+			});
+			row.appendChild(b);
+		}
+
+		const menu = document.createElement("button");
+		menu.type = "button";
+		menu.className = "hb-eb-menu";
+		menu.title = "Actions";
+		menu.innerHTML = '<i class="bi bi-three-dots"></i>';
+		row.appendChild(menu);
+
+		//-- interactions
+		const toggle = () => {
+			if (expanded.has(n.id)) expanded.delete(n.id);
+			else expanded.add(n.id);
+			render();
+		};
+		caret.addEventListener("click", (e) => {
+			e.stopPropagation();
+			if (is_branch) toggle();
+		});
+		row.addEventListener("click", () => {
+			if (is_branch) toggle();
+			else if (n.link) {
+				//-- reopen the editor even when the path didn't change (the
+				//-- nav-hook reopen only fires on an actual navigation)
+				nav_to(n.link).then(() => {
+					render();
+					open_editor_soon();
+				});
+			}
+		});
+		const open_menu = (x, y) => {
+			const loc = idx_map.get(n.id);
+			const items = [];
+			if (!is_branch && n.link) {
+				items.push({
+					label: "Open",
+					icon: "bi-box-arrow-in-right",
+					onClick: () => nav_to(n.link).then(render),
+				});
+			}
+			if (!is_branch && n.link && n.fileExists) {
+				items.push({
+					label: "Validate page…",
+					icon: "bi-check2-circle",
+					onClick: () => op_validate_page(n.link, n.text),
+				});
+			}
+			items.push(
+				{ label: "Rename…", icon: "bi-input-cursor-text", onClick: () => op_rename(n) },
+				{ label: "Properties…", icon: "bi-sliders", onClick: () => op_props(n) },
+				{
+					label: n.draft ? "Clear draft flag" : "Mark as draft",
+					icon: "bi-pencil-square",
+					onClick: () =>
+						toc_call("/_edit/toc/draft", { id: n.id, draft: !n.draft }),
+				},
+				{ sep: true },
+				{
+					label: is_branch ? "Add page inside…" : "Add page after…",
+					icon: "bi-file-earmark-plus",
+					onClick: () =>
+						op_add_page(
+							is_branch
+								? { parentId: n.id, index: undefined }
+								: { parentId: loc.parentId, index: loc.index + 1 },
+						),
+				},
+				{
+					label: is_branch ? "Add section inside…" : "Add section after…",
+					icon: "bi-folder-plus",
+					onClick: () =>
+						op_add_section(
+							is_branch
+								? { parentId: n.id, index: undefined }
+								: { parentId: loc.parentId, index: loc.index + 1 },
+						),
+				},
+				{ sep: true },
+				{
+					label: "Move up",
+					icon: "bi-arrow-up",
+					onClick: () => op_move_step(n, -1),
+				},
+				{
+					label: "Move down",
+					icon: "bi-arrow-down",
+					onClick: () => op_move_step(n, +1),
+				},
+				{ sep: true },
+				{
+					label: "Remove from contents…",
+					icon: "bi-trash",
+					danger: true,
+					onClick: () => op_delete(n),
+				},
+			);
+			show_ctx(x, y, items);
+		};
+		menu.addEventListener("click", (e) => {
+			e.stopPropagation();
+			const r = menu.getBoundingClientRect();
+			open_menu(r.left, r.bottom + 2);
+		});
+		row.addEventListener("contextmenu", (e) => {
+			if (e.shiftKey) return;
+			e.preventDefault();
+			e.stopPropagation();
+			open_menu(e.clientX, e.clientY);
+		});
+
+		//-- drag & drop move
+		row.addEventListener("dragstart", (e) => {
+			drag_id = n.id;
+			e.dataTransfer.effectAllowed = "move";
+			try {
+				e.dataTransfer.setData("text/plain", n.id);
+			} catch {
+				/* IE-era quirk */
+			}
+			row.classList.add("hb-eb-dragging");
+		});
+		row.addEventListener("dragend", () => {
+			drag_id = null;
+			row.classList.remove("hb-eb-dragging");
+			clear_drop_marks();
+		});
+		row.addEventListener("dragover", (e) => {
+			if (!drag_id || drag_id === n.id) return;
+			e.preventDefault();
+			e.dataTransfer.dropEffect = "move";
+			row.classList.remove(
+				"hb-eb-drop-before",
+				"hb-eb-drop-after",
+				"hb-eb-drop-into",
+			);
+			row.classList.add(`hb-eb-drop-${drop_zone(e, row, is_branch)}`);
+		});
+		row.addEventListener("dragleave", () => {
+			row.classList.remove(
+				"hb-eb-drop-before",
+				"hb-eb-drop-after",
+				"hb-eb-drop-into",
+			);
+		});
+		row.addEventListener("drop", (e) => {
+			e.preventDefault();
+			e.stopPropagation();
+			const zone = drop_zone(e, row, is_branch);
+			clear_drop_marks();
+			do_drop(n, zone, idx_map);
+		});
+
+		return row;
+	};
+
+	const drop_zone = (e, row, is_branch) => {
+		const rect = row.getBoundingClientRect();
+		const y = (e.clientY - rect.top) / rect.height;
+		if (y < 0.3) return "before";
+		if (y > 0.7 || !is_branch) return y > 0.5 ? "after" : is_branch ? "into" : "after";
+		return "into";
+	};
+
+	const clear_drop_marks = () => {
+		if (!host) return;
+		for (const el of host.querySelectorAll(
+			".hb-eb-drop-before,.hb-eb-drop-after,.hb-eb-drop-into",
+		)) {
+			el.classList.remove(
+				"hb-eb-drop-before",
+				"hb-eb-drop-after",
+				"hb-eb-drop-into",
+			);
+		}
+	};
+
+	const do_drop = (target, zone, idx_map) => {
+		if (!drag_id || drag_id === target.id) return;
+		const src = idx_map.get(drag_id);
+		const tgt = idx_map.get(target.id);
+		if (!src || !tgt) return;
+		//-- guard: the drop target must not sit inside the dragged subtree
+		//-- (server rejects "into own subtree" too — fail fast client-side)
+		const subtree_contains = (n, id) =>
+			n.id === id ||
+			(n.type === "branch" && n.children.some((c) => subtree_contains(c, id)));
+		if (subtree_contains(src.node, target.id)) return;
+		let parentId;
+		let index;
+		if (zone === "into") {
+			parentId = target.id;
+			index = target.children.length;
+			expanded.add(target.id);
+		} else {
+			parentId = tgt.parentId;
+			index = tgt.index + (zone === "after" ? 1 : 0);
+			//-- the server inserts AFTER removal: leaving the same parent from
+			//-- an earlier position shifts everything down one
+			if (src.parentId === tgt.parentId && src.index < index) index--;
+		}
+		toc_call("/_edit/toc/move", { id: drag_id, parentId, index });
+	};
+
+	const render_contents = (tree_el) => {
+		if (!toc_dto) {
+			tree_el.innerHTML = '<div class="hb-eb-empty">Loading…</div>';
+			return;
+		}
+		const idx_map = toc_index();
+		const frag = document.createDocumentFragment();
+		const walk = (nodes, depth) => {
+			for (const n of nodes) {
+				frag.appendChild(node_row(n, depth, idx_map));
+				if (n.type === "branch" && expanded.has(n.id)) {
+					walk(n.children, depth + 1);
+				}
+			}
+		};
+		walk(toc_dto.tree, 0);
+		if (!toc_dto.tree.length) {
+			const d = document.createElement("div");
+			d.className = "hb-eb-empty";
+			d.textContent = "Navigation is empty — add a page or section.";
+			frag.appendChild(d);
+		}
+		tree_el.innerHTML = "";
+		tree_el.appendChild(frag);
+	};
+
+	//-- --- Files tree -------------------------------------------------------
+
+	//-- nested { name, rel, dirs: [], files: [] } from the flat DTO
+	const files_tree = (file_list) => {
+		const root = { name: files_dto.docId, rel: files_dto.docId, dirs: new Map(), files: [] };
+		const dir_of = (rel) => {
+			//-- rel is docId/a/b — walk/create intermediate dirs
+			const segs = rel.split("/");
+			let cur = root;
+			for (let i = 1; i < segs.length; i++) {
+				const key = segs.slice(0, i + 1).join("/");
+				if (!cur.dirs.has(key)) {
+					cur.dirs.set(key, { name: segs[i], rel: key, dirs: new Map(), files: [] });
+				}
+				cur = cur.dirs.get(key);
+			}
+			return cur;
+		};
+		for (const d of files_dto.dirs) dir_of(d);
+		for (const f of file_list) {
+			const dir = f.file.includes("/")
+				? f.file.slice(0, f.file.lastIndexOf("/"))
+				: f.file;
+			const parent = dir === files_dto.docId ? root : dir_of(dir);
+			parent.files.push(f);
+		}
+		return root;
+	};
+
+	const file_logical = (rel) =>
+		rel.replace(/\.md$/i, "").replace(/\/index$/i, "");
+
+	const open_page_file = (rel) => {
+		nav_to(file_logical(rel)).then(() => {
+			render();
+			open_editor_soon();
+		});
+	};
+
+	const op_new_file = async (dir_rel) => {
+		const v = await dialog({
+			title: "New page file",
+			fields: [
+				{
+					name: "path",
+					label: "File path",
+					value: `${dir_rel}/`,
+					hint: "Kebab-case, ends with .md — e.g. section/my-page.md",
+				},
+			],
+			okText: "Create",
+		});
+		if (v === null) return;
+		let p = String(v.path || "").trim();
+		if (p && !/\.md$/i.test(p)) p += ".md";
+		const stem = p
+			.replace(/\.md$/i, "")
+			.split("/")
+			.pop();
+		const title = (stem || "New Page")
+			.split("-")
+			.filter(Boolean)
+			.map((w) => w[0].toUpperCase() + w.slice(1))
+			.join(" ");
+		const r = await api("POST", "/_edit/files", {
+			path: p,
+			content: `# ${title}\n`,
+		});
+		if (!r.ok || !r.json) {
+			toast((r.json && r.json.error) || "Create failed", true);
+			return;
+		}
+		files_dto = { docId: r.json.docId, dirs: r.json.dirs, files: r.json.files };
+		render();
+		toast(`Created ${r.json.created}`);
+	};
+
+	const op_new_folder = async (dir_rel) => {
+		const v = await dialog({
+			title: "New folder",
+			fields: [
+				{ name: "path", label: "Folder path", value: `${dir_rel}/` },
+			],
+			okText: "Create",
+		});
+		if (v === null) return;
+		const r = await api("POST", "/_edit/files/folder", { path: v.path });
+		if (!r.ok || !r.json) {
+			toast((r.json && r.json.error) || "Create failed", true);
+			return;
+		}
+		files_dto = { docId: r.json.docId, dirs: r.json.dirs, files: r.json.files };
+		render();
+	};
+
+	//-- --- image uploads ----------------------------------------------------
+	//-- OS-drag images onto a folder row (or its "Upload images here…" menu
+	//-- item) to add them to the book — mirrors the `hdoc edit` Files panel.
+
+	const IMG_RE = /\.(png|jpe?g|gif|svg|webp|bmp|ico|avif)$/i;
+
+	const pick_images = () =>
+		new Promise((resolve) => {
+			const inp = document.createElement("input");
+			inp.type = "file";
+			inp.multiple = true;
+			inp.accept = "image/*";
+			inp.onchange = () => resolve(inp.files);
+			inp.click();
+		});
+
+	const upload_images = async (folder_rel, files) => {
+		const imgs = Array.from(files || []).filter(
+			(f) => (f.type || "").startsWith("image/") || IMG_RE.test(f.name),
+		);
+		if (!imgs.length) {
+			toast("Only image files can be uploaded", true);
+			return;
+		}
+		try {
+			for (const f of imgs) {
+				const r = await fetch(
+					`/_edit/upload?path=${encodeURIComponent(`${folder_rel}/${f.name}`)}`,
+					{
+						method: "PUT",
+						headers: {
+							"content-type": f.type || "application/octet-stream",
+						},
+						body: f,
+					},
+				);
+				const json = await r.json().catch(() => null);
+				if (!r.ok || !json || !json.ok) {
+					throw new Error((json && json.error) || "Upload failed");
+				}
+			}
+			toast(`Uploaded ${imgs.length} image${imgs.length > 1 ? "s" : ""} to ${folder_rel}/`);
+			load_files();
+		} catch (e) {
+			toast(String((e && e.message) || e), true);
+		}
+	};
+
+	const op_delete_file = async (f) => {
+		const v = await dialog({
+			title: "Delete file",
+			message: `Permanently delete ${f.file}?${f.linked ? " It is linked from the contents tree." : ""}`,
+			okText: "Delete",
+			danger: true,
+		});
+		if (v === null) return;
+		const r = await api("DELETE", "/_edit/files", { path: f.file });
+		if (!r.ok || !r.json) {
+			toast((r.json && r.json.error) || "Delete failed", true);
+			return;
+		}
+		files_dto = { docId: r.json.docId, dirs: r.json.dirs, files: r.json.files };
+		render();
+		//-- a linked page's leaf now points at a missing file
+		if (f.linked) load_toc();
+		toast(`Deleted ${f.file}`);
+	};
+
+	//-- in-app image preview (the `hdoc edit` ImagePreview modal): the image,
+	//-- its reference, and "Insert into open page"
+	const show_image_preview = (f) => {
+		const overlay = document.createElement("div");
+		overlay.className = "hb-eb-overlay";
+		const box = document.createElement("div");
+		box.className = "hb-eb-dialog hb-eb-imgprev";
+		const alt = (f.file.split("/").pop() || "").replace(/\.[^.]+$/, "");
+		const reference = `![${alt}](/_books/${f.file})`;
+		const can_insert =
+			!!window.HdocEditInline && window.HdocEditInline.isOpen();
+		box.innerHTML = `
+			<div class="hb-eb-dialog-title">${esc_html(f.file.split("/").pop())}</div>
+			<div class="hb-eb-imgprev-frame"><img src="/_books/${esc_html(f.file)}" alt="${esc_html(alt)}"/></div>
+			<div class="hb-eb-imgprev-ref"><code>${esc_html(reference)}</code></div>
+			<div class="hb-eb-dialog-foot">
+				<button type="button" class="hb-eb-btn hb-eb-btn-primary" data-act="insert" ${can_insert ? "" : "disabled"} title="${can_insert ? "Insert at the cursor in the open page" : "Open a page in the editor first"}">Insert into open page</button>
+				<button type="button" class="hb-eb-btn" data-act="copy">Copy reference</button>
+				<button type="button" class="hb-eb-btn" data-act="close">Close</button>
+			</div>`;
+		overlay.appendChild(box);
+		document.body.appendChild(overlay);
+		const done = () => overlay.remove();
+		box.querySelector('[data-act="insert"]').addEventListener("click", () => {
+			if (window.HdocEditInline && window.HdocEditInline.insert(reference)) {
+				done();
+			} else {
+				toast("Open a page in the editor first", true);
+			}
+		});
+		box.querySelector('[data-act="copy"]').addEventListener("click", () => {
+			try {
+				navigator.clipboard.writeText(reference);
+				toast("Reference copied");
+			} catch {
+				toast("Clipboard unavailable", true);
+			}
+		});
+		box.querySelector('[data-act="close"]').addEventListener("click", done);
+		overlay.addEventListener("mousedown", (e) => {
+			if (e.target === overlay) done();
+		});
+		box.setAttribute("tabindex", "-1");
+		box.addEventListener("keydown", (e) => {
+			if (e.key === "Escape") done();
+		});
+		box.focus();
+	};
+
+	const file_row = (f, depth) => {
+		const row = document.createElement("div");
+		row.className = "hb-eb-row";
+		row.style.paddingLeft = `${8 + depth * 14}px`;
+		const icons = { page: "bi-file-earmark-text", image: "bi-image", other: "bi-file-earmark" };
+		row.innerHTML = `<span class="hb-eb-caret"></span><span class="hb-eb-icon"><i class="bi ${icons[f.kind]}"></i></span>`;
+		const label = document.createElement("span");
+		label.className = "hb-eb-label";
+		label.textContent = f.file.split("/").pop();
+		row.appendChild(label);
+		if (f.kind === "page" && !f.linked) {
+			const b = document.createElement("span");
+			b.className = "hb-eb-badge hb-eb-badge-orphan";
+			b.title = "Not linked from the contents tree";
+			b.textContent = "unlinked";
+			row.appendChild(b);
+		}
+		const menu = document.createElement("button");
+		menu.type = "button";
+		menu.className = "hb-eb-menu";
+		menu.title = "Actions";
+		menu.innerHTML = '<i class="bi bi-three-dots"></i>';
+		row.appendChild(menu);
+
+		//-- images drag into the open editor to insert a reference — same
+		//-- custom dataTransfer type `hdoc edit` uses for its Files tree
+		if (f.kind === "image") {
+			row.draggable = true;
+			row.addEventListener("dragstart", (e) => {
+				e.dataTransfer.setData("application/x-hdoc-image", f.file);
+				e.dataTransfer.effectAllowed = "copy";
+			});
+		}
+
+		row.addEventListener("click", () => {
+			//-- non-page assets are only served under /_books/*
+			if (f.kind === "page") open_page_file(f.file);
+			else if (f.kind === "image") show_image_preview(f);
+			else window.open(`/_books/${f.file}`, "_blank");
+		});
+		const open_menu = (x, y) => {
+			const items = [];
+			if (f.kind === "page") {
+				items.push(
+					{
+						label: "Open in editor",
+						icon: "bi-pencil",
+						onClick: () => open_page_file(f.file),
+					},
+					{
+						label: "Validate page…",
+						icon: "bi-check2-circle",
+						onClick: () =>
+							op_validate_page(file_logical(f.file), f.file),
+					},
+				);
+			} else {
+				if (f.kind === "image") {
+					items.push({
+						label: "Preview",
+						icon: "bi-eye",
+						onClick: () => show_image_preview(f),
+					});
+				}
+				items.push({
+					label: "Open in new tab",
+					icon: "bi-box-arrow-up-right",
+					onClick: () => window.open(`/_books/${f.file}`, "_blank"),
+				});
+			}
+			if (
+				f.kind === "image" &&
+				window.HdocEditInline &&
+				window.HdocEditInline.isOpen()
+			) {
+				items.push({
+					label: "Insert into open page",
+					icon: "bi-file-earmark-image",
+					onClick: () => {
+						const alt = (f.file.split("/").pop() || "").replace(
+							/\.[^.]+$/,
+							"",
+						);
+						if (
+							!window.HdocEditInline.insert(
+								`![${alt}](/_books/${f.file})`,
+							)
+						) {
+							toast("Open a page in the editor first", true);
+						}
+					},
+				});
+			}
+			items.push(
+				{ sep: true },
+				{
+					label: "Delete…",
+					icon: "bi-trash",
+					danger: true,
+					onClick: () => op_delete_file(f),
+				},
+			);
+			show_ctx(x, y, items);
+		};
+		menu.addEventListener("click", (e) => {
+			e.stopPropagation();
+			const r = menu.getBoundingClientRect();
+			open_menu(r.left, r.bottom + 2);
+		});
+		row.addEventListener("contextmenu", (e) => {
+			if (e.shiftKey) return;
+			e.preventDefault();
+			e.stopPropagation();
+			open_menu(e.clientX, e.clientY);
+		});
+		return row;
+	};
+
+	const folder_row = (dir, depth, forced_open) => {
+		const row = document.createElement("div");
+		row.className = "hb-eb-row";
+		row.style.paddingLeft = `${8 + depth * 14}px`;
+		const open = forced_open || fexpanded.has(dir.rel);
+		row.innerHTML = `<span class="hb-eb-caret"><i class="bi ${open ? "bi-chevron-down" : "bi-chevron-right"}"></i></span><span class="hb-eb-icon"><i class="bi bi-folder2"></i></span>`;
+		const label = document.createElement("span");
+		label.className = "hb-eb-label";
+		label.textContent = dir.name;
+		row.appendChild(label);
+		const menu = document.createElement("button");
+		menu.type = "button";
+		menu.className = "hb-eb-menu";
+		menu.title = "Actions";
+		menu.innerHTML = '<i class="bi bi-three-dots"></i>';
+		row.appendChild(menu);
+
+		row.addEventListener("click", () => {
+			if (fexpanded.has(dir.rel)) fexpanded.delete(dir.rel);
+			else fexpanded.add(dir.rel);
+			render();
+		});
+		menu.addEventListener("click", (e) => {
+			e.stopPropagation();
+			const r = menu.getBoundingClientRect();
+			show_ctx(r.left, r.bottom + 2, [
+				{
+					label: "New page here…",
+					icon: "bi-file-earmark-plus",
+					onClick: () => op_new_file(dir.rel),
+				},
+				{
+					label: "New folder here…",
+					icon: "bi-folder-plus",
+					onClick: () => op_new_folder(dir.rel),
+				},
+				{
+					label: "Upload images here…",
+					icon: "bi-upload",
+					onClick: async () =>
+						upload_images(dir.rel, await pick_images()),
+				},
+			]);
+		});
+
+		//-- OS-file drop target: drag images from Explorer/Finder onto a
+		//-- folder to upload them there
+		row.addEventListener("dragover", (e) => {
+			const t = e.dataTransfer && e.dataTransfer.types;
+			if (t && t.includes("Files")) {
+				e.preventDefault();
+				e.dataTransfer.dropEffect = "copy";
+				row.classList.add("hb-eb-drop-into");
+			}
+		});
+		row.addEventListener("dragleave", () => {
+			row.classList.remove("hb-eb-drop-into");
+		});
+		row.addEventListener("drop", (e) => {
+			row.classList.remove("hb-eb-drop-into");
+			if (e.dataTransfer && e.dataTransfer.files.length) {
+				e.preventDefault();
+				e.stopPropagation();
+				upload_images(dir.rel, e.dataTransfer.files);
+			}
+		});
+		return row;
+	};
+
+	const render_files = (tree_el) => {
+		if (!files_dto) {
+			tree_el.innerHTML = '<div class="hb-eb-empty">Loading…</div>';
+			load_files();
+			return;
+		}
+		const filtered = files_unlinked_only
+			? files_dto.files.filter((f) => f.kind === "page" && !f.linked)
+			: files_dto.files;
+		const root = files_tree(filtered);
+		//-- when filtering, hide folders with no matches anywhere below
+		const has_content = (dir) => {
+			if (dir.files.length) return true;
+			for (const [, sub] of dir.dirs) if (has_content(sub)) return true;
+			return false;
+		};
+		const frag = document.createDocumentFragment();
+		const walk = (dir, depth) => {
+			for (const [, sub] of [...dir.dirs].sort((a, b) =>
+				a[0].localeCompare(b[0]),
+			)) {
+				if (files_unlinked_only && !has_content(sub)) continue;
+				frag.appendChild(folder_row(sub, depth, files_unlinked_only));
+				//-- a filtered view is for finding things — expand everything
+				if (files_unlinked_only || fexpanded.has(sub.rel)) {
+					walk(sub, depth + 1);
+				}
+			}
+			for (const f of dir.files) {
+				frag.appendChild(file_row(f, depth));
+			}
+		};
+		walk(root, 0);
+		if (!frag.children.length) {
+			const d = document.createElement("div");
+			d.className = "hb-eb-empty";
+			d.textContent = files_unlinked_only
+				? "No unlinked pages — every page is in the contents tree."
+				: "No files.";
+			frag.appendChild(d);
+		}
+		tree_el.innerHTML = "";
+		tree_el.appendChild(frag);
+	};
+
+	//-- --- sidebar panel ----------------------------------------------------
+
+	const render = () => {
+		if (!host) return;
+		const tree_el = host.querySelector(".hb-eb-tree");
+		for (const t of host.querySelectorAll(".hb-eb-tab")) {
+			t.classList.toggle("hb-eb-tab-on", t.dataset.tab === tab);
+		}
+		//-- per-tab header actions
+		host.querySelector(".hb-eb-actions-contents").style.display =
+			tab === "contents" ? "" : "none";
+		host.querySelector(".hb-eb-actions-files").style.display =
+			tab === "files" ? "" : "none";
+		if (tab === "contents") render_contents(tree_el);
+		else render_files(tree_el);
+	};
+
+	const build_host = () => {
+		host = document.createElement("div");
+		host.className = "hb-eb-panel";
+		host.innerHTML = `
+			<div class="hb-eb-tabs">
+				<button type="button" class="hb-eb-tab" data-tab="contents">Contents</button>
+				<button type="button" class="hb-eb-tab" data-tab="files">Files</button>
+			</div>
+			<div class="hb-eb-actions hb-eb-actions-contents">
+				<button type="button" class="hb-eb-btn hb-eb-btn-sm" data-act="add-page" title="Add a page at the top level"><i class="bi bi-file-earmark-plus"></i> Page</button>
+				<button type="button" class="hb-eb-btn hb-eb-btn-sm" data-act="add-section" title="Add a section at the top level"><i class="bi bi-folder-plus"></i> Section</button>
+				<button type="button" class="hb-eb-btn hb-eb-btn-sm" data-act="refresh" title="Reload from disk"><i class="bi bi-arrow-clockwise"></i></button>
+				<button type="button" class="hb-eb-btn hb-eb-btn-sm" data-act="validate-nav" title="Validate the navigation tree (targets, casing, spellings)"><i class="bi bi-check2-circle"></i></button>
+				<button type="button" class="hb-eb-btn hb-eb-btn-sm" data-act="validate-book" title="Validate the whole book (full hdoc validate)"><i class="bi bi-clipboard2-check"></i></button>
+			</div>
+			<div class="hb-eb-actions hb-eb-actions-files">
+				<button type="button" class="hb-eb-btn hb-eb-btn-sm" data-act="new-file" title="New page file"><i class="bi bi-file-earmark-plus"></i> Page</button>
+				<button type="button" class="hb-eb-btn hb-eb-btn-sm" data-act="new-folder" title="New folder"><i class="bi bi-folder-plus"></i> Folder</button>
+				<button type="button" class="hb-eb-btn hb-eb-btn-sm" data-act="upload" title="Upload images to the book root (drop onto a folder to target it)"><i class="bi bi-upload"></i></button>
+				<button type="button" class="hb-eb-btn hb-eb-btn-sm" data-act="refresh-files" title="Reload from disk"><i class="bi bi-arrow-clockwise"></i></button>
+				<label class="hb-eb-check-sm" title="Show only pages not linked from the contents tree"><input type="checkbox" data-act="unlinked-only"/> Unlinked</label>
+			</div>
+			<div class="hb-eb-tree"></div>
+			<div class="hb-eb-note">Edit mode — changes save to hdocbook.json and page files on disk.</div>`;
+
+		for (const t of host.querySelectorAll(".hb-eb-tab")) {
+			t.addEventListener("click", () => {
+				tab = t.dataset.tab;
+				render();
+			});
+		}
+		host
+			.querySelector('[data-act="add-page"]')
+			.addEventListener("click", () =>
+				op_add_page({ parentId: null, index: undefined }),
+			);
+		host
+			.querySelector('[data-act="add-section"]')
+			.addEventListener("click", () =>
+				op_add_section({ parentId: null, index: undefined }),
+			);
+		host
+			.querySelector('[data-act="refresh"]')
+			.addEventListener("click", load_toc);
+		host
+			.querySelector('[data-act="validate-nav"]')
+			.addEventListener("click", op_validate_nav);
+		host
+			.querySelector('[data-act="validate-book"]')
+			.addEventListener("click", op_validate_book);
+		host
+			.querySelector('[data-act="new-file"]')
+			.addEventListener("click", () => op_new_file(docid()));
+		host
+			.querySelector('[data-act="new-folder"]')
+			.addEventListener("click", () => op_new_folder(docid()));
+		host
+			.querySelector('[data-act="upload"]')
+			.addEventListener("click", async () =>
+				upload_images(docid(), await pick_images()),
+			);
+		host
+			.querySelector('[data-act="refresh-files"]')
+			.addEventListener("click", load_files);
+		host
+			.querySelector('[data-act="unlinked-only"]')
+			.addEventListener("change", (e) => {
+				files_unlinked_only = e.target.checked;
+				render();
+			});
+	};
+
+	const attach_panel = () => {
+		const aside = document.querySelector("aside.DocSidebar");
+		if (!aside) return false;
+		if (!host) build_host();
+		if (host.parentElement !== aside) aside.prepend(host);
+		render();
+		return true;
+	};
+
+	const detach_panel = () => {
+		if (host) host.remove();
+	};
+
+	//-- --- toolbar toggle ---------------------------------------------------
+
+	const update_button = () => {
+		const btn = document.getElementById("hb-eb-toggle");
+		if (!btn) return;
+		const dark = document.documentElement.classList.contains("dark");
+		btn.classList.toggle("btn-light", !dark);
+		btn.classList.toggle("btn-secondary", dark);
+		btn.classList.toggle("hb-eb-toggle-on", edit_mode);
+		btn.title = edit_mode ? "Leave edit mode" : "Edit mode";
+	};
+
+	const ensure_button = () => {
+		if (document.getElementById("hb-eb-toggle")) {
+			update_button();
+			return;
+		}
+		//-- NOT the first .toolbar-right — that's the search-box wrapper
+		//-- (.toolbar-search-bar) and a button prepended there wraps the
+		//-- search input onto a new line. Target the icon-button group and
+		//-- sit immediately before the AI (MCP) button.
+		const bar = document.querySelector(
+			".toolbar-right:not(.toolbar-search-bar)",
+		);
+		if (!bar) return;
+		const btn = document.createElement("button");
+		btn.type = "button";
+		btn.id = "hb-eb-toggle";
+		btn.className = "me-2 btn btn-sm rounded-circle toolbar-icon-btn";
+		btn.setAttribute("aria-label", "Toggle edit mode");
+		btn.innerHTML = '<i class="bi bi-pencil-square"></i>';
+		btn.addEventListener("click", () => set_edit_mode(!edit_mode));
+		const ai_btn = bar.querySelector(".hb-icon-mcp");
+		if (ai_btn) bar.insertBefore(btn, ai_btn.closest("button"));
+		else bar.prepend(btn);
+		update_button();
+	};
+
+	//-- live sync: the server watches the book folder and pushes external
+	//-- changes (its own writes are hash-suppressed server-side)
+	const start_events = () => {
+		if (es) return;
+		try {
+			es = new EventSource("/_edit/events");
+		} catch {
+			return;
+		}
+		es.onmessage = (ev) => {
+			let msg;
+			try {
+				msg = JSON.parse(ev.data);
+			} catch {
+				return;
+			}
+			if (msg.type === "structure") {
+				//-- hdocbook.json changed externally: fresh tree + Vue nav
+				load_toc();
+				refresh_vue_nav();
+				return;
+			}
+			if (msg.type === "fs") {
+				//-- hand page-level changes to the inline editor (it decides
+				//-- whether the open buffer is affected)
+				window.dispatchEvent(
+					new CustomEvent("hdoc-ext-change", { detail: msg }),
+				);
+				//-- coalesce bursts (git checkout, save-all) into one refresh
+				if (fs_refresh_timer) clearTimeout(fs_refresh_timer);
+				fs_refresh_timer = setTimeout(() => {
+					fs_refresh_timer = null;
+					if (files_dto) load_files();
+					else render();
+					//-- current page changed and no editor holding it → re-render
+					const cur = logical_path();
+					const rel = String(msg.path || "");
+					const cur_md = [`${cur}.md`, `${cur}/index.md`];
+					if (
+						cur_md.includes(rel) &&
+						!(window.HdocEditInline && window.HdocEditInline.isOpen())
+					) {
+						nav_to(cur).then(render);
+					}
+				}, 400);
+			}
+		};
+	};
+
+	const stop_events = () => {
+		if (es) {
+			try {
+				es.close();
+			} catch {
+				/* ignore */
+			}
+			es = null;
+		}
+	};
+
+	const set_edit_mode = (on) => {
+		edit_mode = on;
+		set_pref("hdoc-edit-book-mode", on ? "1" : "0");
+		document.body.classList.toggle("hb-eb-on", on);
+		update_button();
+		close_ctx();
+		if (on) {
+			attach_panel();
+			load_toc();
+			start_events();
+			open_editor_soon();
+		} else {
+			detach_panel();
+			stop_events();
+			if (window.HdocEditInline) window.HdocEditInline.close();
+			refresh_vue_nav();
+		}
+	};
+
+	//-- --- styles -----------------------------------------------------------
+
+	const inject_styles = () => {
+		const css = `
+body.hb-eb-on aside.DocSidebar #DocSidebarNav { display: none !important; }
+.hb-eb-panel {
+	display: flex; flex-direction: column; min-height: 0; flex: 1 1 auto;
+	font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+	font-size: 13px; color: #212529; padding: 6px 4px 0 0;
+}
+html.dark .hb-eb-panel { color: #dee2e6; }
+.hb-eb-tabs { display: flex; gap: 4px; padding: 2px 2px 8px; }
+.hb-eb-tab {
+	flex: 1; border: 1px solid rgba(0,0,0,.15); background: none; color: inherit;
+	border-radius: 6px; padding: 4px 0; cursor: pointer; font-size: 12px; font-weight: 600;
+}
+html.dark .hb-eb-tab { border-color: rgba(255,255,255,.18); }
+.hb-eb-tab-on { background: #ffd777; color: #6b4400; border-color: transparent; }
+html.dark .hb-eb-tab-on { background: #7a5200; color: #ffe2a0; }
+.hb-eb-actions { display: flex; gap: 4px; padding: 0 2px 8px; align-items: center; }
+.hb-eb-check-sm {
+	display: flex; align-items: center; gap: 4px; font-size: 12px;
+	cursor: pointer; margin-left: auto; padding-right: 2px; user-select: none;
+}
+.hb-eb-btn {
+	border: 1px solid rgba(0,0,0,.2); background: none; color: inherit;
+	border-radius: 6px; padding: 5px 14px; cursor: pointer; font-size: 13px;
+}
+html.dark .hb-eb-btn { border-color: rgba(255,255,255,.25); }
+.hb-eb-btn-sm { padding: 3px 8px; font-size: 12px; }
+.hb-eb-btn-primary { background: #ffd777; color: #6b4400; border-color: transparent; font-weight: 600; }
+html.dark .hb-eb-btn-primary { background: #7a5200; color: #ffe2a0; }
+.hb-eb-btn-danger { background: #c62828; color: #fff; border-color: transparent; font-weight: 600; }
+.hb-eb-tree { flex: 1 1 auto; overflow: auto; min-height: 0; padding-bottom: 8px; }
+.hb-eb-row {
+	display: flex; align-items: center; gap: 4px; padding: 3px 4px;
+	border-radius: 5px; cursor: pointer; user-select: none; position: relative;
+	line-height: 1.35; min-width: 0;
+}
+.hb-eb-row:hover { background: rgba(0,0,0,.05); }
+html.dark .hb-eb-row:hover { background: rgba(255,255,255,.07); }
+.hb-eb-current { background: rgba(255,190,60,.18); }
+html.dark .hb-eb-current { background: rgba(255,190,60,.12); }
+.hb-eb-caret { width: 14px; flex: 0 0 14px; font-size: 11px; opacity: .7; text-align: center; }
+.hb-eb-icon { flex: 0 0 auto; opacity: .65; font-size: 12px; }
+.hb-eb-label { flex: 1 1 auto; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.hb-eb-num { opacity: .5; font-size: 11px; margin-right: 2px; }
+.hb-eb-badge {
+	flex: 0 0 auto; font-size: 10px; padding: 0 5px; border-radius: 8px;
+	border: 1px solid transparent; line-height: 16px;
+}
+.hb-eb-badge-draft { background: rgba(108,117,125,.18); color: #6c757d; }
+html.dark .hb-eb-badge-draft { color: #adb5bd; }
+.hb-eb-badge-missing { background: rgba(198,40,40,.12); color: #c62828; }
+html.dark .hb-eb-badge-missing { color: #ff8a80; }
+.hb-eb-badge-orphan { background: rgba(13,110,253,.12); color: #0d6efd; }
+html.dark .hb-eb-badge-orphan { color: #6ea8fe; }
+.hb-eb-badge-problem {
+	background: #c62828; color: #fff; cursor: pointer; font-weight: 700;
+	min-width: 16px; text-align: center;
+}
+html.dark .hb-eb-badge-problem { background: #b23c3c; }
+.hb-eb-menu {
+	flex: 0 0 auto; border: none; background: none; color: inherit; cursor: pointer;
+	opacity: 0; padding: 0 4px; font-size: 14px; line-height: 1;
+}
+.hb-eb-row:hover .hb-eb-menu { opacity: .7; }
+.hb-eb-menu:hover { opacity: 1 !important; }
+.hb-eb-dragging { opacity: .45; }
+.hb-eb-drop-before { box-shadow: inset 0 2px 0 0 #b8860b; }
+.hb-eb-drop-after { box-shadow: inset 0 -2px 0 0 #b8860b; }
+.hb-eb-drop-into { outline: 2px solid #b8860b; outline-offset: -2px; }
+html.dark .hb-eb-drop-before { box-shadow: inset 0 2px 0 0 #ffd777; }
+html.dark .hb-eb-drop-after { box-shadow: inset 0 -2px 0 0 #ffd777; }
+html.dark .hb-eb-drop-into { outline-color: #ffd777; }
+.hb-eb-empty { opacity: .6; padding: 12px 6px; font-size: 12px; }
+.hb-eb-note {
+	flex: 0 0 auto; font-size: 11px; opacity: .55; padding: 6px 4px 10px;
+	border-top: 1px solid rgba(0,0,0,.08);
+}
+html.dark .hb-eb-note { border-top-color: rgba(255,255,255,.08); }
+#hb-eb-toggle.hb-eb-toggle-on { background: #ffd777 !important; color: #6b4400 !important; }
+html.dark #hb-eb-toggle.hb-eb-toggle-on { background: #7a5200 !important; color: #ffe2a0 !important; }
+.hb-eb-ctx {
+	position: fixed; z-index: 3002; padding: 4px; min-width: 190px;
+	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-eb-ctx { background: #23272b; border-color: rgba(255,255,255,.15); }
+.hb-eb-ctx-item {
+	display: block; width: 100%; text-align: left; white-space: nowrap;
+	border: none; background: none; color: #212529; cursor: pointer;
+	padding: 6px 12px; border-radius: 6px; font-size: 13px;
+}
+html.dark .hb-eb-ctx-item { color: #dee2e6; }
+.hb-eb-ctx-item:hover { background: rgba(0,0,0,.06); }
+html.dark .hb-eb-ctx-item:hover { background: rgba(255,255,255,.08); }
+.hb-eb-ctx-item .bi { color: #b8860b; margin-right: 6px; }
+html.dark .hb-eb-ctx-item .bi { color: #ffd777; }
+.hb-eb-ctx-danger, .hb-eb-ctx-danger .bi { color: #c62828 !important; }
+html.dark .hb-eb-ctx-danger, html.dark .hb-eb-ctx-danger .bi { color: #ff8a80 !important; }
+.hb-eb-ctx-sep { height: 1px; margin: 4px 8px; background: rgba(0,0,0,.1); }
+html.dark .hb-eb-ctx-sep { background: rgba(255,255,255,.12); }
+.hb-eb-overlay {
+	position: fixed; inset: 0; z-index: 3100; background: rgba(0,0,0,.35);
+	display: flex; align-items: flex-start; justify-content: center; padding-top: 14vh;
+}
+.hb-eb-dialog {
+	background: #ffffff; color: #212529; border-radius: 10px; padding: 16px 18px;
+	width: min(440px, 92vw); box-shadow: 0 12px 40px rgba(0,0,0,.3);
+	font-family: system-ui, -apple-system, "Segoe UI", sans-serif; font-size: 13px;
+}
+html.dark .hb-eb-dialog { background: #23272b; color: #dee2e6; }
+.hb-eb-dialog-title { font-weight: 700; font-size: 15px; margin-bottom: 10px; }
+.hb-eb-dialog-msg { margin-bottom: 10px; opacity: .85; }
+.hb-eb-dialog-field { display: block; margin-bottom: 10px; }
+.hb-eb-dialog-field span { display: block; font-size: 12px; opacity: .75; margin-bottom: 3px; }
+.hb-eb-dialog-field input, .hb-eb-dialog-field select {
+	width: 100%; box-sizing: border-box; padding: 6px 8px; border-radius: 6px;
+	border: 1px solid rgba(0,0,0,.25); background: none; color: inherit; font-size: 13px;
+}
+html.dark .hb-eb-dialog-field input, html.dark .hb-eb-dialog-field select { border-color: rgba(255,255,255,.25); }
+html.dark .hb-eb-dialog-field select option { background: #23272b; }
+.hb-eb-dialog-sect {
+	font-weight: 700; font-size: 12px; text-transform: uppercase; opacity: .6;
+	letter-spacing: .04em; margin: 14px 0 8px;
+	border-top: 1px solid rgba(0,0,0,.1); padding-top: 10px;
+}
+html.dark .hb-eb-dialog-sect { border-top-color: rgba(255,255,255,.1); }
+.hb-eb-dialog-check { display: block; margin: 4px 0 10px; cursor: pointer; }
+/* input-group: input and browse button joined, bootstrap-style. The extra
+   .hb-eb-dialog-field qualifier outranks the generic field-label span rule
+   above (which sets display:block and would drop the button underneath). */
+.hb-eb-dialog-field span.hb-eb-dialog-browse-wrap {
+	display: flex; gap: 0; opacity: 1; font-size: 13px; margin-bottom: 0;
+}
+.hb-eb-dialog-browse-wrap input { flex: 1 1 auto; border-radius: 6px 0 0 6px; }
+.hb-eb-dialog-browse-wrap .hb-eb-btn {
+	flex: 0 0 auto; border-radius: 0 6px 6px 0; border-left: none;
+	border-color: rgba(0,0,0,.25); padding: 3px 10px;
+}
+html.dark .hb-eb-dialog-browse-wrap .hb-eb-btn { border-color: rgba(255,255,255,.25); }
+.hb-eb-picker-overlay { z-index: 3150; }
+.hb-eb-picker-list {
+	max-height: 46vh; overflow: auto; margin-bottom: 8px;
+	border: 1px solid rgba(0,0,0,.12); border-radius: 6px; padding: 4px;
+}
+html.dark .hb-eb-picker-list { border-color: rgba(255,255,255,.14); }
+.hb-eb-imgprev { width: min(720px, 92vw); }
+.hb-eb-imgprev-frame {
+	display: flex; align-items: center; justify-content: center;
+	max-height: 56vh; overflow: auto; margin-bottom: 10px; padding: 10px;
+	border: 1px solid rgba(0,0,0,.12); border-radius: 6px;
+	background:
+		repeating-conic-gradient(rgba(128,128,128,.12) 0% 25%, transparent 0% 50%)
+		0 0 / 20px 20px;
+}
+html.dark .hb-eb-imgprev-frame { border-color: rgba(255,255,255,.14); }
+.hb-eb-imgprev-frame img { max-width: 100%; max-height: 52vh; }
+.hb-eb-imgprev-ref { margin-bottom: 10px; overflow-x: auto; }
+.hb-eb-imgprev-ref code { font-size: 12px; opacity: .8; white-space: nowrap; }
+.hb-eb-results { width: min(760px, 94vw); }
+.hb-eb-results-body { max-height: 62vh; overflow: auto; }
+.hb-eb-results-list { margin: 0 0 6px; padding-left: 20px; font-size: 12.5px; line-height: 1.5; }
+.hb-eb-results-list li { margin-bottom: 3px; overflow-wrap: anywhere; }
+.hb-eb-res-err li { color: #c62828; }
+html.dark .hb-eb-res-err li { color: #ff8a80; }
+.hb-eb-res-warn li { color: #b8860b; }
+html.dark .hb-eb-res-warn li { color: #ffd777; }
+.hb-eb-res-skip li { opacity: .6; }
+.hb-eb-results-raw {
+	font-size: 12px; line-height: 1.5; padding: 10px; border-radius: 6px;
+	background: rgba(0,0,0,.05); overflow-x: auto; white-space: pre-wrap;
+	overflow-wrap: anywhere;
+}
+html.dark .hb-eb-results-raw { background: rgba(255,255,255,.06); }
+.hb-eb-results-ok { padding: 14px 4px; font-size: 14px; color: #2e7d32; }
+html.dark .hb-eb-results-ok { color: #81c784; }
+.hb-eb-results-ok .bi { margin-right: 6px; }
+.hb-eb-busy { display: flex; align-items: center; gap: 16px; }
+.hb-eb-busy .hb-eb-dialog-title { margin-bottom: 4px; }
+.hb-eb-busy .hb-eb-dialog-msg { margin-bottom: 4px; }
+.hb-eb-busy-elapsed { font-size: 12px; opacity: .6; font-variant-numeric: tabular-nums; }
+.hb-eb-spinner {
+	flex: 0 0 auto; width: 34px; height: 34px; border-radius: 50%;
+	border: 4px solid rgba(128,128,128,.25); border-top-color: #b8860b;
+	animation: hb-eb-spin .8s linear infinite;
+}
+html.dark .hb-eb-spinner { border-top-color: #ffd777; }
+@keyframes hb-eb-spin { to { transform: rotate(360deg); } }
+.hb-eb-dialog-hint { font-size: 11px; opacity: .55; margin: -6px 0 10px; }
+.hb-eb-dialog-foot { display: flex; gap: 8px; margin-top: 6px; }
+.hb-eb-toast {
+	position: fixed; bottom: 18px; left: 50%; transform: translateX(-50%);
+	z-index: 3200; background: #212529; color: #f8f9fa; border-radius: 8px;
+	padding: 8px 16px; font-size: 13px; box-shadow: 0 6px 20px rgba(0,0,0,.3);
+	font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+	max-width: 80vw;
+}
+.hb-eb-toast-err { background: #c62828; color: #fff; }
+`;
+		const style = document.createElement("style");
+		style.textContent = css;
+		document.head.appendChild(style);
+	};
+
+	//-- --- init -------------------------------------------------------------
+
+	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 hdoc serve / not loopback */
+		}
+		if (!enabled) return;
+
+		inject_styles();
+
+		//-- small API for the inline editor (js/hdoc-edit-inline.js): its
+		//-- "Insert link to page…" menu item reuses the page picker
+		window.HdocEditBook = { pickPage: pick_page };
+
+		document.addEventListener("click", close_ctx);
+		document.addEventListener("keydown", (ev) => {
+			if (ev.key === "Escape") close_ctx();
+		});
+
+		//-- keep the toolbar button present and the panel attached across Vue
+		//-- re-renders; also highlight the current page as the SPA navigates
+		const ensure = () => {
+			ensure_button();
+			if (edit_mode) attach_panel();
+		};
+		const mo = new MutationObserver(() => {
+			//-- cheap presence checks only — bail out fast when nothing to do
+			if (
+				!document.getElementById("hb-eb-toggle") ||
+				(edit_mode && (!host || !host.isConnected))
+			) {
+				ensure();
+			}
+		});
+		mo.observe(document.body, { childList: true, subtree: true });
+		ensure();
+
+		//-- SPA navigation → refresh the current-page highlight, and while
+		//-- edit mode is on pop the page editor out for the newly opened page
+		//-- (the inline patch's own nav hook closes the previous page's
+		//-- editor first — it registered earlier, so it runs first; the small
+		//-- extra delay keeps the reopen after a dirty-buffer prompt too)
+		let last_nav_path = logical_path();
+		const on_nav = () => {
+			render();
+			const now = logical_path();
+			if (now === last_nav_path) return;
+			last_nav_path = now;
+			const id = docid();
+			if (edit_mode && (now === id || now.startsWith(`${id}/`))) {
+				//-- small delay so the inline patch's own nav hook (which
+				//-- closes the previous page's editor) has run first
+				setTimeout(open_editor_soon, 80);
+			}
+		};
+		window.addEventListener("popstate", () => setTimeout(on_nav, 0));
+		for (const fn of ["pushState", "replaceState"]) {
+			const orig = history[fn].bind(history);
+			history[fn] = (...args) => {
+				const r = orig(...args);
+				setTimeout(on_nav, 0);
+				return r;
+			};
+		}
+
+		//-- restore edit mode from the previous session
+		if (pref("hdoc-edit-book-mode") === "1") {
+			//-- the book UI may not be mounted yet — retry briefly
+			let tries = 0;
+			const arm = setInterval(() => {
+				tries++;
+				if (document.querySelector("aside.DocSidebar")) {
+					clearInterval(arm);
+					set_edit_mode(true);
+				} else if (tries > 50) {
+					clearInterval(arm);
+				}
+			}, 200);
+		}
+	};
+
+	init();
+})();