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

package/dist/main/services/service-host-pool/pool.js

@@ -0,0 +1,364 @@
+import { BrowserWindow } from 'electron';
+/** Blank placeholder URL loaded while warming / after reset. */
+const BLANK_URL = 'about:blank';
+/** Hard ceiling on pool size regardless of requested size (doc §3.3). */
+const HARD_MAX_POOL_SIZE = 4;
+/** Storage buckets cleared on every release (doc §3.4 "必须" rows). */
+const RESET_STORAGES = [
+    'cookies',
+    'localstorage',
+    'indexdb',
+    'serviceworkers',
+    'cachestorage',
+];
+export class ServiceHostPool {
+    entries = new Map();
+    currentSpec = null;
+    targetSize = 0;
+    maxPoolSize = 3;
+    nextId = 0;
+    disposed = false;
+    /**
+     * Warm `defaultPoolSize` entries with `defaultSpec`. Normally resolves once the
+     * pool has reached `defaultPoolSize` ready entries — even if a warming window
+     * crashes mid-init and is refilled. NOTE: `warmUpToTarget` caps its refill loop
+     * with a bounded guard, so under SUSTAINED warm crashes `init` resolves
+     * best-effort (possibly under-filled) rather than spinning forever — treat
+     * `getStats().ready` as advisory after init, not a hard invariant.
+     */
+    async init(opts) {
+        if (this.disposed)
+            return;
+        this.currentSpec = opts.defaultSpec;
+        this.maxPoolSize = Math.min(opts.maxPoolSize ?? 3, HARD_MAX_POOL_SIZE);
+        this.targetSize = Math.min(Math.max(opts.defaultPoolSize, 0), this.maxPoolSize);
+        await this.warmUpToTarget();
+    }
+    /**
+     * Hand a ready window matching `spec` to the caller. If none is ready, fall
+     * back to synchronously constructing a fresh window — never blocking on warm
+     * (doc §3.1 "绝不阻塞 acquire"). Fallback windows carry `entryId === null` and
+     * are destroyed (not pooled) on release.
+     *
+     * A spec change (different `preloadPath`) tears down all *pooled* entries and
+     * re-targets the pool to the new spec; in-use entries are left to their owners
+     * and disposed when returned (see `release`).
+     */
+    async acquire(spec) {
+        if (this.currentSpec && this.currentSpec.preloadPath !== spec.preloadPath) {
+            this.onSpecChange(spec);
+        }
+        else if (!this.currentSpec) {
+            this.currentSpec = spec;
+        }
+        for (const entry of this.entries.values()) {
+            if (entry.state === 'ready' && this.matches(entry.spec, spec)) {
+                // A ready entry whose window died (closed/crashed) while idle must never
+                // be handed out — navigating a destroyed WebContents silently no-ops the
+                // spawn. Drop it (and refill) and keep scanning.
+                if (entry.win.isDestroyed()) {
+                    this.reclaim(entry, { destroyIfPooled: false, refill: false });
+                    continue;
+                }
+                entry.state = 'in-use';
+                return { win: entry.win, entryId: entry.id };
+            }
+        }
+        // Pool miss → fallback create. Not pooled; entryId null.
+        const win = this.createWindow(spec);
+        // Kick the load but do not await — acquire must not block.
+        void this.loadBlank(win);
+        return { win, entryId: null };
+    }
+    /**
+     * Return a window. Fallback windows (`entryId === null`) and entries whose
+     * spec no longer matches the current pool spec are torn down. Otherwise the
+     * window is reset (navigated to blank, then storage cleared) and re-pooled as
+     * `ready`, unless that would exceed `maxPoolSize`.
+     */
+    async release(entryId, win) {
+        if (entryId === null) {
+            this.destroyWindow(win);
+            return;
+        }
+        const entry = this.entries.get(entryId);
+        if (!entry) {
+            this.destroyWindow(win);
+            return;
+        }
+        if (this.disposed || !this.currentSpec || !this.matches(entry.spec, this.currentSpec)) {
+            this.disposeEntry(entry);
+            return;
+        }
+        entry.state = 'resetting';
+        await this.reset(entry);
+        // The entry may have been disposed/crashed/spec-changed/destroyed underneath
+        // the reset await; only re-pool if it is still the live, resetting entry with
+        // a live window. A destroyed window must never be re-marked `ready` (a later
+        // acquire would hand it out and the spawn would silently never boot).
+        if (this.disposed
+            || this.entries.get(entryId) !== entry
+            || entry.state !== 'resetting'
+            || entry.win.isDestroyed()) {
+            this.destroyWindow(entry.win);
+            this.entries.delete(entryId);
+            return;
+        }
+        // Honor the hard cap: if re-pooling would exceed maxPoolSize, drop it.
+        const otherPooled = this.warmCount() - (this.isWarm(entry) ? 1 : 0);
+        if (otherPooled >= this.maxPoolSize) {
+            this.disposeEntry(entry);
+            return;
+        }
+        entry.state = 'ready';
+    }
+    /**
+     * The owner of an acquired window reports it died externally (graceful close /
+     * crash) — reclaim its in-use slot so it isn't leaked in `entries` forever
+     * (bridge-router calls this on the `serviceAlreadyClosed` teardown path, where
+     * `release` is intentionally skipped). No-op for an unknown id; idempotent;
+     * never touches the (already-gone) window.
+     */
+    releaseDestroyed(entryId) {
+        if (entryId === null)
+            return;
+        const entry = this.entries.get(entryId);
+        if (!entry)
+            return;
+        this.reclaim(entry, { destroyIfPooled: false, refill: false });
+    }
+    /**
+     * Re-target the pool. `target` is clamped to `[0, maxPoolSize]`. Pooled
+     * entries beyond the target are disposed OLDEST-FIRST (doc §3.3/§3.6); in-use
+     * entries are untouched. Does not warm new entries up (use `init` / refill).
+     */
+    resize(target) {
+        this.targetSize = Math.min(Math.max(target, 0), this.maxPoolSize);
+        // Map iteration is insertion order, so `pooled` is oldest-first. Dispose the
+        // oldest prefix and keep the `targetSize` most-recently-created entries.
+        const pooled = [...this.entries.values()].filter((e) => this.isWarm(e));
+        const surplus = pooled.length - this.targetSize;
+        if (surplus <= 0)
+            return;
+        for (const entry of pooled.slice(0, surplus)) {
+            this.disposeEntry(entry);
+        }
+    }
+    /** Occupancy snapshot. */
+    getStats() {
+        let ready = 0;
+        let inUse = 0;
+        let warming = 0;
+        let resetting = 0;
+        for (const entry of this.entries.values()) {
+            switch (entry.state) {
+                case 'ready':
+                    ready++;
+                    break;
+                case 'in-use':
+                    inUse++;
+                    break;
+                case 'warming':
+                    warming++;
+                    break;
+                case 'resetting':
+                    resetting++;
+                    break;
+            }
+        }
+        return { total: this.entries.size, ready, inUse, warming, resetting, spec: this.currentSpec };
+    }
+    /** Tear down every entry and stop accepting work. */
+    async dispose() {
+        this.disposed = true;
+        this.targetSize = 0;
+        for (const entry of [...this.entries.values()]) {
+            this.disposeEntry(entry);
+        }
+    }
+    // ── internals ──────────────────────────────────────────────────────────
+    matches(a, b) {
+        return a.preloadPath === b.preloadPath;
+    }
+    /** ready + warming + resetting entries are "pooled" (owned by the pool). */
+    isWarm(entry) {
+        return entry.state === 'ready' || entry.state === 'warming' || entry.state === 'resetting';
+    }
+    warmCount() {
+        let n = 0;
+        for (const entry of this.entries.values()) {
+            if (this.isWarm(entry))
+                n++;
+        }
+        return n;
+    }
+    readyCount() {
+        let n = 0;
+        for (const entry of this.entries.values()) {
+            if (entry.state === 'ready')
+                n++;
+        }
+        return n;
+    }
+    /**
+     * Drive the pool to `targetSize` ready entries and resolve only then. Loops so
+     * a crash that drops a warming entry mid-init (which refills asynchronously
+     * via `onGone`) is awaited too, instead of resolving on a stale snapshot. A
+     * generous iteration guard prevents an unbounded spin if windows keep dying.
+     */
+    async warmUpToTarget() {
+        if (!this.currentSpec)
+            return;
+        let guard = 0;
+        const maxIterations = this.targetSize * 8 + 8;
+        while (!this.disposed && this.readyCount() < this.targetSize && guard++ < maxIterations) {
+            while (this.warmCount() < this.targetSize) {
+                void this.warmOne(this.currentSpec);
+            }
+            const warming = [...this.entries.values()]
+                .filter((e) => e.state === 'warming')
+                .map((e) => e.ready);
+            if (warming.length === 0)
+                break;
+            await Promise.all(warming);
+        }
+    }
+    createWindow(spec) {
+        return new BrowserWindow({
+            show: false,
+            width: spec.size?.width,
+            height: spec.size?.height,
+            webPreferences: {
+                preload: spec.preloadPath,
+                partition: spec.partition,
+                // Mirror createServiceHostWindow's process model (create.ts:24-30): the
+                // service-host preload does `require('electron')` and writes globals
+                // onto the page realm, so it requires nodeIntegration:false,
+                // contextIsolation:false, sandbox:false. Default to that contract; let a
+                // caller override via the spec for a different runtime.
+                nodeIntegration: spec.nodeIntegration ?? false,
+                contextIsolation: spec.contextIsolation ?? false,
+                sandbox: spec.sandbox ?? false,
+            },
+        });
+    }
+    loadBlank(win) {
+        // `loadURL` resolves on did-finish-load in Electron; treat any failure as a
+        // settled load so a single bad warm never wedges the pool. The synchronous
+        // call ITSELF throws on an already-destroyed webContents (it isn't a
+        // rejection) — swallow that too, so reset/release of a window that died
+        // mid-flight resolves instead of rejecting (the "never wedges" contract).
+        try {
+            return Promise.resolve(win.webContents.loadURL(BLANK_URL)).then(() => undefined, () => undefined);
+        }
+        catch {
+            return Promise.resolve();
+        }
+    }
+    /** Construct + load a fresh pooled entry, registering crash recovery. */
+    warmOne(spec) {
+        const win = this.createWindow(spec);
+        const id = `pool-${++this.nextId}`;
+        const entry = { id, spec, state: 'warming', win, ready: Promise.resolve() };
+        this.entries.set(id, entry);
+        win.webContents.on('render-process-gone', () => this.onGone(entry));
+        // A window can also die by graceful close (app quit / manual close), which
+        // never fires render-process-gone. Observe it too so a pooled entry isn't
+        // leaked. reclaim is a no-op if WE disposed it (disposeEntry deletes the
+        // entry before its own destroy fires 'closed').
+        win.once('closed', () => this.reclaim(entry, { destroyIfPooled: false, refill: false }));
+        entry.ready = this.loadBlank(win).then(() => {
+            if (entry.state === 'warming')
+                entry.state = 'ready';
+        });
+        return entry.ready;
+    }
+    /**
+     * Reset a released window back to a clean, blank state. Order matters
+     * (doc §3.5.3 / §3.4「等待时序」): navigate to blank FIRST so the old document
+     * stops running and in-flight requests are aborted, THEN clear storage — so a
+     * still-live old page cannot re-populate storage after the clear.
+     */
+    async reset(entry) {
+        await this.loadBlank(entry.win);
+        // Consumers sharing a session opt out of the storage clear (see
+        // ServiceHostSpec.clearStorageOnReset): clearing a shared partition would wipe
+        // other live projects. Navigation-to-blank above still resets the JS realm.
+        if (entry.spec.clearStorageOnReset === false)
+            return;
+        // The window may have been destroyed during the load await; touching a dead
+        // webContents.session throws SYNCHRONOUSLY, which would reject release().
+        if (entry.win.isDestroyed())
+            return;
+        try {
+            const ses = entry.win.webContents.session;
+            await ses.clearStorageData({ storages: [...RESET_STORAGES] });
+            await ses.clearCache();
+        }
+        catch {
+            // Window/session torn down mid-reset — release() re-checks isDestroyed and
+            // disposes the entry, so swallowing here keeps release from rejecting.
+        }
+    }
+    /** A spec change tears down pooled entries and re-targets the pool. */
+    onSpecChange(spec) {
+        for (const entry of [...this.entries.values()]) {
+            if (this.isWarm(entry))
+                this.disposeEntry(entry);
+        }
+        this.currentSpec = spec;
+    }
+    /**
+     * Reclaim an entry whose window died externally (render crash, graceful close,
+     * or an owner-reported destruction). A POOLED death frees a spare → refill
+     * toward target; an IN-USE death is the caller's window → drop the bookkeeping
+     * WITHOUT destroying it from under them, and do not refill (the spare count is
+     * unaffected). `destroyIfPooled` destroys the husk for a pooled render crash
+     * (the BrowserWindow object can outlive a dead render process); skip it for a
+     * `'closed'`/owner-reported window that is already gone. No-op if the entry was
+     * already disposed by us (disposeEntry deletes before its own destroy fires
+     * `'closed'`, so this finds nothing).
+     */
+    reclaim(entry, opts) {
+        if (!this.entries.has(entry.id))
+            return;
+        const wasPooled = this.isWarm(entry);
+        entry.state = 'disposing';
+        this.entries.delete(entry.id);
+        if (wasPooled && opts.destroyIfPooled)
+            this.destroyWindow(entry.win);
+        // Refill ONLY on crash recovery (onGone). A graceful `'closed'` on a pooled
+        // window happens exclusively at app/project teardown (the windows are hidden;
+        // nothing else closes them) — refilling there would `new BrowserWindow` while
+        // Electron is trying to quit, recreating windows faster than they close and
+        // hanging the shutdown. So `refill` is opt-in per caller.
+        if (!opts.refill || this.disposed || !this.currentSpec || !wasPooled)
+            return;
+        while (this.warmCount() < this.targetSize) {
+            void this.warmOne(this.currentSpec);
+        }
+    }
+    /** A pooled window's render process died — reclaim + refill (destroy the husk). */
+    onGone(entry) {
+        this.reclaim(entry, { destroyIfPooled: true, refill: true });
+    }
+    disposeEntry(entry) {
+        entry.state = 'disposing';
+        this.entries.delete(entry.id);
+        this.destroyWindow(entry.win);
+    }
+    destroyWindow(win) {
+        try {
+            if (!win || (typeof win.isDestroyed === 'function' && win.isDestroyed()))
+                return;
+            if (typeof win.destroy === 'function')
+                win.destroy();
+            else if (typeof win.close === 'function')
+                win.close();
+        }
+        catch {
+            // A window already gone (e.g. crashed process) is fine to ignore.
+        }
+    }
+}
+//# sourceMappingURL=pool.js.map

package/dist/main/services/simulator/custom-apis.d.ts

@@ -2,8 +2,42 @@ export type SimulatorApiHandler = (params: unknown) => unknown | Promise<unknown
 export interface SimulatorApiRegistry {
     register(name: string, handler: SimulatorApiHandler): () => void;
     list(): string[];
+    has(name: string): boolean;
     invoke(name: string, params: unknown): Promise<unknown>;
     clear(): void;
 }
+/**
+ * Bridge request/response shapes shared by the simulator-side preload
+ * (`src/preload/runtime/custom-apis.ts`) and the two host-side dispatchers that
+ * service it (the trusted main-window renderer proxy was the original path; the
+ * native-host top-level WebContentsView dispatcher in the ViewManager is the
+ * current one). Kept here next to the registry so both stay in lockstep with
+ * the preload contract.
+ */
+export type CustomApiBridgeRequest = {
+    id: number;
+    op: 'list';
+} | {
+    id: number;
+    op: 'invoke';
+    name: string;
+    params: unknown;
+};
+export type CustomApiBridgeResponse = {
+    id: number;
+    result: unknown;
+} | {
+    id: number;
+    error: string;
+};
+/**
+ * Run a single custom-apis bridge request against the given registry and return
+ * the id-correlated response the preload's pending-map expects. Never throws:
+ * a handler rejection / malformed request becomes an `{ id, error }` response so
+ * the caller only has to ship it back over the bridge channel. The one shared
+ * implementation behind both the `SimulatorCustomApiChannel` IPC handlers and
+ * the native-host `ipc-message-host` dispatcher.
+ */
+export declare function handleCustomApiBridgeRequest(apis: Pick<SimulatorApiRegistry, 'list' | 'invoke'>, req: CustomApiBridgeRequest): Promise<CustomApiBridgeResponse>;
 export declare function createSimulatorApiRegistry(): SimulatorApiRegistry;
 //# sourceMappingURL=custom-apis.d.ts.map

package/dist/main/services/simulator/custom-apis.js

@@ -1,3 +1,22 @@
+/**
+ * Run a single custom-apis bridge request against the given registry and return
+ * the id-correlated response the preload's pending-map expects. Never throws:
+ * a handler rejection / malformed request becomes an `{ id, error }` response so
+ * the caller only has to ship it back over the bridge channel. The one shared
+ * implementation behind both the `SimulatorCustomApiChannel` IPC handlers and
+ * the native-host `ipc-message-host` dispatcher.
+ */
+export async function handleCustomApiBridgeRequest(apis, req) {
+    try {
+        const result = req.op === 'list'
+            ? apis.list()
+            : await apis.invoke(req.name, req.params);
+        return { id: req.id, result };
+    }
+    catch (err) {
+        return { id: req.id, error: err instanceof Error ? err.message : String(err) };
+    }
+}
 export function createSimulatorApiRegistry() {
     const handlers = new Map();
     return {
@@ -11,6 +30,9 @@ export function createSimulatorApiRegistry() {
         list() {
             return Array.from(handlers.keys());
         },
+        has(name) {
+            return handlers.has(name);
+        },
         async invoke(name, params) {
             const handler = handlers.get(name);
             if (!handler)

package/dist/main/services/simulator-appdata/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Native-host AppData panel service.
+ *
+ * Taps the service→render setData stream (bridge-router SERVICE_PUBLISH) — under
+ * native-host the service logic runs in the hidden service-host window, not a
+ * Worker in the simulator guest, so the default Worker-hook source goes blind.
+ * Decodes + accumulates per app via the SHARED `AppDataAccumulator`, mirroring
+ * the Storage/WXML main→renderer contract:
+ *   - PULL: answers `SimulatorAppDataChannel.GetSnapshot` with the ACTIVE app's
+ *     cumulative `accumulator.snapshot()` (empty snapshot when it has no data).
+ *   - PUSH: on each accepted message / bridge eviction for the ACTIVE app,
+ *     pushes the updated snapshot via `SimulatorAppDataChannel.Event`.
+ */
+import type { WebContents } from 'electron';
+import type { MessageEnvelope } from '../../../shared/bridge-channels.js';
+import { type Disposable } from '@dimina-kit/electron-deck/main';
+import { type SenderPolicy } from '../../utils/ipc-registry.js';
+export interface AppDataTap {
+    /** Feed one service→render message for an app; decodes + accumulates + pushes if active. */
+    onServiceToRender(appId: string, msg: MessageEnvelope): void;
+    /** Evict a page bridge (page teardown) from an app's accumulator; pushes if active. */
+    evictBridge(appId: string, bridgeId: string): void;
+    /** The ACTIVE app's current reactive page state for a bridge (`{}` when none). */
+    getPageData(bridgeId: string): Record<string, unknown>;
+    /** Snapshot all accumulated appdata for an app. Optional for compatibility with tests/mocks. */
+    snapshot?: (appId: string) => unknown;
+}
+export interface SimulatorAppDataService extends AppDataTap, Disposable {
+}
+export interface SimulatorAppDataOptions {
+    getActiveAppId: () => string | null;
+    senderPolicy?: SenderPolicy;
+}
+export declare function setupSimulatorAppData(host: WebContents, options: SimulatorAppDataOptions): SimulatorAppDataService;
+//# sourceMappingURL=index.d.ts.map

package/dist/main/services/simulator-appdata/index.js

@@ -0,0 +1,71 @@
+import { SimulatorAppDataChannel } from '../../../shared/ipc-channels.js';
+import { AppDataAccumulator, decodeWorkerMessage, decodedToInput, } from '../../../shared/appdata-accumulator.js';
+import { DisposableRegistry } from '@dimina-kit/electron-deck/main';
+import { IpcRegistry } from '../../utils/ipc-registry.js';
+const EMPTY_SNAPSHOT = { bridges: [], entries: {} };
+export function setupSimulatorAppData(host, options) {
+    const { getActiveAppId } = options;
+    // One accumulator per app — native-host can host multiple sessions; the panel
+    // only ever shows the active one (resolved via getActiveAppId).
+    const accumulators = new Map();
+    function accumulatorFor(appId) {
+        let acc = accumulators.get(appId);
+        if (!acc) {
+            acc = new AppDataAccumulator();
+            accumulators.set(appId, acc);
+        }
+        return acc;
+    }
+    /** Push the active app's snapshot to the renderer (no-op for non-active/destroyed). */
+    function pushIfActive(appId) {
+        if (appId !== getActiveAppId())
+            return;
+        if (host.isDestroyed())
+            return;
+        host.send(SimulatorAppDataChannel.Event, accumulatorFor(appId).snapshot());
+    }
+    function onServiceToRender(appId, msg) {
+        const entries = decodeWorkerMessage(msg);
+        if (!entries)
+            return;
+        const acc = accumulatorFor(appId);
+        let mutated = false;
+        for (const entry of entries) {
+            if (acc.apply(decodedToInput(entry)))
+                mutated = true;
+        }
+        if (mutated)
+            pushIfActive(appId);
+    }
+    function evictBridge(appId, bridgeId) {
+        accumulatorFor(appId).clearBridge(bridgeId);
+        pushIfActive(appId);
+    }
+    function getPageData(bridgeId) {
+        const activeAppId = getActiveAppId();
+        if (!activeAppId)
+            return {};
+        return accumulators.get(activeAppId)?.pageData(bridgeId) ?? {};
+    }
+    const ipc = new IpcRegistry(options.senderPolicy);
+    ipc.handle(SimulatorAppDataChannel.GetSnapshot, () => {
+        const appId = getActiveAppId();
+        if (!appId)
+            return EMPTY_SNAPSHOT;
+        return accumulators.get(appId)?.snapshot() ?? EMPTY_SNAPSHOT;
+    });
+    // disposeAll runs LIFO; add the IPC registry LAST so it is torn down first —
+    // its removeHandler then runs synchronously (before the first `await` yields),
+    // which callers that `dispose()` without awaiting rely on.
+    const registry = new DisposableRegistry();
+    registry.add(() => accumulators.clear());
+    registry.add(ipc);
+    return {
+        onServiceToRender,
+        evictBridge,
+        getPageData,
+        snapshot: (appId) => accumulatorFor(appId).snapshot(),
+        dispose: () => registry.dispose(),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/main/services/simulator-current-page/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Native-host current-page push service.
+ *
+ * The devtools toolbar shows the visible top-of-stack page route. Under
+ * native-host the page stack lives in the DeviceShell WebContentsView (each
+ * page a nested render-host `<webview>`), not a renderer `<webview>` the main
+ * window can observe — so in-app navigation (navigateTo / switchTab / back)
+ * never reaches the renderer's `<webview>` did-navigate events. This service
+ * taps the bridge's active-page signal and pushes the new route to the
+ * main-window renderer (`SimulatorChannel.CurrentPage`), keeping the toolbar in
+ * sync without polling.
+ *
+ * Inert on the default dimina-fe path (which derives the current page from the
+ * simulator `<webview>`'s navigation events); app.ts gates the call on
+ * `ctx.bridge.isNativeHost()`.
+ */
+import type { WebContents } from 'electron';
+import type { BridgeRouterHandle } from '../../ipc/bridge-router.js';
+import { type Disposable } from '@dimina-kit/electron-deck/main';
+export interface SimulatorCurrentPageOptions {
+    bridge: BridgeRouterHandle;
+}
+export declare function setupSimulatorCurrentPage(host: WebContents, options: SimulatorCurrentPageOptions): Disposable;
+//# sourceMappingURL=index.d.ts.map

package/dist/main/services/simulator-current-page/index.js

@@ -0,0 +1,19 @@
+import { SimulatorChannel } from '../../../shared/ipc-channels.js';
+import { DisposableRegistry } from '@dimina-kit/electron-deck/main';
+export function setupSimulatorCurrentPage(host, options) {
+    const registry = new DisposableRegistry();
+    // Push the new route whenever the visible top-of-stack page changes. domReady
+    // events (same kind stream) carry no pagePath and are ignored; the renderer
+    // already seeds the entry route from the launch URL, so the first meaningful
+    // update is the first post-boot navigation.
+    const off = options.bridge.onRenderEvent((ev) => {
+        if (ev.kind !== 'activePage' || !ev.pagePath)
+            return;
+        if (host.isDestroyed())
+            return;
+        host.send(SimulatorChannel.CurrentPage, ev.pagePath);
+    });
+    registry.add(off);
+    return registry;
+}
+//# sourceMappingURL=index.js.map

package/dist/main/services/simulator-storage/index.d.ts

@@ -16,8 +16,27 @@
  *     events stop flowing until they close it.
  */
 import { type WebContents } from 'electron';
-import { type Disposable } from '../../utils/disposable.js';
+import { type ConnectionRegistry, type Disposable } from '@dimina-kit/electron-deck/main';
 import { type SenderPolicy } from '../../utils/ipc-registry.js';
+import type { BridgeRouterHandle } from '../../ipc/bridge-router.js';
+import type { RenderInspector } from '../render-inspect/index.js';
+/**
+ * Runtime async-storage handler (native-host). bridge-router routes async
+ * `wx.setStorage`/`getStorage`/… here so they hit the SAME service-host `file://`
+ * store as the sync APIs — eliminating the default-arch split where async writes
+ * landed on the simulator `http://` origin and sync writes on `file://`. Returns
+ * the value for the wx success callback (or throws → wx fail callback).
+ */
+export interface StorageApi {
+    invoke(appId: string, name: string, params: Record<string, unknown>): Promise<unknown>;
+}
+/** Async wx storage API names routed through the unified service-window store. */
+export declare const STORAGE_API_NAMES: Set<string>;
+/** The storage panel's return — a Disposable plus the native-host runtime hook. */
+export interface SimulatorStorageHandle extends Disposable {
+    /** Present only under native-host; wired to ctx.storageApi for bridge-router. */
+    storageApi: StorageApi | null;
+}
 export interface SimulatorStorageOptions {
     /**
      * Sender gate applied to `SimulatorStorageChannel.GetSnapshot`.
@@ -36,6 +55,22 @@ export interface SimulatorStorageOptions {
      * CDP snapshot/event stream to the active appId.
      */
     getActiveAppId: () => string | null;
+    /**
+     * Bridge-router accessor (native-host only). When present and native-host is
+     * on, element inspection targets the active render-host <webview> guest via
+     * `renderInspector` instead of the simulator iframe's `__simulatorData`.
+     */
+    bridge?: BridgeRouterHandle;
+    /** Injects/drives the render-guest inspector; required for native-host inspect. */
+    renderInspector?: RenderInspector;
+    /**
+     * Connection-layer registry (`@dimina-kit/electron-deck/main`). When provided,
+     * per-webContents teardowns are routed through `acquire(wc).own(cleanup)` so
+     * they fire deterministically on wc destroy / connection reset instead of the
+     * bespoke `wc.once('destroyed', cleanup)` hook. Optional so callers that have
+     * not adopted the connection layer compile and behave unchanged.
+     */
+    connections?: ConnectionRegistry;
 }
-export declare function setupSimulatorStorage(host: WebContents, options: SimulatorStorageOptions): Disposable;
+export declare function setupSimulatorStorage(host: WebContents, options: SimulatorStorageOptions): SimulatorStorageHandle;
 //# sourceMappingURL=index.d.ts.map