@helping-ai-workflow/md2doc 3.16.0 → 3.17.0

package/lib/editor/client.js

@@ -988,6 +988,13 @@
   // never reproduce the lockout — any editor that was open is gone by
   // construction the moment the swap happens.
   let activeEditor = null; // { blockEl, hasChanges(), commitNow(), cancelNow() } | null
+  // v3.17.0 T2: the open in-place code edit (editCodeInPlace()), or null.
+  // While it is open its `editor` IS `activeEditor`; liveCodeEdit() is the
+  // reader that also notices a render having ended it.
+  let codeEditState = null;
+  // v3.17.0 T5: the open diagram panel (openDiagramPanel()), or null; its
+  // `editor` is `activeEditor` while it is open, liveDiagramPanel() reads it.
+  let diagramPanelState = null;
 
   // Task 2 (Phase 3): the currently-open always-on WYSIWYG "burst" — at most
   // one paragraph/heading contenteditable surface is being edited at a time,
@@ -1379,8 +1386,31 @@
     // in `lines` (pendingStructure) — unsaved work like an open burst's text.
     // Measured before: a failed split, then the file changed on disk, and
     // onDiskMtime() reloaded the page silently, the split gone.
-    return stack.isDirty() || burstHasUncommittedEdit() || waveUnwrittenEdit || pendingStructure !== null;
+    // v3.17.0 T2 fix round 1 (R47): code typed into an open in-place edit is
+    // unsaved work too — it reaches `lines` only when the edit commits. T5
+    // (R56 (d)): so is the source typed into an open diagram panel.
+    return stack.isDirty() || burstHasUncommittedEdit() || waveUnwrittenEdit || pendingStructure !== null ||
+      codeEditHasUncommittedText() || diagramPanelHasUncommittedText();
+  }
+  // Guarded the way burstHasUncommittedEdit() is: this also runs inside the
+  // beforeunload handler, where a throw would drop the navigation guard.
+  function codeEditHasUncommittedText() {
+    const s = codeEditState;
+    if (!s || activeEditor !== s.editor) return false;
+    try { return s.host.isConnected && s.editor.hasChanges(); } catch (e) { return false; }
+  }
+  // A pure read (v3.17.0 T10): setDirty() asks this on every call, and it used
+  // to dispose a panel its render had taken away as a side effect (fix round 1,
+  // M3). The dispose now lives in reapDiagramPanel(), which both render tails
+  // call just before their setDirty(); the timer and the theme callback reap
+  // lazily through liveDiagramPanel() as they always did.
+  function diagramPanelHasUncommittedText() {
+    try {
+      const s = diagramPanelState;
+      return !!s && activeEditor === s.editor && s.panel.isConnected && s.editor.hasChanges();
+    } catch (e) { return false; }
   }
+  function reapDiagramPanel() { liveDiagramPanel(); }
 
   function setDirty() {
     document.title = (documentIsDirty() ? '● ' : '') + baseTitle;
@@ -2618,6 +2648,9 @@
     hideTableInsertBubbles();
     hideTableAddBars();
     hideTableGrips();
+    reconcileCodeChips(); // v3.17.0 T3
+    reconcileDiagramEditBtn(); // v3.17.0 T4
+    reconcileImageToolbar(); // v3.17.0 T7
     // Task 4 fix (review finding): the SAME reasoning applies to the
     // selection toolbar and its document-level selectionchange listener.
     // Every call site today resolves the session via switchAwayFrom() first
@@ -2816,6 +2849,7 @@
     // every safeRerenderAll() caller the commit landed. Omitting either is the
     // exact silent-failure shape ruling F4 warns about — safeRerenderAll()'s
     // try/catch would swallow a throw and the DOM would still look right.
+    reapDiagramPanel(); // T10: a panel this render took away is disposed here
     setDirty();
     return true;
   }
@@ -2877,6 +2911,9 @@
     hideTableInsertBubbles();
     hideTableAddBars();
     hideTableGrips();
+    reconcileCodeChips(); // v3.17.0 T3
+    reconcileDiagramEditBtn(); // v3.17.0 T4
+    reconcileImageToolbar(); // v3.17.0 T7
     // Task 4 fix (review finding): the SAME reasoning applies to the
     // selection toolbar and its document-level selectionchange listener —
     // whatever WYSIWYG session was open a moment ago just got detached by
@@ -2984,6 +3021,7 @@
         // navigation-rebuild failure break block selection / save / undo.
       }
     }
+    reapDiagramPanel(); // T10: a panel this render took away is disposed here
     setDirty();
     return true;
   }
@@ -4415,11 +4453,18 @@
       return true;
     }
 
+    // v3.17.0 T9a (M-f): a leave by key hands the caret on once it lands
+    // (handCaretOnBelow()); `endLine` is read at the key, as the span it ends.
+    function leaveByKey(leave) {
+      const tail = lines.length - endLine;
+      return leave().then((ok) => { if (ok) handCaretOnBelow(tail); }).catch(showUnexpectedFailure);
+    }
+
     ta.addEventListener('input', () => autoSize(ta));
     ta.addEventListener('keydown', (e) => {
       if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
         e.preventDefault();
-        commit();
+        leaveByKey(commit);
       } else if (e.key === 'Enter' && seed.enterToBody && !e.shiftKey && !e.altKey && !e.isComposing &&
           ta.selectionStart === ta.selectionEnd && ta.value.indexOf('\n') !== -1 &&
           ta.selectionStart <= ta.value.indexOf('\n')) {
@@ -4432,13 +4477,1082 @@
         ta.setSelectionRange(body, body);
       } else if (e.key === 'Escape') {
         e.preventDefault();
-        cancelAndMaybeDiscard();
+        leaveByKey(cancelAndMaybeDiscard);
       }
     });
     commitBtn.addEventListener('click', commit);
     cancelBtn.addEventListener('click', cancelAndMaybeDiscard);
   }
 
+  // ── v3.17.0 T2: a fenced code block edits in place (D1–D5, D10) ────────
+  //
+  // A click on a fenced code block, the "/" / ＋ / toolbar 程式碼 insert, the
+  // ``` shortcut and 轉換成 程式碼 open this instead of the raw box (R21,
+  // R28). The block's own <pre> becomes the editing host (contenteditable and
+  // data-ed-code-edit on the pre, R26) and shows the body only: no fence on
+  // screen. ⠿ MD 原始碼 and Enter on a selected block still open the whole
+  // block, fences included, in the raw box.
+  //
+  // It is an `activeEditor` like the raw box, so switchAwayFrom(), Ctrl+S, a
+  // click elsewhere and the flight guard resolve it the same way. Its commit
+  // keeps the eight obligations of openRawEditor()'s commit() and
+  // cancelAndMaybeDiscard() above (R27), written out again here because those
+  // close over the textarea: the R84 reconcile guard first; an unchanged text
+  // and language is the cancel path (no op, no undo step); a failed render
+  // rolls back and leaves the edit open on its text; a superseded render is
+  // not success yet; `activeEditor` is cleared before any write that detaches
+  // the focused host; a node the patch kept loses its editing attributes;
+  // reanchor() false ends the visual edit too; and an untouched pristine
+  // insert is discarded on the cancel path.
+  //
+  // Keys (D3): Enter = a newline plus the line's indent, Tab / Shift+Tab
+  // indent or dedent by two spaces, Esc and Ctrl/Cmd+Enter commit and leave,
+  // Ctrl/Cmd+Z and Ctrl/Cmd+Y (Ctrl+Shift+Z) step the edit's own TextHistory
+  // (D4): native undo is useless here, a re-colour replaces the host's
+  // children. Undo with nothing left does nothing; it never reaches the
+  // document stack while the edit is open. Ctrl+S commits, saves and opens
+  // the edit again at the same caret (R48, commitCodeEditAndReenter()).
+  const codeEditLib = window.md2docCodeEdit;
+  const CODE_EDIT_TICK_MS = 300;
+
+  // D1: a block of type code whose rendered first child is a <pre> (Mermaid,
+  // Graphviz, math and WaveDrom render something else) and whose first
+  // source line opens a fence (indented code has none).
+  function isFencedCodeBlock(blockEl) {
+    if (!codeEditLib || !blockEl || !blockEl.getAttribute) return false;
+    if (blockEl.getAttribute('data-block-type') !== 'code') return false;
+    const first = blockEl.firstElementChild;
+    if (!first || first.nodeName !== 'PRE') return false;
+    const rec = blockRecOf(blockEl);
+    if (!rec || rec.endLine < rec.startLine) return false;
+    return codeEditLib.parseFence(lines.slice(rec.startLine - 1, rec.endLine)) !== null;
+  }
+
+  // The open edit, or null. A render that replaced the host, or cleared
+  // `activeEditor` for it, has ended it; its timer and listeners go with it.
+  function liveCodeEdit() {
+    const s = codeEditState;
+    if (!s) return null;
+    if (activeEditor === s.editor && s.host.isConnected) return s;
+    codeEditState = null;
+    disposeCodeEdit(s);
+    return null;
+  }
+  function disposeCodeEdit(s) {
+    if (s.timer) { clearTimeout(s.timer); s.timer = null; }
+    s.listeners.abort();
+  }
+
+  function codeEditText(s) { return s.host.textContent; }
+  // [start, end] of the selection as character offsets in the host, or null
+  // when the selection is not inside it.
+  function codeEditSel(s) {
+    const sel = window.getSelection();
+    if (!sel || !sel.rangeCount) return null;
+    const r = sel.getRangeAt(0);
+    if (!s.host.contains(r.startContainer) || !s.host.contains(r.endContainer)) return null;
+    return [offsetInSurface(s.host, r.startContainer, r.startOffset),
+      offsetInSurface(s.host, r.endContainer, r.endOffset)];
+  }
+
+  function codeEditEscape(str) {
+    return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+  }
+  // The host's children for `text`: one <code>, rebuilt every time (so a
+  // Select All + Delete that took it out gets it back), coloured when the
+  // browser highlighter is loaded and knows the language (D5), plain
+  // otherwise. A trailing newline gets a <br> after it, inside the <code>:
+  // a final newline draws no empty line, and both engines then put what is
+  // typed after it BEFORE it (measured; a <br> outside the <code>, which is
+  // display: block while editing, does not help). The <br> is not text —
+  // textContent and the offset helpers skip it.
+  function codeEditHostHtml(text, info) {
+    const hl = window.md2docHljs;
+    let coloured = null;
+    if (hl && typeof hl.highlightCode === 'function') {
+      try { coloured = hl.highlightCode(text, info); } catch (e) { coloured = null; }
+    }
+    return '<code class="language-' + codeEditEscape(info) + (coloured !== null ? ' hljs' : '') + '">' +
+      (coloured !== null ? coloured : codeEditEscape(text)) +
+      (text.charAt(text.length - 1) === '\n' ? '<br data-ed-code-tail="">' : '') + '</code>';
+  }
+  // The one write of the host's children. The host is the focused element
+  // itself and stays in the document, so the write detaches no focused node
+  // (detach census (d); measured: no focus event across a re-colour).
+  function writeCodeEditHost(s, text) {
+    s.host.innerHTML = codeEditHostHtml(text, s.lang);
+    s.shown = text;
+  }
+  function placeCodeEditSelection(s, a, f) {
+    const walker = document.createTreeWalker(s.host, NodeFilter.SHOW_TEXT);
+    if (!walker.nextNode()) {
+      // An empty body: the caret goes inside the <code>, so what is typed
+      // lands in it.
+      const code = s.host.querySelector('code') || s.host;
+      window.getSelection().setBaseAndExtent(code, 0, code, 0);
+      return;
+    }
+    restoreSelection(s.host, a, f === undefined ? a : f);
+  }
+  function setCodeEditText(s, text, a, f) {
+    writeCodeEditHost(s, text);
+    if (document.activeElement === s.host) placeCodeEditSelection(s, a, f);
+    setDirty(); // R47: the dot and the status follow the edit's own text
+  }
+  // D5: re-colour what is there now, the selection put back by offset.
+  function recolourCodeEdit(s) {
+    const text = codeEditText(s);
+    const sel = codeEditSel(s);
+    writeCodeEditHost(s, text);
+    if (sel && document.activeElement === s.host) placeCodeEditSelection(s, sel[0], sel[1]);
+  }
+
+  // D4: a history step at most once per idle tick of typing, and the
+  // re-colour with it — never inside an IME composition (compositionend
+  // starts the tick again).
+  function scheduleCodeEditTick(s) {
+    if (s.timer) clearTimeout(s.timer);
+    s.timer = setTimeout(() => {
+      s.timer = null;
+      if (liveCodeEdit() !== s || s.composing) return;
+      pushCodeEditHistory(s);
+      recolourCodeEdit(s);
+    }, CODE_EDIT_TICK_MS);
+  }
+  function pushCodeEditHistory(s) {
+    const text = codeEditText(s);
+    const sel = codeEditSel(s) || [text.length, text.length];
+    s.history.push({ text, selStart: sel[0], selEnd: sel[1] });
+  }
+  // The typing since the last tick becomes its own step before an action
+  // that makes one of its own (Enter, Tab, paste, undo, a commit).
+  function flushCodeEditTyping(s) {
+    if (s.timer) { clearTimeout(s.timer); s.timer = null; }
+    if (!s.composing) pushCodeEditHistory(s);
+  }
+
+  // The text and selection one edit gives: 'enter' (D3: newline + indent),
+  // 'tab' / 'dedent', 'insert' (`data`), 'backspace'.
+  function codeEditEditResult(s, kind, data) {
+    const text = codeEditText(s);
+    const sel = codeEditSel(s) || [text.length, text.length];
+    if (kind === 'enter') {
+      const n = codeEditLib.newlineWithIndent(text.slice(0, sel[0]) + text.slice(sel[1]), sel[0]);
+      return { text: n.text, selStart: n.caret, selEnd: n.caret };
+    }
+    if (kind === 'insert') {
+      const at = sel[0] + data.length;
+      return { text: text.slice(0, sel[0]) + data + text.slice(sel[1]), selStart: at, selEnd: at };
+    }
+    if (kind === 'backspace') {
+      const from = sel[0] === sel[1] ? Math.max(0, sel[0] - 1) : sel[0];
+      return { text: text.slice(0, from) + text.slice(sel[1]), selStart: from, selEnd: from };
+    }
+    if (kind === 'tab' && sel[0] === sel[1]) {
+      return { text: text.slice(0, sel[0]) + '  ' + text.slice(sel[0]), selStart: sel[0] + 2, selEnd: sel[0] + 2 };
+    }
+    return codeEditLib.indentLines(text, sel[0], sel[1], kind === 'dedent');
+  }
+  function codeEditKeyEdit(s, kind, data) {
+    flushCodeEditTyping(s);
+    const r = codeEditEditResult(s, kind, data);
+    setCodeEditText(s, r.text, r.selStart, r.selEnd);
+    s.history.push({ text: r.text, selStart: r.selStart, selEnd: r.selEnd });
+  }
+  function stepCodeEditHistory(s, dir) {
+    flushCodeEditTyping(s);
+    const snap = dir < 0 ? s.history.undo() : s.history.redo();
+    if (!snap) return; // nothing left: the document stack is never reached from here
+    setCodeEditText(s, snap.text, snap.selStart, snap.selEnd);
+  }
+
+  function onCodeEditKeydown(s, e) {
+    if (e.isComposing || e.keyCode === 229) return;
+    const mod = e.ctrlKey || e.metaKey;
+    const key = e.key;
+    let act = null;
+    if (key === 'Escape' || (key === 'Enter' && mod)) act = 'leave';
+    else if (mod && !e.altKey && !e.shiftKey && (key === 's' || key === 'S')) act = 'save';
+    else if (key === 'Enter' && !e.altKey) act = 'enter';
+    else if (key === 'Tab' && !mod && !e.altKey) act = e.shiftKey ? 'dedent' : 'tab';
+    else if (mod && !e.altKey && !e.shiftKey && (key === 'z' || key === 'Z')) act = 'undo';
+    else if (mod && !e.altKey && ((!e.shiftKey && (key === 'y' || key === 'Y')) ||
+        (e.shiftKey && (key === 'z' || key === 'Z')))) act = 'redo';
+    if (!act) return;
+    e.preventDefault();
+    e.stopPropagation();
+    if (act === 'leave') leaveCodeEdit(s);
+    else if (act === 'save') commitCodeEditAndReenter(s, { save: true }).catch(showUnexpectedFailure);
+    else if (act === 'undo' || act === 'redo') stepCodeEditHistory(s, act === 'undo' ? -1 : 1);
+    else codeEditKeyEdit(s, act);
+  }
+  // v3.17.0 T9a (M-f): every leave (Esc, Ctrl/Cmd+Enter, unchanged or not)
+  // hands the caret on once it lands, as the raw box's does. T9b: resolves
+  // to whether the leave landed (a held Ctrl+S after it saves then).
+  function leaveCodeEdit(s) {
+    const tail = lines.length - s.endLine;
+    return commitCodeEdit(s).then((ok) => { if (ok) handCaretOnBelow(tail, s.blockEl); return ok; })
+      .catch((e) => { showUnexpectedFailure(e); return false; });
+  }
+  // Plain text only, in both contenteditable modes; a paste is one step.
+  function onCodeEditPaste(s, e) {
+    e.preventDefault();
+    e.stopPropagation();
+    const dt = e.clipboardData || window.clipboardData;
+    const text = dt ? dt.getData('text/plain') : '';
+    if (text) codeEditKeyEdit(s, 'insert', text.replace(/\r\n?/g, '\n'));
+  }
+  // D1's 'true' fallback lets markup in where plaintext-only would not: no
+  // formatting command (in either mode), and a dropped text arrives as plain
+  // text at the drop point. A line break from anywhere but the Enter key (a soft keyboard)
+  // is the Enter edit. A dropped FILE is the document's drop handler's, which
+  // inserts it below the block as it did before (R43).
+  function onCodeEditBeforeInput(s, e) {
+    const t = e.inputType || '';
+    if (/^format/.test(t)) { e.preventDefault(); return; }
+    // The browser's own undo (a menu, a gesture) steps the edit's history
+    // too, never the native stack a re-colour has emptied.
+    if (t === 'historyUndo' || t === 'historyRedo') {
+      e.preventDefault();
+      stepCodeEditHistory(s, t === 'historyUndo' ? -1 : 1);
+      return;
+    }
+    if (t === 'insertParagraph' || t === 'insertLineBreak') {
+      e.preventDefault();
+      codeEditKeyEdit(s, 'enter');
+      return;
+    }
+    if (s.plainOnly || t !== 'insertFromDrop') return;
+    e.preventDefault();
+    const text = e.dataTransfer ? e.dataTransfer.getData('text/plain') : '';
+    const ranges = typeof e.getTargetRanges === 'function' ? e.getTargetRanges() : [];
+    if (ranges.length) {
+      window.getSelection().setBaseAndExtent(ranges[0].startContainer, ranges[0].startOffset,
+        ranges[0].endContainer, ranges[0].endOffset);
+    }
+    if (text) codeEditKeyEdit(s, 'insert', text.replace(/\r\n?/g, '\n'));
+  }
+
+  // R41: the caret under a click point, as an offset in the host's text, or
+  // null when the point is not over it.
+  function codeCaretFromPoint(host, x, y) {
+    let node = null;
+    let off = 0;
+    if (typeof document.caretPositionFromPoint === 'function') {
+      const p = document.caretPositionFromPoint(x, y);
+      if (p) { node = p.offsetNode; off = p.offset; }
+    } else if (typeof document.caretRangeFromPoint === 'function') {
+      const r = document.caretRangeFromPoint(x, y);
+      if (r) { node = r.startContainer; off = r.startOffset; }
+    }
+    if (!node || !host.contains(node)) return null;
+    return offsetInSurface(host, node, off);
+  }
+
+  // D5 / R41: the browser highlighter loads on the first edit, never
+  // awaited (the caret and focus are already placed); a load that failed is
+  // not asked for again, and the text stays plain.
+  function ensureCodeHighlighter(s) {
+    if (window.md2docHljs || diagramEngineGaveUp['highlight.js']) return;
+    loadDiagramEngine('highlight.js').then(() => {
+      if (liveCodeEdit() === s && !s.composing) recolourCodeEdit(s);
+    }, () => {});
+  }
+
+  // Opens the edit on `blockEl` with the caret at `opts.offset` (default 0)
+  // or under the click point `opts.clientX/clientY`. false when the block is
+  // not a fenced code block (the caller opens the raw box instead); true
+  // otherwise, including when another session could not be resolved (it
+  // stays open with its banner) or the block went away meanwhile (notice).
+  // Nothing is awaited on the common path, so focus and caret are placed in
+  // the same task as the gesture and the first keys land in the code (R41).
+  async function editCodeInPlace(blockEl, opts) {
+    let o = opts || {};
+    if (!isFencedCodeBlock(blockEl)) return false;
+    const open = liveCodeEdit();
+    if (open && open.blockEl === blockEl) { open.host.focus(); return true; }
+    // openRawEditor()'s Task G guard: resolve every other session BEFORE this
+    // one registers, so the focusout that focusing the host raises finds
+    // nothing to resolve (an untouched just-inserted block would otherwise be
+    // cancelled, and discarded, by its own focus move).
+    // v3.17.0 T9b (R57, T5 M5): and openDiagramPanel()'s blur first, for the
+    // same reason. The language chip's press keeps focus where it was, and a
+    // surface that keeps focus can open its burst again after the
+    // resolution (measured: an empty new paragraph), so its focusout when the
+    // host takes focus below resolved this brand-new, untouched edit — closed
+    // in the gesture that opened it. The blur's own focusout starts that
+    // resolution now, and the switchAwayFrom() below joins it. Only when
+    // something outside the block held focus: a caller that arrives with
+    // focus on BODY (the click router after its press, the Ctrl+S re-entry)
+    // takes the path it took before.
+    const ae = document.activeElement;
+    const blurred = !!(ae && ae !== document.body && !blockEl.contains(ae) && typeof ae.blur === 'function');
+    if (blurred) ae.blur();
+    if ((blurred && switching) || (activeEditor && activeEditor.blockEl !== blockEl) ||
+        (currentBurst && currentBurst.blockEl !== blockEl)) {
+      const ok = await switchAwayFrom();
+      if (!ok) return true;
+      if (!blockEl.isConnected) { showError(DROPPED_GESTURE_MESSAGE, null, null); return true; }
+      if (!isFencedCodeBlock(blockEl)) return false;
+      if (o.clientX !== undefined) o = { offset: 0 }; // that render may have moved the block under the point
+    }
+    const rec = blockRecOf(blockEl);
+    const source = lines.slice(rec.startLine - 1, rec.endLine).join('\n');
+    const fence = codeEditLib.parseFence(source.split('\n'));
+    const host = blockEl.firstElementChild;
+    const body = fence.body.join('\n');
+    let caret = o.clientX !== undefined ? codeCaretFromPoint(host, o.clientX, o.clientY) : null;
+    if (caret === null) caret = o.offset || 0;
+    caret = Math.max(0, Math.min(body.length, caret));
+    const s = {
+      blockEl, host, fence, lang: fence.info, body, source,
+      blockId: rec.id, startLine: rec.startLine, endLine: rec.endLine,
+      history: new codeEditLib.TextHistory({ text: body, selStart: caret, selEnd: caret }),
+      originalHtml: host.innerHTML, shown: null, timer: null, composing: false,
+      plainOnly: true, inflight: null, listeners: new AbortController(), editor: null,
+    };
+    // R23: the session by value in the raw box's shape, for a reconciliation
+    // to reopen: the whole fenced block as it would be committed.
+    s.editor = {
+      blockEl,
+      hasChanges: () => codeEditText(s) !== s.body || s.lang !== s.fence.info,
+      snapshot: () => codeEditSnapshot(s),
+      commitNow: () => commitCodeEdit(s),
+      // D3: leaving keeps what was typed. resolveOpenSession() calls this only
+      // when nothing changed, which is the commit's own cancel path.
+      cancelNow: () => commitCodeEdit(s),
+      reanchor: () => reanchorCodeEdit(s),
+    };
+    s.commit = () => commitCodeEdit(s);
+    s.end = () => endCodeEditVisual(s);
+    s.commitWithLang = (lang) => commitCodeEditWithLang(s, lang);
+    activeEditor = s.editor;
+    codeEditState = s;
+    host.setAttribute('contenteditable', 'plaintext-only');
+    if (host.contentEditable !== 'plaintext-only') {
+      host.setAttribute('contenteditable', 'true');
+      s.plainOnly = false;
+    }
+    host.setAttribute('data-ed-code-edit', '');
+    host.setAttribute('spellcheck', 'false');
+    // The rendered body is kept when it already is exactly the text (no
+    // flash of uncoloured code while the highlighter loads).
+    const code = host.firstElementChild;
+    if (host.childNodes.length === 1 && code && code.nodeName === 'CODE' &&
+        code.textContent === body && body.charAt(body.length - 1) !== '\n') s.shown = body;
+    else writeCodeEditHost(s, body);
+    const on = { signal: s.listeners.signal };
+    host.addEventListener('keydown', (e) => onCodeEditKeydown(s, e), on);
+    host.addEventListener('input', () => { scheduleCodeEditTick(s); setDirty(); }, on);
+    host.addEventListener('compositionstart', () => { s.composing = true; }, on);
+    host.addEventListener('compositionend', () => { s.composing = false; scheduleCodeEditTick(s); }, on);
+    host.addEventListener('paste', (e) => onCodeEditPaste(s, e), on);
+    host.addEventListener('beforeinput', (e) => onCodeEditBeforeInput(s, e), on);
+    host.focus({ preventScroll: o.clientX !== undefined || !!o.keepScroll });
+    placeCodeEditSelection(s, caret, caret);
+    ensureCodeHighlighter(s);
+    showCodeChipsFor(blockEl, true);
+    return true;
+  }
+
+  function codeEditSnapshot(s) {
+    const text = codeEditText(s);
+    const sel = codeEditSel(s);
+    const built = codeEditLib.buildFence({ indent: s.fence.indent, char: s.fence.char, open: s.fence.open,
+      info: s.lang, body: text.split('\n') });
+    return { blockId: s.blockId, range: null, startLine: s.startLine, endLine: s.endLine, source: s.source,
+      value: built.join('\n'), caret: built[0].length + 1 + (sel ? sel[0] : text.length) };
+  }
+
+  // openRawEditor()'s reanchor(), for a session a patch render kept on
+  // screen: the block's id and lines again from the new `blocks`, only while
+  // its lines are still exactly what the edit opened on. Otherwise the edit
+  // ends visually as well (R27 (7)): the caller drops `activeEditor`, and a
+  // host left contenteditable would be an editor nobody resolves.
+  function reanchorCodeEdit(s) {
+    const raw = s.blockEl.getAttribute('data-block-id');
+    const b = raw === null ? null : blocks.find((x) => x.id === Number(raw));
+    if (b && b.endLine >= b.startLine && lines.slice(b.startLine - 1, b.endLine).join('\n') === s.source) {
+      s.blockId = b.id;
+      s.startLine = b.startLine;
+      s.endLine = b.endLine;
+      return true;
+    }
+    endCodeEditVisual(s);
+    return false;
+  }
+
+  // Ends the edit on screen. `activeEditor` is cleared FIRST: taking the
+  // attributes off and writing the host can blur it, and the focusout handler
+  // must find no session to resolve (R1's order, as in restore() above). A
+  // host still on screen gets its rendered HTML from the open back — a node
+  // the patch kept is byte-identical by construction (R27 (6)).
+  function endCodeEditVisual(s) {
+    if (activeEditor === s.editor) activeEditor = null;
+    if (codeEditState === s) codeEditState = null;
+    disposeCodeEdit(s);
+    hideCodeChips();
+    showCodeChipsUnderPointer();
+    const host = s.host;
+    if (host.isConnected && host.hasAttribute('data-ed-code-edit')) {
+      host.removeAttribute('contenteditable');
+      host.removeAttribute('data-ed-code-edit');
+      host.removeAttribute('spellcheck');
+      host.innerHTML = s.originalHtml;
+    }
+    setDirty(); // R47: an edit left unchanged reads clean again
+  }
+
+  // The cancel path: nothing to write. An untouched pristine insert (the
+  // "/" / ＋ / toolbar skeleton) is taken away again, as the raw box's
+  // cancelAndMaybeDiscard() does.
+  async function cancelCodeEdit(s) {
+    const wasPristine = !!(pristineInsert && pristineInsert.blockId === s.blockId);
+    if (wasPristine) pristineInsert = null;
+    endCodeEditVisual(s);
+    if (wasPristine) return await discardPristineInsert();
+    return true;
+  }
+
+  // One commit at a time per session: a second Esc while the render is out
+  // joins the first.
+  function runCodeEditCommit(s) {
+    if (!s.inflight) {
+      s.inflight = commitCodeEditBody(s).then((r) => { s.lastResult = r; return r; })
+        .finally(() => { s.inflight = null; });
+    }
+    return s.inflight;
+  }
+  async function commitCodeEdit(s) {
+    return (await runCodeEditCommit(s)) !== false;
+  }
+  // true, false (the render failed: rolled back, the edit stays open on its
+  // text, the banner is up) or RENDER_SUPERSEDED.
+  async function commitCodeEditBody(s) {
+    if (s.timer) { clearTimeout(s.timer); s.timer = null; }
+    const text = codeEditText(s);
+    // R37: "unchanged" compares the body and the info string with what was
+    // parsed at the open, never rebuilt lines (an unterminated fence rebuilds
+    // with its closing line, which is a repair only when something changed).
+    // Fix round 1 (R49, M1): asked BEFORE the reconcile guard, like the raw
+    // box's cancel path — leaving an untouched edit writes nothing, so it
+    // never starts a reconciliation that would reopen it as a raw box.
+    if (text === s.body && s.lang === s.fence.info) return await cancelCodeEdit(s);
+    if (reconcileBlocksCommits()) {
+      if (!reconcilePromise) startReconcileRender();
+      return false;
+    }
+    // D10: the fence char and the info string are kept; the fence grows past
+    // the longest run of its char in the body.
+    const built = codeEditLib.buildFence({ indent: s.fence.indent, char: s.fence.char, open: s.fence.open,
+      info: s.lang, body: text.split('\n') });
+    const r = await commitFencedRangeAndRender(s.startLine, s.endLine, built.join('\n'));
+    if (r === null) return await cancelCodeEdit(s);
+    if (r === false || r === RENDER_SUPERSEDED) return r;
+    endCodeEditVisual(s);
+    return true;
+  }
+
+  // R27 (2)-(4), shared by the in-place code edit and the diagram panel (T5):
+  // ONE commitRangeEdit over the block's lines and its render. null: nothing
+  // changed (no op, nothing pushed; the caller takes its cancel path). false:
+  // the render failed, the op is rolled back and the caller stays open on its
+  // text. RENDER_SUPERSEDED: not success yet, the caller touches no DOM. true:
+  // rendered.
+  async function commitFencedRangeAndRender(startLine, endLine, text) {
+    const result = commitRangeEdit({ lines, blocks, stack }, startLine, endLine, text);
+    if (result.op === null) return null;
+    const prevLines = lines;
+    lines = result.lines;
+    const editRange = { startLine: Math.min(result.op.startLine, result.op.endLine + 1),
+      endLine: Math.max(result.op.startLine - 1, result.op.endLine),
+      delta: result.op.after.length - result.op.before.length };
+    const ok = await safeRerenderAll(editRange);
+    if (!ok) {
+      lines = rollbackFailedRender({ lines, stack }, result, prevLines);
+      return false;
+    }
+    return ok === RENDER_SUPERSEDED ? RENDER_SUPERSEDED : true;
+  }
+
+  // D7 / R11: the text and the new language as ONE op, then the edit opens
+  // again on the re-rendered block at the same caret offset. T3's language
+  // chip calls this.
+  function commitCodeEditWithLang(s, lang) {
+    return commitCodeEditAndReenter(s, { lang });
+  }
+
+  // Keys typed while commitCodeEditAndReenter()'s render is out, or null.
+  // The host they would go into is the one that render replaces, and focus is
+  // on BODY between the swap and the re-entry, so they are held here —
+  // whatever the target — and replayed into the edit that opens again.
+  // v3.17.0 T9b: until a press puts the caret in a text surface elsewhere
+  // (`clickedAway`, the v3.13.1 rule: an entry a click positioned elsewhere
+  // is not the edit's). From then on nothing is held — keys go where that
+  // press put the caret — and the edit is not opened again over it.
+  let codeEditReenterHold = null; // { keys: [{ kind, data?, key?, … }], clickedAway, passTarget? }
+
+  // R48 (Ctrl+S) and R11 (a language pick): commit through switchAwayFrom()
+  // (the same gate a click elsewhere uses), open the edit again on the block
+  // at the same start line with the caret where it was, put back what was
+  // typed meanwhile, then save when asked. A failed render leaves the edit
+  // open (R27 (3)), and the held keys go into it; a superseded one leaves no
+  // block to open on, so the held keys are dropped with the notice.
+  // v3.17.0 T9b: a held Ctrl+S is a key in that order like the others
+  // (Task 2 re-review: as a flag it reopened the edit after a held Esc).
+  // Ahead of any leave it saves what was typed before it: this runs again on
+  // the reopened edit, `opts.carry` taking the keys after it there. After a
+  // leave it saves once the leave has landed, and the edit stays closed.
+  // Every save from here goes after the one already out
+  // (saveAfterLastSave()), never alongside it. A press that put the caret in
+  // another text surface while the render was out (`clickedAway`) ends the
+  // re-entry: nothing opens again or takes focus back, and keys held before
+  // that press have nowhere to go (the notice).
+  async function commitCodeEditAndReenter(s, opts) {
+    const sel = codeEditSel(s);
+    const caret = sel ? sel[0] : codeEditText(s).length;
+    const startLine = s.startLine;
+    if (opts.lang !== undefined) s.lang = codeEditLib.setFenceLang(s.lang, opts.lang);
+    const hold = { keys: [], clickedAway: false };
+    codeEditReenterHold = hold;
+    let ok;
+    try {
+      ok = await switchAwayFrom();
+    } finally {
+      if (codeEditReenterHold === hold) codeEditReenterHold = null;
+    }
+    const keys = (opts.carry || []).concat(hold.keys);
+    let target = liveCodeEdit() === s ? s : null;
+    if (!target && ok && !hold.clickedAway && s.lastResult !== RENDER_SUPERSEDED) {
+      const el = blockElAtLine(startLine);
+      if (el && await editCodeInPlace(el, { offset: caret, keepScroll: true })) target = liveCodeEdit();
+    }
+    if (ok && opts.save) saveAfterLastSave();
+    if (!target || hold.clickedAway) {
+      if (keys.some((k) => k.kind !== 'save')) showNotice(FLIGHT_DROPPED_MESSAGE);
+      if (ok && keys.some((k) => k.kind === 'save')) saveAfterLastSave();
+      return !!ok;
+    }
+    const next = replayIntoCodeEdit(target, keys);
+    if (next.rest) return commitCodeEditAndReenter(target, { save: true, carry: next.rest });
+    if (next.leave) {
+      const left = leaveCodeEdit(target);
+      if (next.saveAfterLeave) left.then((landed) => { if (landed) saveAfterLastSave(); });
+    }
+    return !!ok;
+  }
+
+  // The hold itself: capture phase on the document, ahead of every other
+  // keydown listener (the host's own included), so a held key changes
+  // nothing on its way. Text keys, Enter, Tab, Backspace, caret moves and a
+  // second Ctrl+S are kept in order; Esc / Ctrl+Enter leave after the replay;
+  // anything else is dropped with the notice. An IME composition is not held
+  // (its keydowns are isComposing): known limit.
+  function wireCodeEditReenterHold() {
+    // v3.17.0 T9b: a press on a text surface (a paragraph, heading, list
+    // item or cell) puts the caret there; the hold stops at it. A press on
+    // anything else (the margin, chrome, a quote or code block) does not
+    // place a caret, and the keys stay held for the edit.
+    document.addEventListener('mousedown', (e) => {
+      const hold = codeEditReenterHold;
+      if (!hold || hold.clickedAway || e.button !== 0) return;
+      const t = e.target;
+      if (t && t.closest && t.closest('.ed-wys-armed, .ed-wys-cell')) hold.clickedAway = true;
+    }, true);
+    document.addEventListener('keydown', (e) => {
+      const hold = codeEditReenterHold;
+      if (!hold || hold.clickedAway || e.isComposing || e.keyCode === 229) return;
+      // v3.17.0 T5: the diagram panel's textarea stays on screen, focused,
+      // while its Ctrl+S render is out; what is typed there is its own (the
+      // panel carries it over). Only keys that land elsewhere are held.
+      if (hold.passTarget && e.target === hold.passTarget) return;
+      if (e.key === 'Shift' || e.key === 'Control' || e.key === 'Alt' || e.key === 'Meta') return;
+      const mod = e.ctrlKey || e.metaKey;
+      let entry;
+      if (e.key === 'Escape' || (e.key === 'Enter' && mod)) entry = { kind: 'leave', esc: e.key === 'Escape' };
+      else if (mod && !e.altKey && !e.shiftKey && (e.key === 's' || e.key === 'S')) entry = { kind: 'save' };
+      else if (e.key === 'Enter' && !e.altKey) entry = { kind: 'enter' };
+      else if (e.key === 'Tab' && !mod && !e.altKey) entry = { kind: e.shiftKey ? 'dedent' : 'tab' };
+      else if (e.key === 'Backspace' && !mod && !e.altKey) entry = { kind: 'backspace' };
+      else if (e.key.length === 1 && !mod && !e.altKey) entry = { kind: 'insert', data: e.key };
+      else if (caretMoveForKey(e)) {
+        entry = { kind: 'move', key: e.key, shiftKey: e.shiftKey, ctrlKey: e.ctrlKey, altKey: e.altKey, metaKey: e.metaKey };
+      } else entry = { kind: 'drop' };
+      e.preventDefault();
+      e.stopImmediatePropagation();
+      if (entry) hold.keys.push(entry);
+    }, true);
+  }
+  // The held keys into the reopened edit, in order, up to the first held
+  // Ctrl+S ahead of any leave: `rest` is what came after it (null when there
+  // was none), for the caller's next round. The caller runs the leave
+  // (`leave`), and a Ctrl+S held after it (`saveAfterLeave`) saves once it
+  // has landed.
+  function replayIntoCodeEdit(s, keys) {
+    let changed = false;
+    let dropped = false;
+    let leave = false;
+    let saveAfterLeave = false;
+    let rest = null;
+    for (let i = 0; i < keys.length; i++) {
+      const k = keys[i];
+      if (k.kind === 'save') {
+        if (leave) { saveAfterLeave = true; continue; }
+        rest = keys.slice(i + 1);
+        break;
+      }
+      if (leave) { dropped = true; continue; }
+      if (k.kind === 'leave') { leave = true; continue; }
+      if (k.kind === 'drop') { dropped = true; continue; }
+      if (k.kind === 'move') {
+        const mv = caretMoveForKey(k);
+        const sel = window.getSelection();
+        if (mv && sel.modify) sel.modify(mv.extend ? 'extend' : 'move', mv.dir, mv.unit);
+        continue;
+      }
+      const r = codeEditEditResult(s, k.kind, k.data);
+      setCodeEditText(s, r.text, r.selStart, r.selEnd);
+      changed = true;
+    }
+    if (changed) pushCodeEditHistory(s);
+    if (dropped) showNotice(FLIGHT_DROPPED_MESSAGE);
+    return { leave, saveAfterLeave, rest };
+  }
+
+  // R28: the keys held while the ``` shortcut's render was out (typed into
+  // the paragraph it replaced) go into the new edit, in order, before the
+  // gesture's flight ends: text as typed, Enter as a newline with the line's
+  // indent, Backspace as one character back. A held Escape or Ctrl/Cmd+Enter
+  // (the `rawBoxOnly` entries, R66 / R68) commits and leaves. The first other
+  // held key stops the drain, and it and the rest of its run are dropped with
+  // the notice; an entry a click positioned elsewhere stops it and is left to
+  // the ordinary flush. One history step for all of it.
+  function drainHeldKeysIntoCodeEdit() {
+    const s = liveCodeEdit();
+    if (!s || document.activeElement !== s.host) return;
+    let changed = false;
+    let leave = false;
+    while (flightBuffer.length) {
+      const en = flightBuffer[0];
+      if (en.pos) break;
+      const plain = en.kind === 'key' && !en.ctrlKey && !en.metaKey && !en.altKey;
+      let r = null;
+      if (en.kind === 'text') r = codeEditEditResult(s, 'insert', en.data);
+      else if (plain && en.key === 'Enter') r = codeEditEditResult(s, 'enter');
+      else if (plain && !en.shiftKey && en.key === 'Backspace') r = codeEditEditResult(s, 'backspace');
+      else if (en.rawBoxOnly) { flightBuffer.shift(); leave = true; break; }
+      else {
+        while (flightBuffer.length && !flightBuffer[0].pos) flightBuffer.shift();
+        showNotice(FLIGHT_DROPPED_MESSAGE);
+        break;
+      }
+      setCodeEditText(s, r.text, r.selStart, r.selEnd);
+      flightBuffer.shift();
+      changed = true;
+    }
+    if (changed) pushCodeEditHistory(s);
+    if (leave) leaveCodeEdit(s);
+  }
+
+  // R25: a target whose keys are its own — the in-place code edit, and the
+  // diagram panel, language menu and image toolbar of the later v3.17.0
+  // tasks. The document keydown handler leaves them alone below Ctrl+S.
+  function ownsOwnKeys(target) {
+    return !!(target && target.closest &&
+      target.closest('[data-ed-code-edit], .ed-diagram-panel, .ed-code-langmenu, .ed-imgtb'));
+  }
+
+  // ── v3.17.0 T3: the language chip and the copy chip (D7–D9, R40) ───────
+  //
+  // One singleton on document.body, never inside .content (anything in there
+  // can end up in the readbacks, the wave button's reason): fixed at the
+  // top-right of the fenced code block the pointer is over, or of the one
+  // being edited. Every press calls preventDefault() on mousedown, so the
+  // edit keeps focus; only the language filter input takes it. A chip click
+  // on a block that is not being edited opens the edit first (focus, caret at
+  // 0), then the menu (R40); picking commits the text and the language as
+  // one op through codeEditState.commitWithLang().
+  const CODE_CHIP_INSET_PX = 6;
+  const CODE_COPY_RESET_MS = 2000;
+  const codeChips = document.createElement('div');
+  codeChips.className = 'ed-code-chips';
+  codeChips.hidden = true;
+  const codeLangBtn = document.createElement('button');
+  codeLangBtn.type = 'button';
+  codeLangBtn.className = 'ed-code-chip ed-code-lang';
+  codeLangBtn.title = '程式碼語言';
+  codeLangBtn.setAttribute('aria-haspopup', 'listbox');
+  codeLangBtn.setAttribute('aria-expanded', 'false');
+  const codeLangLabel = document.createElement('span');
+  codeLangBtn.appendChild(codeLangLabel);
+  const codeCopyBtn = document.createElement('button');
+  codeCopyBtn.type = 'button';
+  codeCopyBtn.className = 'ed-code-chip ed-code-copy';
+  codeChips.appendChild(codeLangBtn);
+  codeChips.appendChild(codeCopyBtn);
+  document.body.appendChild(codeChips);
+  function codeChipIcon(name) { return icons && icons.NAMES.indexOf(name) !== -1 ? icons.svg(name, 14) : ''; }
+  const CODE_COPY_ICON = codeChipIcon('copy');
+  const CODE_COPY_DONE = codeChipIcon('check') + '<span>Copied</span>';
+  const CODE_COPY_KEYS = /Mac|iPhone|iPad/.test(navigator.platform || '') ? 'Press Cmd+C' : 'Press Ctrl+C';
+  codeLangBtn.insertAdjacentHTML('beforeend', codeChipIcon('chevron-down'));
+  let codeChipsBlock = null; // the .ed-block the chips are drawn for
+  let codeLangMenu = null; // { el, input, list, s, sel, items, cursor }
+  let codeCopyTimer = null;
+
+  // Whether the in-place edit is open right now, with no side effect (unlike
+  // liveCodeEdit(), which disposes a session whose host a render detached).
+  function codeEditIsOpen() {
+    const s = codeEditState;
+    return !!s && activeEditor === s.editor && s.host.isConnected;
+  }
+
+  function resetCodeCopyChip() {
+    clearTimeout(codeCopyTimer);
+    codeCopyTimer = null;
+    codeCopyBtn.classList.remove('is-copied');
+    codeCopyBtn.innerHTML = CODE_COPY_ICON;
+    codeCopyBtn.setAttribute('aria-label', 'Copy code');
+    codeCopyBtn.title = 'Copy code';
+  }
+  resetCodeCopyChip();
+
+  // The info string the chip shows for `blockEl`: the open edit's (a language
+  // picked meanwhile counts), else the block's own fence line.
+  function codeChipInfo(blockEl) {
+    if (codeEditIsOpen() && codeEditState.blockEl === blockEl) return codeEditState.lang;
+    const rec = blockRecOf(blockEl);
+    if (!rec || rec.endLine < rec.startLine) return null;
+    const f = codeEditLib.parseFence(lines.slice(rec.startLine - 1, rec.endLine));
+    return f ? f.info : null;
+  }
+
+  function hideCodeChips() {
+    closeCodeLangMenu({ refocus: false });
+    if (codeChips.hidden && codeChipsBlock === null) return;
+    codeChips.hidden = true;
+    codeChipsBlock = null;
+    resetCodeCopyChip();
+  }
+
+  // D9: top = max(toolbarTopInset() + 4, rect.top + 6), a 6px right inset
+  // (the wave button's formula). `right` rather than `left`, so the copy
+  // chip growing to say Copied does not move the right edge.
+  function placeCodeChips() {
+    const pre = codeChipsBlock && codeChipsBlock.firstElementChild;
+    if (!pre) return false;
+    const r = pre.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) return false;
+    const top = Math.max(toolbarTopInset() + 4, r.top + CODE_CHIP_INSET_PX);
+    // Scrolled until the block's bottom is under the toolbar: nothing to draw on.
+    if (top + codeChips.offsetHeight > r.bottom - 2 || r.top > window.innerHeight) return false;
+    codeChips.style.top = Math.round(top) + 'px';
+    codeChips.style.right = Math.max(4, document.documentElement.clientWidth - r.right + CODE_CHIP_INSET_PX) + 'px';
+    return true;
+  }
+
+  // M6: hiding the chips when an edit ends leaves a pointer that stays over
+  // the block without chips (mouseover only fires on an element change). Once
+  // the DOM has settled, the block under the pointer gets them back.
+  function showCodeChipsUnderPointer() {
+    setTimeout(() => {
+      if (codeEditIsOpen() || !codeChips.hidden) return;
+      const hov = document.querySelectorAll(':hover');
+      const t = hov.length ? hov[hov.length - 1] : null;
+      const blk = t && t.closest ? t.closest('.ed-block[data-block-type="code"]') : null;
+      if (blk) showCodeChipsFor(blk);
+    }, 120);
+  }
+
+  function showCodeChipsFor(blockEl, force) {
+    if (!codeEditLib || !blockEl || !blockEl.isConnected || waveEditorIsModal() ||
+        !isFencedCodeBlock(blockEl) || blockEl.querySelector('.ed-raw')) { hideCodeChips(); return; }
+    if (codeChipsBlock === blockEl && !codeChips.hidden && !force) return;
+    const info = codeChipInfo(blockEl);
+    if (info === null) { hideCodeChips(); return; }
+    if (codeChipsBlock !== blockEl) resetCodeCopyChip();
+    codeChipsBlock = blockEl;
+    codeLangLabel.textContent = codeEditLib.langLabel(info);
+    codeLangBtn.setAttribute('aria-label', '程式碼語言：' + codeLangLabel.textContent);
+    codeChips.hidden = false;
+    if (!placeCodeChips()) hideCodeChips();
+  }
+
+  // After a render: chips for a block that is gone go; the open edit's chips
+  // follow it; a hovered block's chips refresh their label.
+  function reconcileCodeChips() {
+    if (codeLangMenu && !codeEditIsOpen()) closeCodeLangMenu({ refocus: false });
+    if (codeChips.hidden) return;
+    if (codeEditIsOpen()) { showCodeChipsFor(codeEditState.blockEl, true); return; }
+    if (!codeChipsBlock || !codeChipsBlock.isConnected) hideCodeChips();
+    else showCodeChipsFor(codeChipsBlock, true);
+  }
+
+  document.addEventListener('mouseover', (ev) => {
+    const t = ev.target;
+    if (!t || typeof t.closest !== 'function' || waveEditorIsModal()) return;
+    if (t.closest('.ed-code-chips, .ed-code-langmenu')) return;
+    if (codeEditIsOpen()) return; // the edit owns the chips
+    const blk = t.closest('.ed-block[data-block-type="code"]');
+    if (blk) showCodeChipsFor(blk); else hideCodeChips();
+  }, true);
+  // Scroll: the chips are at viewport coordinates, so they follow the open
+  // edit and go otherwise. The menu closes (the "/" menu's rule) except for
+  // its own list scrolling.
+  document.addEventListener('scroll', (e) => {
+    if (codeChips.hidden) return;
+    const t = e.target;
+    if (t && t.nodeType === 1 && t.closest && t.closest('.ed-code-langmenu')) return;
+    // The block's own sideways scroll moves nothing the chips sit on.
+    if (t && t.nodeType === 1 && codeChipsBlock && codeChipsBlock.contains(t)) return;
+    if (codeEditIsOpen()) {
+      if (codeLangMenu) closeCodeLangMenu({ refocus: true });
+      showCodeChipsFor(codeEditState.blockEl, true);
+    } else hideCodeChips();
+  }, { passive: true, capture: true });
+  window.addEventListener('resize', () => {
+    if (codeChips.hidden) return;
+    if (!placeCodeChips()) hideCodeChips();
+  });
+
+  // Presses on the chips and the menu never move focus: the edit keeps it.
+  // The filter input is the one thing that takes it.
+  codeChips.addEventListener('mousedown', (e) => { e.preventDefault(); });
+
+  // ── copy (D8) ──
+  function showCodeCopyResult(ok) {
+    setTimeout(() => drawCodeCopyResult(ok), 0);
+  }
+  function drawCodeCopyResult(ok) {
+    clearTimeout(codeCopyTimer);
+    codeCopyBtn.classList.toggle('is-copied', ok);
+    codeCopyBtn.innerHTML = ok ? CODE_COPY_DONE : '<span>' + CODE_COPY_KEYS + '</span>';
+    codeCopyBtn.setAttribute('aria-label', ok ? 'Copied' : CODE_COPY_KEYS);
+    codeCopyBtn.title = ok ? 'Copied' : CODE_COPY_KEYS;
+    codeCopyTimer = setTimeout(resetCodeCopyChip, CODE_COPY_RESET_MS);
+    if (codeChipsBlock) placeCodeChips();
+  }
+  // The code the copy chip hands over: the edit's current text (typing that
+  // is not committed yet included), else the block's own body.
+  function codeChipText(blockEl) {
+    if (codeEditIsOpen() && codeEditState.blockEl === blockEl) return codeEditText(codeEditState);
+    const rec = blockRecOf(blockEl);
+    const f = rec ? codeEditLib.parseFence(lines.slice(rec.startLine - 1, rec.endLine)) : null;
+    return f ? f.body.join('\n') : null;
+  }
+  function copyCodeFromChip() {
+    const blockEl = codeChipsBlock;
+    if (!blockEl || !blockEl.isConnected) { hideCodeChips(); return; }
+    const text = codeChipText(blockEl);
+    if (text === null) return;
+    // Refused: select the whole code and say which keys to press.
+    function bySelection() {
+      const s = codeEditIsOpen() && codeEditState.blockEl === blockEl ? codeEditState : null;
+      let ok = false;
+      if (s) placeCodeEditSelection(s, 0, codeEditText(s).length);
+      else {
+        const code = blockEl.querySelector('pre > code');
+        if (code) {
+          const range = document.createRange();
+          range.selectNodeContents(code);
+          const sel = window.getSelection();
+          sel.removeAllRanges();
+          sel.addRange(range);
+        }
+      }
+      try { ok = document.execCommand('copy'); } catch (err) { ok = false; }
+      if (ok) window.getSelection().removeAllRanges();
+      showCodeCopyResult(ok);
+    }
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(text).then(() => showCodeCopyResult(true), bySelection);
+    } else bySelection();
+  }
+  // The result is drawn from a timer (showCodeCopyResult), never inside the
+  // click's dispatch: swapping the chip's children there would detach the
+  // click's target before it bubbles, and the click router would read it as a
+  // click outside every block.
+  codeCopyBtn.addEventListener('click', copyCodeFromChip);
+
+  // ── language menu (D7) ──
+  // The CODE_LANGS entry id an info string resolves to ('' for none), or null
+  // for a word the table does not know.
+  function codeLangIdOf(info) {
+    const word = String(info || '').trim().split(/\s+/)[0].toLowerCase();
+    if (!word) return '';
+    const hit = codeEditLib.CODE_LANGS.find((l) => (l.id && l.id === word) || l.aliases.indexOf(word) !== -1);
+    return hit ? hit.id : null;
+  }
+  function markCodeLangCursor(m) {
+    const cur = m.items[m.cursor];
+    m.list.querySelectorAll('.ed-code-langitem').forEach((b) => {
+      const on = !!cur && b.getAttribute('data-ed-lang-id') === cur.id;
+      if (on) {
+        b.setAttribute('data-ed-lang-cursor', '');
+        m.input.setAttribute('aria-activedescendant', b.id);
+        b.scrollIntoView({ block: 'nearest' });
+      } else b.removeAttribute('data-ed-lang-cursor');
+    });
+  }
+  function renderCodeLangItems(m) {
+    m.items = codeEditLib.filterLangs(m.input.value);
+    const current = codeLangIdOf(m.s.lang);
+    const at = m.items.findIndex((l) => l.id === current);
+    m.cursor = at === -1 || m.input.value.trim() !== '' ? 0 : at;
+    m.list.textContent = '';
+    if (!m.items.length) {
+      const none = document.createElement('div');
+      none.className = 'ed-code-langempty';
+      none.textContent = '沒有符合的語言';
+      m.list.appendChild(none);
+      // v3.17.0 T10 (R54c): no option is current, so the input points at none.
+      m.input.removeAttribute('aria-activedescendant');
+      return;
+    }
+    m.items.forEach((l) => {
+      const b = document.createElement('button');
+      b.type = 'button';
+      b.className = 'ed-code-langitem';
+      b.setAttribute('role', 'option');
+      b.setAttribute('tabindex', '-1');
+      b.setAttribute('data-ed-lang-id', l.id);
+      b.id = 'ed-code-lang-' + (l.id || 'text');
+      b.setAttribute('aria-selected', l.id === current ? 'true' : 'false');
+      const label = document.createElement('span');
+      label.textContent = l.label;
+      b.appendChild(label);
+      if (l.id === current) b.insertAdjacentHTML('beforeend', codeChipIcon('check'));
+      b.addEventListener('click', () => { pickCodeLang(m, l.id); });
+      m.list.appendChild(b);
+    });
+    markCodeLangCursor(m);
+  }
+  function placeCodeLangMenu(m) {
+    const b = codeLangBtn.getBoundingClientRect();
+    const w = m.el.offsetWidth;
+    const h = m.el.offsetHeight;
+    const vw = document.documentElement.clientWidth || window.innerWidth;
+    let left = Math.min(b.left, vw - w - SLASH_EDGE_PX);
+    left = Math.max(SLASH_EDGE_PX, left);
+    let top = b.bottom + SLASH_GAP_PX;
+    if (top + h > window.innerHeight - SLASH_GAP_PX) {
+      top = Math.max(toolbarTopInset() + SLASH_GAP_PX, b.top - SLASH_GAP_PX - h);
+    }
+    m.el.style.left = Math.round(left) + 'px';
+    m.el.style.top = Math.round(top) + 'px';
+  }
+  function openCodeLangMenu(s) {
+    closeCodeLangMenu({ refocus: false });
+    const el = document.createElement('div');
+    el.className = 'ed-code-langmenu';
+    const input = document.createElement('input');
+    input.type = 'text';
+    input.className = 'ed-code-langfilter';
+    input.placeholder = '篩選語言';
+    input.setAttribute('aria-label', '篩選語言');
+    input.setAttribute('role', 'combobox');
+    input.setAttribute('aria-expanded', 'true');
+    input.setAttribute('aria-controls', 'ed-code-langlist');
+    input.setAttribute('autocomplete', 'off');
+    input.spellcheck = false;
+    const list = document.createElement('div');
+    list.className = 'ed-code-langlist';
+    list.setAttribute('role', 'listbox');
+    list.id = 'ed-code-langlist';
+    el.appendChild(input);
+    el.appendChild(list);
+    // The caret is read BEFORE focus moves to the filter: a pick puts it back.
+    const m = { el, input, list, s, sel: codeEditSel(s), items: [], cursor: 0 };
+    codeLangMenu = m;
+    document.body.appendChild(el);
+    codeLangBtn.setAttribute('aria-expanded', 'true');
+    el.addEventListener('mousedown', (e) => { if (e.target !== input) e.preventDefault(); });
+    input.addEventListener('input', () => { renderCodeLangItems(m); });
+    input.addEventListener('keydown', (e) => {
+      if (e.isComposing) return;
+      const k = e.key;
+      if (k === 'ArrowDown' || k === 'ArrowUp') {
+        e.preventDefault();
+        e.stopPropagation();
+        if (m.items.length) {
+          m.cursor = (m.cursor + (k === 'ArrowDown' ? 1 : -1) + m.items.length) % m.items.length;
+          markCodeLangCursor(m);
+        }
+      } else if (k === 'Enter') {
+        e.preventDefault();
+        e.stopPropagation();
+        const it = m.items[m.cursor];
+        if (it) pickCodeLang(m, it.id);
+      } else if (k === 'Escape' || k === 'Tab') {
+        e.preventDefault();
+        e.stopPropagation();
+        closeCodeLangMenu({ refocus: true });
+      }
+    });
+    renderCodeLangItems(m);
+    placeCodeLangMenu(m);
+    input.focus({ preventScroll: true });
+  }
+  // `refocus`: give the edit its focus and caret back (a close that keeps
+  // editing); false when the caller is about to move focus itself.
+  function closeCodeLangMenu(o) {
+    const m = codeLangMenu;
+    if (!m) return;
+    codeLangMenu = null;
+    codeLangBtn.setAttribute('aria-expanded', 'false');
+    if (m.el.parentNode) m.el.parentNode.removeChild(m.el);
+    if (o && o.refocus && codeEditIsOpen() && codeEditState === m.s) {
+      m.s.host.focus({ preventScroll: true });
+      if (m.sel) placeCodeEditSelection(m.s, m.sel[0], m.sel[1]);
+    }
+  }
+  // The text and the new language as one op; the edit opens again at the same
+  // caret (commitWithLang). The menu is closed first, with the caret put
+  // back, so the commit reads the selection the user left.
+  async function pickCodeLang(m, lang) {
+    const s = m.s;
+    closeCodeLangMenu({ refocus: false });
+    if (!codeEditIsOpen() || codeEditState !== s) return;
+    if (m.sel) placeCodeEditSelection(s, m.sel[0], m.sel[1]);
+    await s.commitWithLang(lang);
+  }
+  codeLangBtn.addEventListener('click', async () => {
+    if (codeLangMenu) { closeCodeLangMenu({ refocus: true }); return; }
+    let blk = codeChipsBlock;
+    if (!blk || !blk.isConnected) { hideCodeChips(); return; }
+    // R40: a block that is not being edited opens the edit first. Whatever
+    // else is open (a paragraph typed in a moment ago) is resolved BEFORE, and
+    // its render may replace this block: it is found again by content, only
+    // when it is the one block with that source (R104, as the click router
+    // does), else the gesture is dropped with the notice.
+    // v3.17.0 T9a (R54a): and the router's other two guards, for the same
+    // reason (R102, I-R1): a reconciliation that moved since the click, or
+    // one owed while the block's lines on screen are not its lines in
+    // `lines`, would seed the edit from the wrong lines. Refused instead.
+    if (!(codeEditIsOpen() && codeEditState.blockEl === blk)) {
+      const epochAtClick = reconcileEpoch;
+      const identity = commitsSettled() && !reconcileBlocksCommits() ? captureBlockIdentity(blk) : null;
+      if (!(await switchAwayFrom())) return;
+      await settleCommits();
+      blk = refindBlock(blk, identity);
+      if (!blk || reconcileEpoch !== epochAtClick || (reconcileBlocksCommits() && !blockReadsAsDrawn(blk))) {
+        showError(DROPPED_GESTURE_MESSAGE, null, null);
+        return;
+      }
+      if (!(await editCodeInPlace(blk, { offset: 0 }))) return;
+    }
+    const s = liveCodeEdit();
+    if (s && !codeLangMenu) openCodeLangMenu(s);
+  });
+  // A press anywhere else puts the menu away (focus goes where the press
+  // sends it; the click router then resolves the edit as usual).
+  document.addEventListener('mousedown', (e) => {
+    if (!codeLangMenu) return;
+    const t = e.target;
+    if (t && t.closest && t.closest('.ed-code-langmenu, .ed-code-chips')) return;
+    closeCodeLangMenu({ refocus: false });
+  }, true);
+
   // ── Phase-2 Task 3: paragraph / heading WYSIWYG editing ────────────────
   // A block's rendered content is the .ed-block's single element child
   // (see lib/md2doc.js's editMode wrapper: `<div class="ed-block"
@@ -6291,6 +7405,10 @@
       // same offset this branch used to compute, indexOf('\n') + 1, with the
       // value untouched. So the fix-up is deleted rather than kept as a
       // no-op that reads like it is still load-bearing.
+      // v3.17.0 T2 (D2, R21): the skeleton is a fenced block, so it now
+      // opens the in-place edit on its empty body; the raw box is the
+      // fallback for anything that is not one.
+      if (await editCodeInPlace(blockEl, { offset: 0 })) return;
       await openRawEditor(blockEl);
       return;
     }
@@ -6346,19 +7464,18 @@
     // preventDefault() names '.ed-insert' as well as '.ed-handle', so the
     // burst survives the press and the commit that lands inside
     // switchAwayFrom() below can be a rewrite of THIS block's own source —
-    // in which case reresolveBlockEl()'s source fingerprint is guaranteed to
+    // in which case refindBlock()'s source fingerprint is guaranteed to
     // miss, because WE are the reason the source changed, and the gesture is
     // dropped with '文件已更新，請重試這個操作' having done nothing. The
     // narrowed re-resolve (startLine + type, no fingerprint) is used ONLY
     // when the session that just committed was this block's OWN;
-    // reresolveBlockEl() keeps its fingerprint for everybody else.
+    // refindBlock() keeps its fingerprint for everybody else.
     const selfSession = ownsOpenSession(blockEl);
     const ok = await switchAwayFrom();
     if (!ok) return;
     let liveBlockEl = blockEl;
     if (!document.body.contains(blockEl)) {
-      liveBlockEl = reresolveBlockEl(identity) ||
-        (selfSession ? reresolveBlockElAfterSelfCommit(identity) : null);
+      liveBlockEl = refindBlock(blockEl, identity, selfSession);
       if (!liveBlockEl) { showError(DROPPED_GESTURE_MESSAGE, null, null); return; }
     }
     // T7 fix round 1 (LOW-2): same refusal deleteBlockViaGutter() makes below,
@@ -6565,7 +7682,7 @@
   //   startBurst ............................................ include (own
   //       branch); any other id-less block: skip (R2)
   //   setBlockSelection / selection walkers / blockRecOf .... skip (null)
-  //   captureBlockIdentity / reresolveBlockEl ............... skip (null)
+  //   captureBlockIdentity / refindBlock (a detached one) ... skip (null)
   //   commitListStructure targets ........................... n/a (li only)
   //   handleBurstKeydown arrow probe / walkToAdjacentBlockByArrow /
   //       adjacentFocusableBlock ............................ include: the
@@ -6679,6 +7796,45 @@
     return el;
   }
 
+  // v3.17.0 T9a (M-f, L146): a raw box or an in-place code edit left with its
+  // own key (Esc, Ctrl/Cmd+Enter) puts the block's node back, and focus goes
+  // to BODY with the node it was on, where the next key lands nowhere. Once
+  // the leave has landed, the caret goes on to the block right below what was
+  // edited, at its start, or into a transient there when that block takes no
+  // caret or nothing follows. `tail` is how many lines followed the edited
+  // span when the key was pressed: a leave rewrites that span only, so it
+  // still ends `tail` lines before the end of `lines` — which also holds when
+  // the leave took the block away (an untouched insert discarded). Nothing
+  // moves when focus is already somewhere (a click landed meanwhile) or the
+  // screen is not `lines` (a superseded render, a reconciliation owed).
+  // Focus still on `ownEl` (the edited block) counts as nowhere: WebKit keeps
+  // the code edit's host as activeElement once its contenteditable is taken
+  // off when no render replaced it (an unchanged leave; measured).
+  let handingCaretOn = false;
+  function handCaretOnBelow(tail, ownEl) {
+    handingCaretOn = true;
+    try { handCaretOnBelowNow(tail, ownEl); } finally { handingCaretOn = false; }
+  }
+  function handCaretOnBelowNow(tail, ownEl) {
+    const ae = document.activeElement;
+    if (ae && ae !== document.body && ae.isConnected && !(ownEl && ownEl.contains(ae))) return;
+    if (reconcileBlocksCommits() || drawnContent !== lines.join('\n')) return;
+    const editEnd = lines.length - tail;
+    const below = blocks.find((b) => b.startLine > editEnd);
+    const belowEl = below ? blockElById(below.id) : null;
+    const surface = focusableSurfaceOf(belowEl);
+    if (surface) {
+      surface.focus();
+      placeCaretAtSurfaceStart(surface);
+      return;
+    }
+    const t = createTransient(belowEl ? previousBlockEl(belowEl) : lastBlockEl(), { focus: true });
+    // v3.17.0 T10: the transient belongs to the leave. If the leave was an Esc
+    // that discarded text, the next Ctrl+Z takes this transient away and then
+    // brings the text back (burstUndo()).
+    if (t && transient && transient.el === t) transient.afterLeave = true;
+  }
+
   // v3.14.0 T4: data-ed-empty on a paragraph surface that holds no text and no
   // image, off otherwise. The CSS hint keys off it. Called on focusin and
   // input of an armed paragraph surface, by createTransient(), and after the
@@ -6866,8 +8022,7 @@
     const ok = await switchAwayFrom();
     if (!ok) return null;
     if (document.body.contains(blockEl)) return blockEl;
-    const live = reresolveBlockEl(identity) ||
-      (selfSession ? reresolveBlockElAfterSelfCommit(identity) : null);
+    const live = refindBlock(blockEl, identity, selfSession);
     if (!live) showError(DROPPED_GESTURE_MESSAGE, null, null);
     return live;
   }
@@ -7261,7 +8416,7 @@
     closeSlashMenu();
     if (!blockCatalog || !surface || !surface.isConnected) return;
     const el = buildSlashMenuEl();
-    slashMenu = { el, surface, slashOffset, items: [], cursor: 0, query: null };
+    slashMenu = { el, surface, slashOffset, items: [], cursor: 0, query: null, lastMatchLen: 0 };
     document.body.appendChild(el);
     refreshSlashMenu();
   }
@@ -7288,6 +8443,13 @@
       // the block below it and take the next click aimed there. A typed "/"
       // keeps the empty line (D7): the user asked for the menu.
       if (m.slashOffset < 0 && !m.items.length) { closeSlashMenu(); return; }
+      // v3.17.0 T10 (M-a, R42): a typed "/" closes on the third character
+      // past the last query that matched (q.length - lastMatchLen >= 3; the
+      // empty line stays up through the first two). A path such as /usr/bin:
+      // 'u' matched, 's' and 'r' did not, the second "/" is the third and
+      // closes it. The text is plain paragraph text by then; nothing is removed.
+      if (m.items.length) m.lastMatchLen = q.length;
+      else if (q.length - m.lastMatchLen >= 3) { closeSlashMenu(); return; }
       renderSlashItems();
     }
     positionSlashMenu();
@@ -7487,10 +8649,13 @@
     const surface = blockContentEl(blockEl);
     const typed = surface ? slashSurfaceText(surface) : '';
     const identity = captureBlockIdentity(blockEl);
+    // Fix round 1 (C1): gated like every other self-commit fallback; it used
+    // to be taken for any render, its own or not.
+    const selfSession = ownsOpenSession(blockEl);
     openImagePicker(async (files) => {
-      let live = blockEl.isConnected ? blockEl
-        : (identity ? (reresolveBlockEl(identity) || reresolveBlockElAfterSelfCommit(identity)) : null);
-      if (!live) { showNotice(TOOLBAR_NO_ANCHOR_MESSAGE); return; }
+      let live = refindBlock(blockEl, identity, selfSession);
+      // Fix round 1 (I1, R35): the retry notice, as every re-find refusal.
+      if (!live) { showError(DROPPED_GESTURE_MESSAGE, null, null); return; }
       const liveSurface = blockContentEl(live);
       if (!liveSurface || slashSurfaceText(liveSurface) !== typed) { await insertImages(files, live); return; }
       const paths = [];
@@ -7825,8 +8990,16 @@
       return;
     }
     if (match.kind === 'code') {
-      // The caret right after the opening fence: a language typed there is
-      // the info string, and Enter moves on to the body (R22).
+      // v3.17.0 T2 (R21, R28): the in-place edit, caret at the start of the
+      // body; what was typed meanwhile goes into the body (the language is
+      // the chip's now, not the fence line's).
+      if (await editCodeInPlace(el, { offset: 0 })) {
+        drainHeldKeysIntoCodeEdit();
+        return;
+      }
+      // Not a fenced block after all: the v3.15.0 raw box. The caret right
+      // after the opening fence: a language typed there is the info string,
+      // and Enter moves on to the body (R22).
       const fence = converted[0];
       await openRawEditor(el, undefined, { value: converted.join('\n'), caret: fence.length, enterToBody: true });
       drainHeldKeysIntoRawBox(true);
@@ -9091,7 +10264,10 @@
   //      `data-block-id` is null (blockRecOf() returns null for both). Either
   //      way there is no record to read a startLine off.
   // See restoreAfterStructuralOp().
-  async function resolveGutterOperands(blockEl, anchor) {
+  // `opts.goneIsDone` (T9a fix round 2, R64; ⠿ 刪除 only): when the gesture's
+  // own commit removed the block, the gesture is already done — null with no
+  // notice. Every other caller refuses with the notice.
+  async function resolveGutterOperands(blockEl, anchor, opts) {
     // R94: every ⠿ action (and the toolbar's conversions) waits for a commit
     // in flight before it takes the block's identity.
     blockEl = await settledGestureBlock(blockEl);
@@ -9099,7 +10275,7 @@
     // Finding 5a's mousedown preventDefault() deliberately keeps a dirty burst
     // alive across the ⠿ press, so the commit that lands inside
     // switchAwayFrom() below can be a rewrite of the very block the gesture
-    // names — in which case reresolveBlockEl()'s SOURCE fingerprint is
+    // names — in which case refindBlock()'s SOURCE fingerprint is
     // guaranteed to miss, because WE are the reason the source changed. That
     // is not a dropped gesture; startLine + type still name the block, and the
     // fingerprint's job (proving an UNRELATED commit did not move somebody
@@ -9110,9 +10286,13 @@
     if (!ok) return null;
     let liveBlockEl = blockEl;
     if (!document.body.contains(blockEl)) {
-      liveBlockEl = reresolveBlockEl(identity) ||
-        (selfSession ? reresolveBlockElAfterSelfCommit(identity) : null);
-      if (!liveBlockEl) { showError(DROPPED_GESTURE_MESSAGE, null, null); return null; }
+      liveBlockEl = refindBlock(blockEl, identity, selfSession);
+      if (!liveBlockEl) {
+        if (!(opts && opts.goneIsDone && selfSession && selfCommitRemovedBlock(identity))) {
+          showError(DROPPED_GESTURE_MESSAGE, null, null);
+        }
+        return null;
+      }
     }
     // A block that owns no source line has an INVERTED range
     // (endLine === startLine - 1) and every commit helper handed one does
@@ -9370,7 +10550,12 @@
         const target = blocks.find((b) => b.startLine === focusLine);
         const blockEl = target &&
           document.querySelector('.ed-block[data-block-id="' + target.id + '"]');
-        if (blockEl) openRawEditor(blockEl).catch(() => {});
+        // v3.17.0 T2 (R28): a block converted to 程式碼 opens the in-place
+        // edit (the same answer as a click on it); a quote keeps the raw box.
+        if (blockEl) {
+          editCodeInPlace(blockEl, { offset: 0 })
+            .then((opened) => (opened ? null : openRawEditor(blockEl))).catch(() => {});
+        }
       }
       return;
     }
@@ -9623,13 +10808,30 @@
 
   // The narrowed re-resolve for the case above: startLine and type must still
   // match, but the source is allowed to differ because our own switchAwayFrom()
-  // just rewrote it. Deliberately NOT folded into reresolveBlockEl() — every
-  // other caller of that function needs the fingerprint, and a shared helper
-  // that sometimes skips it is the shape that lets a future call site act on a
-  // block the user never pointed at.
+  // just rewrote it. Reached only through refindBlock(), and only when its
+  // caller passes `selfSession` (ownsOpenSession() read before the commit);
+  // every other re-find keeps the content fingerprint, because skipping it is
+  // the shape that lets a call site act on a block the user never pointed at.
+  //
+  // T9a fix round 2 (R64): null when that commit REMOVED the block (R95's
+  // removal of an emptied paragraph). Its start line then names the block
+  // below, of the same type more often than not — measured: empty `Alpha.`,
+  // ⠿ 刪除 on it, and `Beta.` below was deleted too.
+  // Whether the block's own commit took all of its lines away. That commit
+  // rewrote the block's span and nothing else, so the lines below it are the
+  // `tail` lines at the end of the file: the span now runs from its start line
+  // to `lines.length - tail`, and an empty span is a removed block. Read from
+  // line counts only — a type or a source at the start line cannot tell the
+  // block from the one that moved up into its place. An identity taken before
+  // `tail` existed (none today) never reads as removed.
+  function selfCommitRemovedBlock(identity) {
+    return !!identity && identity.tail !== undefined &&
+      lines.length - identity.tail < identityStartLineNow(identity);
+  }
   function reresolveBlockElAfterSelfCommit(identity) {
     if (!identity) return null;
-    if (identity.reconcileEpoch !== reconcileEpoch) return null; // R84, see reresolveBlockEl()
+    if (identity.reconcileEpoch !== reconcileEpoch) return null; // R84 (refindBlock()'s uniqueBlockElBySource() asks the same)
+    if (selfCommitRemovedBlock(identity)) return null;
     const startLine = identityStartLineNow(identity);
     const at = blocks.find((b) => b.startLine === startLine);
     if (!at || at.type !== identity.type) return null;
@@ -10023,7 +11225,7 @@
     // re-resolve is highest here: an id shift used to make this delete a
     // DIFFERENT block's lines, with the ⠿ menu the user pressed pointing at a
     // block that survived.
-    const operands = await resolveGutterOperands(blockEl, anchor);
+    const operands = await resolveGutterOperands(blockEl, anchor, { goneIsDone: true });
     if (!operands) return;
     const els = operands.els;
     const recs = operands.recs;
@@ -11043,12 +12245,17 @@
   function startBurst(editEl) {
     // v3.15.0 B5 fix round 4 (R86 (2)): never on a screen that is not `lines`.
     if (burstsLocked()) return;
-    dropDiscardedBurst();
-    // v3.4.0 (Task 7 item 5): opening ANY new session — burst or raw —
-    // invalidates a still-parked raw-edit discard from a different block; see
-    // discardedRawEdit's own comment for why the two stashes must stay
-    // mutually exclusive.
-    dropDiscardedRawEdit();
+    // v3.17.0 T10: the caret a leave by key hands on (handCaretOnBelow()) is
+    // not a new session of the user's own, so an Esc's discarded text stays
+    // recoverable with the next Ctrl+Z, as it was when that focus went to BODY.
+    if (!handingCaretOn) {
+      dropDiscardedBurst();
+      // v3.4.0 (Task 7 item 5): opening ANY new session — burst or raw —
+      // invalidates a still-parked raw-edit discard from a different block; see
+      // discardedRawEdit's own comment for why the two stashes must stay
+      // mutually exclusive.
+      dropDiscardedRawEdit();
+    }
     const blockEl = editEl.closest('.ed-block');
     if (!blockEl) return;
     // v3.14.0 T1: a transient paragraph has no block record and no line. Its
@@ -11353,7 +12560,11 @@
     // browser leaves in an emptied contenteditable wrote a literal `<br>` line
     // (measured: Backspace ×6 on `Omega.`, click away → `<br>` on disk). A
     // heading keeps its `#` run (R45), so this is paragraphs only.
-    if (burst.blockType === 'paragraph' && transientSurfaceEmpty(burst.blockEl)) {
+    // v3.17.0 T10 (N6): the burst's own surface decides. transientSurfaceEmpty()
+    // answers true when it finds no surface, which would remove a paragraph
+    // this burst never saw empty.
+    if (burst.blockType === 'paragraph' && burst.editEl &&
+        burst.editEl.textContent === '' && !burst.editEl.querySelector('img')) {
       return await removeEmptiedParagraph(burst);
     }
     // Task 5: a table burst serializes through table-md.js's serializeTable()
@@ -11457,7 +12668,13 @@
     }
     if (focusInside && ok !== RENDER_SUPERSEDED) {
       const anchor = preceding ? blockElAtLine(preceding.startLine) : null;
-      if (!preceding || anchor) createTransient(anchor ? subtreeEndOf(anchor) : null, { focus: true });
+      if (!preceding || anchor) {
+        const t = createTransient(anchor ? subtreeEndOf(anchor) : null, { focus: true });
+        // v3.17.0 T10 (N4): this transient is part of the removal — while it
+        // is still empty and nothing else was committed since, one Ctrl+Z
+        // takes it away AND brings the paragraph back (burstUndo()).
+        if (t && transient && transient.el === t) transient.afterEmptied = lines;
+      }
     }
     return true;
   }
@@ -11769,7 +12986,7 @@
   // selection instead of opening the menu, and a drag inside the raw
   // textarea would fight its own text selection.
   const ED_SEL_GESTURE_CHROME = '.ed-handle, .ed-handle-menu, .ed-insert, .ed-slash-menu, ' +
-    '.ed-te-menu, .ed-te-grip, .ed-tb-insert, .ed-seltb, .ed-linkbar, .ed-linkcard, .ed-conflict, .ed-raw';
+    '.ed-te-menu, .ed-te-grip, .ed-tb-insert, .ed-seltb, .ed-linkbar, .ed-linkcard, .ed-imgtb, .ed-conflict, .ed-raw';
   function isSelGestureChrome(target) {
     return !!(target && target.closest && target.closest(ED_SEL_GESTURE_CHROME));
   }
@@ -11973,6 +13190,13 @@
   // fingerprint fails, the caller DROPS the gesture and says so. Never
   // guessed: completing every gesture is worth less than never acting on a
   // block the user did not point at.
+  //
+  // v3.17.0 T9a (M-R5, R35): the start line turned out to be no proof either
+  // (R104: R95's removal of an emptied paragraph shifts lines unlogged, and an
+  // identical block then sits on the old line). A node a render replaced is
+  // now found again only by refindBlock() below — the one block of its type
+  // with that source, or nothing. The start line is still the handle for
+  // reresolveBlockElAfterSelfCommit(), whose source legitimately changed.
   function blockSourceOf(block) {
     return lines.slice(block.startLine - 1, block.endLine).join('\n');
   }
@@ -11982,8 +13206,10 @@
     if (raw === null) return null;
     const b = blocks.find((x) => x.id === Number(raw));
     if (!b) return null;
+    // `tail` (T9a fix round 2, R64): the lines below the block, for
+    // selfCommitRemovedBlock().
     return { startLine: b.startLine, type: b.type, source: blockSourceOf(b),
-      transientSeq: transientCommits.seq, reconcileEpoch };
+      tail: lines.length - b.endLine, transientSeq: transientCommits.seq, reconcileEpoch };
   }
   // v3.14.0 T1 fix round 1 (I2): where `identity`'s block starts NOW. A
   // transient's commit is a pure insertion — no existing line is rewritten —
@@ -11993,7 +13219,9 @@
   // before: type into a transient, then ＋ / ⠿ on any block below it — the
   // gesture's own switchAwayFrom() committed the transient, the target's
   // start line moved by ≥ 2, and the gesture was dropped with
-  // DROPPED_GESTURE_MESSAGE.
+  // DROPPED_GESTURE_MESSAGE. Since v3.17.0 T9a only
+  // reresolveBlockElAfterSelfCommit() reads it; the stale re-find
+  // (refindBlock()) reads no start line.
   function identityStartLineNow(identity) {
     let line = identity.startLine;
     const since = identity.transientSeq === undefined ? transientCommits.seq : identity.transientSeq;
@@ -12002,16 +13230,6 @@
     });
     return line;
   }
-  function reresolveBlockEl(identity) {
-    if (!identity) return null;
-    // v3.15.0 B5 fix round 3 (R84): taken before a reconciliation redraw, it
-    // names a line of the stale screen; the gesture is refused instead.
-    if (identity.reconcileEpoch !== reconcileEpoch) return null;
-    const startLine = identityStartLineNow(identity);
-    const at = blocks.find((b) => b.startLine === startLine);
-    if (!at || at.type !== identity.type || blockSourceOf(at) !== identity.source) return null;
-    return document.querySelector('.ed-block[data-block-id="' + at.id + '"]');
-  }
 
   // What a caller says when it refuses to act rather than act on the wrong
   // block. Dismiss-only, same shape as refuseStructuralListEdit()'s banner —
@@ -12087,7 +13305,8 @@
     if (!blockEl.getAttribute('data-block-id')) return false;
     const editEl = blockContentEl(blockEl);
     if (editEl && (editEl.classList.contains('ed-wys-armed') || editEl.classList.contains('ed-wys-table'))) return false;
-    return !blockEl.querySelector('.ed-raw');
+    // v3.17.0 T2 (R24): nor while it is being edited in place.
+    return !blockEl.querySelector('.ed-raw, [data-ed-code-edit], .ed-diagram-panel');
   }
   // R102 (I-R1): while a reconciliation is owed, `blocks` describes what is
   // drawn (`drawnContent`), not `lines`. True when `blockEl`'s lines read the
@@ -12110,6 +13329,53 @@
     const hits = blocks.filter((b) => b.type === identity.type && blockSourceOf(b) === identity.source);
     return hits.length === 1 ? blockElById(hits[0].id) : null;
   }
+  // v3.17.0 T9a (M-R5, R35): the element a gesture names once what it awaited
+  // has landed — itself while a render kept it on screen, otherwise the one
+  // block found again by content (uniqueBlockElBySource()), or null, and the
+  // caller refuses with the notice and writes nothing. The cost, accepted: a
+  // gesture on a block with an identical twin, after a render replaced it,
+  // needs a second try.
+  //
+  // `selfSession` (fix round 1, C1): the commit that replaced the node was
+  // this block's OWN open session (ownsOpenSession(), read before the
+  // commit). That commit rewrote the block, so `identity.source` can only
+  // belong to ANOTHER block now, and a content match would act on its
+  // identical twin (measured: type into the first of two `Twin.`, ⠿ 刪除 on
+  // it, the second was deleted). The block is then the one at its start line
+  // (reresolveBlockElAfterSelfCommit()), never a content match.
+  function refindBlock(blockEl, identity, selfSession) {
+    if (blockEl && blockEl.isConnected) return blockEl;
+    return selfSession ? reresolveBlockElAfterSelfCommit(identity) : uniqueBlockElBySource(identity);
+  }
+  // v3.17.0 T10 (N2): a checkbox click is not a caret gesture, but the press
+  // does not move focus either (its mousedown is prevented), so a caret that
+  // sat in another paragraph, heading or item stays where the user left it.
+  // Before, the toggle's resolution blurred it and the next keys went to
+  // BODY. Not for a transient, a table cell, or an item of the toggled run
+  // (that run is re-rendered whole).
+  function captureCaretBeforeCheckbox(run) {
+    const act = document.activeElement;
+    const surface = act && act.closest ? act.closest('.ed-wys-armed') : null;
+    if (!surface || surface.closest('[data-ed-transient]')) return null;
+    const blockEl = surface.closest('.ed-block');
+    if (!blockEl || run.indexOf(blockEl) !== -1) return null;
+    const snap = selectionSnapshotIn(surface);
+    if (!snap || snap.focus === null) return null;
+    return { blockEl, identity: captureBlockIdentity(blockEl), selfSession: ownsOpenSession(blockEl),
+      anchor: snap.anchor, focus: snap.focus };
+  }
+  // Puts it back after the toggle's render, in the same block found again —
+  // unless focus went somewhere meanwhile (a click, a key), which wins.
+  function restoreCaretAfterCheckbox(keep) {
+    if (!keep) return;
+    const act = document.activeElement;
+    if (act && act !== document.body && act !== document.documentElement) return;
+    const live = refindBlock(keep.blockEl, keep.identity, keep.selfSession);
+    const surface = live ? blockContentEl(live) : null;
+    if (!surface || !surface.isConnected || !surface.classList.contains('ed-wys-armed')) return;
+    surface.focus({ preventScroll: true });
+    restoreSelection(surface, keep.anchor, keep.focus);
+  }
   // R93: the item a settled checkbox click names (see the click handler).
   function checkItemAfterSettle(li, snap) {
     if (li.isConnected) return li;
@@ -12812,6 +14078,12 @@
       // below its divider is part of that gesture, so the same press also
       // takes the conversion back (undo() puts the caret after the literal).
       if (t && t.el === burst.blockEl && t.afterShortcut) { undo(); return; }
+      // v3.17.0 T10 (N4): the same for the transient an emptied paragraph's
+      // removal left, while `lines` is still what that removal wrote.
+      if (t && t.el === burst.blockEl && t.afterEmptied === lines) { undo(); return; }
+      // v3.17.0 T10: and the one a leave by key handed the caret to, while an
+      // Esc's discarded text waits to be restored (restoreDiscardedRawEdit()).
+      if (t && t.el === burst.blockEl && t.afterLeave && (discardedRawEdit || discardedBurst)) { undo(); return; }
       if (t && t.anchorCaret && t.anchorCaret.surface && t.anchorCaret.surface.isConnected) {
         t.anchorCaret.surface.focus();
         restoreSelection(t.anchorCaret.surface, t.anchorCaret.offset, t.anchorCaret.offset);
@@ -14453,13 +15725,14 @@
   // Resolving first and re-resolving afterwards is also the shape
   // ensureTableBurstOpen() above already uses against the same hazard.
   //
-  // captureBlockIdentity() / reresolveBlockEl() is the handle, for the reason
+  // captureBlockIdentity() / refindBlock() is the handle, for the reason
   // their own comment writes down: blockmap.js renumbers ids from zero on
   // every render, so a captured id can name the destination's NEIGHBOUR after
-  // a commit that changed the block count, and the start line plus the block's
-  // own source lines is what proves the block sitting there afterwards is the
-  // one the press was aimed at. When it cannot be proven nothing is focused —
-  // the conservative half of the trade the gutter gestures already take.
+  // a commit that changed the block count, and (since v3.17.0 T9a) being the
+  // one block of its type with its own source lines is what proves the block
+  // found afterwards is the one the press was aimed at. When it cannot be
+  // proven nothing is focused — the conservative half of the trade the gutter
+  // gestures already take.
   //
   // Nothing is focused when no such block exists either, and the caller's
   // preventDefault() still stands over that press. Handing it back to the
@@ -14495,8 +15768,11 @@
     const identity = captureBlockIdentity(destBlockEl);
     const ok = await switchAwayFrom();
     if (!ok) return;
-    const liveBlockEl = document.body.contains(destBlockEl)
-      ? destBlockEl : reresolveBlockEl(identity);
+    // v3.17.0 T9a (M-R5): a destination a render replaced and that cannot be
+    // found again (R104) is refused with the notice, never walked past in
+    // silence.
+    const liveBlockEl = refindBlock(destBlockEl, identity);
+    if (!liveBlockEl) { showError(DROPPED_GESTURE_MESSAGE, null, null); return; }
     const surface = focusableSurfaceOf(liveBlockEl);
     if (!surface) return;
     surface.focus();
@@ -15173,7 +16449,7 @@
       const srcRec = blocks.find((b) => b.startLine === srcStartLine);
       const liveSrc = srcRec
         ? document.querySelector('.ed-block[data-block-id="' + srcRec.id + '"]') : null;
-      dest = (liveSrc && nextBlock(liveSrc)) || reresolveBlockEl(destIdentity);
+      dest = (liveSrc && nextBlock(liveSrc)) || refindBlock(dest, destIdentity);
       // A transient destination is gone with the render that committed the
       // source; there is nothing to re-resolve and nothing was dropped.
       if (!dest) { if (!destWasTransient) showError(DROPPED_GESTURE_MESSAGE); return; }
@@ -17970,9 +19246,9 @@
   // The DESTINATION needs the same protection and gets it one step earlier:
   // its identity is captured BEFORE resolveGutterOperands(), whose
   // switchAwayFrom() may commit some other block's dirty burst and re-render.
-  // reresolveBlockEl() then proves the block sitting at that start line
-  // afterwards really is the same one, exactly as the source's own re-resolve
-  // does; when it cannot, the gesture is DROPPED with a banner rather than
+  // refindBlock() then proves the block found afterwards really is the
+  // same one (the one block with its source), exactly as the source's own
+  // re-resolve does; when it cannot, the gesture is DROPPED with a banner rather than
   // completed against a block the user did not point at.
   async function performBlockDrop(st) {
     const target = st.dropTarget;
@@ -18013,13 +19289,13 @@
     // '文件已更新，請重試這個操作' with the edit committed and the move not.
     //
     // It is an ASYMMETRY, not a race, and it could not be anything else:
-    // reresolveBlockEl()'s fingerprint is the block's SOURCE, and the commit
+    // refindBlock()'s fingerprint is the block's SOURCE, and the commit
     // that changed that source is this drop's OWN resolveGutterOperands() →
     // switchAwayFrom(). The fingerprint is therefore GUARANTEED to miss. The
     // source side has had reresolveBlockElAfterSelfCommit() for exactly this
     // since S2; this is its destination-side counterpart, gated the same way
     // — on ownsOpenSession() read BEFORE the commit, because `currentBurst` is
-    // gone afterwards — so reresolveBlockEl() keeps its fingerprint for
+    // gone afterwards — so refindBlock() keeps its fingerprint for
     // everybody else. Deliberately NOT a widening of that function: S2's own
     // note says the narrowed variant exists precisely so no other caller loses
     // the fingerprint.
@@ -18031,8 +19307,7 @@
     if (!operands) return;
     let liveDestEl = destEl;
     if (destEl && !document.body.contains(destEl)) {
-      liveDestEl = reresolveBlockEl(destIdentity) ||
-        (destSelfSession ? reresolveBlockElAfterSelfCommit(destIdentity) : null);
+      liveDestEl = refindBlock(destEl, destIdentity, destSelfSession);
       if (!liveDestEl) { showError(DROPPED_GESTURE_MESSAGE, null, null); return; }
     }
     // ── S4 Task 6: THE OPERAND SET (spec §4.5, §3.3, §3.6) ────────────────
@@ -19563,11 +20838,33 @@
     const w = el.getBoundingClientRect().width;
     el.style.top = Math.max(margin, top) + 'px';
     el.style.left = Math.max(margin, Math.min(left, window.innerWidth - w - margin)) + 'px';
-    linkFieldState = { el, input, root, range, existing: opts.existing || null };
+    // v3.17.0 T10 (M-c): where the field sits relative to the selection, so a
+    // page scroll can carry it along (followLinkField).
+    const sr = range.getBoundingClientRect();
+    const fr = el.getBoundingClientRect();
+    linkFieldState = { el, input, root, range, existing: opts.existing || null,
+      dy: fr.top - sr.bottom, dx: fr.left - sr.left };
     input.focus({ preventScroll: true });
     if (input.value) input.select();
   }
 
+  // v3.17.0 T10 (M-c, was R24): a scroll moves the field with its selection
+  // and keeps its typed text; it closes (back to the toolbar) only when the
+  // selection has left the viewport.
+  function followLinkField() {
+    const f = linkFieldState;
+    if (!f) return;
+    if (!f.root.isConnected) { closeLinkField({ restore: false }); return; }
+    const r = f.range.getBoundingClientRect();
+    if (r.bottom <= toolbarTopInset() || r.top >= window.innerHeight ||
+        r.right <= 0 || r.left >= window.innerWidth) {
+      closeLinkField({ restore: true });
+      return;
+    }
+    f.el.style.top = Math.round(r.bottom + f.dy) + 'px';
+    f.el.style.left = Math.round(r.left + f.dx) + 'px';
+  }
+
   // Takes the field down. `restore` puts the focus and the selection back on
   // the surface and shows the selection toolbar again (Esc, a scroll).
   function closeLinkField(opts) {
@@ -19947,7 +21244,9 @@
     // three classes and the checkbox.
     let checkPress = null; // { el, epoch, snap }: the last press on a task checkbox (R89, R93)
     let degradedPress = null; // { el, epoch, identity }: the last press on a degraded block (R102)
+    let degradedReleaseOpened = false; // T9b (R50): the last press's release already opened its block
     document.addEventListener('mousedown', (e) => {
+      degradedReleaseOpened = false;
       // T21 item 2: pointing at something is the other way (besides pressing a
       // key that is not Tab — see handleBurstKeydown()) of saying the walk is
       // over. A click that lands on the SAME surface the walk arrived at does
@@ -19992,6 +21291,8 @@
       // below and clear the set it just built; one released on the page
       // margin would hit the outside-a-block switchAwayFrom() instead.
       if (blockSelClickSuppressed) { blockSelClickSuppressed = false; return; }
+      // v3.17.0 T9b (R50): the release of this press already answered it.
+      if (degradedReleaseOpened) { degradedReleaseOpened = false; return; }
       if (!e.target || !e.target.closest) { await switchAwayFrom(); closeGutterMenu(); return; }
       // showBanner() appends `.ed-conflict` to document.body — OUTSIDE any
       // .ed-block — so without this guard a click on the banner's own
@@ -20014,6 +21315,14 @@
       // here (closest() still answers on the detached subtree); without this
       // a mouse pick also ran the "outside any block" switchAwayFrom() below.
       if (e.target.closest('.ed-slash-menu')) return;
+      // v3.17.0 T3: the code chips and the language menu handle themselves.
+      if (e.target.closest('.ed-code-chips, .ed-code-langmenu')) return;
+      if (e.target.closest('.ed-imgtb')) return; // v3.17.0 T7: so does the image toolbar
+      // v3.17.0 T5: so does the theme toggle — switching the theme is not
+      // leaving what is being edited (the diagram panel's preview follows the
+      // switch while it stays open). Its press keeps focus where it is too
+      // (the mousedown listener beside the diagram panel).
+      if (e.target.closest('.md2doc-theme-toggle')) return;
       // Task 6 (grip handles): a plain click's own `pointerdown`/`pointerup`
       // pair above already opened the menu — unlike the bubbles/menu
       // buttons, the grips have no `click` listener of their own to
@@ -20028,7 +21337,7 @@
       // "clicked outside any block" and fire switchAwayFrom() on the document
       // behind the modal — and wrong about being a list at all.
       if (waveEditorIsModal()) return;
-      if (e.target.closest('.ed-wave-edit-btn')) return;
+      if (e.target.closest('.ed-wave-edit-btn, .ed-diagram-edit-btn')) return;
       // Task 9: task-list checkbox toggle. The .ed-li-check span is
       // non-focusable chrome — no per-node listener, routed here by
       // delegation. Gate BEFORE mutation (same contract as the structural
@@ -20089,6 +21398,9 @@
         checkPress = null;
         const pressEpoch = press ? press.epoch : reconcileEpoch;
         const snap = press ? press.snap : checkItemSnapshot(li);
+        // v3.17.0 T10 (N2): the caret the press found, read before anything
+        // resolves, so it can be put back once the toggle has landed.
+        const keepCaret = captureCaretBeforeCheckbox(run);
         const ok = await switchAwayFrom();
         if (!ok) return;
         await settleCommits();
@@ -20118,8 +21430,9 @@
         // splitSourceMarkers() strips the old one off the replayed line), and
         // everything after that marker — this item's own continuation lines
         // included — comes back byte-for-byte.
-        await commitListStructure(targetRun, null, false,
+        const toggled = await commitListStructure(targetRun, null, false,
           { carryOver: bystanderCarryOver(targetRun, null) });
+        if (toggled === true) restoreCaretAfterCheckbox(keepCaret);
         return;
       }
       // ⠿ handle: toggles its menu for the block it belongs to. ⠿ menu: its
@@ -20169,9 +21482,7 @@
       // tidier test and is NOT usable: for a synthesized event Chromium still
       // derives offsetX from clientX 0, so it comes back as minus the block's
       // whole left offset and every such click reads as a gutter click.
-      if (blockEl && e.target === blockEl && (e.clientX || e.clientY)) {
-        if (e.clientX < blockEl.getBoundingClientRect().left) blockEl = null;
-      }
+      if (blockEl && pressInGutterBand(e.target, blockEl, e)) blockEl = null;
       if (!blockEl) { await switchAwayFrom(); return; } // clicked outside any block
 
       // Task 5: a table block is now armed exactly like paragraph/heading/
@@ -20186,8 +21497,10 @@
       // (Global Constraint) — no bar, no extra step, same as any other
       // degraded block.
       const editEl = blockContentEl(blockEl);
+      // v3.17.0 T2 (R24): a click inside an open in-place edit is a caret
+      // move inside it, never a commit-and-reopen.
       if ((editEl && (editEl.classList.contains('ed-wys-armed') || editEl.classList.contains('ed-wys-table'))) ||
-          blockEl.querySelector('.ed-raw')) return;
+          blockEl.querySelector('.ed-raw, [data-ed-code-edit], .ed-diagram-panel')) return;
       // Degraded block, not yet open: click swaps in the raw textarea
       // immediately — no bar, no menu step. Still resolve whatever else
       // might be open first, same precondition every other open path uses.
@@ -20215,26 +21528,87 @@
       //    right, and its commit runs the owed redraw first (R86).
       const press = degradedPress && degradedPress.el === blockEl ? degradedPress : null;
       degradedPress = null;
-      const epochAtPress = press ? press.epoch : reconcileEpoch;
-      const identity = press ? press.identity
-        : (commitsSettled() && !reconcileBlocksCommits() ? captureBlockIdentity(blockEl) : null);
-      const ok = await switchAwayFrom();
-      if (!ok) return;
-      await settleCommits();
-      // R104 (final re-review 3, I-R2): found again by content only when it is
-      // the one block of its type with that source — a start line is no proof
-      // (R95's removal of an emptied paragraph shifts lines unlogged, and an
-      // identical quote then sat on the clicked one's line and was opened).
-      const live = blockEl.isConnected ? blockEl : uniqueBlockElBySource(identity);
-      if (!live || reconcileEpoch !== epochAtPress ||
-          (reconcileBlocksCommits() && !blockReadsAsDrawn(live))) {
-        showError(DROPPED_GESTURE_MESSAGE, null, null);
-        return;
-      }
-      openRawEditor(live);
+      await openDegradedBlock(blockEl, press, e, null);
+    });
+    // v3.17.0 T9b (R50): the press that loses its click. Its blur committed
+    // what was being typed, and that commit's render replaced the pressed
+    // block before the button came up — so no click follows at all (the trace
+    // above). The release answers for it: when the block the press recorded
+    // has left the document and the button comes up over a degraded block,
+    // the press opens the block it was on, found again by the identity it
+    // recorded, by the same rules as the click (R102 / R104: unique, else the
+    // retry notice). A click that does follow after all is not a second
+    // gesture (`degradedReleaseOpened`, cleared after the release's task).
+    document.addEventListener('mouseup', (e) => {
+      const press = degradedPress;
+      if (!press || press.el.isConnected || e.button !== 0 || e.shiftKey) return;
+      const t = e.target;
+      if (!t || !t.closest || waveEditorIsModal() || t.closest(ED_LIGHTBOX_TARGETS) ||
+          t.closest('.ed-handle, .ed-insert, .ed-handle-menu, .ed-li-check, .ed-te-grip')) return;
+      const upBlock = t.closest('.ed-block');
+      // T10 (M1): the click router's gutter-band rule, the same predicate.
+      if (!upBlock || pressInGutterBand(t, upBlock, e) || !isDegradedBlock(upBlock)) return;
+      degradedPress = null;
+      degradedReleaseOpened = true;
+      // T10 (M2): the flag answers the click of THIS gesture, which comes in
+      // the same task as the release; a later keyboard or programmatic click
+      // has no press of its own and must not be swallowed.
+      setTimeout(() => { degradedReleaseOpened = false; }, 0);
+      if (gutterMenuBlockEl) closeGutterMenu();
+      if (blockSelection) clearBlockSelection();
+      openDegradedBlock(press.el, press, null, upBlock).catch(showUnexpectedFailure);
     });
   }
 
+  // v2.11.1 / T10 (M1): was the press on the block's own box, left of it (its
+  // 40 px gutter band)? Read only for a target that is the block itself and an
+  // event that carries coordinates (a synthesized click reports 0, 0). One
+  // predicate for the click router and the mouseup release path.
+  function pressInGutterBand(target, blockEl, ev) {
+    return !!blockEl && target === blockEl && !!(ev.clientX || ev.clientY) &&
+      ev.clientX < blockEl.getBoundingClientRect().left;
+  }
+
+  // The degraded block's open (a raw box, or the in-place code edit), from a
+  // click on it (`e`) or from the release of a press whose click was lost
+  // (`upBlock`, the block the button came up over: the gesture is the
+  // release's only while that is the block found again, or a node a later
+  // render replaced in turn).
+  async function openDegradedBlock(blockEl, press, e, upBlock) {
+    const epochAtPress = press ? press.epoch : reconcileEpoch;
+    const identity = press ? press.identity
+      : (commitsSettled() && !reconcileBlocksCommits() ? captureBlockIdentity(blockEl) : null);
+    const topAtClick = blockEl.getBoundingClientRect().top;
+    const ok = await switchAwayFrom();
+    if (!ok) return;
+    await settleCommits();
+    // R104 (final re-review 3, I-R2): found again by content only when it is
+    // the one block of its type with that source — a start line is no proof
+    // (R95's removal of an emptied paragraph shifts lines unlogged, and an
+    // identical quote then sat on the clicked one's line and was opened).
+    const live = refindBlock(blockEl, identity);
+    if (!live || reconcileEpoch !== epochAtPress ||
+        (reconcileBlocksCommits() && !blockReadsAsDrawn(live))) {
+      showError(DROPPED_GESTURE_MESSAGE, null, null);
+      return;
+    }
+    // The release: over another block, or on one something opened meanwhile.
+    if (upBlock && ((live !== upBlock && upBlock.isConnected) ||
+        live.querySelector('.ed-raw, [data-ed-code-edit], .ed-diagram-panel'))) return;
+    // v3.17.0 T2 (D2, R21): a fenced code block edits in place. The click
+    // point places the caret only when the clicked node is still the one on
+    // screen, where it was (R41): a render since the press may have moved or
+    // replaced it, and the point would name other text.
+    if (isFencedCodeBlock(live)) {
+      const samePlace = !!e && live === blockEl && (e.clientX || e.clientY) &&
+        Math.abs(live.getBoundingClientRect().top - topAtClick) < 1;
+      editCodeInPlace(live, samePlace ? { clientX: e.clientX, clientY: e.clientY } : { offset: 0 })
+        .catch(showUnexpectedFailure);
+      return;
+    }
+    openRawEditor(live);
+  }
+
   // ── save ───────────────────────────────────────────────────────────────
   // v3.10.0: the outside-edit check (onDiskMtime() below) must not read its
   // own saves as someone else's edit. A ping answered while a save is in
@@ -20248,10 +21622,13 @@
   // conflict card over the user's own save.
   let saveGen = 0;
   let savesInFlight = 0;
+  let lastSave = null; // v3.17.0 T9b: the newest save's round trip (saveAfterLastSave())
   async function save() {
     saveGen++;
     savesInFlight++;
-    try { return await sendSave(); } finally { savesInFlight--; }
+    const sending = sendSave();
+    lastSave = sending;
+    try { return await sending; } finally { savesInFlight--; }
   }
   async function sendSave() {
     // fix 3: the receipt for the bytes about to leave, taken BEFORE the request
@@ -20353,6 +21730,24 @@
     if (ok) return save();
   }
 
+  // v3.17.0 T9b: a save asked for while an earlier one may still be on its
+  // way — a Ctrl+S held through a code edit's or diagram panel's re-entry, a
+  // second Ctrl+S while the first one's resolution is out — is sent once that
+  // one has answered. Sent alongside it, its request carried the baseline the
+  // first reply was about to replace, the server answered 409 (sendSave()'s
+  // note says why) and the conflict card went up over a file this page had
+  // just saved. A queue in the caller, not a lock in sendSave(): those callers
+  // asked for their save while the first was not even sent yet, whereas a
+  // Ctrl+S pressed on its own while a save is out still sends at once
+  // (test/editor-journey.test.js's N5-two-saves drives that path), and no
+  // save waits behind a request that never answers unless it was queued here.
+  function saveAfterLastSave() {
+    const prev = lastSave;
+    const next = (prev ? prev.then(() => {}, () => {}) : Promise.resolve()).then(() => save());
+    lastSave = next;
+    return next;
+  }
+
   // v3.4.0 §3: the save button's own caret rescue. commitThenSave() above
   // may resolve (commit + re-render) a still-open burst before save() ever
   // runs, and that render is exactly the class of render that strands the
@@ -20620,7 +22015,24 @@
   // intra-burst mechanism that never reaches this file's undo()/redo() at
   // all. Widening either of those was out of this task's scope, the same
   // boundary saveViaToolbar()'s own comment draws around Ctrl+S.
+  // (Since v3.17.0 T10 the button does take those two intra-edit routes when
+  // an edit is open, below; Ctrl+Z / Ctrl+Y outside one are unchanged.)
   async function undoViaToolbar() {
+    // v3.17.0 T10 (L95b): inside an open code edit the button steps the edit's
+    // own text history, and inside an open paragraph, heading or list item it
+    // steps the burst, exactly as Ctrl+Z does there. It never commits what is
+    // open first and then undoes the whole commit (a transient typed into
+    // vanished entirely that way).
+    if (codeEditIsOpen()) { stepCodeEditHistory(codeEditState, -1); return; }
+    const b = currentBurst;
+    if (b && b.editEl && b.blockType !== 'table' && b.editEl.isConnected &&
+        b.editEl.contains(document.activeElement) && burstHasUncommittedEdit()) {
+      // Only with typing to step back through: an untouched burst (an empty
+      // transient left standing after Ctrl+S, say) leaves the button the
+      // document undo it always was.
+      burstUndo(b.editEl);
+      return;
+    }
     const saved = captureCaretForSave();
     await undo();
     restoreCaretForSave(saved);
@@ -21685,7 +23097,7 @@
   // carrying the anchor as a stable IDENTITY that is re-resolved when the
   // files come back, instead of as a node reference. The identity triple is
   // insertBlockBelow()'s (captureBlockIdentity / ownsOpenSession /
-  // reresolveBlockEl + reresolveBlockElAfterSelfCommit) — that function solved
+  // refindBlock + reresolveBlockElAfterSelfCommit) — that function solved
   // this same problem for its own anchor and the image path simply never
   // adopted it. Do not "simplify" the re-resolution away: it is the half that
   // survives the dialog.
@@ -21707,16 +23119,14 @@
     if (!blockEl) return;
     const identity = captureBlockIdentity(blockEl);
     // The commit inside switchAwayFrom() can be a rewrite of THIS block's own
-    // source, in which case reresolveBlockEl()'s fingerprint is guaranteed to
+    // source, in which case refindBlock()'s fingerprint is guaranteed to
     // miss because WE are the reason the source changed; the narrowed
     // re-resolve is used only then. Same reasoning as insertBlockBelow().
     const selfSession = ownsOpenSession(blockEl);
     if (!(await switchAwayFrom())) return;
-    const anchorEl = (blockEl && document.body.contains(blockEl))
-      ? blockEl
-      : (reresolveBlockEl(identity) ||
-        (selfSession ? reresolveBlockElAfterSelfCommit(identity) : null));
-    if (!anchorEl) { showNotice(TOOLBAR_NO_ANCHOR_MESSAGE); return; }
+    const anchorEl = refindBlock(blockEl, identity, selfSession);
+    // Fix round 1 (I1, R35): the retry notice, as every re-find refusal.
+    if (!anchorEl) { showError(DROPPED_GESTURE_MESSAGE, null, null); return; }
     // Re-captured AFTER the commit: `identity` above holds the PRE-commit
     // fingerprint, which the commit we just awaited may itself have
     // invalidated. What has to survive the dialog is the anchor as it stands
@@ -21729,9 +23139,8 @@
       // it was — refuse (and skip the upload, so no orphan lands in the
       // user's assets/) rather than silently appending at EOF, which is the
       // very symptom being fixed.
-      const live = document.body.contains(anchorEl)
-        ? anchorEl : reresolveBlockEl(dialogIdentity);
-      if (!live) { showNotice(TOOLBAR_NO_ANCHOR_MESSAGE); return; }
+      const live = refindBlock(anchorEl, dialogIdentity);
+      if (!live) { showError(DROPPED_GESTURE_MESSAGE, null, null); return; }
       insertImages(files, live);
     });
   }
@@ -21739,7 +23148,7 @@
   // The hidden file input both image paths open; `onFiles` gets the picked
   // files (never called for an empty pick). v3.15.0 B1 fix: shared with
   // pickImageIntoParagraph().
-  function openImagePicker(onFiles) {
+  function openImagePicker(onFiles, { multiple = true } = {}) {
     const input = document.createElement('input');
     input.type = 'file';
     // v3.4.1: extension tokens sit beside the MIME tokens deliberately.
@@ -21749,7 +23158,7 @@
     // button that could not pick one. Mixing the two token kinds is what
     // the attribute is specified for.
     input.accept = 'image/png,image/jpeg,image/gif,image/webp,.drawio,.xml';
-    input.multiple = true;
+    input.multiple = multiple;
     input.hidden = true;
     // (a) in pickAndInsertImage()'s comment.
     input.addEventListener('click', (e) => e.stopPropagation());
@@ -21807,6 +23216,14 @@
       if (!images.length) return; // not ours: let the page do whatever it would
       e.preventDefault();
       const anchorEl = (e.target && e.target.closest) ? e.target.closest('.ed-block') : null;
+      // D18 (v3.17.0): a raster picture dropped ON a picture replaces it (the
+      // first file only, one op). A .drawio drop keeps inserting.
+      if (anchorEl && isImageBlock(anchorEl) && isRasterImageFile(images[0])) {
+        // v3.17.0 T9a (R61): a throw (an upload that rejects) is reported,
+        // never left as an unhandled rejection.
+        replaceImageIn(anchorEl, images[0]).catch(showUnexpectedFailure);
+        return;
+      }
       insertImages(images, anchorEl || liveToolbarBlock() || lastBlockEl());
     });
   }
@@ -22341,6 +23758,13 @@
       // — nothing is duplicated here beyond this one line shape, and
       // save()'s own body is still called exactly once, from inside
       // commitThenSave() when the toolbar path runs it.
+      //
+      // v3.17.0 T9b: a resolution already out (a second Ctrl+S while the
+      // first one's commit renders): this press waits for the same
+      // resolution and then saves after the newest save, never alongside it.
+      // Both presses used to get the one cached `switching` promise and run
+      // two save()s back to back, and the second 409'd into the conflict card.
+      if (switching) { switching.then((ok) => { if (ok) saveAfterLastSave(); }); return; }
       switchAwayFrom().then((ok) => { if (ok) save(); });
       return;
     }
@@ -22349,6 +23773,11 @@
     // Ctrl+Z / Ctrl+Y undo its own text, never the document. Ahead of every
     // undo/redo branch below, which is left as it was.
     if (e.target && e.target.closest && e.target.closest('.ed-linkbar')) return;
+    // v3.17.0 T2 (R25, D3): the same for the in-place code edit — its own
+    // keydown listener has already answered Enter / Tab / Esc / undo / redo,
+    // and nothing below (the document undo, Tab, the block keys) may act on
+    // the rest. Ctrl+S above still commits it and saves.
+    if (ownsOwnKeys(e.target)) return;
     // v3.15.0 T5: Ctrl/Cmd+K opens the URL field.
     if (linkShortcutKeydown(e)) return;
 
@@ -22526,7 +23955,15 @@
         if (from && members.length === 1 && !waveDiagramInside(from)) {
           e.preventDefault();
           clearBlockSelection();
-          openRawViaGutter(from);
+          // A Graphviz / Mermaid block opens its panel; a dot block whose
+          // bake failed is a plain code block and takes the raw box.
+          // v3.17.0 T9a (R60): a throw is reported like the 編輯圖表 button's,
+          // and a block that turns out not to open a panel gets its
+          // selection back instead of leaving nothing selected and nothing
+          // open.
+          if (isDiagramBlock(from) !== null) {
+            openDiagramPanelFromGesture(from, { reselect: true }).catch(showUnexpectedFailure);
+          } else openRawViaGutter(from);
           return;
         }
       }
@@ -22824,6 +24261,20 @@
     // own per-instance listener (unchanged); this adds the blur trigger on
     // top of it, through the same switchAwayFrom()/activeEditor path every
     // other commit route in this file already uses.
+    // v3.17.0 T2: focus leaving the in-place code edit resolves it through the
+    // same switchAwayFrom() — committed when changed, ended with no write when
+    // not. A session a render or its own commit already let go of (it cleared
+    // `activeEditor` before the write that blurred the host) is left alone.
+    const codeHost = e.target && e.target.matches && e.target.matches('pre[data-ed-code-edit]') ? e.target : null;
+    if (codeHost) {
+      const s = codeEditState;
+      if (!s || s.host !== codeHost || activeEditor !== s.editor) return;
+      if (e.relatedTarget && codeHost.contains(e.relatedTarget)) return;
+      // v3.17.0 T3: the language filter takes focus without ending the edit.
+      if (e.relatedTarget && e.relatedTarget.closest && e.relatedTarget.closest('.ed-code-langmenu')) return;
+      switchAwayFrom();
+      return;
+    }
     const ta = e.target && e.target.matches && e.target.matches('textarea.ed-raw') ? e.target : null;
     if (!ta) return;
     const blockEl = ta.closest('.ed-block');
@@ -23247,9 +24698,10 @@
     // v3.15.0 T1 (R24): a scroll closes the "/" menu — except the menu's own
     // list scrolling its cursor into view.
     if (slashMenu && !(e && e.target && e.target.nodeType === 1 && slashMenu.el.contains(e.target))) closeSlashMenu();
-    // v3.15.0 T5 (R24): so does the URL field — back to the toolbar over the
-    // selection, which the rest of this function then repositions.
-    if (linkFieldState) closeLinkField({ restore: true });
+    // v3.15.0 T5 (R24), changed in v3.17.0 T10 (M-c): the URL field follows
+    // its selection and closes (back to the toolbar over the selection, which
+    // the rest of this function then repositions) only when it left the view.
+    if (linkFieldState) followLinkField();
     // v3.15.0 T6 (R24): and the link card.
     hideLinkCard();
     if (tePointer && tePointer.dragging) return;   // 拖曳中不動
@@ -23945,6 +25397,7 @@
 
   armEditables(contentEl);
   wireBlockSelection();
+  wireCodeEditReenterHold();
 
   // ── v3.4.0 batch3 Task 6: the wavedrom editing surface ─────────────────
   //
@@ -24156,6 +25609,906 @@
   }, true);
   window.addEventListener('scroll', () => { if (waveEditor === null) hideWaveEditBtn(); }, true);
 
+  // ── v3.17.0 T4: the 編輯圖表 button on Graphviz and Mermaid blocks (E8) ──
+  // A fixed singleton on document.body, never inside .content (the wave
+  // button's reason), at the top-right of the diagram the pointer is over. A
+  // diagram block is a fenced block whose rendered first child is the
+  // graphviz or mermaid div; it has no code chips (those need a pre), so the
+  // two hover paths cannot both fire on one block. The click opens the
+  // diagram panel (openDiagramPanel(), T5).
+  const diagramEditBtn = document.createElement('button');
+  diagramEditBtn.type = 'button';
+  diagramEditBtn.className = 'ed-diagram-edit-btn';
+  diagramEditBtn.title = '編輯這張圖表的原始碼，並即時預覽';
+  diagramEditBtn.hidden = true;
+  diagramEditBtn.insertAdjacentHTML('beforeend', codeChipIcon('pencil'));
+  const diagramEditLabel = document.createElement('span');
+  diagramEditLabel.textContent = '編輯圖表';
+  diagramEditBtn.appendChild(diagramEditLabel);
+  document.body.appendChild(diagramEditBtn);
+  let diagramEditBlock = null; // the .ed-block the button is drawn for
+
+  // 'dot' | 'mermaid' | null. An allow-list on the rendered first child: a
+  // dot block whose bake failed renders a pre and is an ordinary code block.
+  function isDiagramBlock(blockEl) {
+    if (!blockEl || typeof blockEl.getAttribute !== 'function' ||
+        blockEl.getAttribute('data-block-type') !== 'code') return null;
+    const first = blockEl.firstElementChild;
+    if (!first || !first.classList) return null;
+    if (first.classList.contains('graphviz')) return 'dot';
+    if (first.classList.contains('mermaid')) return 'mermaid';
+    return null;
+  }
+
+
+  // After a render: a block the render replaced takes its button with it.
+  function reconcileDiagramEditBtn() {
+    if (diagramEditBlock !== null && !diagramEditBlock.isConnected) hideDiagramEditBtn();
+  }
+
+  function hideDiagramEditBtn() {
+    if (diagramEditBlock === null && diagramEditBtn.hidden) return;
+    diagramEditBlock = null;
+    diagramEditBtn.hidden = true;
+  }
+
+  function showDiagramEditBtnFor(blockEl) {
+    if (waveEditorIsModal() || !blockEl || !blockEl.isConnected || isDiagramBlock(blockEl) === null ||
+        blockEl.querySelector('.ed-raw, .ed-diagram-panel')) { hideDiagramEditBtn(); return; }
+    if (diagramEditBlock === blockEl && !diagramEditBtn.hidden) return;
+    const r = blockEl.firstElementChild.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) { hideDiagramEditBtn(); return; }
+    diagramEditBlock = blockEl;
+    diagramEditBtn.hidden = false;
+    // The wave button's formula: nudged inside the diagram, never under the
+    // toolbar band, never off the viewport.
+    diagramEditBtn.style.top = Math.round(Math.max(toolbarTopInset() + 4, r.top + 6)) + 'px';
+    diagramEditBtn.style.left = Math.round(Math.max(4,
+      Math.min(r.right - diagramEditBtn.offsetWidth - 6,
+               document.documentElement.clientWidth - diagramEditBtn.offsetWidth - 6))) + 'px';
+  }
+
+  document.addEventListener('mouseover', (ev) => {
+    const t = ev.target;
+    if (!t || typeof t.closest !== 'function') return;
+    if (t.closest('.ed-diagram-edit-btn')) return;
+    const blk = t.closest('.ed-block[data-block-type="code"]');
+    if (blk && isDiagramBlock(blk) !== null) showDiagramEditBtnFor(blk); else hideDiagramEditBtn();
+  }, true);
+  document.addEventListener('scroll', () => { hideDiagramEditBtn(); }, { passive: true, capture: true });
+  window.addEventListener('resize', () => { hideDiagramEditBtn(); });
+  // A press on the button never moves focus; the click opens the panel.
+  diagramEditBtn.addEventListener('mousedown', (e) => { e.preventDefault(); });
+  diagramEditBtn.addEventListener('click', () => {
+    const blk = diagramEditBlock;
+    if (!blk || !blk.isConnected) { hideDiagramEditBtn(); return; }
+    hideDiagramEditBtn();
+    openDiagramPanelFromGesture(blk).catch(showUnexpectedFailure);
+  });
+
+  // ── v3.17.0 T7: the image toolbar (D16, D18) ──────────────────────────
+  //
+  // A paragraph that is one image and nothing else (isImageBlock) gets 替換,
+  // 替代文字 and 刪除 while the pointer is over it: a fixed singleton on
+  // document.body, never inside .content, 8 px inside the image's top-left,
+  // the link card's look. It goes 300 ms after the pointer leaves both the
+  // image block and itself, and at once on scroll, resize and render. Every
+  // press on it calls preventDefault() on mousedown (the edit keeps focus)
+  // except the alt-text input, which takes it. 替換 and 替代文字 rewrite
+  // only the destination or the brackets of the one source line
+  // (inlineMd.rewriteImage, D17), as one op each; 刪除 is the block's own
+  // delete. A click on the picture itself still opens the lightbox: the
+  // toolbar sits over the image's corner, it does not change the click
+  // routing.
+  const IMGTB_INSET_PX = 8;
+  const IMGTB_HIDE_MS = 300;
+  const IMGTB_NOT_RASTER_MESSAGE = '只能用圖片檔替換';
+  const imgTb = document.createElement('div');
+  imgTb.className = 'ed-imgtb';
+  imgTb.hidden = true;
+  const imgTbButtons = document.createElement('div');
+  imgTbButtons.className = 'ed-imgtb-btns';
+  imgTb.appendChild(imgTbButtons);
+  function addImgTbButton(label, extraClass, onClick) {
+    const b = document.createElement('button');
+    b.type = 'button';
+    b.className = 'ed-imgtb-btn' + (extraClass ? ' ' + extraClass : '');
+    b.textContent = label;
+    b.addEventListener('click', (e) => { e.stopPropagation(); onClick(); });
+    imgTbButtons.appendChild(b);
+    return b;
+  }
+  const imgTbInput = document.createElement('input');
+  imgTbInput.type = 'text';
+  imgTbInput.className = 'ed-imgtb-input';
+  imgTbInput.placeholder = '替代文字';
+  imgTbInput.setAttribute('aria-label', '替代文字');
+  imgTbInput.hidden = true;
+  imgTb.appendChild(imgTbInput);
+  document.body.appendChild(imgTb);
+  let imgTbBlock = null;      // the .ed-block the toolbar is drawn for
+  let imgTbHideTimer = null;
+  let imgTbAlt = null;        // { identity, original } while the input is showing
+
+  // An image block: a paragraph whose source is one image (D16) and whose
+  // rendered content is exactly one img. .drawio / .xml keep their own flow.
+  function isImageBlock(blockEl) {
+    if (!blockEl || typeof blockEl.getAttribute !== 'function' || !inlineMd ||
+        typeof inlineMd.parseImageParagraph !== 'function' ||
+        blockEl.getAttribute('data-block-type') !== 'paragraph') return false;
+    const rec = blockRecOf(blockEl);
+    if (!rec || rec.endLine < rec.startLine) return false;
+    const parsed = inlineMd.parseImageParagraph(blockSourceOf(rec));
+    if (!parsed || /\.(drawio|xml)([?#].*)?$/i.test(parsed.dest)) return false;
+    const surface = blockContentEl(blockEl);
+    return !!surface && surface.children.length === 1 && surface.firstElementChild.tagName === 'IMG' &&
+      surface.textContent.trim() === '';
+  }
+  // A pick for 替換 must be a picture a browser draws; the picker's list also
+  // names .drawio and .xml, which belong to the insert flow.
+  function isRasterImageFile(file) {
+    const type = String((file && file.type) || '');
+    if (type) return /^image\/(png|jpe?g|gif|webp)$/i.test(type);
+    return /\.(png|jpe?g|gif|webp)$/i.test(String((file && file.name) || ''));
+  }
+
+  function cancelImageToolbarHide() {
+    if (imgTbHideTimer !== null) { clearTimeout(imgTbHideTimer); imgTbHideTimer = null; }
+  }
+  function scheduleImageToolbarHide() {
+    if (imgTb.hidden || imgTbAlt || imgTbHideTimer !== null) return;
+    imgTbHideTimer = setTimeout(() => { imgTbHideTimer = null; if (!imgTbAlt) hideImageToolbar(); }, IMGTB_HIDE_MS);
+  }
+  function hideImageToolbar() {
+    cancelImageToolbarHide();
+    const wasAlt = imgTbAlt;
+    imgTbAlt = null;
+    imgTbBlock = null;
+    if (wasAlt) {
+      imgTbInput.hidden = true;
+      imgTbButtons.hidden = false;
+      if (document.activeElement === imgTbInput) imgTbInput.blur();
+    }
+    if (imgTb.hidden) return;
+    imgTb.hidden = true;
+  }
+  function reconcileImageToolbar() {
+    if (imgTbBlock !== null && !imgTbBlock.isConnected) hideImageToolbar();
+  }
+  function placeImageToolbar(blockEl) {
+    const img = blockEl.querySelector('img');
+    const r = img ? img.getBoundingClientRect() : null;
+    if (!r || (r.width === 0 && r.height === 0)) { hideImageToolbar(); return false; }
+    imgTb.hidden = false;
+    const top = Math.max(r.top + IMGTB_INSET_PX, toolbarTopInset() + 4);
+    if (top > r.bottom - 4) { hideImageToolbar(); return false; }
+    imgTb.style.top = Math.round(top) + 'px';
+    imgTb.style.left = Math.round(Math.max(4, Math.min(r.left + IMGTB_INSET_PX,
+      document.documentElement.clientWidth - imgTb.offsetWidth - 4))) + 'px';
+    return true;
+  }
+  function showImageToolbarFor(blockEl) {
+    if (waveEditorIsModal() || !blockEl || !blockEl.isConnected || !isImageBlock(blockEl)) { hideImageToolbar(); return; }
+    cancelImageToolbarHide();
+    if (imgTbAlt && imgTbBlock !== blockEl) return; // the input owns the toolbar
+    if (imgTbBlock === blockEl && !imgTb.hidden) return;
+    imgTbBlock = blockEl;
+    placeImageToolbar(blockEl);
+  }
+
+  // The one path that writes an image edit: the block found again after
+  // everything that could have moved it (R104: by source, and only when it is
+  // the one such block), one commitRangeEdit over its line, nothing written
+  // when the source reads the same. false: refused or the render failed.
+  async function applyImageEdit(blockEl, identity, patch) {
+    if (!identity || !inlineMd) return false;
+    await settleCommits();
+    const ok = await switchAwayFrom();
+    if (!ok) return false;
+    let el = blockEl && blockEl.isConnected ? blockEl : null;
+    let rec = el ? blockRecOf(el) : null;
+    if (!rec || blockSourceOf(rec) !== identity.source || identity.reconcileEpoch !== reconcileEpoch) {
+      el = uniqueBlockElBySource(identity);
+      rec = el ? blockRecOf(el) : null;
+    }
+    if (!el || !rec || reconcileBlocksCommits()) { showError(DROPPED_GESTURE_MESSAGE, null, null); return false; }
+    const source = blockSourceOf(rec);
+    const next = inlineMd.rewriteImage(source, patch);
+    if (next === source) return true;
+    const r = await commitFencedRangeAndRender(rec.startLine, rec.endLine, next);
+    return r === true;
+  }
+
+  // 替換 (and T8's drop): the picked file replaces the picture, keeping alt
+  // and title. A file that is not a raster picture writes nothing (R39).
+  //
+  // `identity` (final review I1): 替換 passes the block as captured at the
+  // click, from a node on screen then (pickReplacementImage()). The node held
+  // across the file dialog may since have been replaced by a render, and the
+  // data-block-id it still carries then names whatever block holds that id
+  // NOW: measured before this, a paragraph committed above two pictures while
+  // the dialog was open, and the pick replaced the picture ABOVE the one
+  // pointed at, with no notice (or, on a block that is not a picture, was
+  // ignored, its upload left behind). So the block is found again with
+  // refindBlock(), the one rule the rest of the editor uses, and a block that
+  // cannot be found is refused with the retry notice before anything is
+  // uploaded. A drop passes no identity: its node is on screen at the drop.
+  async function replaceImageIn(blockEl, file, identity) {
+    if (!blockEl || !file) return false;
+    if (!isRasterImageFile(file)) { showNotice(IMGTB_NOT_RASTER_MESSAGE); return false; }
+    let el = null;
+    if (identity) {
+      await settleCommits();
+      el = refindBlock(blockEl, identity);
+    } else {
+      el = await settledGestureBlock(blockEl);
+      if (!el) return false; // refused, and said so, by settledGestureBlock()
+    }
+    const live = el && el.isConnected && isImageBlock(el) ? captureBlockIdentity(el) : null;
+    if (!live) { showError(DROPPED_GESTURE_MESSAGE, null, null); return false; }
+    const path = await uploadImageBlob(file);
+    if (!path) return false;
+    return applyImageEdit(el, live, { dest: markdownImageDest(path) });
+  }
+
+  function exitImageAltMode() {
+    if (!imgTbAlt) return;
+    imgTbAlt = null;
+    imgTbInput.hidden = true;
+    imgTbButtons.hidden = false;
+    if (document.activeElement === imgTbInput) imgTbInput.blur();
+    if (imgTbBlock) placeImageToolbar(imgTbBlock);
+    scheduleImageToolbarHide();
+  }
+  async function openImageAltMode() {
+    const first = imgTbBlock;
+    if (!first || imgTbAlt) return;
+    cancelImageToolbarHide();
+    const el = await settledGestureBlock(first);
+    if (!el) { hideImageToolbar(); return; }
+    const identity = captureBlockIdentity(el);
+    const ok = await switchAwayFrom();
+    if (!ok) { hideImageToolbar(); return; }
+    const live = el.isConnected ? el : uniqueBlockElBySource(identity);
+    if (!live || !isImageBlock(live)) { hideImageToolbar(); showError(DROPPED_GESTURE_MESSAGE, null, null); return; }
+    const parsed = inlineMd.parseImageParagraph(blockSourceOf(blockRecOf(live)));
+    imgTbBlock = live;
+    imgTbAlt = { identity: captureBlockIdentity(live), original: parsed.alt };
+    imgTbButtons.hidden = true;
+    imgTbInput.hidden = false;
+    imgTbInput.value = parsed.alt;
+    if (!placeImageToolbar(live)) return;
+    imgTbInput.focus({ preventScroll: true });
+    imgTbInput.select();
+  }
+  imgTbInput.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape') { e.preventDefault(); e.stopPropagation(); exitImageAltMode(); return; }
+    if (e.key !== 'Enter' || e.isComposing) return;
+    e.preventDefault();
+    e.stopPropagation();
+    const alt = imgTbAlt;
+    const blk = imgTbBlock;
+    const value = imgTbInput.value;
+    hideImageToolbar();
+    if (!alt || value === alt.original) return;
+    applyImageEdit(blk, alt.identity, { alt: value }).catch(showUnexpectedFailure);
+  });
+  imgTbInput.addEventListener('blur', () => { if (imgTbAlt) exitImageAltMode(); });
+
+  // Final review I1: the 🖼 path's order (pickAndInsertImage()). The press
+  // resolves any open session first and takes the block's identity while its
+  // node is on screen; the dialog's callback finds the block again by that
+  // identity (replaceImageIn()), never by the node it held across the dialog.
+  async function pickReplacementImage(blk) {
+    const el = await settledGestureBlock(blk);
+    if (!el) return;
+    const identity = captureBlockIdentity(el);
+    const selfSession = ownsOpenSession(el);
+    if (!(await switchAwayFrom())) return;
+    const live = refindBlock(el, identity, selfSession);
+    if (!live || !isImageBlock(live)) { showError(DROPPED_GESTURE_MESSAGE, null, null); return; }
+    const dialogIdentity = captureBlockIdentity(live);
+    openImagePicker(async (files) => { await replaceImageIn(live, files[0], dialogIdentity); }, { multiple: false });
+  }
+  addImgTbButton('替換', '', () => {
+    const blk = imgTbBlock;
+    hideImageToolbar();
+    if (!blk || !blk.isConnected) return;
+    pickReplacementImage(blk).catch(showUnexpectedFailure);
+  });
+  addImgTbButton('替代文字', '', () => { openImageAltMode().catch(showUnexpectedFailure); });
+  addImgTbButton('刪除', 'ed-imgtb-delete', () => {
+    const blk = imgTbBlock;
+    hideImageToolbar();
+    if (!blk || !blk.isConnected) return;
+    clearBlockSelection();
+    deleteBlockViaGutter(blk).catch(showUnexpectedFailure);
+  });
+
+  // Presses keep focus where it is; the alt input is the one thing that takes it.
+  imgTb.addEventListener('mousedown', (e) => { if (e.target !== imgTbInput) e.preventDefault(); });
+  document.addEventListener('mouseover', (ev) => {
+    const t = ev.target;
+    if (!t || typeof t.closest !== 'function' || imgTbAlt) return;
+    if (t.closest('.ed-imgtb')) { cancelImageToolbarHide(); return; }
+    const blk = t.closest('.ed-block[data-block-type="paragraph"]');
+    if (blk && isImageBlock(blk)) showImageToolbarFor(blk); else scheduleImageToolbarHide();
+  }, true);
+  document.documentElement.addEventListener('mouseleave', () => { scheduleImageToolbarHide(); });
+  document.addEventListener('scroll', (ev) => {
+    if (ev.target === imgTbInput || imgTb.contains(ev.target)) return;
+    hideImageToolbar();
+  }, { passive: true, capture: true });
+  window.addEventListener('resize', () => { hideImageToolbar(); });
+
+  // ── v3.17.0 T5: the diagram panel — the source and a live preview (D15) ──
+  //
+  // 編輯圖表 replaces the block's content in place, the raw box's way (the
+  // rendered HTML is kept to put back on Esc): a header (Graphviz / Mermaid,
+  // the hint, 完成), the source in a textarea, the preview, and one message
+  // line under it. Inside the block, never a fixed overlay on body: the panel
+  // is the block while it is open.
+  //
+  // It is an `activeEditor`, so switchAwayFrom(), a click elsewhere, undo /
+  // redo and the flight guard resolve it as they resolve the raw box and the
+  // in-place code edit. 完成, Ctrl/Cmd+Enter and focus leaving the panel
+  // commit: one commitRangeEdit over the whole fenced range, the fence lines
+  // and info string kept (unchanged → no op, no undo step). Esc discards. Its
+  // commit keeps the eight obligations of openRawEditor()'s commit() and
+  // cancelAndMaybeDiscard() (R27), through commitFencedRangeAndRender(), which
+  // it shares with the code edit. Ctrl+S commits, saves and opens the panel
+  // again where the caret was (R48 / R56 (c)).
+  //
+  // Preview (D15): 500 ms after the last input, and once on open. Graphviz
+  // asks POST /api/preview (stateless: never /api/render, which records the
+  // document's draw.io references); Mermaid renders in the browser through
+  // md2docTheme.renderMermaid(), on the theme runtime's serial chain (D13). A
+  // sequence number drops every answer but the newest request's, so a slow
+  // older answer never replaces a newer one. An error, or an answer with
+  // nothing to draw (an empty source, an empty svg: R56 (a)), keeps the last
+  // good svg under .is-stale and says so on the message line. The preview
+  // carries neither .graphviz nor .mermaid: the lightbox, adoptMermaids() and
+  // the recolour observer key on those. Graphviz is recoloured here, and again
+  // on a theme switch; Mermaid is drawn again in the new theme.
+  const DIAGRAM_PREVIEW_MS = 500;
+  const DIAGRAM_PREVIEW_FAILED = '預覽失敗（伺服器沒有回應）';
+  const DIAGRAM_PREVIEW_EMPTY = '沒有可預覽的內容';
+  const DIAGRAM_NO_MERMAID = '預覽失敗（Mermaid 引擎沒有載入）';
+  const DIAGRAM_LANG_LABEL = { dot: 'Graphviz', mermaid: 'Mermaid' };
+
+  // The open panel, or null. A render that replaced its block, or cleared
+  // `activeEditor` for it, has ended it; its timer, listeners and theme
+  // subscription go with it.
+  function liveDiagramPanel() {
+    const s = diagramPanelState;
+    if (!s) return null;
+    if (activeEditor === s.editor && s.panel.isConnected) return s;
+    diagramPanelState = null;
+    disposeDiagramPanel(s);
+    return null;
+  }
+  function disposeDiagramPanel(s) {
+    if (s.timer) { clearTimeout(s.timer); s.timer = null; }
+    s.previewSeq++; // an answer still out lands nowhere
+    s.listeners.abort();
+    if (s.offTheme) { s.offTheme(); s.offTheme = null; }
+  }
+  function diagramThemeIsDark() {
+    const t = window.md2docTheme;
+    return !!(t && typeof t.isDark === 'function' && t.isDark());
+  }
+  function firstLineOf(text) {
+    return String(text === undefined || text === null ? '' : text).split('\n')[0].trim();
+  }
+
+  // The block's lines for `text`: the opening and closing fence lines as they
+  // were, unless the text holds a run of the fence character that needs a
+  // longer fence (D10's rule); an unterminated fence gets its closing line.
+  function diagramFenceLines(s, text) {
+    const f = s.fence;
+    const body = text.split('\n');
+    const built = codeEditLib.buildFence({ indent: f.indent, char: f.char, open: f.open, info: f.info, body });
+    if (built[0].length - f.indent.length - f.info.length !== f.open) return built;
+    const src = s.source.split('\n');
+    return [src[0]].concat(body, [f.closed ? src[1 + f.body.length] : built[built.length - 1]]);
+  }
+  // R23: the session by value in the raw box's shape, the whole fenced block.
+  function diagramPanelSnapshot(s) {
+    const built = diagramFenceLines(s, s.ta.value);
+    return { blockId: s.blockId, range: null, startLine: s.startLine, endLine: s.endLine, source: s.source,
+      value: built.join('\n'), caret: built[0].length + 1 + s.ta.selectionStart };
+  }
+
+  // The panel's language for a block: what isDiagramBlock() reads from the
+  // render, or — only for the Ctrl+S re-entry (`want`, the language of the
+  // panel being reopened) — the fence's info string when the render is not
+  // a diagram. A dot source with a syntax error renders as plain code (the
+  // bake's fallback), and the panel must still open again on it (fix round
+  // 1, I1).
+  const DIAGRAM_INFO_KIND = { dot: 'dot', graphviz: 'dot', mermaid: 'mermaid' };
+  function diagramPanelKindOf(blockEl, want) {
+    const kind = isDiagramBlock(blockEl);
+    if (kind || !want || !codeEditLib || !blockEl || blockEl.getAttribute('data-block-type') !== 'code') return kind;
+    const rec = blockRecOf(blockEl);
+    if (!rec || rec.endLine < rec.startLine) return null;
+    const f = codeEditLib.parseFence(lines.slice(rec.startLine - 1, rec.endLine));
+    const word = f ? f.info.split(/\s+/)[0].toLowerCase() : '';
+    return DIAGRAM_INFO_KIND[word] === want ? want : null;
+  }
+
+  // Opens the panel on a Graphviz or Mermaid block. false when it is not one
+  // (or has no fenced source); true otherwise, including when another session
+  // could not be resolved (it stays open with its banner) or the block went
+  // away meanwhile (notice). `opts.seed` ({ value, selStart, selEnd,
+  // previewHtml }) is the Ctrl+S re-entry: the text the old panel held, which
+  // may be ahead of the file; `opts.kind` is that panel's language.
+  async function openDiagramPanel(blockEl, opts) {
+    const o = opts || {};
+    let kind = diagramPanelKindOf(blockEl, o.kind);
+    if (!kind || !codeEditLib) return false;
+    // openRawEditor()'s Task G guard: every other session is resolved BEFORE
+    // this one registers, so the focusout that focusing the source raises
+    // finds nothing to resolve. The 編輯圖表 press keeps focus where it was,
+    // so focus is taken off first: a surface that keeps focus can open its
+    // burst again after the resolution (measured: the empty transient a "/"
+    // insert leaves below the diagram), and its focusout on ta.focus() below
+    // then resolved the brand-new, untouched panel — closed in the gesture
+    // that opened it. The blur's own focusout starts that resolution now,
+    // and the switchAwayFrom() below joins it.
+    const ae = document.activeElement;
+    if (ae && ae !== document.body && !blockEl.contains(ae) && typeof ae.blur === 'function') ae.blur();
+    if (switching || (activeEditor && activeEditor.blockEl !== blockEl) ||
+        (currentBurst && currentBurst.blockEl !== blockEl)) {
+      const ok = await switchAwayFrom();
+      if (!ok) return true;
+      if (!blockEl.isConnected) { showError(DROPPED_GESTURE_MESSAGE, null, null); return true; }
+      kind = diagramPanelKindOf(blockEl, o.kind);
+      if (!kind) return false;
+    }
+    const rec = blockRecOf(blockEl);
+    if (!rec || rec.endLine < rec.startLine) return false;
+    const source = lines.slice(rec.startLine - 1, rec.endLine).join('\n');
+    const fence = codeEditLib.parseFence(source.split('\n'));
+    if (!fence) return false;
+    const body = fence.body.join('\n');
+
+    const panel = document.createElement('div');
+    panel.className = 'ed-diagram-panel';
+    const head = document.createElement('div');
+    head.className = 'ed-diagram-head';
+    const langEl = document.createElement('span');
+    langEl.className = 'ed-diagram-lang';
+    langEl.textContent = DIAGRAM_LANG_LABEL[kind];
+    const hint = document.createElement('span');
+    hint.className = 'ed-diagram-hint';
+    hint.textContent = '預覽在停止輸入 0.5 秒後更新';
+    const done = document.createElement('button');
+    done.type = 'button';
+    done.className = 'ed-diagram-done';
+    done.textContent = '完成';
+    head.appendChild(langEl);
+    head.appendChild(hint);
+    head.appendChild(done);
+    const ta = document.createElement('textarea');
+    ta.className = 'ed-diagram-src';
+    ta.spellcheck = false;
+    ta.setAttribute('aria-label', DIAGRAM_LANG_LABEL[kind] + ' 原始碼');
+    ta.value = o.seed ? o.seed.value : body;
+    const preview = document.createElement('div');
+    preview.className = 'ed-diagram-preview';
+    preview.tabIndex = -1; // R36: a press on it may take focus, inside the panel
+    if (o.seed && o.seed.previewHtml) preview.insertAdjacentHTML('beforeend', o.seed.previewHtml);
+    const msg = document.createElement('div');
+    msg.className = 'ed-diagram-error';
+    msg.hidden = true;
+    msg.setAttribute('role', 'status');
+    panel.appendChild(head);
+    panel.appendChild(ta);
+    panel.appendChild(preview);
+    panel.appendChild(msg);
+
+    const s = {
+      kind, blockEl, panel, ta, preview, msg, fence, body, source,
+      blockId: rec.id, startLine: rec.startLine, endLine: rec.endLine,
+      originalHtml: blockEl.innerHTML, darkAtOpen: diagramThemeIsDark(),
+      timer: null, previewSeq: 0, inflight: null, lastResult: undefined, reentering: null, pressInside: false,
+      listeners: new AbortController(), offTheme: null, editor: null,
+    };
+    s.editor = {
+      blockEl,
+      hasChanges: () => s.ta.value !== s.body,
+      snapshot: () => diagramPanelSnapshot(s),
+      commitNow: () => commitDiagramPanel(s),
+      cancelNow: () => cancelDiagramPanel(s),
+      reanchor: () => reanchorDiagramPanel(s),
+    };
+    activeEditor = s.editor;
+    // Fix round 1 (M3): a panel a render other than its own ended (its
+    // commit was superseded) is never read through liveDiagramPanel() again
+    // once this one takes the slot; its theme subscription goes now.
+    if (diagramPanelState && diagramPanelState !== s) disposeDiagramPanel(diagramPanelState);
+    diagramPanelState = s;
+    hideDiagramEditBtn();
+    // Detach census: nothing in a rendered diagram holds focus (the button's
+    // press keeps it where it was), so this write detaches no focused node.
+    blockEl.replaceChildren(panel);
+    autoSize(ta);
+    ta.focus({ preventScroll: true });
+    if (o.seed) ta.setSelectionRange(o.seed.selStart, o.seed.selEnd);
+    else ta.setSelectionRange(0, 0);
+
+    const on = { signal: s.listeners.signal };
+    ta.addEventListener('input', () => { autoSize(ta); scheduleDiagramPreview(s); setDirty(); }, on);
+    panel.addEventListener('keydown', (e) => onDiagramPanelKeydown(s, e), on);
+    // R36: a press inside never ends the panel. On anything but the source
+    // and the preview it keeps focus where it is; a focusout with no
+    // relatedTarget right after a press inside is that press, not a leave.
+    panel.addEventListener('mousedown', (e) => {
+      s.pressInside = true;
+      setTimeout(() => { s.pressInside = false; }, 0);
+      const t = e.target;
+      if (t === ta || (t && t.closest && t.closest('.ed-diagram-preview'))) return;
+      e.preventDefault();
+    }, on);
+    panel.addEventListener('focusout', (e) => {
+      if (liveDiagramPanel() !== s) return;
+      if (e.relatedTarget && panel.contains(e.relatedTarget)) return;
+      if (!e.relatedTarget && s.pressInside) return;
+      switchAwayFrom();
+    }, on);
+    done.addEventListener('click', () => {
+      if (liveDiagramPanel() === s && !s.reentering) commitDiagramPanel(s).catch(showUnexpectedFailure);
+    }, on);
+    const theme = window.md2docTheme;
+    if (theme && typeof theme.onTheme === 'function') {
+      s.offTheme = theme.onTheme((dark) => {
+        if (liveDiagramPanel() !== s) return;
+        if (s.kind === 'dot') {
+          const svg = s.preview.querySelector('svg');
+          if (svg) theme.recolourSvg(svg, dark);
+          return;
+        }
+        // Mermaid's colours are its config: drawn again in the theme now on
+        // screen (renderMermaid() reads it when its turn comes).
+        if (s.timer) { clearTimeout(s.timer); s.timer = null; }
+        runDiagramPreview(s);
+      });
+    }
+    if (o.seed) setDirty();
+    runDiagramPreview(s);
+    return true;
+  }
+
+  // Keys of the panel's own (R25: the document keydown leaves the rest of
+  // them alone). Esc discards, Ctrl/Cmd+Enter commits, Ctrl/Cmd+S commits,
+  // saves and reopens, Tab in the source inserts two spaces (R36). While a
+  // Ctrl+S is out, Esc / Ctrl+Enter / a second Ctrl+S are kept for the panel
+  // it reopens.
+  function onDiagramPanelKeydown(s, e) {
+    if (e.isComposing || e.keyCode === 229) return;
+    const mod = e.ctrlKey || e.metaKey;
+    let act = null;
+    if (e.key === 'Escape' && !mod && !e.altKey) act = 'cancel';
+    else if (e.key === 'Enter' && mod) act = 'commit';
+    else if (mod && !e.altKey && !e.shiftKey && (e.key === 's' || e.key === 'S')) act = 'save';
+    else if (e.key === 'Tab' && !mod && !e.altKey && !e.shiftKey && e.target === s.ta) act = 'tab';
+    if (!act) return;
+    e.preventDefault();
+    e.stopPropagation();
+    if (act === 'tab') { insertIntoDiagramSource(s.ta, '  '); return; }
+    if (s.reentering) { s.reentering[act] = true; return; }
+    if (s.inflight || liveDiagramPanel() !== s) return; // a commit is out: it ends the panel, or leaves it open on failure
+    if (act === 'cancel') cancelDiagramPanel(s).catch(showUnexpectedFailure);
+    else if (act === 'commit') commitDiagramPanel(s).catch(showUnexpectedFailure);
+    else commitDiagramPanelAndReenter(s, { save: true }).catch(showUnexpectedFailure);
+  }
+  // Through the browser's own insertText, so the textarea's native undo
+  // (Ctrl+Z inside it) takes the two spaces back too.
+  function insertIntoDiagramSource(ta, text) {
+    let ok = false;
+    try { ok = document.execCommand('insertText', false, text); } catch (e) { ok = false; }
+    if (!ok) {
+      ta.setRangeText(text, ta.selectionStart, ta.selectionEnd, 'end');
+      ta.dispatchEvent(new Event('input', { bubbles: true }));
+    }
+  }
+
+  function scheduleDiagramPreview(s) {
+    if (s.timer) clearTimeout(s.timer);
+    s.timer = setTimeout(() => { s.timer = null; runDiagramPreview(s); }, DIAGRAM_PREVIEW_MS);
+  }
+  async function runDiagramPreview(s) {
+    if (liveDiagramPanel() !== s) return;
+    const seq = ++s.previewSeq;
+    const src = s.ta.value;
+    let out;
+    if (!src.trim()) out = { svg: '' };
+    else {
+      try {
+        out = s.kind === 'dot' ? await fetchDotPreview(src) : await renderMermaidPreview(src);
+      } catch (e) {
+        out = { error: DIAGRAM_PREVIEW_FAILED };
+      }
+    }
+    // Newest request wins: an answer to an older one is dropped.
+    if (seq !== s.previewSeq || liveDiagramPanel() !== s) return;
+    showDiagramPreview(s, out);
+  }
+  // R31: 200 { svg } is a drawing (an empty one is nothing to show), 422 is
+  // the engine's first line, anything else the generic line.
+  async function fetchDotPreview(src) {
+    let res;
+    try {
+      res = await fetch('/api/preview', {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ fileId: ED.fileId, lang: 'dot', source: src }),
+      });
+    } catch (e) {
+      return { error: DIAGRAM_PREVIEW_FAILED };
+    }
+    let j = null;
+    try { j = await res.json(); } catch (e) { j = null; }
+    if (res.status === 200 && j && typeof j.svg === 'string') return { svg: j.svg };
+    if (res.status === 422 && j && firstLineOf(j.error)) return { error: firstLineOf(j.error) };
+    return { error: DIAGRAM_PREVIEW_FAILED };
+  }
+  async function renderMermaidPreview(src) {
+    if (typeof window.mermaid === 'undefined') {
+      if (diagramEngineGaveUp['mermaid.js']) return { error: DIAGRAM_NO_MERMAID };
+      try { await loadDiagramEngine('mermaid.js'); } catch (e) { return { error: DIAGRAM_NO_MERMAID }; }
+    }
+    const theme = window.md2docTheme;
+    if (!theme || typeof theme.renderMermaid !== 'function') return { error: DIAGRAM_NO_MERMAID };
+    try {
+      return { svg: await theme.renderMermaid(src) };
+    } catch (e) {
+      return { error: firstLineOf(e && e.message !== undefined ? e.message : e) || DIAGRAM_PREVIEW_FAILED };
+    }
+  }
+  function setDiagramMessage(s, kind, text) {
+    if (!kind) {
+      s.msg.hidden = true;
+      s.msg.textContent = '';
+      s.msg.removeAttribute('data-kind');
+      return;
+    }
+    s.msg.hidden = false;
+    s.msg.setAttribute('data-kind', kind);
+    s.msg.textContent = text;
+  }
+  function showDiagramPreview(s, out) {
+    const pv = s.preview;
+    if (out.svg) {
+      // Detach census (d): the preview's own children; the preview itself
+      // (which can hold focus, R36) stays in the document.
+      pv.innerHTML = out.svg;
+      pv.classList.remove('is-stale');
+      setDiagramMessage(s, null);
+      const svg = pv.querySelector('svg');
+      const theme = window.md2docTheme;
+      if (svg && theme && diagramThemeIsDark()) {
+        // A Mermaid render in the dark config is a live one (drawDark()'s
+        // mark): only its author-styled shapes and labels are recoloured.
+        if (s.kind === 'mermaid') svg.setAttribute('data-md2doc-live', '');
+        theme.recolourSvg(svg, true);
+      }
+      return;
+    }
+    if (pv.querySelector('svg')) pv.classList.add('is-stale');
+    if (out.error) setDiagramMessage(s, 'error', out.error);
+    else setDiagramMessage(s, 'empty', DIAGRAM_PREVIEW_EMPTY);
+  }
+
+  function runDiagramPanelCommit(s) {
+    if (!s.inflight) {
+      s.inflight = commitDiagramPanelBody(s).then((r) => { s.lastResult = r; return r; })
+        .finally(() => { s.inflight = null; });
+    }
+    return s.inflight;
+  }
+  async function commitDiagramPanel(s) {
+    return (await runDiagramPanelCommit(s)) !== false;
+  }
+  // true, false (the render failed: rolled back, the panel stays open on its
+  // text, the banner is up) or RENDER_SUPERSEDED.
+  async function commitDiagramPanelBody(s) {
+    if (s.timer) { clearTimeout(s.timer); s.timer = null; }
+    const text = s.ta.value;
+    // Unchanged first, like the code edit (R49 M1): leaving an untouched
+    // panel writes nothing and never starts a reconciliation.
+    if (text === s.body) return await cancelDiagramPanel(s);
+    if (reconcileBlocksCommits()) {
+      if (!reconcilePromise) startReconcileRender();
+      return false;
+    }
+    const r = await commitFencedRangeAndRender(s.startLine, s.endLine, diagramFenceLines(s, text).join('\n'));
+    if (r === null) return await cancelDiagramPanel(s);
+    if (r === false || r === RENDER_SUPERSEDED) return r;
+    endDiagramPanelVisual(s);
+    return true;
+  }
+  // Esc and the cancel path: nothing written. An untouched pristine insert
+  // goes away again, as the raw box's cancelAndMaybeDiscard() does.
+  //
+  // Final review I2: what Esc throws away is parked in `discardedRawEdit`,
+  // as the raw box's Esc parks its text, so the next Ctrl+Z reopens the block
+  // with it (a raw box over the whole fenced block: the snapshot is in that
+  // shape, R23). Measured before: type in the panel, Esc, Ctrl+Z, and the
+  // typing was gone for good. Not for a pristine insert (the block itself
+  // goes) or a panel with nothing typed.
+  async function cancelDiagramPanel(s) {
+    const wasPristine = !!(pristineInsert && pristineInsert.blockId === s.blockId);
+    if (wasPristine) pristineInsert = null;
+    if (!wasPristine && s.ta.value !== s.body) {
+      dropDiscardedBurst();
+      discardedRawEdit = diagramPanelSnapshot(s);
+    }
+    endDiagramPanelVisual(s);
+    if (wasPristine) return await discardPristineInsert();
+    return true;
+  }
+  // openRawEditor()'s reanchor(), for a panel a patch render kept on screen;
+  // otherwise the panel ends on screen as well (R27 (7)).
+  function reanchorDiagramPanel(s) {
+    const raw = s.blockEl.getAttribute('data-block-id');
+    const b = raw === null ? null : blocks.find((x) => x.id === Number(raw));
+    if (b && b.endLine >= b.startLine && lines.slice(b.startLine - 1, b.endLine).join('\n') === s.source) {
+      s.blockId = b.id;
+      s.startLine = b.startLine;
+      s.endLine = b.endLine;
+      return true;
+    }
+    endDiagramPanelVisual(s);
+    return false;
+  }
+  // Ends the panel on screen. `activeEditor` is cleared FIRST (R36, R27 (5)):
+  // putting the rendered HTML back detaches the focused source, and the
+  // focusout that raises must find no session to resolve. A block still on
+  // screen gets the HTML it had at the open back, drawn for the theme on
+  // screen now.
+  function endDiagramPanelVisual(s) {
+    if (activeEditor === s.editor) activeEditor = null;
+    if (diagramPanelState === s) diagramPanelState = null;
+    disposeDiagramPanel(s);
+    if (s.panel.isConnected) {
+      s.blockEl.innerHTML = s.originalHtml;
+      redrawRestoredDiagram(s);
+    }
+    setDirty(); // R47: a panel left unchanged reads clean again
+  }
+  // The restored HTML is a copy: a Mermaid host is a new node the theme
+  // runtime does not know (adopted and drawn again in the theme on screen),
+  // and a Graphviz svg holds the colours of the theme it was opened in.
+  function redrawRestoredDiagram(s) {
+    if (s.kind === 'mermaid') {
+      if (typeof window.__md2docThemeMermaid === 'function') {
+        try { window.__md2docThemeMermaid(); } catch (e) { /* the block keeps the markup it had */ }
+      }
+      return;
+    }
+    const theme = window.md2docTheme;
+    const svg = s.blockEl.querySelector('.graphviz svg');
+    if (svg && theme && diagramThemeIsDark() !== s.darkAtOpen) theme.recolourSvg(svg, diagramThemeIsDark());
+  }
+
+  // R48 / R56 (c): commit through switchAwayFrom() (the gate a click
+  // elsewhere uses), open the panel again on the block at the same start line
+  // with the text and selection the old one held — what was typed into it
+  // while the render was out included — then save. Keys that landed elsewhere
+  // meanwhile (focus on BODY once the render took the old panel away) are
+  // held by the code edit's hold and replayed into the new one. A failed
+  // render leaves the panel open (R27 (3)); a superseded one leaves no block
+  // to open on, and the held keys are dropped with the notice.
+  async function commitDiagramPanelAndReenter(s, opts) {
+    const ta = s.ta;
+    const startLine = s.startLine;
+    const sent = ta.value; // what this commit writes
+    const flags = { cancel: false, commit: false, save: false };
+    s.reentering = flags;
+    const hold = { keys: [], clickedAway: false, passTarget: ta };
+    codeEditReenterHold = hold;
+    let ok;
+    try {
+      ok = await switchAwayFrom();
+    } finally {
+      if (codeEditReenterHold === hold) codeEditReenterHold = null;
+      s.reentering = null;
+    }
+    // v3.17.0 T9b (T5 M6): the code edit's rules. A press that put the caret
+    // in another text surface meanwhile ends the re-entry (nothing reopens or
+    // takes focus back); a second Ctrl+S held here goes after this one's save.
+    const savesHeld = flags.save || hold.keys.some((k) => k.kind === 'save');
+    let target = liveDiagramPanel() === s ? s : null;
+    if (!target && ok && !hold.clickedAway && s.lastResult !== RENDER_SUPERSEDED) {
+      const el = blockElAtLine(startLine);
+      const seed = { value: ta.value, selStart: ta.selectionStart, selEnd: ta.selectionEnd,
+        previewHtml: s.preview.innerHTML };
+      if (el && diagramPanelKindOf(el, s.kind) && await openDiagramPanel(el, { seed, kind: s.kind })) target = liveDiagramPanel();
+    }
+    if (ok && opts.save) saveAfterLastSave();
+    if (!target || hold.clickedAway) {
+      // Nowhere to reopen (a superseded render, a block gone, a press
+      // elsewhere): what was typed after the commit took its text, into the
+      // old source or elsewhere, is dropped — said, never silent (fix round
+      // 1, I1). A panel still open (its render failed) keeps its own text.
+      if (hold.keys.some((k) => k.kind !== 'save') || (!target && ta.value !== sent)) showNotice(FLIGHT_DROPPED_MESSAGE);
+      if (ok && savesHeld) saveAfterLastSave();
+      return !!ok;
+    }
+    const leave = replayIntoDiagramPanel(target, hold.keys);
+    let end = null;
+    if (flags.cancel || leave === 'cancel') end = cancelDiagramPanel(target);
+    else if (flags.commit || leave === 'commit') end = commitDiagramPanel(target);
+    if (end) {
+      if (savesHeld) end.then((landed) => { if (landed) saveAfterLastSave(); }, () => {});
+      return end;
+    }
+    if (savesHeld) return commitDiagramPanelAndReenter(target, { save: true });
+    return !!ok;
+  }
+  // Text, Enter, Tab and Backspace held while the old panel was gone go into
+  // the new one's source, in order; Esc (discard) or Ctrl+Enter (commit)
+  // leaves after them; a held Ctrl+S is the caller's (`savesHeld`); anything
+  // else is dropped with the notice.
+  function replayIntoDiagramPanel(s, keys) {
+    const ta = s.ta;
+    let changed = false;
+    let dropped = false;
+    let leave = null;
+    for (const k of keys) {
+      if (k.kind === 'save') continue;
+      if (leave) { dropped = true; continue; }
+      if (k.kind === 'leave') { leave = k.esc ? 'cancel' : 'commit'; continue; }
+      const text = k.kind === 'insert' ? k.data : k.kind === 'enter' ? '\n' : k.kind === 'tab' ? '  ' : null;
+      if (text !== null) {
+        ta.setRangeText(text, ta.selectionStart, ta.selectionEnd, 'end');
+        changed = true;
+      } else if (k.kind === 'backspace') {
+        const a = ta.selectionStart;
+        const b = ta.selectionEnd;
+        ta.setRangeText('', a === b ? Math.max(0, a - 1) : a, b, 'end');
+        changed = true;
+      } else {
+        dropped = true;
+      }
+    }
+    if (changed) { autoSize(ta); scheduleDiagramPreview(s); setDirty(); }
+    if (dropped) showNotice(FLIGHT_DROPPED_MESSAGE);
+    return leave;
+  }
+
+  // v3.17.0 T5: a press on the theme toggle never takes focus from an edit,
+  // so switching the theme does not end it (the click router ignores the
+  // toggle's click as well).
+  document.addEventListener('mousedown', (e) => {
+    if (e.button === 0 && e.target && e.target.closest && e.target.closest('.md2doc-theme-toggle')) e.preventDefault();
+  }, true);
+
+  // The button's gesture: whatever else is open (a paragraph typed in a
+  // moment ago) is resolved first, and its render may replace this block. It
+  // is found again by content, only when it is the one block with that source
+  // (R104, as the click router does), else the gesture is dropped with the
+  // notice.
+  // `opts.reselect` (Enter on a selected block, R60 (3)): when the panel does
+  // not open after all (openDiagramPanel() false: the block is no Graphviz /
+  // Mermaid block with a fenced source by then), the block is selected again.
+  async function openDiagramPanelFromGesture(blk, opts) {
+    const epochAtPress = reconcileEpoch;
+    const identity = commitsSettled() && !reconcileBlocksCommits() ? captureBlockIdentity(blk) : null;
+    if (!(await switchAwayFrom())) return;
+    await settleCommits();
+    const live = refindBlock(blk, identity);
+    if (!live || reconcileEpoch !== epochAtPress || (reconcileBlocksCommits() && !blockReadsAsDrawn(live))) {
+      showError(DROPPED_GESTURE_MESSAGE, null, null);
+      return;
+    }
+    const opened = await openDiagramPanel(live);
+    if (opened === false && opts && opts.reselect && live.isConnected && !blockSelection && !activeEditor) {
+      const rec = blockRecOf(live);
+      if (rec) setBlockSelection({ anchorLine: rec.startLine, focusLine: rec.startLine });
+    }
+  }
+
   // The fence BODY of one block: its source lines with the opening fence, and
   // the closing fence when there is one, taken off. An unterminated fence at the
   // end of the document has no closing line to drop, and dropping the last line