@helping-ai-workflow/md2doc 3.6.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();
 

package/lib/editor/server.js

@@ -208,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
@@ -249,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:
   //
@@ -486,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) => {
@@ -615,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.
@@ -635,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 });
       }
 
@@ -656,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 });
       }
 
@@ -791,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,
@@ -864,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();
 
@@ -891,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);
     },
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helping-ai-workflow/md2doc",
-  "version": "3.6.0",
+  "version": "3.6.1",
   "description": "Markdown → HTML / PDF renderer with WaveDrom, Mermaid, Graphviz, and draw.io support",
   "keywords": [
     "markdown",