@helping-ai-workflow/md2doc 3.3.0 → 3.4.2

package/lib/editor/server.js

@@ -2,6 +2,8 @@
 const fs = require('fs');
 const path = require('path');
 const http = require('http');
+const crypto = require('crypto');
+const drawioLib = require('../drawio.js');
 const { renderMarkdown } = require('../md2doc.js');
 
 const LINEOPS_SRC = fs.readFileSync(path.join(__dirname, 'lineops.js'), 'utf8');
@@ -54,6 +56,50 @@ 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');
 
+// v3.4.0 batch3 Task 6: the wavedrom GUI's four modules.
+//
+// wave-codec.js / wave-geometry.js / wave-store.js are plain CommonJS ON
+// PURPOSE, and rewriting them into the UMD header every other module here uses
+// is not available: test/wave-codec.test.js bans the spelling `require(` in the
+// codec outright, test/wave-geometry.test.js bans every host-object read a UMD
+// header performs (`typeof self`, `root.x = …`), and test/wave-store.test.js
+// pins the store's require list to exactly `["require('./wave-codec.js')"]`. So
+// the browser gets them through the small CommonJS shim below instead —
+// the module text itself is inlined byte for byte.
+//
+// wave-ui.js is UMD like its neighbours and needs no shim; in the page it
+// defines `window.md2docWaveUi` and takes the other three as parameters.
+const WAVE_CODEC_SRC = fs.readFileSync(path.join(__dirname, 'wave-codec.js'), 'utf8');
+const WAVE_GEOMETRY_SRC = fs.readFileSync(path.join(__dirname, 'wave-geometry.js'), 'utf8');
+const WAVE_STORE_SRC = fs.readFileSync(path.join(__dirname, 'wave-store.js'), 'utf8');
+const WAVE_UI_SRC = fs.readFileSync(path.join(__dirname, 'wave-ui.js'), 'utf8');
+
+// One CommonJS module, wrapped so a plain <script> can carry it.
+//
+// The `'use strict'` is the FIRST statement of the script, not of the wrapper
+// function, so the whole tag — module body included — is strict. That is
+// load-bearing rather than tidy: the store deep-freezes every document it
+// keeps, and a frozen object only BITES in strict mode. test/wave-store.test.js
+// T24 measured the sloppy-mode alternative — four of five writes to a frozen
+// document were silent — so a wrapper that lost the prologue would put the
+// original corruption back and make it quieter.
+//
+// `require` here resolves by basename against what has already been shimmed,
+// which is enough for the only two edges that exist (both './wave-codec.js')
+// and stays a total function for anything else: an unknown name answers
+// undefined and the module that asked fails where it asked.
+function waveModuleTag(name, src) {
+  return '<script>\'use strict\';\n' +
+    'window.__md2docWave = window.__md2docWave || {};\n' +
+    '(function () {\n' +
+    'var module = { exports: {} };\n' +
+    'var exports = module.exports;\n' +
+    'function require(p) { return window.__md2docWave[String(p).split(\'/\').pop()]; }\n' +
+    src + '\n' +
+    'window.__md2docWave[' + JSON.stringify(name) + '] = module.exports;\n' +
+    '})();</script>\n';
+}
+
 // 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
@@ -194,6 +240,235 @@ async function createEditorServer({
   let neverOpenedTimer = null;
   let started = false;
 
+  // v3.4.0 batch2 Task 6 — Ruling B2-2: watch every `.drawio`/`.xml` file the
+  // CURRENTLY OPEN document references, and let /api/ping's already-firing
+  // 10s heartbeat (see its own comment below) double as the staleness check,
+  // rather than inventing a push transport server.js has never had (no
+  // WebSocket/SSE/fs.watch anywhere in this stack — see this task's
+  // investigation note).
+  //
+  // TWO maps, and the split is the whole point of fix round 1:
+  //
+  //   drawioWatch   fileId -> { refs }.  WHAT THE LAST BAKE RESOLVED.
+  //                 The list of absolute paths that render actually resolved,
+  //                 i.e. the only paths worth stat'ing for this document.
+  //                 Fix round 2 (re-review G13): this used to carry a
+  //                 `stamps` Map as well, which nothing ever read — the new
+  //                 tab's baseline comes from trackDrawioRefs()'s RETURN
+  //                 value, handed straight to registerDrawioClient() in the
+  //                 same expression. Dead state in a freshly written
+  //                 mechanism is a maintenance trap, so it is gone; the stamp
+  //                 lib/md2doc.js takes before the bake (review F4) still
+  //                 travels, just not through here.
+  //
+  //   drawioClients clientKey -> { fileId, stamps, pending, lastSeen }.
+  //                 WHAT ONE BROWSER TAB IS ACTUALLY SHOWING. Review F3: the
+  //                 baseline used to be per-file, so with two tabs open on one
+  //                 document the first to ping consumed the one signal and the
+  //                 second sat on a stale diagram looking perfectly healthy.
+  //                 A tab gets its id minted by GET /edit/:id — the same
+  //                 response that paints its DOM — so its baseline is exactly
+  //                 the bytes it is displaying, with no window in which
+  //                 another tab's render could seed it wrong.
+  //
+  // Review F2's invariant: a client's `stamps` advances ONLY when that client
+  // has told us its DOM now shows those bytes. Until then every heartbeat
+  // keeps reporting the same staleness, so every one of the client's bail
+  // paths (network error, mid-gesture DOM, focus inside the block, …) really
+  // does get retried on the next tick instead of losing the change forever.
+  const drawioWatch = new Map();
+  const drawioClients = new Map();
+  // The token that identifies a CONTENT VERSION, not a ping. Minted once per
+  // (client, observed stamp set) and repeated verbatim on every later ping
+  // that still sees the same bytes — if it were per-ping, a refresh that took
+  // longer than one 10s beat would always ack a token the server had already
+  // superseded, and the pair would never converge.
+  let drawioTokenSeq = 0;
+  let drawioLastSweep = 0;
+  // 10 minutes = 60 missed heartbeats. A tab that has not pinged in that long
+  // is closed (or its machine slept); keeping its entry would leak one small
+  // object per tab ever opened for the life of the server process.
+  const DRAWIO_CLIENT_IDLE_MS = 10 * 60 * 1000;
+
+  function drawioClientKey(fileId, clientId) {
+    if (typeof clientId !== 'string' || clientId === '') return null;
+    if (typeof fileId !== 'number' || !isFinite(fileId)) return null;
+    return String(fileId) + '\u0000' + clientId;
+  }
+
+  function sweepDrawioClients(now) {
+    if (now - drawioLastSweep < 60 * 1000) return;
+    drawioLastSweep = now;
+    for (const [k, c] of drawioClients) {
+      if (now - c.lastSeen > DRAWIO_CLIENT_IDLE_MS) drawioClients.delete(k);
+    }
+  }
+
+  // Fix round 2 (re-review G5). A tab that is still talking to us is alive by
+  // definition, so a well-formed clientId with no entry gets one back rather
+  // than being answered 204 forever with no signal and no route back but a
+  // reload. Reachable the moment a laptop sleeps or a background tab's timers
+  // are frozen for longer than the sweep window — and before this, the tab's
+  // own returning heartbeat was what deleted it (the sweep ran BEFORE the
+  // lastSeen refresh), so the failure mode was silent, permanent, and caused
+  // by the recovery attempt itself.
+  //
+  // Seeded with an EMPTY stamp map on purpose, not with the last bake's: we
+  // do not know what that tab's DOM is showing, and an empty baseline makes
+  // the next check report stale, which costs one re-render the client then
+  // acks. Wrong in the safe direction (one redundant bake) instead of the
+  // unsafe one (a tab that silently never updates again).
+  //
+  // Fix round 3 (re-review2 H4): the bound is EVICT-OLDEST, applied at BOTH
+  // doors. Round 2 capped only the ping door and refused past the cap, which
+  // was wrong twice over: `GET /edit/:id` wrote into the same map with no
+  // check at all, and refusing meant that once 64 entries accumulated, a
+  // genuinely swept live tab could never re-register — G5's own guard rail
+  // reintroducing exactly the silent deafness G5 was raised about. Dropping
+  // the least-recently-seen entry instead keeps the map at <= MAX from both
+  // doors AND never turns a live tab away: the entry we drop is by
+  // construction the one that has gone quietest.
+  //
+  // WHAT THIS BOUNDS, EXACTLY (fix round 4, re-review3 M3 — the sentence this
+  // replaces claimed more than the code delivers): **the map, not the render
+  // load.** Round 2's refuse-at-cap did cap the bakes a fresh-id-per-ping
+  // caller could provoke — past 64 ids it answered a bare 204, so no token and
+  // no `/api/render` followed. Evict-oldest removes that ceiling on purpose:
+  // a caller rotating a new id every ping now gets `{stale, token}` every
+  // time and can drive `/api/render` — and therefore headless-Chromium bakes
+  // — without bound. That trade is deliberate, because the refusal it removes
+  // is exactly what made a swept live tab permanently deaf, and availability
+  // for the real tab is worth more here than a ceiling on a caller that is
+  // already inside the loopback-only, Host-checked front door (see the
+  // DNS-rebinding note above `hostIsLoopback`). Recorded as a known
+  // limitation rather than guarded: every guard added to this mechanism so
+  // far has produced the next round's finding.
+  const DRAWIO_CLIENT_MAX = 64;
+  function makeRoomForDrawioClient() {
+    while (drawioClients.size >= DRAWIO_CLIENT_MAX) {
+      let oldestKey = null, oldestSeen = Infinity;
+      for (const [k, c] of drawioClients) {
+        if (c.lastSeen < oldestSeen) { oldestSeen = c.lastSeen; oldestKey = k; }
+      }
+      if (oldestKey === null) return;   // unreachable while size > 0
+      drawioClients.delete(oldestKey);
+    }
+  }
+  function ensureDrawioClient(fileId, clientId, now) {
+    const key = drawioClientKey(fileId, clientId);
+    if (key === null) return null;
+    let c = drawioClients.get(key);
+    if (c) { c.lastSeen = now; return c; }
+    if (!drawioWatch.has(fileId)) return null;
+    makeRoomForDrawioClient();
+    c = { fileId, stamps: new Map(), pending: null, lastSeen: now };
+    drawioClients.set(key, c);
+    return c;
+  }
+
+  // Called after every render that actually re-reads the source markdown
+  // (GET /edit/:id and POST /api/render both call renderMarkdown() fresh).
+  // Records WHAT WAS BAKED; deliberately does NOT touch any client's
+  // baseline — that is review F2's invariant, and the trap F2 names is
+  // exactly this function: /api/render runs BEFORE the client has decided
+  // whether it can apply the result, so advancing anything here would lose
+  // every post-response bail.
+  function trackDrawioRefs(fileId, refs) {
+    const list = Array.isArray(refs) ? refs : [];
+    const paths = [];
+    const stamps = new Map();
+    for (const r of list) {
+      const abs = r && typeof r.path === 'string' ? r.path : null;
+      if (!abs || stamps.has(abs)) continue;
+      paths.push(abs);
+      stamps.set(abs, r.stamp === undefined ? null : r.stamp);
+    }
+    drawioWatch.set(fileId, { refs: paths });
+    return stamps;
+  }
+
+  function registerDrawioClient(fileId, stamps) {
+    const clientId = crypto.randomBytes(12).toString('hex');
+    const key = drawioClientKey(fileId, clientId);
+    if (key === null) return clientId;   // unreachable today; never key on null
+    const now = Date.now();
+    makeRoomForDrawioClient();           // H4: this door is bounded too
+    drawioClients.set(key, {
+      fileId, stamps: new Map(stamps), pending: null, lastSeen: now,
+    });
+    sweepDrawioClients(now);             // G5: after the write, never before
+    return clientId;
+  }
+
+  function sameStamps(a, b) {
+    if (a.size !== b.size) return false;
+    for (const [k, v] of a) { if (!b.has(k) || b.get(k) !== v) return false; }
+    return true;
+  }
+
+  // (a) requirement: a document with no drawio references must cost this
+  // heartbeat NOTHING beyond the Map lookups below — zero fs.statSync calls,
+  // same as the bare 204 this replaces. Only a document that actually has
+  // `refs.length > 0` pays for the stat loop that follows.
+  //
+  // Returns the token to hand the client, or null for "nothing stale".
+  function checkDrawioStale(fileId, clientId) {
+    const state = drawioWatch.get(fileId);
+    if (!state || state.refs.length === 0) return null;
+    const key = drawioClientKey(fileId, clientId);
+    if (key === null) return null;
+    const c = drawioClients.get(key);
+    // An unknown client here is one touchDrawioClient() declined to
+    // (re-)register: a page from before this feature (no clientId at all), a
+    // malformed id, or a fileId this server never rendered. It gets the old
+    // bare 204 rather than a signal it has no baseline to interpret. Note
+    // that hitting DRAWIO_CLIENT_MAX is NOT one of those cases any more —
+    // see makeRoomForDrawioClient() (re-review2 H4).
+    if (!c) return null;
+    const now = new Map();
+    let changed = false;
+    for (const p of state.refs) {
+      const st = drawioLib.drawioStampOf(p);
+      now.set(p, st);
+      if (c.stamps.get(p) !== st) changed = true;
+    }
+    if (!changed) { c.pending = null; return null; }
+    if (c.pending && sameStamps(c.pending.stamps, now)) return c.pending.id;
+    drawioTokenSeq += 1;
+    c.pending = { id: 'd' + drawioTokenSeq, stamps: now };
+    return c.pending.id;
+  }
+
+  // Keeps a live tab out of the idle sweep above (re-registering it if the
+  // sweep already got there — G5), and is the one place the sweep is actually
+  // driven from: the heartbeat is the only thing that fires often enough to
+  // be worth hanging it on, and it is throttled to at most once a minute
+  // inside sweepDrawioClients().
+  //
+  // ORDER IS LOAD-BEARING: ensure/touch first, sweep second. The other way
+  // round, a tab returning from a >10-minute freeze is deleted by the very
+  // ping it sent to say it was back.
+  function touchDrawioClient(fileId, clientId) {
+    const now = Date.now();
+    ensureDrawioClient(fileId, clientId, now);
+    sweepDrawioClients(now);
+  }
+
+  // The client's half of F2's invariant: it sends back the token it was given
+  // ONLY after its DOM really carries that render. Anything less than a
+  // complete apply (a block skipped because the user's focus was inside it,
+  // a mid-gesture DOM, a failed fetch) sends nothing, so `stamps` stays put
+  // and the very next heartbeat reports the same staleness again.
+  function ackDrawioApplied(fileId, clientId, token) {
+    if (typeof token !== 'string' || token === '') return;
+    const key = drawioClientKey(fileId, clientId);
+    if (key === null) return;
+    const c = drawioClients.get(key);
+    if (!c || !c.pending || c.pending.id !== token) return;
+    c.stamps = c.pending.stamps;
+    c.pending = null;
+  }
+
   function bumpIdle(server) {
     if (!started) return;
     if (idleTimer) clearTimeout(idleTimer);
@@ -281,11 +556,15 @@ async function createEditorServer({
         const eol = (crlfCount > bareLf && crlfCount > bareCr) ? '\r\n'
           : (bareCr > bareLf && bareCr > crlfCount) ? '\r'
           : '\n';
-        const { html, blocks } = await renderMarkdown(mdText, file, { editMode: true });
+        const { html, blocks, drawioRefs } = await renderMarkdown(mdText, file, { editMode: true });
+        // Fix round 1 (review F3): mint this TAB's own staleness baseline from
+        // the very render that is about to paint it. Per-tab, not per-file —
+        // two tabs on one document must each get told about an external edit.
+        const drawioClientId = registerDrawioClient(fileId, trackDrawioRefs(fileId, drawioRefs));
         const lines = mdText.split(/\r\n|\r|\n/);
         assertBlockRangesFit(blocks, lines);
         const payload = JSON.stringify({
-          fileId, mtimeMs, eol, lines, blocks,
+          fileId, mtimeMs, eol, lines, blocks, drawioClientId,
         });
         const inject =
           `<script>window.__ED__ = ${payload.replace(/</g, '\\u003c')}</script>\n` +
@@ -303,6 +582,10 @@ async function createEditorServer({
           `<script>${ASSET_SRC}</script>\n` +
           `<script>${TURNDOWN_SRC}</script>\n` +
           `<script>${PASTE_MD_SRC}</script>\n` +
+          waveModuleTag('wave-codec.js', WAVE_CODEC_SRC) +
+          waveModuleTag('wave-geometry.js', WAVE_GEOMETRY_SRC) +
+          waveModuleTag('wave-store.js', WAVE_STORE_SRC) +
+          `<script>${WAVE_UI_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
@@ -329,7 +612,10 @@ async function createEditorServer({
         const { fileId, content } = await readJson(req);
         const file = absFiles[fileId];
         if (!file) return send(res, 404, { error: 'unknown file' });
-        const { parts, blocks } = await renderMarkdown(content, file, { editMode: true });
+        const { parts, blocks, drawioRefs } = await renderMarkdown(content, file, { editMode: true });
+        // Refs only — NOT any client's baseline. See trackDrawioRefs()'s own
+        // comment: the client has not yet decided whether it can apply this.
+        trackDrawioRefs(fileId, drawioRefs);
         bumpIdle(server);
         return send(res, 200, { parts, blocks });
       }
@@ -384,12 +670,46 @@ async function createEditorServer({
           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' });
 
+        // v3.4.1: two gates, not one widened whitelist.
+        //
+        // The raster gate is `extFor(body.mime)` and it is unchanged --
+        // `image/svg+xml` stays out for the reason asset.js documents (an SVG
+        // can carry <script>, and a MIME string is attacker-controlled).
+        //
+        // The drawio gate below exists because that first gate CANNOT answer
+        // for .drawio at all: browsers report `file.type === ''` for it, so
+        // v3.4.0 shipped a renderer that embeds `.drawio`/`.xml` and an insert
+        // path that answered every such upload with 'unsupported image type'.
+        //
+        // Its rule is the half that makes it safe: the EXTENSION picks the
+        // candidate and the CONTENT decides whether anything is written. The
+        // extension is matched against two literals and the stored value is
+        // taken from this table rather than from the name, so no casing,
+        // Unicode lookalike or double-extension in an attacker-supplied
+        // filename can become the extension on disk. A payload renamed to
+        // .xml is refused unless drawio's own parser recognises a root it
+        // writes (<mxfile> or <mxGraphModel>).
+        const DRAWIO_EXT = { '.drawio': '.drawio', '.xml': '.xml' };
+        let ext = assetLib.extFor(body.mime);
+        if (!ext) {
+          const rawName = String(body.name === null || body.name === undefined ? '' : body.name);
+          const m = /\.(drawio|xml)$/i.exec(rawName);
+          const candidate = m ? DRAWIO_EXT['.' + m[1].toLowerCase()] : null;
+          if (!candidate) return send(res, 400, { error: 'unsupported image type' });
+          // `buf` is what lands on disk, so `buf` is what gets checked --
+          // never a re-decode of `body.data`, which could differ.
+          if (!drawioLib.isDrawioXml(buf.toString('utf8'))) {
+            return send(res, 400, {
+              error: 'refused: this file is not a draw.io diagram (no <mxfile> or <mxGraphModel> root)',
+            });
+          }
+          ext = candidate;
+        }
+
         const baseDir = path.dirname(file);
         const assetsDir = path.join(baseDir, 'assets');
         fs.mkdirSync(assetsDir, { recursive: true });
@@ -458,6 +778,40 @@ async function createEditorServer({
 
       if (req.method === 'POST' && url.pathname === '/api/ping') {
         bumpIdle(server);
+        // v3.4.0 batch2 Task 6: fileId / drawioClientId / drawioAck are NEW,
+        // all optional, on the body this heartbeat already sent every 10s
+        // (old clients / the existing test in test/editor-server.test.js send
+        // `{}` — that still resolves to "no tracked state", the same
+        // zero-cost 204 as before). A body that fails to parse degrades the
+        // same way: no staleness check, plain 204 — a malformed ping body
+        // must never be the thing that breaks the idle-keepalive contract.
+        //
+        // Fix round 1 (review F8): an explicit 8 KB readJson limit, not the
+        // 50 MB default — the same precedent /api/save set for its own body,
+        // for the same reason. This body is always three short scalars, and
+        // this is the ONE route that fires unconditionally every 10 seconds
+        // from every open tab; it has no business also being the most
+        // permissive one in the server.
+        let fileId, drawioClientId, drawioAck;
+        try {
+          const body = await readJson(req, 8 * 1024);
+          if (body) {
+            fileId = body.fileId;
+            drawioClientId = body.drawioClientId;
+            drawioAck = body.drawioAck;
+          }
+        } catch (e) {
+          fileId = undefined; drawioClientId = undefined; drawioAck = undefined;
+        }
+        // Ack FIRST, then re-check: a client that has just confirmed it
+        // applied version N must get a 204 on this same beat unless the file
+        // has moved on past N since.
+        touchDrawioClient(fileId, drawioClientId);
+        ackDrawioApplied(fileId, drawioClientId, drawioAck);
+        const staleToken = checkDrawioStale(fileId, drawioClientId);
+        if (staleToken) {
+          return send(res, 200, { stale: true, token: staleToken });
+        }
         res.writeHead(204);
         return res.end();
       }

package/lib/editor/toolbar-model.js

@@ -11,11 +11,14 @@
   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).
+// The 23-button roster, spec §4 table (`export▾` moved out of scope — no
+// browser-reachable export path) plus the v3.4.0 §3 `save` button. Seven
+// groups, in render order; group order here doubles as separator placement
+// for the caller (a separator sits between consecutive groups).
 const BUTTON_DEFS = [
+  // file
+  { id: 'save', group: 'file', label: '💾', icon: '💾', title: '儲存 (Ctrl+S)', toggle: false },
+
   // 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 },
@@ -59,11 +62,22 @@ const BUTTON_DEFS = [
 
 const BUTTONS = Object.freeze(BUTTON_DEFS.map((b) => Object.freeze(Object.assign({}, b))));
 
-const GROUPS = Object.freeze(['history', 'block', 'inline', 'indent', 'insert', 'view']);
+const GROUPS = Object.freeze(['file', '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']);
+// v3.4.0 §3: 'save' is here because unsaved changes have nothing to do with
+// where the caret is — a document can be dirty with no block focused at all.
+// NOTE (ruling P2): this entry does NOT currently change save's behaviour.
+// `state.save.disabled = !dirty` below runs AFTER the no-block loop that
+// reads this set, so it unconditionally overwrites whatever the no-block
+// loop decided for 'save' — today the two never disagree in a way that
+// shows through. This entry is kept anyway because it records the intent
+// ("save must not be gateable on hasBlock") independently of where the
+// `!dirty` line happens to sit; if that line is ever moved above the
+// no-block loop, this set becomes the only thing still enforcing it. Do not
+// delete it as "dead code" without re-checking that ordering.
+const NO_BLOCK_ALLOWED = new Set(['undo', 'redo', 'outline', 'preview', 'save']);
 
 // 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
@@ -103,6 +117,7 @@ function deriveState(ctx) {
   const inList = !!c.inList;
   const listOrdered = !!c.listOrdered;
   const mode = c.mode;
+  const dirty = !!c.dirty;
   const hasBlock = blockType !== null && blockType !== undefined;
 
   const state = {};
@@ -211,21 +226,43 @@ function deriveState(ctx) {
     }
   }
 
+  // v3.4.0 §3: the save button IS the save-state indicator — grey when the
+  // document matches disk, lit when it does not. The truth stays
+  // single-sourced: client.js's `documentIsDirty()` — since v3.4.0 batch3
+  // Task 7 that is `stack.isDirty() || burstHasUncommittedEdit() ||
+  // waveUnwrittenEdit` — arrives as ctx.dirty and is not recomputed here.
+  // This runs before the source-mode override below so that override can
+  // still give save its own exemption.
+  state.save.disabled = !dirty;
+
   // mode 'source' is the full-document raw-source escape hatch: everything
   // 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
+  // which in v3.2.1 is the edit <-> source toggle), since T11-2 'outline'
+  // (☰), and since v3.4.0 §3 'save'. 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.
+  // mode with no way to open that drawer at all. 'save' stays reachable
+  // because source mode can still hold unsaved changes (the user can type
+  // into the source textarea) — see the per-button comment below for the
+  // exact shape of the exemption. 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 three ids.
   if (mode === 'source') {
     for (const b of BUTTONS) {
-      state[b.id].disabled = b.id !== 'preview' && b.id !== 'outline';
+      if (b.id === 'preview' || b.id === 'outline') { state[b.id].disabled = false; continue; }
+      // v3.4.0 §3: save is a third exemption, for the same shape of reason
+      // outline already had one — source mode can still hold unsaved
+      // changes (the user can type into the source textarea), so forcing
+      // the only save button grey here would make a mode that holds
+      // unsaved work with no way out of it. The exemption is from the MODE
+      // forcing it grey, not from being grey — a clean document still shows
+      // it disabled in source mode (see the `state.save.disabled = !dirty`
+      // line above, which already ran and is left untouched here).
+      if (b.id === 'save') continue;
+      state[b.id].disabled = true;
     }
   }