@dimina-kit/devtools 0.4.0-dev.20260828161241 → 0.4.0-dev.20260907055341

package/dist/main/services/safe-area/index.d.ts

@@ -2,14 +2,28 @@ import type { WebContents } from 'electron';
 import type { ConnectionRegistry } from '@dimina-kit/electron-deck/main';
 import type { NativeDeviceInfo } from '../../../shared/ipc-channels.js';
 import { type CdpSessionBroker } from '../cdp-session/index.js';
+/** What the guest's own page contributes to the inset policy: whether the
+ *  shell draws a tabBar under it, and whether it draws a navigation bar over
+ *  the notch for it. */
+export interface GuestPageInsetPolicy {
+    isTabPage: boolean;
+    isCustomNav: boolean;
+}
+/**
+ * Read a guest's inset policy off its render-host URL (`isTab`, `navStyle` —
+ * both written by `buildRenderHostDocumentUrl`). An unparseable URL degrades to
+ * the default-nav, non-tab policy rather than failing the attach.
+ */
+export declare function parseGuestPageInsetPolicy(src: string): GuestPageInsetPolicy;
 export interface SafeAreaController {
     /** Attach the debugger to a freshly-attached render-host guest and push the
-     *  current device's insets. `isTabPage` selects the bottom-inset policy (0 for
-     *  tab pages, the real inset for full-bleed non-tab pages). No-op (warn) if the
-     *  guest is already claimed by an external CDP client — env then stays 0. */
-    applyToGuest(guestWc: WebContents, device: NativeDeviceInfo | null, isTabPage: boolean): void;
+     *  current device's insets. `page` selects the top policy (real inset only for
+     *  a custom-nav page) and the bottom policy (0 for tab pages, the real inset
+     *  for full-bleed non-tab pages). No-op (warn) if the guest is already claimed
+     *  by an external CDP client — env then stays 0. */
+    applyToGuest(guestWc: WebContents, device: NativeDeviceInfo | null, page: GuestPageInsetPolicy): void;
     /** Re-push insets to every still-attached guest after a device change (each
-     *  guest keeps the page type it attached with). */
+     *  guest keeps the page policy it attached with). */
     reapplyAll(device: NativeDeviceInfo | null): void;
     /** Release this controller's session leases (teardown). Does not itself
      *  detach the shared debugger session — see cdp-session/index.ts. */

package/dist/main/services/safe-area/index.js

@@ -1,12 +1,37 @@
 import { createCdpSessionBroker } from '../cdp-session/index.js';
-function guestInsets(device, isTabPage) {
-    const top = device?.safeAreaInsets.top ?? 0;
+/**
+ * Read a guest's inset policy off its render-host URL (`isTab`, `navStyle` —
+ * both written by `buildRenderHostDocumentUrl`). An unparseable URL degrades to
+ * the default-nav, non-tab policy rather than failing the attach.
+ */
+export function parseGuestPageInsetPolicy(src) {
+    try {
+        const params = new URL(src).searchParams;
+        return {
+            isTabPage: params.get('isTab') === '1',
+            isCustomNav: params.get('navStyle') === 'custom',
+        };
+    }
+    catch {
+        return { isTabPage: false, isCustomNav: false };
+    }
+}
+function guestInsets(device, page) {
+    // Only a custom-nav (full-bleed) page borders the unsafe top zone; a
+    // default-nav page already starts below the shell nav bar, which covers the
+    // notch itself.
+    const top = page.isCustomNav ? (device?.safeAreaInsets.top ?? 0) : 0;
     // A tab page's content sits above the shell-drawn tabBar (which fills the
     // bottom safe area), so it never borders the bottom unsafe zone. A non-tab
     // page is full-bleed to the device bottom, so surface the real inset for its
     // own `env(safe-area-inset-bottom)` opt-in.
-    const bottom = isTabPage ? 0 : (device?.safeAreaInsets.bottom ?? 0);
-    return { top, topMax: top, right: 0, rightMax: 0, bottom, bottomMax: bottom, left: 0, leftMax: 0 };
+    const bottom = page.isTabPage ? 0 : (device?.safeAreaInsets.bottom ?? 0);
+    // Left/right come straight from the device (e.g. a landscape Dynamic Island
+    // rotates into a side notch) — unlike top/bottom they don't depend on page
+    // type, since neither shell chrome nor the tabBar reserves horizontal space.
+    const right = device?.safeAreaInsets.right ?? 0;
+    const left = device?.safeAreaInsets.left ?? 0;
+    return { top, topMax: top, right, rightMax: right, bottom, bottomMax: bottom, left, leftMax: left };
 }
 export function createSafeAreaController(options = {}) {
     // Own (and dispose on this controller's own dispose()) a private broker
@@ -17,10 +42,10 @@ export function createSafeAreaController(options = {}) {
     // passes one; falls back to a private instance so this module stays
     // independently testable/usable.
     const broker = options.broker ?? createCdpSessionBroker({ connections: options.connections });
-    // Each guest's page type, fixed for its life — tracked SEPARATELY from the
+    // Each guest's page policy, fixed for its life — tracked SEPARATELY from the
     // lease so a lost session (external detach) doesn't lose the policy: a
     // later `override`/`reapplyAll` can reacquire and keep applying the same
-    // isTabPage this guest attached with.
+    // policy this guest attached with.
     const pageType = new Map();
     // Current lease per guest, if any. Cleared (not just left stale) on
     // `lease.onDetach` — an external detach or a real Chrome DevTools window
@@ -39,7 +64,7 @@ export function createSafeAreaController(options = {}) {
         lease.onDetach(() => { leases.delete(wc); });
         return lease;
     }
-    function override(wc, device, isTabPage) {
+    function override(wc, device, page) {
         if (wc.isDestroyed())
             return;
         const lease = ensureLease(wc);
@@ -51,17 +76,17 @@ export function createSafeAreaController(options = {}) {
             return;
         }
         void lease
-            .send('Emulation.setSafeAreaInsetsOverride', { insets: guestInsets(device, isTabPage) })
+            .send('Emulation.setSafeAreaInsetsOverride', { insets: guestInsets(device, page) })
             .catch((err) => {
             console.warn('[safe-area] setSafeAreaInsetsOverride failed:', err instanceof Error ? err.message : err);
         });
     }
     return {
-        applyToGuest: (wc, device, isTabPage) => {
+        applyToGuest: (wc, device, page) => {
             if (!wc || wc.isDestroyed())
                 return;
             const isFirstTime = !pageType.has(wc);
-            pageType.set(wc, isTabPage);
+            pageType.set(wc, page);
             if (isFirstTime) {
                 const forget = () => { pageType.delete(wc); leases.delete(wc); };
                 if (options.connections) {
@@ -71,11 +96,11 @@ export function createSafeAreaController(options = {}) {
                     wc.once('destroyed', forget);
                 }
             }
-            override(wc, device, isTabPage);
+            override(wc, device, page);
         },
         reapplyAll: (device) => {
-            for (const [wc, isTabPage] of pageType)
-                override(wc, device, isTabPage);
+            for (const [wc, page] of pageType)
+                override(wc, device, page);
         },
         dispose: () => {
             // Release our leases only — the shared session's actual detach is the

package/dist/main/services/simulator/ui-extensions.d.ts

@@ -9,5 +9,13 @@ export interface SimulatorUiExtensionRegistry {
 export interface SimulatorUiExtensionRegistryOptions {
     loadSource?: (scriptPath: string) => Promise<string>;
 }
+/**
+ * The rules a registration has to satisfy on its own, with no window and no
+ * renderer involved: the id is a lookup key on both sides of the bridge, and
+ * the script is read straight from disk with no base to resolve against. They
+ * hold wherever a registration is accepted, so whoever accepts one first is
+ * where a host learns it is unusable.
+ */
+export declare function assertSimulatorUiExtensionShape(registration: SimulatorUiExtensionRegistration): void;
 export declare function createSimulatorUiExtensionRegistry(options?: SimulatorUiExtensionRegistryOptions): SimulatorUiExtensionRegistry;
 //# sourceMappingURL=ui-extensions.d.ts.map

package/dist/main/services/simulator/ui-extensions.js

@@ -2,17 +2,27 @@ import { readFile } from 'node:fs/promises';
 import { isAbsolute } from 'node:path';
 import { pathToFileURL } from 'node:url';
 const EXTENSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * The rules a registration has to satisfy on its own, with no window and no
+ * renderer involved: the id is a lookup key on both sides of the bridge, and
+ * the script is read straight from disk with no base to resolve against. They
+ * hold wherever a registration is accepted, so whoever accepts one first is
+ * where a host learns it is unusable.
+ */
+export function assertSimulatorUiExtensionShape(registration) {
+    if (!EXTENSION_ID_RE.test(registration.id)) {
+        throw new Error(`Invalid simulator UI extension id: "${registration.id}"`);
+    }
+    if (!isAbsolute(registration.rendererScriptPath)) {
+        throw new Error('Simulator UI extension rendererScriptPath must be absolute');
+    }
+}
 export function createSimulatorUiExtensionRegistry(options = {}) {
     const loadSource = options.loadSource ?? (scriptPath => readFile(scriptPath, 'utf8'));
     const entries = new Map();
     let active = null;
     function assertRegistration(registration) {
-        if (!EXTENSION_ID_RE.test(registration.id)) {
-            throw new Error(`Invalid simulator UI extension id: "${registration.id}"`);
-        }
-        if (!isAbsolute(registration.rendererScriptPath)) {
-            throw new Error('Simulator UI extension rendererScriptPath must be absolute');
-        }
+        assertSimulatorUiExtensionShape(registration);
         if (entries.has(registration.id)) {
             throw new Error(`Simulator UI extension "${registration.id}" is already registered`);
         }

package/dist/main/services/simulator-storage/index.d.ts

@@ -19,7 +19,7 @@
  *     opens one, the shared session detaches externally and events stop
  *     flowing until they close it.
  */
-import { type WebContents } from 'electron';
+import { type BrowserWindow, type WebContents } from 'electron';
 import { type ConnectionRegistry, type Disposable } from '@dimina-kit/electron-deck/main';
 import { type SyncStorageChange } from '../../../shared/ipc-channels.js';
 import { type SenderPolicy } from '../../utils/ipc-registry.js';
@@ -96,6 +96,17 @@ export interface SimulatorStorageOptions {
      * compile and behave unchanged, just without cross-module session sharing.
      */
     broker?: CdpSessionBroker;
+    /**
+     * Owning window (typically `mainWindow`). Scopes every simulator-webview
+     * discovery path (initial scan, `web-contents-created`, lazy re-find) to
+     * webviews that live inside THIS window — required in a multi-window
+     * workbench, where `webContents`/`app.on('web-contents-created')` are
+     * process-global and would otherwise let one window's instance attach to
+     * (and read/write through) another window's simulator. Optional so
+     * existing single-window callers/tests compile and keep their prior
+     * unscoped behavior.
+     */
+    window?: BrowserWindow;
 }
 export declare function setupSimulatorStorage(host: WebContents, options: SimulatorStorageOptions): SimulatorStorageHandle;
 //# sourceMappingURL=index.d.ts.map

package/dist/main/services/simulator-storage/index.js

@@ -25,6 +25,7 @@ import { SimulatorElementChannel, SimulatorStorageChannel, } from '../../../shar
 import { IpcRegistry } from '../../utils/ipc-registry.js';
 import { decodeStorageValue, encodeStorageValue, serviceStorage } from './service-storage-ops.js';
 import { createCdpSessionBroker } from '../cdp-session/index.js';
+import { windowHostsWebContents } from './window-scope.js';
 /** Async wx storage API names routed through the unified service-window store. */
 export const STORAGE_API_NAMES = new Set([
     'setStorage',
@@ -40,6 +41,17 @@ function isSimulatorWebview(wc) {
         return false;
     return wc.getURL().includes('simulator.html');
 }
+/**
+ * `win` undefined means no owning window was configured — the legacy
+ * unscoped behavior, kept so single-window callers/tests that don't pass
+ * `window` keep compiling and behaving unchanged. Every production call
+ * site (window-runtime-services.ts) always passes its window.
+ */
+function belongsToWindow(win, wc) {
+    if (!win)
+        return true;
+    return windowHostsWebContents(win, wc);
+}
 function safeOff(target, event, fn) {
     try {
         if (target.isDestroyed?.())
@@ -198,7 +210,7 @@ export function setupSimulatorStorage(host, options) {
     async function ensureAttached() {
         if (attachedWc && !attachedWc.isDestroyed())
             return;
-        const sim = findSimulatorWebContents();
+        const sim = findSimulatorWebContents(options.window);
         if (!sim)
             return;
         await attachToSim(sim);
@@ -392,7 +404,7 @@ export function setupSimulatorStorage(host, options) {
     // Attach to any simulator webview that already exists (project may have
     // been opened before this function runs).
     for (const wc of wcStatic.getAllWebContents()) {
-        if (isSimulatorWebview(wc)) {
+        if (isSimulatorWebview(wc) && belongsToWindow(options.window, wc)) {
             void attachToSim(wc);
             break;
         }
@@ -406,7 +418,7 @@ export function setupSimulatorStorage(host, options) {
         const sub = new DisposableRegistry();
         wcSubs.set(wc, sub);
         const onFinishLoad = () => {
-            if (isSimulatorWebview(wc))
+            if (isSimulatorWebview(wc) && belongsToWindow(options.window, wc))
                 void attachToSim(wc);
         };
         wc.on('did-finish-load', onFinishLoad);
@@ -455,7 +467,7 @@ export function setupSimulatorStorage(host, options) {
                 return null;
             return options.renderInspector.highlight(wc, sid);
         }
-        const sim = findSimulatorWebContents();
+        const sim = findSimulatorWebContents(options.window);
         if (!sim)
             return null;
         try {
@@ -474,7 +486,7 @@ export function setupSimulatorStorage(host, options) {
                 await options.renderInspector.unhighlight(wc);
             return;
         }
-        const sim = findSimulatorWebContents();
+        const sim = findSimulatorWebContents(options.window);
         if (!sim)
             return;
         try {
@@ -591,9 +603,12 @@ export function setupSimulatorStorage(host, options) {
 // bridge via executeJavaScript. Looked up independently from `attachedWc` so
 // it keeps working when the user opens Chrome DevTools and the storage
 // debugger detaches (debugger.attach is mutually exclusive with F12).
-function findSimulatorWebContents() {
+// Scoped to `win` for the same reason as the attach paths above — an
+// unscoped scan would resolve to whichever window's simulator comes first
+// in the process-global registry, not necessarily this instance's own.
+function findSimulatorWebContents(win) {
     for (const wc of wcStatic.getAllWebContents()) {
-        if (isSimulatorWebview(wc))
+        if (isSimulatorWebview(wc) && belongsToWindow(win, wc))
             return wc;
     }
     return null;

package/dist/main/services/simulator-storage/window-scope.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Window-ownership judgment for simulator webContents discovery.
+ *
+ * The workbench runs one `setupSimulatorStorage` instance per project
+ * window, but Electron's `webContents`/`app.on('web-contents-created')`
+ * APIs are process-global — every instance sees every window's webviews.
+ * Without this filter, whichever instance's scan/callback fires first wins
+ * the simulator it finds, so opening a second project window can steal the
+ * first window's already-attached simulator (its Storage panel then reads
+ * and writes the second project's partition).
+ *
+ * The ownership rule itself (does a webContents sit inside a window's own
+ * renderer, its `contentView` tree, or a `<webview>` guest embedded in
+ * either) is shared with dimina-electron-runtime's bridge router, which
+ * faces the identical process-global-vs-per-window problem for its IPC
+ * routing — so it's owned by @dimina-kit/electron-deck/main and re-exported
+ * here under the name this package's callers expect.
+ */
+export { windowHostsWebContents } from '@dimina-kit/electron-deck/main';
+//# sourceMappingURL=window-scope.d.ts.map

package/dist/main/services/simulator-storage/window-scope.js

@@ -0,0 +1,20 @@
+/**
+ * Window-ownership judgment for simulator webContents discovery.
+ *
+ * The workbench runs one `setupSimulatorStorage` instance per project
+ * window, but Electron's `webContents`/`app.on('web-contents-created')`
+ * APIs are process-global — every instance sees every window's webviews.
+ * Without this filter, whichever instance's scan/callback fires first wins
+ * the simulator it finds, so opening a second project window can steal the
+ * first window's already-attached simulator (its Storage panel then reads
+ * and writes the second project's partition).
+ *
+ * The ownership rule itself (does a webContents sit inside a window's own
+ * renderer, its `contentView` tree, or a `<webview>` guest embedded in
+ * either) is shared with dimina-electron-runtime's bridge router, which
+ * faces the identical process-global-vs-per-window problem for its IPC
+ * routing — so it's owned by @dimina-kit/electron-deck/main and re-exported
+ * here under the name this package's callers expect.
+ */
+export { windowHostsWebContents } from '@dimina-kit/electron-deck/main';
+//# sourceMappingURL=window-scope.js.map

package/dist/main/services/views/host-slot-port-channel.d.ts

@@ -50,13 +50,30 @@ import type { WebContents } from 'electron';
 export interface HostSlotMessageSubscription {
     dispose(): void;
 }
+/**
+ * Handle returned by `attach`, scoped to the ONE webContents it was made for.
+ * `dispose()` removes the listeners that `attach` installed on that wc and, if
+ * that wc still owns the live port, closes it. Idempotent, and never touches a
+ * successor's attachment: releasing a superseded wc leaves the current one
+ * delivering.
+ *
+ * The owner calls this when it replaces or destroys that wc, so the channel
+ * holds no main-side state for a webContents its owner has let go — the
+ * channel does not have to be the wc's sole owner for its listeners to be
+ * released on time.
+ */
+export interface HostSlotAttachment {
+    dispose(): void;
+}
 export interface HostSlotPortChannel {
     /**
      * Hook a freshly created slot webContents: registers the `did-finish-load`
-     * (per-load handshake) and `destroyed` (drop the live port) listeners via
-     * `wc.on(...)`. Call exactly once per wc, right after the view is created.
+     * (per-load handshake), `did-start-navigation` (document-replacing
+     * navigation) and `destroyed` (drop the live port) listeners via
+     * `wc.on(...)`. Call exactly once per wc, right after the view is created,
+     * and `dispose()` the returned handle when that wc is replaced or destroyed.
      */
-    attach(wc: WebContents): void;
+    attach(wc: WebContents): HostSlotAttachment;
     /**
      * Drop the live port NOW (close + clear): the document it belongs to is
      * being replaced. Called synchronously when the HOST initiates a

package/dist/main/services/views/host-slot-port-channel.js

@@ -165,7 +165,7 @@ export function createHostSlotPortChannel(opts) {
     }
     return {
         attach(wc) {
-            wc.on('did-finish-load', () => handshake(wc));
+            const onDidFinishLoad = () => handshake(wc);
             // Page-initiated navigation (location.href / reload): the document the
             // port lives in is being replaced — invalidate so send() reports false
             // through the navigation window instead of confirming delivery into a
@@ -178,7 +178,7 @@ export function createHostSlotPortChannel(opts) {
             //  - main frame only: an <iframe> navigating keeps the main document.
             // Reads the details object (electron >= 12 shape); falls back to the
             // deprecated positional args (`isInPlace` === details.isSameDocument).
-            wc.on('did-start-navigation', (details, _url, isInPlace, isMainFramePositional) => {
+            const onDidStartNavigation = (details, _url, isInPlace, isMainFramePositional) => {
                 if (activeWc !== wc)
                     return;
                 const isSameDocument = typeof details?.isSameDocument === 'boolean'
@@ -190,11 +190,39 @@ export function createHostSlotPortChannel(opts) {
                 if (isSameDocument || !isMainFrame)
                     return;
                 dropActivePort(true, 'awaitingHandshake');
-            });
-            wc.on('destroyed', () => {
+            };
+            const onDestroyed = () => {
                 if (activeWc === wc)
                     dropActivePort(true, 'absent');
-            });
+            };
+            wc.on('did-finish-load', onDidFinishLoad);
+            wc.on('did-start-navigation', onDidStartNavigation);
+            wc.on('destroyed', onDestroyed);
+            let released = false;
+            return {
+                dispose() {
+                    if (released)
+                        return;
+                    released = true;
+                    // This wc is going away: if it still owns the live port, the
+                    // document that port belongs to is going with it, so close it and
+                    // let send() report false. A superseded wc owns nothing — the
+                    // successor's port is untouched.
+                    if (activeWc === wc)
+                        dropActivePort(true, 'absent');
+                    // A destroyed webContents still carries its JS-side emitter, so the
+                    // removals below are meaningful on both live and dead wcs; the
+                    // try/catch only covers hosts that reject the call outright.
+                    try {
+                        wc.off('did-finish-load', onDidFinishLoad);
+                        wc.off('did-start-navigation', onDidStartNavigation);
+                        wc.off('destroyed', onDestroyed);
+                    }
+                    catch {
+                        /* wc already gone; its listeners went with it */
+                    }
+                },
+            };
         },
         invalidate() {
             dropActivePort(true, 'awaitingHandshake');

package/dist/main/services/views/managed-web-contents-view.js

@@ -4,6 +4,18 @@ export function createManagedWebContentsView(opts) {
     let view = null;
     let preloadOverride = null;
     let runtimeAcquired = false;
+    /** The channel attachment for the CURRENT wc; released when that wc is replaced or destroyed. */
+    let attachment = null;
+    /**
+     * Hand the channel back the wc this manager is done with. This manager owns
+     * the wc's whole life, so it is the only thing that knows the wc is gone;
+     * without this the channel would keep listeners on a webContents nobody can
+     * reach any more.
+     */
+    function releaseAttachment() {
+        attachment?.dispose();
+        attachment = null;
+    }
     function liveWebContents() {
         const wc = view?.webContents;
         if (!wc || wc.isDestroyed())
@@ -22,6 +34,7 @@ export function createManagedWebContentsView(opts) {
         if (view !== current)
             return;
         console.error(`[${opts.viewId}] ${detail} — destroying so the next ensureView() rebuilds`);
+        releaseAttachment();
         view = null;
         opts.reconciler.destroyView(opts.viewId, current);
         opts.onBroken?.();
@@ -30,6 +43,10 @@ export function createManagedWebContentsView(opts) {
         if (view && liveWebContents()) {
             return view;
         }
+        // The outgoing wc (if any) is about to be destroyed, so its attachment
+        // goes first — a wc this manager no longer owns must not keep the channel
+        // wired to it.
+        releaseAttachment();
         if (view) {
             opts.reconciler.destroyView(opts.viewId, view);
         }
@@ -48,7 +65,7 @@ export function createManagedWebContentsView(opts) {
         }
         const next = new WebContentsView({ webPreferences });
         view = next;
-        opts.port.attach(next.webContents);
+        attachment = opts.port.attach(next.webContents);
         try {
             next.setBackgroundColor('#121212');
         }
@@ -105,6 +122,9 @@ export function createManagedWebContentsView(opts) {
             // registry, so a send() racing teardown reports false instead of posting
             // into a wc that is about to be closed.
             opts.port.dispose();
+            // Then hand back the wc itself, so no listener rests on a webContents
+            // this manager is about to close.
+            releaseAttachment();
             // Host-controllable slot view: removed from the contentView + its
             // WebContents closed (the host's loaded content is torn down on app exit).
             opts.reconciler.destroyView(opts.viewId, view);

package/dist/main/services/views/native-simulator-view.js

@@ -5,6 +5,7 @@ import { handleWindowOpenExternal } from '../../windows/navigation-hardening.js'
 import { SimulatorCustomApiBridgeChannel } from '../../../shared/ipc-channels.js';
 import * as layout from '../layout/index.js';
 import { handleCustomApiBridgeRequest, } from '../simulator/custom-apis.js';
+import { parseGuestPageInsetPolicy } from '../safe-area/index.js';
 import { configureMiniappSession, miniappPartition } from './miniapp-partition.js';
 import { refreshGuestStylesheets } from './refresh-styles.js';
 import { parseRoute } from '../../../shared/simulator-route.js';
@@ -230,27 +231,23 @@ export function createNativeSimulatorView(ctx, reconciler, deps) {
         // them with contextIsolation/sandbox off so the render runtime + its preload
         // share the page realm. (A top-level WebContentsView can host these guests; a
         // `<webview>` guest cannot — that's the whole point of Option A.)
-        // Page type (`isTab`) of each attaching guest, captured from its render-host
-        // URL in will-attach (where `params.src` carries the full URL) and consumed
-        // FIFO in the matching did-attach — `guestWc.getURL()` is still empty there.
+        // Inset policy (`isTab`, `navStyle`) of each attaching guest, captured from
+        // its render-host URL in will-attach (where `params.src` carries the full
+        // URL) and consumed FIFO in the matching did-attach — `guestWc.getURL()` is
+        // still empty there.
         // Per-attach scope: a fresh simWc + handlers are built on every (re)attach.
         // (The guest's `bgColor` query param — WeChat/Android/Harmony white-flash
         // parity — is consumed entirely outside main: device-shell.tsx's `<webview>`
         // CSS background and render-host/preload.cjs both read it directly, since
         // `WebContents` has no `setBackgroundColor` for main to call here.)
-        const pendingGuestIsTab = [];
+        const pendingGuestPages = [];
         simWc.on('will-attach-webview', (_event, webPreferences, params) => {
             ;
             webPreferences.partition = partition;
             params.partition = partition;
             webPreferences.contextIsolation = false;
             webPreferences.sandbox = false;
-            let isTab = false;
-            try {
-                isTab = new URL(params.src).searchParams.get('isTab') === '1';
-            }
-            catch { /* keep false */ }
-            pendingGuestIsTab.push(isTab);
+            pendingGuestPages.push(parseGuestPageInsetPolicy(params.src));
         });
         simWc.on('did-attach-webview', (_event, guestWc) => {
             // Scale the nested render-host page with the device zoom. The host WCV is
@@ -264,13 +261,13 @@ export function createNativeSimulatorView(ctx, reconciler, deps) {
             }
             catch { /* guest not ready; setNativeSimulatorViewBounds re-applies */ }
             // Simulate this device's CSS env(safe-area-inset-*) on the fresh guest
-            // before it paints, so notch-aware page layout resolves correctly. The
-            // bottom inset is page-type-dependent (see services/safe-area): a tab
-            // page's content sits above the shell tabBar (bottom 0); a non-tab page
-            // is full-bleed (real bottom inset). The page type was captured from the
+            // before it paints, so notch-aware page layout resolves correctly. Both
+            // the top and the bottom inset depend on the page (see services/safe-area):
+            // only a custom-nav page borders the unsafe top zone, and only a non-tab
+            // page borders the bottom one. The policy was captured from the
             // render-host URL in will-attach (FIFO).
-            const isTabGuest = pendingGuestIsTab.shift() ?? false;
-            safeArea.applyToGuest(guestWc, ctx.bridge?.getDevice() ?? null, isTabGuest);
+            const guestPage = pendingGuestPages.shift() ?? { isTabPage: false, isCustomNav: false };
+            safeArea.applyToGuest(guestWc, ctx.bridge?.getDevice() ?? null, guestPage);
             // Page-level resource loads (images/fonts/page fetch) run in THIS guest's
             // network stack, never the simulator's — without this, only wx.request
             // (forwarded to the simulator) shows in the Network panel and everything

package/dist/main/services/views/overlay-panels-view.d.ts

@@ -16,6 +16,10 @@ export interface ProjectCreateShowPayload {
     templates: unknown[];
     defaultBaseDir: string;
 }
+/** Payload shown by the device-picker overlay panel (`devicePicker:show`). */
+export interface DevicePickerShowPayload {
+    deviceName: string;
+}
 /**
  * The main-owned overlay panels: the settings sheet (right-side panel over a
  * transparent backdrop), the transient compile-mode popover, and the tooltip.
@@ -65,8 +69,17 @@ export interface OverlayPanelsView {
     hideUpdateDialog(): void;
     /** Forward a download-progress tick into the (already-shown) update overlay. */
     notifyUpdateDownloadProgress(percent: number): void;
+    /**
+     * Show the simulator toolbar's device picker (VIEW_LAYER.dialog). Same
+     * reason as `showProjectCreateDialog`: the simulator WCV overlaps the
+     * centred search panel, so it cannot be a DOM dialog in the toolbar's own
+     * renderer.
+     */
+    showDevicePicker(data: DevicePickerShowPayload): void;
+    hideDevicePicker(): void;
     getProjectCreateDialogWebContentsId(): number | null;
     getUpdateDialogWebContentsId(): number | null;
+    getDevicePickerWebContentsId(): number | null;
 }
 export declare function createOverlayPanelsView(ctx: ViewManagerContext, reconciler: PlacementReconciler, deps: {
     /** The host-toolbar strip height that offsets the overlay top edge. */