@helping-ai-workflow/md2doc 3.0.1 → 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/table-md.js

@@ -365,19 +365,18 @@
     // from the last position to the first and requires ALL THREE widths
     // dropped even though "Name" and "Note" still sit at index-shifted but
     // TEXT-unchanged positions; only text-matching, combined with the
-    // all-or-nothing gate below, gets that right). A mismatch that is
-    // simply a RENAMED header (or a dragged ROW promoting a different row
-    // to "header" — the per-column-alignment-survives-header-change
-    // scenario) is walked the exact same way as any other mismatch: it
-    // doesn't advance `j`, so — per the all-or-nothing gate below — it
-    // discards the width source for the WHOLE table, not just that one
-    // column. That reflow-on-rename is TODAY'S shipped, pre-existing
-    // behaviour (v3.0.0 already reflows the whole table on any edit; a
-    // rename doing the same is not a regression) — deliberately NOT
-    // "fixed" here per the 2026-09-02 review round-1 ruling: detecting
-    // rename-vs-permutation is design work that doesn't belong in a patch
-    // release. See test/table-width.test.js's "renamed header" case, which
-    // pins this so the next change to it is deliberate.
+    // all-or-nothing gate below, gets that right).
+    //
+    // v3.0.2 superseded the 2026-09-02 review round-1 ruling that a renamed
+    // header or a deleted column must discard the whole table's width memory:
+    // the forward scan below skips an original column that no longer appears,
+    // and only a genuine column REORDER still takes the whole-table refusal.
+    // What is still NOT handled — deliberately — is a table with DUPLICATE
+    // header names: the scan pairs by TEXT, so after a delete a survivor can
+    // inherit the same-named other column's width. Telling the instances
+    // apart needs identity matching, which is a larger change than this
+    // patch release carries. See test/table-width.test.js cases 14, 15, 20,
+    // 21, 23 and 24, which pin every branch of the above.
     const original = columnWidthsOf(originalMd);
     let widths = null;
     // Set for a column that falls off the END of the original header list
@@ -415,31 +414,51 @@
     const matchedSepFields = new Array(headerContents.length);
     if (original) {
       const matched = new Array(headerContents.length);
+      // v3.0.2: a FORWARD SCAN, not the pre-v3.0.2 lockstep compare. The
+      // lockstep version left `j` parked on the first original column that
+      // did not match, so it could never recover from one mismatch — and
+      // "some original column was never consumed" is the signature of a
+      // DELETE and a RENAME just as much as of the column REORDER the gate
+      // below actually exists to refuse. Scanning forward lets a delete or
+      // a rename skip the original it no longer has, and moves the refusal
+      // into an explicit test (`moved`) instead of a side effect of `j`.
+      const unmatchedNames = [];
       let j = 0;
       for (let i = 0; i < headerContents.length; i++) {
-        if (j < original.headerFields.length &&
-            headerContents[i].trim() === original.headerFields[j].trim()) {
-          matched[i] = original.widths[j];
-          matchedSepFields[i] = original.sepFields[j];
-          j++;
+        const name = headerContents[i].trim();
+        let k = -1;
+        for (let q = j; q < original.headerFields.length; q++) {
+          if (original.headerFields[q].trim() === name) { k = q; break; }
+        }
+        if (k >= 0) {
+          matched[i] = original.widths[k];
+          matchedSepFields[i] = original.sepFields[k];
+          j = k + 1;
         } else {
           matched[i] = undefined;
+          // The EMPTY name is exempt from the reorder test below, and the
+          // exemption is load-bearing, not defensive: insertColumn()
+          // (lib/editor/client.js:6448-6465) creates a th (or td) with no
+          // content at all — the element itself at line 6451 — so every
+          // inserted column is named ''. A table that
+          // already holds one blank header would therefore see the new
+          // column's '' "found elsewhere in the original" and take the
+          // whole-table refusal — a straight regression against v3.0.1 on
+          // the ordinary insert-a-column-twice flow.
+          if (name !== '') unmatchedNames.push(name);
           if (j >= original.headerFields.length) sepFallbackNatural[i] = true;
         }
       }
-      // Only trust this walk as a width source AT ALL if it found EVERY
-      // original column, in order, somewhere in the current header row (j
-      // reached the end). A PARTIAL match — some columns matched, some
-      // didn't — means the table's column identity changed in a way this
-      // can't safely map: a column DRAG that reorders existing columns
-      // (rather than just adding one) still finds two of three headers
-      // byte-identical to their originals via this same greedy walk, but
-      // "a column move must carry its alignment with it" requires ALL
-      // THREE widths dropped, not just the moved one — a per-column guess
-      // here would silently keep stale padding on a column that only
-      // happens to still have the same text. So a partial match discards
-      // the width source for the WHOLE table, same as no original at all.
-      if (j === original.headerFields.length) {
+      // A column that could not find itself in what remains of the original,
+      // yet whose name IS somewhere in the original, has MOVED relative to
+      // the others. That is the one shape a per-column width guess gets
+      // silently wrong ("a column move must carry its alignment with it"),
+      // so it still discards the width source for the WHOLE table. A name
+      // that is absent from the original entirely is an insert or a rename:
+      // nothing stale to carry, so its neighbours keep their widths.
+      const moved = unmatchedNames.some((n) =>
+        original.headerFields.some((f) => f.trim() === n));
+      if (!moved) {
         widths = matched;
         // A matched column is then widened, for every row of that column
         // at once (header + separator + every body row), to whatever the
@@ -485,9 +504,22 @@
       //      (`widths` itself is null: cases 1 and 7 stay byte-identical to
       //      the pre-v3.0.1 minimal form), or a mismatch that is neither a
       //      matched-but-non-uniform column nor a trailing new one (a
-      //      renamed header, or a row-drag promotion) — moot in practice,
-      //      since the all-or-nothing gate above already discarded
-      //      `widths` entirely for those cases.
+      //      renamed header, or a row-drag promotion). Since v3.0.2 the
+      //      gate above no longer discards `widths` for a rename, so this
+      //      branch is now the live path for a renamed column: its header
+      //      and body rows take padField()'s `|| 0` natural width and its
+      //      separator takes the bare 3-dash minimal. A row-drag promotion
+      //      ONLY leaves every column unmatched — and so only produces the
+      //      same all-undefined `widths`, byte-for-byte the `null` output,
+      //      because every preference above falls through to this 0 — when
+      //      none of the promoted row's cells collides with an ORIGINAL
+      //      header name. A collision re-enters the by-text match above (the
+      //      `k >= 0` branch), so that column inherits the OLD column's
+      //      width and the row emits half-aligned rather than fully minimal
+      //      (measured: promoting a 'Note' / 'zzz' row past an original
+      //      'Name | Note' header keeps column 0 at the original Note
+      //      column's width while column 1 falls to 3-dash minimal). The two
+      //      promotion scenarios this suite covers are both collision-free.
       const origField = matchedSepFields[i];
       const w = widths
         ? (widths[i] !== undefined ? widths[i]

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 };
+});