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

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

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

@@ -0,0 +1,147 @@
+import { createManagedWebContentsView } from './managed-web-contents-view.js';
+/**
+ * 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 function deriveSlotControl(base, extra) {
+    return {
+        loadURL: (url) => base.loadURL(url),
+        loadFile: (filePath) => base.loadFile(filePath),
+        get webContents() {
+            return base.webContents;
+        },
+        hide: () => base.hide(),
+        setPreloadPath: (path) => base.setPreloadPath(path),
+        onMessage: (channel, handler) => base.onMessage(channel, handler),
+        onReady: (handler) => base.onReady(handler),
+        send: (channel, payload) => base.send(channel, payload),
+        ...extra,
+    };
+}
+/**
+ * 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 function createHostSlotView(reconciler, config, deps) {
+    let extentMode = 'auto';
+    let lastExtent = 0;
+    // The real current size the advertiser last reported, independent of
+    // `extentMode` — tracked separately from `lastExtent` (the last value we
+    // actually NOTIFIED) because `setExtent` still no-ops while fixed. Needed
+    // to reapply the true current size immediately when switching back to
+    // 'auto': the advertiser (measure-loop.ts) dedupes against its own last-
+    // EMITTED value, so if content stayed exactly the size it was before the
+    // switch to fixed, it will never re-report that value on its own.
+    let lastAdvertisedExtent = null;
+    const port = config.portChannel;
+    const managed = createManagedWebContentsView({
+        reconciler,
+        viewId: config.viewId,
+        marker: config.marker,
+        sessionRuntime: config.sessionRuntime,
+        port,
+    });
+    function notifyExtent(extent) {
+        lastExtent = extent;
+        deps.onExtentChanged(extent);
+        deps.reapplyPresentOverlays?.();
+    }
+    function setExtent(extent) {
+        lastAdvertisedExtent = extent;
+        if (extentMode !== 'auto')
+            return;
+        // Push the reserved extent back to the main-window renderer so its
+        // placeholder div resizes (closing the dynamic-size loop). The notified
+        // extent IS retained in main (`getExtent`) 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.
+        notifyExtent(extent);
+    }
+    function hideView() {
+        reconciler.setBaseDesired(config.viewId, {
+            viewId: config.viewId,
+            placement: { visible: false },
+            layer: config.layer,
+        });
+        reconciler.reconcileNow();
+        // Collapse the renderer placeholder to 0 too. Otherwise its anchor keeps a
+        // non-zero reserved extent and re-publishes bounds on the next window
+        // resize, silently re-adding the view we just hid (unstable hide). Zeroing
+        // the extent flips the anchor to `present:false` so it stops re-publishing.
+        // Through the funnel so the retained value follows to 0 — a renderer
+        // mounting after the hide must replay 0, not the stale pre-hide extent.
+        notifyExtent(0);
+        // Also clear the advertised-size memory: a hidden strip's pre-hide size is
+        // stale content state, not a value a later `setExtentMode('auto')` should
+        // resurrect (see the `lastAdvertisedExtent`-reapply branch below) — the
+        // advertiser (still mounted, unaware of the hide) reports the real size
+        // again on its own once content changes, or immediately on next mount.
+        lastAdvertisedExtent = null;
+    }
+    const control = {
+        loadURL: (url) => managed.loadURL(url),
+        loadFile: (filePath) => managed.loadFile(filePath),
+        get webContents() {
+            return managed.liveWebContents();
+        },
+        hide() {
+            hideView();
+        },
+        setPreloadPath: (path) => managed.setPreloadPath(path),
+        setExtentMode(mode) {
+            // Validate BEFORE touching any state: a poisoned `{ fixed }` (NaN /
+            // ±Infinity / negative) must neither reach the renderer placeholder
+            // (`extent: 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(`${config.setExtentModeErrorLabel}: fixed extent must be a finite, non-negative number (got ${mode.fixed})`);
+            }
+            extentMode = mode;
+            if (mode !== 'auto') {
+                // Pin immediately: a preload-less/static slot never advertises, so
+                // waiting for the next report would leave the strip at extent 0.
+                notifyExtent(mode.fixed);
+            }
+            else if (lastAdvertisedExtent !== null && lastAdvertisedExtent !== lastExtent) {
+                // Reapply the real current advertised size immediately rather than
+                // waiting for the next report — see `lastAdvertisedExtent`'s
+                // doc-comment above for why that report may never come. No-op when
+                // nothing has ever been advertised, or the advertised value already
+                // matches what's notified (avoids a spurious flash/duplicate push).
+                notifyExtent(lastAdvertisedExtent);
+            }
+        },
+        onMessage(channel, handler) {
+            return port.onMessage(channel, handler);
+        },
+        onReady(handler) {
+            return port.onReady(handler);
+        },
+        send(channel, payload) {
+            return port.send(channel, payload);
+        },
+    };
+    reconciler.registerView(config.viewId, {
+        getView: () => managed.getView(),
+        ensureView: () => managed.ensureView(),
+        ensureLazy: (desired) => {
+            if (desired?.placement.visible && !managed.liveWebContents())
+                managed.ensureView();
+        },
+    });
+    return {
+        control,
+        setExtent,
+        getExtent: () => lastExtent,
+        getWebContentsId: () => managed.liveWebContents()?.id ?? null,
+        dispose: () => managed.dispose(),
+    };
+}
+//# sourceMappingURL=host-slot-view.js.map