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

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

@@ -0,0 +1,147 @@
+import { HOST_DIALOG_RUNTIME_MARKER } from '../../../shared/constants.js';
+import { VIEW_ID, VIEW_LAYER } from '../../../shared/view-ids.js';
+import { acquireHostDialogSessionRuntime, releaseHostDialogSessionRuntime, } from './host-dialog-session-runtime.js';
+import { createHostDialogPortChannel } from './host-dialog-port-channel.js';
+import { createManagedWebContentsView } from './managed-web-contents-view.js';
+// Shown immediately on `show()` for whichever axis hasn't been measured yet.
+// The dialog is a by-demand overlay — there is no renderer placeholder to
+// pre-report intrinsic size the way the toolbar/sidebar's forward anchor
+// does, so the first show of a not-yet-measured axis has nothing to center
+// against. Waiting/polling for the report would mask the async race (banned
+// by this repo's timing rules); a conservative default plus a re-center the
+// moment `reportMeasuredExtent` lands is the fail-safe alternative.
+const DEFAULT_WIDTH = 480;
+const DEFAULT_HEIGHT = 320;
+/**
+ * Host-dialog factory — its PLACEMENT is deliberately NOT built on
+ * `createHostSlotView`. That factory models a persistent, single-axis,
+ * renderer-anchored strip (`setBaseDesired`); the dialog is a by-demand,
+ * dual-axis, main-centered overlay (`setOverlayDesired` /
+ * `deleteOverlayDesired`), closer in shape to the settings/popover/tooltip
+ * overlays in `overlay-panels-view.ts` than to the toolbar/sidebar. It still
+ * doesn't reuse `createOverlayPanel` from that file: those panels load a
+ * FIXED renderer-dir entry and push typed data, whereas the dialog loads
+ * ARBITRARY host content and needs the toolbar/sidebar's `loadURL`/`loadFile`
+ * + gated port-channel surface. The underlying WebContentsView lazy-create /
+ * liveness / load / teardown lifecycle IS shared with the base slots though
+ * — see `managed-web-contents-view.ts`.
+ */
+export function createHostDialogView(ctx, reconciler) {
+    const port = createHostDialogPortChannel({
+        isCurrent: (wc) => managed.liveWebContents()?.id === wc.id,
+    });
+    let visible = false;
+    let width = DEFAULT_WIDTH;
+    let height = DEFAULT_HEIGHT;
+    const managed = createManagedWebContentsView({
+        reconciler,
+        viewId: VIEW_ID.hostDialog,
+        marker: HOST_DIALOG_RUNTIME_MARKER,
+        sessionRuntime: {
+            acquire: acquireHostDialogSessionRuntime,
+            release: releaseHostDialogSessionRuntime,
+        },
+        port,
+        onBroken: () => {
+            // Same "withdraw the stale desired placement" contract as hide(): a
+            // crashed dialog must not resurrect as a blank, content-less modal the
+            // next time something calls reposition() (e.g. a window resize).
+            visible = false;
+            reconciler.deleteOverlayDesired(VIEW_ID.hostDialog);
+        },
+    });
+    function computeBounds() {
+        const [winW = 0, winH = 0] = ctx.windows.mainWindow.getContentSize();
+        // Clamp to the window so a dialog whose advertised/default size exceeds
+        // the current content area still gets valid non-negative bounds instead
+        // of spilling off-window or going negative.
+        const w = Math.min(width, Math.max(1, winW));
+        const h = Math.min(height, Math.max(1, winH));
+        return {
+            x: Math.max(0, Math.round((winW - w) / 2)),
+            y: Math.max(0, Math.round((winH - h) / 2)),
+            width: w,
+            height: h,
+        };
+    }
+    function present() {
+        reconciler.setOverlayDesired(VIEW_ID.hostDialog, {
+            viewId: VIEW_ID.hostDialog,
+            placement: { visible: true, bounds: computeBounds() },
+            layer: VIEW_LAYER.hostDialog,
+        });
+        reconciler.reconcileNow();
+    }
+    function reportMeasuredExtent(axis, extent) {
+        if (!Number.isFinite(extent) || extent <= 0)
+            return;
+        if (axis === 'inline') {
+            width = extent;
+        }
+        else {
+            height = extent;
+        }
+        if (visible)
+            present();
+    }
+    // The host swaps content into the SAME dialog view via loadURL/loadFile
+    // (e.g. re-purposing one dialog for a different prompt) — width/height are
+    // this factory's own closure state, seeded once from the DEFAULT_*
+    // constants and only ever mutated by reportMeasuredExtent, so without a
+    // reset here a fresh, unmeasured document would inherit the PREVIOUS
+    // document's size until it happens to report its own. And while the
+    // dialog is currently VISIBLE, resetting the closure state alone doesn't
+    // reach the screen — the on-screen bounds only change via `present()` —
+    // so without the same `if (visible) present()` `reportMeasuredExtent`
+    // already does, the OLD document's bounds would stay displayed
+    // indefinitely (forever, if the new document never reports at all, e.g. a
+    // fixture missing `[data-host-dialog-root]`) instead of falling back to
+    // the default the moment the swap happens.
+    function resetMeasuredExtent() {
+        width = DEFAULT_WIDTH;
+        height = DEFAULT_HEIGHT;
+        if (visible)
+            present();
+    }
+    const control = {
+        loadURL: (url) => {
+            resetMeasuredExtent();
+            return managed.loadURL(url);
+        },
+        loadFile: (filePath) => {
+            resetMeasuredExtent();
+            return managed.loadFile(filePath);
+        },
+        get webContents() {
+            return managed.liveWebContents();
+        },
+        setPreloadPath: (path) => managed.setPreloadPath(path),
+        onMessage: (channel, handler) => port.onMessage(channel, handler),
+        onReady: (handler) => port.onReady(handler),
+        send: (channel, payload) => port.send(channel, payload),
+        show() {
+            managed.ensureView();
+            visible = true;
+            present();
+        },
+        hide() {
+            visible = false;
+            reconciler.deleteOverlayDesired(VIEW_ID.hostDialog);
+            reconciler.reconcileNow();
+        },
+        isVisible: () => visible,
+    };
+    reconciler.registerView(VIEW_ID.hostDialog, {
+        getView: () => managed.getView(),
+        ensureView: () => managed.ensureView(),
+    });
+    return {
+        control,
+        reportMeasuredExtent,
+        getHostDialogWebContentsId: () => managed.liveWebContents()?.id ?? null,
+        reposition: () => { if (visible)
+            present(); },
+        dispose: () => managed.dispose(),
+    };
+}
+//# sourceMappingURL=host-dialog-view.js.map

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

@@ -0,0 +1,18 @@
+/**
+ * Sidebar-specific instantiation of `createHostSlotPortChannel` (see that
+ * module for the full per-load handshake / navigation-invalidation
+ * contract).
+ */
+import type { WebContents } from 'electron';
+import { type HostSlotMessageSubscription, type HostSlotPortChannel } from './host-slot-port-channel.js';
+export type HostSidebarMessageSubscription = HostSlotMessageSubscription;
+export type HostSidebarPortChannel = HostSlotPortChannel;
+export declare function createHostSidebarPortChannel(opts: {
+    /**
+     * Is `wc` still the manager's CURRENT live sidebar 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;
+}): HostSidebarPortChannel;
+//# sourceMappingURL=host-sidebar-port-channel.d.ts.map

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

@@ -0,0 +1,15 @@
+/**
+ * Sidebar-specific instantiation of `createHostSlotPortChannel` (see that
+ * module for the full per-load handshake / navigation-invalidation
+ * contract).
+ */
+import { ViewChannel } from '../../../shared/ipc-channels-overlays.js';
+import { createHostSlotPortChannel, } from './host-slot-port-channel.js';
+export function createHostSidebarPortChannel(opts) {
+    return createHostSlotPortChannel({
+        isCurrent: opts.isCurrent,
+        channel: ViewChannel.HostSidebarPort,
+        logPrefix: '[host-sidebar]',
+    });
+}
+//# sourceMappingURL=host-sidebar-port-channel.js.map

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

@@ -0,0 +1,10 @@
+/**
+ * Sidebar-specific instantiation of `createHostSlotSessionRuntime` (see that
+ * module for the full ref-counting contract). Kept as a thin, independently
+ * named wrapper — same rationale as `host-toolbar-session-runtime.ts` — so
+ * a sidebar-focused test can `vi.resetModules()` this module's state without
+ * touching the toolbar's independent ref-count.
+ */
+export declare function acquireHostSidebarSessionRuntime(): void;
+export declare function releaseHostSidebarSessionRuntime(): void;
+//# sourceMappingURL=host-sidebar-session-runtime.d.ts.map

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

@@ -0,0 +1,17 @@
+/**
+ * Sidebar-specific instantiation of `createHostSlotSessionRuntime` (see that
+ * module for the full ref-counting contract). Kept as a thin, independently
+ * named wrapper — same rationale as `host-toolbar-session-runtime.ts` — so
+ * a sidebar-focused test can `vi.resetModules()` this module's state without
+ * touching the toolbar's independent ref-count.
+ */
+import { createHostSlotSessionRuntime } from './host-slot-session-runtime.js';
+import { hostSidebarRuntimePreloadPath } from '../../utils/paths.js';
+const runtime = createHostSlotSessionRuntime(hostSidebarRuntimePreloadPath);
+export function acquireHostSidebarSessionRuntime() {
+    runtime.acquire();
+}
+export function releaseHostSidebarSessionRuntime() {
+    runtime.release();
+}
+//# sourceMappingURL=host-sidebar-session-runtime.js.map

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

@@ -0,0 +1,59 @@
+import type { HostSlotControl } from './host-slot-view.js';
+import type { PlacementReconciler } from './placement-reconciler.js';
+import type { ViewManagerContext } from './view-manager.js';
+/**
+ * Width mode for the host-sidebar placeholder strip, mirroring
+ * `HostToolbarHeightMode` on the inline axis.
+ */
+export type HostSidebarWidthMode = 'auto' | {
+    fixed: number;
+};
+/**
+ * The control object the downstream host uses to own the sidebar
+ * WebContentsView. Derives the shared members from `HostSlotControl` — see
+ * that interface for their contract, which carries over unchanged on the
+ * inline axis — and adds only `setWidthMode` in place of the base's
+ * `setExtentMode`, mirroring `HostToolbarControl.setHeightMode`.
+ */
+export interface HostSidebarControl extends Omit<HostSlotControl, 'setExtentMode'> {
+    /**
+     * Pin or unpin the sidebar strip width. Same contract as
+     * `HostToolbarControl.setHeightMode` on the inline axis.
+     */
+    setWidthMode(mode: HostSidebarWidthMode): void;
+}
+/**
+ * The host-sidebar slice of `ViewManager`'s public surface, split into its
+ * own file (mixed in via `extends`) to keep view-manager.ts under the repo's
+ * file-length ratchet. Mirrors `hostToolbar`'s members on the inline axis;
+ * never coexists with a height-cycle dependency on settings/popover/tooltip.
+ */
+export interface HostSidebarViewManagerMembers {
+    /** Return the webContents ID of the host-sidebar overlay if alive, else null. */
+    getHostSidebarWebContentsId(): number | null;
+    /** Return the last host-sidebar width NOTIFIED to the main-window renderer. */
+    getHostSidebarWidth(): number;
+    /** Reverse size-advertiser sink for the sidebar strip's inline (width) axis. */
+    setHostSidebarWidth(extent: number): void;
+    /** Host-facing control surface for the sidebar WebContentsView. */
+    readonly hostSidebar: HostSidebarControl;
+}
+export interface HostSidebarView {
+    readonly control: HostSidebarControl;
+    setHostSidebarWidth(extent: number): void;
+    getHostSidebarWidth(): number;
+    getHostSidebarWebContentsId(): number | null;
+    dispose(): void;
+}
+/**
+ * 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 declare function createHostSidebarView(ctx: ViewManagerContext, reconciler: PlacementReconciler): HostSidebarView;
+//# sourceMappingURL=host-sidebar-view.d.ts.map

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