@dimina-kit/devtools 0.4.0-dev.20260706154125 → 0.4.0-dev.20260707110006

package/dist/main/app/app.js

@@ -356,7 +356,7 @@ export async function createDevtoolsRuntime(config = {}) {
     const context = createContext(config, mainWindow, rendererDir);
     // Anchor the main window's renderer as the first Connection. Resources
     // scoped to the main webContents (acquired by later wiring) tear down with
-    // it; see packages/electron-deck/docs/foundation.md §4.
+    // it; see packages/electron-deck/docs/foundation.md (teardown paths).
     context.connections.acquire(mainWindow.webContents);
     context.registry.add(registerAppIpc(context));
     // Sandboxed project file-system IPC (the renderer-side project:fs:* surface).

package/dist/main/index.bundle.js

@@ -827,7 +827,7 @@ function registerProjectFsIpc(ctx) {
 // src/main/app/app.ts
 import { app as app15, BrowserWindow as BrowserWindow8, nativeImage, session as session4 } from "electron";
 import fs12 from "fs";
-import path23 from "path";
+import path24 from "path";
 
 // src/main/utils/paths.ts
 import fs3 from "fs";
@@ -3043,8 +3043,8 @@ function createHostToolbarView(ctx, reconciler, deps) {
     hide() {
       hideHostToolbar();
     },
-    setPreloadPath(path24) {
-      hostToolbarPreloadOverride = path24;
+    setPreloadPath(path25) {
+      hostToolbarPreloadOverride = path25;
     },
     setHeightMode(mode) {
       if (mode !== "auto" && !(Number.isFinite(mode.fixed) && mode.fixed >= 0)) {
@@ -5298,7 +5298,7 @@ var ServiceHostPool = class {
   /**
    * Hand a ready window matching `spec` to the caller. If none is ready, fall
    * back to synchronously constructing a fresh window — never blocking on warm
-   * (doc §3.1 "绝不阻塞 acquire"). Fallback windows carry `entryId === null` and
+   * (see prewarm-webview.md's invariants section). Fallback windows carry `entryId === null` and
    * are destroyed (not pooled) on release.
    *
    * A spec change (different `preloadPath`) tears down all *pooled* entries and
@@ -5374,7 +5374,7 @@ var ServiceHostPool = class {
   }
   /**
    * Re-target the pool. `target` is clamped to `[0, maxPoolSize]`. Pooled
-   * entries beyond the target are disposed OLDEST-FIRST (doc §3.3/§3.6); in-use
+   * entries beyond the target are disposed OLDEST-FIRST (see prewarm-webview.md); in-use
    * entries are untouched. Does not warm new entries up (use `init` / refill).
    */
   resize(target) {
@@ -5503,7 +5503,7 @@ var ServiceHostPool = class {
   }
   /**
    * Reset a released window back to a clean, blank state. Order matters
-   * (doc §3.5.3 / §3.4「等待时序」): navigate to blank FIRST so the old document
+   * (see prewarm-webview.md's state-machine and reset-ordering sections): navigate to blank FIRST so the old document
    * stops running and in-flight requests are aborted, THEN clear storage — so a
    * still-live old page cannot re-populate storage after the clear.
    */
@@ -10227,13 +10227,13 @@ function createRenderInspector(options = {}) {
 import { toDisposable as toDisposable6 } from "@dimina-kit/electron-deck/main";
 
 // src/main/services/simulator-temp-files/store.ts
-function registerTempFile(store, path24, mime, bytes) {
+function registerTempFile(store, path25, mime, bytes) {
   const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(new Uint8Array(bytes));
-  store.delete(path24);
-  store.set(path24, { bytes: buf, mime });
+  store.delete(path25);
+  store.set(path25, { bytes: buf, mime });
 }
-function revokeTempFile(store, path24) {
-  store.delete(path24);
+function revokeTempFile(store, path25) {
+  store.delete(path25);
 }
 function revokeAllTempFiles(store) {
   store.clear();
@@ -10661,10 +10661,10 @@ function setupSimulatorTempFiles(simSession) {
   const store = /* @__PURE__ */ new Map();
   const pendingWaiters = /* @__PURE__ */ new Map();
   let disposed = false;
-  function drainWaiters(path24) {
-    const list = pendingWaiters.get(path24);
+  function drainWaiters(path25) {
+    const list = pendingWaiters.get(path25);
     if (!list) return;
-    pendingWaiters.delete(path24);
+    pendingWaiters.delete(path25);
     for (const fn of list) fn();
   }
   function drainAllWaiters() {
@@ -10677,15 +10677,15 @@ function setupSimulatorTempFiles(simSession) {
   const registry = new IpcRegistry(simulatorOnlyPolicy);
   registry.on("simulator:temp-file:write", (_event, payload) => {
     if (disposed) return;
-    const { path: path24, mime, bytes } = payload;
-    registerTempFile(store, path24, mime, bytes);
+    const { path: path25, mime, bytes } = payload;
+    registerTempFile(store, path25, mime, bytes);
     enforceStoreCap(store);
-    drainWaiters(path24);
+    drainWaiters(path25);
   });
   registry.on("simulator:temp-file:revoke", (_event, payload) => {
     if (disposed) return;
-    const { path: path24 } = payload;
-    revokeTempFile(store, path24);
+    const { path: path25 } = payload;
+    revokeTempFile(store, path25);
   });
   registry.on("simulator:temp-file:revoke-all", () => {
     if (disposed) return;
@@ -10829,9 +10829,97 @@ function setupSimulatorSessionPolicy() {
 
 // src/main/services/workbench-coi-server.ts
 import http2 from "node:http";
-import nodeFs2 from "node:fs";
+import nodeFs3 from "node:fs";
 import fs11 from "node:fs/promises";
+import path23 from "node:path";
+
+// src/main/services/fs-watch-sse.ts
+import nodeFs2 from "node:fs";
 import path22 from "node:path";
+
+// src/main/services/http-json.ts
+function jsonRes(res, code, obj) {
+  const body = Buffer.from(JSON.stringify(obj));
+  res.writeHead(code, { "Content-Type": "application/json; charset=utf-8", "Content-Length": body.length });
+  res.end(body);
+}
+
+// src/main/services/fs-watch-sse.ts
+var WATCH_DEBOUNCE_MS = 80;
+function shouldReportWatchPath(rel) {
+  if (rel === "" || rel.startsWith("..") || path22.isAbsolute(rel)) return false;
+  return !rel.split("/").some((segment) => SKIP_DIRS.has(segment));
+}
+function handleFsWatchRequest(req, res, getProjectRoot) {
+  const watchedRoot = getProjectRoot();
+  if (!watchedRoot) {
+    jsonRes(res, 409, { error: "No active project", code: "ENOACTIVE" });
+    return;
+  }
+  let watcher;
+  try {
+    watcher = nodeFs2.watch(watchedRoot, { recursive: true }, onChange);
+  } catch (e) {
+    jsonRes(res, 500, { error: String(e) });
+    return;
+  }
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream; charset=utf-8",
+    "Cache-Control": "no-store",
+    Connection: "keep-alive"
+  });
+  let pending = /* @__PURE__ */ new Set();
+  let debounceTimer = null;
+  let liveCheck = null;
+  let closed = false;
+  function cleanup() {
+    if (closed) return;
+    closed = true;
+    if (debounceTimer) clearTimeout(debounceTimer);
+    if (liveCheck) clearInterval(liveCheck);
+    watcher.close();
+  }
+  function flush() {
+    if (closed || pending.size === 0) return;
+    const paths = [...pending];
+    pending = /* @__PURE__ */ new Set();
+    res.write(`data: ${JSON.stringify({ paths })}
+
+`);
+  }
+  function onChange(_event, filename) {
+    const rel = filename ? filename.toString().split(path22.sep).join("/") : ".";
+    if (rel !== "." && !shouldReportWatchPath(rel)) return;
+    pending.add(rel);
+    if (!debounceTimer) {
+      debounceTimer = setTimeout(() => {
+        debounceTimer = null;
+        flush();
+      }, WATCH_DEBOUNCE_MS);
+    }
+  }
+  watcher.on("error", () => {
+    if (closed) return;
+    res.write(`data: ${JSON.stringify({ watcherDead: true })}
+
+`);
+    cleanup();
+    res.end();
+  });
+  liveCheck = setInterval(() => {
+    if (closed) return;
+    if (getProjectRoot() !== watchedRoot) {
+      res.write(`data: ${JSON.stringify({ watcherDead: true })}
+
+`);
+      cleanup();
+      res.end();
+    }
+  }, WATCH_DEBOUNCE_MS);
+  req.on("close", cleanup);
+}
+
+// src/main/services/workbench-coi-server.ts
 var MAX_FS_WRITE_BYTES = 32 * 1024 * 1024;
 var MIME = {
   ".html": "text/html; charset=utf-8",
@@ -10855,8 +10943,8 @@ function setIsolationHeaders(res) {
 }
 function containedStaticPath(root, pathname) {
   const rel = pathname.replace(/^\/+/, "") || "index.html";
-  const resolved = path22.resolve(root, rel);
-  if (resolved !== root && !resolved.startsWith(root + path22.sep)) return null;
+  const resolved = path23.resolve(root, rel);
+  if (resolved !== root && !resolved.startsWith(root + path23.sep)) return null;
   return resolved;
 }
 function serveStaticFile(res, root, pathname) {
@@ -10867,23 +10955,23 @@ function serveStaticFile(res, root, pathname) {
     return;
   }
   Promise.all([fs11.realpath(root), fs11.realpath(candidate)]).then(([realRoot, realFile]) => {
-    if (realFile !== realRoot && !realFile.startsWith(realRoot + path22.sep)) {
+    if (realFile !== realRoot && !realFile.startsWith(realRoot + path23.sep)) {
       res.writeHead(403);
       res.end("Forbidden");
       return;
     }
-    nodeFs2.stat(realFile, (err2, stat) => {
+    nodeFs3.stat(realFile, (err2, stat) => {
       if (err2 || !stat.isFile()) {
         res.writeHead(404);
         res.end("Not Found");
         return;
       }
       res.writeHead(200, {
-        "Content-Type": MIME[path22.extname(realFile)] ?? "application/octet-stream",
+        "Content-Type": MIME[path23.extname(realFile)] ?? "application/octet-stream",
         "Content-Length": stat.size,
         "Cache-Control": "no-store"
       });
-      nodeFs2.createReadStream(realFile).pipe(res);
+      nodeFs3.createReadStream(realFile).pipe(res);
     });
   }).catch(() => {
     if (!res.headersSent) {
@@ -10892,11 +10980,6 @@ function serveStaticFile(res, root, pathname) {
     }
   });
 }
-function jsonRes(res, code, obj) {
-  const body = Buffer.from(JSON.stringify(obj));
-  res.writeHead(code, { "Content-Type": "application/json; charset=utf-8", "Content-Length": body.length });
-  res.end(body);
-}
 var BodyTooLargeError = class extends Error {
   constructor() {
     super("request body exceeds limit");
@@ -10952,6 +11035,7 @@ function fsErrorStatus(e) {
   if (code === "ENOACTIVE") return 409;
   if (code === "EACCES" || code === "EINVAL") return 403;
   if (code === "ENOENT") return 404;
+  if (code === "EISDIR") return 404;
   return 500;
 }
 async function fsStat(ctx) {
@@ -10960,7 +11044,8 @@ async function fsStat(ctx) {
 }
 async function fsReaddir(ctx) {
   const entries = await readdirWithin(ctx.projectRoot, ctx.rel);
-  jsonRes(ctx.res, 200, entries.map((e) => [e.name, e.isDirectory() ? 2 : 1]));
+  const visible = entries.filter((e) => !(e.isDirectory() && SKIP_DIRS.has(e.name)));
+  jsonRes(ctx.res, 200, visible.map((e) => [e.name, e.isDirectory() ? 2 : 1]));
 }
 async function fsRead(ctx) {
   const buf = await readFileBufferWithin(ctx.projectRoot, ctx.rel);
@@ -11032,7 +11117,7 @@ async function listFilesRecursive(dir, base = "") {
   for (const e of entries) {
     const rel = base ? `${base}/${e.name}` : e.name;
     if (e.isDirectory()) {
-      out.push(...await listFilesRecursive(path22.join(dir, e.name), rel));
+      out.push(...await listFilesRecursive(path23.join(dir, e.name), rel));
     } else if (e.isFile()) {
       out.push(rel);
     }
@@ -11049,9 +11134,9 @@ async function readContributedExtensions(extensionsDir) {
   }
   for (const e of entries) {
     if (!e.isDirectory()) continue;
-    const extDir = path22.join(extensionsDir, e.name);
+    const extDir = path23.join(extensionsDir, e.name);
     try {
-      const pkgRaw = await fs11.readFile(path22.join(extDir, "package.json"), "utf8");
+      const pkgRaw = await fs11.readFile(path23.join(extDir, "package.json"), "utf8");
       const files = await listFilesRecursive(extDir);
       out.push({ dir: e.name, packageJson: JSON.parse(pkgRaw), files });
     } catch {
@@ -11060,11 +11145,15 @@ async function readContributedExtensions(extensionsDir) {
   return out;
 }
 async function startWorkbenchCoiServer(options) {
-  const root = path22.resolve(options.rootDir);
-  const contribRoot = options.extensionsDir ? path22.resolve(options.extensionsDir) : null;
+  const root = path23.resolve(options.rootDir);
+  const contribRoot = options.extensionsDir ? path23.resolve(options.extensionsDir) : null;
   const server = http2.createServer((req, res) => {
     setIsolationHeaders(res);
     const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    if (url.pathname === "/__fs/watch") {
+      handleFsWatchRequest(req, res, options.getProjectRoot);
+      return;
+    }
     if (url.pathname.startsWith("/__fs/")) {
       handleFsRequest(req, res, options.getProjectRoot(), url).catch((e) => {
         if (!res.headersSent) jsonRes(res, 500, { error: String(e) });
@@ -11279,7 +11368,7 @@ async function disposeContext(ctx) {
 function createConfiguredMainWindow(config, rendererDir2) {
   const mainWindow = createMainWindow({
     title: config.appName ?? "Dimina DevTools",
-    indexHtml: path23.join(rendererDir2, "entries/main/index.html"),
+    indexHtml: path24.join(rendererDir2, "entries/main/index.html"),
     width: config.window?.width,
     height: config.window?.height,
     minWidth: config.window?.minWidth,
@@ -11558,8 +11647,8 @@ async function createDevtoolsRuntime(config = {}) {
       bridge: context.bridge
     }));
   }
-  const bundleDir = config.editorViewConfig?.bundleDir ?? path23.join(devtoolsPackageRoot, "dist/vscode-workbench");
-  if (!fs12.existsSync(path23.join(bundleDir, "index.html"))) {
+  const bundleDir = config.editorViewConfig?.bundleDir ?? path24.join(devtoolsPackageRoot, "dist/vscode-workbench");
+  if (!fs12.existsSync(path24.join(bundleDir, "index.html"))) {
     console.warn(
       `[workbench] editor bundle not found at ${bundleDir} \u2014 skipping embedded editor assembly`
     );

package/dist/main/ipc/bridge-router.d.ts

@@ -108,7 +108,7 @@ export interface BridgeRouterHandle {
      */
     census?(): BridgeResourceCensus;
     /**
-     * The flag-gated debugTap (§7) over the bridge message stream. Exposed so a
+     * The flag-gated debugTap (see foundation.md) over the bridge message stream. Exposed so a
      * hidden devtools panel / automation can read `.entries()` when
      * `DIMINA_DEBUG_TAP=1`; a no-op snapshot otherwise. Optional so the many
      * partial `BridgeRouterHandle` test mocks don't each have to stub it.

package/dist/main/ipc/bridge-router.js

@@ -63,10 +63,11 @@ const STACK_ID = 'stack_0';
  * constant instead of a magic number.
  */
 export const LAUNCH_TIMEOUT_MS = 20_000;
-/** Hard ceiling on the pre-warm pool, mirroring ServiceHostPool/doc §3.3. */
+/** Hard ceiling on the pre-warm pool, mirroring ServiceHostPool/prewarm-webview.md. */
 const PREWARM_MAX_POOL_SIZE = 4;
 /**
- * Resolve the pre-warm pool size from env (doc §6). Returns 0 (OFF) unless
+ * Resolve the pre-warm pool size from env (see prewarm-webview.md's config
+ * section). Returns 0 (OFF) unless
  * `DIMINA_PREWARM_POOL_SIZE` is a positive integer and `DIMINA_PREWARM_DISABLE`
  * is not set. Default OFF — pooling is opt-in so the spawn path is unchanged
  * unless explicitly enabled.
@@ -82,7 +83,7 @@ function resolvePrewarmPoolSize() {
         return 0;
     return Math.min(n, PREWARM_MAX_POOL_SIZE);
 }
-/** debugTap (§7) is opt-in via `DIMINA_DEBUG_TAP=1` — off everywhere else. */
+/** debugTap (see foundation.md) is opt-in via `DIMINA_DEBUG_TAP=1` — off everywhere else. */
 function resolveDebugTapEnabled() {
     return process.env.DIMINA_DEBUG_TAP === '1';
 }
@@ -181,8 +182,8 @@ export function installBridgeRouter(ctx) {
     if (prewarmPoolSize > 0) {
         const pool = new ServiceHostPool();
         state.pool = pool;
-        // Defer warm-up off the cold-start critical path (doc §3.3: app.ready +
-        // idle). Warming eagerly here races main-window startup — it creates an
+        // Defer warm-up off the cold-start critical path (see prewarm-webview.md:
+        // app.ready + idle). Warming eagerly here races main-window startup — it creates an
         // extra hidden BrowserWindow before the workbench renderer has settled,
         // which made the e2e's first-window/preload-readiness flaky. The timer is
         // cancelled on teardown so it can't warm a disposed pool.
@@ -451,7 +452,7 @@ export function installBridgeRouter(ctx) {
     };
     ipcMain.on(C.DISPOSE, onDispose);
     ctx.registry.add(() => { ipcMain.removeListener(C.DISPOSE, onDispose); });
-    // debugTap (§7) ingress recorder — near-free no-op unless DIMINA_DEBUG_TAP=1.
+    // debugTap (see foundation.md) ingress recorder — near-free no-op unless DIMINA_DEBUG_TAP=1.
     // Hung on the bridge dispatch chokepoint so the cross-wc message flow is
     // inspectable (the first real consumer of the workbench debugTap primitive).
     const tapIn = (channel, sender, payload) => {
@@ -753,7 +754,8 @@ async function handleSpawn(state, ctx, event, opts) {
     appSession.pages.set(bridgeId, rootPage);
     bindWc(state.serviceWcIdToAppSessionId, serviceWindow.webContents, appSessionId);
     bindSimulatorWc(state.simulatorWcIdToAppSessionIds, simulatorWc, appSessionId);
-    // Track the service-host webContents as a Connection (foundation.md §4.3) and
+    // Track the service-host webContents as a Connection (the soft-reuse
+    // teardown path documented in foundation.md) and
     // own this session's serviceWc→appSessionId binding on its CURRENT lifetime
     // segment. On a pooled-window REUSE, `disposeAppSession` calls
     // `connections.reset(serviceWc.id)` → this owned cleanup fires + a fresh
@@ -761,7 +763,8 @@ async function handleSpawn(state, ctx, event, opts) {
     // real destroy the connection closes and fires it too. The cleanup is guarded
     // by `appSessionId` so it only clears a binding that is still THIS session's.
     // (The simulatorWc binding stays manual in `disposeAppSession`: the simulator
-    // wc outlives individual app sessions — cross-connection state, §4.4 — so it
+    // wc outlives individual app sessions — cross-connection state documented in
+    // foundation.md — so it
     // cannot hang off any single session's segment.)
     state.connections.acquire(serviceWindow.webContents).own(() => {
         if (state.serviceWcIdToAppSessionId.get(appSession.serviceWc.id) === appSessionId) {
@@ -1732,8 +1735,8 @@ function ensureRenderBound(state, sender, bridgeId) {
         page.renderWc = sender;
         state.wcIdToBridgeId.set(sender.id, bridgeId);
         // Consolidate the render-guest bookkeeping teardown onto the connection
-        // layer (foundation.md §4 / P2): the render guest is its own webContents =
-        // its own connection (§4.4); own() ties this cleanup to its lifetime so it
+        // layer (see foundation.md): the render guest is its own webContents =
+        // its own connection; own() ties this cleanup to its lifetime so it
         // fires on destroy, replacing the bespoke `once('destroyed')`. acquire() is
         // idempotent — re-binding the same sender re-uses its connection.
         state.connections.acquire(sender).own(() => {
@@ -1874,7 +1877,7 @@ function closeSessionPages(state, ap) {
 // the unpooled path.
 async function releaseServiceWindow(state, ap, opts) {
     if (ap.poolEntryId !== null && state.pool && !opts.serviceAlreadyClosed) {
-        // Soft reuse (foundation.md §4.3): the pooled service-host webContents keeps
+        // Soft reuse (see foundation.md): the pooled service-host webContents keeps
         // its wc.id but is about to run a NEW app session. Reset its Connection
         // BEFORE returning it to the pool — dispose this session's owned segment
         // (the serviceWc binding cleanup) and swap a fresh one — so an old in-flight

package/dist/main/ipc/project-fs.d.ts

@@ -1,5 +1,9 @@
 import type { WorkbenchContext } from '../services/workbench-context.js';
 import type { Disposable } from '@dimina-kit/electron-deck/main';
+/** Dependency/VCS/build directories invisible to every project-tree consumer:
+ * IPC `listFiles`, the `/__fs/readdir` bridge (so the workbench mirror and the
+ * WAL ledger seed never walk into them), and the `/__fs/watch` change stream. */
+export declare const SKIP_DIRS: ReadonlySet<string>;
 /**
  * Synchronous, string-level guard: reject empty root (ENOACTIVE), NUL bytes
  * and empty paths (EINVAL), and lexical `..` escapes (EACCES) by resolving

package/dist/main/ipc/project-fs.js

@@ -49,7 +49,10 @@ import { validate } from '../utils/ipc-schema.js';
 import { ProjectFsChannel } from '../../shared/ipc-channels.js';
 /** Cap for `listFiles` — huge monorepos would otherwise stall the renderer. */
 const LIST_FILE_LIMIT = 5000;
-const SKIP_DIRS = new Set([
+/** Dependency/VCS/build directories invisible to every project-tree consumer:
+ * IPC `listFiles`, the `/__fs/readdir` bridge (so the workbench mirror and the
+ * WAL ledger seed never walk into them), and the `/__fs/watch` change stream. */
+export const SKIP_DIRS = new Set([
     'node_modules', '.git', '.svn', '.hg', 'dist', 'build',
     '.next', '.cache', '.turbo', '.parcel-cache', '.nuxt', '.output', '.vite',
 ]);

package/dist/main/runtime/miniapp-runtime.d.ts

@@ -1,6 +1,6 @@
 /**
- * MiniappRuntime — the stable, host-facing contract surface (foundation.md §3
- * "MiniappRuntime 契约" layer).
+ * MiniappRuntime — the stable, host-facing contract surface documented in
+ * host-migration.md's public-contract section.
  *
  * HAND-WRITTEN, not derived from `WorkbenchContext`. A `Pick`-style projection
  * would drag every nested internal service type (ViewManager,
@@ -18,7 +18,8 @@
  *  - `workspace.openProject` stays writable (no `readonly`) for backward
  *    compat: hosts MAY still gate permissions by reassigning it. The preferred
  *    path is now the declarative `WorkbenchAppConfig.onBeforeOpenProject` hook
- *    (runs before any side effect, throw to veto) — see host-migration.md §7.
+ *    (runs before any side effect, throw to veto) — see host-migration.md's
+ *    `onBeforeOpenProject` hook section.
  *
  * `asMiniappRuntime(ctx)` is an identity return — the contract is a typed
  * VIEW onto the live context, not a snapshot/projection. That is what makes

package/dist/main/services/fs-watch-sse.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `GET /__fs/watch`: SSE stream of the active project root's disk changes, for
+ * the editor's memfs↔disk sync engine (devtools-fs-core-feasibility.md §7).
+ * Read-only — it adds no write surface, which is why workbench-coi-server.ts
+ * dispatches it before (and outside) the mutating-action guard of the generic
+ * `/__fs/*` handler. Split into its own module purely to keep each file within
+ * the repo size gate; the COI server is its only consumer.
+ *
+ * One `fs.watch(root, {recursive:true})` per connection (darwin supports
+ * `recursive`), changes batched over an 80ms window and pushed as
+ * `data: {"paths":["rel", ...]}` with POSIX-separated root-relative paths.
+ * `getProjectRoot` (not a resolved string) is threaded through so a project
+ * close/switch mid-stream is detected by re-polling the SAME source
+ * `handleFsRequest` uses — no separate close event is invented. Watcher errors
+ * (e.g. EMFILE) push `data: {"watcherDead":true}` then end the stream; no
+ * active project at connect time is a 409, matching the ENOACTIVE semantics of
+ * every other `/__fs` action.
+ */
+import type http from 'node:http';
+/** `false` for build/vcs/dependency churn, the empty string, and any path that
+ * (defensively — `fs.watch`'s filename is always root-relative) escapes the root.
+ * Matches SKIP_DIRS as a path SEGMENT at any depth — the same set `/__fs/readdir`
+ * omits, so the watcher never reports paths the editor mirror cannot see (a
+ * prefix match would let `packages/x/node_modules/...` through). The one
+ * accepted edge: a plain FILE named exactly like a skip dir (e.g. `dist`)
+ * is also unreported, though readdir would list it. */
+declare function shouldReportWatchPath(rel: string): boolean;
+export declare const __testing: {
+    shouldReportWatchPath: typeof shouldReportWatchPath;
+};
+export declare function handleFsWatchRequest(req: http.IncomingMessage, res: http.ServerResponse, getProjectRoot: () => string): void;
+export {};
+//# sourceMappingURL=fs-watch-sse.d.ts.map

package/dist/main/services/fs-watch-sse.js

@@ -0,0 +1,99 @@
+import nodeFs from 'node:fs';
+import path from 'node:path';
+import { SKIP_DIRS } from '../ipc/project-fs.js';
+import { jsonRes } from './http-json.js';
+/** Debounce window for batching change notifications (ms). */
+const WATCH_DEBOUNCE_MS = 80;
+/** `false` for build/vcs/dependency churn, the empty string, and any path that
+ * (defensively — `fs.watch`'s filename is always root-relative) escapes the root.
+ * Matches SKIP_DIRS as a path SEGMENT at any depth — the same set `/__fs/readdir`
+ * omits, so the watcher never reports paths the editor mirror cannot see (a
+ * prefix match would let `packages/x/node_modules/...` through). The one
+ * accepted edge: a plain FILE named exactly like a skip dir (e.g. `dist`)
+ * is also unreported, though readdir would list it. */
+function shouldReportWatchPath(rel) {
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel))
+        return false;
+    return !rel.split('/').some((segment) => SKIP_DIRS.has(segment));
+}
+export const __testing = { shouldReportWatchPath };
+export function handleFsWatchRequest(req, res, getProjectRoot) {
+    const watchedRoot = getProjectRoot();
+    if (!watchedRoot) {
+        jsonRes(res, 409, { error: 'No active project', code: 'ENOACTIVE' });
+        return;
+    }
+    let watcher;
+    try {
+        watcher = nodeFs.watch(watchedRoot, { recursive: true }, onChange);
+    }
+    catch (e) {
+        jsonRes(res, 500, { error: String(e) });
+        return;
+    }
+    res.writeHead(200, {
+        'Content-Type': 'text/event-stream; charset=utf-8',
+        'Cache-Control': 'no-store',
+        Connection: 'keep-alive',
+    });
+    let pending = new Set();
+    let debounceTimer = null;
+    let liveCheck = null;
+    let closed = false;
+    function cleanup() {
+        if (closed)
+            return;
+        closed = true;
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        if (liveCheck)
+            clearInterval(liveCheck);
+        watcher.close();
+    }
+    function flush() {
+        if (closed || pending.size === 0)
+            return;
+        const paths = [...pending];
+        pending = new Set();
+        res.write(`data: ${JSON.stringify({ paths })}\n\n`);
+    }
+    function onChange(_event, filename) {
+        // FSEvents overflow delivers a null filename ("something changed,
+        // rescan"). Dropping it loses data; report '.' and let the client's
+        // watch-batch expansion (wal-audit.ts) reconcile the whole tree.
+        const rel = filename ? filename.toString().split(path.sep).join('/') : '.';
+        if (rel !== '.' && !shouldReportWatchPath(rel))
+            return;
+        pending.add(rel);
+        if (!debounceTimer) {
+            debounceTimer = setTimeout(() => {
+                debounceTimer = null;
+                flush();
+            }, WATCH_DEBOUNCE_MS);
+        }
+    }
+    watcher.on('error', () => {
+        if (closed)
+            return;
+        res.write(`data: ${JSON.stringify({ watcherDead: true })}\n\n`);
+        cleanup();
+        res.end();
+    });
+    // The active project root has no dedicated close/switch event to subscribe
+    // to; poll the same getter `handleFsRequest` uses, on the debounce cadence,
+    // so a closed or switched project tears this stream down promptly. Push
+    // `watcherDead` BEFORE ending so the client gets a deterministic
+    // end-of-channel signal instead of depending on how its EventSource
+    // classifies the reconnect-then-409 that would follow a bare close.
+    liveCheck = setInterval(() => {
+        if (closed)
+            return;
+        if (getProjectRoot() !== watchedRoot) {
+            res.write(`data: ${JSON.stringify({ watcherDead: true })}\n\n`);
+            cleanup();
+            res.end();
+        }
+    }, WATCH_DEBOUNCE_MS);
+    req.on('close', cleanup);
+}
+//# sourceMappingURL=fs-watch-sse.js.map

package/dist/main/services/http-json.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Minimal JSON responder shared by the workbench COI server and its
+ * `/__fs/watch` SSE module (fs-watch-sse.ts). Lives in its own module because
+ * workbench-coi-server.ts imports fs-watch-sse.ts — either file owning it
+ * would force an import cycle for the other.
+ */
+import type http from 'node:http';
+export declare function jsonRes(res: http.ServerResponse, code: number, obj: unknown): void;
+//# sourceMappingURL=http-json.d.ts.map

package/dist/main/services/http-json.js

@@ -0,0 +1,6 @@
+export function jsonRes(res, code, obj) {
+    const body = Buffer.from(JSON.stringify(obj));
+    res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': body.length });
+    res.end(body);
+}
+//# sourceMappingURL=http-json.js.map

package/dist/main/services/render-inspect/index.d.ts

@@ -38,7 +38,7 @@ export interface RenderInspectorOptions {
     /** Override the injected IIFE source (default: read the built bundle). Test seam. */
     loadSource?: () => string;
     /**
-     * Connection registry (foundation.md §4 / P2). When provided, the per-wc
+     * Connection registry (see foundation.md's teardown-paths section). When provided, the per-wc
      * `injected` bookkeeping is torn down via the wc's connection (deterministic
      * with the rest of that webContents's resources) instead of a bespoke
      * `once('destroyed')`. Optional so focused unit tests can omit it (they fall

package/dist/main/services/render-inspect/index.js

@@ -71,7 +71,7 @@ export function createRenderInspector(options = {}) {
         }
         injected.add(wc.id);
         // Consolidate the per-wc bookkeeping teardown onto the connection layer
-        // (foundation.md §4 / P2) when a registry is available; fall back to the
+        // (see foundation.md) when a registry is available; fall back to the
         // bespoke `once('destroyed')` only when omitted (focused unit tests).
         const forget = () => {
             injected.delete(wc.id);