@dimina-kit/devtools 0.3.2-dev.20260525152421 → 0.3.2-dev.20260610082053

package/dist/main/ipc/simulator.js

@@ -1,12 +1,33 @@
-import { SimulatorChannel, SimulatorCustomApiChannel } from '../../shared/ipc-channels.js';
-import { SimulatorAttachSchema, SimulatorCustomApiInvokeSchema, SimulatorResizeSchema, SimulatorSetVisibleSchema, } from '../../shared/ipc-schemas.js';
+import { ServiceHostChannel, SimulatorChannel, SimulatorCustomApiChannel } from '../../shared/ipc-channels.js';
+import { SimulatorAttachNativeSchema, SimulatorCustomApiInvokeSchema, SimulatorResizeSchema, SimulatorSetDeviceInfoSchema, SimulatorSetNativeBoundsSchema, SimulatorSetVisibleSchema, } from '../../shared/ipc-schemas.js';
 import { validate } from '../utils/ipc-schema.js';
 import { IpcRegistry } from '../utils/ipc-registry.js';
+/**
+ * Map the renderer's logical device metrics onto the subset of a
+ * HostEnvSnapshot the service-host window's `getSystemInfoSync` consumes.
+ * `windowHeight` excludes the status bar (the page area); `windowWidth` has no
+ * horizontal chrome. Zoom is intentionally absent — it is a display scale, not
+ * a logical-size change.
+ */
+function deviceInfoToHostEnv(d) {
+    return {
+        brand: d.brand,
+        model: d.model,
+        system: d.system,
+        platform: d.platform,
+        pixelRatio: d.pixelRatio,
+        screenWidth: d.screenWidth,
+        screenHeight: d.screenHeight,
+        windowWidth: d.screenWidth,
+        windowHeight: Math.max(0, d.screenHeight - d.statusBarHeight),
+        statusBarHeight: d.statusBarHeight,
+    };
+}
 export function registerSimulatorIpc(ctx) {
     return new IpcRegistry(ctx.senderPolicy)
-        .handle(SimulatorChannel.Attach, (_, ...args) => {
-        const [simWcId, simWidth] = validate(SimulatorChannel.Attach, SimulatorAttachSchema, args);
-        ctx.views.attachSimulator(simWcId, simWidth);
+        .handle(SimulatorChannel.AttachNative, (_, ...args) => {
+        const [simulatorUrl, simWidth] = validate(SimulatorChannel.AttachNative, SimulatorAttachNativeSchema, args);
+        ctx.views.attachNativeSimulator(simulatorUrl, simWidth);
     })
         .handle(SimulatorChannel.Detach, () => {
         ctx.views.detachSimulator();
@@ -14,6 +35,29 @@ export function registerSimulatorIpc(ctx) {
         .handle(SimulatorChannel.Resize, (_, ...args) => {
         const [simWidth] = validate(SimulatorChannel.Resize, SimulatorResizeSchema, args);
         ctx.views.resize(simWidth);
+    })
+        .handle(SimulatorChannel.SetNativeBounds, (_, ...args) => {
+        const [p] = validate(SimulatorChannel.SetNativeBounds, SimulatorSetNativeBoundsSchema, args);
+        ctx.views.setNativeSimulatorViewBounds(p);
+    })
+        .handle(SimulatorChannel.SetDeviceInfo, (_, ...args) => {
+        const [device] = validate(SimulatorChannel.SetDeviceInfo, SimulatorSetDeviceInfoSchema, args);
+        // Cache the selection (rides the next NATIVE_HOST_ENABLED reply for a
+        // race-free DeviceShell init) and push DEVICE_CHANGE to the live simulator
+        // WCV so the DeviceShell resizes the bezel + re-renders status bar / notch.
+        ctx.bridge?.setDevice(device);
+        // Re-push the CSS env(safe-area-inset-*) override to attached render-host
+        // guests so notch-aware page layout updates without a reload.
+        ctx.views.reapplySafeArea(device);
+        // Live-update the running service-host window's host-env snapshot so
+        // `wx.getSystemInfoSync()` reflects the selected device without a relaunch.
+        // The service-host preload mutates `__diminaSpawnContext` in place;
+        // `getSystemInfoSync` reads it fresh on each call. No service window yet
+        // (pre-spawn) → no-op.
+        const serviceWc = ctx.bridge?.getServiceWc();
+        if (serviceWc && !serviceWc.isDestroyed()) {
+            serviceWc.send(ServiceHostChannel.HostEnvUpdate, deviceInfoToHostEnv(device));
+        }
     })
         .handle(SimulatorChannel.SetVisible, (_, ...args) => {
         const [visible, simWidth] = validate(SimulatorChannel.SetVisible, SimulatorSetVisibleSchema, args);

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

@@ -1,4 +1,4 @@
 import type { WorkbenchContext } from '../services/workbench-context.js';
-import type { Disposable } from '../utils/disposable.js';
+import type { Disposable } from '@dimina-kit/electron-deck/main';
 export declare function registerToolbarIpc(ctx: Pick<WorkbenchContext, 'toolbar' | 'senderPolicy'>): Disposable;
 //# sourceMappingURL=toolbar.d.ts.map

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

@@ -0,0 +1,19 @@
+import type { WorkbenchContext } from '../services/workbench-context.js';
+import type { Disposable } from '@dimina-kit/electron-deck/main';
+/**
+ * Renderer-driven overlay bounds.
+ *
+ * The main window's React layout is the source of truth for where the
+ * editor view and the simulator's Chromium DevTools overlay live on
+ * screen. A `ResizeObserver` in the renderer watches each placeholder
+ * `<div>` and publishes its client rect (in CSS pixels, relative to the
+ * window's content area) through these channels. The view manager caches
+ * the latest payload per kind and applies it to the WebContentsView.
+ *
+ * Width / height = 0 is the canonical "overlay hidden" signal — the React
+ * panel is collapsed or the tab is not selected. The view manager removes
+ * the child view from the contentView but keeps the WebContents alive so
+ * subsequent re-shows skip the OpenSumi DI bootstrap.
+ */
+export declare function registerViewsIpc(ctx: Pick<WorkbenchContext, 'views' | 'senderPolicy'>): Disposable;
+//# sourceMappingURL=views.d.ts.map

package/dist/main/ipc/views.js

@@ -0,0 +1,65 @@
+import { ipcMain } from 'electron';
+import { ViewChannel } from '../../shared/ipc-channels.js';
+import { ViewBoundsSchema, HostToolbarAdvertiseHeightSchema, } from '../../shared/ipc-schemas.js';
+import { validate } from '../utils/ipc-schema.js';
+import { IpcRegistry } from '../utils/ipc-registry.js';
+/**
+ * Renderer-driven overlay bounds.
+ *
+ * The main window's React layout is the source of truth for where the
+ * editor view and the simulator's Chromium DevTools overlay live on
+ * screen. A `ResizeObserver` in the renderer watches each placeholder
+ * `<div>` and publishes its client rect (in CSS pixels, relative to the
+ * window's content area) through these channels. The view manager caches
+ * the latest payload per kind and applies it to the WebContentsView.
+ *
+ * Width / height = 0 is the canonical "overlay hidden" signal — the React
+ * panel is collapsed or the tab is not selected. The view manager removes
+ * the child view from the contentView but keeps the WebContents alive so
+ * subsequent re-shows skip the OpenSumi DI bootstrap.
+ */
+export function registerViewsIpc(ctx) {
+    const registry = new IpcRegistry(ctx.senderPolicy)
+        .handle(ViewChannel.SimulatorDevtoolsBounds, (_event, ...args) => {
+        const [bounds] = validate(ViewChannel.SimulatorDevtoolsBounds, ViewBoundsSchema, args);
+        ctx.views.setSimulatorDevtoolsBounds(bounds);
+    })
+        // Host-controllable toolbar: forward anchor (the MAIN renderer measures the
+        // placeholder rect → toolbar WCV bounds). invoke, mirroring
+        // SimulatorDevtoolsBounds. Sender is the trusted main renderer.
+        .handle(ViewChannel.HostToolbarBounds, (_event, ...args) => {
+        const [bounds] = validate(ViewChannel.HostToolbarBounds, ViewBoundsSchema, args);
+        ctx.views.setHostToolbarBounds(bounds);
+    });
+    // Reverse size-advertiser: the toolbar WCV's OWN renderer sends this, and the
+    // host loads ARBITRARY content into that WCV. We DELIBERATELY do NOT add the
+    // toolbar wc to the global sender policy — that would trust it for ALL ~72
+    // IpcRegistry channels (project-fs / session / settings / panels
+    // executeJavaScript / storage …), a large blast radius if the host content is
+    // ever compromised. Instead this is a RAW `ipcMain.on` gated on the EXACT
+    // current host-toolbar wc id — the same precise-sender-id trust model the
+    // simulator custom-api bridge uses (view-manager `attachNativeCustomApiBridge`).
+    // The host content can reach ONLY this one channel, carrying only a
+    // non-negative integer height.
+    const onAdvertiseHeight = (event, ...args) => {
+        if (event.sender.id !== ctx.views.getHostToolbarWebContentsId())
+            return;
+        let extent;
+        try {
+            ;
+            [{ extent }] = validate(ViewChannel.HostToolbarAdvertiseHeight, HostToolbarAdvertiseHeightSchema, args);
+        }
+        catch {
+            return; // malformed payload from the host's own content — drop it
+        }
+        ctx.views.setHostToolbarHeight(extent);
+    };
+    ipcMain.on(ViewChannel.HostToolbarAdvertiseHeight, onAdvertiseHeight);
+    return {
+        dispose() {
+            void registry.dispose();
+            ipcMain.removeListener(ViewChannel.HostToolbarAdvertiseHeight, onAdvertiseHeight);
+        },
+    };
+}
+//# sourceMappingURL=views.js.map

package/dist/main/runtime/devtools-backend.d.ts

@@ -0,0 +1,17 @@
+import type { RuntimeBackend } from '@dimina-kit/electron-deck';
+import type { WorkbenchAppConfig } from '../../shared/types.js';
+/**
+ * Adapts the devtools runtime into a {@link RuntimeBackend} the framework
+ * (`@dimina-kit/electron-deck`) orchestrates. The framework owns the process
+ * lifecycle gate (whenReady) + wire/trust primitives; the backend supplies the
+ * full devtools assembly — reusing the exact same `runDevtoolsBootstrap` / `createDevtoolsRuntime`
+ * assembly bodies (extracted from the former createWorkbenchApp), so the app is
+ * byte-identical to the pre-extraction behaviour (no behavioural re-creation).
+ *
+ * v2 scope: the backend owns window creation (the framework skips its own when a
+ * backend is present), so `assemble` ignores the framework `runtime` and builds
+ * the real devtools main window itself. Trust/frame unification and surfacing
+ * the runtime facade are deferred (see framework-extraction-v2.md §7).
+ */
+export declare function createDevtoolsBackend(config?: WorkbenchAppConfig): RuntimeBackend;
+//# sourceMappingURL=devtools-backend.d.ts.map

package/dist/main/runtime/devtools-backend.js

@@ -0,0 +1,49 @@
+import { runDevtoolsBootstrap, createDevtoolsRuntime } from '../app/app.js';
+import { registerAppLifecycle } from '../app/lifecycle.js';
+/**
+ * Adapts the devtools runtime into a {@link RuntimeBackend} the framework
+ * (`@dimina-kit/electron-deck`) orchestrates. The framework owns the process
+ * lifecycle gate (whenReady) + wire/trust primitives; the backend supplies the
+ * full devtools assembly — reusing the exact same `runDevtoolsBootstrap` / `createDevtoolsRuntime`
+ * assembly bodies (extracted from the former createWorkbenchApp), so the app is
+ * byte-identical to the pre-extraction behaviour (no behavioural re-creation).
+ *
+ * v2 scope: the backend owns window creation (the framework skips its own when a
+ * backend is present), so `assemble` ignores the framework `runtime` and builds
+ * the real devtools main window itself. Trust/frame unification and surfacing
+ * the runtime facade are deferred (see framework-extraction-v2.md §7).
+ */
+export function createDevtoolsBackend(config = {}) {
+    // Hoisted so `onShutdown` can reach the assembled context (assigned by `assemble`).
+    let instance = null;
+    return {
+        // The backend builds the devtools main window itself (framework skips its own).
+        // Its only construction-time needs are the host preload + `sandbox:false`
+        // (main-window/create.ts) and wrapping contentView in a `View` container.
+        // NOTE: `ownsWindows` is NOT structurally required — the framework's
+        // `mainWindowWebPreferences()` + `onMainWindowCreated()` hooks can supply both,
+        // and the project close→back lifecycle maps onto the Window facade's
+        // `onClose`/`newSession` (probe-validated). Retained for now; migrating to
+        // `runtime.windows.main` is the documented next step. (The `persist:simulator`
+        // partition is a fixed session used by child WCVs, not main-window state.)
+        ownsWindows: true,
+        // Pre-ready: app name / CDP port / CSP / privileged scheme — must run before
+        // the framework awaits app.whenReady().
+        beforeReady: () => {
+            runDevtoolsBootstrap(config);
+        },
+        // Setup (post-whenReady): app lifecycle (window-all-closed → quit) + the
+        // full devtools assembly.
+        assemble: async () => {
+            registerAppLifecycle();
+            instance = await createDevtoolsRuntime(config);
+        },
+        // Dispose the devtools context during the framework's deterministic shutdown
+        // (app.on('will-quit') → shutdown() → runShutdownCleanup(), awaited once).
+        // Without this, the compile session (a child process, torn down by
+        // closeProject) and the IPC registry would leak on exit. The framework awaits
+        // this hook, so teardown is no longer a best-effort before-quit reach-around.
+        onShutdown: () => instance?.dispose(),
+    };
+}
+//# sourceMappingURL=devtools-backend.js.map

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

@@ -0,0 +1,39 @@
+/**
+ * MiniappRuntime — the stable, host-facing contract surface (foundation.md §3
+ * "MiniappRuntime 契约" layer, P4).
+ *
+ * `WorkbenchContext` is the rich internal main-process state: runtime kernel +
+ * host config + trust/infra plumbing, all mixed. Downstream hosts (qdmp, a
+ * re-skin of devtools that depends ONLY on devtools) don't consume that whole
+ * grab-bag — they drive the miniapp KERNEL: the view lifecycle (including the
+ * host-controllable toolbar at `views.hostToolbar`), the cross-wc bridge, the
+ * workspace, the custom-API registry, async storage, the appdata tap, the
+ * connection layer, and the main→renderer notifier.
+ *
+ * This module NAMES that kernel as an explicit, documented contract so the
+ * surface a host depends on is compiler-enforced and versionable, instead of
+ * "whatever fields of WorkbenchContext you happen to reach for". Config inputs
+ * (appName / panels / apiNamespaces / branding / project templates) are the
+ * host's INPUT, not part of the runtime it consumes; trust/infra
+ * (senderPolicy / trustedWindowSenderIds / registry / toolbar action-table)
+ * stay internal.
+ *
+ * Derived via `Pick<WorkbenchContext, …>` so the field TYPES never drift from
+ * the real implementation — `MiniappRuntime` is a view onto `WorkbenchContext`,
+ * and the conformance assertion below fails to compile the moment the context
+ * stops satisfying the contract.
+ *
+ * The host-controllable toolbar WebContentsView hangs off `views.hostToolbar`
+ * (a ViewManager concern), so it's reachable through the contract WITHOUT a 9th
+ * top-level member — `runtime.views.hostToolbar.loadURL(...)`.
+ */
+import type { WorkbenchContext } from '../services/workbench-context.js';
+/** The stable miniapp-kernel surface a downstream host (qdmp) consumes. */
+export type MiniappRuntime = Pick<WorkbenchContext, 'views' | 'bridge' | 'workspace' | 'simulatorApis' | 'storageApi' | 'appData' | 'connections' | 'notify'>;
+/**
+ * Project a full `WorkbenchContext` down to its `MiniappRuntime` view. Hosts
+ * call this to get a value typed to exactly the contract — no wider access to
+ * the context's internals leaks through.
+ */
+export declare function asMiniappRuntime(ctx: WorkbenchContext): MiniappRuntime;
+//# sourceMappingURL=miniapp-runtime.d.ts.map

package/dist/main/runtime/miniapp-runtime.js

@@ -0,0 +1,17 @@
+/**
+ * Project a full `WorkbenchContext` down to its `MiniappRuntime` view. Hosts
+ * call this to get a value typed to exactly the contract — no wider access to
+ * the context's internals leaks through.
+ */
+export function asMiniappRuntime(ctx) {
+    return ctx;
+}
+/**
+ * Compile-time conformance guard: if `WorkbenchContext` ever stops structurally
+ * satisfying `MiniappRuntime` (a kernel field renamed / its type narrowed),
+ * THIS line fails `tsc`, catching the contract break at build time. The runtime
+ * value is unused.
+ */
+const _conformance = (ctx) => ctx;
+void _conformance;
+//# sourceMappingURL=miniapp-runtime.js.map

package/dist/main/services/automation/exec.d.ts

@@ -1,10 +1,35 @@
+import type { WebContents } from 'electron';
 import type { WorkbenchContext } from '../workbench-context.js';
 import type { ElementRef } from './shared.js';
 export declare function getSimulator(ctx: WorkbenchContext): Electron.WebContents | null;
 export declare function evalInSim<T = unknown>(ctx: WorkbenchContext, expression: string): Promise<T>;
-/** Build JS that locates an element by selector+index inside the active page iframe. */
+/**
+ * Native-host: the active page's DOM lives directly in the visible render-host
+ * <webview> guest (no iframe), so element/page automation must run in that
+ * WebContents' main world. Returns null on the default dimina-fe arch, where the
+ * page lives inside an iframe of the simulator guest and automation goes through
+ * `evalInSim` + `inIframe` instead.
+ */
+export declare function getActivePageWc(ctx: WorkbenchContext): WebContents | null;
+/**
+ * Wrap guest code so `_doc` is the page document. Under native-host the render
+ * guest IS the page document — no iframe lookup (cf. `inIframe`, which digs into
+ * the simulator guest's last iframe). Mirrors `inIframe`'s `_doc` contract so the
+ * same handler `body` strings work in both arches unchanged.
+ */
+export declare function wrapGuest(code: string): string;
+/**
+ * Run page-level automation code against the right document for the current arch:
+ *   - native-host with a live active render guest → run in that guest's main
+ *     world via `wrapGuest` (the guest IS the page document).
+ *   - otherwise (default dimina-fe, or native-host with no active guest yet) →
+ *     fall back to `evalInSim(inIframe(code))` (the existing simulator-iframe path).
+ * The `code` is the same body either arch expects — it reads `_doc`.
+ */
+export declare function evalInActivePage<T = unknown>(ctx: WorkbenchContext, code: string): Promise<T>;
+/** Build JS that locates an element by selector+index inside the active page document. */
 export declare function buildElAccess(ref: ElementRef, varName?: string): string;
-/** Run `body` inside the active page iframe with `varName` bound to the element at `ref`. */
+/** Run `body` inside the active page document with `varName` bound to the element at `ref`. */
 export declare function evalInElement<T = unknown>(ctx: WorkbenchContext, ref: ElementRef, body: string, varName?: string): Promise<T>;
 /** Wrap code to run inside the active page iframe (last iframe in the stack). */
 export declare function inIframe(code: string): string;

package/dist/main/services/automation/exec.js

@@ -10,13 +10,47 @@ export async function evalInSim(ctx, expression) {
         throw new Error('Simulator not connected');
     return sim.executeJavaScript(expression);
 }
-/** Build JS that locates an element by selector+index inside the active page iframe. */
+/**
+ * Native-host: the active page's DOM lives directly in the visible render-host
+ * <webview> guest (no iframe), so element/page automation must run in that
+ * WebContents' main world. Returns null on the default dimina-fe arch, where the
+ * page lives inside an iframe of the simulator guest and automation goes through
+ * `evalInSim` + `inIframe` instead.
+ */
+export function getActivePageWc(ctx) {
+    return ctx.bridge?.isNativeHost() ? ctx.bridge.getActiveRenderWc() : null;
+}
+/**
+ * Wrap guest code so `_doc` is the page document. Under native-host the render
+ * guest IS the page document — no iframe lookup (cf. `inIframe`, which digs into
+ * the simulator guest's last iframe). Mirrors `inIframe`'s `_doc` contract so the
+ * same handler `body` strings work in both arches unchanged.
+ */
+export function wrapGuest(code) {
+    return `(() => { const _doc = document; return (function(){ ${code} })() })()`;
+}
+/**
+ * Run page-level automation code against the right document for the current arch:
+ *   - native-host with a live active render guest → run in that guest's main
+ *     world via `wrapGuest` (the guest IS the page document).
+ *   - otherwise (default dimina-fe, or native-host with no active guest yet) →
+ *     fall back to `evalInSim(inIframe(code))` (the existing simulator-iframe path).
+ * The `code` is the same body either arch expects — it reads `_doc`.
+ */
+export async function evalInActivePage(ctx, code) {
+    const renderWc = getActivePageWc(ctx);
+    if (renderWc) {
+        return renderWc.executeJavaScript(wrapGuest(code));
+    }
+    return evalInSim(ctx, inIframe(code));
+}
+/** Build JS that locates an element by selector+index inside the active page document. */
 export function buildElAccess(ref, varName = 'el') {
     return `const ${varName} = _doc.querySelectorAll(${JSON.stringify(ref.selector)})[${ref.index}]`;
 }
-/** Run `body` inside the active page iframe with `varName` bound to the element at `ref`. */
+/** Run `body` inside the active page document with `varName` bound to the element at `ref`. */
 export function evalInElement(ctx, ref, body, varName = 'el') {
-    return evalInSim(ctx, inIframe(`${buildElAccess(ref, varName)}\n${body}`));
+    return evalInActivePage(ctx, `${buildElAccess(ref, varName)}\n${body}`);
 }
 /** Wrap code to run inside the active page iframe (last iframe in the stack). */
 export function inIframe(code) {

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

@@ -1,12 +1,41 @@
-import { evalInSim, getSimulator, inIframe } from '../exec.js';
-import { parseLocationRoute } from '../../../../shared/simulator-route.js';
+import { evalInSim, getActivePageWc, getSimulator } from '../exec.js';
+import { decodePageSpec, parseLocationRoute } from '../../../../shared/simulator-route.js';
+import { waitForActivePage } from '../wait-active-page.js';
 export const appHandlers = {};
+/** Nav methods that take a `{ url }` arg (navigateBack is handled separately). */
+const NAV_METHODS = new Set(['navigateTo', 'redirectTo', 'reLaunch', 'switchTab']);
 // -- App domain --
 async function readRoute(ctx) {
     const { search } = await evalInSim(ctx, `({ search: location.search })`);
     return parseLocationRoute(search);
 }
+/**
+ * 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.
+ */
+async function readNativeActivePage(ctx) {
+    const renderWc = getActivePageWc(ctx);
+    if (!renderWc)
+        return null;
+    const search = await renderWc
+        .executeJavaScript('location.search')
+        .catch(() => '');
+    const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
+    const pagePath = params.get('pagePath') || '';
+    if (!pagePath)
+        return null;
+    // The guest URL carries the full page spec on `pagePath` (may include `?k=v`).
+    const spec = decodePageSpec(pagePath);
+    return { pagePath: spec.pagePath, query: spec.query };
+}
 appHandlers['App.getCurrentPage'] = async (ctx) => {
+    if (ctx.bridge?.isNativeHost()) {
+        const page = await readNativeActivePage(ctx);
+        return { pageId: 1, path: page?.pagePath ?? '', query: page?.query ?? {} };
+    }
     const route = await readRoute(ctx);
     const iframeCount = await evalInSim(ctx, `document.querySelectorAll('iframe').length`);
     return {
@@ -16,8 +45,28 @@ appHandlers['App.getCurrentPage'] = async (ctx) => {
     };
 };
 appHandlers['App.getPageStack'] = async (ctx) => {
-    const route = await readRoute(ctx);
     const pageStack = [];
+    if (ctx.bridge?.isNativeHost()) {
+        // DeviceShell reports its full ordered stack (bottom→top) via PAGE_STACK;
+        // the bridge stores it. Report that. Before the first signal (or in a mock
+        // without the accessor) fall back to the single visible page.
+        const stack = ctx.bridge.getPageStack?.();
+        if (stack && stack.length > 0) {
+            stack.forEach((entry, i) => {
+                pageStack.push({
+                    pageId: i + 1,
+                    path: entry.pagePath,
+                    query: Object.fromEntries(Object.entries(entry.query ?? {}).map(([k, v]) => [k, String(v)])),
+                });
+            });
+            return { pageStack };
+        }
+        const page = await readNativeActivePage(ctx);
+        if (page)
+            pageStack.push({ pageId: 1, path: page.pagePath, query: page.query });
+        return { pageStack };
+    }
+    const route = await readRoute(ctx);
     if (!route)
         return { pageStack };
     // Mirrors upstream HashRouter.parseSearch: `[entry]` or `[entry, current]`.
@@ -30,24 +79,88 @@ appHandlers['App.getPageStack'] = async (ctx) => {
 appHandlers['App.callWxMethod'] = async (ctx, params) => {
     const method = params.method;
     const args = params.args || [];
+    // NATIVE-HOST: the authoritative `wx.*` runs in the hidden service-host
+    // window (the simulator / render-guest context has no `wx`). Run EVERY method
+    // there — nav so the page stack goes through the real runtime path, and
+    // non-nav (setNavigationBarTitle / getSystemInfoSync / tabBar APIs / …) so
+    // they don't fall through to the default-arch eval-in-simulator path below,
+    // which throws "wx is not defined" under native-host.
+    if (ctx.bridge?.isNativeHost()) {
+        const serviceWc = ctx.bridge.getServiceWc();
+        if (!serviceWc)
+            throw new Error('Service host not connected');
+        if (NAV_METHODS.has(method) || method === 'navigateBack') {
+            const arg = method === 'navigateBack'
+                ? (args[0] ?? { delta: 1 })
+                : (args[0] ?? {});
+            // Capture the active page BEFORE navigating so we can wait for it to
+            // actually change, instead of blindly sleeping a fixed duration.
+            const since = ctx.bridge.getActiveBridgeId();
+            await serviceWc.executeJavaScript(`wx.${method}(${JSON.stringify(arg)})`);
+            // Wait for the bridge's `activePage` signal (the new page mounted), with a
+            // timeout floor = the old blind-wait duration. Resolves as soon as the new
+            // page is active — far faster than the fixed sleep for the common case —
+            // and still bounded for edges (e.g. switchTab back to an already-mounted
+            // tab keeps the same bridgeId, so it falls through to the floor, same as
+            // the old behaviour). See wait-active-page.ts.
+            const timeoutMs = method === 'navigateBack' ? 1500 : 2000;
+            await waitForActivePage(ctx.bridge, {
+                since,
+                timeoutMs,
+                onTimeout: () => console.warn(`[automation] ${method}: activePage signal not seen within ${timeoutMs}ms — proceeding on timeout floor`),
+            });
+            return { result: undefined };
+        }
+        // Non-nav: invoke on the service-host wx and return its (sync) value. Async
+        // methods that report via a success callback return undefined here, same as
+        // the default-arch generic path below.
+        const argsStr = args.map((a) => JSON.stringify(a)).join(', ');
+        const result = await serviceWc.executeJavaScript(`
+      new Promise((resolve, reject) => {
+        try {
+          if (typeof wx === 'undefined' || typeof wx[${JSON.stringify(method)}] !== 'function') {
+            reject(new Error('wx.' + ${JSON.stringify(method)} + ' is not a function in service host'))
+            return
+          }
+          resolve(wx.${method}(${argsStr}))
+        } catch (e) { reject(e && e.message ? e.message : String(e)) }
+      })
+    `);
+        return { result };
+    }
     // For navigation methods, handle specially via DOM click / wx.* on the iframe
     if (['navigateTo', 'redirectTo', 'reLaunch', 'switchTab'].includes(method)) {
         const opts = args[0];
         const url = opts?.url;
         if (url) {
             const cleanUrl = url.startsWith('/') ? url : `/${url}`;
-            // Try clicking a matching DOM element first
-            const clicked = await evalInSim(ctx, inIframe(`
+            // Try clicking a matching DOM element first. We can't use `inIframe`
+            // here — tabBar mini-apps keep prior tabs' iframes around (display:none)
+            // and `iframes[length-1]` ends up being the hidden, freshly-cached tab
+            // rather than the visible one. Pick the visible iframe explicitly.
+            const clicked = await evalInSim(ctx, `(() => {
+        const iframes = Array.from(document.querySelectorAll('iframe'))
+        const visible = iframes.filter((f) => {
+          const cs = window.getComputedStyle(f)
+          if (cs.display === 'none' || cs.visibility === 'hidden') return false
+          const rect = f.getBoundingClientRect()
+          return rect.width > 0 && rect.height > 0
+        })
+        const target = visible[visible.length - 1] || iframes[iframes.length - 1]
+        if (!target || !target.contentDocument) return false
         const path = ${JSON.stringify(cleanUrl)}
-        const el = Array.from(_doc.querySelectorAll('[data-path]'))
-          .find(e => e.getAttribute('data-path') === path)
+        const el = Array.from(target.contentDocument.querySelectorAll('[data-path]'))
+          .find((e) => e.getAttribute('data-path') === path)
         if (el) { el.click(); return true }
         return false
-      `)).catch(() => false);
+      })()`).catch(() => false);
             if (!clicked) {
-                // Fallback: drive navigation via wx.* on the rendered page iframe.
-                // Upstream's query router doesn't react to URL mutation; the active
-                // page's iframe exposes wx.* with the live dimina runtime bindings.
+                // Fallback cascade for navigation methods:
+                //   1. iframe wx[method] — page-iframe surface (older arch, where
+                //      jdimina installed `window.wx` on each page frame).
+                //   2. top-window wx[method] — set up by simulator/main.tsx, binds
+                //      MiniApp.switchTab / navigateTo / etc. Required for switchTab
+                //      since page-iframe wx (jdimina) doesn't expose it.
                 const apiName = JSON.stringify(method);
                 const urlJson = JSON.stringify(cleanUrl);
                 await evalInSim(ctx, `(() => {
@@ -60,6 +173,9 @@ appHandlers['App.callWxMethod'] = async (ctx, params) => {
                 }
               } catch (_) {}
             }
+            if (typeof wx !== 'undefined' && wx && typeof wx[${apiName}] === 'function') {
+              wx[${apiName}]({ url: ${urlJson} })
+            }
           })()`);
             }
             // Wait for navigation