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

package/dist/main/runtime/devtools-runtime-mock.harness.js

@@ -0,0 +1,313 @@
+/**
+ * Shared electron/fs/`@dimina-kit/devkit` mock core for
+ * `window-close-reveal.harness.ts` (app/) and
+ * `devtools-backend-before-quit.harness.ts` (runtime/) — both those harnesses
+ * drive a REAL runtime (`createDevtoolsRuntime` or `createDevtoolsBackend`)
+ * against the same mock set (lifted from `quit-flag-onclose.test.ts`) and
+ * previously duplicated it in full; this module holds the part that's
+ * actually identical between them.
+ *
+ * `BrowserWindow` here tracks visible/minimized state and implements
+ * `hide`/`isVisible`/`minimize`/`isMinimized`/`restore` on top of `show`/
+ * `showInactive` — the window-close-reveal guards need all of that, while the
+ * before-quit/shutdown-race tests only ever `destroy()` a window and never
+ * observe the extra state, so carrying it there is a no-op.
+ *
+ * `vi.mock(...)` calls here run once per importing test file's own isolated
+ * module graph (vitest scopes mocking per test file). A harness that imports
+ * this module chains into that same module graph, so importing THIS module
+ * (directly, or transitively through one of the two harnesses above) has the
+ * same effect as if each `vi.mock` call were written directly in the test
+ * file itself.
+ */
+import { vi } from 'vitest';
+// ── Hoisted stub state ──────────────────────────────────────────────────
+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 ────────────────────────────────────────────────────────
+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;
+        // The list window and every workbench window start shown/restored — the
+        // reveal/hide guards this state exists for only ever move a window AWAY
+        // from it, never establish it.
+        visible = true;
+        minimized = false;
+        webContents = new WebContents();
+        contentView = new WebContentsView();
+        isDestroyed = () => this.destroyed;
+        isVisible = () => this.visible && !this.destroyed;
+        isMinimized = () => this.minimized;
+        getContentSize = () => [1280, 980];
+        setIcon = vi.fn();
+        setTitle = vi.fn();
+        show = vi.fn(() => {
+            this.visible = true;
+        });
+        showInactive = vi.fn(() => {
+            this.visible = true;
+        });
+        hide = vi.fn(() => {
+            this.visible = false;
+        });
+        minimize = vi.fn(() => {
+            this.minimized = true;
+        });
+        restore = vi.fn(() => {
+            this.minimized = false;
+            this.visible = true;
+        });
+        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,
+    })),
+}));
+export { stubs, devkitStubs };
+//# sourceMappingURL=devtools-runtime-mock.harness.js.map

package/dist/main/services/app-services.d.ts

@@ -0,0 +1,62 @@
+import type { BrowserWindow } from 'electron';
+import { type Disposable } from '@dimina-kit/electron-deck/main';
+import type { ProjectsProvider, ProjectTemplate } from './projects/types.js';
+import { type SimulatorApiRegistry } from './simulator/custom-apis.js';
+/**
+ * The services that belong to the whole application rather than to one window.
+ *
+ * They are all registered or configured ONCE by the host (through
+ * `WorkbenchAppConfig` and the `WorkbenchAppInstance` registration methods),
+ * so every window context reads the same instance. Anything whose owner is a
+ * single window — views, connections, the CDP broker, the workspace — stays on
+ * `WorkbenchContext` instead.
+ */
+export interface AppServices {
+    /** Backing store for the project list. One list, shown by every window. */
+    projectsProvider: ProjectsProvider;
+    /** Built-in templates merged with the host's, per `builtinTemplates`. */
+    projectTemplates: ProjectTemplate[];
+    /**
+     * Reference-counted `webContents.id` → live registration count for
+     * host-owned BrowserWindows registered as trusted senders. A host window is
+     * registered against the app, not against whichever window happened to be
+     * open at the time, so the map is shared and every context's sender policy
+     * consults the same entries.
+     */
+    trustedWindowSenderIds: Map<number, number>;
+    /**
+     * Simulator custom APIs registered by the host. The host registers each
+     * handler once (in `onSetup`), so the registry is app-wide: a window opened
+     * later must answer the same `wx.*` calls as the one that was open during
+     * registration.
+     */
+    simulatorApis: SimulatorApiRegistry;
+}
+export interface CreateAppServicesOptions {
+    projectsProvider?: ProjectsProvider;
+    projectTemplates?: ProjectTemplate[];
+    builtinTemplates?: 'all' | 'none' | readonly string[];
+}
+export declare function createAppServices(opts?: CreateAppServicesOptions): AppServices;
+/**
+ * Adds `win.webContents` to the trusted-sender set and returns a Disposable
+ * that removes it again.
+ *
+ * Trust is reference-counted: registering the SAME window N times keeps it
+ * trusted until every one of the N returned Disposables has been disposed.
+ * Each register bumps the count, each dispose decrements it, and the window is
+ * un-trusted only when the count reaches zero.
+ *
+ * The window's `closed` event short-circuits the ref-count: it deletes the
+ * map entry outright (the window is dead, so it must be un-trusted
+ * immediately regardless of how many Disposables are still outstanding).
+ * After `closed`, disposing any leftover Disposable is a safe no-op — the
+ * map entry is already gone, so the decrement finds `undefined` and bails
+ * without driving the count negative or resurrecting trust.
+ *
+ * Each returned Disposable is itself idempotent (`removed` flag), and its
+ * `closed` listener removes itself once fired so a long-lived app doesn't
+ * accumulate dead listeners on closed windows.
+ */
+export declare function registerTrustedWindow(services: Pick<AppServices, 'trustedWindowSenderIds'>, win: BrowserWindow): Disposable;
+//# sourceMappingURL=app-services.d.ts.map

package/dist/main/services/app-services.js

@@ -0,0 +1,64 @@
+import { toDisposable } from '@dimina-kit/electron-deck/main';
+import { createLocalProjectsProvider } from './projects/local-provider.js';
+import { resolveTemplates } from './projects/templates.js';
+import { BUILTIN_TEMPLATES } from './projects/builtin-templates.js';
+import { createSimulatorApiRegistry, } from './simulator/custom-apis.js';
+export function createAppServices(opts = {}) {
+    return {
+        projectsProvider: opts.projectsProvider ?? createLocalProjectsProvider(),
+        projectTemplates: resolveTemplates(BUILTIN_TEMPLATES, opts.projectTemplates ?? [], opts.builtinTemplates ?? 'all'),
+        trustedWindowSenderIds: new Map(),
+        simulatorApis: createSimulatorApiRegistry(),
+    };
+}
+/**
+ * Adds `win.webContents` to the trusted-sender set and returns a Disposable
+ * that removes it again.
+ *
+ * Trust is reference-counted: registering the SAME window N times keeps it
+ * trusted until every one of the N returned Disposables has been disposed.
+ * Each register bumps the count, each dispose decrements it, and the window is
+ * un-trusted only when the count reaches zero.
+ *
+ * The window's `closed` event short-circuits the ref-count: it deletes the
+ * map entry outright (the window is dead, so it must be un-trusted
+ * immediately regardless of how many Disposables are still outstanding).
+ * After `closed`, disposing any leftover Disposable is a safe no-op — the
+ * map entry is already gone, so the decrement finds `undefined` and bails
+ * without driving the count negative or resurrecting trust.
+ *
+ * Each returned Disposable is itself idempotent (`removed` flag), and its
+ * `closed` listener removes itself once fired so a long-lived app doesn't
+ * accumulate dead listeners on closed windows.
+ */
+export function registerTrustedWindow(services, win) {
+    const senderId = win.webContents.id;
+    const counts = services.trustedWindowSenderIds;
+    counts.set(senderId, (counts.get(senderId) ?? 0) + 1);
+    let removed = false;
+    const onClosed = () => {
+        // The window is gone: zero the ref-count for this sender id outright,
+        // regardless of any other outstanding registrations for the same window.
+        counts.delete(senderId);
+        win.removeListener('closed', onClosed);
+    };
+    function remove() {
+        if (removed)
+            return;
+        removed = true;
+        win.removeListener('closed', onClosed);
+        const count = counts.get(senderId);
+        // `undefined` → the entry was already cleared (e.g. by `closed` or by a
+        // prior sibling's decrement that hit zero). Nothing to do — never go
+        // negative, never resurrect trust.
+        if (count === undefined)
+            return;
+        if (count <= 1)
+            counts.delete(senderId);
+        else
+            counts.set(senderId, count - 1);
+    }
+    win.once('closed', onClosed);
+    return toDisposable(remove);
+}
+//# sourceMappingURL=app-services.js.map

package/dist/main/services/automation/connection-target.d.ts

@@ -0,0 +1,36 @@
+import type { WindowService } from '../window-service.js';
+import type { WorkspaceService } from '../workspace/workspace-service.js';
+/** The slice of a window context that decides where a connection's commands go. */
+export interface TargetContext {
+    windows: Pick<WindowService, 'mainWindow'>;
+    workspace: Pick<WorkspaceService, 'hasActiveSession'>;
+}
+/**
+ * The project window one automation connection acts on.
+ *
+ * The active context follows window focus, so resolving it afresh per message
+ * would let a click on another project's window redirect a script that is
+ * already driving one — the script does nothing wrong and its commands land
+ * somewhere else. A connection therefore PINS the first context it reaches
+ * that has a session and keeps it for the rest of its life. Which window a
+ * connection drives is decided by what it reached first, never by what the
+ * user is looking at.
+ *
+ * Nothing is pinned before a project window exists: a client may connect at
+ * boot and open a project afterwards, so until a context with a session shows
+ * up every use resolves the active one (the project list, which drives
+ * nothing). Pinning the list window would tie the connection to a window that
+ * can never run a command.
+ */
+export interface ConnectionTarget<T extends TargetContext> {
+    /**
+     * The context to run a command against. Throws once the pinned window is
+     * gone, so a connection whose project was closed fails loudly instead of
+     * sliding onto whichever project happens to be open now.
+     */
+    resolve(): T;
+    /** The same target, but null instead of a throw once its window is gone. */
+    peek(): T | null;
+}
+export declare function createConnectionTarget<T extends TargetContext>(getCtx: () => T): ConnectionTarget<T>;
+//# sourceMappingURL=connection-target.d.ts.map

package/dist/main/services/automation/connection-target.js

@@ -0,0 +1,29 @@
+export function createConnectionTarget(getCtx) {
+    let pinned = null;
+    // The window, not the session, is what a connection is pinned to: closing
+    // the project inside a window (`Tool.close`) leaves that window able to open
+    // another, while destroying the window ends the connection's target for good.
+    const isGone = (ctx) => {
+        const win = ctx.windows.mainWindow;
+        return !win || win.isDestroyed();
+    };
+    const current = () => {
+        if (pinned)
+            return isGone(pinned) ? null : pinned;
+        const ctx = getCtx();
+        if (ctx.workspace.hasActiveSession())
+            pinned = ctx;
+        return ctx;
+    };
+    return {
+        peek: current,
+        resolve() {
+            const ctx = current();
+            if (!ctx) {
+                throw new Error('The project window this connection was driving has been closed. Reconnect to drive another project.');
+            }
+            return ctx;
+        },
+    };
+}
+//# sourceMappingURL=connection-target.js.map

package/dist/main/services/automation/console-bridge.d.ts

@@ -0,0 +1,28 @@
+import type { WebContents } from 'electron';
+import type { ConnectionRegistry } from '@dimina-kit/electron-deck/main';
+import type { ConsoleForwarder } from '../console-forward/index.js';
+import type { RpcEvent } from './shared.js';
+/** The slice of a window context the two console taps read. */
+export interface ConsoleTargetContext {
+    consoleForwarder?: ConsoleForwarder;
+    connections: ConnectionRegistry;
+}
+/**
+ * The `App.logAdded` stream of ONE automation connection, taken from the same
+ * window that connection's commands reach.
+ *
+ * Two taps, because the two architectures deliver guest console differently:
+ *   - native-host: the render/service preloads post to main, bridge-router
+ *     routes into the window's always-on ConsoleForwarder, and we subscribe.
+ *   - default dimina-fe: the page/service console flows through the simulator
+ *     guest's `ipc-message-host` channel, so we listen on that webContents.
+ * Both are re-pointed by `sync()`, which is what keeps the log stream and the
+ * command stream on the same window as the target and its simulator change.
+ */
+export interface ConsoleBridge {
+    /** Re-point both taps at the connection's current target. */
+    sync(): void;
+    dispose(): void;
+}
+export declare function createConsoleBridge<T extends ConsoleTargetContext>(target: () => T | null, simulatorOf: (ctx: T) => WebContents | null, emit: (event: RpcEvent) => void): ConsoleBridge;
+//# sourceMappingURL=console-bridge.d.ts.map

package/dist/main/services/automation/console-bridge.js

@@ -0,0 +1,91 @@
+import { SimulatorChannel } from '../../../shared/ipc-channels.js';
+/**
+ * How often an idle connection re-checks its target for a console to attach
+ * to. A connection that never sends a message (a script that only listens for
+ * logs) has no other moment to notice its window's simulator appearing or
+ * being replaced by a rebuild.
+ */
+const SYNC_INTERVAL_MS = 1000;
+export function createConsoleBridge(target, simulatorOf, emit) {
+    let subscribedForwarder = null;
+    let forwarderSub;
+    let attachedSim = null;
+    let simHandler = null;
+    // The destroyed-teardown is owned by the sim's connection rather than a
+    // bespoke `sim.once('destroyed')`, so it cannot accumulate across re-attaches.
+    let simDestroyedDisposer = null;
+    function logAdded(entry) {
+        const e = entry ?? {};
+        emit({ method: 'App.logAdded', params: { type: e.level || 'log', args: e.args || [] } });
+    }
+    // Keyed on the forwarder itself, not the context: a window is wired with its
+    // forwarder after the context exists, so a context-identity check would miss
+    // the forwarder arriving on a context we already looked at.
+    function syncForwarder(ctx) {
+        const forwarder = ctx?.consoleForwarder ?? null;
+        if (forwarder === subscribedForwarder)
+            return;
+        forwarderSub?.dispose();
+        subscribedForwarder = forwarder;
+        forwarderSub = forwarder?.subscribe((entry) => logAdded(entry));
+    }
+    function detachSim() {
+        if (attachedSim && simHandler) {
+            try {
+                if (!attachedSim.isDestroyed()) {
+                    ;
+                    attachedSim.removeListener('ipc-message-host', simHandler);
+                }
+            }
+            catch { /* noop */ }
+        }
+        try {
+            simDestroyedDisposer?.dispose();
+        }
+        catch { /* noop */ }
+        attachedSim = null;
+        simHandler = null;
+        simDestroyedDisposer = null;
+    }
+    function syncSim(ctx) {
+        const sim = ctx ? simulatorOf(ctx) : null;
+        const next = sim && !sim.isDestroyed() ? sim : null;
+        if (next === attachedSim)
+            return;
+        detachSim();
+        if (!next || !ctx)
+            return;
+        const onIpcMessageHost = (_event, channel, data) => {
+            if (channel !== SimulatorChannel.Console)
+                return;
+            logAdded(data);
+        };
+        attachedSim = next;
+        simHandler = onIpcMessageHost;
+        next.on('ipc-message-host', onIpcMessageHost);
+        simDestroyedDisposer = ctx.connections.acquire(next).own(() => {
+            // Dead webContents: drop the refs (removeListener on it would throw) and
+            // let the next sync attach to the replacement.
+            attachedSim = null;
+            simHandler = null;
+            simDestroyedDisposer = null;
+        });
+    }
+    function sync() {
+        const ctx = target();
+        syncForwarder(ctx);
+        syncSim(ctx);
+    }
+    const timer = setInterval(sync, SYNC_INTERVAL_MS);
+    return {
+        sync,
+        dispose() {
+            clearInterval(timer);
+            detachSim();
+            forwarderSub?.dispose();
+            forwarderSub = undefined;
+            subscribedForwarder = null;
+        },
+    };
+}
+//# sourceMappingURL=console-bridge.js.map

package/dist/main/services/automation/handlers/app.js

@@ -11,10 +11,10 @@ async function readRoute(ctx) {
 }
 /**
  * Native-host: derive the visible page's `{ pagePath, query }` from the active
- * render guest. The page-stack depth isn't surfaced by the bridge handle, so the
- * native page stack is reported as the single active page (see App.getPageStack).
- * Reads the guest's own `location.search` — the render-host preload encodes
- * `pagePath` (+ per-page query) there.
+ * render guest. This is the source for `App.getCurrentPage` and the fallback for
+ * `App.getPageStack` before DeviceShell reports its full ordered stack through
+ * the bridge. The render-host preload encodes `pagePath` (+ per-page query) in
+ * the guest's own `location.search`.
  */
 async function readNativeActivePage(ctx) {
     const renderWc = getActivePageWc(ctx);