@dimina-kit/devtools 0.4.0-dev.20260718095333 → 0.4.0-dev.20260728063215

package/dist/main/index.js

@@ -1,10 +1,58 @@
 import { app } from 'electron';
 import { launch } from './app/launch.js';
+import { createGitHubReleaseChecker } from './services/update/index.js';
+// Only a packaged RELEASE-channel build self-updates against this repo's
+// GitHub Releases:
+// - `pnpm dev` runs stay quiet (no API calls, no update dialog) — same
+//   app.isPackaged gate used elsewhere for dev-only behavior.
+// - A packaged DEV-channel build (release.yml's `channel: dev` — distributed
+//   only as a 30-day Actions artifact for QA/branch testing, never a GitHub
+//   Release) must NOT get this either: release.yml's dev channel never
+//   creates a GitHub Release, so /releases/latest always reflects the
+//   RELEASE channel — a dev build would be prompted to "update" to an
+//   unrelated stable build, and clicking it would silently swap out the
+//   very branch/PR build the person downloaded it to test. dev-channel
+//   versions always carry bump-dev-version.js's `-dev.<timestamp>` suffix;
+//   release-channel versions never do — use that as the channel signal.
+// - Hosts that embed devtools via `launch(config)` supply their own
+//   `updateChecker` (or none) and are unaffected — this default only
+//   applies to this entry point.
+//
+// Custom parseVersion, NOT the default asset-name fallback and NOT
+// 'trailing-number':
+// - release.yml's GitHub Release tag (`release-YYYYMMDD-N`) is an unrelated
+//   release-sequence label, not this app's version — 'trailing-number' would
+//   compare its bare counter against app.getVersion() (e.g. "0.4.0")
+//   numerically, which looks "newer" once the counter passes the app's major
+//   version, reporting an update on every single check forever.
+// - The built-in asset-name fallback (defaultParseVersion's SEMVER_RE) finds
+//   the version inside `dimina-devtools-0.4.0-mac-arm64.dmg` (see release.yml's
+//   "Rename macOS dmg" / Archive steps) but its optional prerelease-suffix
+//   capture greedily swallows the trailing `-mac-arm64.dmg` as a "prerelease"
+//   tag, so the update dialog would show a garbled "0.5.0-mac-arm64.dmg".
+//   Extract just the clean `x.y.z` from our own known asset naming instead.
+// Short-circuited: app.getVersion() must only be read once isPackaged is
+// already known true, both because it's meaningless before then and because
+// some minimal test/dev electron mocks don't stub getVersion() at all.
+const updateChecker = app.isPackaged && !app.getVersion().includes('-dev.')
+    ? createGitHubReleaseChecker({
+        owner: 'EchoTechFE',
+        repo: 'dimina-kit',
+        parseVersion: (release) => {
+            for (const asset of release.assets) {
+                const match = /^dimina-devtools-(\d+\.\d+\.\d+)-/.exec(asset.name);
+                if (match)
+                    return match[1];
+            }
+            return null;
+        },
+    })
+    : undefined;
 // Fire-and-forget boot: launch() returns the electron-deck whenReady gate
 // promise. A bare call would let a boot failure escape as an unhandledRejection
 // (no diagnostics, can be swallowed). Surface it via a structured failure exit:
 // log the cause and exit non-zero (per workbench-model.md fire-and-forget rule).
-launch().catch((err) => {
+launch({ updateChecker }).catch((err) => {
     console.error('[devtools] fatal: launch() failed during boot', err);
     app.exit(1);
 });

package/dist/main/ipc/bridge-router.d.ts

@@ -33,6 +33,33 @@ export interface RenderEvent {
      * Lets the current-page panel push the route without a separate lookup. */
     pagePath?: string;
 }
+/**
+ * Fires once per app session, the moment its hidden SERVICE HOST window's
+ * `service.html` document has `did-finish-load`'d — i.e. `serviceWcId` is
+ * GUARANTEED resolvable via `webContents.fromId(serviceWcId)` right now. This
+ * is document readiness, NOT mini-app runtime readiness: `injectLogicBundle`
+ * and the service's own `serviceResourceLoaded` handshake both happen AFTER
+ * this fires (see `bootServiceHost`) — a consumer that needs "the mini-app
+ * has actually booted" must not treat this as that signal.
+ *
+ * Exists so a consumer that needs to act on the service host wc THE MOMENT it
+ * becomes resolvable (e.g. attaching the right-panel DevTools front-end) has
+ * a real event to react to instead of polling `getServiceWc(appId)` on a
+ * fixed retry budget and silently giving up if that budget is exhausted
+ * before the wc resolves under load — the bug this event was added to fix
+ * (see `native-simulator-devtools-host.ts`'s `onServiceHostReady` subscriber).
+ *
+ * `appId`-keyed resolution (`getServiceWc(appId)`) is NOT equivalent to this
+ * event during same-app respawn overlap — `getServiceWc` returns the MOST
+ * RECENT live session for that appId, which may not be the specific session
+ * that just fired this event. Consumers that must target the EXACT session
+ * should resolve `serviceWcId` directly rather than re-resolving by `appId`.
+ */
+export interface ServiceHostReadyEvent {
+    appId: string;
+    appSessionId: string;
+    serviceWcId: number;
+}
 /**
  * Point-in-time counts of every resource class RouterState owns. Leak coverage
  * (unit + e2e) asserts EXACT equality of this ledger around a churn cycle —
@@ -75,8 +102,17 @@ export interface BridgeRouterHandle {
      * before the first PAGE_STACK signal. Optional: only the native-host bridge
      * provides it (the default path derives the stack from the simulator URL). */
     getPageStack?(appId?: string): PageStackEntry[] | null;
+    /** The current (or named) app session's resource-server baseUrl (serves
+     * that session's framework js/css), or null when no matching session
+     * exists. Per-session, never a global singleton — see AppSession.resourceBaseUrl. */
+    getResourceBaseUrl?(appId?: string): string | null;
     /** Subscribe to render-side activity (domReady / active-page change). */
     onRenderEvent(listener: (event: RenderEvent) => void): () => void;
+    /** Subscribe to a service host's `did-finish-load` readiness (see
+     * `ServiceHostReadyEvent`'s doc comment). A subscriber registering after
+     * the still-live session's event already fired gets a missed-signal
+     * catch-up — it never needs to poll. */
+    onServiceHostReady(listener: (event: ServiceHostReadyEvent) => void): () => void;
     /** The currently-selected device (renderer toolbar), or null pre-selection. */
     getDevice(): NativeDeviceInfo | null;
     /** Cache the selected device + push DEVICE_CHANGE to the live simulator WC(s). */

package/dist/main/ipc/bridge-router.js

@@ -166,6 +166,8 @@ export function installBridgeRouter(ctx) {
         pendingApiCalls: new Map(),
         pool: null,
         emitRenderEvent: () => { },
+        emitServiceHostReady: () => { },
+        lastServiceHostReady: null,
         connections: ctx.connections,
         debugTap: createDebugTap({ enabled: resolveDebugTapEnabled() }),
         appLifecycle: createAppLifecycleController(),
@@ -237,6 +239,22 @@ export function installBridgeRouter(ctx) {
         }
     };
     state.emitRenderEvent = emitRenderEvent;
+    // Subscribers to `ServiceHostReadyEvent` (see its doc comment). Separate
+    // from `renderEventListeners`: this is session-scoped (appSessionId +
+    // serviceWcId), not page/bridgeId-scoped like `RenderEvent`.
+    const serviceHostReadyListeners = new Set();
+    const emitServiceHostReady = (event) => {
+        state.lastServiceHostReady = event;
+        for (const listener of serviceHostReadyListeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                console.warn('[bridge-router] service-host-ready listener threw:', error);
+            }
+        }
+    };
+    state.emitServiceHostReady = emitServiceHostReady;
     // Expose a thin accessor over RouterState so other main services (storage,
     // automation, appdata) can resolve live render/service WebContents without
     // owning router state. Getters resolve fresh — the pre-warm pool can swap
@@ -269,6 +287,10 @@ export function installBridgeRouter(ctx) {
             const ap = resolveCurrentApp(state, ctx, appId);
             return ap?.pageStack ?? null;
         },
+        getResourceBaseUrl: (appId) => {
+            const ap = resolveCurrentApp(state, ctx, appId);
+            return ap?.resourceBaseUrl ?? null;
+        },
         getActiveRenderWc: (appId) => {
             const ap = resolveCurrentApp(state, ctx, appId);
             if (!ap)
@@ -280,6 +302,35 @@ export function installBridgeRouter(ctx) {
             renderEventListeners.add(listener);
             return () => renderEventListeners.delete(listener);
         },
+        onServiceHostReady: (listener) => {
+            serviceHostReadyListeners.add(listener);
+            // Missed-signal catch-up (mirrors host-toolbar-port-channel.ts's
+            // `onReady`): a subscriber registering AFTER the session it cares
+            // about already booted must not wait forever for an event that
+            // already happened. Scheduled on a microtask (never synchronous —
+            // matches the same-tick-dispose/re-attach safety the host-toolbar
+            // pattern documents) and RE-VALIDATED at fire time: the session must
+            // still be live and still bound to the SAME serviceWcId the event
+            // captured, so a session that respawned/closed between registration
+            // and the microtask can't resurrect a stale attach.
+            const candidate = state.lastServiceHostReady;
+            if (candidate) {
+                queueMicrotask(() => {
+                    if (!serviceHostReadyListeners.has(listener))
+                        return;
+                    const ap = state.appSessions.get(candidate.appSessionId);
+                    if (!ap || ap.serviceWc.isDestroyed() || ap.serviceWc.id !== candidate.serviceWcId)
+                        return;
+                    try {
+                        listener(candidate);
+                    }
+                    catch (error) {
+                        console.warn('[bridge-router] service-host-ready catch-up listener threw:', error);
+                    }
+                });
+            }
+            return () => serviceHostReadyListeners.delete(listener);
+        },
         getDevice: () => currentDevice,
         setDevice: (device) => {
             currentDevice = device;
@@ -970,6 +1021,11 @@ async function bootServiceHost(state, ap, ctx) {
     // any diagnostic queued for this session (or the global bucket) into its now
     // resolvable console. Safe to call even when nothing is queued.
     ctx.consoleForwarder?.notifyServiceHostReady?.(ap.appSessionId);
+    // Same authoritative moment, exposed as a general subscribable event (see
+    // `ServiceHostReadyEvent`'s doc comment) — other main-process consumers
+    // (the right-panel DevTools attach) need this exact signal too and must
+    // not poll `getServiceWc` on a fixed retry budget for it.
+    state.emitServiceHostReady({ appId: ap.appId, appSessionId: ap.appSessionId, serviceWcId: ap.serviceWc.id });
     ap.logicInjected = await injectLogicBundle(ap);
     if (!ap.logicInjected) {
         // The compiled logic.js never executed, so `modDefine` registered nothing.

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

@@ -4,5 +4,6 @@ export { registerPopoverIpc, popoverModule } from './popover.js';
 export { registerProjectsIpc, projectsModule } from './projects.js';
 export { registerSessionIpc, sessionModule } from './session.js';
 export { registerSettingsIpc, settingsModule } from './settings.js';
+export { registerInternalDevtoolsIpc } from './internal-devtools.js';
 export { simulatorModule } from './simulator-module.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/main/ipc/index.js

@@ -4,5 +4,6 @@ export { registerPopoverIpc, popoverModule } from './popover.js';
 export { registerProjectsIpc, projectsModule } from './projects.js';
 export { registerSessionIpc, sessionModule } from './session.js';
 export { registerSettingsIpc, settingsModule } from './settings.js';
+export { registerInternalDevtoolsIpc } from './internal-devtools.js';
 export { simulatorModule } from './simulator-module.js';
 //# sourceMappingURL=index.js.map

package/dist/main/ipc/internal-devtools.d.ts

@@ -0,0 +1,15 @@
+import type { Disposable } from '@dimina-kit/electron-deck/main';
+import { type SenderPolicy } from '../utils/ipc-registry.js';
+import type { InternalDevtoolsWindow } from '../windows/internal-devtools-window/index.js';
+/**
+ * Standalone internal (app-wide) DevTools debug window. The simulator
+ * toolbar's "debug" button opens (or focuses) it via the window controller —
+ * a module-local narrow deps interface, not `WorkbenchContext`, per the
+ * shrink-only WorkbenchContext-import gate (see eslint.config.js).
+ */
+export interface InternalDevtoolsIpcDeps {
+    internalDevtoolsWindow?: InternalDevtoolsWindow;
+    senderPolicy: SenderPolicy;
+}
+export declare function registerInternalDevtoolsIpc(ctx: InternalDevtoolsIpcDeps): Disposable;
+//# sourceMappingURL=internal-devtools.d.ts.map

package/dist/main/ipc/internal-devtools.js

@@ -0,0 +1,9 @@
+import { InternalDevtoolsChannel } from '../../shared/ipc-channels.js';
+import { IpcRegistry } from '../utils/ipc-registry.js';
+export function registerInternalDevtoolsIpc(ctx) {
+    return new IpcRegistry(ctx.senderPolicy)
+        .handle(InternalDevtoolsChannel.Open, () => {
+        ctx.internalDevtoolsWindow?.open();
+    });
+}
+//# sourceMappingURL=internal-devtools.js.map

package/dist/main/runtime/devtools-backend-before-quit.harness.d.ts

@@ -0,0 +1,61 @@
+import type { WorkbenchAppConfig } from '../../shared/types.js';
+import type { RuntimeBackend } from '@dimina-kit/electron-deck';
+declare const stubs: {
+    handlers: Map<string, (...args: unknown[]) => unknown>;
+    projectsJsonPath: string;
+    getProjectsJson(): string | null;
+    setProjectsJson(v: string | null): void;
+    projectsWithAppJson: Set<string>;
+    makeEmitter: () => {
+        listeners: Record<string, Set<(...args: unknown[]) => unknown>>;
+        on(event: string, fn: (...args: unknown[]) => unknown): /*elided*/ any;
+        once(event: string, fn: (...args: unknown[]) => unknown): /*elided*/ any;
+        off(event: string, fn: (...args: unknown[]) => unknown): /*elided*/ any;
+        removeListener(event: string, fn: (...args: unknown[]) => unknown): /*elided*/ any;
+        emit(event: string, ...args: unknown[]): void;
+    };
+    reset: () => void;
+};
+declare const devkitStubs: {
+    sessionClose: import("vitest").Mock<() => Promise<void>>;
+};
+declare const viewManagerStubs: {
+    createdManagers: Array<{
+        disposeAll: () => void;
+    }>;
+};
+export { stubs, devkitStubs, viewManagerStubs };
+/**
+ * Shared per-test setup both `devtools-backend-before-quit.test.ts` and
+ * `devtools-backend-shutdown-race.test.ts` need identically: reset modules
+ * (fresh `let`-scoped module-level state in `devtools-backend.ts` each
+ * test), reset the mock harness above, and dynamically re-import `electron`
+ * + `createDevtoolsBackend` — dynamic, not a static top-level import,
+ * because it must happen AFTER `vi.resetModules()` picks up a fresh module
+ * instance each test. Registers its own `beforeEach`; call once per
+ * describing test file. Returns a mutable state object (not individual
+ * values) because `beforeEach` reassigns its fields once per test, after
+ * this function itself has already returned.
+ */
+export interface BackendTestState {
+    createDevtoolsBackend: typeof import('./devtools-backend.js').createDevtoolsBackend;
+    electron: typeof import('electron');
+}
+export declare function registerBackendTestLifecycle(): BackendTestState;
+/**
+ * Shared setup for the two tests (one in `devtools-backend-before-quit.test.ts`,
+ * one in `devtools-backend-shutdown-race.test.ts`) that need to observe
+ * `assemble()` PAUSED mid-flight, inside a still-pending `config.onSetup`:
+ * builds the backend with a gated `onSetup`, runs `beforeReady`/`assemble`,
+ * and waits until the assembled `ViewManager` is actually reachable (proof
+ * `createDevtoolsRuntime` has progressed past instance construction) before
+ * handing control back — the caller then fires whatever quit-path event it's
+ * testing while `onSetup` is still gated, and is responsible for calling
+ * `releaseOnSetup()` + awaiting `assemblePromise` itself.
+ */
+export declare function startAssemblingWithGatedOnSetup(createDevtoolsBackend: BackendTestState['createDevtoolsBackend'], extraConfig?: Omit<WorkbenchAppConfig, 'onSetup'>): Promise<{
+    backend: RuntimeBackend;
+    assemblePromise: Promise<void>;
+    releaseOnSetup: () => void;
+}>;
+//# sourceMappingURL=devtools-backend-before-quit.harness.d.ts.map

package/dist/main/runtime/devtools-backend-before-quit.harness.js

@@ -0,0 +1,356 @@
+/**
+ * Shared vitest mock harness for `devtools-backend-before-quit.test.ts` and
+ * `devtools-backend-shutdown-race.test.ts` — both drive the REAL
+ * `createDevtoolsBackend`/`createDevtoolsRuntime` against this same
+ * electron/fs/`@dimina-kit/devkit`/view-manager mock set (lifted from
+ * `quit-flag-onclose.test.ts`), split out to keep each test file under the
+ * repo's 500-line file-length ratchet without duplicating ~350 lines of
+ * mock setup between them.
+ *
+ * `vi.mock(...)` calls here run once per importing test file's own isolated
+ * module graph (vitest scopes mocking per test file), so importing this
+ * module has the same effect as if each call were written directly in the
+ * importing file — both test files' `beforeEach` still dynamically
+ * `await import('./devtools-backend.js')` AFTER `vi.resetModules()`, well
+ * after this module's mock registrations have already run.
+ */
+import { beforeEach, expect, vi } from 'vitest';
+// ── Hoisted stub state (lifted from quit-flag-onclose.test.ts) ────────────
+// `export const x = vi.hoisted(...)` is rejected by vitest's hoisting
+// transform ("Cannot export hoisted variable") — declare then export below.
+const stubs = vi.hoisted(() => {
+    const handlers = new Map();
+    const projectsJsonPath = '/tmp/dimina-test-userdata/dimina-projects.json';
+    let projectsJsonContent = null;
+    const projectsWithAppJson = new Set();
+    function makeEmitter() {
+        const listeners = {};
+        return {
+            listeners,
+            on(event, fn) {
+                ;
+                (listeners[event] ??= new Set()).add(fn);
+                return this;
+            },
+            once(event, fn) {
+                const wrap = (...args) => {
+                    listeners[event]?.delete(wrap);
+                    return fn(...args);
+                };
+                (listeners[event] ??= new Set()).add(wrap);
+                return this;
+            },
+            off(event, fn) {
+                listeners[event]?.delete(fn);
+                return this;
+            },
+            removeListener(event, fn) {
+                listeners[event]?.delete(fn);
+                return this;
+            },
+            emit(event, ...args) {
+                for (const fn of [...(listeners[event] ?? [])])
+                    fn(...args);
+            },
+        };
+    }
+    function reset() {
+        handlers.clear();
+        projectsJsonContent = null;
+        projectsWithAppJson.clear();
+    }
+    return {
+        handlers,
+        projectsJsonPath,
+        getProjectsJson() {
+            return projectsJsonContent;
+        },
+        setProjectsJson(v) {
+            projectsJsonContent = v;
+        },
+        projectsWithAppJson,
+        makeEmitter,
+        reset,
+    };
+});
+// ── electron stub ────────────────────────────────────────────────────────
+// `app` is a live emitter so `registerAppLifecycle` can attach a
+// `before-quit` listener that the test fires directly.
+vi.mock('electron', () => {
+    const ipcEmitter = stubs.makeEmitter();
+    const ipcMain = {
+        ...ipcEmitter,
+        handle: vi.fn((channel, fn) => {
+            stubs.handlers.set(channel, fn);
+        }),
+        removeHandler: vi.fn((channel) => {
+            stubs.handlers.delete(channel);
+        }),
+        on: vi.fn((event, fn) => ipcEmitter.on(event, fn)),
+        removeListener: vi.fn((event, fn) => ipcEmitter.removeListener(event, fn)),
+    };
+    const appEmitter = stubs.makeEmitter();
+    const app = {
+        ...appEmitter,
+        isPackaged: true,
+        whenReady: vi.fn(() => Promise.resolve()),
+        getPath: vi.fn(() => '/tmp/dimina-test-userdata'),
+        quit: vi.fn(),
+        setName: vi.fn(),
+        commandLine: {
+            getSwitchValue: vi.fn(() => ''),
+            appendSwitch: vi.fn(),
+        },
+    };
+    // `WebContents` and `BrowserWindow` below both wrap a `stubs.makeEmitter()`
+    // and need the SAME on/once/off/removeListener/emit delegation (the
+    // emitter's own methods use `this` internally, so a plain property copy
+    // would call them with the wrong receiver — each needs `.bind(em)`). Shared
+    // base class instead of re-declaring the same 5 bound fields in both.
+    class EmittingStub {
+        em = stubs.makeEmitter();
+        on = this.em.on.bind(this.em);
+        once = this.em.once.bind(this.em);
+        off = this.em.off.bind(this.em);
+        removeListener = this.em.removeListener.bind(this.em);
+        emit = this.em.emit.bind(this.em);
+    }
+    class WebContents extends EmittingStub {
+        destroyed = false;
+        id = Math.floor(Math.random() * 1e6);
+        send = vi.fn();
+        isDestroyed = () => this.destroyed;
+        openDevTools = vi.fn();
+        closeDevTools = vi.fn();
+        setDevToolsWebContents = vi.fn();
+        setWindowOpenHandler = vi.fn();
+        loadFile = vi.fn(() => Promise.resolve());
+        loadURL = vi.fn(() => Promise.resolve());
+        executeJavaScript = vi.fn(() => Promise.resolve(undefined));
+        reload = vi.fn();
+        getType = () => 'window';
+        getURL = () => '';
+        debugger = {
+            attach: vi.fn(),
+            detach: vi.fn(),
+            isAttached: () => false,
+            on: vi.fn(),
+            removeListener: vi.fn(),
+            sendCommand: vi.fn(() => Promise.resolve({ entries: [] })),
+        };
+        close = vi.fn(() => {
+            this.destroyed = true;
+        });
+    }
+    class WebContentsView {
+        webContents = new WebContents();
+        setBounds = vi.fn();
+        setBackgroundColor = vi.fn();
+    }
+    class View {
+        children = [];
+        addChildView(child) {
+            this.children.push(child);
+        }
+        removeChildView(child) {
+            const i = this.children.indexOf(child);
+            if (i >= 0)
+                this.children.splice(i, 1);
+        }
+    }
+    class BrowserWindow extends EmittingStub {
+        destroyed = false;
+        webContents = new WebContents();
+        contentView = new WebContentsView();
+        isDestroyed = () => this.destroyed;
+        getContentSize = () => [1280, 980];
+        setIcon = vi.fn();
+        setTitle = vi.fn();
+        show = vi.fn();
+        showInactive = vi.fn();
+        focus = vi.fn();
+        close = vi.fn();
+        destroy = vi.fn(() => {
+            this.destroyed = true;
+        });
+        loadFile = vi.fn(() => Promise.resolve());
+        loadURL = vi.fn(() => Promise.resolve());
+        static getAllWindows = vi.fn(() => []);
+    }
+    const sessionStub = {
+        fromPartition: vi.fn(() => ({
+            webRequest: {
+                onBeforeSendHeaders: vi.fn(),
+                onHeadersReceived: vi.fn(),
+            },
+            registerPreloadScript: vi.fn(),
+            protocol: { handle: vi.fn(), unhandle: vi.fn() },
+        })),
+        defaultSession: {
+            protocol: { handle: vi.fn(), unhandle: vi.fn() },
+        },
+    };
+    const dialog = {
+        showOpenDialog: vi.fn(() => Promise.resolve({ canceled: true, filePaths: [] })),
+        showMessageBox: vi.fn(() => Promise.resolve({ response: 0 })),
+    };
+    const Menu = {
+        buildFromTemplate: vi.fn((tpl) => ({ template: tpl })),
+        setApplicationMenu: vi.fn(),
+    };
+    const shell = {
+        openExternal: vi.fn(() => Promise.resolve()),
+        openPath: vi.fn(() => Promise.resolve('')),
+    };
+    const nativeImage = {
+        createFromPath: vi.fn(() => ({ isEmpty: () => true })),
+    };
+    const nativeTheme = { ...stubs.makeEmitter(), themeSource: 'system' };
+    const globalShortcut = {
+        register: vi.fn(() => false),
+        unregister: vi.fn(),
+        unregisterAll: vi.fn(),
+    };
+    const webContentsStatic = {
+        fromId: vi.fn(() => null),
+        getAllWebContents: vi.fn(() => []),
+    };
+    const Tray = vi.fn();
+    return {
+        app,
+        ipcMain,
+        BrowserWindow,
+        WebContentsView,
+        BrowserView: WebContentsView,
+        View,
+        webContents: webContentsStatic,
+        session: sessionStub,
+        protocol: { registerSchemesAsPrivileged: vi.fn(), handle: vi.fn(), unhandle: vi.fn() },
+        dialog,
+        Menu,
+        shell,
+        nativeImage,
+        nativeTheme,
+        globalShortcut,
+        Tray,
+        default: {},
+    };
+});
+vi.mock('fs', async () => {
+    const real = await vi.importActual('fs');
+    function existsSync(p) {
+        const s = String(p);
+        if (s === stubs.projectsJsonPath)
+            return stubs.getProjectsJson() !== null;
+        if (s.endsWith('/app.json') || s.endsWith('\\app.json')) {
+            const dir = s.replace(/[\\/]app\.json$/, '');
+            return stubs.projectsWithAppJson.has(dir);
+        }
+        return true;
+    }
+    function readFileSync(p, opts) {
+        const s = String(p);
+        if (s === stubs.projectsJsonPath) {
+            const content = stubs.getProjectsJson();
+            if (content === null)
+                throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+            return content;
+        }
+        return real.readFileSync(p, opts);
+    }
+    function writeFileSync(p, data) {
+        const s = String(p);
+        if (s === stubs.projectsJsonPath) {
+            stubs.setProjectsJson(typeof data === 'string' ? data : Buffer.from(data).toString('utf8'));
+        }
+    }
+    const mocked = {
+        ...real,
+        existsSync,
+        readFileSync,
+        writeFileSync,
+        mkdirSync: vi.fn(),
+        statSync: vi.fn(() => ({ isDirectory: () => true, isFile: () => false, size: 0, mtimeMs: 0 })),
+        watch: vi.fn(),
+        realpathSync: vi.fn((p) => p),
+    };
+    return { ...mocked, default: mocked };
+});
+const devkitStubs = vi.hoisted(() => ({
+    sessionClose: vi.fn(() => Promise.resolve()),
+}));
+vi.mock('@dimina-kit/devkit', () => ({
+    openProject: vi.fn(() => Promise.resolve({
+        port: 12345,
+        appInfo: { appId: 'fakeApp' },
+        close: devkitStubs.sessionClose,
+    })),
+}));
+// ── view-manager spy shim ───────────────────────────────────────────────
+// `createDevtoolsBackend` keeps its assembled `instance` in a private
+// closure — the returned `RuntimeBackend` exposes no getter for
+// `instance.context.views`. Wrapping `createViewManager` here (real
+// implementation, just observed) gives the test a handle on the exact
+// `ViewManager` the backend's `assemble` wires up, equivalent to
+// `vi.spyOn(instance.context.views, 'disposeAll')` without needing the
+// backend to leak its internals.
+const viewManagerStubs = vi.hoisted(() => ({
+    createdManagers: [],
+}));
+vi.mock('../services/views/view-manager.js', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        createViewManager: (ctx) => {
+            const real = actual.createViewManager(ctx);
+            vi.spyOn(real, 'disposeAll');
+            viewManagerStubs.createdManagers.push(real);
+            return real;
+        },
+    };
+});
+export { stubs, devkitStubs, viewManagerStubs };
+export function registerBackendTestLifecycle() {
+    const state = {};
+    beforeEach(async () => {
+        vi.resetModules();
+        stubs.reset();
+        devkitStubs.sessionClose.mockClear();
+        viewManagerStubs.createdManagers.length = 0;
+        state.electron = await import('electron');
+        ({ createDevtoolsBackend: state.createDevtoolsBackend } = await import('./devtools-backend.js'));
+    });
+    return state;
+}
+/**
+ * Shared setup for the two tests (one in `devtools-backend-before-quit.test.ts`,
+ * one in `devtools-backend-shutdown-race.test.ts`) that need to observe
+ * `assemble()` PAUSED mid-flight, inside a still-pending `config.onSetup`:
+ * builds the backend with a gated `onSetup`, runs `beforeReady`/`assemble`,
+ * and waits until the assembled `ViewManager` is actually reachable (proof
+ * `createDevtoolsRuntime` has progressed past instance construction) before
+ * handing control back — the caller then fires whatever quit-path event it's
+ * testing while `onSetup` is still gated, and is responsible for calling
+ * `releaseOnSetup()` + awaiting `assemblePromise` itself.
+ */
+export async function startAssemblingWithGatedOnSetup(createDevtoolsBackend, extraConfig = {}) {
+    let releaseOnSetup = () => { };
+    const onSetupGate = new Promise((resolve) => {
+        releaseOnSetup = resolve;
+    });
+    const backend = createDevtoolsBackend({
+        ...extraConfig,
+        onSetup: async () => {
+            await onSetupGate;
+        },
+    });
+    backend.beforeReady?.({});
+    const assemblePromise = Promise.resolve(backend.assemble({}));
+    // Let `assemble` progress through `createDevtoolsRuntime` up to (and into)
+    // the pending `onSetup` gate — the instance must exist by then.
+    await vi.waitFor(() => {
+        expect(viewManagerStubs.createdManagers.length).toBeGreaterThan(0);
+    });
+    return { backend, assemblePromise, releaseOnSetup };
+}
+//# sourceMappingURL=devtools-backend-before-quit.harness.js.map