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

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

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

@@ -1,249 +1,42 @@
-import { WebContentsView } from 'electron';
-import { handleWindowOpenExternal } from '../../windows/navigation-hardening.js';
 import { HOST_TOOLBAR_RUNTIME_MARKER } from '../../../shared/constants.js';
 import { VIEW_ID, VIEW_LAYER } from '../../../shared/view-ids.js';
 import { acquireHostToolbarSessionRuntime, releaseHostToolbarSessionRuntime, } from './host-toolbar-session-runtime.js';
 import { createHostToolbarPortChannel } from './host-toolbar-port-channel.js';
-import { destroyChildView } from './destroy-child-view.js';
+import { createHostSlotView, deriveSlotControl } from './host-slot-view.js';
+/**
+ * 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 function createHostToolbarView(ctx, reconciler, deps) {
-    let hostToolbarView = null;
-    let hostToolbarPreloadOverride = null;
-    let hostToolbarViewAdded = false;
-    // Whether THIS manager holds a reference on the shared defaultSession
-    // registration of the toolbar-runtime preload (see
-    // host-toolbar-session-runtime.ts). Acquired on first toolbar need,
-    // released exactly once in dispose — a manager that never used the
-    // toolbar must not decrement a ref it never took.
-    let hostToolbarRuntimeAcquired = false;
-    // Placeholder height authority: 'auto' = advertiser reports forward to the
-    // renderer; { fixed } = host-pinned, advertiser reports are dropped.
-    let hostToolbarHeightMode = 'auto';
-    // Last toolbar height NOTIFIED to the main-window renderer — the replay
-    // source behind `getHostToolbarHeight()`. Updated ONLY inside
-    // `notifyHostToolbarHeight` so the retained value can never diverge from
-    // what the renderer was told (an advertiser report dropped by a `{ fixed }`
-    // pin must not pollute it, and a setHeightMode validation reject leaves it
-    // untouched).
-    let hostToolbarLastHeight = 0;
-    // Gated narrow channel to the toolbar PAGE (per-load MessagePort handshake;
-    // see host-toolbar-port-channel.ts). Control-level registry — created with
-    // the manager so onMessage() works before any toolbar view exists.
-    const hostToolbarPort = createHostToolbarPortChannel({
-        isCurrent: (wc) => liveHostToolbarWebContents() === wc,
+    const port = createHostToolbarPortChannel({
+        isCurrent: (wc) => slot.getWebContentsId() === wc.id,
     });
-    // The toolbar's webContents lifecycle belongs to the HOST, which may close
-    // it out from under us (the documented rebuild path). In real Electron a
-    // WebContentsView whose webContents was destroyed can report `webContents`
-    // as undefined — not merely a destroyed handle — so every access must
-    // tolerate BOTH (observed in the R1 e2e: `.isDestroyed()` on undefined threw
-    // inside the control surface after the host closed the wc).
-    function liveHostToolbarWebContents() {
-        const wc = hostToolbarView?.webContents;
-        if (!wc || wc.isDestroyed())
-            return null;
-        return wc;
-    }
-    // Lazily create the host-toolbar view. Mirrors `showSettings` for the
-    // webPreferences shape and the native simulator for nav hardening +
-    // background color (the host may load arbitrary URLs / content). Idempotent.
-    function ensureHostToolbarView() {
-        if (hostToolbarView && liveHostToolbarWebContents()) {
-            return hostToolbarView;
-        }
-        // Rebuilding after the host destroyed the underlying webContents: detach the
-        // dead view from the contentView and reset the added-flag so the new view
-        // gets re-mounted (otherwise the `hostToolbarViewAdded` guard would skip the
-        // addChildView and the toolbar would silently disappear).
-        if (hostToolbarView && hostToolbarViewAdded) {
-            try {
-                ctx.windows.mainWindow.contentView.removeChildView(hostToolbarView);
-            }
-            catch { /* already removed */ }
-            hostToolbarViewAdded = false;
-        }
-        // The instance is being replaced — forget its reconciled mount state so the
-        // rebuilt view is treated as a fresh attach (not skipped as already-attached).
-        reconciler.forgetActual(VIEW_ID.hostToolbar);
-        // The framework's height-advertiser runtime is SESSION-resident: register
-        // it on session.defaultSession (ref-counted across coexisting managers)
-        // BEFORE the view exists, so the very first load already runs it. The
-        // toolbar WCV stays on the defaultSession (no partition/session override)
-        // — moving it onto its own partition would silently detach it from this
-        // registration and height advertising would die with no error.
-        if (!hostToolbarRuntimeAcquired) {
-            acquireHostToolbarSessionRuntime();
-            hostToolbarRuntimeAcquired = true;
-        }
-        // `webPreferences.preload` is the HOST's alone (setPreloadPath); the
-        // built-in advertiser no longer rides it (it would execute twice — the
-        // session copy + the webPreferences copy). The additionalArguments marker
-        // is what the session runtime's guard keys on to activate here and stay a
-        // zero-footprint no-op in every other defaultSession renderer.
-        const webPreferences = {
-            nodeIntegration: false,
-            contextIsolation: true,
-            sandbox: false,
-            additionalArguments: [HOST_TOOLBAR_RUNTIME_MARKER],
-        };
-        if (hostToolbarPreloadOverride !== null) {
-            webPreferences.preload = hostToolbarPreloadOverride;
-        }
-        const view = new WebContentsView({ webPreferences });
-        hostToolbarView = view;
-        // Hook the per-load MessagePort handshake (did-finish-load) + dead-port
-        // cleanup (destroyed) on the fresh wc. AFTER the assignment above so the
-        // channel's isCurrent guard sees this wc as the live one.
-        hostToolbarPort.attach(view.webContents);
-        // Paint the surface a neutral color so growing the reserved strip never
-        // flashes white before the host content paints (mirrors the native
-        // simulator's setBackgroundColor anti-flash).
-        try {
-            view.setBackgroundColor('#121212');
-        }
-        catch { /* stub may lack it */ }
-        // The host may load arbitrary URLs; route popups + cross-origin in-place
-        // navigation to the OS browser (mirror the native simulator hardening).
-        try {
-            view.webContents.setWindowOpenHandler(({ url }) => handleWindowOpenExternal(url));
-        }
-        catch { /* stub may lack it */ }
-        return view;
-    }
-    // Single funnel for the height notify: retain-then-push, so the retained
-    // value is exactly the last value the renderer was told. Every height
-    // notify site MUST go through here — the renderer pulls the retained value
-    // on project-view mount to replay a push it missed (the toolbar's
-    // size-advertiser deduplicates and never re-reports).
-    function notifyHostToolbarHeight(height) {
-        hostToolbarLastHeight = height;
-        ctx.notify.hostToolbarHeightChanged(height);
-        deps.reapplyPresentOverlays();
-    }
-    function setHostToolbarHeight(extent) {
-        // While the host pins a fixed height, drop advertiser reports entirely —
-        // the session-resident advertiser is always installed, so forwarding its
-        // reports would make the strip oscillate between the pinned and measured
-        // heights on every content resize. Dropped reports must not touch the
-        // retained value either: retention records what was NOTIFIED, not what
-        // was reported.
-        if (hostToolbarHeightMode !== 'auto')
-            return;
-        // Push the reserved height back to the main-window renderer so its
-        // placeholder div resizes (closing the dynamic-height loop). The notified
-        // height IS retained in main (`getHostToolbarHeight`) so a renderer that
-        // mounts later can pull/replay it; the renderer placeholder remains the
-        // geometry authority — the forward anchor re-reports bounds from it.
-        notifyHostToolbarHeight(extent);
-    }
-    function hideHostToolbar() {
-        reconciler.setBaseDesired(VIEW_ID.hostToolbar, {
-            viewId: VIEW_ID.hostToolbar,
-            placement: { visible: false },
-            layer: VIEW_LAYER.hostToolbar,
-        });
-        reconciler.reconcileNow();
-        // Collapse the renderer placeholder to 0 too. Otherwise its anchor keeps a
-        // non-zero reserved height and re-publishes bounds on the next window
-        // resize, silently re-adding the view we just hid (unstable hide). Zeroing
-        // the height flips the anchor to `present:false` so it stops re-publishing.
-        // Through the funnel so the retained value follows to 0 — a renderer
-        // mounting after the hide must replay 0, not the stale pre-hide height.
-        notifyHostToolbarHeight(0);
-    }
-    const control = {
-        async loadURL(url) {
-            const view = ensureHostToolbarView();
-            // Invalidate SYNCHRONOUSLY at initiation, before the load is issued:
-            // the current document is about to be replaced, so a same-tick send()
-            // must report false instead of confirming delivery into it. The channel
-            // recovers on the new document's did-finish-load handshake. (Cannot
-            // rely on did-start-navigation here — that only covers page-initiated
-            // navigations once the load is actually under way.)
-            hostToolbarPort.invalidate();
-            await view.webContents.loadURL(url);
-        },
-        async loadFile(filePath) {
-            const view = ensureHostToolbarView();
-            // Same initiation-invalidates contract as loadURL above.
-            hostToolbarPort.invalidate();
-            await view.webContents.loadFile(filePath);
-        },
-        get webContents() {
-            return liveHostToolbarWebContents();
-        },
-        hide() {
-            hideHostToolbar();
-        },
-        setPreloadPath(path) {
-            // The HOST's own webPreferences.preload, applied when the view is next
-            // (re)created. `null` = no host preload. The framework advertiser is
-            // session-resident and unaffected either way (see ensureHostToolbarView).
-            hostToolbarPreloadOverride = path;
-        },
-        setHeightMode(mode) {
-            // Validate BEFORE touching any state: a poisoned `{ fixed }` (NaN /
-            // ±Infinity / negative) must neither reach the renderer placeholder
-            // (`height: NaNpx` corrupts the strip with no error anywhere) nor
-            // clobber the standing mode — fail-closed, not fail-corrupt.
-            if (mode !== 'auto' && !(Number.isFinite(mode.fixed) && mode.fixed >= 0)) {
-                throw new TypeError(`hostToolbar.setHeightMode: fixed height must be a finite, non-negative number (got ${mode.fixed})`);
-            }
-            hostToolbarHeightMode = mode;
-            if (mode !== 'auto') {
-                // Pin immediately: a preload-less/static toolbar never advertises, so
-                // waiting for the next report would leave the strip at height 0.
-                notifyHostToolbarHeight(mode.fixed);
-            }
-            // Switching back to 'auto' deliberately does NOT synthesize a notify —
-            // replaying a stale cached height would flash the old size; the NEXT
-            // advertiser report drives the placeholder again. The RETAINED value
-            // survives the switch though: a freshly-mounting renderer still needs
-            // the pinned height until that next report lands.
-        },
-        onMessage(channel, handler) {
-            return hostToolbarPort.onMessage(channel, handler);
-        },
-        onReady(handler) {
-            return hostToolbarPort.onReady(handler);
-        },
-        send(channel, payload) {
-            return hostToolbarPort.send(channel, payload);
-        },
-    };
-    reconciler.registerView(VIEW_ID.hostToolbar, {
-        getView: () => hostToolbarView,
-        ensureView: () => ensureHostToolbarView(),
-        setAdded: (added) => { hostToolbarViewAdded = added; },
-        ensureLazy: (desired) => {
-            if (desired?.placement.visible && !liveHostToolbarWebContents())
-                ensureHostToolbarView();
-        },
+    const slot = createHostSlotView(reconciler, {
+        viewId: VIEW_ID.hostToolbar,
+        layer: VIEW_LAYER.hostToolbar,
+        marker: HOST_TOOLBAR_RUNTIME_MARKER,
+        sessionRuntime: {
+            acquire: acquireHostToolbarSessionRuntime,
+            release: releaseHostToolbarSessionRuntime,
+        },
+        portChannel: port,
+        setExtentModeErrorLabel: 'hostToolbar.setHeightMode',
+    }, {
+        onExtentChanged: (height) => ctx.notify.hostToolbarHeightChanged(height),
+        reapplyPresentOverlays: () => deps.reapplyPresentOverlays(),
+    });
+    const control = deriveSlotControl(slot.control, {
+        setHeightMode: (mode) => slot.control.setExtentMode(mode),
     });
-    function dispose() {
-        // Narrow channel first: close the live MessagePort + sweep the onMessage
-        // registry, so a send() racing teardown reports false instead of posting
-        // into a wc that is about to be closed.
-        hostToolbarPort.dispose();
-        // Host-controllable toolbar view: removed from the contentView + its
-        // WebContents closed (the host's loaded content is torn down on app exit).
-        destroyChildView(ctx.windows.mainWindow, hostToolbarView);
-        hostToolbarView = null;
-        hostToolbarViewAdded = false;
-        // Release this manager's reference on the shared defaultSession
-        // toolbar-runtime registration (only if it ever acquired one — a manager
-        // that never used the toolbar must not drive the shared count to zero).
-        // The LAST release unregisters; other coexisting managers keep theirs.
-        if (hostToolbarRuntimeAcquired) {
-            releaseHostToolbarSessionRuntime();
-            hostToolbarRuntimeAcquired = false;
-        }
-    }
     return {
         control,
-        setHostToolbarHeight,
-        getHostToolbarHeight: () => hostToolbarLastHeight,
-        getHostToolbarWebContentsId: () => liveHostToolbarWebContents()?.id ?? null,
-        dispose,
+        setHostToolbarHeight: (extent) => slot.setExtent(extent),
+        getHostToolbarHeight: () => slot.getExtent(),
+        getHostToolbarWebContentsId: () => slot.getWebContentsId(),
+        dispose: () => slot.dispose(),
     };
 }
 //# sourceMappingURL=host-toolbar-view.js.map

package/dist/main/services/views/managed-web-contents-view.d.ts

@@ -0,0 +1,48 @@
+import type { WebContents } from 'electron';
+import { WebContentsView } from 'electron';
+import type { PlacementReconciler } from './placement-reconciler.js';
+import type { HostSlotPortChannel } from './host-slot-port-channel.js';
+export interface ManagedWebContentsViewOptions {
+    reconciler: PlacementReconciler;
+    viewId: string;
+    /** `--dimina-host-*` marker passed as `additionalArguments`, self-guards the session-resident advertiser preload. */
+    marker: string;
+    sessionRuntime: {
+        acquire(): void;
+        release(): void;
+    };
+    /** The per-load handshake channel; shares this view's lazy-create/liveness/dispose lifecycle. */
+    port: HostSlotPortChannel;
+    /**
+     * Fires after a crashed/failed view has been torn down (see `ensureView`'s
+     * `render-process-gone`/`did-fail-load` handling below). The base slots
+     * (host-toolbar/host-sidebar) don't need this — their `ensureLazy` already
+     * rebuilds a fresh view on the next reconcile pass once `liveWebContents()`
+     * correctly reports the crash. host-dialog does: its on-demand placement
+     * (`visible` flag, `overlayDesired`) isn't reconciler-driven the same way,
+     * so without this a stale `visible: true` would resurrect a blank,
+     * content-less modal on the next reposition (e.g. a window resize).
+     */
+    onBroken?(): void;
+}
+/**
+ * Shared lazy-create / liveness / load / teardown lifecycle for the
+ * host-controllable WebContentsViews (host-toolbar, host-sidebar,
+ * host-dialog): a single `WebContentsView` recreated on demand when the
+ * previous one dies, backed by a ref-counted session-runtime registration and
+ * the per-load port-channel attach. Placement (persistent strip vs by-demand
+ * centered overlay) is layered on top by the caller — this module only owns
+ * "is there a live view, and (re)create/load/tear it down when needed."
+ */
+export interface ManagedWebContentsView {
+    loadURL(url: string): Promise<void>;
+    loadFile(filePath: string): Promise<void>;
+    liveWebContents(): WebContents | null;
+    /** Raw view accessor for `reconciler.registerView`'s `getView` slot (may be non-null with a destroyed webContents). */
+    getView(): WebContentsView | null;
+    setPreloadPath(path: string | null): void;
+    ensureView(): WebContentsView;
+    dispose(): void;
+}
+export declare function createManagedWebContentsView(opts: ManagedWebContentsViewOptions): ManagedWebContentsView;
+//# sourceMappingURL=managed-web-contents-view.d.ts.map

package/dist/main/services/views/managed-web-contents-view.js

@@ -0,0 +1,123 @@
+import { WebContentsView } from 'electron';
+import { handleWindowOpenExternal } from '../../windows/navigation-hardening.js';
+export function createManagedWebContentsView(opts) {
+    let view = null;
+    let preloadOverride = null;
+    let runtimeAcquired = false;
+    function liveWebContents() {
+        const wc = view?.webContents;
+        if (!wc || wc.isDestroyed())
+            return null;
+        return wc;
+    }
+    // `liveWebContents()`'s `!wc.isDestroyed()` alone cannot tell "alive" from
+    // "alive but broken" — a crashed renderer process or a failed main-frame
+    // load leaves `webContents` non-destroyed but blank/unresponsive, so
+    // without this the same dead view (still fielding clicks if it's an
+    // on-screen slot) would be handed back to every future `ensureView()`
+    // forever, and the host's own `webContents` getter would keep reporting it
+    // as live. Guarded by `view !== current` so a listener from an already-
+    // superseded instance can't tear down the CURRENT one.
+    function teardown(current, detail) {
+        if (view !== current)
+            return;
+        console.error(`[${opts.viewId}] ${detail} — destroying so the next ensureView() rebuilds`);
+        view = null;
+        opts.reconciler.destroyView(opts.viewId, current);
+        opts.onBroken?.();
+    }
+    function ensureView() {
+        if (view && liveWebContents()) {
+            return view;
+        }
+        if (view) {
+            opts.reconciler.destroyView(opts.viewId, view);
+        }
+        if (!runtimeAcquired) {
+            opts.sessionRuntime.acquire();
+            runtimeAcquired = true;
+        }
+        const webPreferences = {
+            nodeIntegration: false,
+            contextIsolation: true,
+            sandbox: false,
+            additionalArguments: [opts.marker],
+        };
+        if (preloadOverride !== null) {
+            webPreferences.preload = preloadOverride;
+        }
+        const next = new WebContentsView({ webPreferences });
+        view = next;
+        opts.port.attach(next.webContents);
+        try {
+            next.setBackgroundColor('#121212');
+        }
+        catch {
+            /* stub may lack it */
+        }
+        try {
+            next.webContents.setWindowOpenHandler(({ url }) => handleWindowOpenExternal(url));
+        }
+        catch {
+            /* stub may lack it */
+        }
+        next.webContents.on('did-fail-load', (_event, errorCode, _errorDescription, _validatedURL, isMainFrame) => {
+            // -3 is ERR_ABORTED, which fires on every routine superseded navigation
+            // (e.g. a fresh loadURL/loadFile cancelling this one) — not a real failure.
+            if (!isMainFrame || errorCode === -3)
+                return;
+            teardown(next, `did-fail-load (code ${errorCode})`);
+        });
+        next.webContents.on('render-process-gone', (_event, details) => {
+            teardown(next, `render-process-gone (${details.reason})`);
+        });
+        return next;
+    }
+    return {
+        async loadURL(url) {
+            const v = ensureView();
+            // Invalidate SYNCHRONOUSLY at initiation, before the load is issued:
+            // the current document is about to be replaced, so a same-tick send()
+            // must report false instead of confirming delivery into it. The channel
+            // recovers on the new document's did-finish-load handshake. (Cannot
+            // rely on did-start-navigation here — that only covers page-initiated
+            // navigations once the load is actually under way.)
+            opts.port.invalidate();
+            await v.webContents.loadURL(url);
+        },
+        async loadFile(filePath) {
+            const v = ensureView();
+            // Same initiation-invalidates contract as loadURL above.
+            opts.port.invalidate();
+            await v.webContents.loadFile(filePath);
+        },
+        liveWebContents,
+        getView: () => view,
+        setPreloadPath(path) {
+            // The HOST's own webPreferences.preload, applied when the view is next
+            // (re)created. `null` = no host preload. The framework advertiser is
+            // session-resident and unaffected either way (see ensureView).
+            preloadOverride = path;
+        },
+        ensureView,
+        dispose() {
+            // Narrow channel first: close the live MessagePort + sweep the onMessage
+            // registry, so a send() racing teardown reports false instead of posting
+            // into a wc that is about to be closed.
+            opts.port.dispose();
+            // Host-controllable slot view: removed from the contentView + its
+            // WebContents closed (the host's loaded content is torn down on app exit).
+            opts.reconciler.destroyView(opts.viewId, view);
+            view = null;
+            // Release this manager's reference on the shared defaultSession
+            // slot-runtime registration (only if it ever acquired one — a manager
+            // that never used the slot must not drive the shared count to zero).
+            // The LAST release unregisters; other coexisting managers keep theirs.
+            if (runtimeAcquired) {
+                opts.sessionRuntime.release();
+                runtimeAcquired = false;
+            }
+        },
+    };
+}
+//# sourceMappingURL=managed-web-contents-view.js.map