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

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

@@ -1,97 +1,12 @@
 /**
- * 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).
+ * Toolbar-specific instantiation of `createHostSlotPortChannel` (see that
+ * module for the full per-load handshake / navigation-invalidation
+ * contract).
  */
 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;
-}
+import { type HostSlotMessageSubscription, type HostSlotPortChannel } from './host-slot-port-channel.js';
+export type HostToolbarMessageSubscription = HostSlotMessageSubscription;
+export type HostToolbarPortChannel = HostSlotPortChannel;
 export declare function createHostToolbarPortChannel(opts: {
     /**
      * Is `wc` still the manager's CURRENT live toolbar webContents? Guards a

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

@@ -1,248 +1,15 @@
 /**
- * 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).
+ * Toolbar-specific instantiation of `createHostSlotPortChannel` (see that
+ * module for the full per-load handshake / navigation-invalidation
+ * contract).
  */
-import { MessageChannelMain } from 'electron';
-import { ViewChannel } from '../../../shared/ipc-channels.js';
+import { ViewChannel } from '../../../shared/ipc-channels-overlays.js';
+import { createHostSlotPortChannel, } from './host-slot-port-channel.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;
-        },
-    };
+    return createHostSlotPortChannel({
+        isCurrent: opts.isCurrent,
+        channel: ViewChannel.HostToolbarPort,
+        logPrefix: '[host-toolbar]',
+    });
 }
 //# sourceMappingURL=host-toolbar-port-channel.js.map

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

@@ -1,35 +1,10 @@
 /**
- * Ref-counted registration of the host-toolbar framework runtime on
- * `session.defaultSession`.
- *
- * The toolbar's height advertiser does not ride the toolbar WCV's
- * `webPreferences.preload`: a host's `setPreloadPath` would replace it and the
- * strip height would collapse 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: 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).
+ * Toolbar-specific instantiation of `createHostSlotSessionRuntime` (see that
+ * module for the full ref-counting contract). Kept as a thin, independently
+ * named wrapper rather than inlined into `host-toolbar-view.ts` because
+ * `host-toolbar-session-preload.test.ts` re-imports this module's state via
+ * `vi.resetModules()` per test.
  */
 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

@@ -1,55 +1,17 @@
 /**
- * Ref-counted registration of the host-toolbar framework runtime on
- * `session.defaultSession`.
- *
- * The toolbar's height advertiser does not ride the toolbar WCV's
- * `webPreferences.preload`: a host's `setPreloadPath` would replace it and the
- * strip height would collapse 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: 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.
+ * Toolbar-specific instantiation of `createHostSlotSessionRuntime` (see that
+ * module for the full ref-counting contract). Kept as a thin, independently
+ * named wrapper rather than inlined into `host-toolbar-view.ts` because
+ * `host-toolbar-session-preload.test.ts` re-imports this module's state via
+ * `vi.resetModules()` per test.
  */
-import { session } from 'electron';
+import { createHostSlotSessionRuntime } from './host-slot-session-runtime.js';
 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).
- */
+const runtime = createHostSlotSessionRuntime(hostToolbarRuntimePreloadPath);
 export function acquireHostToolbarSessionRuntime() {
-    if (refCount === 0) {
-        registrationId = session.defaultSession.registerPreloadScript({
-            type: 'frame',
-            filePath: hostToolbarRuntimePreloadPath,
-        });
-    }
-    refCount++;
+    runtime.acquire();
 }
-/**
- * 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;
-    }
+    runtime.release();
 }
 //# sourceMappingURL=host-toolbar-session-runtime.js.map

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

@@ -1,21 +1,48 @@
+import type { HostSlotControl } from './host-slot-view.js';
 import type { PlacementReconciler } from './placement-reconciler.js';
-import type { HostToolbarControl, ViewManagerContext } from './view-manager.js';
+import type { ViewManagerContext } from './view-manager.js';
 /**
- * A strip above the devtools header that the downstream host loads its own
- * content into and fully controls. Bounds come from a renderer DOM anchor
- * (forward anchor, like the simulator DevTools overlay); its height is dynamic
- * via a reverse size-advertiser the toolbar's own renderer drives.
+ * 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`.
+ * Derives the shared members (`loadURL`, `loadFile`, `webContents`, `hide`,
+ * `setPreloadPath`, `onMessage`, `onReady`, `send`) from `HostSlotControl` —
+ * see that interface for their contract, generalized from
+ * `window.diminaHostToolbar` to the axis-neutral "slot page" — and adds only
+ * `setHeightMode` in place of the base's `setExtentMode`.
+ */
+export interface HostToolbarControl extends Omit<HostSlotControl, 'setExtentMode'> {
+    /**
+     * 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;
+}
 export interface HostToolbarView {
     readonly control: HostToolbarControl;
     setHostToolbarHeight(extent: number): void;
     getHostToolbarHeight(): number;
     getHostToolbarWebContentsId(): number | null;
-    /** Teardown for `disposeAll`: sweep the port, destroy the view, release the runtime ref. */
     dispose(): void;
 }
+/**
+ * Toolbar-specific instantiation of `createHostSlotView` (see that module for
+ * the full lazy-create / port-channel / extent-mode contract). Kept as its own
+ * named wrapper — not inlined into `view-manager.ts` — to freeze the existing
+ * `HostToolbarControl`/`HostToolbarHeightMode` public surface independently of
+ * the generic slot's neutral naming.
+ */
 export declare function createHostToolbarView(ctx: ViewManagerContext, reconciler: PlacementReconciler, deps: {
-    /** Re-apply the settings/popover overlays whose height depends on the toolbar strip. */
     reapplyPresentOverlays(): void;
 }): HostToolbarView;
 //# sourceMappingURL=host-toolbar-view.d.ts.map