@helping-ai-workflow/md2doc 3.5.0 → 3.6.1

package/lib/editor/cli.js

@@ -16,7 +16,7 @@ const AUTO_CLOSE_MESSAGES = {
 };
 
 async function startEditSession({
-  files, port = null, open = true, quiet = false, idleTimeoutMs, neverOpenedGraceMs,
+  files, port = null, open = true, quiet = false, connectionGraceMs, neverOpenedGraceMs,
 }) {
   const srv = await createEditorServer({
     files,
@@ -25,7 +25,7 @@ async function startEditSession({
     // Included when the caller supplies a value; otherwise omitted so
     // createEditorServer's own default applies, rather than a duplicated
     // default here that could drift out of sync with it.
-    ...(idleTimeoutMs === undefined ? {} : { idleTimeoutMs }),
+    ...(connectionGraceMs === undefined ? {} : { connectionGraceMs }),
     ...(neverOpenedGraceMs === undefined ? {} : { neverOpenedGraceMs }),
   });
   const urls = files.map((f) => srv.urlFor(f));

package/lib/editor/client.js

@@ -17310,6 +17310,44 @@
     }).catch(() => {});
   }, 10000);
 
+  // v3.6.0: session liveness no longer rides this 10s ping. Browsers throttle
+  // a backgrounded (merely unfocused, tab still open) tab's timers — MEASURED
+  // on this branch, Chrome's real background-timer throttling (not
+  // puppeteer's automation defaults, which disable it) clamps this very
+  // setInterval to roughly once per minute once the tab has been hidden a
+  // while, well past the server's old 30s idle deadline. A connection is not
+  // a timer, so it does not get throttled the same way: this stream stays
+  // open for exactly as long as the tab does, and server.js (see GET
+  // /api/alive's own comment) treats the stream closing — after a short
+  // grace, to absorb an F5 reload's own close-then-reopen — as the tab
+  // actually closing. No onmessage/onerror wiring is needed: server.js never
+  // sends this tab anything meaningful to react to, the connection's mere
+  // existence is the whole signal, and EventSource's own built-in reconnect
+  // already covers a transient network blip without any code here.
+  //
+  // Opened IMMEDIATELY, deliberately — liveness protection starts at the
+  // first possible moment, not after an arbitrary delay. An earlier version
+  // of this delayed the open by 1500ms to dodge a test-harness interaction
+  // (Puppeteer's `waitUntil: 'networkidle0'` never resolves once a
+  // permanently-open connection exists — this whole document is ONE inlined
+  // HTML response, so a fresh page normally goes network-idle well under a
+  // second). That delay was the wrong fix: MEASURED on the very machine that
+  // needed it, ordinary page loads went idle at 1027-1290ms, leaving only a
+  // 210-473ms margin against the delay — one slow tick during page load and
+  // the wait hangs for its full 30s timeout anyway, in up to 286 call sites
+  // across the suite. The product should not contort its own liveness
+  // window around a test harness's definition of idle; the suite's affected
+  // `page.goto()`/`page.reload()` calls now wait on `networkidle2` instead
+  // (tolerates the one permanent connection this page is SUPPOSED to hold —
+  // see each touched test file for specifics), which is not a timing bet at
+  // all.
+  if (typeof EventSource === 'function') {
+    try {
+      new EventSource('/api/alive?fileId=' + encodeURIComponent(ED.fileId) +
+        '&clientId=' + encodeURIComponent(ED.drawioClientId));
+    } catch (e) { /* degrade to no liveness signal rather than throw */ }
+  }
+
   armEditables(contentEl);
   wireBlockSelection();
 
@@ -17542,7 +17580,8 @@
     // An older cached page that predates the injection must degrade to "the
     // button does nothing visible", never to a throw out of a click handler.
     if (!ui || !mods || !mods['wave-store.js'] || !mods['wave-codec.js'] ||
-        !mods['wave-geometry.js']) return;
+        !mods['wave-geometry.js'] || !mods['wave-draw.js'] ||
+        !mods['wave-panels.js']) return;
     if (waveEditor !== null) return;
     hideWaveEditBtn();
 
@@ -17603,8 +17642,27 @@
         document: document,
         host: document.body,
         source: body.text,
+        // v3.6.0 Task 15: which block in this document the editor is over,
+        // for the 匯出 filename (`exportName()` in wave-ui.js). The editor
+        // cannot derive it — it is handed one block's TEXT and nothing about
+        // where that text came from — and two diagrams in one document
+        // exporting under the same filename is a silent overwrite in the
+        // user's downloads folder.
+        blockIndex: id,
+        // …and the document's own name for the other half of that filename.
+        // `baseTitle`, NOT `document.title`: this file owns the page title
+        // while a session is open and writes the dirty marker into it
+        // (`(documentIsDirty() ? '● ' : '') + baseTitle`, above). Handing over
+        // the decorated title would land a user who has actually edited with
+        // `●-doc-wave-1.svg`, and a user who has not with the clean name —
+        // i.e. it would look right in exactly the case nobody exports in.
+        // `baseTitle` is the title as it was before this file touched it,
+        // which is md2doc's `path.basename(src, '.md')`.
+        fileLabel: baseTitle,
         codec: mods['wave-codec.js'],
         geometry: mods['wave-geometry.js'],
+        draw: mods['wave-draw.js'],
+        panels: mods['wave-panels.js'],
         createStore: mods['wave-store.js'].createStore,
         // The store's own answer to「哪一條 lane 是哪一條」across one operation,
         // handed over rather than re-derived: the editor's cell cursor and its
@@ -17760,10 +17818,29 @@
 
   /** One refusal, recorded and raised. The only producer of `waveUnwrittenEdit`. */
   function waveRefuseGesture(seam, reason) {
-    // A refusal is not papered over and not rolled back. wave-ui has already
-    // said so on the status line, which is where the user's eyes are, but a
-    // status line is not a decision — this raises it as a banner naming the
-    // lines it could not write and waits for the user to acknowledge it.
+    // A refusal is not papered over and not rolled back. This raises it as a
+    // banner naming the lines it could not write, and waits for the user to
+    // acknowledge it.
+    //
+    // v3.6.0 Task 16 fix round 2 (N1) withdraws the reason that used to stand
+    // here — "wave-ui has already said so on the status line, which is where
+    // the user's eyes are, but a status line is not a decision". wave-ui does
+    // write the reason there (`afterStoreMoved`'s
+    // `這個改動沒辦法只改幾個位元組寫回去：…`), but that line is ONE
+    // `role="status"` string and the next thing the same gesture says
+    // replaces it. MEASURED on the journey fixture: the fourth Alt+↑ of the
+    // Task 16 scenario refuses — "the value at [\"signal\"] is or contains an
+    // object, so replacing it would re-serialise part of the document's
+    // structure…" — and `moveSelectedLane`'s landing line
+    // (`搬動的 lane 落在群組「bus」裡`) is written straight after it, so the
+    // sentence the user is left looking at reads like success.
+    //
+    // That is a FAMILY, not one caller: `addLaneFromToolbar` and 複製 have
+    // written over the same refusal since before Task 16, and the rail's drag
+    // drop announces nothing at all. Re-ordering those says is behaviour, and
+    // it is parked as a next-version follow-up rather than done here. So the
+    // banner below is not a nicety layered on a status line that already said
+    // it — it is the only part of the refusal that cannot be clobbered.
     seam.unwritten = true;
     waveUnwrittenEdit = true;
     setDirty();

package/lib/editor/server.js

@@ -56,7 +56,7 @@ 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.
+// v3.4.0 batch3 Task 6: the wavedrom GUI's 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
@@ -67,11 +67,28 @@ const PASTE_MD_SRC = fs.readFileSync(path.join(__dirname, 'paste-md.js'), 'utf8'
 // the browser gets them through the small CommonJS shim below instead —
 // the module text itself is inlined byte for byte.
 //
+// v3.6.0 Task 1: wave-draw.js joins them, plain CommonJS too — a pure
+// extraction out of wave-ui.js, not test-guarded like the other three, but
+// needing the identical shim for a different reason: wave-ui.js itself is
+// injected as a bare <script> with no `require()` of its own (see its own
+// header comment), so it cannot resolve `require('./wave-draw.js')` in the
+// browser any more than the page around it could. `createWaveEditor()` takes
+// it in as `opts.draw` instead, the same way it already takes `opts.codec`
+// and `opts.geometry`.
+//
+// v3.6.0 Task 2: wave-panels.js joins them for the identical reason —
+// another pure extraction out of wave-ui.js (the toolbar, the right-hand
+// panels and the lane rail this time), needing the same shim because
+// wave-ui.js still cannot `require()` anything in the browser. Taken in as
+// `opts.panels`.
+//
 // 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.
+// defines `window.md2docWaveUi` and takes the other five 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_DRAW_SRC = fs.readFileSync(path.join(__dirname, 'wave-draw.js'), 'utf8');
+const WAVE_PANELS_SRC = fs.readFileSync(path.join(__dirname, 'wave-panels.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.
@@ -191,21 +208,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
@@ -232,20 +292,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:
   //
@@ -469,13 +552,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) => {
@@ -585,6 +739,8 @@ async function createEditorServer({
           waveModuleTag('wave-codec.js', WAVE_CODEC_SRC) +
           waveModuleTag('wave-geometry.js', WAVE_GEOMETRY_SRC) +
           waveModuleTag('wave-store.js', WAVE_STORE_SRC) +
+          waveModuleTag('wave-draw.js', WAVE_DRAW_SRC) +
+          waveModuleTag('wave-panels.js', WAVE_PANELS_SRC) +
           `<script>${WAVE_UI_SRC}</script>\n` +
           `<script>${clientJs}</script>\n`;
         // Splice at the LAST "</body>" — the document's real closing tag.
@@ -596,8 +752,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.
@@ -616,7 +774,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 });
       }
 
@@ -637,7 +794,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 });
       }
 
@@ -772,19 +928,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,
@@ -845,22 +1019,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();
 
@@ -872,9 +1049,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);
     },
   };
 }