@dimina-kit/devtools 0.4.0-dev.20260701155140 → 0.4.0-dev.20260702164903

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

@@ -25,6 +25,29 @@ export interface RenderEvent {
      * Lets the current-page panel push the route without a separate lookup. */
     pagePath?: string;
 }
+/**
+ * Point-in-time counts of every resource class RouterState owns. Leak coverage
+ * (unit + e2e) asserts EXACT equality of this ledger around a churn cycle —
+ * coarse memory sampling cannot see a leaked listener or a stale map entry, so
+ * the owner of the bookkeeping reports precise counts instead.
+ */
+export interface BridgeResourceCensus {
+    appSessions: number;
+    pageSessions: number;
+    serviceWcBindings: number;
+    /** Distinct live simulator webContents currently hosting ≥1 session. */
+    simulatorWcs: number;
+    /** Total session memberships across all simulator wcs. */
+    simulatorWcBindings: number;
+    renderWcBindings: number;
+    pendingApiCalls: number;
+    /**
+     * `listenerCount('destroyed')` per unique live simulator wc (keyed by wc id).
+     * One teardown hook per live session — a count above the hosted-session count
+     * is the one-dead-listener-per-soft-reload leak class.
+     */
+    simulatorDestroyedListeners: Record<number, number>;
+}
 export interface BridgeRouterHandle {
     /** Whether native-host mode is on (main is the source of truth). */
     isNativeHost(): boolean;
@@ -71,6 +94,11 @@ export interface BridgeRouterHandle {
      * error channel.
      */
     disposeSessionsForSimulator?(simulatorWcId: number): Promise<void>;
+    /**
+     * The router's resource ledger (see BridgeResourceCensus). Optional so the
+     * many partial BridgeRouterHandle test mocks don't each have to stub it.
+     */
+    census?(): BridgeResourceCensus;
     /**
      * The flag-gated debugTap (§7) over the bridge message stream. Exposed so a
      * hidden devtools panel / automation can read `.entries()` when

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

@@ -4,6 +4,7 @@ import { pathToFileURL } from 'node:url';
 import { BRIDGE_CHANNELS as C, SIMULATOR_EVENTS as E, deviceInfoToHostEnv } from '../../shared/bridge-channels.js';
 import { isPersistentSimulatorApi } from '../../shared/simulator-api-metadata.js';
 import { devtoolsPackageRoot } from '../utils/paths.js';
+import { createSessionListenerBag } from './session-listener-bag.js';
 import { createDebugTap } from '@dimina-kit/electron-deck/main';
 import { startDiminaResourceServer } from '../services/dimina-resource-server.js';
 import { buildServiceHostSpawnUrl, createServiceHostWindow, navigateServiceHost, serviceHostSpec, } from '../windows/service-host-window/create.js';
@@ -147,7 +148,8 @@ export function installBridgeRouter(ctx) {
     const state = {
         appSessions: new Map(),
         pageSessions: new Map(),
-        wcIdToAppSessionId: new Map(),
+        serviceWcIdToAppSessionId: new Map(),
+        simulatorWcIdToAppSessionIds: new Map(),
         wcIdToBridgeId: new Map(),
         pendingApiCalls: new Map(),
         pool: null,
@@ -299,8 +301,37 @@ export function installBridgeRouter(ctx) {
             return Promise.all(ids.map((id) => disposeAppSession(state, id))).then(() => { });
         },
         debugTap: state.debugTap,
+        census: () => {
+            const simulatorDestroyedListeners = {};
+            let simulatorWcBindings = 0;
+            for (const ids of state.simulatorWcIdToAppSessionIds.values())
+                simulatorWcBindings += ids.size;
+            for (const ap of state.appSessions.values()) {
+                const wc = ap.simulatorWc;
+                if (!wc.isDestroyed() && simulatorDestroyedListeners[wc.id] === undefined) {
+                    simulatorDestroyedListeners[wc.id] = wc.listenerCount('destroyed');
+                }
+            }
+            return {
+                appSessions: state.appSessions.size,
+                pageSessions: state.pageSessions.size,
+                serviceWcBindings: state.serviceWcIdToAppSessionId.size,
+                simulatorWcs: state.simulatorWcIdToAppSessionIds.size,
+                simulatorWcBindings,
+                renderWcBindings: state.wcIdToBridgeId.size,
+                pendingApiCalls: state.pendingApiCalls.size,
+                simulatorDestroyedListeners,
+            };
+        },
     };
     ctx.bridge = bridgeHandle;
+    // e2e resource-census probe: Playwright's electronApp.evaluate() reads the
+    // router's ledger straight off this main-process global — no IPC surface
+    // needed. Test builds only.
+    if (process.env.NODE_ENV === 'test') {
+        ;
+        globalThis.__diminaResourceCensus = () => bridgeHandle.census?.();
+    }
     // Always-on guest console fan-out. Owns `ctx.guestConsole` (the sink the
     // consoleLog case below routes to) so that render-layer console output is
     // mirrored into the service host's own console — surfacing it in the embedded
@@ -322,8 +353,7 @@ export function installBridgeRouter(ctx) {
         const ap = state.appSessions.get(payload.appSessionId);
         if (!ap)
             return;
-        const senderApp = appByWc(state, event.sender);
-        if (!senderApp || senderApp.appSessionId !== ap.appSessionId)
+        if (!senderBoundToSession(state, event.sender, ap))
             return;
         if (ap.pages.has(payload.bridgeId)) {
             ap.activeBridgeId = payload.bridgeId;
@@ -340,8 +370,7 @@ export function installBridgeRouter(ctx) {
         const ap = state.appSessions.get(payload.appSessionId);
         if (!ap)
             return;
-        const senderApp = appByWc(state, event.sender);
-        if (!senderApp || senderApp.appSessionId !== ap.appSessionId)
+        if (!senderBoundToSession(state, event.sender, ap))
             return;
         ap.pageStack = payload.stack;
     };
@@ -366,8 +395,7 @@ export function installBridgeRouter(ctx) {
         // its tab (mirrors the default path's postMessage(pageUnload) eviction).
         if (payload.event === 'pageUnload' && ctx.appData) {
             const ap = state.appSessions.get(payload.appSessionId);
-            const senderApp = appByWc(state, event.sender);
-            if (ap && senderApp && senderApp.appSessionId === ap.appSessionId) {
+            if (ap && senderBoundToSession(state, event.sender, ap)) {
                 ctx.appData.evictBridge(ap.appId, payload.bridgeId);
             }
         }
@@ -384,9 +412,11 @@ export function installBridgeRouter(ctx) {
         if (!target)
             return;
         // Only the app's service window or simulator window can issue dispose.
-        const senderApp = appByWc(state, event.sender);
-        if (senderApp && senderApp.appSessionId !== target.appSessionId) {
-            console.warn(`[bridge-router] DISPOSE rejected: sender belongs to ${senderApp.appSessionId}, target ${target.appSessionId}`);
+        // (Unknown senders pass — lenient by design; a simulator WCV is authorized
+        // for every session it hosts, so an older session's own dispose stays
+        // valid while a newer spawn shares the wc.)
+        if (!senderBoundToSession(state, event.sender, target) && appByWc(state, event.sender)) {
+            console.warn(`[bridge-router] DISPOSE rejected: sender not bound to target ${target.appSessionId}`);
             return;
         }
         // AppData bridge eviction happens inside disposeAppSession (single
@@ -581,8 +611,8 @@ async function handleSpawn(state, ctx, event, opts) {
         pages: new Map(),
         activeBridgeId: null,
         poolEntryId,
-        onServiceClosed: null,
         onServiceBoot: null,
+        listenerBag: createSessionListenerBag(),
         registryHandle: null,
     };
     const rootPage = {
@@ -601,8 +631,8 @@ async function handleSpawn(state, ctx, event, opts) {
     state.appSessions.set(appSessionId, appSession);
     state.pageSessions.set(bridgeId, rootPage);
     appSession.pages.set(bridgeId, rootPage);
-    bindWc(state.wcIdToAppSessionId, serviceWindow.webContents, appSessionId);
-    bindWc(state.wcIdToAppSessionId, simulatorWc, appSessionId);
+    bindWc(state.serviceWcIdToAppSessionId, serviceWindow.webContents, appSessionId);
+    bindSimulatorWc(state.simulatorWcIdToAppSessionIds, simulatorWc, appSessionId);
     // Track the service-host webContents as a Connection (foundation.md §4.3) and
     // own this session's serviceWc→appSessionId binding on its CURRENT lifetime
     // segment. On a pooled-window REUSE, `disposeAppSession` calls
@@ -614,16 +644,15 @@ async function handleSpawn(state, ctx, event, opts) {
     // wc outlives individual app sessions — cross-connection state, §4.4 — so it
     // cannot hang off any single session's segment.)
     state.connections.acquire(serviceWindow.webContents).own(() => {
-        if (state.wcIdToAppSessionId.get(appSession.serviceWc.id) === appSessionId) {
-            state.wcIdToAppSessionId.delete(appSession.serviceWc.id);
+        if (state.serviceWcIdToAppSessionId.get(appSession.serviceWc.id) === appSessionId) {
+            state.serviceWcIdToAppSessionId.delete(appSession.serviceWc.id);
         }
     });
     appSession.registryHandle = ctx.registry.add(() => disposeAppSession(state, appSessionId));
     const onServiceClosed = () => {
         void disposeAppSession(state, appSessionId, { serviceAlreadyClosed: true });
     };
-    appSession.onServiceClosed = onServiceClosed;
-    serviceWindow.once('closed', onServiceClosed);
+    appSession.listenerBag.once(serviceWindow, 'closed', onServiceClosed);
     // The simulator WCV owns the app's UI lifetime. When it is destroyed —
     // project close (`views.disposeAll`/detach) or a DeviceShell respawn
     // (`attachNativeSimulator`, e.g. watcher hot reload) — the guest never gets
@@ -636,7 +665,7 @@ async function handleSpawn(state, ctx, event, opts) {
     const onSimulatorDestroyed = () => {
         void disposeAppSession(state, appSessionId);
     };
-    simulatorWc.once('destroyed', onSimulatorDestroyed);
+    appSession.listenerBag.once(simulatorWc, 'destroyed', onSimulatorDestroyed);
     // The simulator WCV may have been torn down DURING this spawn's awaits
     // (loadAppConfig / resource server / service-host creation) — e.g. a project
     // close/switch that ran while we were mid-flight. In that case its 'destroyed'
@@ -703,8 +732,7 @@ async function handlePageOpen(state, event, opts) {
     if (!ap)
         throw new Error(`[bridge-router] PAGE_OPEN unknown appSession ${opts.appSessionId}`);
     // Only the simulator window owning the app can open additional pages.
-    const senderApp = appByWc(state, event.sender);
-    if (!senderApp || senderApp.appSessionId !== opts.appSessionId) {
+    if (!senderBoundToSession(state, event.sender, ap)) {
         throw new Error('[bridge-router] PAGE_OPEN rejected: caller not bound to app session');
     }
     const pagePath = normalizePagePath(opts.pagePath);
@@ -739,8 +767,7 @@ function handlePageClose(state, sender, payload) {
     const ap = state.appSessions.get(page.appSessionId);
     if (!ap)
         return;
-    const senderApp = appByWc(state, sender);
-    if (!senderApp || senderApp.appSessionId !== ap.appSessionId) {
+    if (!senderBoundToSession(state, sender, ap)) {
         console.warn('[bridge-router] PAGE_CLOSE rejected: caller not bound to app session');
         return;
     }
@@ -750,8 +777,7 @@ function handlePageLifecycle(state, sender, payload) {
     const ap = state.appSessions.get(payload.appSessionId);
     if (!ap)
         return;
-    const senderApp = appByWc(state, sender);
-    if (!senderApp || senderApp.appSessionId !== ap.appSessionId)
+    if (!senderBoundToSession(state, sender, ap))
         return;
     forwardToService(ap, {
         type: payload.event,
@@ -763,8 +789,7 @@ function handleNavCallback(state, sender, payload) {
     const ap = state.appSessions.get(payload.appSessionId);
     if (!ap)
         return;
-    const senderApp = appByWc(state, sender);
-    if (!senderApp || senderApp.appSessionId !== ap.appSessionId)
+    if (!senderBoundToSession(state, sender, ap))
         return;
     const result = { errMsg: payload.errMsg };
     if (payload.ok) {
@@ -794,23 +819,50 @@ async function bootServiceHost(state, ap, ctx) {
         reportLogicLoadFailure(ap, ctx);
         return;
     }
-    // serviceLoaded is flipped only when service responds with
-    // `serviceResourceLoaded`; see handleContainerMsg. Setting it here would
-    // race a per-page `resourceLoaded` ahead of the service-side handler.
-    forwardToService(ap, makeLoadResource(ap, ap.pages.get(ap.appSessionId), 'service'));
+    // A root page absent from the compiled manifest — most commonly a page the
+    // developer deleted, then hot-reloaded to — is not registered in logic.js.
+    // BOTH the service runtime AND the render runtime eager-`modRequire(pagePath)`
+    // it and throw `module <pagePath> not found`, which aborts the launch and
+    // leaves the simulator permanently blank. Gate BOTH sends and surface a
+    // WeChat-style diagnostic instead: the shell stays alive (an empty phone frame
+    // + a clear Console error) rather than a silent dead blank. Choosing a valid
+    // fallback page belongs at the renderer reload source (it owns the pagePath
+    // the render guest is spawned with); here we only refuse a load guaranteed to
+    // throw, so main and render never disagree about which page is live.
+    const rootPage = ap.pages.get(ap.appSessionId);
+    const rootMissing = !!rootPage && !pageInManifest(ap, rootPage.pagePath);
+    if (rootMissing) {
+        reportPageNotFound(ap, ctx, rootPage.pagePath);
+    }
+    else if (rootPage) {
+        // serviceLoaded is flipped only when service responds with
+        // `serviceResourceLoaded`; see handleContainerMsg. Setting it here would
+        // race a per-page `resourceLoaded` ahead of the service-side handler.
+        forwardToService(ap, makeLoadResource(ap, rootPage, 'service'));
+    }
     // Flush any render `loadResource` that arrived (renderHostReady) while
     // injection was in-flight — now that the bundle is confirmed present.
+    // `sendRenderLoadResource` refuses a page absent from the manifest, so a
+    // missing root never reaches the throwing render `modRequire`.
     for (const page of ap.pages.values()) {
-        if (page.renderLoadPending) {
-            page.renderLoadPending = false;
-            sendRenderLoadResource(ap, page);
-        }
+        if (!page.renderLoadPending)
+            continue;
+        page.renderLoadPending = false;
+        sendRenderLoadResource(ap, page);
     }
 }
 function sendRenderLoadResource(ap, page) {
-    if (page.renderWc && !page.renderWc.isDestroyed()) {
-        page.renderWc.send(C.TO_RENDER, { msg: makeLoadResource(ap, page, 'render') });
-    }
+    if (!page.renderWc || page.renderWc.isDestroyed())
+        return;
+    // Single choke point for BOTH the boot flush above and the late
+    // `renderHostReady` direct-send in `routeFromRender`: never send a render load
+    // for a page absent from the compiled manifest. The render runtime
+    // eager-`modRequire`s the pagePath and would throw `module <pagePath> not
+    // found`, blanking the simulator (a page the developer deleted, then
+    // hot-reloaded to). bootServiceHost surfaces the one-shot diagnostic.
+    if (!pageInManifest(ap, page.pagePath))
+        return;
+    page.renderWc.send(C.TO_RENDER, { msg: makeLoadResource(ap, page, 'render') });
 }
 /** The compiled logic.js URL `injectLogicBundle` fetches (mode-dependent). */
 function logicBundleUrl(ap) {
@@ -857,6 +909,21 @@ function reportLogicLoadFailure(ap, ctx) {
     console.error(message);
     ctx.guestConsole?.emit({ source: 'service', level: 'error', args: [message] });
 }
+/** Whether `pagePath` still exists in the app's freshly compiled manifest. */
+function pageInManifest(ap, pagePath) {
+    return ap.manifest.pages.includes(normalizePagePath(pagePath));
+}
+/**
+ * WeChat-devtools-style "page does not exist" diagnostic. Emitted (main log +
+ * guest Console) when a mount targets a pagePath that is not in the compiled
+ * manifest — most commonly a page the developer deleted, then hot-reloaded.
+ */
+function reportPageNotFound(ap, ctx, pagePath) {
+    const message = `Page[${pagePath}] not found. May be caused by: 1. Forgetting to add page route in app.json. `
+        + '2. Invoking Page() in async task.';
+    console.error(`[bridge-router] ${message}`);
+    ctx.guestConsole?.emit({ source: 'service', level: 'error', args: [message] });
+}
 function maybeSendResourceLoaded(ap, page) {
     if (page.resourceLoadedSent || !ap.serviceLoaded || !page.renderLoaded)
         return;
@@ -1260,11 +1327,13 @@ function handleApiResponse(state, sender, payload) {
         clearTimeout(pending.timer);
         return;
     }
-    // Only the simulator window bound to that app may respond. Validate BEFORE
+    // Only a simulator window bound to the OWNING session may respond. Membership
+    // (senderBoundToSession), not sender-resolution equality: during a soft-reload
+    // overlap the shared simulator wc still answers the outgoing session's
+    // in-flight calls, which a latest-wins comparison would drop. Validate BEFORE
     // mutating pending state so a spoofed/foreign response can't tear down a
     // live subscription.
-    const senderApp = appByWc(state, sender);
-    if (!senderApp || senderApp.appSessionId !== ap.appSessionId) {
+    if (!senderBoundToSession(state, sender, ap)) {
         console.warn('[bridge-router] API_RESPONSE rejected: sender not bound to app session');
         return;
     }
@@ -1395,9 +1464,20 @@ function pageFromMsg(state, ap, msg) {
 function appByWc(state, wc) {
     if (wc.isDestroyed())
         return undefined;
-    const appSessionId = state.wcIdToAppSessionId.get(wc.id);
+    const appSessionId = state.serviceWcIdToAppSessionId.get(wc.id);
     if (appSessionId)
         return state.appSessions.get(appSessionId);
+    // A simulator wc hosts several sessions during a soft reload; a message that
+    // doesn't name its session belongs to the LATEST still-alive spawn (the Set
+    // preserves spawn order).
+    const hosted = state.simulatorWcIdToAppSessionIds.get(wc.id);
+    if (hosted) {
+        let latest;
+        for (const id of hosted)
+            latest = state.appSessions.get(id) ?? latest;
+        if (latest)
+            return latest;
+    }
     const bridgeId = state.wcIdToBridgeId.get(wc.id);
     if (bridgeId) {
         const page = state.pageSessions.get(bridgeId);
@@ -1406,6 +1486,21 @@ function appByWc(state, wc) {
     }
     return undefined;
 }
+/**
+ * Whether `sender` is authorized to control app session `ap`. A simulator WCV
+ * is authorized for EVERY session it hosts (`simulatorWcIdToAppSessionIds` is
+ * a membership set, so an older session's own control traffic stays valid
+ * while a newer spawn boots on the same wc); any other sender (service host,
+ * render guest) resolves one-to-one through `appByWc`.
+ */
+function senderBoundToSession(state, sender, ap) {
+    if (sender.isDestroyed())
+        return false;
+    const hosted = state.simulatorWcIdToAppSessionIds.get(sender.id);
+    if (hosted)
+        return hosted.has(ap.appSessionId);
+    return appByWc(state, sender)?.appSessionId === ap.appSessionId;
+}
 function resolveAppByBridgeId(state, bridgeId) {
     if (state.appSessions.has(bridgeId))
         return state.appSessions.get(bridgeId);
@@ -1419,6 +1514,17 @@ function bindWc(map, wc, id) {
         return;
     map.set(wc.id, id);
 }
+/** Add a session to a simulator wc's hosted set (created on first bind). */
+function bindSimulatorWc(map, wc, id) {
+    if (wc.isDestroyed())
+        return;
+    let hosted = map.get(wc.id);
+    if (!hosted) {
+        hosted = new Set();
+        map.set(wc.id, hosted);
+    }
+    hosted.add(id);
+}
 function readBridgeId(msg) {
     return typeof msg.body?.bridgeId === 'string' ? msg.body.bridgeId : undefined;
 }
@@ -1483,6 +1589,14 @@ async function disposeAppSession(state, appSessionId, opts = {}) {
         state.pageSessions.delete(page.bridgeId);
     }
     ap.pages.clear();
+    // Detach every session-scoped hook on emitters that outlive this session —
+    // the shared simulator WCV's 'destroyed' and the service window's 'closed' —
+    // BEFORE the window is released/closed below: a pool-recycled window must
+    // not re-trigger this session's teardown from a stale 'closed', and the
+    // simulator wc must not accumulate one dead hook per soft reload until the
+    // MaxListeners warning fires. Idempotent with teardown being triggered BY
+    // one of these hooks (removing a fired once() is a no-op).
+    ap.listenerBag.dispose();
     if (ap.poolEntryId !== null && state.pool && !opts.serviceAlreadyClosed) {
         // Soft reuse (foundation.md §4.3): the pooled service-host webContents keeps
         // its wc.id but is about to run a NEW app session. Reset its Connection
@@ -1492,13 +1606,10 @@ async function disposeAppSession(state, appSessionId, opts = {}) {
         // clean segment. The connection object stays alive (it's reused), so this is
         // reset (not close); a real destroy still closes it via its 'destroyed' hook.
         state.connections.reset(ap.serviceWc.id);
-        // Return the window to the pool instead of closing it. Detach the per-spawn
-        // listeners first so the pool resetting/recycling (or a later pool-side
-        // destroy) can't re-trigger disposeAppSession or boot this disposed session
-        // into the next spawn's recycled window.
-        if (ap.onServiceClosed && !ap.serviceWindow.isDestroyed()) {
-            ap.serviceWindow.removeListener('closed', ap.onServiceClosed);
-        }
+        // Return the window to the pool instead of closing it. Detach the boot
+        // listener first (the 'closed' hook already came off with the listener-bag
+        // dispose above) so a stale did-finish-load can't boot this disposed
+        // session into the next spawn's recycled window.
         if (ap.onServiceBoot && !ap.serviceWindow.isDestroyed()) {
             ap.serviceWindow.webContents.removeListener('did-finish-load', ap.onServiceBoot);
         }
@@ -1518,8 +1629,22 @@ async function disposeAppSession(state, appSessionId, opts = {}) {
     else if (!opts.serviceAlreadyClosed && !ap.serviceWindow.isDestroyed()) {
         ap.serviceWindow.close();
     }
-    state.wcIdToAppSessionId.delete(ap.serviceWc.id);
-    state.wcIdToAppSessionId.delete(ap.simulatorWc.id);
+    // Value-checked unbind for the service wc: this delete runs after the
+    // pool-release await above, so on the pool path the next spawn may have
+    // already re-acquired the SAME window and rebound its wc id — only remove
+    // an entry that still names THIS session.
+    if (state.serviceWcIdToAppSessionId.get(ap.serviceWc.id) === appSessionId) {
+        state.serviceWcIdToAppSessionId.delete(ap.serviceWc.id);
+    }
+    // The simulator wc's hosted set sheds only this session; sessions that are
+    // still live on the shared wc (the soft-reload survivor) keep their
+    // membership. The map entry goes away with the last session.
+    const hosted = state.simulatorWcIdToAppSessionIds.get(ap.simulatorWc.id);
+    if (hosted) {
+        hosted.delete(appSessionId);
+        if (hosted.size === 0)
+            state.simulatorWcIdToAppSessionIds.delete(ap.simulatorWc.id);
+    }
     // Only the local fallback server needs closing; the dev-server base is owned
     // by the workspace session, not this app session.
     if (ap.resourceServer) {

package/dist/main/ipc/session-listener-bag.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Session-scoped listener bookkeeping. An app session hangs lifecycle hooks on
+ * emitters it does NOT own — the shared simulator WebContentsView, a pooled
+ * service-host window — and those emitters outlive the session (one simulator
+ * wc soft-reloads through many sessions). Every such hook is registered
+ * through this bag so the session's single teardown chokepoint can detach them
+ * all with one `dispose()`; a hook left behind survives as a dead listener on
+ * the shared emitter, growing by one per soft reload until Node's MaxListeners
+ * warning fires.
+ */
+type Listener = (...args: unknown[]) => void;
+/**
+ * Structural surface of the Node/Electron emitters the bag manages.
+ * `removeListener(event, fn)` also detaches a `once(event, fn)` registration:
+ * Node's once wrapper keeps a `.listener` back-reference to `fn` and
+ * removeListener matches through it. `isDestroyed` covers Electron objects
+ * (WebContents / BrowserWindow) whose methods throw once destroyed.
+ */
+export interface BagEmitter {
+    on(event: string, listener: Listener): unknown;
+    once(event: string, listener: Listener): unknown;
+    removeListener(event: string, listener: Listener): unknown;
+    isDestroyed?(): boolean;
+}
+export interface SessionListenerBag {
+    /** Attach `fn` via `emitter.on` and track it for dispose. No-op after dispose. */
+    on(emitter: BagEmitter, event: string, fn: Listener): void;
+    /** Attach `fn` via `emitter.once` and track it for dispose. No-op after dispose. */
+    once(emitter: BagEmitter, event: string, fn: Listener): void;
+    /**
+     * Detach every tracked listener that may still be attached. Emitters that
+     * report `isDestroyed()` are skipped — their listeners died with them, and
+     * touching a destroyed Electron object throws. Removing a `once` that
+     * already fired is a no-op, so dispose is safe to call FROM one of the
+     * bag's own hooks (teardown triggered by the hook itself). Idempotent.
+     */
+    dispose(): void;
+}
+export declare function createSessionListenerBag(): SessionListenerBag;
+export {};
+//# sourceMappingURL=session-listener-bag.d.ts.map

package/dist/main/ipc/session-listener-bag.js

@@ -0,0 +1,40 @@
+/**
+ * Session-scoped listener bookkeeping. An app session hangs lifecycle hooks on
+ * emitters it does NOT own — the shared simulator WebContentsView, a pooled
+ * service-host window — and those emitters outlive the session (one simulator
+ * wc soft-reloads through many sessions). Every such hook is registered
+ * through this bag so the session's single teardown chokepoint can detach them
+ * all with one `dispose()`; a hook left behind survives as a dead listener on
+ * the shared emitter, growing by one per soft reload until Node's MaxListeners
+ * warning fires.
+ */
+export function createSessionListenerBag() {
+    const records = [];
+    let disposed = false;
+    return {
+        on(emitter, event, fn) {
+            if (disposed)
+                return;
+            emitter.on(event, fn);
+            records.push({ emitter, event, fn });
+        },
+        once(emitter, event, fn) {
+            if (disposed)
+                return;
+            emitter.once(event, fn);
+            records.push({ emitter, event, fn });
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const { emitter, event, fn } of records) {
+                if (emitter.isDestroyed?.())
+                    continue;
+                emitter.removeListener(event, fn);
+            }
+            records.length = 0;
+        },
+    };
+}
+//# sourceMappingURL=session-listener-bag.js.map

package/dist/main/ipc/simulator.js

@@ -1,5 +1,5 @@
 import { ServiceHostChannel, SimulatorChannel, SimulatorCustomApiChannel } from '../../shared/ipc-channels.js';
-import { SimulatorAttachNativeSchema, SimulatorCustomApiInvokeSchema, SimulatorSetDeviceInfoSchema, } from '../../shared/ipc-schemas.js';
+import { SimulatorAttachNativeSchema, SimulatorCustomApiInvokeSchema, SimulatorSetDeviceInfoSchema, SimulatorSoftReloadSchema, } from '../../shared/ipc-schemas.js';
 import { deviceInfoToHostEnv } from '../../shared/bridge-channels.js';
 import { validate } from '../utils/ipc-schema.js';
 import { IpcRegistry } from '../utils/ipc-registry.js';
@@ -8,6 +8,10 @@ export function registerSimulatorIpc(ctx) {
         .handle(SimulatorChannel.AttachNative, (_, ...args) => {
         const [simulatorUrl, simWidth] = validate(SimulatorChannel.AttachNative, SimulatorAttachNativeSchema, args);
         return ctx.views.attachNativeSimulator(simulatorUrl, simWidth);
+    })
+        .handle(SimulatorChannel.SoftReload, (_, ...args) => {
+        const [simulatorUrl] = validate(SimulatorChannel.SoftReload, SimulatorSoftReloadSchema, args);
+        return ctx.views.softReloadNativeSimulator(simulatorUrl);
     })
         .handle(SimulatorChannel.Detach, () => {
         ctx.views.detachSimulator();

package/dist/main/services/elements-forward/index.js

@@ -49,6 +49,7 @@
  * hook + dispatch scripts) as self-contained code.
  */
 import { webContents as electronWebContents } from 'electron';
+import { isFrontendSettled } from '../views/inject-when-ready.js';
 /**
  * CDP domains that target the RENDER GUEST'S document tree. A command in one of
  * these is intercepted and sent to the active render guest's debugger instead of
@@ -274,6 +275,12 @@ export function installElementsForward(deps) {
     function dispatchToFrontend(message) {
         if (disposed || devtoolsWc.isDestroyed())
             return;
+        // Unified settled gate (same predicate as the reconcile tick): an unsettled
+        // front-end wipes its state on load anyway, so the message is meaningless
+        // there — and the executeJavaScript would queue one did-stop-loading waiter
+        // per push (an activePage burst piles them). The post-settle tick re-primes.
+        if (!isFrontendSettled(devtoolsWc))
+            return;
         let json;
         try {
             json = JSON.stringify(message);
@@ -309,6 +316,10 @@ export function installElementsForward(deps) {
     function pushDocumentUpdated() {
         if (disposed || devtoolsWc.isDestroyed())
             return;
+        // Same unified settled gate as dispatchToFrontend — render events (the
+        // activePage burst) drive this during churn.
+        if (!isFrontendSettled(devtoolsWc))
+            return;
         let script;
         try {
             script = buildDocumentUpdatedScript();
@@ -594,6 +605,14 @@ export function installElementsForward(deps) {
                 stop();
                 return;
             }
+            // An unsettled front-end can't run the script anyway, and executeJavaScript
+            // against it queues one did-stop-loading waiter PER TICK on the emitter
+            // (150ms × a seconds-long reload piles past the MaxListeners ceiling).
+            // MUST be the shared Electron-aligned predicate — a bare isLoading()
+            // probe diverges from Electron's internal isLoadingMainFrame gate and
+            // keeps piling. Skip; the first post-settle tick re-establishes the hook.
+            if (!isFrontendSettled(devtoolsWc))
+                return;
             devtoolsWc
                 .executeJavaScript(buildReconcileScript())
                 .then((res) => {

package/dist/main/services/network-forward/index.js

@@ -1,4 +1,5 @@
 import { DisposableRegistry, toDisposable } from '@dimina-kit/electron-deck/main';
+import { isFrontendSettled } from '../views/inject-when-ready.js';
 // ── requestId namespacing (pure, testable) ──────────────────────────────────
 /**
  * CDP events whose `params.requestId` we rewrite into the virtual namespace.
@@ -359,6 +360,18 @@ export function createNetworkForwarder(bridge) {
             trimQueue();
             return;
         }
+        if (!isFrontendSettled(wc)) {
+            // An unsettled front-end can't run the dispatch script anyway — and every
+            // executeJavaScript against it queues one did-stop-loading waiter on the
+            // emitter, so a relaunch's network burst piles them past the MaxListeners
+            // ceiling. MUST be the shared Electron-aligned predicate (a bare
+            // isLoading() probe diverges from the internal isLoadingMainFrame gate).
+            // Hold the (bounded) queue; the next event's flush or the ready-retry
+            // delivers after the load.
+            trimQueue();
+            scheduleReadyRetry();
+            return;
+        }
         if (sink === 'idle')
             beginProbing();
         // Pack greedily up to MAX_BATCH_CHARS so one executeJavaScript stays sized;

package/dist/main/services/views/destroy-child-view.d.ts

@@ -0,0 +1,9 @@
+import type { BrowserWindow, WebContentsView } from 'electron';
+/**
+ * Detach a child overlay WebContentsView from the main window's contentView and
+ * close its webContents. Tolerates an already-removed view and a destroyed
+ * webContents (best-effort teardown). The single low-level view-destroy path
+ * shared by every overlay domain.
+ */
+export declare function destroyChildView(mainWindow: BrowserWindow, view: WebContentsView | null): void;
+//# sourceMappingURL=destroy-child-view.d.ts.map

package/dist/main/services/views/destroy-child-view.js

@@ -0,0 +1,23 @@
+/**
+ * Detach a child overlay WebContentsView from the main window's contentView and
+ * close its webContents. Tolerates an already-removed view and a destroyed
+ * webContents (best-effort teardown). The single low-level view-destroy path
+ * shared by every overlay domain.
+ */
+export function destroyChildView(mainWindow, view) {
+    if (!view)
+        return;
+    if (!mainWindow.isDestroyed()) {
+        try {
+            mainWindow.contentView.removeChildView(view);
+        }
+        catch { /* already removed */ }
+    }
+    try {
+        if (!view.webContents.isDestroyed()) {
+            view.webContents.close();
+        }
+    }
+    catch { /* ignore */ }
+}
+//# sourceMappingURL=destroy-child-view.js.map