@dimina-kit/devtools 0.4.0-dev.20260701083540 → 0.4.0-dev.20260702145840

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

@@ -12,18 +12,42 @@ import type { DebugTap } from '@dimina-kit/electron-deck/main';
  */
 /**
  * Render-side activity worth re-reading panel data on: a page's DOM mounted
- * (`domReady`) or the visible page changed (`activePage`). Panels that pull
- * from the active render guest (WXML/element-inspect) subscribe via
- * `BridgeRouterHandle.onRenderEvent` so they can refresh without polling.
+ * (`domReady`), the visible page changed (`activePage`), or the active page's
+ * DOM mutated in place (`domMutated`, from the render-guest MutationObserver).
+ * Panels that pull from the active render guest (WXML/element-inspect) subscribe
+ * via `BridgeRouterHandle.onRenderEvent` so they can refresh without polling.
  */
 export interface RenderEvent {
-    kind: 'domReady' | 'activePage';
+    kind: 'domReady' | 'activePage' | 'domMutated';
     appId: string;
     bridgeId: string;
     /** activePage only: the now-visible page's route (bare pagePath), if known.
      * 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;
@@ -70,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,9 @@ async function handleSpawn(state, ctx, event, opts) {
         pages: new Map(),
         activeBridgeId: null,
         poolEntryId,
-        onServiceClosed: null,
         onServiceBoot: null,
+        listenerBag: createSessionListenerBag(),
+        registryHandle: null,
     };
     const rootPage = {
         bridgeId,
@@ -600,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
@@ -613,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);
         }
     });
-    ctx.registry.add(() => disposeAppSession(state, appSessionId));
+    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
@@ -635,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'
@@ -702,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);
@@ -738,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;
     }
@@ -749,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,
@@ -762,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) {
@@ -793,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) {
@@ -856,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;
@@ -977,6 +1045,20 @@ function handleContainerMsg(ap, page, msg, ctx, state) {
             // Guarded + non-throwing: console capture must never break message routing.
             ctx.guestConsole?.emit(msg.body);
             break;
+        case 'storageChanged':
+            // Native-host SYNC storage liveness: the service-host's `setStorageSync`/etc.
+            // write `localStorage` directly (no main round-trip), so they post the change
+            // here for the Storage panel to stay live. Trust `ap.appId` (sender-resolved),
+            // not any appId in the body. Guarded + non-throwing.
+            ctx.onServiceStorageChanged?.(ap.appId, msg.body);
+            break;
+        case 'wxmlChanged':
+            // Native-host WXML liveness: the render-guest MutationObserver posts this when
+            // the active page's DOM mutated in place (setData). Surface it as a render
+            // event so the WXML panel service re-pulls + pushes — same pipeline as
+            // domReady/activePage. Trust `page.bridgeId` (sender-resolved), not the body.
+            state.emitRenderEvent({ kind: 'domMutated', appId: ap.appId, bridgeId: page.bridgeId });
+            break;
         default:
             break;
     }
@@ -1245,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;
     }
@@ -1380,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);
@@ -1391,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);
@@ -1404,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;
 }
@@ -1428,6 +1549,15 @@ async function disposeAppSession(state, appSessionId, opts = {}) {
     if (!ap)
         return;
     state.appSessions.delete(appSessionId);
+    // Remove this session's shutdown-fallback registry entry so the registry does
+    // not accumulate one stale closure per respawn. Ordered AFTER the delete
+    // above: dispose() runs the wrapped fn (disposeAppSession again), which
+    // early-returns now that the session is gone — no recursion, no double-run.
+    // (At whole-app shutdown the registry marks the entry released before calling
+    // the fn, so this dispose() is a no-op then.)
+    const registryHandle = ap.registryHandle;
+    ap.registryHandle = null;
+    void registryHandle?.dispose();
     state.appLifecycle.dispose(appSessionId);
     // Evict AppData bridges FIRST — eviction enumerates `ap.pages`, which the
     // page teardown below progressively empties (and finally clears).
@@ -1459,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
@@ -1468,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);
         }
@@ -1494,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, SimulatorSetNativeBoundsSchema, } 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,13 +8,13 @@ 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();
-    })
-        .handle(SimulatorChannel.SetNativeBounds, (_, ...args) => {
-        const [p] = validate(SimulatorChannel.SetNativeBounds, SimulatorSetNativeBoundsSchema, args);
-        ctx.views.setNativeSimulatorViewBounds(p);
     })
         .handle(SimulatorChannel.SetDeviceInfo, (_, ...args) => {
         const [device] = validate(SimulatorChannel.SetDeviceInfo, SimulatorSetDeviceInfoSchema, args);

package/dist/main/ipc/views.js

@@ -1,6 +1,6 @@
 import { ipcMain } from 'electron';
 import { ViewChannel } from '../../shared/ipc-channels.js';
-import { ViewBoundsSchema, HostToolbarAdvertiseHeightSchema, } from '../../shared/ipc-schemas.js';
+import { PlacementSnapshotSchema, HostToolbarAdvertiseHeightSchema, } from '../../shared/ipc-schemas.js';
 import { validate } from '../utils/ipc-schema.js';
 import { IpcRegistry } from '../utils/ipc-registry.js';
 /**
@@ -20,24 +20,13 @@ import { IpcRegistry } from '../utils/ipc-registry.js';
  */
 export function registerViewsIpc(ctx) {
     const registry = new IpcRegistry(ctx.senderPolicy)
-        .handle(ViewChannel.SimulatorDevtoolsBounds, (_event, ...args) => {
-        const [bounds] = validate(ViewChannel.SimulatorDevtoolsBounds, ViewBoundsSchema, args);
-        ctx.views.setSimulatorDevtoolsBounds(bounds);
-    })
-        // Embedded workbench editor: forward anchor (the MAIN renderer measures
-        // the 'editor' dock slot rect → workbench WCV bounds). invoke, mirroring
-        // SimulatorDevtoolsBounds. No-op in the view manager when the workbench view
-        // was never attached (the host did not opt into the workbench editor).
-        .handle(ViewChannel.WorkbenchBounds, (_event, ...args) => {
-        const [bounds] = validate(ViewChannel.WorkbenchBounds, ViewBoundsSchema, args);
-        ctx.views.setWorkbenchBounds(bounds);
-    })
-        // Host-controllable toolbar: forward anchor (the MAIN renderer measures the
-        // placeholder rect → toolbar WCV bounds). invoke, mirroring
-        // SimulatorDevtoolsBounds. Sender is the trusted main renderer.
-        .handle(ViewChannel.HostToolbarBounds, (_event, ...args) => {
-        const [bounds] = validate(ViewChannel.HostToolbarBounds, ViewBoundsSchema, args);
-        ctx.views.setHostToolbarBounds(bounds);
+        // Window-level placement snapshot: the single source of truth for every
+        // managed native view's bounds/visibility/z-order. The renderer's central
+        // publisher coalesces one snapshot per frame; the reconciler diffs it
+        // against the actual view tree. Supersedes the per-view bounds channels.
+        .handle(ViewChannel.PlacementSnapshot, (_event, ...args) => {
+        const [snapshot] = validate(ViewChannel.PlacementSnapshot, PlacementSnapshotSchema, args);
+        ctx.views.setPlacementSnapshot(snapshot);
     })
         // Height replay pull: a freshly-mounted main-renderer placeholder asks for
         // the last NOTIFIED toolbar height (main retains it — the toolbar's