@helping-ai-workflow/md2doc 3.2.0 → 3.3.0

package/lib/editor/docsource.js

@@ -11,7 +11,8 @@
 })(typeof self !== 'undefined' ? self : this, function () {
 
 // Pure state machine + lines[]<->string conversion for the "追加 4 全文原始碼
-// 逃生口" (whole-document source escape hatch): 編輯 ⇄ 原始碼 ⇄ 預覽.
+// 逃生口" (whole-document source escape hatch): 編輯 ⇄ 原始碼.
+// v3.2.1: 預覽（preview）已移除，見下方 MODES 上的說明。
 //
 // EOL representation: `eol` is always a single literal separator string --
 // '\n', '\r\n' or '\r' -- the same convention server.js already establishes
@@ -31,12 +32,21 @@
 //   2. `\r\n` is listed before the two single-character alternatives, so a
 //      CRLF pair is always consumed as ONE separator, never split into a
 //      spurious blank line between a lone \r and a lone \n.
-const MODES = ['edit', 'source', 'preview'];
+const MODES = ['edit', 'source'];
 
-// Three-state cycle: edit -> source -> preview -> edit. An unrecognized
-// mode (defensive: a caller passing something stale) falls back to the
-// first state rather than throwing, matching how the rest of this module
-// prefers a safe default over a thrown exception for malformed input.
+// v3.2.1: 兩態循環 edit <-> source。preview 移除 —— 實測它相對 edit 只做
+// 兩件事（applyPreviewEditability(false) 與兩行隱藏 ⠿／＋ 的 CSS），卻擋在
+// source 回 edit 的路上，而且 22 顆工具列按鈕中 13 顆在它底下仍然寫得進磁碟。
+//
+// 為什麼是移除而不是加閘門：一個「列舉可及面」推導出來的唯讀閘門必然漏掉
+// 一整族 —— 切換前就已經開著的 ⠿ 選單在切換後仍是 140x118、display:flex，
+// 其 16 個項目每一個都寫得進磁碟。閘門要約 8 個守衛點跨 2 個檔案才擋得住，
+// 而 preview 本身沒有任何 edit 給不了的能力。
+//
+// An unrecognized mode (defensive: a caller passing something stale) falls
+// back to the first state rather than throwing, matching how the rest of
+// this module prefers a safe default over a thrown exception for malformed
+// input.
 function next(mode) {
   const idx = MODES.indexOf(mode);
   return MODES[(idx + 1) % MODES.length];

package/lib/editor/server.js

@@ -145,15 +145,61 @@ function assertBlockRangesFit(blocks, lines) {
   }
 }
 
-async function createEditorServer({ files, idleTimeoutMs = 30000, clientJs = '', listenPort = 0 }) {
+// F13: the never-opened grace deadline is deliberately its own constant,
+// not idleTimeoutMs reused. idleTimeoutMs governs the gap since the last
+// browser ping (client.js pings every 10s; the default 30,000ms tolerates
+// a short run of missed pings once a real tab is confirmed present).
+// Before the URL is opened there is no ping to measure against — the wait
+// is instead for a human to alt-tab to a browser, or, over SSH, copy the
+// printed URL across to a local machine and load it there, which routinely
+// takes longer than idleTimeoutMs allows. Reusing idleTimeoutMs for that
+// wait would close sessions on people still reading the terminal output.
+// Five minutes is chosen as a margin generous for that human handoff while
+// still finite; test/cli-edit.test.js drives it through a shortened
+// override — an unopened session still exits on its own, and a session
+// opened partway through the grace window keeps working afterward.
+const DEFAULT_NEVER_OPENED_GRACE_MS = 5 * 60 * 1000;
+
+// T21 item 3: closing this server has to mean "stop serving now", not "stop
+// serving once every open socket happens to go away". `server.close()` on its
+// own does the latter: it stops accepting, then waits for the connections it
+// already has. A browser handed the edit URL opens a socket it may never send
+// a request on (a speculative preconnect), and such a socket is not one Node
+// retires by itself — driven against `md2doc --edit` on this box with a
+// viewer stub that opened one TCP connection to the port and sent no bytes,
+// SIGINT printed cli.js's line and the process was still alive 10 s later,
+// 3 runs of 3 — while the same runs with a viewer stub that connected and
+// sent a request, and with `--no-open`, exited in 7-10 ms. The same hang
+// reaches the idle and never-opened deadlines below, which have no second
+// keystroke to rescue them, so every exit this file owns goes through here.
+//
+// closeAllConnections() lands the sockets that close() would wait on. It is
+// Node >= 18.2 and package.json's engines floor is >= 18, so the call is
+// guarded rather than assumed; on an 18.0/18.1 runtime the behaviour is
+// exactly what it was before this function existed.
+function shutdownServer(server, reason) {
+  // F13: name the reason before closing, so cli.js's listener (the process's
+  // stdout writer) can print a line distinct from the other exits.
+  if (reason) server.emit('md2doc-auto-close', reason);
+  server.close();
+  if (typeof server.closeAllConnections === 'function') server.closeAllConnections();
+}
+
+async function createEditorServer({
+  files, idleTimeoutMs = 30000, neverOpenedGraceMs = DEFAULT_NEVER_OPENED_GRACE_MS,
+  clientJs = '', listenPort = 0,
+}) {
   const absFiles = files.map((f) => path.resolve(f));
   let idleTimer = null;
+  let neverOpenedTimer = null;
   let started = false;
 
   function bumpIdle(server) {
     if (!started) return;
     if (idleTimer) clearTimeout(idleTimer);
-    idleTimer = setTimeout(() => server.close(), idleTimeoutMs);
+    idleTimer = setTimeout(() => {
+      shutdownServer(server, 'idle');
+    }, idleTimeoutMs);
     if (idleTimer.unref) idleTimer.unref();
   }
 
@@ -442,6 +488,28 @@ async function createEditorServer({ files, idleTimeoutMs = 30000, clientJs = '',
     server.listen(listenPort, '127.0.0.1');
   });
   const port = server.address().port;
+
+  // F13: counts from listen (this point), not from process start — listen
+  // is the moment a client could first reach the server, and that is the
+  // deadline this timer is measuring against. Unref'd like idleTimer, and
+  // for the same reason: the listening socket is what should keep the
+  // process alive, not this timer. A timer that held a ref would keep the
+  // process up on its own even if the socket already went away, which is
+  // backwards for a clock whose only job is to give up and exit.
+  neverOpenedTimer = setTimeout(() => {
+    // The guard against closing a session that has already been opened —
+    // this timer is armed once, at listen time, and left to run; it is
+    // not cancelled by the GET /edit/:id handler. Whether the URL was
+    // opened by the time the deadline arrives is decided here, by reading
+    // `started` fresh at fire time. Proven load-bearing by mutation: with
+    // this line removed, an actively-pinged session still gets closed the
+    // moment this deadline passes (see test/cli-edit.test.js's "must
+    // survive the never-opened grace deadline" case).
+    if (started) return;
+    shutdownServer(server, 'never-opened');
+  }, neverOpenedGraceMs);
+  if (neverOpenedTimer.unref) neverOpenedTimer.unref();
+
   return {
     server,
     port,
@@ -449,7 +517,11 @@ async function createEditorServer({ files, idleTimeoutMs = 30000, clientJs = '',
       const i = absFiles.indexOf(path.resolve(absPath));
       return i === -1 ? null : `http://127.0.0.1:${port}/edit/${i}`;
     },
-    close() { if (idleTimer) clearTimeout(idleTimer); server.close(); },
+    close() {
+      if (idleTimer) clearTimeout(idleTimer);
+      if (neverOpenedTimer) clearTimeout(neverOpenedTimer);
+      shutdownServer(server, null);
+    },
   };
 }
 

package/lib/editor/toolbar-model.js

@@ -29,11 +29,11 @@ const BUTTON_DEFS = [
   { id: 'check', group: 'block', label: '☑', icon: '☑', title: '待辦清單', toggle: false },
 
   // inline
-  { id: 'bold', group: 'inline', label: 'B', icon: 'B', title: '粗體', toggle: false },
-  { id: 'italic', group: 'inline', label: 'I', icon: 'I', title: '斜體', toggle: false },
-  { id: 'strike', group: 'inline', label: 'S', icon: 'S', title: '刪除線', toggle: false },
-  { id: 'inline-code', group: 'inline', label: '`', icon: '`', title: '行內程式碼', toggle: false },
-  { id: 'link', group: 'inline', label: '🔗', icon: '🔗', title: '連結', toggle: false },
+  { id: 'bold', group: 'inline', label: 'B', icon: 'B', title: '粗體', toggle: true },
+  { id: 'italic', group: 'inline', label: 'I', icon: 'I', title: '斜體', toggle: true },
+  { id: 'strike', group: 'inline', label: 'S', icon: 'S', title: '刪除線', toggle: true },
+  { id: 'inline-code', group: 'inline', label: '`', icon: '`', title: '行內程式碼', toggle: true },
+  { id: 'link', group: 'inline', label: '🔗', icon: '🔗', title: '連結', toggle: true },
 
   // indent
   { id: 'outdent', group: 'indent', label: '⇤', icon: '⇤', title: '減少縮排', toggle: false },
@@ -48,7 +48,13 @@ const BUTTON_DEFS = [
 
   // view
   { id: 'outline', group: 'view', label: '☰', icon: '☰', title: '大綱', toggle: false },
-  { id: 'preview', group: 'view', label: '👁', icon: '👁', title: '預覽', toggle: true },
+  // v3.2.1: 這顆是 edit <-> source 的兩態切換（preview 模式已移除）。id 保留
+  // 為 'preview' 是刻意的 —— 每一支選擇器、journey 案例與 runtime 測試都指名
+  // 它，改名只換得一個更好聽的字串。label / title 不是烘死值：deriveState()
+  // 每次都依當前 mode 覆寫成【下一個】狀態的名字，這裡的值只是 edit 模式的
+  // 起始值。toggle: false —— 兩態下 aria-pressed 講不出真話（按鈕講的是去處，
+  // 不是目前所在），真話由會變的 label / title 承擔。
+  { id: 'preview', group: 'view', label: 'M↓', icon: 'M↓', title: '切換到原始碼模式', toggle: false },
 ];
 
 const BUTTONS = Object.freeze(BUTTON_DEFS.map((b) => Object.freeze(Object.assign({}, b))));
@@ -59,8 +65,36 @@ const GROUPS = Object.freeze(['history', 'block', 'inline', 'indent', 'insert',
 // state right after rerenderAll, before any block gets focus/selection).
 const NO_BLOCK_ALLOWED = new Set(['undo', 'redo', 'outline', 'preview']);
 
-// ctx: {blockType, indent, headingDepth, inList, listOrdered, hasSelection, mode}
-// -> { [id]: {active: bool, disabled: bool, label?: string} }
+// The mark element each inline button toggles. This module cannot ask the
+// DOM which marks a selection sits in, so the client measures that and hands
+// the answer in as `ctx.marks` — keyed by TAG, not by button id, because
+// .ed-seltb carries a U button with no counterpart in this roster and both
+// toolbars are painted from one measurement. The mapping from button to tag
+// has to live somewhere, and here is where the button ids are.
+const MARK_TAG_BY_ID = Object.freeze({
+  bold: 'STRONG',
+  italic: 'EM',
+  strike: 'DEL',
+  'inline-code': 'CODE',
+  link: 'A',
+});
+
+// The inline-format ids, read off the map above rather than retyped. The
+// `hasSelection` rule below used to carry a hand-written copy of this list;
+// the marks rule under it would have been a second.
+const MARK_IDS = Object.freeze(Object.keys(MARK_TAG_BY_ID));
+
+// The per-tag values `ctx.marks` may carry, and what each one means for the
+// button that toggles that tag. The client's selectionMarkStates() is what
+// produces them; the names are shared vocabulary, not a re-derivation.
+//   'whole'   the selection lies inside one mark of that tag
+//   'partial' the selection overlaps marks of that tag without lying in one
+//   'none'    no mark of that tag is involved
+//   'inert'   pressing the button would do nothing at all
+
+// ctx: {blockType, indent, headingDepth, inList, listOrdered, hasSelection,
+//       mode, marks}
+// -> { [id]: {active: bool, mixed: bool, disabled: bool, label?: string} }
 function deriveState(ctx) {
   const c = ctx || {};
   const blockType = c.blockType;
@@ -73,14 +107,21 @@ function deriveState(ctx) {
 
   const state = {};
   for (const b of BUTTONS) {
-    state[b.id] = { active: false, disabled: false };
+    state[b.id] = { active: false, mixed: false, disabled: false };
   }
 
-  // preview is the tri-state edit/source/preview toggle: "pressed" whenever
-  // the current mode is not plain editing. It stays enabled in source mode
-  // via the mode==='source' override below (do not gate this on inList/
-  // hasBlock — it is the escape hatch OUT of those states).
-  state.preview.active = mode !== 'edit';
+  // v3.2.1: the mode button names the NEXT state, never the current one.
+  // Under the old tri-state cycle it was permanently labelled 「預覽」 and
+  // reported aria-pressed=true in BOTH non-edit modes, so pressing it twice
+  // landed in source with no grips and an interface that said nothing about
+  // where you were — the reported "stuck" defect. It carries no `active`
+  // now: with two states the honest signal is the label, and the current
+  // mode is spelled out in .ed-toolbar-status by the client.
+  // It stays enabled in source mode via the mode==='source' override below
+  // (do not gate this on inList/hasBlock — it is the escape hatch OUT of
+  // those states).
+  state.preview.label = mode === 'source' ? '✎' : 'M↓';
+  state.preview.title = mode === 'source' ? '切換到編輯模式' : '切換到原始碼模式';
 
   // headings: dropdown whose label tracks the current heading depth.
   state.headings.label = blockType === 'heading' ? 'H' + headingDepth : 'H';
@@ -139,22 +180,57 @@ function deriveState(ctx) {
   // refuse for reasons this ctx does not carry (a structural list gate, a
   // block that owns no source line).
   if (!c.hasSelection) {
-    for (const id of ['bold', 'italic', 'strike', 'inline-code', 'link']) {
+    for (const id of MARK_IDS) {
       state[id].disabled = true;
     }
   }
 
+  // v3.3.0 (F2): what the selection is already marked as. Before this the ctx
+  // carried one boolean about the selection and nothing about its identity.
+  // MEASURED on the build before this change, reading the fixed toolbar's B
+  // over a selection wholly inside a <strong>, one straddling its edge, and one
+  // in plain text: aria-pressed came back null on all three — the buttons were
+  // `toggle: false`, so the client's aria-pressed write skipped them.
+  //
+  // `active` and `mixed` are separate booleans rather than one tri-state
+  // because `active` is what the toggle-roster test sweeps for and what the
+  // rest of this function already speaks. The client turns the pair into
+  // aria-pressed true / mixed / false.
+  //
+  // 'inert' disables. It is NOT the same question as `hasSelection`: that one
+  // asks whether the action would refuse the selection outright, this one asks
+  // whether the branch the action would actually take is a no-op. A press on
+  // an inert button leaves the document exactly as it was.
+  const marks = c.marks;
+  if (marks) {
+    for (const id of MARK_IDS) {
+      const m = marks[MARK_TAG_BY_ID[id]];
+      state[id].active = m === 'whole';
+      state[id].mixed = m === 'partial';
+      if (m === 'inert') state[id].disabled = true;
+    }
+  }
+
   // mode 'source' is the full-document raw-source escape hatch: everything
-  // is disabled except the toggle that got you there (preview). This
-  // overrides every disabled flag computed above.
+  // is disabled except the mode button that got you there (id 'preview',
+  // which in v3.2.1 is the edit <-> source toggle) and, since T11-2,
+  // 'outline' (☰). The mode button is still the ONLY way back to 'edit' —
+  // that has not changed. 'outline' stays reachable because it is what
+  // opens the sidebar drawer (toggleOutlineSidebar() in
+  // lib/editor/client.js), and the fixed `.sidebar-toggle` button that used
+  // to reach the drawer another way is hidden in edit mode entirely (see the
+  // T11-2 comment in lib/md2doc.js) — a disabled ☰ here would leave source
+  // mode with no way to open that drawer at all. This override still runs
+  // last and still overrides every disabled flag computed above for every
+  // other button; do not narrow it for anything but these two ids.
   if (mode === 'source') {
     for (const b of BUTTONS) {
-      state[b.id].disabled = b.id !== 'preview';
+      state[b.id].disabled = b.id !== 'preview' && b.id !== 'outline';
     }
   }
 
   return state;
 }
 
-return { BUTTONS, GROUPS, deriveState };
+return { BUTTONS, GROUPS, MARK_TAG_BY_ID, deriveState };
 });

package/lib/md2doc.js

@@ -1349,7 +1349,19 @@ ${itemsHtml}
      it. Fixed chrome takes no layout space, so the page has to make its
      own: this is the only place that offset is written. The mobile rule at
      max-width:1080px above already reserves 60px for .sidebar-toggle; the
-     bar sits above it, so the two offsets ADD there.
+     bar sits above it. That 60px is NOT re-reserved here: T11-2 hides
+     .sidebar-toggle in edit mode (the rule further down this stylesheet), so
+     in edit mode there is no button under the bar to clear, and adding the
+     two offsets left a band of empty page nothing was ever painted into.
+     Measured on the build that did add them, at 1080/1000/800 wide:
+     .page-layout's computed padding-top was 104px against a 44px toolbar —
+     60px of dead space, and a 105px gap between the toolbar's bottom edge
+     and the first block against 45px at 1200 wide, where the desktop rule
+     applies. The @media block below therefore still has to carry an explicit
+     value, identical to the desktop one: the READER stylesheet's own
+     'max-width: 1080px' rule sets padding-top: 60px for the drawer toggle it
+     still shows, and deleting this override would hand the edit page that
+     60px straight back.
      .reader-sidebar is sticky at top: 24px in the base stylesheet — pushed
      down by the same amount here so the outline does not slide under the
      bar, with its height reduced to match so it still ends at the viewport
@@ -1360,7 +1372,7 @@ ${itemsHtml}
     height: calc(100vh - 48px - var(--ed-toolbar-h));
   }
   @media (max-width: 1080px) {
-    .page-layout { padding-top: calc(60px + var(--ed-toolbar-h)); }
+    .page-layout { padding-top: var(--ed-toolbar-h); }
     .reader-sidebar { top: 0; height: 100vh; padding-top: calc(16px + var(--ed-toolbar-h)); }
   }
   /* The 大綱 button's DESKTOP half, on an attribute of its OWN.
@@ -1382,7 +1394,41 @@ ${itemsHtml}
   @media (min-width: 1081px) {
     body[data-ed-outline-hidden] .reader-sidebar,
     body[data-ed-outline-hidden] .sidebar-splitter { display: none; }
-  }`;
+  }
+  /* T11-2 step 3: this button sits at z-index 100 (base stylesheet, above)
+     directly under .ed-toolbar's z-index 101. Measured at 1080x900 and
+     800x900: document.elementFromPoint() at the button's own rect centre
+     returns the toolbar, not the button, at both widths — a real pointer
+     click never lands on it there, only a synthetic .click() does. The
+     toolbar's own left/right are both 0, spanning the full viewport width,
+     so nothing about that occlusion is a function of width; the two
+     measured points are a sample of a band the toolbar covers edge to
+     edge, not two lucky ones. It is safe to remove in edit mode because
+     lib/editor/client.js's toolbar carries its own outline button
+     (runToolbarAction()'s 'outline' case, which calls toggleOutlineSidebar(),
+     the same function this button calls) which opens the identical drawer,
+     and Task 8 gave that toolbar a keyboard cursor (Alt+F10) — the outline
+     button is not among the ids Task 8 measured as stranding the caret on
+     BODY after activation. This rule is edit-mode-only (editModeLayoutCss);
+     reader-mode output never includes it, so the mobile drawer toggle there
+     is unaffected. */
+  .sidebar-toggle { display: none; }
+  /* T11-2 step 5: enterSourceMode() (lib/editor/client.js) sets
+     contentEl.hidden = true and mounts a plain textarea in its place, and
+     setDocMode() writes docMode onto body as data-ed-mode. Measured on that
+     build: with ten TOC links listed, clicking the last one moved neither
+     the (hidden) reading position nor the textarea's own scrollTop
+     (3924 before and after) — the click target was a normal anchor jump /
+     scrollIntoView() reaching into a subtree rooted at .content, and
+     .content's own display:none is what absorbed it; the same subtree
+     relationship holds for a search result's jump target. Hiding the TOC
+     nav and the search-results panel while data-ed-mode="source" removes
+     the two controls whose only reachable target sits in that hidden
+     subtree; the search input row (.reader-tools) is left as-is — driving
+     it against the textarea's own line numbers instead is a separate
+     feasibility question, not answered here. */
+  body[data-ed-mode="source"] .toc,
+  body[data-ed-mode="source"] .search-results { display: none !important; }`;
 
   const html = `<!DOCTYPE html>
 <html lang="en">
@@ -2092,6 +2138,17 @@ ${itemsHtml}
     background: #ffffff;
   }
   body[data-lightbox-open] { overflow: hidden; }
+  /* The 'html, body { overflow-x: clip }' rule above keeps documentElement's
+     own overflow-x at clip, not visible, so overflow does not propagate from
+     body to the viewport per the CSS spec's root-propagation rule; the
+     scrolling element stays documentElement, and its overflow-y sits at the
+     visible default. That is the gap the body rule above does not close --
+     measured in test/lightbox.test.js and test/editor-journey.test.js: a
+     wheel over .lightbox-bar, PageDown and End all reach documentElement
+     while it is open. Locking documentElement's own overflow here closes
+     it; JS mirrors the data-lightbox-open attribute onto the html element
+     in openLightbox/closeLightbox below. */
+  html[data-lightbox-open] { overflow: hidden; }
   @media print { .lightbox { display: none !important; } }
   @media (max-width: 1080px) {
     .sidebar-toggle { display: inline-flex; align-items: center; }
@@ -2318,7 +2375,21 @@ ${itemsHtml}
      this element's containing block and left:100% lands it flush against
      the menu's right edge. Source order matters: equal specificity with
      .ed-handle-menu's own left:-4px, so this rule must stay AFTER it. */
-  .ed-handle-submenu { left: 100%; margin-left: 4px; }
+  /* Viewport-clamp backstop: openConvertSubmenu() (lib/editor/client.js)
+     shifts the panel's top up so its bottom clears the viewport when there
+     is room to do so — that shift is the clamp. This rule covers what the
+     shift cannot: a viewport shorter than the panel, where the viewport's
+     own top edge still leaves the panel's bottom edge off-screen. What
+     happens under max-height, in the order it happens: CONVERT_TARGETS's
+     buttons (lib/editor/convert-md.js), each carrying .ed-handle-menu-btn's
+     own height (26px), first shrink via flex as the cap tightens (measured
+     on this branch: 26px at a cap around 342px, stepping down to 18px
+     around a 250px cap) — no scrolling yet, the list still fits end to
+     end, just shorter per row. overflow-y: auto only starts moving content
+     once the rows have already reached that floor and the cap is still
+     tighter than the list at 18px per row. (No backticks in this comment:
+     it lives inside a JS template literal.) */
+  .ed-handle-submenu { left: 100%; margin-left: 4px; max-height: calc(100vh - 8px); overflow-y: auto; }
   .ed-handle-menu-btn:hover { background: rgba(255, 255, 255, 0.18); }
   .ed-handle-menu-btn[hidden] { display: none; }
   /* §10-gap fix: block-level INSERT — the ＋ button sits NEXT TO the ⠿
@@ -2529,7 +2600,23 @@ ${itemsHtml}
     font: inherit; font-size: 13px; line-height: 1;
     white-space: nowrap; cursor: pointer;
   }
-  .ed-seltb-btn:hover { background: rgba(255, 255, 255, 0.18); }
+  .ed-seltb-btn:hover:not([aria-disabled="true"]) { background: rgba(255, 255, 255, 0.18); }
+  /* v3.3.0 (F2): the four states these buttons report about the selection.
+     'true' (the selection is entirely inside a mark of this type) is the
+     filled treatment the fixed toolbar already uses. 'mixed' (the selection
+     overlaps marks of this type without lying inside one) is deliberately NOT
+     the filled one — pressing it removes marks rather than adding any — so it
+     gets a dashed edge and a half-strength ground instead. 'false' keeps the
+     rule above. INERT is aria-disabled, never the disabled DOM property; see
+     paintSelToolbarMarks() in lib/editor/client.js for why. */
+  .ed-seltb-btn[aria-pressed="true"] {
+    background: #e6edf3; color: #101215; border-color: #e6edf3;
+  }
+  .ed-seltb-btn[aria-pressed="mixed"] {
+    background: rgba(230, 237, 243, 0.3);
+    border-style: dashed; border-color: rgba(230, 237, 243, 0.8);
+  }
+  .ed-seltb-btn[aria-disabled="true"] { opacity: 0.38; cursor: default; }
   .ed-seltb-b { font-weight: bold; }
   .ed-seltb-i { font-style: italic; }
   .ed-seltb-s { text-decoration: line-through; }
@@ -2550,13 +2637,67 @@ ${itemsHtml}
   .ed-toolbar {
     position: fixed; top: 0; left: 0; right: 0; z-index: 101;
     box-sizing: border-box; height: var(--ed-toolbar-h);
-    display: flex; align-items: center; justify-content: center;
+    display: flex; align-items: center; justify-content: flex-start;
     flex-wrap: nowrap; overflow-x: auto; overflow-y: hidden;
     gap: 6px; padding: 8px 12px;
+    /* F12, both halves measured on this build at 900px viewport height.
+       justify-content was center. Centering an overflowing flex row splits
+       the overflow across BOTH ends, and the leading end of a scroll
+       container's content is not reachable by scrolling: driven at 820 /
+       640 / 420 px wide, sweeping scrollLeft from 0 to its maximum in 8px
+       steps and reading every button's rect, the buttons that never once sat
+       inside the viewport were [undo] / [undo, redo, headings] /
+       [undo, redo, headings, quote, code, list]. On this build — leading-edge
+       layout plus the padding-right below, driven together, not one at a time
+       — the same sweep leaves that set empty at all three widths.
+
+       padding-right buys the buttons room to clear .ed-toolbar-status, whose
+       fixed box occupies the viewport's right 124px (right: 12px plus
+       min-width: 7rem at this font size). The claim it supports is narrow:
+       SOME scroll position exists at which a given button is clear of the
+       slot. It is NOT "a button can never sit under the slot" — driven at
+       scrollLeft 0 after this change, [outline, preview] still overlap the
+       slot at a 900px viewport and [check, bold, italic, strike] do at 420px.
+       What makes that harmless is the slot's own pointer-events: none, in
+       the rule further down — the load-bearing line, not this one. */
+    padding-right: 124px;
     background: rgba(16, 18, 21, 0.92); color: #e6edf3;
+    /* F12, second half: before this the bar scrolled but nothing on screen
+       said so, so a button parked outside the viewport looked absent rather
+       than off to one side. Two edge gradients, painted only on the side
+       that still has content hidden behind it; the client runtime writes
+       data-ed-tb-overflow from scrollLeft against the scroll maximum.
+
+       Deliberately a background layer on the bar itself rather than a new
+       overlay node. An overlay would have to be taken out of flow to avoid
+       becoming a flex item in this row, and an out-of-flow child of this bar
+       anchors to the scrolled content box and drifts with it (the
+       .ed-toolbar-status note below records that measurement) — while
+       anchoring it to the viewport instead would add a floating layer to the
+       set test/editor-journey.test.js enumerates and demands a scroll answer
+       for. A background layer needs neither: background-attachment defaults
+       to scroll, which pins the gradient to this element's padding box while
+       its contents move underneath.
+
+       These gradients sit behind the buttons, because that is where the
+       painting order puts a background layer: above the background colour,
+       below the element's content. That is the reason they are dark rather
+       than light — darkening the ground a translucent button sits on is what
+       reads as content passing under an edge, where a light wash behind the
+       same button would not. */
+    --ed-tb-edge-l: rgba(0, 0, 0, 0);
+    --ed-tb-edge-r: rgba(0, 0, 0, 0);
+    background-image:
+      linear-gradient(to right, var(--ed-tb-edge-l), rgba(0, 0, 0, 0)),
+      linear-gradient(to left, var(--ed-tb-edge-r), rgba(0, 0, 0, 0));
+    background-repeat: no-repeat;
+    background-position: left center, right center;
+    background-size: 26px 100%, 26px 100%;
     font-size: 13px;
     box-shadow: 0 2px 8px rgba(0, 0, 0, 0.25);
   }
+  .ed-toolbar[data-ed-tb-overflow~="left"] { --ed-tb-edge-l: rgba(0, 0, 0, 0.55); }
+  .ed-toolbar[data-ed-tb-overflow~="right"] { --ed-tb-edge-r: rgba(0, 0, 0, 0.55); }
   .ed-toolbar-sep {
     flex: 0 0 auto; width: 1px; height: 18px; margin: 0 2px;
     background: rgba(255, 255, 255, 0.25);
@@ -2570,18 +2711,45 @@ ${itemsHtml}
     white-space: nowrap; cursor: pointer;
   }
   .ed-toolbar-btn:hover:not(:disabled) { background: rgba(255, 255, 255, 0.18); }
+  /* F12: where the toolbar's keyboard cursor is. An outline rather than a
+     background so it stays legible on a button that is already pressed-in
+     (aria-pressed paints that one nearly white). Claim no more for it than a
+     keyboard route: the buttons keep their tabindex="-1" and the caret stays
+     in the document, so no focus move happens for assistive technology to
+     follow, and what this cue does for a screen reader has not been measured
+     here. What it does do is let the row be walked without a mouse. */
+  .ed-toolbar-btn[data-ed-tb-cursor] {
+    outline: 2px solid #6ea8fe; outline-offset: 1px;
+  }
   .ed-toolbar-btn:disabled { opacity: 0.38; cursor: default; }
   .ed-toolbar-btn[aria-pressed="true"] {
     background: #e6edf3; color: #101215; border-color: #e6edf3;
   }
+  /* v3.3.0 (F2): the middle state, matching .ed-seltb-btn[aria-pressed="mixed"]
+     above so the two bars answer the same question the same way. */
+  .ed-toolbar-btn[aria-pressed="mixed"] {
+    background: rgba(230, 237, 243, 0.3);
+    border-style: dashed; border-color: rgba(230, 237, 243, 0.8);
+  }
   .ed-toolbar-b { font-weight: bold; }
   .ed-toolbar-i { font-style: italic; }
   .ed-toolbar-s { text-decoration: line-through; }
-  /* H1 fix: the brief's literal margin-left: auto (a flex-flow item) was
-     measured to break .ed-toolbar's justify-content: center — an auto
-     margin on any flex item absorbs ALL positive free space before
-     justify-content sees any, so the ~22-button group snapped flush left on
-     every viewport wide enough not to overflow. position: fixed removes
+  /* H1 fix — and its reason has since moved, so both readings are kept here
+     rather than one silently standing in for the other. The brief's literal
+     margin-left: auto (a flex-flow item) was measured on v3.2.0 to break
+     .ed-toolbar's justify-content: center — an auto margin on any flex item
+     absorbs ALL positive free space before justify-content sees any, so the
+     ~22-button group snapped flush left on every viewport wide enough not to
+     overflow. F12 replaced that declaration with justify-content: flex-start
+     (the .ed-toolbar rule above), so flush left IS the shipped layout now and
+     that particular failure mode no longer exists. What the rule guards today
+     is the slot's out-of-flow-ness, and the assertion beside it in
+     test/editmode-render.test.js carries the re-driven numbers: against the
+     slot as it ships the margin changes nothing at all, while putting the slot
+     back in flow with it turns the slot into a scrolling flex item
+     (scrollWidth 975 -> 1093 at 420px) and moves its rect off the strip
+     .ed-toolbar's padding-right reserves for it ([1276, 1388] -> [1164, 1276]
+     at 1400px). position: fixed removes
      the slot from the flex layout entirely (buttons measured byte-identical
      to a build with the slot absent, at both a 1400px and a 420px viewport),
      and — unlike position: absolute against .ed-toolbar's own
@@ -2590,16 +2758,21 @@ ${itemsHtml}
      row's overflow-x: auto scrolls (measured identical rect at scrollLeft
      0 / mid / max, where the absolute alternative moved by the exact scroll
      delta). References no gutter-alignment custom property.
-     H2 fix: pointer-events: none below is LOAD-BEARING while this slot
-     ships empty, not decorative. At narrow viewports .ed-toolbar's own
-     overflow-x: auto lets the button row scroll to a rest position where
-     this fixed 7rem box's footprint physically covers three real buttons
-     (image / outline / preview, measured at 420px width, scrollLeft at its
-     max 221) — document.elementFromPoint() over any of them resolves to
-     this span, not the button underneath, and a real click on it never
-     reaches the button's listener. Harmless today only because the span
-     carries no content to interact with. WHOEVER WIRES UP TWO-WAY SYNC
-     (§3) AND PUTS REAL CONTENT OR CONTROLS HERE MUST remove or scope this
+     H2 fix: pointer-events: none below is LOAD-BEARING, not decorative.
+     v3.2.1 filled this slot with the current mode's name ('編輯' / '原始碼'),
+     so it no longer ships empty — but that content is inert TEXT, never a
+     control, which is exactly what keeps the rule below sufficient. The
+     overlap it keeps harmless is real and still present after F12 moved this
+     bar's scroll geometry: at scrollLeft 0, this box's footprint covers
+     outline and preview at a 900px-wide viewport, and check / bold / italic /
+     strike at 420px. Re-driven on this build, hit-testing the middle of each
+     of those overlaps: with the rule as it ships,
+     document.elementFromPoint() answers the BUTTON at every one of them; flip
+     this span's pointer-events to auto and leave everything else alone, and
+     every one of them answers this span instead. That reading is the same hit
+     test a press resolves through, and the rule below is what stands between
+     the two readings — not the span's emptiness. WHOEVER PUTS A CONTROL HERE (or
+     wires up two-way sync, §3) MUST remove or scope this
      rule AND independently solve the overlap (e.g. reflow the slot in-flow
      at narrow widths, or shrink/hide it below some width) — simply
      deleting this line without doing that reopens the swallowed-click
@@ -2611,13 +2784,19 @@ ${itemsHtml}
     pointer-events: none; }
   /* The H▾ dropdown: same singleton-panel idiom as .ed-insert-menu, but
      anchored to a fixed bar rather than moved into a block, so it is
-     positioned in viewport coordinates by the client runtime. */
+     positioned in viewport coordinates by the client runtime.
+     max-height/overflow-y: same backstop role as .ed-handle-submenu above
+     (Task 9 fix round 1, Ruling T9-5) — toggleToolbarHeadingMenu()
+     (lib/editor/client.js) does the shift-to-fit; this covers a viewport
+     shorter than the panel, where the shift alone cannot bring the whole
+     list on-screen. */
   .ed-toolbar-menu {
     position: fixed; z-index: 102;
     display: flex; flex-direction: column; gap: 2px;
     padding: 4px; border-radius: 8px;
     background: rgba(16, 18, 21, 0.96); color: #e6edf3;
     box-shadow: 0 2px 8px rgba(0, 0, 0, 0.35);
+    max-height: calc(100vh - 8px); overflow-y: auto;
   }
   .ed-toolbar-menu[hidden] { display: none; }
   .ed-toolbar-menu-btn {
@@ -2636,8 +2815,6 @@ ${itemsHtml}
     border: 1px solid #d0d7de; border-radius: 8px; resize: vertical;
     white-space: pre; overflow-wrap: normal;
   }
-  body[data-ed-mode="preview"] .ed-handle,
-  body[data-ed-mode="preview"] .ed-insert { display: none !important; }
   .ed-editing { position: relative; }
   .ed-raw {
     display: block; width: 100%; font-family: monospace; font-size: 13px;
@@ -4206,6 +4383,7 @@ ${mermaidInitTag}`)
     lightboxReturnScroll = window.scrollY;
     suppressAnchorCapture = true;
     document.body.setAttribute('data-lightbox-open', '');
+    document.documentElement.setAttribute('data-lightbox-open', '');
     lightboxEl.hidden = false;
     lightboxStage.scrollTop = 0;
     lightboxStage.scrollLeft = 0;
@@ -4218,6 +4396,7 @@ ${mermaidInitTag}`)
     if (!lightboxIsOpen()) return;
     lightboxEl.hidden = true;
     document.body.removeAttribute('data-lightbox-open');
+    document.documentElement.removeAttribute('data-lightbox-open');
     annoCancelDraft();
     annoSyncInline();
     annoSourceNode = null;