From 4d8315da5c656d141a7a83118d405fc239181052 Mon Sep 17 00:00:00 2001 From: agent_coder Date: Fri, 3 Jul 2026 02:29:09 +0300 Subject: [PATCH] docs(#298 review): document the browser-safety invariant of the isNodeRuntime guard (F1) The whole fix's correctness rests on isNodeRuntime being false in the browser (so the interactive live-DOM comment branch still runs), and that is NOT covered by any test (client vitest runs under jsdom->node where isNodeRuntime is true). Document it: Vite substitutes only process.env, not the bare process object, so typeof process is undefined in the client bundle; do not add a process polyfill without revisiting this guard, or comment interactivity dies silently. Co-Authored-By: Claude Opus 4.8 (1M context) --- packages/editor-ext/src/lib/comment/comment.ts | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/packages/editor-ext/src/lib/comment/comment.ts b/packages/editor-ext/src/lib/comment/comment.ts index 9d6680d2..7d59cef5 100644 --- a/packages/editor-ext/src/lib/comment/comment.ts +++ b/packages/editor-ext/src/lib/comment/comment.ts @@ -178,6 +178,14 @@ export const Comment = Mark.create({ // interactive live-DOM branch below is browser-only. This stops server-side // HTML/Markdown export (happy-dom DOMSerializer) from appending a foreign // jsdom node into a happy-dom tree. + // Safe in the browser: Vite substitutes only `process.env` (a member + // expression), NOT the bare `process` object, so `typeof process` is + // "undefined" in the client bundle → isNodeRuntime is false → the interactive + // live-DOM branch below still runs and comment marks stay clickable in the + // editor. This browser-safety is load-bearing and NOT covered by a test + // (client vitest runs under jsdom→node, where isNodeRuntime is true). Do NOT + // add a `process` polyfill (e.g. vite-plugin-node-polyfills) without + // revisiting this guard, or comment interactivity dies silently. const isNodeRuntime = typeof process !== "undefined" && !!process.versions?.node;