@helping-ai-workflow/md2doc 3.0.2 → 3.2.0

package/lib/editor/server.js

@@ -23,12 +23,50 @@ const INDENT_CLAMP_SRC = fs.readFileSync(path.join(__dirname, 'indent-clamp.js')
 // indent-clamp.js above — it only has to land before client.js reads
 // window.md2docConvertMd.
 const CONVERT_MD_SRC = fs.readFileSync(path.join(__dirname, 'convert-md.js'), 'utf8');
+// v3.2.0: the pure string-diff module behind incremental DOM patching —
+// stripBlockId()/patchmap() compare oldParts[i] against newParts[j] with only
+// data-block-id normalized (see the global constraint on that). Same "no
+// dependency on any other editor module" property as indent-clamp.js and
+// convert-md.js above; it only has to land before client.js reads
+// window.md2docPatchmap.
+const PATCHMAP_SRC = fs.readFileSync(path.join(__dirname, 'patchmap.js'), 'utf8');
 // S3 spec §3.3/§3.6/§4.4: the pure block multi-select model — line-range
 // normalization, membership, Shift+arrow stepping, the §3.3 grip rule and the
 // post-operation collapse. Same "no dependency on any other editor module"
 // property as indent-clamp.js and convert-md.js above; it only has to land
 // before client.js reads window.md2docSelection.
 const SELECTION_SRC = fs.readFileSync(path.join(__dirname, 'selection.js'), 'utf8');
+// v3.1.0 Task E: the four Phase-1 modules behind the visible toolbar, the
+// paste pipeline, the image-drop asset endpoint and the whole-document
+// source escape hatch. Same "pure module, no dependency on any other editor
+// module" property as indent-clamp.js / convert-md.js / selection.js above —
+// each only has to land before client.js reads its window global.
+const TOOLBAR_MODEL_SRC = fs.readFileSync(path.join(__dirname, 'toolbar-model.js'), 'utf8');
+const DOCSOURCE_SRC = fs.readFileSync(path.join(__dirname, 'docsource.js'), 'utf8');
+const ASSET_SRC = fs.readFileSync(path.join(__dirname, 'asset.js'), 'utf8');
+// turndown's BROWSER build. node's `require('turndown')` resolves to
+// lib/turndown.cjs.js, which is not loadable as a plain <script> tag — the
+// UMD build is, and it defines the global `TurndownService` that
+// paste-md.js's getTurndownService() reads at CALL time (not factory time,
+// so this tag's position relative to paste-md.js's is not load-bearing;
+// it is injected first anyway, to keep the dependency reading left-to-right).
+const TURNDOWN_SRC = fs.readFileSync(
+  require.resolve('turndown/lib/turndown.browser.umd.js'), 'utf8');
+const PASTE_MD_SRC = fs.readFileSync(path.join(__dirname, 'paste-md.js'), 'utf8');
+
+// The SAME pure module the page gets, required here for the node side of
+// /api/asset. asset.js is deliberately free of `require('fs')`/`require('path')`
+// (it is plain string arithmetic), so every filesystem decision below is made
+// here — including the '/'-normalization isWithin's contract demands.
+const assetLib = require('./asset.js');
+
+// asset.js's isWithin() is POSIX-only BY CONTRACT (see its own comment): it
+// does not understand '\\' as a separator and fails CLOSED on a native-Windows
+// path, refusing every legitimate write. Normalizing at this boundary is the
+// caller's job, and this is that boundary.
+function toPosixPath(p) {
+  return String(p === null || p === undefined ? '' : p).split('\\').join('/');
+}
 
 function readJson(req, limitBytes = 50 * 1024 * 1024) {
   return new Promise((resolve, reject) => {
@@ -51,6 +89,37 @@ function readJson(req, limitBytes = 50 * 1024 * 1024) {
   });
 }
 
+// DNS-rebinding defense. The content-type gate below stops a cross-site
+// "simple" POST, but it cannot stop a request the browser believes is
+// SAME-origin: a page on evil.com served with a 1-second-TTL A record can
+// rebind that name to 127.0.0.1 and then POST to http://evil.com:PORT/... with
+// a real application/json body. No preflight fires, the content-type check is
+// satisfied, and the attacker is inside.
+//
+// What made that reachable is that a route needs no unguessable precondition.
+// /api/save happens to have one — `baseMtimeMs` must equal the file's actual
+// mtimeMs, a float an attacker cannot guess — but /api/asset needs only a
+// `fileId` inside [0, absFiles.length), which is guessable in one try, and it
+// WRITES FILES. So the check belongs at the front door rather than on the one
+// route that happened to lack a second lock: the Host header is attacker-
+// controlled in name only, since a rebinding attack must send the name it
+// rebound, and that name is never a loopback literal.
+//
+// A missing Host is rejected too (HTTP/1.0 clients): this server is only ever
+// addressed by lib/editor/open.js and a browser, both of which send one.
+function hostIsLoopback(hostHeader, port) {
+  if (typeof hostHeader !== 'string' || hostHeader === '') return false;
+  const h = hostHeader.toLowerCase();
+  const names = ['127.0.0.1', 'localhost', '[::1]'];
+  for (const n of names) {
+    if (h === n + ':' + port) return true;
+    // A bare Host (no ':port') means the scheme's default port. Only accept it
+    // when that is genuinely the port we are listening on.
+    if (port === 80 && h === n) return true;
+  }
+  return false;
+}
+
 function send(res, status, obj) {
   const body = JSON.stringify(obj);
   res.writeHead(status, { 'content-type': 'application/json' });
@@ -91,6 +160,16 @@ async function createEditorServer({ files, idleTimeoutMs = 30000, clientJs = '',
   const server = http.createServer(async (req, res) => {
     try {
       const url = new URL(req.url, 'http://127.0.0.1');
+
+      // FIRST, ahead of every route including GET /edit/:id — see
+      // hostIsLoopback() above for the attack this closes. Placed here rather
+      // than on /api/asset alone: that route is merely where it was reachable,
+      // not where the hole is.
+      const addr = server.address();
+      if (!hostIsLoopback(req.headers.host, addr && addr.port)) {
+        return send(res, 403, { error: 'forbidden host' });
+      }
+
       const editMatch = url.pathname.match(/^\/edit\/(\d+)$/);
 
       // Cross-origin defense for every state-changing POST route: a
@@ -101,7 +180,13 @@ async function createEditorServer({ files, idleTimeoutMs = 30000, clientJs = '',
       // browser would otherwise let the request fire-and-forget cross-origin.
       // /api/ping is included; lib/editor/client.js's fetch calls already
       // send this header for render, save, and ping.
-      const STATE_CHANGING_POST_PATHS = new Set(['/api/render', '/api/save', '/api/ping']);
+      // v3.1.0: '/api/asset' is in this set for the same reason the other
+      // three are, and more urgently — it is the only route that CREATES a
+      // file. A route left out of this set has NO cross-origin defense at
+      // all: any page the user happens to be browsing while `md2doc --edit`
+      // is running could fire a cross-site "simple" POST at every candidate
+      // localhost port and write to disk.
+      const STATE_CHANGING_POST_PATHS = new Set(['/api/render', '/api/save', '/api/ping', '/api/asset']);
       if (req.method === 'POST' && STATE_CHANGING_POST_PATHS.has(url.pathname)) {
         const contentType = String(req.headers['content-type'] || '');
         if (!/^application\/json\b/i.test(contentType)) {
@@ -165,7 +250,13 @@ async function createEditorServer({ files, idleTimeoutMs = 30000, clientJs = '',
           `<script>${HISTORY_SRC}</script>\n` +
           `<script>${INDENT_CLAMP_SRC}</script>\n` +
           `<script>${CONVERT_MD_SRC}</script>\n` +
+          `<script>${PATCHMAP_SRC}</script>\n` +
           `<script>${SELECTION_SRC}</script>\n` +
+          `<script>${TOOLBAR_MODEL_SRC}</script>\n` +
+          `<script>${DOCSOURCE_SRC}</script>\n` +
+          `<script>${ASSET_SRC}</script>\n` +
+          `<script>${TURNDOWN_SRC}</script>\n` +
+          `<script>${PASTE_MD_SRC}</script>\n` +
           `<script>${clientJs}</script>\n`;
         // Splice at the LAST "</body>" — the document's real closing tag.
         // The first occurrence can sit inside an inlined diagram bundle's JS
@@ -192,9 +283,9 @@ async function createEditorServer({ files, idleTimeoutMs = 30000, clientJs = '',
         const { fileId, content } = await readJson(req);
         const file = absFiles[fileId];
         if (!file) return send(res, 404, { error: 'unknown file' });
-        const { bodyHtml, blocks } = await renderMarkdown(content, file, { editMode: true });
+        const { parts, blocks } = await renderMarkdown(content, file, { editMode: true });
         bumpIdle(server);
-        return send(res, 200, { bodyHtml, blocks });
+        return send(res, 200, { parts, blocks });
       }
 
       if (req.method === 'POST' && url.pathname === '/api/save') {
@@ -218,6 +309,107 @@ async function createEditorServer({ files, idleTimeoutMs = 30000, clientJs = '',
         return send(res, 200, { mtimeMs: fs.statSync(file).mtimeMs });
       }
 
+      // v3.1.0 追加 3: the image-drop / image-paste asset endpoint. Writes ONE
+      // raster image next to the document under `assets/` and answers with the
+      // relative markdown path the client then inserts as source.
+      //
+      // Six guards, none of them optional:
+      //   0. '/api/asset' is in STATE_CHANGING_POST_PATHS above (the CSRF
+      //      content-type gate). Without it this is a world-writable file
+      //      drop for any page in the user's browser.
+      //   1. fileId is type-checked. `/api/save`'s `!file` guard alone lets
+      //      `fileId: "length"` through (absFiles.length is a number, so the
+      //      lookup succeeds); Number.isInteger + a range check does not.
+      //   2. An explicit 8 MB readJson limit, not the 50 MB default.
+      //   3. The extension comes ONLY from the MIME whitelist (extFor); a
+      //      caller-supplied 'x.html' can never become the name on disk.
+      //   4. assets/ is created here — nothing else in this server creates
+      //      directories, so the first drop would otherwise be a guaranteed
+      //      ENOENT 500.
+      //   5. The string-level isWithin() check is followed by a realpath
+      //      re-check (a literal comparison cannot see a symlinked assets/,
+      //      and writeFileSync FOLLOWS symlinks), and the file itself is
+      //      opened 'wx' — which refuses to follow an existing symlink AND
+      //      closes uniqueName()'s check-then-write TOCTOU window.
+      if (req.method === 'POST' && url.pathname === '/api/asset') {
+        const body = await readJson(req, 8 * 1024 * 1024);
+        const fileId = body ? body.fileId : undefined;
+        if (!Number.isInteger(fileId) || fileId < 0 || fileId >= absFiles.length) {
+          return send(res, 400, { error: 'fileId must be an index into the open file list' });
+        }
+        const file = absFiles[fileId];
+        const ext = assetLib.extFor(body.mime);
+        if (!ext) return send(res, 400, { error: 'unsupported image type' });
+        const b64 = typeof body.data === 'string' ? body.data : '';
+        const buf = Buffer.from(b64, 'base64');
+        if (buf.length === 0) return send(res, 400, { error: 'empty image payload' });
+
+        const baseDir = path.dirname(file);
+        const assetsDir = path.join(baseDir, 'assets');
+        fs.mkdirSync(assetsDir, { recursive: true });
+        let existing;
+        try { existing = fs.readdirSync(assetsDir); } catch (e) { existing = []; }
+
+        // Ruling 10: the candidate is composed as a FULL filename before
+        // uniqueName sees it. `existing` is a raw readdir listing whose
+        // entries carry extensions, so a bare stem could never match one —
+        // a second same-named image would sail past collision detection and
+        // then hit the 'wx' flag as a hard EEXIST instead of becoming -2.
+        //
+        // The comparison is CASE-FOLDED, because the write below is not.
+        // macOS and Windows are both supported targets (it is why
+        // sanitizeName defends '\\' and ':'), and their filesystems are
+        // case-insensitive: `existing.indexOf('Shot.png')` misses an on-disk
+        // `shot.png`, so no '-2' is generated, open(..., 'wx') returns EEXIST
+        // and the user gets a generic 「圖片上傳失敗」 that repeats identically
+        // on every retry. asset.js is reviewed and unchanged — the numbering
+        // is still entirely its own; only the SPACE the question is asked in
+        // moves. The user's original stem casing is then restored, so a
+        // dropped `Shot.png` is still written as `Shot.png`.
+        const stem = assetLib.sanitizeName(body.name);
+        const desiredLower = (stem + ext).toLowerCase();
+        const pickedLower = assetLib.uniqueName(
+          desiredLower, existing.map((e) => String(e).toLowerCase()));
+        let name;
+        if (pickedLower === desiredLower) {
+          name = stem + ext;
+        } else {
+          // uniqueName only ever inserts '-<n>' immediately before the
+          // extension, so that suffix is what is lifted back across. Matched
+          // rather than sliced by length: toLowerCase() is not guaranteed to
+          // preserve length for every code point.
+          const m = /(-\d+)$/.exec(pickedLower.slice(0, pickedLower.length - ext.length));
+          name = stem + (m ? m[1] : '') + ext;
+        }
+        const target = path.join(assetsDir, name);
+        if (!assetLib.isWithin(toPosixPath(assetsDir), toPosixPath(target))) {
+          return send(res, 400, { error: 'refused: asset path escapes the assets directory' });
+        }
+        // Second boundary, against the filesystem rather than the string: a
+        // pre-existing `assets` SYMLINK pointing anywhere at all passes the
+        // check above unchanged, because that check only ever saw text.
+        let realBase, realAssets;
+        try {
+          realBase = fs.realpathSync(baseDir);
+          realAssets = fs.realpathSync(assetsDir);
+        } catch (e) {
+          return send(res, 500, { error: 'cannot resolve the assets directory' });
+        }
+        if (!assetLib.isWithin(toPosixPath(realBase), toPosixPath(realAssets))) {
+          return send(res, 400, { error: 'refused: assets directory escapes the document directory' });
+        }
+        try {
+          fs.writeFileSync(path.join(realAssets, name), buf, { flag: 'wx' });
+        } catch (e) {
+          if (e && e.code === 'EEXIST') {
+            return send(res, 409, { error: 'asset already exists: ' + name });
+          }
+          throw e;
+        }
+        bumpIdle(server);
+        return send(res, 200, { name, path: assetLib.relPath(name) });
+      }
+
       if (req.method === 'POST' && url.pathname === '/api/ping') {
         bumpIdle(server);
         res.writeHead(204);

package/lib/editor/toolbar-model.js

@@ -0,0 +1,160 @@
+'use strict';
+/* UMD, same shape as convert-md.js / lineops.js: `require`-able in node for
+   the unit tests, and injected into the editor page as
+   `window.md2docToolbarModel` (lib/editor/server.js). client.js is inlined
+   into the page as a plain <script>, not bundled, so a bare require(...) at
+   the factory's top level would be an undefined identifier in the browser.
+   This module is pure button-model arithmetic: no `document`, `window`, or
+   `navigator` reference anywhere below. */
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) module.exports = factory();
+  else root.md2docToolbarModel = factory();
+})(typeof self !== 'undefined' ? self : this, function () {
+
+// The 22-button roster, spec §4 table (`export▾` moved out of scope — no
+// browser-reachable export path). Six groups, in render order; group order
+// here doubles as separator placement for the caller (a separator sits
+// between consecutive groups).
+const BUTTON_DEFS = [
+  // history
+  { id: 'undo', group: 'history', label: 'Undo', icon: '↶', title: '復原 (Ctrl+Z)', toggle: false },
+  { id: 'redo', group: 'history', label: 'Redo', icon: '↷', title: '重做 (Ctrl+Y)', toggle: false },
+
+  // block
+  { id: 'headings', group: 'block', label: 'H', icon: 'H', title: '標題', toggle: true },
+  { id: 'quote', group: 'block', label: '❝', icon: '❝', title: '引用', toggle: true },
+  { id: 'code', group: 'block', label: '</>', icon: '</>', title: '程式碼區塊', toggle: true },
+  { id: 'list', group: 'block', label: '•', icon: '•', title: '項目符號列表', toggle: true },
+  { id: 'ordered-list', group: 'block', label: '1.', icon: '1.', title: '編號列表', toggle: true },
+  { 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 },
+
+  // indent
+  { id: 'outdent', group: 'indent', label: '⇤', icon: '⇤', title: '減少縮排', toggle: false },
+  { id: 'indent', group: 'indent', label: '⇥', icon: '⇥', title: '增加縮排', toggle: false },
+
+  // insert
+  { id: 'table', group: 'insert', label: '⊞', icon: '⊞', title: '插入表格', toggle: false },
+  { id: 'insert-before', group: 'insert', label: '⬆', icon: '⬆', title: '在上方插入區塊', toggle: false },
+  { id: 'insert-after', group: 'insert', label: '⬇', icon: '⬇', title: '在下方插入區塊', toggle: false },
+  { id: 'line', group: 'insert', label: '―', icon: '―', title: '插入分隔線', toggle: false },
+  { id: 'image', group: 'insert', label: '🖼', icon: '🖼', title: '插入圖片', toggle: false },
+
+  // view
+  { id: 'outline', group: 'view', label: '☰', icon: '☰', title: '大綱', toggle: false },
+  { id: 'preview', group: 'view', label: '👁', icon: '👁', title: '預覽', toggle: true },
+];
+
+const BUTTONS = Object.freeze(BUTTON_DEFS.map((b) => Object.freeze(Object.assign({}, b))));
+
+const GROUPS = Object.freeze(['history', 'block', 'inline', 'indent', 'insert', 'view']);
+
+// Buttons that stay enabled even when there is no block at all (the zeroed
+// 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} }
+function deriveState(ctx) {
+  const c = ctx || {};
+  const blockType = c.blockType;
+  const indent = c.indent;
+  const headingDepth = c.headingDepth;
+  const inList = !!c.inList;
+  const listOrdered = !!c.listOrdered;
+  const mode = c.mode;
+  const hasBlock = blockType !== null && blockType !== undefined;
+
+  const state = {};
+  for (const b of BUTTONS) {
+    state[b.id] = { active: 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';
+
+  // headings: dropdown whose label tracks the current heading depth.
+  state.headings.label = blockType === 'heading' ? 'H' + headingDepth : 'H';
+  state.headings.active = blockType === 'heading';
+
+  // other block-type-driven active flags
+  state.quote.active = blockType === 'blockquote';
+  state.code.active = blockType === 'code';
+
+  // list vs ordered-list are mutually exclusive by construction: exactly one
+  // reflects the current list's ordered-ness, the other stays inactive.
+  if (inList && listOrdered) {
+    state['ordered-list'].active = true;
+    state.list.active = false;
+  } else if (inList && !listOrdered) {
+    state.list.active = true;
+    state['ordered-list'].active = false;
+  }
+
+  // outdent/indent guard on list membership and current depth.
+  if (!inList) {
+    state.outdent.disabled = true;
+    state.indent.disabled = true;
+  }
+  if (indent === 0) {
+    state.outdent.disabled = true;
+  }
+
+  // check is a `block`-group conversion target, same as quote/code/list/
+  // ordered-list: it turns the CURRENT block into a task-list item, so it is
+  // not gated on already being in a list — a bare paragraph is exactly the
+  // primary case (spec review ruling: gating it on inList made it dead for
+  // that case).
+
+  // No block at all (rerenderAll's zeroed state): everything disabled except
+  // the handful of buttons that don't depend on having a focused block.
+  if (!hasBlock) {
+    for (const b of BUTTONS) {
+      if (!NO_BLOCK_ALLOWED.has(b.id)) state[b.id].disabled = true;
+    }
+  }
+
+  // v3.2.0: the five inline-format buttons are dead unless there is a
+  // non-collapsed selection INSIDE the burst's own edit surface.
+  // applyMarkToggle() (client.js, `function applyMarkToggle`) and
+  // applyLinkToggle() (just below it) both return immediately when the root
+  // is null, when there is no range, when the range is collapsed, or when
+  // either of its containers lies outside that root — `link` included (it
+  // does not even open the prompt).
+  //
+  // `hasSelection` is that whole four-part refusal test, computed once on the
+  // client as hasFormattableSelection() and handed in here — so "no button is
+  // enabled that the action would silently refuse" holds for these five. It
+  // is NOT a claim about the model as a whole: every other enablement rule
+  // below is derived from the block record, and a runtime action can still
+  // 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']) {
+      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.
+  if (mode === 'source') {
+    for (const b of BUTTONS) {
+      state[b.id].disabled = b.id !== 'preview';
+    }
+  }
+
+  return state;
+}
+
+return { BUTTONS, GROUPS, deriveState };
+});

package/lib/md2doc.js

@@ -313,7 +313,7 @@ function renderEditModeList(listToken, blocks, biRef, out) {
     item.tokens.filter((tk) => tk.type === 'list')
       .forEach((ct) => renderEditModeList(ct, blocks, biRef, parts));
   });
-  return parts.join('\n');
+  return parts;
 }
 
 async function renderMarkdown(mdText, srcPath, opts = {}) {
@@ -487,6 +487,10 @@ async function renderMarkdown(mdText, srcPath, opts = {}) {
   }
 
   let bodyHtml;
+  // v3.2.0: the per-block edit-mode parts (1:1 with `blocks`), already baked.
+  // Stays null outside editMode — the reader/PDF path has no per-block DOM to
+  // patch, only the whole-document `bodyHtml`.
+  let parts = null;
   let tocHtml = '';
   let serializedSections = '[]';
   // NOTE: intentionally no try/catch here. A throw from marked/katex parsing
@@ -893,7 +897,7 @@ ${itemsHtml}
       // exactly what the whole-document parse would emit for that token,
       // using the same renderer/options set above.
       const tokens = marked.lexer(mdPre);
-      const parts = [];
+      parts = [];
       // `v` is the block cursor; `prevLi`/`types` are the §3.8 run state the
       // flat list renderer above threads through its own recursion (see
       // liRunStartsHere()).
@@ -901,7 +905,7 @@ ${itemsHtml}
       for (const t of tokens) {
         if (t.type === 'space') continue;
         if (t.type === 'list') {
-          parts.push(renderEditModeList(t, blocks, biRef));
+          parts.push(...renderEditModeList(t, blocks, biRef));
           continue;
         }
         resetLiRunState(biRef); // §3.8 rule (c): a non-li block ends every run
@@ -920,6 +924,14 @@ ${itemsHtml}
         throw new Error('edit-mode render consumed ' + biRef.v +
           ' blocks but the block map has ' + blocks.length);
       }
+      // v3.2.0: bake EACH part, then join — not join-then-bake. The patch path
+      // inserts parts[i] straight into the DOM and the client has no graphviz
+      // renderer (__md2docInitDiagrams handles only mermaid and WaveDrom), so
+      // an unbaked part lands as an empty <div class="graphviz">. bakeGraphviz
+      // short-circuits on parts with no data-graphviz-src, and each placeholder
+      // falls entirely inside one part, so this is byte-identical to baking the
+      // joined string.
+      parts = await Promise.all(parts.map(bakeGraphviz));
       bodyHtml = parts.join('\n');
     } else {
       bodyHtml = marked.parse(mdPre);
@@ -1328,6 +1340,48 @@ ${itemsHtml}
     content: ""; position: absolute;
     left: calc(-1 * (var(--ed-gutter-w) + var(--ed-gutter-shift))); top: 0;
     width: calc(var(--ed-gutter-w) + var(--ed-gutter-shift)); height: 100%;
+  }
+  /* v3.1.0 §4: room for the fixed toolbar (.ed-toolbar, further up this
+     stylesheet). The bar is position:fixed — NOT sticky — because
+     lib/editor/client.js mounts it on document.body: rerenderAll() replaces
+     .content's innerHTML wholesale, so a toolbar living inside the content
+     column would be destroyed by the first commit with nothing to rebuild
+     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.
+     .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
+     bottom. */
+  .page-layout { padding-top: var(--ed-toolbar-h); }
+  .reader-sidebar {
+    top: calc(24px + var(--ed-toolbar-h));
+    height: calc(100vh - 48px - var(--ed-toolbar-h));
+  }
+  @media (max-width: 1080px) {
+    .page-layout { padding-top: calc(60px + 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.
+     ⚠ It deliberately does NOT reuse body[data-sidebar-open], and the reason
+     was measured rather than reasoned: the rule
+     'body[data-sidebar-open] .sidebar-scrim { display: block; }' sits at BASE scope in this
+     stylesheet, not inside the max-width:1080px drawer block. Giving that
+     same attribute a second, desktop meaning therefore also paints
+     .sidebar-scrim (position:fixed; inset:0; z-index:98; rgba(0,0,0,.35))
+     across the whole viewport — the desktop page went grey and
+     click-through-dead, and the scrim's own click handler (which calls
+     setSidebarOpen(false)) meant the next click anywhere silently undid it.
+     A private attribute, written by toggleOutlineSidebar() in
+     lib/editor/client.js, leaves data-sidebar-open to the mobile drawer
+     alone and lets #sidebar-toggle's aria-expanded stay truthful.
+     The attribute names the non-default state ("hidden") because on desktop
+     the outline is a sticky column that is SHOWN by default; the mobile
+     drawer keeps its own "open" attribute for the same reason in reverse. */
+  @media (min-width: 1081px) {
+    body[data-ed-outline-hidden] .reader-sidebar,
+    body[data-ed-outline-hidden] .sidebar-splitter { display: none; }
   }`;
 
   const html = `<!DOCTYPE html>
@@ -2480,6 +2534,110 @@ ${itemsHtml}
   .ed-seltb-i { font-style: italic; }
   .ed-seltb-s { text-decoration: line-through; }
   .ed-seltb-u { text-decoration: underline; }
+  /* v3.1.0 §4: the always-visible editing toolbar. Its numeric language is
+     .lightbox-bar's (8px/12px padding, 6px gap, 13px type) over .ed-seltb's
+     dark pill, so the two floating surfaces read as one family.
+     position:fixed, NOT sticky: lib/editor/client.js mounts this on
+     document.body because rerenderAll() replaces .content's innerHTML
+     wholesale and would silently destroy a toolbar mounted inside it.
+     Deliberately does NOT read any --ed-gutter-* token — those describe the
+     ⠿/＋ pair's geometry and this is a new, unrelated scale (the height is
+     its own token because the edit-mode layout chunk at the end of this
+     stylesheet has to reserve exactly that much room for it).
+     z-index sits above the mobile drawer (99) and .sidebar-toggle (100) but
+     below .ed-conflict (999): a save conflict must always be reachable. */
+  :root { --ed-toolbar-h: 44px; }
+  .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;
+    flex-wrap: nowrap; overflow-x: auto; overflow-y: hidden;
+    gap: 6px; padding: 8px 12px;
+    background: rgba(16, 18, 21, 0.92); color: #e6edf3;
+    font-size: 13px;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.25);
+  }
+  .ed-toolbar-sep {
+    flex: 0 0 auto; width: 1px; height: 18px; margin: 0 2px;
+    background: rgba(255, 255, 255, 0.25);
+  }
+  .ed-toolbar-btn {
+    flex: 0 0 auto;
+    min-width: 28px; height: 26px; padding: 0 8px;
+    border: 1px solid rgba(255, 255, 255, 0.25); border-radius: 6px;
+    background: rgba(255, 255, 255, 0.08); color: inherit;
+    font: inherit; font-size: 13px; line-height: 1;
+    white-space: nowrap; cursor: pointer;
+  }
+  .ed-toolbar-btn:hover:not(:disabled) { background: rgba(255, 255, 255, 0.18); }
+  .ed-toolbar-btn:disabled { opacity: 0.38; cursor: default; }
+  .ed-toolbar-btn[aria-pressed="true"] {
+    background: #e6edf3; color: #101215; border-color: #e6edf3;
+  }
+  .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
+     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
+     position: fixed box — it anchors to the browser viewport, not to
+     .ed-toolbar's scrolled content, so it does not drift as the button
+     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
+     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
+     regression, this time on content someone can actually see and try to
+     click. */
+  .ed-toolbar-status { position: fixed; top: 0; right: 12px;
+    height: var(--ed-toolbar-h); line-height: var(--ed-toolbar-h);
+    min-width: 7rem; text-align: right; font-size: 12px; opacity: .8;
+    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. */
+  .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);
+  }
+  .ed-toolbar-menu[hidden] { display: none; }
+  .ed-toolbar-menu-btn {
+    min-width: 120px; padding: 4px 10px; text-align: left;
+    border: none; border-radius: 4px; background: transparent; color: inherit;
+    font: inherit; font-size: 13px; line-height: 1.4; cursor: pointer;
+  }
+  .ed-toolbar-menu-btn:hover { background: rgba(255, 255, 255, 0.18); }
+  /* 追加 4: the whole-document source escape hatch. Replaces the rendered
+     content column for the duration of source mode; the document's own
+     lines[] is untouched until the mode is left (see docsource.js). */
+  .ed-source {
+    display: block; width: 100%; box-sizing: border-box;
+    min-height: 70vh; padding: 12px;
+    font-family: monospace; font-size: 13px; line-height: 1.6;
+    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;
@@ -4132,8 +4290,11 @@ ${mermaidInitTag}`)
 </html>`;
 
   const bakedHtml = await bakeGraphviz(html);
+  // editMode's bodyHtml is already baked per-part above; re-baking here is a
+  // short-circuit no-op (bakeGraphviz bails out when there's no
+  // data-graphviz-src left). Non-editMode bodyHtml is baked here as before.
   const bakedBody = await bakeGraphviz(bodyHtml);
-  return { html: bakedHtml, bodyHtml: bakedBody, blocks };
+  return { html: bakedHtml, bodyHtml: bakedBody, parts, blocks };
 }
 module.exports = { renderMarkdown };