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

package/dist/main/services/views/host-sidebar-view.js

@@ -0,0 +1,44 @@
+import { HOST_SIDEBAR_RUNTIME_MARKER } from '../../../shared/constants.js';
+import { VIEW_ID, VIEW_LAYER } from '../../../shared/view-ids.js';
+import { acquireHostSidebarSessionRuntime, releaseHostSidebarSessionRuntime, } from './host-sidebar-session-runtime.js';
+import { createHostSidebarPortChannel } from './host-sidebar-port-channel.js';
+import { createHostSlotView, deriveSlotControl } from './host-slot-view.js';
+/**
+ * Sidebar-specific instantiation of `createHostSlotView` (see that module for
+ * the full lazy-create / port-channel / extent-mode contract). Symmetric to
+ * `createHostToolbarView` on the inline (width) axis instead of block
+ * (height) — the slot itself is axis-agnostic (a single advertised extent
+ * number); which CSS dimension it resizes is decided entirely by the host's
+ * renderer placeholder layout, not here. The sidebar never coexists with the
+ * settings/popover/tooltip overlays, so unlike the toolbar there is no
+ * `reapplyPresentOverlays` dependency to thread through.
+ */
+export function createHostSidebarView(ctx, reconciler) {
+    const port = createHostSidebarPortChannel({
+        isCurrent: (wc) => slot.getWebContentsId() === wc.id,
+    });
+    const slot = createHostSlotView(reconciler, {
+        viewId: VIEW_ID.hostSidebar,
+        layer: VIEW_LAYER.hostSidebar,
+        marker: HOST_SIDEBAR_RUNTIME_MARKER,
+        sessionRuntime: {
+            acquire: acquireHostSidebarSessionRuntime,
+            release: releaseHostSidebarSessionRuntime,
+        },
+        portChannel: port,
+        setExtentModeErrorLabel: 'hostSidebar.setWidthMode',
+    }, {
+        onExtentChanged: (width) => ctx.notify.hostSidebarWidthChanged(width),
+    });
+    const control = deriveSlotControl(slot.control, {
+        setWidthMode: (mode) => slot.control.setExtentMode(mode),
+    });
+    return {
+        control,
+        setHostSidebarWidth: (extent) => slot.setExtent(extent),
+        getHostSidebarWidth: () => slot.getExtent(),
+        getHostSidebarWebContentsId: () => slot.getWebContentsId(),
+        dispose: () => slot.dispose(),
+    };
+}
+//# sourceMappingURL=host-sidebar-view.js.map

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

@@ -0,0 +1,107 @@
+/**
+ * Gated narrow channel between the main process and a downstream host-slot
+ * WebContentsView's page (host-toolbar / host-sidebar / host-dialog), over a
+ * per-load transferred MessagePort.
+ *
+ * Why a MessagePort and not plain IPC: a slot's 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 internal devtools channels, and main-side inbound traffic is
+ * validated at this single waist.
+ *
+ * Lifecycle (per-load handshake):
+ *  - On every slot-wc `did-finish-load` main builds a fresh
+ *    `MessageChannelMain`, transfers port2 to the new document via
+ *    `wc.postMessage(opts.channel, 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 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 `loadURL/loadFile` calls `invalidate()`
+ *          synchronously AT INITIATION (the slot view 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 HostSlotMessageSubscription {
+    dispose(): void;
+}
+export interface HostSlotPortChannel {
+    /**
+     * Hook a freshly created slot webContents: registers the `did-finish-load`
+     * (per-load handshake) and `destroyed` (drop the live port) listeners via
+     * `wc.on(...)`. Call exactly once per wc, right after the view is created.
+     */
+    attach(wc: WebContents): void;
+    /**
+     * Drop the live port NOW (close + clear): the document it belongs to is
+     * being replaced. Called 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): HostSlotMessageSubscription;
+    /**
+     * 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): HostSlotMessageSubscription;
+    /**
+     * Post `{ channel, payload }` to the slot page over the live port. Returns
+     * false (delivering NOTHING, creating NOTHING) when there is no live slot
+     * 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 (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 createHostSlotPortChannel(opts: {
+    /**
+     * Is `wc` still the manager's CURRENT live slot 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;
+    /** The IPC channel name used for the per-load port-transfer postMessage. */
+    channel: string;
+    /** Log-line prefix identifying which slot this instance belongs to. */
+    logPrefix: string;
+}): HostSlotPortChannel;
+//# sourceMappingURL=host-slot-port-channel.d.ts.map

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

@@ -0,0 +1,261 @@
+/**
+ * Gated narrow channel between the main process and a downstream host-slot
+ * WebContentsView's page (host-toolbar / host-sidebar / host-dialog), over a
+ * per-load transferred MessagePort.
+ *
+ * Why a MessagePort and not plain IPC: a slot's 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 internal devtools channels, and main-side inbound traffic is
+ * validated at this single waist.
+ *
+ * Lifecycle (per-load handshake):
+ *  - On every slot-wc `did-finish-load` main builds a fresh
+ *    `MessageChannelMain`, transfers port2 to the new document via
+ *    `wc.postMessage(opts.channel, 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 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 `loadURL/loadFile` calls `invalidate()`
+ *          synchronously AT INITIATION (the slot view 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';
+export function createHostSlotPortChannel(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 slot 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]) {
+            // Exception isolation, same posture as `invokeReadyHandler`: these are
+            // arbitrary host-registered handlers running inside a `MessagePortMain`
+            // 'message' listener — an uncaught throw here escapes straight to
+            // process-level `uncaughtException`, and would also starve every
+            // sibling handler still due to run for this message. Report-and-continue.
+            if (entry.channel === channel)
+                invokeMessageHandler(entry.handler, payload);
+        }
+    }
+    function invokeMessageHandler(handler, payload) {
+        try {
+            handler(payload);
+        }
+        catch (err) {
+            console.error(`${opts.logPrefix} onMessage handler threw:`, err);
+        }
+    }
+    /**
+     * 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(`${opts.logPrefix} 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(opts.channel, 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(`${opts.logPrefix} 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-slot-port-channel.js.map

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

@@ -0,0 +1,40 @@
+/**
+ * Ref-counted registration of a downstream-host-slot framework runtime on
+ * `session.defaultSession`.
+ *
+ * A slot's size advertiser does not ride the slot WCV's `webPreferences.preload`:
+ * a host's `setPreloadPath` would replace it and the reserved strip/pane would
+ * collapse to 0. Instead the runtime bundle is registered once per process as a
+ * session frame preload; its own guard (an `additionalArguments` 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
+ * slot 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 slot runtime.
+ *
+ * Each `createHostSlotSessionRuntime(preloadPath)` call owns its own
+ * independent ref-count closure (one instance per slot TYPE, e.g. toolbar vs.
+ * sidebar), never a cross-slot shared counter. Module-level state per call site
+ * that binds one; tests reset it via `vi.resetModules()` + re-import.
+ */
+export interface HostSlotSessionRuntime {
+    /**
+     * 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).
+     */
+    acquire(): void;
+    /**
+     * Release a reference. Unregisters (with the stored registration id) only when
+     * the LAST reference is released; a still-alive ViewManager's slot keeps its
+     * session runtime. Safe to call only by managers that actually acquired.
+     */
+    release(): void;
+}
+export declare function createHostSlotSessionRuntime(preloadPath: string): HostSlotSessionRuntime;
+//# sourceMappingURL=host-slot-session-runtime.d.ts.map

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

@@ -0,0 +1,50 @@
+/**
+ * Ref-counted registration of a downstream-host-slot framework runtime on
+ * `session.defaultSession`.
+ *
+ * A slot's size advertiser does not ride the slot WCV's `webPreferences.preload`:
+ * a host's `setPreloadPath` would replace it and the reserved strip/pane would
+ * collapse to 0. Instead the runtime bundle is registered once per process as a
+ * session frame preload; its own guard (an `additionalArguments` 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
+ * slot 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 slot runtime.
+ *
+ * Each `createHostSlotSessionRuntime(preloadPath)` call owns its own
+ * independent ref-count closure (one instance per slot TYPE, e.g. toolbar vs.
+ * sidebar), never a cross-slot shared counter. Module-level state per call site
+ * that binds one; tests reset it via `vi.resetModules()` + re-import.
+ */
+import { session } from 'electron';
+export function createHostSlotSessionRuntime(preloadPath) {
+    let refCount = 0;
+    let registrationId = null;
+    return {
+        acquire() {
+            if (refCount === 0) {
+                registrationId = session.defaultSession.registerPreloadScript({
+                    type: 'frame',
+                    filePath: preloadPath,
+                });
+            }
+            refCount++;
+        },
+        release() {
+            if (refCount === 0)
+                return;
+            refCount--;
+            if (refCount === 0 && registrationId !== null) {
+                session.defaultSession.unregisterPreloadScript(registrationId);
+                registrationId = null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=host-slot-session-runtime.js.map

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

@@ -0,0 +1,109 @@
+import type { WebContents } from 'electron';
+import type { PlacementReconciler } from './placement-reconciler.js';
+import type { HostSlotMessageSubscription, HostSlotPortChannel } from './host-slot-port-channel.js';
+export type HostSlotExtentMode = 'auto' | {
+    fixed: number;
+};
+/**
+ * The control surface a downstream host uses to own a persistent, single-axis
+ * slot's WebContentsView (host-toolbar, host-sidebar). Axis-neutral base for
+ * `HostToolbarControl`/`HostSidebarControl`, which each derive from it via
+ * `Omit<HostSlotControl, 'setExtentMode'>` and rename that one member to the
+ * axis-specific `setHeightMode`/`setWidthMode` — see either for the frozen,
+ * per-slot public surface these members ship under.
+ */
+export interface HostSlotControl {
+    /** Load a URL into the slot's view (lazy-creates the view). */
+    loadURL(url: string): Promise<void>;
+    /** Load a local file into the slot's view (lazy-creates the view). */
+    loadFile(filePath: string): Promise<void>;
+    /** The slot's live WebContents, or null if not yet created/destroyed. */
+    readonly webContents: WebContents | null;
+    /** Remove the slot's view from the contentView and reset it (kept alive). */
+    hide(): void;
+    /**
+     * The HOST's own `webPreferences.preload` for the slot's view (purely
+     * additive). The framework's advertiser runtime does NOT ride
+     * `webPreferences.preload` — it is session-resident (registered on
+     * `session.defaultSession`, self-guarded by the slot's own 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;
+    setExtentMode(mode: HostSlotExtentMode): void;
+    /**
+     * Register a host-side handler for messages the slot PAGE sends over its
+     * gated port channel. 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): HostSlotMessageSubscription;
+    /**
+     * 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): HostSlotMessageSubscription;
+    /**
+     * Post `{ channel, payload }` to the slot page (received via the page's
+     * `onMessage(channel, handler)`). Gated and non-queueing: returns false —
+     * delivering nothing, creating no view — while there is no live slot
+     * 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 webContentsId gating needed: the false/true
+     * result IS the readiness signal.
+     */
+    send(channel: string, payload: unknown): boolean;
+}
+/**
+ * Build an axis-specific control surface (`HostToolbarControl`/
+ * `HostSidebarControl`) from `createHostSlotView`'s underlying `slot.control`
+ * plus that one axis's renamed extent-mode setter. Forwards every shared
+ * member explicitly (not a shallow spread) so the `webContents` accessor
+ * stays a LIVE getter into `base` rather than a one-time snapshot.
+ */
+export declare function deriveSlotControl<Extra extends Record<string, unknown>>(base: HostSlotControl, extra: Extra): Omit<HostSlotControl, 'setExtentMode'> & Extra;
+export interface HostSlotView {
+    readonly control: HostSlotControl;
+    setExtent(extent: number): void;
+    getExtent(): number;
+    getWebContentsId(): number | null;
+    dispose(): void;
+}
+export interface HostSlotConfig {
+    viewId: string;
+    layer: number;
+    marker: string;
+    sessionRuntime: {
+        acquire(): void;
+        release(): void;
+    };
+    portChannel: HostSlotPortChannel;
+    /** Prefix for the `setExtentMode` fixed-value validation error, e.g. `'hostToolbar.setHeightMode'`. */
+    setExtentModeErrorLabel: string;
+}
+/**
+ * Shared implementation behind the persistent, single-axis host slots
+ * (host-toolbar, host-sidebar): lazily-created `WebContentsView` + ref-counted
+ * session runtime + per-load port-channel handshake + `setBaseDesired`
+ * placement, with an auto/fixed extent mode reported back through
+ * `deps.onExtentChanged`. See `host-toolbar-view.ts` for the frozen
+ * toolbar-shaped public wrapper.
+ */
+export declare function createHostSlotView(reconciler: PlacementReconciler, config: HostSlotConfig, deps: {
+    onExtentChanged(extent: number): void;
+    reapplyPresentOverlays?(): void;
+}): HostSlotView;
+//# sourceMappingURL=host-slot-view.d.ts.map