@dimina-kit/devtools 0.3.2-dev.20260611063505 → 0.4.0-dev.20260612025610

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

@@ -0,0 +1,103 @@
+/**
+ * Gated narrow channel between the main process and the host-toolbar
+ * WebContentsView's page, over a per-load transferred MessagePort.
+ *
+ * Why a MessagePort and not plain IPC: the toolbar page is HOST-ARBITRARY
+ * content. A dedicated port pair gives it exactly one pipe whose main-side end
+ * lives in this module — the page never gains a generic `ipcRenderer` reach
+ * into the ~72 internal devtools channels, and main-side inbound traffic is
+ * validated at this single waist.
+ *
+ * Lifecycle (per-load handshake):
+ *  - On every toolbar-wc `did-finish-load` main builds a fresh
+ *    `MessageChannelMain`, transfers port2 to the new document via
+ *    `wc.postMessage(ViewChannel.HostToolbarPort, null, [port2])`, keeps
+ *    port1 and `start()`s it. The previous port1 (if any) is closed first —
+ *    its document is gone.
+ *  - `onMessage` registrations are CONTROL-level (this module's registry), not
+ *    per-port: they may be made before any view exists and survive page
+ *    reloads / wc rebuilds, because each new handshake dispatches into the
+ *    same registry.
+ *  - `send` is gated and non-queueing: `false` means "not delivered, ever" —
+ *    no toolbar view is conjured, nothing is buffered for a later handshake.
+ *  - A port1 `'close'` event (the renderer end died without a re-handshake
+ *    yet) drops the live-port reference so `send` reports `false` instead of
+ *    posting into a dead pipe.
+ *  - NAVIGATION INVALIDATES THE PORT. The port pair belongs to one DOCUMENT,
+ *    so starting a navigation that replaces that document closes port1 and
+ *    `send` returns `false` until the new document's `did-finish-load`
+ *    handshake. Two paths:
+ *      (a) host-initiated `hostToolbar.loadURL/loadFile` calls `invalidate()`
+ *          synchronously AT INITIATION (view-manager does this before the
+ *          `webContents.loadURL/loadFile` await), so a same-tick `send` can
+ *          never report `true` for an envelope posted into the document the
+ *          load is about to replace;
+ *      (b) page-initiated navigation (location.href / reload) is caught by a
+ *          `did-start-navigation` listener — guarded to the ACTIVE wc,
+ *          main-frame, cross-document only. Same-document navigations
+ *          (anchors, pushState, history) and subframe navigations do NOT
+ *          invalidate: the document the port lives in survives those, and no
+ *          main-frame `did-finish-load` would follow to ever restore the
+ *          channel.
+ *
+ * Envelope both directions: `{ channel: string, payload: unknown }`. Inbound
+ * data that is not an object with a string `channel` is DROPPED without
+ * throwing (the counterpart is arbitrary host content).
+ */
+import type { WebContents } from 'electron';
+/** Handle returned by `onMessage`; `dispose()` detaches (idempotent). */
+export interface HostToolbarMessageSubscription {
+    dispose(): void;
+}
+export interface HostToolbarPortChannel {
+    /**
+     * Hook a freshly created toolbar 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.
+     */
+    attach(wc: WebContents): void;
+    /**
+     * Drop the live port NOW (close + clear): the document it belongs to is
+     * being replaced. Called by view-manager synchronously when the HOST
+     * initiates a `loadURL`/`loadFile` — the host-initiated half of the
+     * navigation-invalidates contract (the page-initiated half is the
+     * `did-start-navigation` listener `attach` installs). `send` returns false
+     * from this call until the next `did-finish-load` handshake. Idempotent.
+     */
+    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
+     * live toolbar wc, the current load's handshake hasn't completed, or a
+     * document-replacing navigation is in flight (see `invalidate`).
+     */
+    send(channel: string, payload: unknown): boolean;
+    /**
+     * Teardown (view-manager `disposeAll`): close the live port, sweep the
+     * handler registry, refuse further handshakes. Subsequent `send` returns
+     * false; late `dispose()` of an old subscription stays a no-op.
+     */
+    dispose(): void;
+}
+export declare function createHostToolbarPortChannel(opts: {
+    /**
+     * Is `wc` still the manager's CURRENT live toolbar webContents? Guards a
+     * stale wc's late `did-finish-load` from hijacking the channel after a
+     * rebuild swapped the view out underneath it.
+     */
+    isCurrent: (wc: WebContents) => boolean;
+}): HostToolbarPortChannel;
+//# sourceMappingURL=host-toolbar-port-channel.d.ts.map

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

@@ -0,0 +1,248 @@
+/**
+ * Gated narrow channel between the main process and the host-toolbar
+ * WebContentsView's page, over a per-load transferred MessagePort.
+ *
+ * Why a MessagePort and not plain IPC: the toolbar page is HOST-ARBITRARY
+ * content. A dedicated port pair gives it exactly one pipe whose main-side end
+ * lives in this module — the page never gains a generic `ipcRenderer` reach
+ * into the ~72 internal devtools channels, and main-side inbound traffic is
+ * validated at this single waist.
+ *
+ * Lifecycle (per-load handshake):
+ *  - On every toolbar-wc `did-finish-load` main builds a fresh
+ *    `MessageChannelMain`, transfers port2 to the new document via
+ *    `wc.postMessage(ViewChannel.HostToolbarPort, null, [port2])`, keeps
+ *    port1 and `start()`s it. The previous port1 (if any) is closed first —
+ *    its document is gone.
+ *  - `onMessage` registrations are CONTROL-level (this module's registry), not
+ *    per-port: they may be made before any view exists and survive page
+ *    reloads / wc rebuilds, because each new handshake dispatches into the
+ *    same registry.
+ *  - `send` is gated and non-queueing: `false` means "not delivered, ever" —
+ *    no toolbar view is conjured, nothing is buffered for a later handshake.
+ *  - A port1 `'close'` event (the renderer end died without a re-handshake
+ *    yet) drops the live-port reference so `send` reports `false` instead of
+ *    posting into a dead pipe.
+ *  - NAVIGATION INVALIDATES THE PORT. The port pair belongs to one DOCUMENT,
+ *    so starting a navigation that replaces that document closes port1 and
+ *    `send` returns `false` until the new document's `did-finish-load`
+ *    handshake. Two paths:
+ *      (a) host-initiated `hostToolbar.loadURL/loadFile` calls `invalidate()`
+ *          synchronously AT INITIATION (view-manager does this before the
+ *          `webContents.loadURL/loadFile` await), so a same-tick `send` can
+ *          never report `true` for an envelope posted into the document the
+ *          load is about to replace;
+ *      (b) page-initiated navigation (location.href / reload) is caught by a
+ *          `did-start-navigation` listener — guarded to the ACTIVE wc,
+ *          main-frame, cross-document only. Same-document navigations
+ *          (anchors, pushState, history) and subframe navigations do NOT
+ *          invalidate: the document the port lives in survives those, and no
+ *          main-frame `did-finish-load` would follow to ever restore the
+ *          channel.
+ *
+ * Envelope both directions: `{ channel: string, payload: unknown }`. Inbound
+ * data that is not an object with a string `channel` is DROPPED without
+ * throwing (the counterpart is arbitrary host content).
+ */
+import { MessageChannelMain } from 'electron';
+import { ViewChannel } from '../../../shared/ipc-channels.js';
+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;
+    /** 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.
+        if (typeof data !== 'object' || data === null)
+            return;
+        const { channel, payload } = data;
+        if (typeof channel !== 'string')
+            return;
+        // Snapshot so a handler that (un)subscribes mid-dispatch can't skew iteration.
+        for (const entry of [...handlers]) {
+            if (entry.channel === channel)
+                entry.handler(payload);
+        }
+    }
+    /**
+     * 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();
+            }
+            catch {
+                /* already closed */
+            }
+        }
+    }
+    /**
+     * 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 (state === 'disposed')
+            return;
+        if (!opts.isCurrent(wc))
+            return;
+        // The previous load's document is gone; its port goes with it.
+        dropActivePort(true, 'awaitingHandshake');
+        const { port1, port2 } = new MessageChannelMain();
+        port1.on('message', (event) => {
+            dispatch(event.data);
+        });
+        // Renderer end died without a re-handshake (page crash / wc close): drop
+        // the reference so send() reports false instead of posting into the void.
+        port1.on('close', () => {
+            if (activePort === port1)
+                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) {
+            wc.on('did-finish-load', () => 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
+            // document being torn down. TRIPLE guard, because over-invalidating
+            // mutes the channel FOREVER (no main-frame did-finish-load follows to
+            // re-handshake):
+            //  - activeWc: a stale wc's late event must not drop a successor's port
+            //    (same discipline as the 'destroyed' handler below);
+            //  - cross-document only: anchors/pushState/history keep the document;
+            //  - 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) => {
+                if (activeWc !== wc)
+                    return;
+                const isSameDocument = typeof details?.isSameDocument === 'boolean'
+                    ? details.isSameDocument
+                    : isInPlace;
+                const isMainFrame = typeof details?.isMainFrame === 'boolean'
+                    ? details.isMainFrame
+                    : isMainFramePositional;
+                if (isSameDocument || !isMainFrame)
+                    return;
+                dropActivePort(true, 'awaitingHandshake');
+            });
+            wc.on('destroyed', () => {
+                if (activeWc === wc)
+                    dropActivePort(true, 'absent');
+            });
+        },
+        invalidate() {
+            dropActivePort(true, 'awaitingHandshake');
+        },
+        onMessage(channel, handler) {
+            if (typeof channel !== 'string' || channel === '') {
+                throw new TypeError('hostToolbar.onMessage: channel must be a non-empty string');
+            }
+            const entry = { channel, handler };
+            handlers.push(entry);
+            return {
+                dispose() {
+                    const i = handlers.indexOf(entry);
+                    if (i >= 0)
+                        handlers.splice(i, 1);
+                },
+            };
+        },
+        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;
+            activePort.postMessage({ channel, payload });
+            return true;
+        },
+        dispose() {
+            dropActivePort(true, 'absent');
+            state = 'disposed';
+            handlers.length = 0;
+            readyHandlers.length = 0;
+        },
+    };
+}
+//# sourceMappingURL=host-toolbar-port-channel.js.map

package/dist/main/services/views/host-toolbar-session-runtime.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Ref-counted registration of the host-toolbar framework runtime on
+ * `session.defaultSession`.
+ *
+ * The toolbar's height advertiser no longer rides the toolbar WCV's
+ * `webPreferences.preload` (a host's `setPreloadPath` used to replace it and
+ * the strip height collapsed to 0). Instead the runtime bundle
+ * (`hostToolbarRuntimePreloadPath`) is registered once per process as a
+ * session frame preload; its own guard (`--dimina-host-toolbar` marker +
+ * `isMainFrame`) keeps it a zero-footprint no-op in every other defaultSession
+ * renderer.
+ *
+ * Ref-counting (codex condition 3): multiple ViewManagers can coexist in one
+ * process and share the ONE defaultSession. Each manager acquires at most one
+ * reference (on first toolbar need) and releases it in `disposeAll`. Only the
+ * first acquire registers; only the last release unregisters (with the id
+ * `registerPreloadScript` returned). After a full release a new acquire
+ * re-registers — there is deliberately no "registered once ever" latch, so
+ * dispose-everything-then-relaunch flows keep their toolbar runtime.
+ *
+ * Module-level state; tests reset it via `vi.resetModules()` + re-import.
+ */
+/**
+ * Take a reference on the shared session registration. Registers the runtime
+ * preload on `session.defaultSession` when the count rises from zero. Call at
+ * most once per ViewManager (the manager tracks its own acquired-flag).
+ */
+export declare function acquireHostToolbarSessionRuntime(): void;
+/**
+ * Release a reference. Unregisters (with the stored registration id) only when
+ * the LAST reference is released; a still-alive ViewManager's toolbar keeps
+ * its session runtime. Safe to call only by managers that actually acquired.
+ */
+export declare function releaseHostToolbarSessionRuntime(): void;
+//# sourceMappingURL=host-toolbar-session-runtime.d.ts.map

package/dist/main/services/views/host-toolbar-session-runtime.js

@@ -0,0 +1,55 @@
+/**
+ * Ref-counted registration of the host-toolbar framework runtime on
+ * `session.defaultSession`.
+ *
+ * The toolbar's height advertiser no longer rides the toolbar WCV's
+ * `webPreferences.preload` (a host's `setPreloadPath` used to replace it and
+ * the strip height collapsed to 0). Instead the runtime bundle
+ * (`hostToolbarRuntimePreloadPath`) is registered once per process as a
+ * session frame preload; its own guard (`--dimina-host-toolbar` marker +
+ * `isMainFrame`) keeps it a zero-footprint no-op in every other defaultSession
+ * renderer.
+ *
+ * Ref-counting (codex condition 3): multiple ViewManagers can coexist in one
+ * process and share the ONE defaultSession. Each manager acquires at most one
+ * reference (on first toolbar need) and releases it in `disposeAll`. Only the
+ * first acquire registers; only the last release unregisters (with the id
+ * `registerPreloadScript` returned). After a full release a new acquire
+ * re-registers — there is deliberately no "registered once ever" latch, so
+ * dispose-everything-then-relaunch flows keep their toolbar runtime.
+ *
+ * Module-level state; tests reset it via `vi.resetModules()` + re-import.
+ */
+import { session } from 'electron';
+import { hostToolbarRuntimePreloadPath } from '../../utils/paths.js';
+let refCount = 0;
+let registrationId = null;
+/**
+ * Take a reference on the shared session registration. Registers the runtime
+ * preload on `session.defaultSession` when the count rises from zero. Call at
+ * most once per ViewManager (the manager tracks its own acquired-flag).
+ */
+export function acquireHostToolbarSessionRuntime() {
+    if (refCount === 0) {
+        registrationId = session.defaultSession.registerPreloadScript({
+            type: 'frame',
+            filePath: hostToolbarRuntimePreloadPath,
+        });
+    }
+    refCount++;
+}
+/**
+ * Release a reference. Unregisters (with the stored registration id) only when
+ * the LAST reference is released; a still-alive ViewManager's toolbar keeps
+ * its session runtime. Safe to call only by managers that actually acquired.
+ */
+export function releaseHostToolbarSessionRuntime() {
+    if (refCount === 0)
+        return;
+    refCount--;
+    if (refCount === 0 && registrationId !== null) {
+        session.defaultSession.unregisterPreloadScript(registrationId);
+        registrationId = null;
+    }
+}
+//# sourceMappingURL=host-toolbar-session-runtime.js.map

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

@@ -1,6 +1,7 @@
 import type { WebContents } from 'electron';
 import type { NativeDeviceInfo } from '../../../shared/ipc-channels.js';
 import { type WorkbenchContext } from '../workbench-context.js';
+import { type HostToolbarMessageSubscription } from './host-toolbar-port-channel.js';
 /**
  * Context surface used by the ViewManager. We only need a small slice of the
  * full WorkbenchContext here; typing it this way documents the actual dependency.
@@ -23,12 +24,11 @@ export interface ViewManagerContext {
      * frame preload instead. Optional so partial test contexts compile.
      */
     preloadPath?: string;
-    panels: string[];
     notify: WorkbenchContext['notify'];
     bridge?: WorkbenchContext['bridge'];
     /**
      * Native-host network forwarder. `attachNativeSimulator` hands it the freshly
-     * created simulator WebContentsView (`attachSimulator`) so it can attach the
+     * created simulator WebContentsView (`networkForward.attachSimulator`) so it can attach the
      * CDP debugger, and the DevTools front-end host wc (`setDevtoolsHost`) so it can
      * inject that WCV's Network.* events into the native Network tab (service-host
      * console line is the fallback). Optional so partial test contexts compile.
@@ -43,12 +43,6 @@ export interface ViewManagerContext {
      * Optional so partial test contexts compile.
      */
     simulatorApis?: WorkbenchContext['simulatorApis'];
-    /**
-     * Header bar height in px, used to position overlay views below the header.
-     * Optional here so partial test contexts compile; `createWorkbenchContext`
-     * always supplies it (default 40).
-     */
-    headerHeight?: number;
 }
 /**
  * Unified lifecycle manager for Electron WebContentsView overlays.
@@ -64,23 +58,22 @@ export interface ViewManagerContext {
  * window's own renderer is the content root and is not managed here.
  */
 export interface ViewManager {
-    /**
-     * Create a DevTools view for the given simulator webContents and add it to
-     * the main window contentView (only when the `devtools` tab is the default
-     * tab; otherwise the view is created but not added yet).
-     */
-    attachSimulator(simWcId: number, simWidth: number): void;
     /**
      * NATIVE-HOST ONLY. Create the simulator itself as a top-level
      * WebContentsView (not a renderer `<webview>` guest) loading `simulatorUrl`,
-     * position it in the simulator panel region, and treat its webContents as
-     * THE simulator webContents (so `getSimulatorWebContents` resolves it and the
-     * spawn/SIMULATOR_EVENTS pipeline flows through it). This is required because
-     * Electron force-disables the `<webview>` tag inside a webview guest, so the
-     * default `<webview>`-in-`<webview>` topology can never host DeviceShell's
+     * and treat its webContents as THE simulator webContents (so
+     * `getSimulatorWebContents` resolves it and the spawn/SIMULATOR_EVENTS
+     * pipeline flows through it). This is required because Electron
+     * force-disables the `<webview>` tag inside a webview guest, so a
+     * `<webview>`-in-`<webview>` topology can never host DeviceShell's
      * per-page render-host `<webview>`s. A top-level WebContentsView's webContents
      * is NOT a guest and CAN host them. Then wires the DevTools/console view on
-     * top of it via `attachSimulator`. No-op (logs) when `preloadPath` is unset.
+     * top of it via `attachNativeSimulatorDevtoolsHost`. Neither view is added
+     * to the contentView here — both mount only when the renderer's view anchors
+     * publish a non-zero rect (`setNativeSimulatorViewBounds` /
+     * `setSimulatorDevtoolsBounds`). No-op (logs) when `preloadPath` is unset.
+     * `simWidth` rides the wire for schema compatibility but is unused: all
+     * geometry is anchor-published.
      */
     attachNativeSimulator(simulatorUrl: string, simWidth: number): void;
     /**
@@ -90,10 +83,6 @@ export interface ViewManager {
      * `windows/views.ts` module, which every detach call relied on.
      */
     detachSimulator(): void;
-    /** Reveal the existing DevTools view (idempotent). */
-    showSimulator(simWidth: number): void;
-    /** Remove (but do not destroy) the simulator view from the contentView. */
-    hideSimulator(): void;
     /** Lazy-create and show the settings overlay view. */
     showSettings(): Promise<void>;
     /** Remove the settings overlay view (kept around for next open). */
@@ -110,12 +99,6 @@ export interface ViewManager {
     getSimulatorWebContentsId(): number | null;
     /** Return the live webContents of the currently attached simulator, or null. */
     getSimulatorWebContents(): WebContents | null;
-    /** Return the last known simulator width. */
-    getLastSimWidth(): number;
-    /** Whether the simulator overlay is currently added to the contentView. */
-    isSimulatorAdded(): boolean;
-    /** Whether a DevTools view exists (created but maybe not added). */
-    hasSimulatorView(): boolean;
     /** Return the settings overlay's WebContents (for renderer-notifier). */
     getSettingsWebContents(): WebContents | null;
     /** Return the webContents ID of the settings overlay if alive, else null. */
@@ -151,10 +134,12 @@ export interface ViewManager {
      * pick it up automatically when they attach (`did-attach-webview`).
      */
     reapplySafeArea(device: NativeDeviceInfo | null): void;
-    /** Update lastSimWidth; reposition simulator + settings if they are added. */
+    /**
+     * Window-resize entry point. Re-applies the settings overlay's bounds only.
+     * Simulator + DevTools overlay geometry is anchor-published (the renderer's
+     * ResizeObserver re-measures on the same resize), so no static re-apply here.
+     */
     resize(simWidth: number): void;
-    /** Show or hide the simulator overlay based on visibility flag. */
-    setVisible(visible: boolean, simWidth: number): void;
     /**
      * Apply a renderer-measured rectangle to the simulator's Chromium
      * DevTools overlay view. `{ width: 0, height: 0 }` is treated as "hide" —
@@ -185,7 +170,9 @@ export interface ViewManager {
      * 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).
+     * dynamic-height loop). Ignored while a `{ fixed }` height mode is pinned
+     * via `hostToolbar.setHeightMode` (the session-resident advertiser always
+     * runs, so its reports must not fight a host-pinned height).
      */
     setHostToolbarHeight(extent: number): void;
     /**
@@ -195,6 +182,14 @@ export interface ViewManager {
      */
     readonly hostToolbar: HostToolbarControl;
 }
+/**
+ * Height mode for the host-toolbar placeholder strip. `'auto'` (default): the
+ * session-resident advertiser's reports drive the height. `{ fixed }`: the
+ * host pins the height; advertiser reports are ignored until `'auto'` again.
+ */
+export type HostToolbarHeightMode = 'auto' | {
+    fixed: number;
+};
 /**
  * The control object the downstream host uses to own the toolbar
  * WebContentsView. Lazily backed by the view-manager's `hostToolbarView`.
@@ -209,13 +204,59 @@ export interface HostToolbarControl {
     /** Remove the toolbar view from the contentView and reset it (kept alive). */
     hide(): void;
     /**
-     * Override the preload used when the toolbar view is first created. The
-     * host-shell (`launch(config)`) passes the host-controlled
-     * `toolbar.preloadPath` here; the host owns the bridge (it calls
-     * `exposeWorkbenchBridge()` itself). Must be set before the first
-     * `loadURL`/`loadFile`; `null` restores the built-in size-advertiser preload.
+     * The HOST's own `webPreferences.preload` for the toolbar view (purely
+     * additive). The framework's height-advertiser runtime does NOT ride
+     * `webPreferences.preload` — it is session-resident (registered on
+     * `session.defaultSession`, self-guarded by the `--dimina-host-toolbar`
+     * marker + `isMainFrame`), so a host preload set here coexists with it and
+     * never replaces it. Must be set before the view is (re)created (first
+     * `loadURL`/`loadFile`, or the next one after the host closed the
+     * webContents); `null` (default) means "no host preload" — it does not and
+     * cannot restore any built-in preload.
      */
     setPreloadPath(path: string | null): void;
+    /**
+     * Register a host-side handler for messages the toolbar PAGE sends via
+     * `window.diminaHostToolbar.send(channel, payload)`. Control-level: may be
+     * called before the view exists and survives page reloads / wc rebuilds
+     * (each per-load MessagePort handshake re-attaches the registry to the new
+     * port). Throws on an empty / non-string channel. `dispose()` detaches
+     * (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
+     * non-queueing: returns false — delivering nothing, creating no view —
+     * while there is no live toolbar webContents, the current load's
+     * MessagePort handshake hasn't completed, or a document-replacing
+     * navigation is in flight (`loadURL`/`loadFile` was issued, or the page
+     * itself started a main-frame cross-document navigation, and the new
+     * document hasn't handshaked yet); true once the envelope went out.
+     * No manual `getHostToolbarWebContentsId` gating needed: the false/true
+     * result IS the readiness signal.
+     */
+    send(channel: string, payload: unknown): boolean;
+    /**
+     * Pin or unpin the toolbar strip height. `{ fixed }` notifies the renderer
+     * placeholder with that height immediately (so a preload-less/static toolbar
+     * is visible without any advertiser report) and ignores subsequent advertiser
+     * reports. `'auto'` (default) re-enables advertiser-driven height starting
+     * from the NEXT report — it does not synthesize/replay a stale height.
+     */
+    setHeightMode(mode: HostToolbarHeightMode): void;
 }
 /**
  * Build a ViewManager bound to the given context. The returned object is the