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

package/dist/main/menu/index.d.ts

@@ -1,3 +1,3 @@
-import type { WorkbenchContext } from '../services/workbench-context.js';
-export declare function installAppMenu(ctx: WorkbenchContext): void;
+import type { MenuContext } from '../../shared/types.js';
+export declare function installAppMenu(ctx: MenuContext): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/main/menu/index.js

@@ -1,5 +1,7 @@
 import { Menu } from 'electron';
-import { openSettingsWindow } from '../app/launch.js';
+// The built-in menu consumes the narrow MenuContext, the same surface a host
+// menuBuilder receives — proof that the hand-written contract covers the
+// real internal consumption (settings entry + navigate-back).
 export function installAppMenu(ctx) {
     const template = [
         {
@@ -8,7 +10,7 @@ export function installAppMenu(ctx) {
                 {
                     label: '开发工具设置',
                     click: () => {
-                        void openSettingsWindow(ctx).catch(() => { });
+                        void ctx.openSettings().catch(() => { });
                     },
                 },
                 { type: 'separator' },

package/dist/main/runtime/miniapp-runtime.d.ts

@@ -17,8 +17,6 @@
  *    past the drift sentinel.
  *  - `workspace.openProject` stays writable (no `readonly`): qdmp gates
  *    project permissions by reassigning it (documented monkey-patch contract).
- *  - `windows` is an OPAQUE handle (`object`): hosts pass it through to
- *    framework helpers but never reach into it (no BrowserWindow leak).
  *
  * `asMiniappRuntime(ctx)` is an identity return — the contract is a typed
  * VIEW onto the live context, not a snapshot/projection. That is what makes
@@ -35,6 +33,53 @@ export interface MiniappProjectStatusPayload {
     /** True when the status update is emitted by the file-watcher rebuild loop. */
     hotReload?: boolean;
 }
+/**
+ * Structured shape of `getSession().appInfo` — the doc-promised
+ * (`host-migration.md` "appInfo 已结构化") DTO, named so hosts can type what
+ * they receive without deep imports or casts.
+ *
+ * `appId` is REQUIRED: the renderer derives its IPC scoping from it and the
+ * default devkit adapter always supplies one (fallback included). A custom
+ * adapter that returns a session without a string `appId` is rejected at the
+ * `openProject` boundary (see workspace-service.ts) — it never becomes the
+ * active session. The decorative rest stays optional: `name`/`path` come from
+ * the devkit adapter, `appName` from the devtools-side mirror; minimal custom
+ * adapters may omit all three.
+ */
+export interface MiniappSessionAppInfo {
+    appId: string;
+    name?: string;
+    path?: string;
+    appName?: string;
+}
+/**
+ * The page-side bridge the framework injects into the host-toolbar WCV as
+ * `window.diminaHostToolbar` (see src/preload/runtime/host-toolbar-port.ts).
+ * Declared here (the electron-free contract module) so TypeScript toolbar
+ * pages can type the bridge without hand-rolling — and without importing
+ * anything Electron-flavored.
+ *
+ * Shape mirrors the injected bridge EXACTLY:
+ *  - `send` returns void (pre-handshake sends are queued, bounded at 128);
+ *  - `onMessage` returns a BARE un-subscribe function — unlike the main-side
+ *    control's `{ dispose }` — because that is what the preload exposes.
+ * Both throw a `TypeError` synchronously when `channel` is not a non-empty
+ * string (parity with the main side's `onMessage` guard).
+ */
+export interface DiminaHostToolbarPageBridge {
+    send: (channel: string, payload: unknown) => void;
+    onMessage: (channel: string, handler: (payload: unknown) => void) => () => void;
+}
+declare global {
+    interface Window {
+        /**
+         * Present ONLY inside the host-toolbar WebContentsView's main frame
+         * (guarded injection — see host-toolbar-runtime.ts); optional everywhere
+         * else, so page code must runtime-guard before use.
+         */
+        diminaHostToolbar?: DiminaHostToolbarPageBridge;
+    }
+}
 /**
  * Host-facing control surface for the toolbar WebContentsView — the exact
  * post-R2 message-channel surface (`send`/`onMessage`), with no `webContents`
@@ -67,9 +112,22 @@ export interface MiniappHostToolbar {
     onMessage: (channel: string, handler: (payload: unknown) => void) => {
         dispose: () => void;
     };
+    /**
+     * Observe handshake readiness. Fires the handler once per load generation,
+     * exactly when the toolbar page's MessagePort handshake completes (i.e.
+     * when `send` flips to true). Registering while the channel is already
+     * ready fires once asynchronously on a microtask (missed-signal guard);
+     * a reload / re-handshake fires registered handlers again. `dispose()`
+     * detaches (idempotent).
+     */
+    onReady: (handler: () => void) => {
+        dispose: () => void;
+    };
     /**
      * Pin (`{ fixed }`) or unpin (`'auto'`) the toolbar strip height. `'auto'`
      * (default) lets the in-page height advertiser drive the placeholder.
+     * `{ fixed }` values must be finite and non-negative — anything else throws
+     * a `TypeError` synchronously and leaves the standing mode untouched.
      */
     setHeightMode: (mode: 'auto' | {
         fixed: number;
@@ -103,10 +161,11 @@ export interface MiniappWorkspace {
     /**
      * Minimal live-session DTO, or null when no session. Deliberately excludes
      * the session's own `close` — hosts end sessions via `closeProject`, never
-     * behind the workspace's back.
+     * behind the workspace's back. `appInfo` is structured (see
+     * {@link MiniappSessionAppInfo}) — no casting required.
      */
     getSession: () => {
-        appInfo: unknown;
+        appInfo: MiniappSessionAppInfo;
     } | null;
 }
 /**
@@ -115,8 +174,6 @@ export interface MiniappWorkspace {
  * plumbing is a deliberate semver decision, not an accident of projection.
  */
 export interface MiniappRuntime {
-    /** Absolute path to the devtools renderer dist directory. */
-    rendererDir: string;
     /** View layer — only the host-owned toolbar control is public. */
     views: {
         readonly hostToolbar: MiniappHostToolbar;
@@ -127,15 +184,26 @@ export interface MiniappRuntime {
     notify: {
         projectStatus: (payload: MiniappProjectStatusPayload) => void;
     };
-    /** Lifecycle sink: hosts register their own teardown via `registry.add`. */
+    /**
+     * Lifecycle sink: hosts register their own teardown via `registry.add`.
+     * Accepts BOTH disposal idioms — a `{ dispose }` object (what
+     * `hostToolbar.onMessage`/`onReady` return) or a bare `() => void` —
+     * matching the live registry, so `registry.add(sub)` works without the
+     * `registry.add(() => sub.dispose())` wrapper.
+     */
     registry: {
-        add: (dispose: () => void) => unknown;
+        add: (d: {
+            dispose: () => void;
+        } | (() => void)) => void;
     };
     /**
-     * Opaque window-service handle. Pass it through to framework helpers
-     * (e.g. `openSettingsWindow`); it exposes nothing to reach into.
+     * Open (or re-focus) the standalone workbench-settings window. Replaces the
+     * retired `windows` opaque pass-through (whose only documented purpose —
+     * `openSettingsWindow(ctx)` — could never typecheck from the contract) and
+     * the `rendererDir` member that existed solely to feed it; hosts needing
+     * the renderer dist path use the `/paths` export instead.
      */
-    windows: object;
+    openSettings: () => Promise<void>;
 }
 /**
  * View a full `WorkbenchContext` as its `MiniappRuntime` contract. Identity

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

@@ -68,6 +68,16 @@ export interface HostToolbarPortChannel {
     invalidate(): void;
     /** Register a control-level inbound handler for `channel`. */
     onMessage(channel: string, handler: (payload: unknown) => void): HostToolbarMessageSubscription;
+    /**
+     * 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): HostToolbarMessageSubscription;
     /**
      * Post `{ channel, payload }` to the toolbar page over the live port.
      * Returns false (delivering NOTHING, creating NOTHING) when there is no

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

@@ -50,10 +50,20 @@ export function createHostToolbarPortChannel(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;
-    let disposed = false;
+    /** 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 toolbar page is host-arbitrary content — anything
         // that is not an object envelope with a string channel is dropped.
@@ -68,10 +78,16 @@ export function createHostToolbarPortChannel(opts) {
                 entry.handler(payload);
         }
     }
-    function dropActivePort(close) {
+    /**
+     * 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();
@@ -81,13 +97,39 @@ export function createHostToolbarPortChannel(opts) {
             }
         }
     }
+    /**
+     * 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('[host-toolbar] 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 (disposed)
+        if (state === 'disposed')
             return;
         if (!opts.isCurrent(wc))
             return;
         // The previous load's document is gone; its port goes with it.
-        dropActivePort(true);
+        dropActivePort(true, 'awaitingHandshake');
         const { port1, port2 } = new MessageChannelMain();
         port1.on('message', (event) => {
             dispatch(event.data);
@@ -96,12 +138,17 @@ export function createHostToolbarPortChannel(opts) {
         // the reference so send() reports false instead of posting into the void.
         port1.on('close', () => {
             if (activePort === port1)
-                dropActivePort(false);
+                dropActivePort(false, 'absent');
         });
         wc.postMessage(ViewChannel.HostToolbarPort, 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) {
@@ -129,15 +176,15 @@ export function createHostToolbarPortChannel(opts) {
                     : isMainFramePositional;
                 if (isSameDocument || !isMainFrame)
                     return;
-                dropActivePort(true);
+                dropActivePort(true, 'awaitingHandshake');
             });
             wc.on('destroyed', () => {
                 if (activeWc === wc)
-                    dropActivePort(true);
+                    dropActivePort(true, 'absent');
             });
         },
         invalidate() {
-            dropActivePort(true);
+            dropActivePort(true, 'awaitingHandshake');
         },
         onMessage(channel, handler) {
             if (typeof channel !== 'string' || channel === '') {
@@ -153,6 +200,37 @@ export function createHostToolbarPortChannel(opts) {
                 },
             };
         },
+        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;
@@ -160,9 +238,10 @@ export function createHostToolbarPortChannel(opts) {
             return true;
         },
         dispose() {
-            disposed = true;
-            dropActivePort(true);
+            dropActivePort(true, 'absent');
+            state = 'disposed';
             handlers.length = 0;
+            readyHandlers.length = 0;
         },
     };
 }

package/dist/main/services/views/view-manager.d.ts

@@ -224,6 +224,18 @@ export interface HostToolbarControl {
      * (idempotent).
      */
     onMessage(channel: string, handler: (payload: unknown) => void): HostToolbarMessageSubscription;
+    /**
+     * 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): HostToolbarMessageSubscription;
     /**
      * Post `{ channel, payload }` to the toolbar page (received via
      * `window.diminaHostToolbar.onMessage(channel, handler)`). Gated and

package/dist/main/services/views/view-manager.js

@@ -306,6 +306,13 @@ export function createViewManager(ctx) {
             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
@@ -319,6 +326,9 @@ export function createViewManager(ctx) {
         onMessage(channel, handler) {
             return hostToolbarPort.onMessage(channel, handler);
         },
+        onReady(handler) {
+            return hostToolbarPort.onReady(handler);
+        },
         send(channel, payload) {
             return hostToolbarPort.send(channel, payload);
         },

package/dist/main/services/workbench-context.d.ts

@@ -41,6 +41,13 @@ export interface WorkbenchContext {
     windows: WindowService;
     /** Unified main → renderer event dispatcher */
     notify: RendererNotifier;
+    /**
+     * Open (or re-focus) the standalone workbench-settings window. First-class
+     * member so contract holders (`MiniappRuntime` / `MenuContext`) can open
+     * settings without reaching into `windows`/`notify` plumbing. Wired by
+     * `createWorkbenchContext` to the real `openSettingsWindow` path.
+     */
+    openSettings: () => Promise<void>;
     /** Single source of truth for project + session + per-project settings */
     workspace: WorkspaceService;
     /**

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

@@ -4,6 +4,7 @@ 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';
@@ -29,6 +30,10 @@ export function createWorkbenchContext(opts) {
     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;
@@ -99,6 +107,25 @@ 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', () => {

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/runtime/host-toolbar-port.d.ts

@@ -1,6 +1,16 @@
 /**
  * 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
@@ -35,10 +45,5 @@
  * envelope (queued first-comers survive), one console.warn per load.
  */
 export declare 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).
- */
 export declare function installHostToolbarPortBridge(): void;
 //# sourceMappingURL=host-toolbar-port.d.ts.map