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

package/dist/main/services/views/view-manager.js

@@ -17,6 +17,9 @@ import { acquireHostToolbarSessionRuntime, releaseHostToolbarSessionRuntime, } f
 import { createHostToolbarPortChannel, } from './host-toolbar-port-channel.js';
 import { parseRoute } from '../../../shared/simulator-route.js';
 import { HEADER_H, HOST_TOOLBAR_RUNTIME_MARKER } from '../../../shared/constants.js';
+import { reconcile, createInitialState } from '@dimina-kit/electron-deck/layout';
+import { applyViewOps } from './apply-view-ops.js';
+import { VIEW_ID, VIEW_LAYER } from '../../../shared/view-ids.js';
 /**
  * Resolve a DevTools source request against the service-host URL that created
  * the inspected app. Its pkgRoot is authoritative; the workspace is only a
@@ -46,6 +49,32 @@ export function resolveProjectEditorTarget(serviceHostUrl, activeProjectRoot, re
         column: typeof req.column === 'number' ? req.column + 1 : undefined,
     };
 }
+// `webContents.executeJavaScript()` registers a transient `did-stop-loading`
+// listener on the target wc whenever that wc is still loading (Electron's
+// `waitTillCanExecuteJavaScript` defers the eval until load finishes, then
+// removes the listener). The DevTools front-end host wc takes a burst of injects
+// during its boot window — tab customization, default-panel selection, the 150ms
+// Elements-forward reconcile, and Network-forward probing all call
+// `executeJavaScript()` on it before the front-end has finished loading — so the
+// pending listeners can transiently exceed Node's default EventEmitter ceiling
+// of 10 and print a spurious `MaxListenersExceededWarning: 11 did-stop-loading
+// listeners`. They drain once the wc stops loading; this is a boot-time
+// concurrency spike, not a per-event leak. Raise the ceiling on the DevTools
+// host wc, which we knowingly inject into repeatedly during its boot window, so
+// the benign spike stays quiet. (Confirmed at runtime: the tripped emitter is
+// this host wc's `did-stop-loading`, count 11 — see the `process.on('warning')`
+// diagnostic in app bootstrap.)
+const DEVTOOLS_HOST_EXEC_JS_MAX_LISTENERS = 50;
+function raiseExecuteJavaScriptListenerCeiling(wc) {
+    try {
+        if (wc.isDestroyed())
+            return;
+        if (wc.getMaxListeners() >= DEVTOOLS_HOST_EXEC_JS_MAX_LISTENERS)
+            return;
+        wc.setMaxListeners(DEVTOOLS_HOST_EXEC_JS_MAX_LISTENERS);
+    }
+    catch { /* torn-down / stub wc — best effort, warning is non-fatal */ }
+}
 /**
  * Build a ViewManager bound to the given context. The returned object is the
  * only component allowed to instantiate or add/remove overlay WebContentsViews.
@@ -69,12 +98,6 @@ export function createViewManager(ctx) {
     let nativeSimulatorViewAdded = false;
     let nativeSimulatorProjectPath = null;
     let settleNativeSimulatorReady = null;
-    // Model A: the renderer's measured inner-screen rect is the SOLE authority for
-    // the native simulator WCV bounds (see docs/simulator-render-architecture.md).
-    // Cache the last rect so a report that lands before attachNativeSimulator (the
-    // project-open ordering) is not lost — attach replays it instead of using a
-    // coarse panel-size fallback (which raced and caused the clip/surround flips).
-    let lastRendererRect = null;
     // NATIVE-HOST ONLY. The `ipcMain.on` listener that services the
     // `__diminaCustomApis` bridge for the current native simulator webContents
     // (see `attachNativeCustomApiBridge`). Tracked so we can remove it before
@@ -87,7 +110,6 @@ export function createViewManager(ctx) {
     // pick up the correct scale in `did-attach-webview`. Defaults to 1 (100%).
     let currentZoomFactor = 1;
     let settingsView = null;
-    let settingsViewAdded = false;
     let popoverView = null;
     let simulatorWebContentsId = null;
     // NATIVE-HOST ONLY. The webContents the right-panel Chrome DevTools front-end
@@ -111,17 +133,11 @@ export function createViewManager(ctx) {
     let stopServiceConsole = null;
     let nativeDevtoolsRetryTimer = null;
     let nativeDevtoolsRetryToken = 0;
-    // Renderer-driven overlay bounds for the simulator DevTools view — the SOLE
-    // mount/geometry authority (no static-layout fallback). A zero-area
-    // rectangle means "hide" — the overlay is removed from the contentView but
-    // its WebContents stays alive.
-    let simulatorBoundsOverride = null;
     // ── Embedded workbench editor WebContentsView ────────────────────────
     // The opt-in VS Code workbench hosting the 'editor' dock slot. Lazily created
     // by `attachWorkbench` from the COI server URL; its bounds ride the renderer
     // 'editor'-slot anchor (forward anchor, like the simulator DevTools overlay).
     let workbenchView = null;
-    let workbenchViewAdded = false;
     // Whether the devtools-theme → workbench-theme `nativeTheme` listener is live.
     // Bound lazily on first workbench attach, removed on detach.
     let workbenchThemeSyncBound = false;
@@ -178,37 +194,177 @@ export function createViewManager(ctx) {
         }
         catch { /* ignore */ }
     }
-    // Renderer publishes width/height = 0 to mean "hide overlay" — the
-    // surrounding React panel is unmounted/collapsed. We keep the cached
-    // value (so future republishes win over legacy layout) but remove the
-    // child view from the contentView until a non-empty rect arrives.
-    function isHidden(b) {
-        return b.width <= 0 || b.height <= 0;
+    // ── Placement reconciler ────────────────────────────────────────────────
+    // The main-process view tree is converged toward the renderer's declared
+    // placement by a level-triggered reconciler (docs/view-placement-reconciler.md).
+    // The renderer publishes a window-level snapshot into `baseDesired`;
+    // settings/popover are main-owned and live in `overlayDesired`. Any change
+    // merges the two, runs the pure reconcile core, and applies the ordered ops
+    // through `viewTarget`. `epochCounter` is a single monotonic tick — main is the
+    // only (serial) reconcile caller, so the core's stale guard passes by
+    // construction; `rendererGeneration` still drives the reset on renderer restart.
+    let placementState = createInitialState();
+    let epochCounter = 0;
+    let rendererGeneration = 0;
+    const baseDesired = new Map();
+    const overlayDesired = new Map();
+    // simulator / simulator-devtools WCVs are built by the project-open flow, not
+    // by an attach op; gate them hidden until they exist so the reconciler never
+    // records an attach that addChildView can't perform. The view-creation sites
+    // call reconcileNow() to re-open the gate. workbench is gated until it has a
+    // source or a live view (it lazy-creates from the URL in target.attach).
+    function gateReadiness(v) {
+        if (v.viewId === VIEW_ID.simulator && !nativeSimulatorView)
+            return { ...v, placement: { visible: false } };
+        if (v.viewId === VIEW_ID.simulatorDevtools && !simulatorView)
+            return { ...v, placement: { visible: false } };
+        if (v.viewId === VIEW_ID.workbench && !workbenchView && !workbenchUrl)
+            return { ...v, placement: { visible: false } };
+        return v;
     }
-    function setSimulatorDevtoolsBounds(bounds) {
-        simulatorBoundsOverride = bounds;
-        if (!simulatorView || simulatorView.webContents.isDestroyed())
-            return;
-        if (ctx.windows.mainWindow.isDestroyed())
-            return;
-        if (isHidden(bounds)) {
-            if (simulatorViewAdded) {
+    function resolveView(viewId) {
+        switch (viewId) {
+            case VIEW_ID.simulator: return nativeSimulatorView;
+            case VIEW_ID.simulatorDevtools: return simulatorView;
+            case VIEW_ID.workbench: return workbenchView;
+            case VIEW_ID.hostToolbar: return hostToolbarView;
+            case VIEW_ID.settings: return settingsView;
+            case VIEW_ID.popover: return popoverView;
+            default: return null;
+        }
+    }
+    function markAdded(viewId, added) {
+        switch (viewId) {
+            case VIEW_ID.simulator:
+                nativeSimulatorViewAdded = added;
+                break;
+            case VIEW_ID.simulatorDevtools:
+                simulatorViewAdded = added;
+                break;
+            case VIEW_ID.hostToolbar:
+                hostToolbarViewAdded = added;
+                break;
+            // popover has no added-flag (create == added).
+        }
+    }
+    // simulator zoom rides in `extra`: setBounds also drives the WCV zoomFactor and
+    // propagates it to nested render-host guests (from the old
+    // setNativeSimulatorViewBounds body).
+    function applyNativeSimulatorBounds(view, bounds, zoom) {
+        const p = layout.computeNativeSimulatorViewParams(bounds, zoom);
+        currentZoomFactor = p.zoomFactor;
+        view.setBounds(p.bounds);
+        const simWc = view.webContents;
+        if (!simWc.isDestroyed())
+            simWc.setZoomFactor(p.zoomFactor);
+        try {
+            for (const wc of webContents.getAllWebContents()) {
+                if (wc.isDestroyed())
+                    continue;
+                if (wc.hostWebContents === simWc)
+                    wc.setZoomFactor(p.zoomFactor);
+            }
+        }
+        catch { /* hostWebContents unavailable; guests get zoom on attach */ }
+    }
+    const viewTarget = {
+        attach(viewId) {
+            if (ctx.windows.mainWindow.isDestroyed())
+                return;
+            if (viewId === VIEW_ID.workbench && !workbenchView && workbenchUrl) {
+                // Lazy-load the workbench; attachWorkbench adds it + sets the flag.
+                void attachWorkbench(workbenchUrl);
+                return;
+            }
+            if (viewId === VIEW_ID.hostToolbar) {
+                const view = ensureHostToolbarView();
+                ctx.windows.mainWindow.contentView.addChildView(view);
+                hostToolbarViewAdded = true;
+                return;
+            }
+            const view = resolveView(viewId);
+            if (!view)
+                return;
+            ctx.windows.mainWindow.contentView.addChildView(view);
+            markAdded(viewId, true);
+        },
+        detach(viewId) {
+            const view = resolveView(viewId);
+            if (view && !ctx.windows.mainWindow.isDestroyed()) {
                 try {
-                    ctx.windows.mainWindow.contentView.removeChildView(simulatorView);
+                    ctx.windows.mainWindow.contentView.removeChildView(view);
                 }
                 catch { /* already removed */ }
-                simulatorViewAdded = false;
             }
-            return;
-        }
-        if (!simulatorViewAdded) {
-            ctx.windows.mainWindow.contentView.addChildView(simulatorView);
-            simulatorViewAdded = true;
-            // Re-attaching this base overlay moved it to the top of the z-stack; keep
-            // any open settings/popover above it.
-            raiseTopOverlays();
-        }
-        simulatorView.setBounds(bounds);
+            markAdded(viewId, false);
+        },
+        setBounds(viewId, bounds, extra) {
+            const view = resolveView(viewId);
+            if (!view || view.webContents.isDestroyed())
+                return;
+            if (viewId === VIEW_ID.simulator) {
+                applyNativeSimulatorBounds(view, bounds, extra?.zoom ?? 1);
+                return;
+            }
+            view.setBounds(bounds);
+        },
+        setVisible(viewId, visible) {
+            const view = resolveView(viewId);
+            if (!view)
+                return;
+            try {
+                view.setVisible(visible);
+            }
+            catch { /* stub may lack setVisible */ }
+        },
+        reorder(order) {
+            // A single attached view is already in place — nothing to reorder.
+            if (order.length <= 1 || ctx.windows.mainWindow.isDestroyed())
+                return;
+            const cv = ctx.windows.mainWindow.contentView;
+            for (const viewId of order) {
+                const view = resolveView(viewId);
+                if (view) {
+                    try {
+                        cv.addChildView(view);
+                    }
+                    catch { /* already attached */ }
+                }
+            }
+        },
+    };
+    // Create the lazily-built views (host-toolbar, workbench) BEFORE reconcile so
+    // the setBounds op — which the core emits before attach — lands on a live view
+    // rather than a not-yet-created one.
+    function ensureLazyViews() {
+        const ht = baseDesired.get(VIEW_ID.hostToolbar);
+        if (ht?.placement.visible && !liveHostToolbarWebContents())
+            ensureHostToolbarView();
+        const wb = baseDesired.get(VIEW_ID.workbench);
+        if (wb?.placement.visible && !workbenchView && workbenchUrl)
+            void attachWorkbench(workbenchUrl);
+    }
+    function reconcileNow() {
+        ensureLazyViews();
+        const views = [];
+        for (const v of baseDesired.values())
+            views.push(gateReadiness(v));
+        for (const v of overlayDesired.values())
+            views.push(v);
+        const result = reconcile(placementState, {
+            generation: rendererGeneration,
+            epoch: ++epochCounter,
+            views,
+        });
+        placementState = result.state;
+        applyViewOps(result.ops, viewTarget);
+    }
+    function setPlacementSnapshot(snapshot) {
+        rendererGeneration = snapshot.generation;
+        baseDesired.clear();
+        for (const v of snapshot.views)
+            baseDesired.set(v.viewId, v);
+        reconcileNow();
     }
     // ── Embedded workbench editor WebContentsView ────────────────────────
     /** Current devtools color scheme, mirrored into the workbench's theme. */
@@ -257,9 +413,6 @@ export function createViewManager(ctx) {
         }
         catch { /* stub may lack it */ }
         ctx.windows.mainWindow.contentView.addChildView(view);
-        workbenchViewAdded = true;
-        // Keep settings/popover above the freshly-added base overlay.
-        raiseTopOverlays();
         // Hand the workbench the current devtools scheme as a URL query so its very
         // first paint already matches (the runtime setter only exists post-init).
         const loadUrl = `${url}index.html?theme=${workbenchThemeScheme()}`;
@@ -271,40 +424,6 @@ export function createViewManager(ctx) {
     function setWorkbenchSource(url) {
         workbenchUrl = url;
     }
-    function setWorkbenchBounds(bounds) {
-        if (ctx.windows.mainWindow.isDestroyed())
-            return;
-        // Zero-area rect means "hide" — remove the child view but keep its
-        // WebContents (and the workbench's loaded state) alive. Never triggers the
-        // lazy load: a hidden slot must not pull the workbench onto screen.
-        if (isHidden(bounds)) {
-            if (workbenchView && workbenchViewAdded && !workbenchView.webContents.isDestroyed()) {
-                try {
-                    ctx.windows.mainWindow.contentView.removeChildView(workbenchView);
-                }
-                catch { /* already removed */ }
-                workbenchViewAdded = false;
-            }
-            return;
-        }
-        // First time the 'editor' slot becomes visible: lazily create + load the
-        // workbench (off the boot critical path). attachWorkbench assigns
-        // workbenchView + addChildView synchronously, so bounds apply immediately
-        // while the bundle loads in the background.
-        if (!workbenchView && workbenchUrl) {
-            void attachWorkbench(workbenchUrl);
-        }
-        if (!workbenchView || workbenchView.webContents.isDestroyed())
-            return;
-        if (!workbenchViewAdded) {
-            ctx.windows.mainWindow.contentView.addChildView(workbenchView);
-            workbenchViewAdded = true;
-            // Re-attaching this base overlay moved it to the top of the z-stack; keep
-            // any open settings/popover above it.
-            raiseTopOverlays();
-        }
-        workbenchView.setBounds(bounds);
-    }
     function detachWorkbench() {
         if (workbenchThemeSyncBound) {
             nativeTheme.removeListener('updated', pushWorkbenchTheme);
@@ -312,7 +431,8 @@ export function createViewManager(ctx) {
         }
         destroyViewInternal(workbenchView);
         workbenchView = null;
-        workbenchViewAdded = false;
+        baseDesired.delete(VIEW_ID.workbench);
+        reconcileNow();
     }
     // Build the `file:///workspace/<rel>` URI string with each path SEGMENT
     // percent-encoded. A raw `rel` passed to `vscode.Uri.parse` mis-parses a
@@ -412,6 +532,9 @@ export function createViewManager(ctx) {
             catch { /* already removed */ }
             hostToolbarViewAdded = false;
         }
+        // The instance is being replaced — forget its reconciled mount state so the
+        // rebuilt view is treated as a fresh attach (not skipped as already-attached).
+        placementState.actual.delete(VIEW_ID.hostToolbar);
         // The framework's height-advertiser runtime is SESSION-resident: register
         // it on session.defaultSession (ref-counted across coexisting managers)
         // BEFORE the view exists, so the very first load already runs it. The
@@ -457,31 +580,6 @@ export function createViewManager(ctx) {
         catch { /* stub may lack it */ }
         return view;
     }
-    function setHostToolbarBounds(bounds) {
-        if (ctx.windows.mainWindow.isDestroyed())
-            return;
-        // Zero-area rect means "hide" — remove the child view but keep its
-        // WebContents (and the host's loaded content) alive. Do NOT create the
-        // view just to immediately hide it.
-        if (isHidden(bounds)) {
-            if (hostToolbarView && hostToolbarViewAdded && liveHostToolbarWebContents()) {
-                try {
-                    ctx.windows.mainWindow.contentView.removeChildView(hostToolbarView);
-                }
-                catch { /* already removed */ }
-            }
-            hostToolbarViewAdded = false;
-            return;
-        }
-        const view = ensureHostToolbarView();
-        if (!hostToolbarViewAdded) {
-            // addChildView appends = topmost z-order, which is correct for a strip
-            // that sits above the devtools header.
-            ctx.windows.mainWindow.contentView.addChildView(view);
-            hostToolbarViewAdded = true;
-        }
-        view.setBounds(bounds);
-    }
     // Single funnel for the height notify: retain-then-push, so the retained
     // value is exactly the last value the renderer was told. Every height
     // notify site MUST go through here — the renderer pulls the retained value
@@ -490,9 +588,9 @@ export function createViewManager(ctx) {
     function notifyHostToolbarHeight(height) {
         hostToolbarLastHeight = height;
         ctx.notify.hostToolbarHeightChanged(height);
-        if (settingsViewAdded)
+        if (overlayDesired.has(VIEW_ID.settings))
             applySettingsBounds();
-        if (popoverView)
+        if (overlayDesired.has(VIEW_ID.popover))
             applyPopoverBounds();
     }
     function setHostToolbarHeight(extent) {
@@ -512,13 +610,12 @@ export function createViewManager(ctx) {
         notifyHostToolbarHeight(extent);
     }
     function hideHostToolbar() {
-        if (hostToolbarView && hostToolbarViewAdded && !ctx.windows.mainWindow.isDestroyed()) {
-            try {
-                ctx.windows.mainWindow.contentView.removeChildView(hostToolbarView);
-            }
-            catch { /* already removed */ }
-        }
-        hostToolbarViewAdded = false;
+        baseDesired.set(VIEW_ID.hostToolbar, {
+            viewId: VIEW_ID.hostToolbar,
+            placement: { visible: false },
+            layer: VIEW_LAYER.hostToolbar,
+        });
+        reconcileNow();
         // Collapse the renderer placeholder to 0 too. Otherwise its anchor keeps a
         // non-zero reserved height and re-publishes bounds on the next window
         // resize, silently re-adding the view we just hid (unstable hide). Zeroing
@@ -590,17 +687,36 @@ export function createViewManager(ctx) {
     function overlayHeaderHeight() {
         return HEADER_H + hostToolbarLastHeight;
     }
+    // settings/popover bounds are main-computed; publish them into overlayDesired
+    // and let the reconciler place them (they are top-tier layers, so a reorder
+    // keeps them above every base overlay — the old raiseTopOverlays is gone).
     function applySettingsBounds() {
         if (!settingsView || ctx.windows.mainWindow.isDestroyed())
             return;
         const [w = 0, h = 0] = ctx.windows.mainWindow.getContentSize();
-        settingsView.setBounds(layout.computeSettingsBounds(w, h, overlayHeaderHeight()));
+        overlayDesired.set(VIEW_ID.settings, {
+            viewId: VIEW_ID.settings,
+            placement: {
+                visible: true,
+                bounds: layout.computeSettingsBounds(w, h, overlayHeaderHeight()),
+            },
+            layer: VIEW_LAYER.settings,
+        });
+        reconcileNow();
     }
     function applyPopoverBounds() {
         if (!popoverView || ctx.windows.mainWindow.isDestroyed())
             return;
         const [w = 0, h = 0] = ctx.windows.mainWindow.getContentSize();
-        popoverView.setBounds(layout.computePopoverBounds(w, h, overlayHeaderHeight()));
+        overlayDesired.set(VIEW_ID.popover, {
+            viewId: VIEW_ID.popover,
+            placement: {
+                visible: true,
+                bounds: layout.computePopoverBounds(w, h, overlayHeaderHeight()),
+            },
+            layer: VIEW_LAYER.popover,
+        });
+        reconcileNow();
     }
     function clearNativeDevtoolsRetry() {
         nativeDevtoolsRetryToken++;
@@ -736,7 +852,7 @@ export function createViewManager(ctx) {
             ctx.notify.editorOpenFile(target);
         };
         serviceWc.on('devtools-open-url', onOpenUrl);
-        // Consolidate teardown onto the connection layer (foundation.md §4 / P2),
+        // Consolidate teardown onto the connection layer,
         // but as a wc-LIFETIME resource: the open-in-editor wiring inspects this
         // service-host wc and must SURVIVE pool reuse (`reset`) — the dedup set
         // entry + listener stay valid across sessions reusing the same wc, and the
@@ -871,6 +987,11 @@ export function createViewManager(ctx) {
         // request the `console` view, and also persist the choice via the
         // `panel-selectedTab` localStorage key so subsequent reloads honor it.
         const devtoolsWc = simulatorView.webContents;
+        // The boot-time burst of `executeJavaScript()` injects on this host wc (tab
+        // customization / console default / Elements+Network forwarding below) each
+        // queue a pending `did-stop-loading` waiter while the front-end is still
+        // loading (see raiseExecuteJavaScriptListenerCeiling).
+        raiseExecuteJavaScriptListenerCeiling(devtoolsWc);
         // Hand the network forwarder THIS front-end host wc — it injects the
         // simulator WCV's Network.* CDP events into `window.DevToolsAPI.dispatchMessage`
         // here so the native Network tab renders them (falls back to the service-host
@@ -936,11 +1057,9 @@ export function createViewManager(ctx) {
         // unadded and unsized until the first publish arrives. No static-layout
         // fallback — an attach-time computed rect raced the precise anchor rect
         // and flashed the overlay at the wrong rectangle.
-        if (simulatorBoundsOverride && !isHidden(simulatorBoundsOverride)) {
-            ctx.windows.mainWindow.contentView.addChildView(simulatorView);
-            simulatorViewAdded = true;
-            simulatorView.setBounds(simulatorBoundsOverride);
-        }
+        // The view now exists: re-run the reconciler so a placement published before
+        // this attach (project-open ordering) attaches it once the gate re-opens.
+        reconcileNow();
         if (ctx.bridge?.isNativeHost()) {
             unsubscribeNativeRenderEvents = ctx.bridge.onRenderEvent(onNativeRenderEvent);
             followNativeDevtoolsServiceHost();
@@ -988,6 +1107,8 @@ export function createViewManager(ctx) {
         catch { /* ignore */ }
         nativeSimulatorView = null;
         nativeSimulatorViewAdded = false;
+        // The view is gone: gateReadiness now hides it, so reconcile detaches it.
+        reconcileNow();
     }
     /**
      * NATIVE-HOST ONLY. The native simulator is a top-level WebContentsView with
@@ -1033,8 +1154,8 @@ export function createViewManager(ctx) {
         };
         nativeCustomApiBridgeHandler = handler;
         ipcMain.on(SimulatorCustomApiBridgeChannel.Request, handler);
-        // Consolidate this per-webContents teardown onto the connection layer
-        // (foundation.md §4 / P1 DoD #3): acquiring the simWc connection makes the
+        // Consolidate this per-webContents teardown onto the connection layer:
+        // acquiring the simWc connection makes the
         // registry track this trusted webContents, and `own()`-ing the detach ties
         // the ipcMain listener's lifetime to the connection so it's torn down
         // deterministically when the wc is destroyed (or the connection is reset),
@@ -1063,8 +1184,8 @@ export function createViewManager(ctx) {
             settleNativeSimulatorReady = resolve;
         });
         // Derive THIS project's session partition from the simulator URL's appId so
-        // its cookies/localStorage/cache are isolated from every other project (P0
-        // debt). Same project → same partition (storage survives a relaunch);
+        // its cookies/localStorage/cache are isolated from every other project.
+        // Same project → same partition (storage survives a relaunch);
         // unknown appId → the shared fallback. Configure the partition's session
         // (protocol handlers + CORS/referer policy) before any project content loads
         // on it — idempotent per partition.
@@ -1233,13 +1354,11 @@ export function createViewManager(ctx) {
         // embedded DevTools the right panel hosts. Attaches the CDP debugger; no-op
         // if the forwarder is unwired (partial test ctx) or the debugger is claimed.
         ctx.networkForward?.attachSimulator(simWc);
-        // Model A: bounds come ONLY from the renderer's measured inner-screen rect.
-        // If a report already landed before this attach (project-open ordering),
-        // replay it now — setNativeSimulatorViewBounds adds + sizes the view. Else
-        // the view stays unadded until the next reportBounds. No coarse fallback.
-        if (lastRendererRect) {
-            setNativeSimulatorViewBounds(lastRendererRect);
-        }
+        // Model A: bounds come ONLY from the renderer's window-level placement
+        // snapshot. The view now exists, so re-reconcile: gateReadiness admits the
+        // simulator (gated hidden while its WCV was absent) and the latest desired
+        // placement attaches + sizes it. Until the next snapshot it stays unadded.
+        reconcileNow();
         // Native-host page code (console.log / wx.request / Sources) runs in the
         // hidden SERVICE HOST window, not this DeviceShell host nor the render-host
         // guests. Keep the right-panel DevTools host view stable and point it at the
@@ -1277,19 +1396,11 @@ export function createViewManager(ctx) {
         // Drop the settings view too — the previous detachAllViews() did.
         destroyViewInternal(settingsView);
         settingsView = null;
-        settingsViewAdded = false;
         destroyViewInternal(simulatorView);
         simulatorView = null;
         simulatorViewAdded = false;
         simulatorWebContentsId = null;
         nativeSimulatorProjectPath = null;
-        // Drop the renderer-published rect so a stale "hidden" override doesn't
-        // suppress the next view before its renderer republishes.
-        simulatorBoundsOverride = null;
-        // Also drop the cached native-simulator rect: attachNativeSimulator replays
-        // lastRendererRect on attach, so a leftover rect/offset from a torn-down
-        // session must not be replayed onto a fresh re-attach (stale slice/offset).
-        lastRendererRect = null;
     }
     // Remove (but do not destroy) the DevTools overlay from the contentView.
     // Internal teardown helper for re-attach; user-facing visibility is the
@@ -1325,39 +1436,11 @@ export function createViewManager(ctx) {
             settingsView.setBackgroundColor('#00000000');
             await settingsView.webContents.loadFile(path.join(ctx.rendererDir, 'entries/settings/index.html'));
         }
-        if (!settingsViewAdded) {
-            ctx.windows.mainWindow.contentView.addChildView(settingsView);
-            settingsViewAdded = true;
-        }
         applySettingsBounds();
     }
     function hideSettings() {
-        if (settingsView && settingsViewAdded) {
-            try {
-                ctx.windows.mainWindow.contentView.removeChildView(settingsView);
-            }
-            catch { /* ignore */ }
-            settingsViewAdded = false;
-        }
-    }
-    // Keep the TOP-tier overlays (settings, popover) above the BASE-tier native
-    // overlays (the native simulator WCV + the console/DevTools WCV). Native
-    // overlays are z-ordered by `addChildView` insertion order — the last-added
-    // sits on top — so RE-attaching a base overlay while a top overlay is open
-    // (e.g. the simulator re-shows on a tab switch, or the console bounds
-    // republish re-adds it) would move the base ABOVE the open settings/popover
-    // and occlude it. Whenever a base overlay is (re)added, re-append the open top
-    // overlays so they stay on top. Settings is re-appended before popover so a
-    // simultaneously-open popover ends up topmost. A no-op when neither is open
-    // (pinned by the z-order guard test).
-    function raiseTopOverlays() {
-        if (ctx.windows.mainWindow.isDestroyed())
-            return;
-        const cv = ctx.windows.mainWindow.contentView;
-        if (settingsView && settingsViewAdded)
-            cv.addChildView(settingsView);
-        if (popoverView)
-            cv.addChildView(popoverView);
+        overlayDesired.delete(VIEW_ID.settings);
+        reconcileNow();
     }
     function showPopover(data) {
         hidePopover();
@@ -1373,7 +1456,6 @@ export function createViewManager(ctx) {
         applyNavigationHardening(popover.webContents, ctx.rendererDir);
         popoverView = popover;
         popover.setBackgroundColor('#00000000');
-        ctx.windows.mainWindow.contentView.addChildView(popover);
         applyPopoverBounds();
         popover.webContents.once('did-finish-load', () => {
             ctx.notify.popoverInit(popover, data);
@@ -1381,19 +1463,23 @@ export function createViewManager(ctx) {
         popover.webContents.loadFile(path.join(ctx.rendererDir, 'entries/popover/index.html'));
     }
     function hidePopover() {
-        if (popoverView) {
-            destroyViewInternal(popoverView);
-            popoverView = null;
-            ctx.notify.popoverClosed();
-        }
+        if (!popoverView)
+            return;
+        overlayDesired.delete(VIEW_ID.popover);
+        // Destroy the WCV first (removeChildView + close), THEN reconcile: the detach
+        // op then finds the view already gone and does not double-removeChildView.
+        destroyViewInternal(popoverView);
+        popoverView = null;
+        reconcileNow();
+        ctx.notify.popoverClosed();
     }
     function repositionAll() {
         // Simulator + DevTools overlay: bounds owned by the renderer's anchor
         // publishes; their ResizeObserver/window-resize listeners re-measure, so
         // no static re-apply here.
-        if (settingsView && settingsViewAdded)
+        if (overlayDesired.has(VIEW_ID.settings))
             applySettingsBounds();
-        if (popoverView)
+        if (overlayDesired.has(VIEW_ID.popover))
             applyPopoverBounds();
     }
     function disposeAll() {
@@ -1420,63 +1506,11 @@ export function createViewManager(ctx) {
         }
         safeArea.dispose();
     }
-    function setNativeSimulatorViewBounds(params) {
-        // Cache unconditionally so attachNativeSimulator can replay a report that
-        // landed before the view existed (project-open ordering). This rect is the
-        // ONLY authority for the native WCV bounds.
-        lastRendererRect = params;
-        if (ctx.windows.mainWindow.isDestroyed() || !nativeSimulatorView)
-            return;
-        const p = layout.computeNativeSimulatorViewParams(params, params.zoom);
-        currentZoomFactor = p.zoomFactor;
-        // A zero-area rect means "hide" — the renderer reports this when the
-        // simulator panel/cell is toggled off or unmounts (toolbar toggle only
-        // mutates renderer layout state, so without this the WCV would stay
-        // painted over its old region). Mirror `setSimulatorDevtoolsBounds`:
-        // remove the child view from the contentView but keep its WebContents
-        // alive, so re-showing doesn't re-pay the simulator bootstrap.
-        if (isHidden(p.bounds)) {
-            if (nativeSimulatorViewAdded) {
-                try {
-                    ctx.windows.mainWindow.contentView.removeChildView(nativeSimulatorView);
-                }
-                catch { /* already removed */ }
-                nativeSimulatorViewAdded = false;
-            }
-            return;
-        }
-        if (!nativeSimulatorViewAdded) {
-            ctx.windows.mainWindow.contentView.addChildView(nativeSimulatorView);
-            nativeSimulatorViewAdded = true;
-            // Re-attaching this base overlay moved it to the top of the z-stack; keep
-            // any open settings/popover above it.
-            raiseTopOverlays();
-        }
-        nativeSimulatorView.setBounds(p.bounds);
-        const simWc = nativeSimulatorView.webContents;
-        if (!simWc.isDestroyed()) {
-            simWc.setZoomFactor(p.zoomFactor);
-        }
-        // Propagate zoom to any already-attached nested render-host guests so the
-        // page rescales live on zoom change (newly-attached guests get it in
-        // did-attach-webview). `webContents.getAllWebContents()` includes guests;
-        // filter to those hosted by this simulator wc.
-        try {
-            for (const wc of webContents.getAllWebContents()) {
-                if (wc.isDestroyed())
-                    continue;
-                if (wc.hostWebContents === simWc) {
-                    wc.setZoomFactor(p.zoomFactor);
-                }
-            }
-        }
-        catch { /* hostWebContents unavailable; guests get zoom on attach */ }
-    }
     function resize(_simWidth) {
         // Simulator + DevTools overlay bounds are owned solely by the renderer's
         // anchor publishes — its ResizeObserver/window-resize listeners re-measure
         // on this same resize. No static re-apply (it raced the precise rect).
-        if (settingsViewAdded)
+        if (overlayDesired.has(VIEW_ID.settings))
             applySettingsBounds();
     }
     return {
@@ -1520,15 +1554,12 @@ export function createViewManager(ctx) {
         },
         getHostToolbarWebContentsId: () => liveHostToolbarWebContents()?.id ?? null,
         getHostToolbarHeight: () => hostToolbarLastHeight,
-        setNativeSimulatorViewBounds,
         resize,
-        setSimulatorDevtoolsBounds,
+        setPlacementSnapshot,
         attachWorkbench,
         setWorkbenchSource,
-        setWorkbenchBounds,
         detachWorkbench,
         openFileInWorkbench,
-        setHostToolbarBounds,
         setHostToolbarHeight,
         hostToolbar,
     };