@dimina-kit/devtools 0.3.2-dev.20260611135124 → 0.4.0-dev.20260612152115

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

@@ -58,17 +58,26 @@ const API_CALL_TIMEOUT_MS = 5_000;
  * rather than assuming a single session.
  */
 function resolveCurrentApp(state, ctx, appId) {
+    // Same-appId matches prefer the MOST RECENT spawn (Maps preserve insertion
+    // order): after a respawn/reopen the newest session is the live one — the
+    // first match could be a just-superseded session mid-teardown.
     if (appId) {
+        let match;
         for (const ap of state.appSessions.values())
             if (ap.appId === appId)
-                return ap;
+                match = ap;
+        if (match)
+            return match;
     }
     const appInfo = ctx.workspace?.getSession?.()?.appInfo;
     const activeAppId = appInfo?.appId;
     if (activeAppId) {
+        let match;
         for (const ap of state.appSessions.values())
             if (ap.appId === activeAppId)
-                return ap;
+                match = ap;
+        if (match)
+            return match;
     }
     // Maps preserve insertion order; the last entry is the most recent spawn.
     let last;
@@ -87,6 +96,12 @@ export function installBridgeRouter(ctx) {
         emitRenderEvent: () => { },
         connections: ctx.connections,
         debugTap: createDebugTap({ enabled: resolveDebugTapEnabled() }),
+        evictAppDataBridges: (ap) => {
+            if (!ctx.appData)
+                return;
+            for (const page of ap.pages.values())
+                ctx.appData.evictBridge(ap.appId, page.bridgeId);
+        },
     };
     // Opt-in (default OFF) pre-warm pool for service-host windows. When enabled,
     // handleSpawn acquires a warm window instead of constructing one per spawn.
@@ -298,12 +313,8 @@ export function installBridgeRouter(ctx) {
             console.warn(`[bridge-router] DISPOSE rejected: sender belongs to ${senderApp.appSessionId}, target ${target.appSessionId}`);
             return;
         }
-        // Native-host AppData: clear the app's accumulated bridges so a re-opened
-        // project doesn't show ghost tabs from the prior session.
-        if (ctx.appData) {
-            for (const page of target.pages.values())
-                ctx.appData.evictBridge(target.appId, page.bridgeId);
-        }
+        // AppData bridge eviction happens inside disposeAppSession (single
+        // chokepoint shared with the simulator-WCV 'destroyed' path).
         void disposeAppSession(state, target.appSessionId);
     };
     ipcMain.on(C.DISPOSE, onDispose);
@@ -517,6 +528,19 @@ async function handleSpawn(state, ctx, event, opts) {
     };
     appSession.onServiceClosed = onServiceClosed;
     serviceWindow.once('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
+    // to send its graceful `C.DISPOSE`, so without this hook the app session and
+    // its hidden service-host window leak, and `resolveCurrentApp` keeps
+    // resolving the STALE session for the same appId: `getActiveRenderWc` then
+    // dereferences dead pages and every panel pull (WXML/elements) returns null
+    // for the whole next session. Disposing here is idempotent with the graceful
+    // path (`disposeAppSession` early-returns once the session is gone).
+    const onSimulatorDestroyed = () => {
+        void disposeAppSession(state, appSessionId);
+    };
+    simulatorWc.once('destroyed', onSimulatorDestroyed);
     if (usedPool) {
         // A pooled/fallback window passes through about:blank (warm load or the
         // fallback's initial load). Boot only once the REAL service.html navigation
@@ -1144,6 +1168,9 @@ async function disposeAppSession(state, appSessionId, opts = {}) {
     if (!ap)
         return;
     state.appSessions.delete(appSessionId);
+    // Evict AppData bridges FIRST — eviction enumerates `ap.pages`, which the
+    // page teardown below progressively empties (and finally clears).
+    state.evictAppDataBridges(ap);
     // Drain any pending API calls owned by this app session. One-shot calls
     // normally self-clean on response/timeout, but persistent (`keep: true`)
     // subscriptions (e.g. audioListen) live with their timer cleared until

package/dist/main/ipc/views.js

@@ -30,7 +30,16 @@ export function registerViewsIpc(ctx) {
         .handle(ViewChannel.HostToolbarBounds, (_event, ...args) => {
         const [bounds] = validate(ViewChannel.HostToolbarBounds, ViewBoundsSchema, args);
         ctx.views.setHostToolbarBounds(bounds);
-    });
+    })
+        // Height replay pull: a freshly-mounted main-renderer placeholder asks for
+        // the last NOTIFIED toolbar height (main retains it — the toolbar's
+        // size-advertiser deduplicates and never re-pushes, so a push that fired
+        // while no project view was mounted is otherwise lost: cold start races
+        // it, close-project → reopen hits it always). Rides the SAME
+        // senderPolicy-gated registry as HostToolbarBounds: the toolbar WCV's
+        // arbitrary host content must not reach this — only the trusted main
+        // renderer pulls. Live delegation, not a registration-time snapshot.
+        .handle(ViewChannel.HostToolbarGetHeight, () => ctx.views.getHostToolbarHeight());
     // Reverse size-advertiser: the toolbar WCV's OWN renderer sends this, and the
     // host loads ARBITRARY content into that WCV. We DELIBERATELY do NOT add the
     // toolbar wc to the global sender policy — that would trust it for ALL ~72

package/dist/main/menu/index.d.ts

@@ -1,3 +1,3 @@
-import type { WorkbenchContext } from '../services/workbench-context.js';
-export declare function installAppMenu(ctx: WorkbenchContext): void;
+import type { MenuContext } from '../../shared/types.js';
+export declare function installAppMenu(ctx: MenuContext): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/main/menu/index.js

@@ -1,5 +1,7 @@
 import { Menu } from 'electron';
-import { openSettingsWindow } from '../app/launch.js';
+// The built-in menu consumes the narrow MenuContext, the same surface a host
+// menuBuilder receives — proof that the hand-written contract covers the
+// real internal consumption (settings entry + navigate-back).
 export function installAppMenu(ctx) {
     const template = [
         {
@@ -8,7 +10,7 @@ export function installAppMenu(ctx) {
                 {
                     label: '开发工具设置',
                     click: () => {
-                        void openSettingsWindow(ctx).catch(() => { });
+                        void ctx.openSettings().catch(() => { });
                     },
                 },
                 { type: 'separator' },

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

@@ -17,8 +17,6 @@
  *    past the drift sentinel.
  *  - `workspace.openProject` stays writable (no `readonly`): qdmp gates
  *    project permissions by reassigning it (documented monkey-patch contract).
- *  - `windows` is an OPAQUE handle (`object`): hosts pass it through to
- *    framework helpers but never reach into it (no BrowserWindow leak).
  *
  * `asMiniappRuntime(ctx)` is an identity return — the contract is a typed
  * VIEW onto the live context, not a snapshot/projection. That is what makes
@@ -35,6 +33,53 @@ export interface MiniappProjectStatusPayload {
     /** True when the status update is emitted by the file-watcher rebuild loop. */
     hotReload?: boolean;
 }
+/**
+ * Structured shape of `getSession().appInfo` — the doc-promised
+ * (`host-migration.md` "appInfo 已结构化") DTO, named so hosts can type what
+ * they receive without deep imports or casts.
+ *
+ * `appId` is REQUIRED: the renderer derives its IPC scoping from it and the
+ * default devkit adapter always supplies one (fallback included). A custom
+ * adapter that returns a session without a string `appId` is rejected at the
+ * `openProject` boundary (see workspace-service.ts) — it never becomes the
+ * active session. The decorative rest stays optional: `name`/`path` come from
+ * the devkit adapter, `appName` from the devtools-side mirror; minimal custom
+ * adapters may omit all three.
+ */
+export interface MiniappSessionAppInfo {
+    appId: string;
+    name?: string;
+    path?: string;
+    appName?: string;
+}
+/**
+ * The page-side bridge the framework injects into the host-toolbar WCV as
+ * `window.diminaHostToolbar` (see src/preload/runtime/host-toolbar-port.ts).
+ * Declared here (the electron-free contract module) so TypeScript toolbar
+ * pages can type the bridge without hand-rolling — and without importing
+ * anything Electron-flavored.
+ *
+ * Shape mirrors the injected bridge EXACTLY:
+ *  - `send` returns void (pre-handshake sends are queued, bounded at 128);
+ *  - `onMessage` returns a BARE un-subscribe function — unlike the main-side
+ *    control's `{ dispose }` — because that is what the preload exposes.
+ * Both throw a `TypeError` synchronously when `channel` is not a non-empty
+ * string (parity with the main side's `onMessage` guard).
+ */
+export interface DiminaHostToolbarPageBridge {
+    send: (channel: string, payload: unknown) => void;
+    onMessage: (channel: string, handler: (payload: unknown) => void) => () => void;
+}
+declare global {
+    interface Window {
+        /**
+         * Present ONLY inside the host-toolbar WebContentsView's main frame
+         * (guarded injection — see host-toolbar-runtime.ts); optional everywhere
+         * else, so page code must runtime-guard before use.
+         */
+        diminaHostToolbar?: DiminaHostToolbarPageBridge;
+    }
+}
 /**
  * Host-facing control surface for the toolbar WebContentsView — the exact
  * post-R2 message-channel surface (`send`/`onMessage`), with no `webContents`
@@ -67,9 +112,22 @@ export interface MiniappHostToolbar {
     onMessage: (channel: string, handler: (payload: unknown) => void) => {
         dispose: () => void;
     };
+    /**
+     * Observe handshake readiness. Fires the handler once per load generation,
+     * exactly when the toolbar page's MessagePort handshake completes (i.e.
+     * when `send` flips to true). Registering while the channel is already
+     * ready fires once asynchronously on a microtask (missed-signal guard);
+     * a reload / re-handshake fires registered handlers again. `dispose()`
+     * detaches (idempotent).
+     */
+    onReady: (handler: () => void) => {
+        dispose: () => void;
+    };
     /**
      * Pin (`{ fixed }`) or unpin (`'auto'`) the toolbar strip height. `'auto'`
      * (default) lets the in-page height advertiser drive the placeholder.
+     * `{ fixed }` values must be finite and non-negative — anything else throws
+     * a `TypeError` synchronously and leaves the standing mode untouched.
      */
     setHeightMode: (mode: 'auto' | {
         fixed: number;
@@ -103,10 +161,11 @@ export interface MiniappWorkspace {
     /**
      * Minimal live-session DTO, or null when no session. Deliberately excludes
      * the session's own `close` — hosts end sessions via `closeProject`, never
-     * behind the workspace's back.
+     * behind the workspace's back. `appInfo` is structured (see
+     * {@link MiniappSessionAppInfo}) — no casting required.
      */
     getSession: () => {
-        appInfo: unknown;
+        appInfo: MiniappSessionAppInfo;
     } | null;
 }
 /**
@@ -115,8 +174,6 @@ export interface MiniappWorkspace {
  * plumbing is a deliberate semver decision, not an accident of projection.
  */
 export interface MiniappRuntime {
-    /** Absolute path to the devtools renderer dist directory. */
-    rendererDir: string;
     /** View layer — only the host-owned toolbar control is public. */
     views: {
         readonly hostToolbar: MiniappHostToolbar;
@@ -127,15 +184,26 @@ export interface MiniappRuntime {
     notify: {
         projectStatus: (payload: MiniappProjectStatusPayload) => void;
     };
-    /** Lifecycle sink: hosts register their own teardown via `registry.add`. */
+    /**
+     * Lifecycle sink: hosts register their own teardown via `registry.add`.
+     * Accepts BOTH disposal idioms — a `{ dispose }` object (what
+     * `hostToolbar.onMessage`/`onReady` return) or a bare `() => void` —
+     * matching the live registry, so `registry.add(sub)` works without the
+     * `registry.add(() => sub.dispose())` wrapper.
+     */
     registry: {
-        add: (dispose: () => void) => unknown;
+        add: (d: {
+            dispose: () => void;
+        } | (() => void)) => void;
     };
     /**
-     * Opaque window-service handle. Pass it through to framework helpers
-     * (e.g. `openSettingsWindow`); it exposes nothing to reach into.
+     * Open (or re-focus) the standalone workbench-settings window. Replaces the
+     * retired `windows` opaque pass-through (whose only documented purpose —
+     * `openSettingsWindow(ctx)` — could never typecheck from the contract) and
+     * the `rendererDir` member that existed solely to feed it; hosts needing
+     * the renderer dist path use the `/paths` export instead.
      */
-    windows: object;
+    openSettings: () => Promise<void>;
 }
 /**
  * View a full `WorkbenchContext` as its `MiniappRuntime` contract. Identity

package/dist/main/services/notifications/renderer-notifier.d.ts

@@ -12,6 +12,15 @@ export interface ProjectStatusPayload {
     /** True when the status update is emitted by the file-watcher rebuild loop. */
     hotReload?: boolean;
 }
+/**
+ * Payload for the `project:compileLog` push — one filtered dmcc log line.
+ * `at` is stamped in the main process when the line is captured.
+ */
+export interface CompileLogPayload {
+    at: number;
+    stream: 'stdout' | 'stderr';
+    text: string;
+}
 /**
  * Payload for the `settings:init` event sent into the embedded settings overlay
  * right after it is shown.
@@ -43,6 +52,8 @@ export interface WorkbenchSettingsInitPayload {
 export interface RendererNotifier {
     /** Broadcast project compile status transitions to the main renderer. */
     projectStatus(payload: ProjectStatusPayload): void;
+    /** Push one per-line dmcc compile-log entry to the main renderer. */
+    compileLog(payload: CompileLogPayload): void;
     /** Ask the main renderer to navigate back to its landing screen. */
     windowNavigateBack(): void;
     /** Tell the main renderer the compile popover has been closed. */

package/dist/main/services/notifications/renderer-notifier.js

@@ -24,6 +24,9 @@ export function createRendererNotifier(ctx) {
         projectStatus(payload) {
             sendToMain(ProjectChannel.Status, payload);
         },
+        compileLog(payload) {
+            sendToMain(ProjectChannel.CompileLog, payload);
+        },
         windowNavigateBack() {
             sendToMain(WindowChannel.NavigateBack);
         },

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

@@ -68,6 +68,16 @@ export interface HostToolbarPortChannel {
     invalidate(): void;
     /** Register a control-level inbound handler for `channel`. */
     onMessage(channel: string, handler: (payload: unknown) => void): HostToolbarMessageSubscription;
+    /**
+     * Observe handshake readiness. Fires `handler` once per load GENERATION,
+     * at the moment that generation's handshake completes (`send` flips true).
+     * Registering while already `ready` schedules a one-shot catch-up fire on a
+     * microtask — never synchronously — and the catch-up RE-CHECKS at fire time
+     * that (a) the subscription is still registered and (b) the generation is
+     * unchanged / the port is still live, so a same-frame `dispose()` or
+     * host-initiated load suppresses it. Inert (never fires) after `dispose()`.
+     */
+    onReady(handler: () => void): HostToolbarMessageSubscription;
     /**
      * Post `{ channel, payload }` to the toolbar page over the live port.
      * Returns false (delivering NOTHING, creating NOTHING) when there is no

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

@@ -50,10 +50,20 @@ export function createHostToolbarPortChannel(opts) {
     let activePort = null;
     /** The wc that owns `activePort` (so a stale wc's `destroyed` can't drop a successor's port). */
     let activeWc = null;
-    let disposed = false;
+    /** Named lifecycle state. INVARIANT: `state === 'ready'` ⟺ `activePort !== null`. */
+    let state = 'absent';
+    /**
+     * Monotonic per-handshake counter. Each completed handshake is one load
+     * GENERATION; `onReady` catch-up fires capture it at registration and
+     * re-check it at fire time so a fire scheduled for generation N can never
+     * deliver after a navigation/handshake moved the channel past N.
+     */
+    let generation = 0;
     // Array (not Map<channel, Set>) so the same handler function may be
     // registered twice and each registration disposes independently.
     const handlers = [];
+    // onReady registrations. Same array-of-entries discipline as `handlers`.
+    const readyHandlers = [];
     function dispatch(data) {
         // Inbound waist: the toolbar page is host-arbitrary content — anything
         // that is not an object envelope with a string channel is dropped.
@@ -68,10 +78,16 @@ export function createHostToolbarPortChannel(opts) {
                 entry.handler(payload);
         }
     }
-    function dropActivePort(close) {
+    /**
+     * Drop the live port and transition to `next` (`'absent'` for death paths,
+     * `'awaitingHandshake'` for navigation paths). Never demotes `disposed`.
+     */
+    function dropActivePort(close, next) {
         const port = activePort;
         activePort = null;
         activeWc = null;
+        if (state !== 'disposed')
+            state = next;
         if (close && port) {
             try {
                 port.close();
@@ -81,13 +97,39 @@ export function createHostToolbarPortChannel(opts) {
             }
         }
     }
+    /**
+     * Invoke one onReady handler with exception ISOLATION: subscribers are
+     * arbitrary control-level code — one throwing must neither starve sibling
+     * registrations nor escape the surrounding event/microtask callback (a
+     * throw out of a `did-finish-load` listener or a `queueMicrotask` body is
+     * process-level `uncaughtException` territory). Report-and-continue.
+     */
+    function invokeReadyHandler(handler) {
+        try {
+            handler();
+        }
+        catch (err) {
+            console.error('[host-toolbar] onReady handler threw:', err);
+        }
+    }
+    /** Fire every still-registered onReady handler exactly once (snapshot iteration). */
+    function fireReadyHandlers() {
+        for (const entry of [...readyHandlers]) {
+            // A handler may dispose a sibling registration mid-fire: re-check
+            // membership so a disposed entry never fires. Per-handler isolation
+            // (NOT around the loop): a throwing handler must not abort the fire
+            // for later-registered siblings.
+            if (readyHandlers.includes(entry))
+                invokeReadyHandler(entry.handler);
+        }
+    }
     function handshake(wc) {
-        if (disposed)
+        if (state === 'disposed')
             return;
         if (!opts.isCurrent(wc))
             return;
         // The previous load's document is gone; its port goes with it.
-        dropActivePort(true);
+        dropActivePort(true, 'awaitingHandshake');
         const { port1, port2 } = new MessageChannelMain();
         port1.on('message', (event) => {
             dispatch(event.data);
@@ -96,12 +138,17 @@ export function createHostToolbarPortChannel(opts) {
         // the reference so send() reports false instead of posting into the void.
         port1.on('close', () => {
             if (activePort === port1)
-                dropActivePort(false);
+                dropActivePort(false, 'absent');
         });
         wc.postMessage(ViewChannel.HostToolbarPort, null, [port2]);
         port1.start();
         activePort = port1;
         activeWc = wc;
+        state = 'ready';
+        generation++;
+        // Readiness signal AFTER the port is live: a handler calling send() from
+        // inside its onReady fire must observe `true`.
+        fireReadyHandlers();
     }
     return {
         attach(wc) {
@@ -129,15 +176,15 @@ export function createHostToolbarPortChannel(opts) {
                     : isMainFramePositional;
                 if (isSameDocument || !isMainFrame)
                     return;
-                dropActivePort(true);
+                dropActivePort(true, 'awaitingHandshake');
             });
             wc.on('destroyed', () => {
                 if (activeWc === wc)
-                    dropActivePort(true);
+                    dropActivePort(true, 'absent');
             });
         },
         invalidate() {
-            dropActivePort(true);
+            dropActivePort(true, 'awaitingHandshake');
         },
         onMessage(channel, handler) {
             if (typeof channel !== 'string' || channel === '') {
@@ -153,6 +200,37 @@ export function createHostToolbarPortChannel(opts) {
                 },
             };
         },
+        onReady(handler) {
+            // Torn-down control: inert registration — never fires, never throws.
+            if (state === 'disposed') {
+                return { dispose() { } };
+            }
+            const entry = { handler };
+            readyHandlers.push(entry);
+            if (state === 'ready') {
+                // Missed-signal catch-up: the handshake already happened, so the
+                // subscriber would otherwise wait forever. Asynchronous on a
+                // microtask (never re-enter host code synchronously inside
+                // onReady()), and RE-CHECKED at fire time — both the subscription's
+                // liveness and the load generation can change between scheduling and
+                // the microtask (same-frame dispose() / same-frame loadFile).
+                const scheduledGeneration = generation;
+                queueMicrotask(() => {
+                    if (state !== 'ready' || generation !== scheduledGeneration || !activePort)
+                        return;
+                    if (!readyHandlers.includes(entry))
+                        return;
+                    invokeReadyHandler(entry.handler);
+                });
+            }
+            return {
+                dispose() {
+                    const i = readyHandlers.indexOf(entry);
+                    if (i >= 0)
+                        readyHandlers.splice(i, 1);
+                },
+            };
+        },
         send(channel, payload) {
             if (!activePort)
                 return false;
@@ -160,9 +238,10 @@ export function createHostToolbarPortChannel(opts) {
             return true;
         },
         dispose() {
-            disposed = true;
-            dropActivePort(true);
+            dropActivePort(true, 'absent');
+            state = 'disposed';
             handlers.length = 0;
+            readyHandlers.length = 0;
         },
     };
 }

package/dist/main/services/views/view-manager.d.ts

@@ -112,6 +112,16 @@ export interface ViewManager {
      * must trust its id — see `createWorkbenchSenderPolicy`.
      */
     getHostToolbarWebContentsId(): number | null;
+    /**
+     * Return the last host-toolbar height NOTIFIED to the main-window renderer
+     * (an advertiser report in `'auto'` mode, a `setHeightMode({ fixed })` pin,
+     * or 0 after `hostToolbar.hide()`); 0 before any notify. The renderer pulls
+     * this on project-view mount to REPLAY a height whose push it missed — the
+     * toolbar's size-advertiser deduplicates and never re-reports, so a notify
+     * fired while no project view is mounted (cold start on the project list;
+     * always on close-project → reopen) would otherwise be lost forever.
+     */
+    getHostToolbarHeight(): number;
     /**
      * NATIVE-HOST ONLY. Position the simulator content WebContentsView over the
      * renderer-measured simulator panel REGION rect (the flex:1 placeholder slot,
@@ -168,10 +178,12 @@ export interface ViewManager {
     }): void;
     /**
      * Reverse size-advertiser sink: the toolbar WCV's own renderer advertises
-     * its intrinsic content height (block-axis extent); we store it and push it
-     * to the main-window renderer so the placeholder div resizes (closing the
-     * dynamic-height loop). Ignored while a `{ fixed }` height mode is pinned
-     * via `hostToolbar.setHeightMode` (the session-resident advertiser always
+     * its intrinsic content height (block-axis extent); we retain it as the
+     * last-notified height (`getHostToolbarHeight`) and push it to the
+     * main-window renderer so the placeholder div resizes (closing the
+     * dynamic-height loop). Ignored ENTIRELY while a `{ fixed }` height mode is
+     * pinned via `hostToolbar.setHeightMode` — dropped reports neither notify
+     * nor touch the retained value (the session-resident advertiser always
      * runs, so its reports must not fight a host-pinned height).
      */
     setHostToolbarHeight(extent: number): void;
@@ -224,6 +236,18 @@ export interface HostToolbarControl {
      * (idempotent).
      */
     onMessage(channel: string, handler: (payload: unknown) => void): HostToolbarMessageSubscription;
+    /**
+     * Observe handshake readiness — the push counterpart to polling `send()`
+     * for `true`. Fires the handler once per load generation, exactly when
+     * that load's MessagePort handshake completes; registering while the
+     * channel is ALREADY ready fires once asynchronously on a microtask
+     * (missed-signal race guard, re-validated at fire time). A reload /
+     * re-handshake fires registered handlers again; a host-initiated
+     * `loadURL`/`loadFile` invalidates readiness at initiation, so handlers
+     * registered in that window wait for the NEW document's handshake.
+     * `dispose()` detaches (idempotent); `disposeAll` sweeps everything.
+     */
+    onReady(handler: () => void): HostToolbarMessageSubscription;
     /**
      * Post `{ channel, payload }` to the toolbar page (received via
      * `window.diminaHostToolbar.onMessage(channel, handler)`). Gated and

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

@@ -95,6 +95,13 @@ export function createViewManager(ctx) {
     // Placeholder height authority: 'auto' = advertiser reports forward to the
     // renderer; { fixed } = host-pinned, advertiser reports are dropped.
     let hostToolbarHeightMode = 'auto';
+    // Last toolbar height NOTIFIED to the main-window renderer — the replay
+    // source behind `getHostToolbarHeight()`. Updated ONLY inside
+    // `notifyHostToolbarHeight` so the retained value can never diverge from
+    // what the renderer was told (an advertiser report dropped by a `{ fixed }`
+    // pin must not pollute it, and a setHeightMode validation reject leaves it
+    // untouched).
+    let hostToolbarLastHeight = 0;
     // Gated narrow channel to the toolbar PAGE (per-load MessagePort handshake;
     // see host-toolbar-port-channel.ts). Control-level registry — created with
     // the manager so onMessage() works before any toolbar view exists.
@@ -248,18 +255,30 @@ export function createViewManager(ctx) {
         }
         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
+    // on project-view mount to replay a push it missed (the toolbar's
+    // size-advertiser deduplicates and never re-reports).
+    function notifyHostToolbarHeight(height) {
+        hostToolbarLastHeight = height;
+        ctx.notify.hostToolbarHeightChanged(height);
+    }
     function setHostToolbarHeight(extent) {
         // While the host pins a fixed height, drop advertiser reports entirely —
         // the session-resident advertiser is always installed, so forwarding its
         // reports would make the strip oscillate between the pinned and measured
-        // heights on every content resize.
+        // heights on every content resize. Dropped reports must not touch the
+        // retained value either: retention records what was NOTIFIED, not what
+        // was reported.
         if (hostToolbarHeightMode !== 'auto')
             return;
         // Push the reserved height back to the main-window renderer so its
-        // placeholder div resizes (closing the dynamic-height loop). The height is
-        // not retained in main — the renderer placeholder is the single source of
-        // truth, and the forward anchor re-reports bounds from it.
-        ctx.notify.hostToolbarHeightChanged(extent);
+        // placeholder div resizes (closing the dynamic-height loop). The notified
+        // height IS retained in main (`getHostToolbarHeight`) so a renderer that
+        // mounts later can pull/replay it; the renderer placeholder remains the
+        // geometry authority — the forward anchor re-reports bounds from it.
+        notifyHostToolbarHeight(extent);
     }
     function hideHostToolbar() {
         if (hostToolbarView && hostToolbarViewAdded && !ctx.windows.mainWindow.isDestroyed()) {
@@ -273,7 +292,9 @@ export function createViewManager(ctx) {
         // non-zero reserved height and re-publishes bounds on the next window
         // resize, silently re-adding the view we just hid (unstable hide). Zeroing
         // the height flips the anchor to `present:false` so it stops re-publishing.
-        ctx.notify.hostToolbarHeightChanged(0);
+        // Through the funnel so the retained value follows to 0 — a renderer
+        // mounting after the hide must replay 0, not the stale pre-hide height.
+        notifyHostToolbarHeight(0);
     }
     const hostToolbar = {
         async loadURL(url) {
@@ -306,19 +327,31 @@ export function createViewManager(ctx) {
             hostToolbarPreloadOverride = path;
         },
         setHeightMode(mode) {
+            // Validate BEFORE touching any state: a poisoned `{ fixed }` (NaN /
+            // ±Infinity / negative) must neither reach the renderer placeholder
+            // (`height: NaNpx` corrupts the strip with no error anywhere) nor
+            // clobber the standing mode — fail-closed, not fail-corrupt.
+            if (mode !== 'auto' && !(Number.isFinite(mode.fixed) && mode.fixed >= 0)) {
+                throw new TypeError(`hostToolbar.setHeightMode: fixed height must be a finite, non-negative number (got ${mode.fixed})`);
+            }
             hostToolbarHeightMode = mode;
             if (mode !== 'auto') {
                 // Pin immediately: a preload-less/static toolbar never advertises, so
                 // waiting for the next report would leave the strip at height 0.
-                ctx.notify.hostToolbarHeightChanged(mode.fixed);
+                notifyHostToolbarHeight(mode.fixed);
             }
             // Switching back to 'auto' deliberately does NOT synthesize a notify —
             // replaying a stale cached height would flash the old size; the NEXT
-            // advertiser report drives the placeholder again.
+            // advertiser report drives the placeholder again. The RETAINED value
+            // survives the switch though: a freshly-mounting renderer still needs
+            // the pinned height until that next report lands.
         },
         onMessage(channel, handler) {
             return hostToolbarPort.onMessage(channel, handler);
         },
+        onReady(handler) {
+            return hostToolbarPort.onReady(handler);
+        },
         send(channel, payload) {
             return hostToolbarPort.send(channel, payload);
         },
@@ -1136,6 +1169,7 @@ export function createViewManager(ctx) {
             return popoverView.webContents.id;
         },
         getHostToolbarWebContentsId: () => liveHostToolbarWebContents()?.id ?? null,
+        getHostToolbarHeight: () => hostToolbarLastHeight,
         setNativeSimulatorViewBounds,
         resize,
         setSimulatorDevtoolsBounds,