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

package/dist/main/utils/ipc-context-source.d.ts

@@ -0,0 +1,40 @@
+import type { WebContents } from 'electron';
+import type { SenderPolicy } from './ipc-registry.js';
+/**
+ * Resolves which window context owns an incoming IPC sender.
+ *
+ * `register*Ipc` takes one of these instead of a bare context so a single
+ * handler body serves both shapes: one window (every accepted sender maps to
+ * that window's context) and several windows (each message is answered by the
+ * context of the window it actually came from).
+ */
+export interface IpcContextSource<T> {
+    /**
+     * Set only by the adapter over a context that carries no `senderPolicy` —
+     * narrow test contexts. It keeps {@link IpcRegistry} in its policy-less mode
+     * (accept every sender, skip the main-frame check), so wrapping such a
+     * context in a source is not itself a trust change.
+     */
+    readonly ungated?: boolean;
+    /** The context owning `sender`, or null when no context claims it. */
+    resolve(sender: WebContents): T | null;
+    /** Every context this source can hand out. */
+    list(): T[];
+}
+/**
+ * What every `register*Ipc` accepts: a router covering all live windows, or a
+ * single context standing in for itself.
+ */
+export type IpcInput<T> = T | IpcContextSource<T>;
+/** Structural test: a source exposes both members, a context exposes neither. */
+export declare function isIpcContextSource<T>(value: unknown): value is IpcContextSource<T>;
+/**
+ * Accept either a source or a single context. A single context gates on its
+ * own `senderPolicy` — the same predicate a policy-only registry applies — and
+ * owns every sender that predicate accepts. A context without a policy stays
+ * ungated so narrow test contexts keep the behaviour a bare registry gave them.
+ */
+export declare function toIpcContextSource<T extends {
+    senderPolicy?: SenderPolicy;
+}>(input: T | IpcContextSource<T>): IpcContextSource<T>;
+//# sourceMappingURL=ipc-context-source.d.ts.map

package/dist/main/utils/ipc-context-source.js

@@ -0,0 +1,23 @@
+/** Structural test: a source exposes both members, a context exposes neither. */
+export function isIpcContextSource(value) {
+    if (value == null || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return typeof candidate.resolve === 'function' && typeof candidate.list === 'function';
+}
+/**
+ * Accept either a source or a single context. A single context gates on its
+ * own `senderPolicy` — the same predicate a policy-only registry applies — and
+ * owns every sender that predicate accepts. A context without a policy stays
+ * ungated so narrow test contexts keep the behaviour a bare registry gave them.
+ */
+export function toIpcContextSource(input) {
+    if (isIpcContextSource(input))
+        return input;
+    const ctx = input;
+    const policy = ctx.senderPolicy;
+    if (!policy)
+        return { ungated: true, resolve: () => ctx, list: () => [ctx] };
+    return { resolve: (sender) => (policy(sender) ? ctx : null), list: () => [ctx] };
+}
+//# sourceMappingURL=ipc-context-source.js.map

package/dist/main/utils/ipc-registry.d.ts

@@ -1,6 +1,7 @@
-import type { IpcMainEvent } from 'electron';
+import type { IpcMainEvent, IpcMainInvokeEvent } from 'electron';
 import { ipcMain } from 'electron';
 import { type Disposable, type IpcSenderPolicy } from '@dimina-kit/electron-deck/main';
+import type { IpcContextSource } from './ipc-context-source.js';
 type HandleFn = Parameters<typeof ipcMain.handle>[1];
 type ListenerFn = Parameters<typeof ipcMain.on>[1];
 /**
@@ -10,57 +11,62 @@ type ListenerFn = Parameters<typeof ipcMain.on>[1];
  * the channel, false otherwise.
  */
 export type SenderPolicy = IpcSenderPolicy;
-/**
- * Defense-in-depth frame check (sits alongside the sender white-list). A trusted
- * webContents could embed a sub-frame of arbitrary origin; only its top (main)
- * frame should reach gated IPC, so a sub-frame can't spoof the trusted sender.
- *
- * Verified on Electron 41 that `event.senderFrame` is reliably present on
- * invoke / send / sendSync — including the editor's `beforeunload` sendSync
- * write — and equals `sender.mainFrame` for top-frame traffic, so this never
- * mis-rejects legitimate callers.
- *
- * Fail-closed on a null frame for REAL events: a sub-frame can send a message
- * and immediately navigate/destroy itself, so by delivery time `senderFrame`
- * resolves to null — allowing that would let the navigate-after-send trick
- * bypass the boundary. A real Electron event always exposes the `senderFrame`
- * property and `sender.mainFrame`, so we can tell a real event (frame-modeled,
- * possibly null) from a frame-unaware unit-test stub (neither present) and only
- * skip the check for the latter (the sender-id white-list still gates tests).
- */
 /**
  * Tiny fluent helper that wraps every `ipcMain.handle` / `ipcMain.on` with a
  * matching removeHandler/removeListener registered into an internal registry.
  *
- * Each `register*Ipc(ctx)` returns one of these as a Disposable so the
+ * Each `register*Ipc(...)` returns one of these as a Disposable so the
  * workbench-level registry can dispose all built-in handlers in one shot.
  *
- * If a {@link SenderPolicy} is provided, every incoming invocation is gated:
- * - `handle`: rejected senders cause the invoke promise to reject with
- *   `Error('IPC sender rejected for channel <channel>')`.
- * - `on`: rejected senders are silently dropped (the original listener is
- *   never called).
- * In both cases a single `console.warn` is emitted with the channel name
- * and a short sender summary. Without a policy the wrapper is a no-op,
- * preserving backwards compatibility for unit tests and callers that
- * opted out.
+ * The constructor takes either a {@link SenderPolicy} (trust only: is this
+ * sender allowed?) or an {@link IpcContextSource} (trust plus ownership: which
+ * window context does this sender belong to?). With either, every incoming
+ * invocation is gated:
+ * - `handle` / `handleRouted`: rejected senders cause the invoke promise to
+ *   reject with `Error('IPC sender rejected for channel <channel>')`.
+ * - `on` / `onRouted`: rejected senders are silently dropped (the original
+ *   listener is never called).
+ * - `handleSync` / `handleSyncRouted`: rejected senders get a structured
+ *   `{ ok: false, code: 'EREJECTED', … }` returnValue, because sendSync blocks
+ *   the renderer until one is set.
+ * In every case a single `console.warn` is emitted with the channel name and a
+ * short sender summary. With no policy — or a source that declares itself
+ * `ungated` — the wrapper is a pass-through, preserving backwards
+ * compatibility for unit tests and callers that opted out.
+ *
+ * The `*Routed` variants hand the owning context to the handler as its first
+ * argument. `TCtx` is `never` unless the registry was built from a source, so
+ * they are unusable (and unreachable) on a policy-only registry.
  */
-export declare class IpcRegistry implements Disposable {
-    private policy?;
+export declare class IpcRegistry<TCtx = never> implements Disposable {
     private cleanups;
     private _disposed;
-    constructor(policy?: SenderPolicy | undefined);
+    private readonly policy;
+    private readonly source;
+    /** False reproduces the policy-less pass-through exactly: no main-frame
+     * check, and a synchronous handler keeps its synchronous return value. */
+    private readonly gated;
+    constructor(policyOrSource?: SenderPolicy | IpcContextSource<TCtx>);
+    /** Trust gate and owner resolution for one incoming message. */
+    private admit;
+    private warnRejected;
+    private addInvokeHandler;
     handle(channel: string, fn: HandleFn): this;
+    /** {@link handle} answered by the context that owns the calling sender. */
+    handleRouted(channel: string, fn: (ctx: TCtx, event: IpcMainInvokeEvent, ...args: unknown[]) => unknown): this;
+    private addSyncHandler;
     /**
      * Register a SYNCHRONOUS `ipcRenderer.sendSync` handler. Unlike {@link on}
      * (fire-and-forget), the renderer is blocked until we set `event.returnValue`,
-     * so `fn` MUST be synchronous and return the value to hand back. The sender
-     * policy gates it like {@link handle}; a rejected sender or a thrown error
-     * yields a structured `{ ok: false, code, message }` returnValue instead of
-     * the silent drop `on` uses, so the blocked renderer always gets an answer.
+     * so `fn` MUST be synchronous and return the value to hand back.
      */
     handleSync(channel: string, fn: (event: IpcMainEvent, ...args: unknown[]) => unknown): this;
+    /** {@link handleSync} answered by the context that owns the calling sender. */
+    handleSyncRouted(channel: string, fn: (ctx: TCtx, event: IpcMainEvent, ...args: unknown[]) => unknown): this;
+    private addListener;
     on(channel: string, fn: ListenerFn): this;
+    /** {@link on} answered by the context that owns the calling sender. */
+    onRouted(channel: string, fn: (ctx: TCtx, event: IpcMainEvent, ...args: unknown[]) => unknown): this;
     dispose(): Promise<void>;
 }
 export {};

package/dist/main/utils/ipc-registry.js

@@ -1,5 +1,5 @@
 import { ipcMain } from 'electron';
-import { isMainFrameIpcSender, } from '@dimina-kit/electron-deck/main';
+import { addMuxedInvokeHandler, isMainFrameIpcSender, } from '@dimina-kit/electron-deck/main';
 import { IpcValidationError } from './ipc-schema.js';
 import { createLogger } from './logger.js';
 const log = createLogger('ipc');
@@ -48,25 +48,41 @@ function summarizeSender(sender) {
  * possibly null) from a frame-unaware unit-test stub (neither present) and only
  * skip the check for the latter (the sender-id white-list still gates tests).
  */
+/** Internal marker for "this sender is not allowed on this channel". */
+const REJECT = Symbol('ipc-reject');
+// Channel multiplexing (one real `ipcMain.handle` per channel, dispatched to
+// whichever per-window registration claims the sender — needed because the
+// storage, WXML and AppData panels each register their channels once per
+// window) is shared with dimina-electron-runtime's bridge router; see
+// @dimina-kit/electron-deck/main's ipc-mux.ts for the mux itself.
 /**
  * Tiny fluent helper that wraps every `ipcMain.handle` / `ipcMain.on` with a
  * matching removeHandler/removeListener registered into an internal registry.
  *
- * Each `register*Ipc(ctx)` returns one of these as a Disposable so the
+ * Each `register*Ipc(...)` returns one of these as a Disposable so the
  * workbench-level registry can dispose all built-in handlers in one shot.
  *
- * If a {@link SenderPolicy} is provided, every incoming invocation is gated:
- * - `handle`: rejected senders cause the invoke promise to reject with
- *   `Error('IPC sender rejected for channel <channel>')`.
- * - `on`: rejected senders are silently dropped (the original listener is
- *   never called).
- * In both cases a single `console.warn` is emitted with the channel name
- * and a short sender summary. Without a policy the wrapper is a no-op,
- * preserving backwards compatibility for unit tests and callers that
- * opted out.
+ * The constructor takes either a {@link SenderPolicy} (trust only: is this
+ * sender allowed?) or an {@link IpcContextSource} (trust plus ownership: which
+ * window context does this sender belong to?). With either, every incoming
+ * invocation is gated:
+ * - `handle` / `handleRouted`: rejected senders cause the invoke promise to
+ *   reject with `Error('IPC sender rejected for channel <channel>')`.
+ * - `on` / `onRouted`: rejected senders are silently dropped (the original
+ *   listener is never called).
+ * - `handleSync` / `handleSyncRouted`: rejected senders get a structured
+ *   `{ ok: false, code: 'EREJECTED', … }` returnValue, because sendSync blocks
+ *   the renderer until one is set.
+ * In every case a single `console.warn` is emitted with the channel name and a
+ * short sender summary. With no policy — or a source that declares itself
+ * `ungated` — the wrapper is a pass-through, preserving backwards
+ * compatibility for unit tests and callers that opted out.
+ *
+ * The `*Routed` variants hand the owning context to the handler as its first
+ * argument. `TCtx` is `never` unless the registry was built from a source, so
+ * they are unusable (and unreachable) on a policy-only registry.
  */
 export class IpcRegistry {
-    policy;
     // Every cleanup is a synchronous ipcMain.removeHandler/removeListener call,
     // so dispose() can (and must) run them all before returning: callers
     // `dispose()` without awaiting and rely on every channel being unregistered
@@ -74,48 +90,81 @@ export class IpcRegistry {
     // live until a later microtask.
     cleanups = [];
     _disposed = false;
-    constructor(policy) {
-        this.policy = policy;
+    policy;
+    source;
+    /** False reproduces the policy-less pass-through exactly: no main-frame
+     * check, and a synchronous handler keeps its synchronous return value. */
+    gated;
+    constructor(policyOrSource) {
+        const isPolicy = typeof policyOrSource === 'function';
+        this.policy = isPolicy ? policyOrSource : null;
+        this.source = policyOrSource != null && !isPolicy ? policyOrSource : null;
+        this.gated = this.policy != null || (this.source != null && !this.source.ungated);
     }
-    handle(channel, fn) {
-        const policy = this.policy;
+    /** Trust gate and owner resolution for one incoming message. */
+    admit(event) {
+        const source = this.source;
+        if (source) {
+            // An ungated source always claims the sender, so the frame check — part
+            // of the trust gate, not of ownership — stays off with it.
+            if (source.ungated)
+                return source.resolve(event.sender);
+            if (!isMainFrameIpcSender(event))
+                return REJECT;
+            const ctx = source.resolve(event.sender);
+            return ctx == null ? REJECT : ctx;
+        }
+        // A bare policy answers trust only, so the accepted branch carries no
+        // context; `TCtx` is `never` in that mode, so no handler can observe it.
+        if (!this.policy)
+            return undefined;
+        return this.policy(event.sender) && isMainFrameIpcSender(event)
+            ? undefined
+            : REJECT;
+    }
+    warnRejected(channel, sender) {
+        console.warn(`[ipc] sender rejected for channel '${channel}' (${summarizeSender(sender)})`);
+    }
+    addInvokeHandler(channel, invoke) {
         // The gate is `async` so a rejected sender surfaces as a *rejected
         // promise* (the invoke-result contract) rather than a synchronous throw —
         // synchronous throws can escape callers that wrap the result in
         // `Promise.resolve(...)` instead of `await`-ing it directly.
-        const guarded = policy
+        const guarded = this.gated
             ? async (event, ...args) => {
-                const sender = event.sender;
-                if (!policy(sender) || !isMainFrameIpcSender(event)) {
-                    console.warn(`[ipc] sender rejected for channel '${channel}' (${summarizeSender(sender)})`);
+                const ctx = this.admit(event);
+                if (ctx === REJECT) {
+                    this.warnRejected(channel, event.sender);
                     throw new Error(`IPC sender rejected for channel ${channel}`);
                 }
-                return fn(event, ...args);
+                return invoke(ctx, event, args);
             }
-            : fn;
-        ipcMain.handle(channel, guarded);
-        this.cleanups.push(() => ipcMain.removeHandler(channel));
+            : (event, ...args) => invoke(this.admit(event), event, args);
+        this.cleanups.push(addMuxedInvokeHandler(ipcMain, channel, {
+            claims: (event) => this.admit(event) !== REJECT,
+            handle: guarded,
+        }));
         return this;
     }
-    /**
-     * Register a SYNCHRONOUS `ipcRenderer.sendSync` handler. Unlike {@link on}
-     * (fire-and-forget), the renderer is blocked until we set `event.returnValue`,
-     * so `fn` MUST be synchronous and return the value to hand back. The sender
-     * policy gates it like {@link handle}; a rejected sender or a thrown error
-     * yields a structured `{ ok: false, code, message }` returnValue instead of
-     * the silent drop `on` uses, so the blocked renderer always gets an answer.
-     */
-    handleSync(channel, fn) {
-        const policy = this.policy;
+    handle(channel, fn) {
+        const raw = fn;
+        return this.addInvokeHandler(channel, (_ctx, event, args) => raw(event, ...args));
+    }
+    /** {@link handle} answered by the context that owns the calling sender. */
+    handleRouted(channel, fn) {
+        return this.addInvokeHandler(channel, (ctx, event, args) => fn(ctx, event, ...args));
+    }
+    addSyncHandler(channel, invoke) {
         const listener = (event, ...args) => {
             const syncEvent = event;
-            // Everything — including the policy check — runs inside the try so EVERY
-            // path sets `event.returnValue`. sendSync blocks the renderer until it is
+            // Everything — including the gate — runs inside the try so EVERY path
+            // sets `event.returnValue`. sendSync blocks the renderer until it is
             // set, so an unset value (e.g. a throwing policy fn) would hang the
             // renderer forever; the catch guarantees a sentinel instead.
             try {
-                if (policy && (!policy(event.sender) || !isMainFrameIpcSender(event))) {
-                    console.warn(`[ipc] sender rejected for channel '${channel}' (${summarizeSender(event.sender)})`);
+                const ctx = this.admit(event);
+                if (ctx === REJECT) {
+                    this.warnRejected(channel, event.sender);
                     syncEvent.returnValue = {
                         ok: false,
                         code: 'EREJECTED',
@@ -123,7 +172,7 @@ export class IpcRegistry {
                     };
                     return;
                 }
-                syncEvent.returnValue = fn(event, ...args);
+                syncEvent.returnValue = invoke(ctx, event, args);
             }
             catch (err) {
                 reportListenerError(channel, err);
@@ -139,12 +188,22 @@ export class IpcRegistry {
         this.cleanups.push(() => ipcMain.removeListener(channel, listener));
         return this;
     }
-    on(channel, fn) {
-        const policy = this.policy;
-        const raw = fn;
-        const safeInvoke = (event, args) => {
+    /**
+     * Register a SYNCHRONOUS `ipcRenderer.sendSync` handler. Unlike {@link on}
+     * (fire-and-forget), the renderer is blocked until we set `event.returnValue`,
+     * so `fn` MUST be synchronous and return the value to hand back.
+     */
+    handleSync(channel, fn) {
+        return this.addSyncHandler(channel, (_ctx, event, args) => fn(event, ...args));
+    }
+    /** {@link handleSync} answered by the context that owns the calling sender. */
+    handleSyncRouted(channel, fn) {
+        return this.addSyncHandler(channel, (ctx, event, args) => fn(ctx, event, ...args));
+    }
+    addListener(channel, invoke) {
+        const safeInvoke = (ctx, event, args) => {
             try {
-                const ret = raw(event, ...args);
+                const ret = invoke(ctx, event, args);
                 if (isThenable(ret)) {
                     // Async listeners would otherwise leak rejections into Electron's
                     // event loop as `UnhandledPromiseRejection`. Funnel them into the
@@ -156,20 +215,28 @@ export class IpcRegistry {
                 reportListenerError(channel, err);
             }
         };
-        const guarded = policy
+        const guarded = this.gated
             ? (event, ...args) => {
-                const sender = event.sender;
-                if (!policy(sender) || !isMainFrameIpcSender(event)) {
-                    console.warn(`[ipc] sender rejected for channel '${channel}' (${summarizeSender(sender)})`);
+                const ctx = this.admit(event);
+                if (ctx === REJECT) {
+                    this.warnRejected(channel, event.sender);
                     return;
                 }
-                safeInvoke(event, args);
+                safeInvoke(ctx, event, args);
             }
-            : (event, ...args) => safeInvoke(event, args);
+            : (event, ...args) => safeInvoke(this.admit(event), event, args);
         ipcMain.on(channel, guarded);
         this.cleanups.push(() => ipcMain.removeListener(channel, guarded));
         return this;
     }
+    on(channel, fn) {
+        const raw = fn;
+        return this.addListener(channel, (_ctx, event, args) => raw(event, ...args));
+    }
+    /** {@link on} answered by the context that owns the calling sender. */
+    onRouted(channel, fn) {
+        return this.addListener(channel, (ctx, event, args) => fn(ctx, event, ...args));
+    }
     dispose() {
         // Synchronous drain (LIFO, idempotent): every channel is unregistered
         // before this returns; the promise only carries aggregated errors.

package/dist/main/utils/sender-policy.d.ts

@@ -31,4 +31,13 @@ import type { SenderPolicy } from './ipc-registry.js';
  * iframe — is rejected.
  */
 export declare function createWorkbenchSenderPolicy(ctx: Pick<WorkbenchContext, 'windows' | 'views' | 'trustedWindowSenderIds'>): SenderPolicy;
+/**
+ * The senders this context structurally OWNS: its own main-window renderer,
+ * its own settings window and the overlay views mounted inside it. Deliberately
+ * excludes `trustedWindowSenderIds` — that map is shared by the whole app, so
+ * every context would claim the same host window and ownership would stop being
+ * unique. `createWindowContextRouter` routes on this check first for exactly
+ * that reason.
+ */
+export declare function createWorkbenchOwnedSenderCheck(ctx: Pick<WorkbenchContext, 'windows' | 'views'>): SenderPolicy;
 //# sourceMappingURL=sender-policy.d.ts.map

package/dist/main/utils/sender-policy.js

@@ -29,6 +29,26 @@
  * iframe — is rejected.
  */
 export function createWorkbenchSenderPolicy(ctx) {
+    const ownsSender = createWorkbenchOwnedSenderCheck(ctx);
+    return (sender) => {
+        if (ownsSender(sender))
+            return true;
+        if (sender.isDestroyed())
+            return false;
+        // Host-registered trusted windows (registerTrustedWindow). The map is
+        // app-wide, so this is the one accepted sender no single context owns.
+        return ctx.trustedWindowSenderIds.has(sender.id);
+    };
+}
+/**
+ * The senders this context structurally OWNS: its own main-window renderer,
+ * its own settings window and the overlay views mounted inside it. Deliberately
+ * excludes `trustedWindowSenderIds` — that map is shared by the whole app, so
+ * every context would claim the same host window and ownership would stop being
+ * unique. `createWindowContextRouter` routes on this check first for exactly
+ * that reason.
+ */
+export function createWorkbenchOwnedSenderCheck(ctx) {
     return (sender) => {
         if (sender.isDestroyed())
             return false;
@@ -38,9 +58,6 @@ export function createWorkbenchSenderPolicy(ctx) {
         // Standalone settings BrowserWindow renderer
         if (ctx.windows.isSettingsWindowSender(sender.id))
             return true;
-        // Host-registered trusted windows (registerTrustedWindow)
-        if (ctx.trustedWindowSenderIds.has(sender.id))
-            return true;
         // Settings overlay view (mounted inside the main window)
         const settingsViewId = ctx.views.getSettingsWebContentsId();
         if (settingsViewId != null && sender.id === settingsViewId)
@@ -64,6 +81,12 @@ export function createWorkbenchSenderPolicy(ctx) {
         const updateDialogViewId = ctx.views.getUpdateDialogWebContentsId();
         if (updateDialogViewId != null && sender.id === updateDialogViewId)
             return true;
+        // Device-picker overlay view. Same devtools-owned trust level — the
+        // simulator toolbar's device selector, moved out of the main renderer's
+        // DOM so the simulator WCV can't occlude it.
+        const devicePickerViewId = ctx.views.getDevicePickerWebContentsId();
+        if (devicePickerViewId != null && sender.id === devicePickerViewId)
+            return true;
         // The host-toolbar overlay is DELIBERATELY NOT trusted here. The host loads
         // arbitrary content into it, so granting it the global white-list would open
         // all ~72 IpcRegistry channels to that content. Its one channel (the reverse

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

@@ -15,8 +15,9 @@ export declare function themeBg(): string;
  * phone keeps contrast against it in BOTH schemes.
  *
  * Dark: #282828 | Light: #f7f7f9 — both match the renderer's --color-surface-2
- * chrome tone (design.css). Dark is devtools-owned rather than a Cornetto
- * --qd-muted alias: pixel-verified against Figma node 66:1729 at rgb(40,40,40),
+ * chrome tone (@dimina-kit/design, css/tokens.css). Dark is a package-owned
+ * value rather than a Cornetto --qd-muted alias: pixel-verified against Figma
+ * node 66:1729 at rgb(40,40,40),
  * which doesn't match any Cornetto dark token (--qd-muted is #383838, off by
  * 16 units — confirmed too light against the app's own dark-mode screenshots).
  * Light's #f7f7f9 IS an exact --qd-muted match (verified against node 25:5),

package/dist/main/utils/theme.js

@@ -19,8 +19,9 @@ export function themeBg() {
  * phone keeps contrast against it in BOTH schemes.
  *
  * Dark: #282828 | Light: #f7f7f9 — both match the renderer's --color-surface-2
- * chrome tone (design.css). Dark is devtools-owned rather than a Cornetto
- * --qd-muted alias: pixel-verified against Figma node 66:1729 at rgb(40,40,40),
+ * chrome tone (@dimina-kit/design, css/tokens.css). Dark is a package-owned
+ * value rather than a Cornetto --qd-muted alias: pixel-verified against Figma
+ * node 66:1729 at rgb(40,40,40),
  * which doesn't match any Cornetto dark token (--qd-muted is #383838, off by
  * 16 units — confirmed too light against the app's own dark-mode screenshots).
  * Light's #f7f7f9 IS an exact --qd-muted match (verified against node 25:5),

package/dist/main/windows/main-window/create.d.ts

@@ -6,6 +6,14 @@ export interface WindowOptions {
     minWidth?: number;
     minHeight?: number;
     indexHtml: string;
+    /**
+     * Query string appended to the loaded `file://` URL. This is how a window
+     * receives its own bootstrap identity (the workbench window reads the project
+     * it belongs to from here), so the renderer entry knows what to mount without
+     * a round-trip. Survives navigation-hardening: that check matches on the
+     * `file://` prefix only and ignores the query (see navigation-hardening.ts).
+     */
+    query?: Record<string, string>;
     /**
      * Auto-show the window on `ready-to-show` in non-test envs. Defaults to
      * `true`. `false` lets a login-gating host keep the window hidden and call
@@ -13,5 +21,13 @@ export interface WindowOptions {
      */
     autoShow?: boolean;
 }
+/**
+ * Shows `win` the way the current env expects: `showInactive()` in test env
+ * so e2e windows don't steal focus, `show()` otherwise. Shared by this
+ * module's own `ready-to-show` handler and by the workbench window manager's
+ * reveal-after-hook-and-paint gate (`workbench-window.ts`), so the two reveal
+ * paths can never pick different show methods.
+ */
+export declare function revealMainWindow(win: BrowserWindow): void;
 export declare function createMainWindow(opts: WindowOptions): BrowserWindow;
 //# sourceMappingURL=create.d.ts.map

package/dist/main/windows/main-window/create.js

@@ -3,6 +3,19 @@ import path from 'path';
 import { mainPreloadPath } from '../../utils/paths.js';
 import { themeBg } from '../../utils/theme.js';
 import { applyNavigationHardening } from '../navigation-hardening.js';
+/**
+ * Shows `win` the way the current env expects: `showInactive()` in test env
+ * so e2e windows don't steal focus, `show()` otherwise. Shared by this
+ * module's own `ready-to-show` handler and by the workbench window manager's
+ * reveal-after-hook-and-paint gate (`workbench-window.ts`), so the two reveal
+ * paths can never pick different show methods.
+ */
+export function revealMainWindow(win) {
+    if (process.env.NODE_ENV === 'test')
+        win.showInactive();
+    else
+        win.show();
+}
 export function createMainWindow(opts) {
     const mainWindow = new BrowserWindow({
         width: opts.width ?? 1280,
@@ -25,16 +38,11 @@ export function createMainWindow(opts) {
         const isTest = process.env.NODE_ENV === 'test';
         // Visibility is governed by `autoShow` in BOTH envs. A login-gating host
         // opts out via `autoShow: false` and reveals the window itself once auth
-        // passes — don't flash an un-authed window. The env only chooses HOW to
-        // show: test uses showInactive() so e2e windows don't steal focus, prod
-        // uses show(). The framework must never force-show when the host opted
-        // out, in test env either (that would fight the host's own reveal handler).
-        if (opts.autoShow !== false) {
-            if (isTest)
-                mainWindow.showInactive();
-            else
-                mainWindow.show();
-        }
+        // passes — don't flash an un-authed window. The framework must never
+        // force-show when the host opted out, in test env either (that would
+        // fight the host's own reveal handler).
+        if (opts.autoShow !== false)
+            revealMainWindow(mainWindow);
         // Don't auto-open a detached DevTools for the devtools UI shell itself —
         // it's noise for normal use (the mini-app's Console lives in the embedded
         // right-panel DevTools, not here). Opt in via env for debugging the shell.
@@ -46,7 +54,7 @@ export function createMainWindow(opts) {
     // Restrict the main renderer to file:// URLs under the renderer bundle and
     // route every popup through the OS browser. See navigation-hardening.ts.
     applyNavigationHardening(mainWindow.webContents, rendererDir);
-    mainWindow.loadFile(opts.indexHtml);
+    mainWindow.loadFile(opts.indexHtml, opts.query ? { query: opts.query } : undefined);
     const container = new View();
     const mainWebView = mainWindow.contentView;
     container.addChildView(mainWebView);

package/dist/main/windows/main-window/events.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserWindow } from 'electron';
+import { BrowserWindow } from 'electron';
 import type { WorkbenchContext } from '../../services/workbench-context.js';
 import { type Disposable } from '@dimina-kit/electron-deck/main';
 export interface MainWindowEventState {

package/dist/main/windows/main-window/events.js

@@ -1,5 +1,29 @@
-import { globalShortcut } from 'electron';
+import { BrowserWindow, globalShortcut } from 'electron';
 import { DisposableRegistry, toDisposable } from '@dimina-kit/electron-deck/main';
+const DEVTOOLS_ACCELERATOR = 'CommandOrControl+Shift+I';
+let devToolsShortcutHolders = 0;
+/**
+ * Claims a share of the ONE process-wide DevTools accelerator. `globalShortcut`
+ * is a process singleton: a per-window registration is refused for every window
+ * after the first, which would give that first window the shortcut for the
+ * whole app and kill it outright when that window closed. So the accelerator is
+ * registered once, opens whichever window is focused when it is pressed, and is
+ * released only when the last holder lets go — a later window can then claim it
+ * again. `unregisterAll()` in lifecycle stays as a process-exit safety net.
+ */
+function acquireDevToolsShortcut() {
+    if (devToolsShortcutHolders === 0) {
+        globalShortcut.register(DEVTOOLS_ACCELERATOR, () => {
+            BrowserWindow.getFocusedWindow()?.webContents.openDevTools({ mode: 'detach' });
+        });
+    }
+    devToolsShortcutHolders += 1;
+    return toDisposable(() => {
+        devToolsShortcutHolders -= 1;
+        if (devToolsShortcutHolders === 0)
+            globalShortcut.unregister(DEVTOOLS_ACCELERATOR);
+    });
+}
 export function wireMainWindowEvents(win, state = {}) {
     const registry = new DisposableRegistry();
     const mainWebView = win.contentView.children[0];
@@ -24,18 +48,7 @@ export function wireMainWindowEvents(win, state = {}) {
             win.removeListener('close', onCloseHandler);
         }));
     }
-    // DevTools shortcut: scoped to this main window so its disposal is tied
-    // to ctx.registry. `unregisterAll()` in lifecycle remains as a process-exit
-    // safety net.
-    const devToolsAccelerator = 'CommandOrControl+Shift+I';
-    const registered = globalShortcut.register(devToolsAccelerator, () => {
-        win.webContents.openDevTools({ mode: 'detach' });
-    });
-    if (registered) {
-        registry.add(toDisposable(() => {
-            globalShortcut.unregister(devToolsAccelerator);
-        }));
-    }
+    registry.add(acquireDevToolsShortcut());
     return registry;
 }
 //# sourceMappingURL=events.js.map