@helping-ai-workflow/md2doc 3.6.0 → 3.7.0

package/lib/editor/server.js

@@ -38,6 +38,10 @@ const PATCHMAP_SRC = fs.readFileSync(path.join(__dirname, 'patchmap.js'), 'utf8'
 // 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');
+// Table cell-range selection's pure model — same "no dependency on any other
+// editor module" property as selection.js; it only has to land before
+// client.js reads window.md2docCellRange.
+const CELL_RANGE_SRC = fs.readFileSync(path.join(__dirname, 'cell-range.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
@@ -208,21 +212,64 @@ function assertBlockRangesFit(blocks, lines) {
   }
 }
 
-// F13: the never-opened grace deadline is deliberately its own constant,
-// not idleTimeoutMs reused. idleTimeoutMs governs the gap since the last
-// browser ping (client.js pings every 10s; the default 30,000ms tolerates
-// a short run of missed pings once a real tab is confirmed present).
-// Before the URL is opened there is no ping to measure against — the wait
-// is instead for a human to alt-tab to a browser, or, over SSH, copy the
-// printed URL across to a local machine and load it there, which routinely
-// takes longer than idleTimeoutMs allows. Reusing idleTimeoutMs for that
-// wait would close sessions on people still reading the terminal output.
-// Five minutes is chosen as a margin generous for that human handoff while
-// still finite; test/cli-edit.test.js drives it through a shortened
-// override — an unopened session still exits on its own, and a session
-// opened partway through the grace window keeps working afterward.
+// F13: the never-opened grace deadline is deliberately its own constant, not
+// connectionGraceMs (see that constant's own comment) reused. connectionGraceMs
+// governs the gap between one /api/alive connection dropping and a
+// replacement showing up once a real tab is confirmed to have existed at
+// all. Before the URL is opened there is no connection to have dropped in
+// the first place — the wait here is instead for a human to alt-tab to a
+// browser, or, over SSH, copy the printed URL across to a local machine and
+// load it there, which routinely takes longer than connectionGraceMs allows.
+// Reusing connectionGraceMs for that wait would close sessions on people
+// still reading the terminal output. Five minutes is chosen as a margin
+// generous for that human handoff while still finite; test/cli-edit.test.js
+// drives it through a shortened override — an unopened session still exits
+// on its own, and a session opened partway through the grace window keeps
+// working afterward.
 const DEFAULT_NEVER_OPENED_GRACE_MS = 5 * 60 * 1000;
 
+// v3.6.0: replaces idleTimeoutMs as the "is anyone still there" clock.
+// idleTimeoutMs measured the gap since the last /api/ping — a plain
+// setInterval(..., 10000) in client.js — and pings from a backgrounded
+// (merely unfocused, tab still open) browser tab are throttled by the
+// browser itself. MEASURED on this branch (see LIVENESS-REPORT.md): once
+// Chrome's real background-timer throttling is allowed to engage — puppeteer
+// disables it by default for automation stability, and the first measurement
+// pass on this branch silently measured THAT instead — a backgrounded tab's
+// 10s ping settled at roughly once per minute. 60s > the old 30,000ms
+// default, so a tab the user had only alt-tabbed away from looked exactly
+// like a closed one and the session was killed out from under a document
+// still open on screen. A connection is not a timer, so it is not subject to
+// that clamp: GET /api/alive holds its response open for as long as the tab
+// (or this same document's tab, after a reload) keeps it open, and dropping
+// to zero open connections is what this grace measures from.
+//
+// The grace itself exists for one trap: an F5 reload closes the old
+// connection and opens a new one, and the two are NOT the same event — there
+// is a real (if small) gap between them, during which the connection count is
+// genuinely zero. Without a grace, every reload would kill the session.
+// MEASURED (LIVENESS-REPORT.md, five consecutive page.reload() calls against
+// a real headless Chrome hitting the real /api/alive route): the old
+// connection's 'close' to the replacement connection's arrival ran
+// 55-73ms, averaging 64ms. This default (5s) is roughly 70x that measured
+// margin — headroom for a slower disk, a loaded machine, or a proxy in the
+// path — while still closing a genuinely abandoned session within a few
+// seconds rather than lingering. test/cli-edit.test.js and
+// test/editor-server.test.js drive it through a shortened override, the same
+// pattern DEFAULT_NEVER_OPENED_GRACE_MS above already uses.
+const DEFAULT_CONNECTION_GRACE_MS = 5000;
+
+// server.js sends one of these on every open /api/alive stream so an idle
+// stream is never silently dropped by an intermediary (a corporate proxy, a
+// misbehaving localhost tool) that closes connections it hasn't seen traffic
+// on in a while, and so a half-open socket (the far end vanished without a
+// TCP FIN, e.g. a laptop that lost power) is discovered on the next write
+// rather than held forever. A bare SSE comment line (no `data:` field) is
+// invisible to EventSource's onmessage — nothing to parse, nothing to react
+// to, exactly the "the connection's mere existence is the signal" contract
+// client.js documents at its own call site.
+const ALIVE_KEEPALIVE_MS = 15000;
+
 // T21 item 3: closing this server has to mean "stop serving now", not "stop
 // serving once every open socket happens to go away". `server.close()` on its
 // own does the latter: it stops accepting, then waits for the connections it
@@ -249,20 +296,43 @@ function shutdownServer(server, reason) {
 }
 
 async function createEditorServer({
-  files, idleTimeoutMs = 30000, neverOpenedGraceMs = DEFAULT_NEVER_OPENED_GRACE_MS,
+  files, neverOpenedGraceMs = DEFAULT_NEVER_OPENED_GRACE_MS,
+  connectionGraceMs = DEFAULT_CONNECTION_GRACE_MS,
   clientJs = '', listenPort = 0,
 }) {
   const absFiles = files.map((f) => path.resolve(f));
-  let idleTimer = null;
   let neverOpenedTimer = null;
   let started = false;
+  // v3.6.0: the liveness mechanism. `aliveConnections` holds every currently
+  // open GET /api/alive response, GLOBALLY across every tab and every file
+  // this one server serves — `md2doc --edit a.md b.md` is one session, and
+  // closing the tab for a.md must not tear down b.md's still-open tab, so
+  // the decision that matters is "is the set empty", never "which file was
+  // this connection for". `started` now means "at least one such connection
+  // has ever been registered" — see registerAliveConnection() and
+  // DEFAULT_NEVER_OPENED_GRACE_MS's own comment on why that boundary moved
+  // off GET /edit/:id.
+  const aliveConnections = new Set();
+  let shutdownGraceTimer = null;
+  // Guards against the (already-benign, but worth making impossible on
+  // purpose) case of two shutdown triggers landing close together — e.g. a
+  // connection's 'close' event arriving from closeAllConnections() itself
+  // while the process is already on its way out through srv.close().
+  let closing = 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).
+  // rather than inventing a SEPARATE push transport for it. v3.6.0 DID add
+  // one push transport to this stack — GET /api/alive, an SSE stream, but
+  // only for session liveness (see registerAliveConnection() below and
+  // DEFAULT_CONNECTION_GRACE_MS's comment for why polling could not do that
+  // job). The reasoning that kept drawio staleness on polling is unchanged
+  // and still applies to drawio specifically: a filesystem watch would need
+  // one watcher per referenced file with no bound on how many a document can
+  // reference, and the existing 10s heartbeat already has a client on the
+  // other end of it for a different reason, so riding it costs nothing extra
+  // beyond the stat calls in checkDrawioStale() below.
   //
   // TWO maps, and the split is the whole point of fix round 1:
   //
@@ -486,13 +556,84 @@ async function createEditorServer({
     c.pending = null;
   }
 
-  function bumpIdle(server) {
-    if (!started) return;
-    if (idleTimer) clearTimeout(idleTimer);
-    idleTimer = setTimeout(() => {
-      shutdownServer(server, 'idle');
-    }, idleTimeoutMs);
-    if (idleTimer.unref) idleTimer.unref();
+  // Fires shutdownServer() at most once, regardless of which of this file's
+  // several deadlines got there first (see `closing`'s own comment above).
+  function shutdownOnce(server, reason) {
+    if (closing) return;
+    closing = true;
+    cancelShutdownGrace();
+    shutdownServer(server, reason);
+  }
+
+  function cancelShutdownGrace() {
+    if (shutdownGraceTimer) { clearTimeout(shutdownGraceTimer); shutdownGraceTimer = null; }
+  }
+
+  // Armed the moment `aliveConnections` drops to zero, cancelled the moment
+  // a new one arrives (registerAliveConnection() below calls
+  // cancelShutdownGrace() unconditionally on every new connection, whether or
+  // not a grace timer happens to be running). This is the trap named in the
+  // design doc: an F5 reload closes the old /api/alive stream and opens a
+  // fresh one, and those are two SEPARATE events with a real gap between
+  // them — without this grace, every reload would read as "the tab closed"
+  // and kill the session out from under the user mid-refresh. See
+  // DEFAULT_CONNECTION_GRACE_MS's own comment for the measurement that sized
+  // the default.
+  function armShutdownGrace(server) {
+    if (shutdownGraceTimer || closing) return;
+    shutdownGraceTimer = setTimeout(() => {
+      shutdownGraceTimer = null;
+      // Re-check rather than trust the callback firing at all means "still
+      // zero": a connection could have registered and then, in a pathological
+      // fast sequence, this timer's callback could still be queued from
+      // before that registration cancelled it. Belt-and-braces; cheap.
+      if (aliveConnections.size > 0) return;
+      shutdownOnce(server, 'idle');
+    }, connectionGraceMs);
+    if (shutdownGraceTimer.unref) shutdownGraceTimer.unref();
+  }
+
+  // Registers one open GET /api/alive response as "this tab is here". Every
+  // call cancels any pending shutdown grace FIRST — a fresh connection is by
+  // definition proof the session should stay up, whether it is genuinely the
+  // first tab, a second tab, or a reload's replacement for one that just
+  // dropped. `started` flips here rather than on GET /edit/:id — see
+  // DEFAULT_NEVER_OPENED_GRACE_MS's comment on why the "was this session ever
+  // really opened" boundary is a live connection now, not the HTML request
+  // that precedes it by however long the browser takes to run client.js.
+  function registerAliveConnection(server, res, fileId, clientId) {
+    cancelShutdownGrace();
+    started = true;
+    // Stashed on the response object itself rather than threaded through a
+    // second Map: nothing in the closing decision reads these back (see this
+    // function's own comment), so a real diagnostic (a future `/api/debug`,
+    // a log line) is the only consumer, and it already has `res` in hand.
+    res._md2docAliveFileId = fileId;
+    res._md2docAliveClientId = clientId;
+    res.writeHead(200, {
+      'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'no-store',
+      connection: 'keep-alive',
+    });
+    // Flushes the headers immediately rather than waiting for the first
+    // keepalive tick — the client's EventSource does not consider the
+    // connection open (readyState transitions to OPEN) until bytes arrive.
+    res.write(': connected\n\n');
+    aliveConnections.add(res);
+    const keepalive = setInterval(() => {
+      // A write to an already-gone socket throws; the 'close' listener below
+      // is what actually tears this connection's bookkeeping down; this
+      // catch only stops that throw from reaching an uncaught spot on a beat
+      // that lost a race against the socket's own teardown.
+      try { res.write(': keepalive\n\n'); } catch (e) { /* 'close' handles cleanup */ }
+    }, ALIVE_KEEPALIVE_MS);
+    if (keepalive.unref) keepalive.unref();
+    res.on('close', () => {
+      clearInterval(keepalive);
+      if (!aliveConnections.has(res)) return; // already handled (e.g. shutdown path)
+      aliveConnections.delete(res);
+      if (aliveConnections.size === 0) armShutdownGrace(server);
+    });
   }
 
   const server = http.createServer(async (req, res) => {
@@ -594,6 +735,7 @@ async function createEditorServer({
           `<script>${CONVERT_MD_SRC}</script>\n` +
           `<script>${PATCHMAP_SRC}</script>\n` +
           `<script>${SELECTION_SRC}</script>\n` +
+          `<script>${CELL_RANGE_SRC}</script>\n` +
           `<script>${TOOLBAR_MODEL_SRC}</script>\n` +
           `<script>${DOCSOURCE_SRC}</script>\n` +
           `<script>${ASSET_SRC}</script>\n` +
@@ -615,8 +757,10 @@ async function createEditorServer({
         const out = bodyAt !== -1
           ? html.slice(0, bodyAt) + inject + html.slice(bodyAt)
           : html + inject;
-        started = true;
-        bumpIdle(server);
+        // `started` no longer flips here — see registerAliveConnection()'s
+        // comment. This request only proves the HTML was served, not that a
+        // live tab is behind it (this same GET is also what a plain HTTP
+        // client, e.g. curl or this file's own test helpers, sends).
         // no-store: the page embeds a snapshot of the client runtime AND the
         // file's lines/mtime — a cached copy is stale code + a guaranteed
         // mtime conflict after any external edit.
@@ -635,7 +779,6 @@ async function createEditorServer({
         // 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 });
       }
 
@@ -656,7 +799,6 @@ async function createEditorServer({
         const tmp = file + '.md2doc-tmp';
         fs.writeFileSync(tmp, content, 'utf8');
         fs.renameSync(tmp, file);
-        bumpIdle(server);
         return send(res, 200, { mtimeMs: fs.statSync(file).mtimeMs });
       }
 
@@ -791,19 +933,37 @@ async function createEditorServer({
           }
           throw e;
         }
-        bumpIdle(server);
         return send(res, 200, { name, path: assetLib.relPath(name) });
       }
 
+      // v3.6.0: the liveness stream. A GET (EventSource cannot send any other
+      // method), held open for as long as the tab exists. fileId/clientId are
+      // read here purely so a future diagnostic has them to hand — see
+      // registerAliveConnection()'s own comment for why nothing about
+      // whether the session stays alive depends on either one being
+      // well-formed; the response object's own identity is the only thing
+      // the closing decision is keyed on, deliberately, the same way
+      // drawioClients above is keyed on a validated pair while THIS map does
+      // not need one at all.
+      if (req.method === 'GET' && url.pathname === '/api/alive') {
+        const aliveFileId = Number(url.searchParams.get('fileId'));
+        const aliveClientId = url.searchParams.get('clientId');
+        registerAliveConnection(server, res, aliveFileId, aliveClientId);
+        return; // response intentionally stays open — nothing more to send
+      }
+
       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.
+        // must never be the thing that breaks the drawio-staleness contract.
+        // v3.6.0: this route no longer has any bearing on whether the
+        // session stays alive — see GET /api/alive above for that. It is
+        // kept exactly as it was for the ONE job it still does: the drawio
+        // staleness heartbeat below.
         //
         // 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,
@@ -864,22 +1024,25 @@ async function createEditorServer({
 
   // F13: counts from listen (this point), not from process start — listen
   // is the moment a client could first reach the server, and that is the
-  // deadline this timer is measuring against. Unref'd like idleTimer, and
-  // for the same reason: the listening socket is what should keep the
-  // process alive, not this timer. A timer that held a ref would keep the
-  // process up on its own even if the socket already went away, which is
-  // backwards for a clock whose only job is to give up and exit.
+  // deadline this timer is measuring against. Unref'd like shutdownGraceTimer,
+  // and for the same reason: the listening socket (or, once one exists, an
+  // open /api/alive connection) is what should keep the process alive, not
+  // this timer. A timer that held a ref would keep the process up on its own
+  // even if the socket already went away, which is backwards for a clock
+  // whose only job is to give up and exit.
   neverOpenedTimer = setTimeout(() => {
     // The guard against closing a session that has already been opened —
-    // this timer is armed once, at listen time, and left to run; it is
-    // not cancelled by the GET /edit/:id handler. Whether the URL was
-    // opened by the time the deadline arrives is decided here, by reading
-    // `started` fresh at fire time. Proven load-bearing by mutation: with
-    // this line removed, an actively-pinged session still gets closed the
-    // moment this deadline passes (see test/cli-edit.test.js's "must
-    // survive the never-opened grace deadline" case).
+    // this timer is armed once, at listen time, and left to run; it is not
+    // cancelled by GET /api/alive registering a connection. Whether a live
+    // connection was ever established by the time the deadline arrives is
+    // decided here, by reading `started` fresh at fire time (registerAliveConnection()
+    // is the only place that sets it — see its own comment). Proven
+    // load-bearing by mutation: with this line removed, an actively-connected
+    // session still gets closed the moment this deadline passes (see
+    // test/cli-edit.test.js's "must survive the never-opened grace deadline"
+    // case).
     if (started) return;
-    shutdownServer(server, 'never-opened');
+    shutdownOnce(server, 'never-opened');
   }, neverOpenedGraceMs);
   if (neverOpenedTimer.unref) neverOpenedTimer.unref();
 
@@ -891,9 +1054,8 @@ async function createEditorServer({
       return i === -1 ? null : `http://127.0.0.1:${port}/edit/${i}`;
     },
     close() {
-      if (idleTimer) clearTimeout(idleTimer);
       if (neverOpenedTimer) clearTimeout(neverOpenedTimer);
-      shutdownServer(server, null);
+      shutdownOnce(server, null);
     },
   };
 }

package/lib/md2doc.js

@@ -1423,6 +1423,14 @@ ${itemsHtml}
   /* min-width: 0 so an unbreakable token inside an item cannot widen the row
      past its siblings — that would break the equal-width guarantee above. */
   .ed-block[data-block-type="li"] > .ed-li-text { flex: 1 1 auto; min-width: 0; }
+  /* The MD 原始碼 raw editor replaces the item's children with one .ed-editing
+     wrap, which is then this flex row's only child. Without a grow it shrank
+     to the textarea's intrinsic size and .ed-raw's width: 100% resolved
+     against that: 189px at every viewport width (measured), where every other
+     block's raw editor spans the column. The marker, and with it the indent,
+     is gone while the textarea is open, so it spans the full column at every
+     depth; the source line's own leading spaces show the nesting. */
+  .ed-block[data-block-type="li"] > .ed-editing { flex: 1 1 auto; min-width: 0; }
   /* column-gap already provides the marker/checkbox separation. */
   .ed-block[data-block-type="li"] > .ed-li-check { flex: 0 0 auto; margin-right: 0; }
   .ed-block[data-list-type="ul"] > .ed-li-marker::before { content: "\\2022"; }${edOlCounterCss}
@@ -3267,6 +3275,11 @@ ${usesDrawio ? `  /* v3.4.0 §4: a document with no drawio reference must not pa
      indicator' is the singleton line shown while dragging a row.
      '.ed-te-row-dragging' dims the row actually being dragged. */
   .ed-te-hl { background: rgba(59, 130, 246, 0.15) !important; }
+  /* Table cell-range selection: the painted rectangle, and the table that
+     holds one (its caret and native selection are hidden while it stands). */
+  .ed-cell-range { background: rgba(59, 130, 246, 0.18) !important; }
+  .ed-cell-range-active { caret-color: transparent; }
+  .ed-cell-range-active ::selection { background: transparent; }
   .ed-te-menu {
     position: fixed; z-index: 12;
     display: flex; align-items: center; gap: 4px;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helping-ai-workflow/md2doc",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "Markdown → HTML / PDF renderer with WaveDrom, Mermaid, Graphviz, and draw.io support",
   "keywords": [
     "markdown",
@@ -45,7 +45,7 @@
   },
   "scripts": {
     "preinstall": "node scripts/preinstall.js",
-    "test": "node test/md2doc.test.js && node test/blockmap.test.js && node test/drawio.test.js && node test/images.test.js && node test/scroll-anchor.test.js && node test/lightbox.test.js && node test/lightbox-anno.test.js && node test/lightbox-anno-style.test.js && node test/reader-panels.test.js && node test/cli.test.js && node test/code-operator.test.js && node test/convert-md.test.js && node test/render-api.test.js && node test/lineops.test.js && node test/indent-clamp.test.js && node test/selection.test.js && node test/editmode-render.test.js && node test/editmode-wavedrom-reinit.test.js && node test/editor-server.test.js && node test/cli-edit.test.js && node test/open-viewer.test.js && node test/editor-client.test.js && node test/editor-client-runtime.test.js && node test/roundtrip.test.js && node test/byte-stability.test.js && node test/editor-server-throw.test.js && node test/editor-reader-rebind.test.js && node test/inline-md.test.js && node test/table-md.test.js && node test/table-anchor-recovery.test.js && node test/gate-compat.test.js && node test/history.test.js && node test/list-md.test.js && node test/table-width.test.js && node test/toolbar-model.test.js && node test/docsource.test.js && node test/asset.test.js && node test/paste-md.test.js && node test/patchmap.test.js && node test/wave-codec.test.js && node test/wave-draw.test.js && node test/wave-geometry.test.js && node test/wave-store.test.js && node test/wave-rail-clearance.test.js && node test/editor-journey.test.js && node test/detach-census.test.js"
+    "test": "node test/md2doc.test.js && node test/blockmap.test.js && node test/drawio.test.js && node test/images.test.js && node test/scroll-anchor.test.js && node test/lightbox.test.js && node test/lightbox-anno.test.js && node test/lightbox-anno-style.test.js && node test/reader-panels.test.js && node test/cli.test.js && node test/code-operator.test.js && node test/convert-md.test.js && node test/render-api.test.js && node test/lineops.test.js && node test/indent-clamp.test.js && node test/selection.test.js && node test/cell-range.test.js && node test/editmode-render.test.js && node test/editmode-wavedrom-reinit.test.js && node test/editor-server.test.js && node test/cli-edit.test.js && node test/open-viewer.test.js && node test/editor-client.test.js && node test/editor-client-runtime.test.js && node test/roundtrip.test.js && node test/byte-stability.test.js && node test/editor-server-throw.test.js && node test/editor-reader-rebind.test.js && node test/inline-md.test.js && node test/table-md.test.js && node test/table-anchor-recovery.test.js && node test/gate-compat.test.js && node test/history.test.js && node test/list-md.test.js && node test/table-width.test.js && node test/toolbar-model.test.js && node test/docsource.test.js && node test/asset.test.js && node test/paste-md.test.js && node test/patchmap.test.js && node test/wave-codec.test.js && node test/wave-draw.test.js && node test/wave-geometry.test.js && node test/wave-store.test.js && node test/wave-rail-clearance.test.js && node test/editor-journey.test.js && node test/detach-census.test.js && node test/editor-arrow-nav.test.js && node test/editor-cell-range.test.js"
   },
   "repository": {
     "type": "git",