@dimina-kit/devtools 0.4.0 → 0.5.0-dev.20260908120530

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

@@ -1,7 +1,13 @@
 import { nativeTheme, WebContentsView } from 'electron';
 import { handleWindowOpenExternal } from '../../windows/navigation-hardening.js';
+import { themeBg } from '../../utils/theme.js';
 import { VIEW_ID } from '../../../shared/view-ids.js';
-import { destroyChildView } from './destroy-child-view.js';
+/**
+ * Upper bound on how long a hold may defer the workbench attach. A hung or
+ * very slow first compile (or a lost release on some open path) degrades to a
+ * bounded editor delay plus a warn — never a permanently blank editor slot.
+ */
+const ATTACH_HOLD_CAP_MS = 3000;
 export function createWorkbenchView(ctx, reconciler) {
     let workbenchView = null;
     // Whether the devtools-theme → workbench-theme `nativeTheme` listener is live.
@@ -11,8 +17,20 @@ export function createWorkbenchView(ctx, reconciler) {
     // heavy WebContentsView load is deferred until the 'editor' slot first becomes
     // visible (first non-zero `setWorkbenchBounds`) so it never sits on the app
     // boot critical path (which would delay preload/window-ready and trip the e2e
-    // health check into a relaunch).
+    // health check into a relaunch), and further deferred while an attach hold
+    // (below) is in force.
     let workbenchUrl = null;
+    // Attach gate: while held (and the view does not exist yet), the lazy attach
+    // is deferred so the workbench's heavy load never competes with a project
+    // open's boot-critical window (old-session teardown + first compile) for
+    // CPU. Generation-tagged: a newer hold supersedes an older one (latest-wins,
+    // mirroring the open op-lock), so a superseded open's late release cannot
+    // open a newer open's gate. The gate only postpones creation — it never
+    // hides or destroys an existing view, and detachWorkbench leaves it intact
+    // (an in-flight open holds across the old view's teardown).
+    let attachHeld = false;
+    let attachHoldGeneration = 0;
+    let attachHoldTimer = null;
     /** Current devtools color scheme, mirrored into the workbench's theme. */
     function workbenchThemeScheme() {
         return nativeTheme.shouldUseDarkColors ? 'dark' : 'light';
@@ -27,6 +45,14 @@ export function createWorkbenchView(ctx, reconciler) {
         if (!workbenchView || workbenchView.webContents.isDestroyed())
             return;
         const wc = workbenchView.webContents;
+        // Keep the WCV surface in sync with the active color scheme: the workbench
+        // page can only recolor its own inner #workbench, never the html/body
+        // backdrop, so the native surface must follow the theme flip too.
+        try {
+            if (typeof workbenchView.setBackgroundColor === 'function')
+                workbenchView.setBackgroundColor(themeBg());
+        }
+        catch { /* view/wc gone mid-flip */ }
         if (typeof wc.executeJavaScript !== 'function')
             return;
         const script = `window.__WB_SET_THEME && window.__WB_SET_THEME(${JSON.stringify(workbenchThemeScheme())})`;
@@ -43,6 +69,17 @@ export function createWorkbenchView(ctx, reconciler) {
             },
         });
         workbenchView = view;
+        // Paint the WCV surface the themed window background (themeBg(): dark
+        // #1a1a1a / light #fafafa) so the boot screen ("booting workbench…") and
+        // any layout gap never flash a mismatched white strip before the workbench
+        // CSS loads. The workbench is a plain WebContentsView (not a BrowserWindow),
+        // so the process-wide installThemeBackgroundSync() never reaches it — match
+        // the main window's own backgroundColor here, and re-sync on every theme
+        // flip below.
+        try {
+            view.setBackgroundColor(themeBg());
+        }
+        catch { /* view not ready for a bg yet */ }
         // Track devtools theme flips for the lifetime of the workbench view only —
         // registered here (not at construction) so test electron mocks that omit
         // `nativeTheme` and never open the editor stay unaffected. Removed in
@@ -58,9 +95,13 @@ export function createWorkbenchView(ctx, reconciler) {
             view.webContents.setWindowOpenHandler(({ url: target }) => handleWindowOpenExternal(target));
         }
         catch { /* stub may lack it */ }
-        ctx.windows.mainWindow.contentView.addChildView(view);
         // Hand the workbench the current devtools scheme as a URL query so its very
         // first paint already matches (the runtime setter only exists post-init).
+        // The project identity deliberately does NOT ride this URL: the attach can
+        // happen before the open commits a session (the gate self-releases after
+        // ATTACH_HOLD_CAP_MS on a slow compile, and the release fires just ahead of
+        // the commit), so the page polls it from the COI server's `/__project`
+        // instead — see workbench-coi-server.ts.
         const loadUrl = `${url}index.html?theme=${workbenchThemeScheme()}`;
         await view.webContents.loadURL(loadUrl).catch((err) => {
             console.error('[workbench] attachWorkbench — loadURL failed', err);
@@ -70,14 +111,63 @@ export function createWorkbenchView(ctx, reconciler) {
     function setWorkbenchSource(url) {
         workbenchUrl = url;
     }
+    // Release the gate for `generation` (stale generations no-op) and replay the
+    // reconcile so a pending visible desired attaches through the normal lazy
+    // path. `viaCap` marks the self-release at the hold cap — loud, so a slow
+    // compile and a lost release stay distinguishable from a normal settle.
+    function releaseAttachHold(generation, viaCap) {
+        if (!attachHeld || generation !== attachHoldGeneration)
+            return;
+        attachHeld = false;
+        if (attachHoldTimer) {
+            clearTimeout(attachHoldTimer);
+            attachHoldTimer = null;
+        }
+        if (viaCap) {
+            console.warn(`[workbench] attach gate: hold not released within ${ATTACH_HOLD_CAP_MS}ms (compile still running or a release was lost) — attaching now`);
+        }
+        reconciler.reconcileNow();
+    }
+    /**
+     * Close the attach gate until the returned release fn runs, a newer hold
+     * supersedes it, explicit user intent (openFileInWorkbench) opens it, or the
+     * cap timer fires. The release fn is idempotent and generation-bound.
+     */
+    function holdWorkbenchAttach() {
+        const generation = ++attachHoldGeneration;
+        attachHeld = true;
+        if (attachHoldTimer)
+            clearTimeout(attachHoldTimer);
+        attachHoldTimer = setTimeout(() => releaseAttachHold(generation, true), ATTACH_HOLD_CAP_MS);
+        return () => releaseAttachHold(generation, false);
+    }
+    /**
+     * Void the current hold WITHOUT the release replay: the gate belongs to an
+     * open request, and a teardown that preempts it (closeProject / app-level
+     * disposeAll) invalidates that request — its late release or cap firing must
+     * not rebuild the view after the project is gone. Bumping the generation
+     * turns every pending release fn into a no-op; no-op when nothing is held.
+     */
+    function cancelWorkbenchAttachHold() {
+        if (!attachHeld && !attachHoldTimer)
+            return;
+        attachHeld = false;
+        attachHoldGeneration++;
+        if (attachHoldTimer) {
+            clearTimeout(attachHoldTimer);
+            attachHoldTimer = null;
+        }
+    }
     function detachWorkbench() {
         if (workbenchThemeSyncBound) {
             nativeTheme.removeListener('updated', pushWorkbenchTheme);
             workbenchThemeSyncBound = false;
         }
-        destroyChildView(ctx.windows.mainWindow, workbenchView);
+        reconciler.destroyView(VIEW_ID.workbench, workbenchView);
         workbenchView = null;
-        reconciler.deleteBaseDesired(VIEW_ID.workbench);
+        if (!attachHeld) {
+            reconciler.deleteBaseDesired(VIEW_ID.workbench);
+        }
         reconciler.reconcileNow();
     }
     // Build the `file:///workspace/<rel>` URI string with each path SEGMENT
@@ -123,6 +213,11 @@ export function createWorkbenchView(ctx, reconciler) {
     // the document is actually shown; false when there is no workbench view or
     // every attempt failed.
     function openFileInWorkbench(relPath, line, column) {
+        // Explicit user intent (a source-link click) beats the boot-priority
+        // scheduling: open the gate first so the release's reconcile replay can
+        // lazy-create the view synchronously before the liveness check below.
+        if (attachHeld)
+            releaseAttachHold(attachHoldGeneration, false);
         if (!workbenchView || workbenchView.webContents.isDestroyed())
             return false;
         // The workbench mirrors the active project under file:///workspace/<rel>; the
@@ -148,23 +243,15 @@ export function createWorkbenchView(ctx, reconciler) {
         return true;
     }
     // workbench is gated until it has a source or a live view (it lazy-creates
-    // from the URL in the attach op).
+    // from the URL in the attach op), and while an attach hold is in force.
     reconciler.registerView(VIEW_ID.workbench, {
         getView: () => workbenchView,
-        gateHidden: () => !workbenchView && !workbenchUrl,
-        beforeAttach: () => {
-            if (!workbenchView && workbenchUrl) {
-                // Lazy-load the workbench; attachWorkbench adds it to the contentView.
-                void attachWorkbench(workbenchUrl);
-                return true;
-            }
-            return false;
-        },
+        gateHidden: () => !workbenchView && (!workbenchUrl || attachHeld),
         ensureLazy: (desired) => {
-            if (desired?.placement.visible && !workbenchView && workbenchUrl)
+            if (desired?.placement.visible && !workbenchView && workbenchUrl && !attachHeld)
                 void attachWorkbench(workbenchUrl);
         },
     });
-    return { attachWorkbench, setWorkbenchSource, detachWorkbench, openFileInWorkbench };
+    return { attachWorkbench, setWorkbenchSource, detachWorkbench, openFileInWorkbench, holdWorkbenchAttach, cancelWorkbenchAttachHold };
 }
 //# sourceMappingURL=workbench-view.js.map

package/dist/main/services/window-contexts/context-router.d.ts

@@ -0,0 +1,36 @@
+import type { WebContents } from 'electron';
+import { type Disposable } from '@dimina-kit/electron-deck/main';
+import type { IpcContextSource } from '../../utils/ipc-context-source.js';
+import type { SenderPolicy } from '../../utils/ipc-registry.js';
+/**
+ * What the router needs of a window context to place an incoming sender.
+ * Kept to these two predicates so the router stays independent of the rest of
+ * the context; the concrete context type is supplied by the caller.
+ */
+export interface RoutableWindowContext {
+    /** Every sender this window accepts, app-shared trusted windows included. */
+    senderPolicy: SenderPolicy;
+    /** Only the senders this window structurally owns (see sender-policy.ts). */
+    ownsSender: SenderPolicy;
+}
+/** Registry of live window contexts, and the authority on which one owns a sender. */
+export interface WindowContextRouter<T extends RoutableWindowContext = RoutableWindowContext> extends IpcContextSource<T> {
+    /** Register a window context; the returned Disposable unregisters it. */
+    register(ctx: T): Disposable;
+    /**
+     * The context owning `sender`, or null when no registered context claims it.
+     * A pure query: looking a sender up never changes which context is active.
+     */
+    resolve(sender: WebContents): T | null;
+    /**
+     * The context last marked active by `setActive`. With none marked — or after
+     * the marked one unregisters — it falls back to the first still-registered
+     * context, and null when none are.
+     */
+    active(): T | null;
+    /** Mark `ctx` active (on window focus). Ignored for unregistered contexts. */
+    setActive(ctx: T): void;
+    list(): T[];
+}
+export declare function createWindowContextRouter<T extends RoutableWindowContext = RoutableWindowContext>(): WindowContextRouter<T>;
+//# sourceMappingURL=context-router.d.ts.map

package/dist/main/services/window-contexts/context-router.js

@@ -0,0 +1,55 @@
+import { toDisposable } from '@dimina-kit/electron-deck/main';
+export function createWindowContextRouter() {
+    const contexts = [];
+    let activeCtx = null;
+    const first = () => contexts[0] ?? null;
+    return {
+        register(ctx) {
+            contexts.push(ctx);
+            activeCtx ??= ctx;
+            return toDisposable(() => {
+                const at = contexts.indexOf(ctx);
+                if (at === -1)
+                    return;
+                contexts.splice(at, 1);
+                if (activeCtx === ctx)
+                    activeCtx = first();
+            });
+        },
+        resolve(sender) {
+            // Two passes, because the two predicates answer different questions.
+            // `senderPolicy` also accepts host windows registered through
+            // `registerTrustedWindow`, whose id map is app-wide — every context says
+            // yes to such a sender, so a single-pass scan would hand it to whichever
+            // window happened to register first. Pass one therefore only accepts a
+            // context that OWNS the sender (its own renderer, settings window or
+            // overlay views), which is unique by construction. Pass two covers the
+            // accepted-but-unowned senders that are left: they belong to the app
+            // rather than to a window, so the active window answers them.
+            //
+            // Neither pass moves "active": window focus is what decides which window
+            // an app-wide sender belongs to, and a background window handling its own
+            // IPC must not steal that answer from the focused one.
+            for (const ctx of contexts) {
+                if (ctx.ownsSender(sender))
+                    return ctx;
+            }
+            for (const ctx of contexts) {
+                if (ctx.senderPolicy(sender))
+                    return activeCtx ?? first();
+            }
+            return null;
+        },
+        active() {
+            return activeCtx ?? first();
+        },
+        setActive(ctx) {
+            if (contexts.includes(ctx))
+                activeCtx = ctx;
+        },
+        list() {
+            return contexts.slice();
+        },
+    };
+}
+//# sourceMappingURL=context-router.js.map

package/dist/main/services/workbench-coi-host.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The single http listener behind every project window's workbench bridge.
+ *
+ * Browser storage is keyed by ORIGIN: IndexedDB, OPFS, Cache Storage, service
+ * worker registrations, Web Locks and BroadcastChannel all live in a bucket
+ * named after scheme + host + PORT. A listener bound to port 0 gets a different
+ * port every time, so one http server per project window put every window on
+ * its own origin — the VS Code workspace- and global-scope mementos a window
+ * wrote (open editors, view state, explorer expansion) died with it, reopening
+ * the same project minted a fresh empty bucket, and each new port accumulated
+ * another service-worker registration and cache entry that nothing reclaimed.
+ *
+ * So the listener is shared by every window in the process and a window's
+ * bridge is addressed by an opaque path prefix (`/w/<token>/`) rather than by
+ * port: one origin for all workbenches, distinct `/__fs` + `/__project`
+ * routing per window. The prefix is routing, not a security boundary — pages
+ * on one origin can already reach each other's paths, which is the situation
+ * the app-wide server had before per-project windows existed.
+ *
+ * The listener also outlives the last window that used it, because closing
+ * every project and opening another one is an ordinary switch and must not
+ * move the origin. Only {@link closeAllCoiHosts} takes a listener down.
+ */
+import http from 'node:http';
+export interface CoiHostSession {
+    /**
+     * Answers one request for this window. `url` has already had the window's
+     * `/w/<token>` prefix stripped, so the handler sees the same pathnames it
+     * would on a server of its own.
+     */
+    handle: (req: http.IncomingMessage, res: http.ServerResponse, url: URL) => void;
+}
+export interface CoiHostRegistration {
+    /** Scheme + host + port of the shared listener, with no trailing slash. */
+    origin: string;
+    port: number;
+    /** The path segment that routes to this session. */
+    token: string;
+    /** Drops the route, closing the shared listener when the last one goes. */
+    release: () => Promise<void>;
+}
+/**
+ * Tear down every listener. For process shutdown and for test isolation — a
+ * window's own teardown never gets here, because the origin has to survive it.
+ */
+export declare function closeAllCoiHosts(): Promise<void>;
+export declare function registerCoiHostSession(opts: {
+    rootDir: string;
+    extensionsDir: string | null;
+    session: CoiHostSession;
+}): Promise<CoiHostRegistration>;
+//# sourceMappingURL=workbench-coi-host.d.ts.map

package/dist/main/services/workbench-coi-host.js

@@ -0,0 +1,227 @@
+/**
+ * The single http listener behind every project window's workbench bridge.
+ *
+ * Browser storage is keyed by ORIGIN: IndexedDB, OPFS, Cache Storage, service
+ * worker registrations, Web Locks and BroadcastChannel all live in a bucket
+ * named after scheme + host + PORT. A listener bound to port 0 gets a different
+ * port every time, so one http server per project window put every window on
+ * its own origin — the VS Code workspace- and global-scope mementos a window
+ * wrote (open editors, view state, explorer expansion) died with it, reopening
+ * the same project minted a fresh empty bucket, and each new port accumulated
+ * another service-worker registration and cache entry that nothing reclaimed.
+ *
+ * So the listener is shared by every window in the process and a window's
+ * bridge is addressed by an opaque path prefix (`/w/<token>/`) rather than by
+ * port: one origin for all workbenches, distinct `/__fs` + `/__project`
+ * routing per window. The prefix is routing, not a security boundary — pages
+ * on one origin can already reach each other's paths, which is the situation
+ * the app-wide server had before per-project windows existed.
+ *
+ * The listener also outlives the last window that used it, because closing
+ * every project and opening another one is an ordinary switch and must not
+ * move the origin. Only {@link closeAllCoiHosts} takes a listener down.
+ */
+import http from 'node:http';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { serveStaticFile, setIsolationHeaders } from './workbench-coi-static.js';
+import { createCoiServerShutdown } from './workbench-coi-shutdown.js';
+/**
+ * Tear down every listener. For process shutdown and for test isolation — a
+ * window's own teardown never gets here, because the origin has to survive it.
+ */
+export async function closeAllCoiHosts() {
+    if (closingAll)
+        return closingAll;
+    const pending = [...hosts.values()];
+    hosts.clear();
+    const run = (async () => {
+        await Promise.all(pending.map(async (p) => {
+            const host = await p.catch(() => null);
+            if (!host || host.closed)
+                return;
+            host.closed = true;
+            await host.shutdown.close(host.server);
+        }));
+    })();
+    closingAll = run;
+    try {
+        await run;
+    }
+    finally {
+        if (closingAll === run)
+            closingAll = null;
+    }
+}
+/**
+ * One host per bundle + extensions pair. Two hosts serving different bundles
+ * are genuinely different servers; every window of one app shares one entry.
+ */
+const hosts = new Map();
+/**
+ * In-flight {@link closeAllCoiHosts}. A registration that was already waiting
+ * on `createHost` when a global close began must not hand its window an origin
+ * that close is about to take away, so it waits here and starts a fresh host.
+ */
+let closingAll = null;
+const WINDOW_PREFIX = /^\/w\/([A-Za-z0-9-]+)(\/.*)?$/;
+function notFound(res) {
+    res.writeHead(404);
+    res.end('Not Found');
+}
+function badRequest(res) {
+    res.writeHead(400);
+    res.end('Bad Request');
+}
+function serverError(res) {
+    res.writeHead(500);
+    res.end('Internal Server Error');
+}
+async function createHost(rootDir) {
+    const sessions = new Map();
+    const shutdown = createCoiServerShutdown();
+    const server = http.createServer((req, res) => {
+        setIsolationHeaders(res);
+        let url;
+        try {
+            url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        }
+        catch {
+            // A malformed request line must not become an uncaught exception in the
+            // main process.
+            badRequest(res);
+            return;
+        }
+        const routed = WINDOW_PREFIX.exec(url.pathname);
+        if (routed) {
+            const session = sessions.get(routed[1]);
+            // A request for a window that has already been torn down. 404 rather
+            // than fall through to the bundle: the caller asked for one specific
+            // window's bridge, and answering with another window's data would be
+            // worse than not answering.
+            if (!session) {
+                notFound(res);
+                return;
+            }
+            // Strip the prefix by rewriting `pathname` on a copy. Re-parsing the
+            // remainder as a URL reference would read a leading `//` as an authority,
+            // so `/w/<token>//__project` would arrive as `/` on host `__project`.
+            const forwarded = new URL(url);
+            forwarded.pathname = routed[2] || '/';
+            try {
+                session.handle(req, res, forwarded);
+            }
+            catch (err) {
+                // One window's handler must not take the shared listener's process
+                // with it — an uncaught exception here would end every other project
+                // window too. A handler answers its own client errors (a malformed
+                // percent escape, say), so anything reaching this point is a defect in
+                // it: 500 rather than 400, and logged, because a silent 400 would read
+                // as the caller's fault and hide the bug for good.
+                console.error('[workbench-coi] session handler threw', err);
+                if (res.headersSent)
+                    res.destroy();
+                else
+                    serverError(res);
+            }
+            return;
+        }
+        // No window prefix. Every bridge endpoint has to know WHICH window asked,
+        // so answering one here would mean guessing a project — the ambiguity the
+        // prefix exists to remove. The bundle itself is project-independent and is
+        // still served, so an absolute asset URL inside it keeps working.
+        if (url.pathname.startsWith('/__')) {
+            notFound(res);
+            return;
+        }
+        let decoded;
+        try {
+            decoded = decodeURIComponent(url.pathname);
+        }
+        catch {
+            // A stray `%` in the path. Answering 400 keeps the listener alive; the
+            // throw would otherwise escape the request handler.
+            badRequest(res);
+            return;
+        }
+        shutdown.trackRequest(res);
+        serveStaticFile(res, rootDir, decoded);
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr ? addr.port : 0;
+    return {
+        server,
+        origin: `http://127.0.0.1:${port}`,
+        port,
+        rootDir,
+        sessions,
+        shutdown,
+        closed: false,
+    };
+}
+export async function registerCoiHostSession(opts) {
+    const rootDir = path.resolve(opts.rootDir);
+    // JSON, not a separator character: `('/a', '/b|/c')` and `('/a|/b', '/c')`
+    // are both legal path pairs and would otherwise collide onto one host, so two
+    // different bundles would serve each other's files.
+    const key = JSON.stringify([rootDir, opts.extensionsDir ?? null]);
+    // Loop rather than a single lookup: a release running concurrently can have
+    // marked the cached host closed without having removed it yet, and joining a
+    // closing server would hand back a dead origin.
+    for (;;) {
+        if (closingAll) {
+            await closingAll;
+            continue;
+        }
+        let pending = hosts.get(key);
+        if (!pending) {
+            pending = createHost(rootDir);
+            hosts.set(key, pending);
+        }
+        let host;
+        try {
+            host = await pending;
+        }
+        catch (err) {
+            if (hosts.get(key) === pending)
+                hosts.delete(key);
+            throw err;
+        }
+        // `closingAll` is re-checked because it can have started while this
+        // registration was awaiting `pending`: the host may still read as open and
+        // yet be one `await` away from losing its port.
+        if (host.closed || closingAll || hosts.get(key) !== pending) {
+            if (hosts.get(key) === pending)
+                hosts.delete(key);
+            continue;
+        }
+        const token = randomUUID();
+        host.sessions.set(token, opts.session);
+        let released = false;
+        return {
+            origin: host.origin,
+            port: host.port,
+            token,
+            release: async () => {
+                if (released)
+                    return;
+                released = true;
+                host.sessions.delete(token);
+                // The listener deliberately stays up with no windows on it. Closing it
+                // would release the port, and the next window would bind a different
+                // one — a different origin, so the storage the closed window wrote
+                // would be unreachable. Closing the last project and opening another
+                // is the ordinary way to switch projects, so the origin has to hold
+                // for the life of the process, not just while a window is open.
+            },
+        };
+    }
+}
+//# sourceMappingURL=workbench-coi-host.js.map

package/dist/main/services/workbench-coi-server.d.ts

@@ -21,6 +21,17 @@ export interface WorkbenchCoiServerOptions {
      * for none (built-in `wx*` associations only).
      */
     getFileTypes?: () => unknown;
+    /**
+     * Reads the active project's identity — `appId` (null until the open commits
+     * a session) plus its root path — served at `/__project` as the workspace id
+     * the editor names its VS Code workspace after. Read per-request, because the
+     * editor page can load BEFORE the project commits (see `/__project` below).
+     * Omit when the host has no project identity to offer.
+     */
+    getProjectIdentity?: () => {
+        appId: string | null;
+        projectPath: string;
+    };
 }
 export declare function startWorkbenchCoiServer(options: WorkbenchCoiServerOptions): Promise<WorkbenchCoiServer>;
 //# sourceMappingURL=workbench-coi-server.d.ts.map