@dimina-kit/devtools 0.3.2-dev.20260611063505 → 0.4.0-dev.20260612025610

package/dist/main/services/workbench-context.js

@@ -4,31 +4,19 @@ import { defaultAdapter } from './default-adapter.js';
 import { createRendererNotifier, } from './notifications/renderer-notifier.js';
 import { createViewManager } from './views/view-manager.js';
 import { createWindowService } from './window-service.js';
+import { openSettingsWindow } from '../windows/settings-window/index.js';
 import { createWorkspaceService, } from './workspace/workspace-service.js';
 import { createLocalProjectsProvider } from './projects/local-provider.js';
 import { createSimulatorApiRegistry, } from './simulator/custom-apis.js';
-import { createToolbarStore } from './toolbar/toolbar-store.js';
 import { resolveTemplates, sanitizeTemplates } from './projects/templates.js';
 import { BUILTIN_TEMPLATES } from './projects/builtin-templates.js';
-export function hasBuiltinPanel(ctx, panelId) {
-    return ctx.panels.includes(panelId);
-}
-export function getDefaultTab(ctx) {
-    if (hasBuiltinPanel(ctx, 'console'))
-        return 'simulator';
-    if (ctx.panels.length > 0)
-        return ctx.panels[0];
-    return 'simulator';
-}
 export function createWorkbenchContext(opts) {
     const ctx = {
         adapter: opts.adapter ?? defaultAdapter,
         preloadPath: opts.preloadPath,
         rendererDir: opts.rendererDir,
-        panels: opts.panels ?? ['wxml', 'console', 'appdata', 'storage'],
         apiNamespaces: opts.apiNamespaces ?? [],
         appName: opts.appName ?? 'Dimina DevTools',
-        headerHeight: opts.headerHeight ?? 40,
         brandingProvider: opts.brandingProvider,
     };
     ctx.registry = new DisposableRegistry();
@@ -39,10 +27,13 @@ export function createWorkbenchContext(opts) {
     ctx.connections = createConnectionRegistry();
     ctx.trustedWindowSenderIds = new Map();
     ctx.simulatorApis = createSimulatorApiRegistry();
-    ctx.toolbar = createToolbarStore();
     ctx.windows = createWindowService(opts.mainWindow);
     ctx.views = createViewManager(ctx);
     ctx.notify = createRendererNotifier(ctx);
+    // Lazy closure (not a bound snapshot): reads ctx.windows/notify/rendererDir
+    // at call time through the live context, which structurally satisfies the
+    // helper's narrow OpenSettingsWindowDeps.
+    ctx.openSettings = () => openSettingsWindow(ctx);
     ctx.projectsProvider = opts.projectsProvider ?? createLocalProjectsProvider();
     ctx.projectTemplates = resolveTemplates(BUILTIN_TEMPLATES, opts.projectTemplates ?? [], opts.builtinTemplates ?? 'all');
     ctx.customCreateProjectDialog = opts.customCreateProjectDialog;

package/dist/main/services/workspace/workspace-service.d.ts

@@ -1,4 +1,4 @@
-import type { CompileConfig } from '../../../shared/types.js';
+import type { AppInfo, CompileConfig, ProjectSession } from '../../../shared/types.js';
 import type { WorkbenchContext } from '../workbench-context.js';
 import type { Project, ProjectPages, ProjectSettings } from '../projects/project-repository.js';
 /**
@@ -9,7 +9,7 @@ import type { Project, ProjectPages, ProjectSettings } from '../projects/project
 export interface OpenProjectResult {
     success: boolean;
     port?: number;
-    appInfo?: unknown;
+    appInfo?: AppInfo;
     error?: string;
 }
 /**
@@ -32,11 +32,7 @@ export interface WorkspaceService {
     validateProjectDir(dirPath: string): Promise<string | null>;
     openProject(projectPath: string): Promise<OpenProjectResult>;
     closeProject(): Promise<void>;
-    getSession(): {
-        close: () => Promise<void>;
-        port: number;
-        appInfo: unknown;
-    } | null;
+    getSession(): ProjectSession | null;
     getProjectPath(): string;
     /**
      * The project path most recently torn down by `closeProject`, or '' if none

package/dist/main/services/workspace/workspace-service.js

@@ -1,7 +1,15 @@
+import { z } from 'zod';
 import * as repo from '../projects/project-repository.js';
 import { DEFAULT_COMPILE_CONFIG } from '../projects/types.js';
 import { clearSimulatorServicewechatReferer, setSimulatorServicewechatReferer, } from '../simulator/referer.js';
 import { loadWorkbenchSettings } from '../settings/index.js';
+/**
+ * Runtime guard for the adapter-return boundary: `session.appInfo` must be an
+ * object carrying a string `appId` (the renderer derives its IPC scoping from
+ * it; a session without one cannot be driven). Loose: extra fields pass
+ * through untouched — only the contract-critical `appId` is enforced.
+ */
+const SessionAppInfoSchema = z.looseObject({ appId: z.string() });
 /** Build a workspace service bound to the given workbench context. */
 export function createWorkspaceService(ctx) {
     let currentSession = null;
@@ -62,6 +70,12 @@ export function createWorkspaceService(ctx) {
             ? provider.validateProjectDir(dirPath)
             : null,
         async openProject(projectPath) {
+            clearSimulatorServicewechatReferer();
+            await disposeSession();
+            currentProjectPath = '';
+            // A fresh open starts a clean sandbox window — drop any previously
+            // recorded last-closed root so it can't accept writes after this point.
+            lastClosedProjectPath = '';
             // Reject obviously broken projects up front so we never spin up a
             // compile/server that the simulator will then fetch asset-by-asset.
             // Without this guard, deleted recent-list entries and typo'd CLI paths
@@ -76,18 +90,6 @@ export function createWorkspaceService(ctx) {
                 sendStatus('error', dirError);
                 return { success: false, error: dirError };
             }
-            const gate = ctx.beforeOpenProject ? await ctx.beforeOpenProject(projectPath) : undefined;
-            if (gate && !gate.allow) {
-                const message = gate.userMessage ?? gate.reason;
-                sendStatus('error', message);
-                return { success: false, error: message };
-            }
-            clearSimulatorServicewechatReferer();
-            await disposeSession();
-            currentProjectPath = '';
-            // A fresh open starts a clean sandbox window — drop any previously
-            // recorded last-closed root so it can't accept writes after this point.
-            lastClosedProjectPath = '';
             sendStatus('compiling', '正在编译...');
             const { compile } = loadWorkbenchSettings();
             let session;
@@ -105,13 +107,32 @@ export function createWorkspaceService(ctx) {
                 sendStatus('error', String(err));
                 return { success: false, error: String(err) };
             }
+            // Adapter-return boundary: enforce the AppInfo producer contract the
+            // moment the adapter resolves, BEFORE the session is recorded. A
+            // session without a string appId cannot be driven by the renderer, so
+            // it must never become the active session. The adapter already spun up
+            // live resources (compile watcher, dev-server port) — close them
+            // best-effort before reporting; the validation report is the law and a
+            // failing close() must not mask it (or escape as a throw).
+            if (!SessionAppInfoSchema.safeParse(session.appInfo).success) {
+                try {
+                    await session.close();
+                }
+                catch (closeErr) {
+                    console.warn('[workspace] closing appId-less adapter session failed (non-fatal):', closeErr);
+                }
+                const error = 'adapter returned session.appInfo without a string appId — ' +
+                    'the CompilationAdapter must supply appInfo.appId';
+                sendStatus('error', error);
+                return { success: false, error };
+            }
             currentSession = session;
             currentProjectPath = projectPath;
             bestEffort('updateLastOpened', () => {
                 if (provider.updateLastOpened)
                     provider.updateLastOpened(projectPath);
             });
-            bestEffort('sendStatus', () => sendStatus('ready', gate?.statusMessage ?? '编译完成'));
+            bestEffort('sendStatus', () => sendStatus('ready', '编译完成'));
             bestEffort('applyReferer', () => applyRefererFromSession(session));
             return {
                 success: true,

package/dist/main/utils/paths.d.ts

@@ -20,8 +20,17 @@ export declare function cjsSiblingPreloadPath(preloadPath: string): string;
  * contextBridge so the renderer never needs `window.require('electron')`.
  */
 export declare const mainPreloadPath: string;
-/** Preload for the host-controllable toolbar WCV — runs the reverse size-advertiser. */
-export declare const hostToolbarPreloadPath: string;
+/**
+ * Session-registered toolbar-runtime preload bundle (the reverse
+ * size-advertiser, self-guarded by the `--dimina-host-toolbar` marker +
+ * `isMainFrame`). Registered on `session.defaultSession` via
+ * `registerPreloadScript({ type: 'frame', filePath })` — see
+ * `src/main/services/views/host-toolbar-session-runtime.ts`. Session preloads
+ * are always loaded as CommonJS, so this points at the `.cjs` bundle (same
+ * rule `cjsSiblingPreloadPath` exists for). Resolved from the package root so
+ * npm/pnpm node_modules and ASAR packaging alike get an absolute, correct path.
+ */
+export declare const hostToolbarRuntimePreloadPath: string;
 export declare const simulatorDir: string;
 export declare function getRendererDir(): string;
 export declare function getPreloadDir(): string;

package/dist/main/utils/paths.js

@@ -48,8 +48,17 @@ export function cjsSiblingPreloadPath(preloadPath) {
  * contextBridge so the renderer never needs `window.require('electron')`.
  */
 export const mainPreloadPath = path.join(devtoolsPackageRoot, 'dist/preload/windows/main.cjs');
-/** Preload for the host-controllable toolbar WCV — runs the reverse size-advertiser. */
-export const hostToolbarPreloadPath = path.join(devtoolsPackageRoot, 'dist/preload/windows/host-toolbar.cjs');
+/**
+ * Session-registered toolbar-runtime preload bundle (the reverse
+ * size-advertiser, self-guarded by the `--dimina-host-toolbar` marker +
+ * `isMainFrame`). Registered on `session.defaultSession` via
+ * `registerPreloadScript({ type: 'frame', filePath })` — see
+ * `src/main/services/views/host-toolbar-session-runtime.ts`. Session preloads
+ * are always loaded as CommonJS, so this points at the `.cjs` bundle (same
+ * rule `cjsSiblingPreloadPath` exists for). Resolved from the package root so
+ * npm/pnpm node_modules and ASAR packaging alike get an absolute, correct path.
+ */
+export const hostToolbarRuntimePreloadPath = path.join(devtoolsPackageRoot, 'dist/preload/windows/host-toolbar-runtime.cjs');
 export const simulatorDir = path.join(devtoolsPackageRoot, 'dist/simulator');
 export function getRendererDir() {
     return rendererDir;

package/dist/main/windows/settings-window/index.d.ts

@@ -1,3 +1,36 @@
+import type { BrowserWindow } from 'electron';
+import { type WorkbenchSettings } from '../../services/settings/index.js';
 export { createSettingsWindow } from './create.js';
 export { wireSettingsWindowEvents } from './events.js';
+/**
+ * Exactly what `openSettingsWindow` needs — its OWN narrow deps interface,
+ * not a `Pick<WorkbenchContext, …>`: picking from the full context couples
+ * this helper to the whole context type (and made the contract's old
+ * `windows: object` pass-through promise unfulfillable). A full
+ * `WorkbenchContext` satisfies this structurally, so assembly points pass
+ * the context straight through.
+ */
+export interface OpenSettingsWindowDeps {
+    /** Absolute path to the renderer dist directory (settings entry HTML). */
+    rendererDir: string;
+    windows: {
+        readonly mainWindow: BrowserWindow;
+        readonly settingsWindow: BrowserWindow | null;
+        setSettingsWindow(win: BrowserWindow | null): void;
+    };
+    notify: {
+        workbenchSettingsInit(window: BrowserWindow, payload: {
+            settings: WorkbenchSettings;
+        }): void;
+    };
+}
+/**
+ * Open (or re-focus) the standalone workbench-settings window. Reuses the
+ * live window when one is already registered; otherwise creates it, registers
+ * it on the window service, and wires its `closed` cleanup. Concurrent calls
+ * share a single in-flight creation (exactly one window; every caller still
+ * gets the show/focus/snapshot semantics). Always shows + focuses, then
+ * pushes the current settings snapshot into it.
+ */
+export declare function openSettingsWindow(deps: OpenSettingsWindowDeps): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

package/dist/main/windows/settings-window/index.js

@@ -1,3 +1,62 @@
+import { createSettingsWindow } from './create.js';
+import { wireSettingsWindowEvents } from './events.js';
+import { loadWorkbenchSettings, } from '../../services/settings/index.js';
 export { createSettingsWindow } from './create.js';
 export { wireSettingsWindowEvents } from './events.js';
+/**
+ * In-flight creation guard, keyed by the windows registry (the identity that
+ * owns the `settingsWindow` slot). Overlapping `openSettingsWindow` calls
+ * before the first creation lands must share ONE creation — without this,
+ * both observe `settingsWindow === null` across the async construction
+ * boundary, build two BrowserWindows, and the loser is orphaned (alive,
+ * unreachable, never reused).
+ */
+const inFlightCreations = new WeakMap();
+async function getOrCreateSettingsWindow(deps) {
+    const existing = deps.windows.settingsWindow;
+    if (existing && !existing.isDestroyed())
+        return existing;
+    const inFlight = inFlightCreations.get(deps.windows);
+    if (inFlight)
+        return inFlight;
+    const creation = (async () => {
+        const win = await createSettingsWindow(deps.windows.mainWindow, deps.rendererDir);
+        deps.windows.setSettingsWindow(win);
+        wireSettingsWindowEvents(win, () => {
+            // Electron delivers 'closed' asynchronously: a just-destroyed window's
+            // late callback may arrive AFTER a successor was registered. Only the
+            // CURRENT registration's own close may clear the slot — a stale
+            // window's close must not drop a live successor.
+            if (deps.windows.settingsWindow === win) {
+                deps.windows.setSettingsWindow(null);
+            }
+        });
+        return win;
+    })();
+    inFlightCreations.set(deps.windows, creation);
+    try {
+        return await creation;
+    }
+    finally {
+        if (inFlightCreations.get(deps.windows) === creation) {
+            inFlightCreations.delete(deps.windows);
+        }
+    }
+}
+/**
+ * Open (or re-focus) the standalone workbench-settings window. Reuses the
+ * live window when one is already registered; otherwise creates it, registers
+ * it on the window service, and wires its `closed` cleanup. Concurrent calls
+ * share a single in-flight creation (exactly one window; every caller still
+ * gets the show/focus/snapshot semantics). Always shows + focuses, then
+ * pushes the current settings snapshot into it.
+ */
+export async function openSettingsWindow(deps) {
+    const win = await getOrCreateSettingsWindow(deps);
+    win.show();
+    win.focus();
+    deps.notify.workbenchSettingsInit(win, {
+        settings: loadWorkbenchSettings(),
+    });
+}
 //# sourceMappingURL=index.js.map

package/dist/preload/index.d.ts

@@ -12,7 +12,22 @@
 export { installConsoleInstrumentation } from './instrumentation/console.js';
 export { createAppDataSource } from './instrumentation/app-data.js';
 export type { AppDataSnapshot } from './instrumentation/app-data.js';
+/**
+ * @deprecated Will be removed in the next minor. Under the native-host (sole)
+ * runtime the simulator top frame is a top-level WebContentsView — the page DOM
+ * lives in child render-host `<webview>` guests, so this top-frame DOM observer
+ * only ever publishes `null`. Panel WXML flows over the main-process
+ * `SimulatorWxmlChannel` (`src/main/services/simulator-wxml`) instead.
+ */
 export { createWxmlSource } from './instrumentation/wxml.js';
+/**
+ * @deprecated Will be removed in the next minor. The host's
+ * `miniapp-snapshot:push/pull` IPC has no receiving end under the native-host
+ * (sole) runtime: the simulator is a top-level WebContentsView without an
+ * embedder (its `sendToHost` fires into the void) and the renderer-side puller
+ * was removed. Panel data flows over the main-process `SimulatorWxmlChannel` /
+ * `SimulatorAppDataChannel` / `SimulatorStorageChannel` instead.
+ */
 export { createMiniappSnapshotHost } from './miniapp-snapshot/host.js';
 export type { MiniappSnapshotHost, MiniappSnapshotSource, SnapshotEnvelope, SnapshotSourceId, } from './miniapp-snapshot/types.js';
 export { installSimulatorBridge } from './runtime/bridge.js';

package/dist/preload/index.js

@@ -11,7 +11,22 @@
  */
 export { installConsoleInstrumentation } from './instrumentation/console.js';
 export { createAppDataSource } from './instrumentation/app-data.js';
+/**
+ * @deprecated Will be removed in the next minor. Under the native-host (sole)
+ * runtime the simulator top frame is a top-level WebContentsView — the page DOM
+ * lives in child render-host `<webview>` guests, so this top-frame DOM observer
+ * only ever publishes `null`. Panel WXML flows over the main-process
+ * `SimulatorWxmlChannel` (`src/main/services/simulator-wxml`) instead.
+ */
 export { createWxmlSource } from './instrumentation/wxml.js';
+/**
+ * @deprecated Will be removed in the next minor. The host's
+ * `miniapp-snapshot:push/pull` IPC has no receiving end under the native-host
+ * (sole) runtime: the simulator is a top-level WebContentsView without an
+ * embedder (its `sendToHost` fires into the void) and the renderer-side puller
+ * was removed. Panel data flows over the main-process `SimulatorWxmlChannel` /
+ * `SimulatorAppDataChannel` / `SimulatorStorageChannel` instead.
+ */
 export { createMiniappSnapshotHost } from './miniapp-snapshot/host.js';
 export { installSimulatorBridge } from './runtime/bridge.js';
 export { installCustomApisBridge } from './runtime/custom-apis.js';

package/dist/preload/runtime/host-toolbar-port.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Preload side of the host-toolbar gated narrow channel.
+ *
+ * ── PUBLIC SURFACE EVOLUTION RULE ───────────────────────────────────────────
+ * `window.diminaHostToolbar` is a published page-facing API, typed by the
+ * exported `DiminaHostToolbarPageBridge` (src/main/runtime/miniapp-runtime.ts)
+ * — arbitrary host toolbar pages compile against it. Members may only be
+ * ADDED, never changed: any semantic change to an existing member (signature,
+ * return shape, queueing/throw behavior) ships under a NEW name instead.
+ * Exception: security fixes / compliance corrections may change existing
+ * member semantics, and MUST be called out in the release's version notes.
+ * Keep the exported bridge type in lockstep with what is exposed here.
+ *
+ * Receives the per-load MessagePort main transfers on `did-finish-load`
+ * (`ViewChannel.HostToolbarPort`, `event.ports[0]`) and bridges it to the page
+ * as `window.diminaHostToolbar` — EXACTLY `{ send, onMessage }`, functions
+ * only. The raw MessagePort never crosses into the main world: the page only
+ * ever talks through these two functions, so the `{ channel, payload }`
+ * envelope stays the single waist (same posture as the main side's
+ * host-toolbar-port-channel.ts).
+ *
+ * Ordering reality this module absorbs (spike .repro/wave3-spike):
+ *  - The page script runs BEFORE the handshake can complete (the port is
+ *    posted on did-finish-load). Page `send()`s issued before the port
+ *    arrives go into a PENDING QUEUE and flush in order on handshake —
+ *    without it the first message of every load is silently dropped. The
+ *    queue is BOUNDED at `HOST_TOOLBAR_PENDING_LIMIT` (128): the toolbar page
+ *    is arbitrary host content, and a page whose handshake never arrives must
+ *    not grow main-world-driven memory without limit. Overflow drops the
+ *    NEWEST send (boot sequences front-load their important messages; the
+ *    first-comers survive), warns ONCE per load, and never throws into page
+ *    code.
+ *  - Page handlers likewise register before the port exists; the registry is
+ *    module-level (per-load — the preload re-runs on every navigation) and is
+ *    re-attached to each newly delivered port, so a same-load re-handshake
+ *    keeps existing handlers alive. The LATER port wins for sends.
+ *  - Inbound dispatch uses `addEventListener('message')` + `start()`
+ *    (without `start()` a DOM MessagePort never delivers) and DROPS malformed
+ *    envelopes without throwing.
+ */
+/**
+ * Cap on pre-handshake queued sends. 128 comfortably covers any sane toolbar
+ * boot sequence while bounding what a page whose handshake never completes
+ * can make the isolated world retain. Overflow policy: drop the NEWEST
+ * envelope (queued first-comers survive), one console.warn per load.
+ */
+export declare const HOST_TOOLBAR_PENDING_LIMIT = 128;
+export declare function installHostToolbarPortBridge(): void;
+//# sourceMappingURL=host-toolbar-port.d.ts.map

package/dist/preload/runtime/host-toolbar-port.js

@@ -0,0 +1,151 @@
+/**
+ * Preload side of the host-toolbar gated narrow channel.
+ *
+ * ── PUBLIC SURFACE EVOLUTION RULE ───────────────────────────────────────────
+ * `window.diminaHostToolbar` is a published page-facing API, typed by the
+ * exported `DiminaHostToolbarPageBridge` (src/main/runtime/miniapp-runtime.ts)
+ * — arbitrary host toolbar pages compile against it. Members may only be
+ * ADDED, never changed: any semantic change to an existing member (signature,
+ * return shape, queueing/throw behavior) ships under a NEW name instead.
+ * Exception: security fixes / compliance corrections may change existing
+ * member semantics, and MUST be called out in the release's version notes.
+ * Keep the exported bridge type in lockstep with what is exposed here.
+ *
+ * Receives the per-load MessagePort main transfers on `did-finish-load`
+ * (`ViewChannel.HostToolbarPort`, `event.ports[0]`) and bridges it to the page
+ * as `window.diminaHostToolbar` — EXACTLY `{ send, onMessage }`, functions
+ * only. The raw MessagePort never crosses into the main world: the page only
+ * ever talks through these two functions, so the `{ channel, payload }`
+ * envelope stays the single waist (same posture as the main side's
+ * host-toolbar-port-channel.ts).
+ *
+ * Ordering reality this module absorbs (spike .repro/wave3-spike):
+ *  - The page script runs BEFORE the handshake can complete (the port is
+ *    posted on did-finish-load). Page `send()`s issued before the port
+ *    arrives go into a PENDING QUEUE and flush in order on handshake —
+ *    without it the first message of every load is silently dropped. The
+ *    queue is BOUNDED at `HOST_TOOLBAR_PENDING_LIMIT` (128): the toolbar page
+ *    is arbitrary host content, and a page whose handshake never arrives must
+ *    not grow main-world-driven memory without limit. Overflow drops the
+ *    NEWEST send (boot sequences front-load their important messages; the
+ *    first-comers survive), warns ONCE per load, and never throws into page
+ *    code.
+ *  - Page handlers likewise register before the port exists; the registry is
+ *    module-level (per-load — the preload re-runs on every navigation) and is
+ *    re-attached to each newly delivered port, so a same-load re-handshake
+ *    keeps existing handlers alive. The LATER port wins for sends.
+ *  - Inbound dispatch uses `addEventListener('message')` + `start()`
+ *    (without `start()` a DOM MessagePort never delivers) and DROPS malformed
+ *    envelopes without throwing.
+ */
+import { contextBridge, ipcRenderer } from 'electron';
+import { ViewChannel } from '../../shared/ipc-channels.js';
+const BRIDGE_KEY = 'diminaHostToolbar';
+/**
+ * Cap on pre-handshake queued sends. 128 comfortably covers any sane toolbar
+ * boot sequence while bounding what a page whose handshake never completes
+ * can make the isolated world retain. Overflow policy: drop the NEWEST
+ * envelope (queued first-comers survive), one console.warn per load.
+ */
+export const HOST_TOOLBAR_PENDING_LIMIT = 128;
+/**
+ * Subscribe the handshake channel and expose the page bridge. Call ONLY from
+ * a passing toolbar-runtime guard (`activateHostToolbarRuntime`) — a failing
+ * guard must leave zero footprint (no bridge key, no IPC listener).
+ */
+/**
+ * Entry-waist channel validation, parity with the main side's
+ * `hostToolbar.onMessage` guard (same TypeError, message names `channel`).
+ * Runs BEFORE any state is touched (no queue slot, no registry entry), in
+ * both port states — a page author's typo throws at the call site instead of
+ * vanishing into main's silent inbound drop.
+ */
+function assertValidChannel(method, channel) {
+    if (typeof channel !== 'string' || channel === '') {
+        throw new TypeError(`diminaHostToolbar.${method}: channel must be a non-empty string`);
+    }
+}
+export function installHostToolbarPortBridge() {
+    let activePort = null;
+    const pending = [];
+    // One overflow warning per load (this installer runs once per document) —
+    // a runaway page send-loop must not get per-drop console spam.
+    let warnedPendingOverflow = false;
+    const handlers = [];
+    const dispatch = (data) => {
+        // Defensive symmetry with main: drop anything that is not an object
+        // envelope with a string channel — never throw in the dispatcher.
+        if (typeof data !== 'object' || data === null)
+            return;
+        const { channel, payload } = data;
+        if (typeof channel !== 'string')
+            return;
+        for (const entry of [...handlers]) {
+            if (entry.channel === channel)
+                entry.handler(payload);
+        }
+    };
+    const onPortMessage = (event) => {
+        dispatch(event.data);
+    };
+    ipcRenderer.on(ViewChannel.HostToolbarPort, (event) => {
+        const port = event.ports[0];
+        if (!port)
+            return;
+        // Same-load duplicate handshake: the LATER port wins. Main closed (or is
+        // about to close) its end of the old pair — detach and stop writing to it.
+        if (activePort) {
+            try {
+                activePort.removeEventListener('message', onPortMessage);
+                activePort.close();
+            }
+            catch {
+                /* already dead */
+            }
+        }
+        activePort = port;
+        // addEventListener (not onmessage) keeps the handler removable on
+        // re-handshake; it REQUIRES start() or inbound never delivers.
+        port.addEventListener('message', onPortMessage);
+        port.start();
+        // Flush sends issued before the port arrived, in order.
+        while (pending.length > 0) {
+            const envelope = pending.shift();
+            port.postMessage(envelope);
+        }
+    });
+    // EXACTLY { send, onMessage } — functions only; the port stays in the
+    // isolated world.
+    contextBridge.exposeInMainWorld(BRIDGE_KEY, {
+        send(channel, payload) {
+            assertValidChannel('send', channel);
+            const envelope = { channel, payload };
+            if (activePort) {
+                activePort.postMessage(envelope);
+                return;
+            }
+            // Bounded queue: drop the NEWEST send on overflow (FIFO first-comers
+            // survive), warn once per load, never throw into page code.
+            if (pending.length >= HOST_TOOLBAR_PENDING_LIMIT) {
+                if (!warnedPendingOverflow) {
+                    warnedPendingOverflow = true;
+                    console.warn(`[dimina-devtools] host-toolbar pending queue full (${HOST_TOOLBAR_PENDING_LIMIT}); ` +
+                        'dropping further pre-handshake send() calls until the port arrives');
+                }
+                return;
+            }
+            pending.push(envelope);
+        },
+        onMessage(channel, handler) {
+            assertValidChannel('onMessage', channel);
+            const entry = { channel, handler };
+            handlers.push(entry);
+            return () => {
+                const i = handlers.indexOf(entry);
+                if (i >= 0)
+                    handlers.splice(i, 1);
+            };
+        },
+    });
+}
+//# sourceMappingURL=host-toolbar-port.js.map

package/dist/preload/runtime/host-toolbar-runtime.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Session-resident host-toolbar framework runtime: GUARD + ACTIVATION.
+ *
+ * The toolbar-runtime preload is registered on `session.defaultSession` via
+ * `registerPreloadScript({ type: 'frame', … })`, so it executes in EVERY
+ * defaultSession renderer — the main window, settings/popover overlays, and
+ * (with `nodeIntegrationInSubFrames`) even subframes. This module is the guard
+ * that keeps it inert everywhere except the host-toolbar WCV's main frame:
+ *
+ *  - the toolbar WCV's creation injects `HOST_TOOLBAR_RUNTIME_MARKER` into its
+ *    process argv via `webPreferences.additionalArguments`;
+ *  - the marker is PROCESS-level (subframes of the toolbar window carry it
+ *    too — spike .repro/wave3-spike/RESULTS.md item 3), so the guard needs
+ *    BOTH wings: `isMainFrame` AND `argv.includes(marker)`;
+ *  - a renderer that fails the guard returns immediately with ZERO footprint
+ *    (no advertiser, no listeners, no globals — spike item 4).
+ *
+ * Why session-resident at all: the advertiser used to ride the toolbar WCV's
+ * `webPreferences.preload`, so a host calling `setPreloadPath(<its own
+ * preload>)` REPLACED it and the strip height collapsed to 0. With the runtime
+ * on the session layer, the host preload and the framework runtime coexist.
+ */
+/**
+ * Pure guard predicate: should the toolbar runtime activate in a renderer with
+ * this `argv` / `isMainFrame`? True only for the MAIN frame of a process whose
+ * argv carries the `'--dimina-host-toolbar'` marker.
+ */
+export declare function shouldActivateHostToolbarRuntime(argv: readonly string[], isMainFrame: boolean): boolean;
+/**
+ * Run the guard; only when it passes, install the height advertiser
+ * (`installHostToolbarAdvertiserWhenReady`) and the narrow-channel page
+ * bridge (`installHostToolbarPortBridge` — `window.diminaHostToolbar` +
+ * the MessagePort handshake listener). Returns whether the runtime
+ * activated. A failed guard installs NOTHING (zero footprint in non-toolbar
+ * windows and subframes: no advertiser, no bridge key, no IPC listener).
+ */
+export declare function activateHostToolbarRuntime(env: {
+    argv: readonly string[];
+    isMainFrame: boolean;
+}): boolean;
+//# sourceMappingURL=host-toolbar-runtime.d.ts.map

package/dist/preload/runtime/host-toolbar-runtime.js

@@ -0,0 +1,49 @@
+/**
+ * Session-resident host-toolbar framework runtime: GUARD + ACTIVATION.
+ *
+ * The toolbar-runtime preload is registered on `session.defaultSession` via
+ * `registerPreloadScript({ type: 'frame', … })`, so it executes in EVERY
+ * defaultSession renderer — the main window, settings/popover overlays, and
+ * (with `nodeIntegrationInSubFrames`) even subframes. This module is the guard
+ * that keeps it inert everywhere except the host-toolbar WCV's main frame:
+ *
+ *  - the toolbar WCV's creation injects `HOST_TOOLBAR_RUNTIME_MARKER` into its
+ *    process argv via `webPreferences.additionalArguments`;
+ *  - the marker is PROCESS-level (subframes of the toolbar window carry it
+ *    too — spike .repro/wave3-spike/RESULTS.md item 3), so the guard needs
+ *    BOTH wings: `isMainFrame` AND `argv.includes(marker)`;
+ *  - a renderer that fails the guard returns immediately with ZERO footprint
+ *    (no advertiser, no listeners, no globals — spike item 4).
+ *
+ * Why session-resident at all: the advertiser used to ride the toolbar WCV's
+ * `webPreferences.preload`, so a host calling `setPreloadPath(<its own
+ * preload>)` REPLACED it and the strip height collapsed to 0. With the runtime
+ * on the session layer, the host preload and the framework runtime coexist.
+ */
+import { HOST_TOOLBAR_RUNTIME_MARKER } from '../../shared/constants.js';
+import { installHostToolbarAdvertiserWhenReady } from './host-toolbar-advertiser.js';
+import { installHostToolbarPortBridge } from './host-toolbar-port.js';
+/**
+ * Pure guard predicate: should the toolbar runtime activate in a renderer with
+ * this `argv` / `isMainFrame`? True only for the MAIN frame of a process whose
+ * argv carries the `'--dimina-host-toolbar'` marker.
+ */
+export function shouldActivateHostToolbarRuntime(argv, isMainFrame) {
+    return isMainFrame && argv.includes(HOST_TOOLBAR_RUNTIME_MARKER);
+}
+/**
+ * Run the guard; only when it passes, install the height advertiser
+ * (`installHostToolbarAdvertiserWhenReady`) and the narrow-channel page
+ * bridge (`installHostToolbarPortBridge` — `window.diminaHostToolbar` +
+ * the MessagePort handshake listener). Returns whether the runtime
+ * activated. A failed guard installs NOTHING (zero footprint in non-toolbar
+ * windows and subframes: no advertiser, no bridge key, no IPC listener).
+ */
+export function activateHostToolbarRuntime(env) {
+    if (!shouldActivateHostToolbarRuntime(env.argv, env.isMainFrame))
+        return false;
+    installHostToolbarAdvertiserWhenReady();
+    installHostToolbarPortBridge();
+    return true;
+}
+//# sourceMappingURL=host-toolbar-runtime.js.map