@dimina-kit/devtools 0.3.2-dev.20260601115343 → 0.3.2-dev.20260610114009

package/dist/preload/runtime/custom-apis.js

@@ -4,29 +4,32 @@ import { exposeOnMainWorld } from '../shared/expose.js';
 /**
  * Re-send interval and ceiling for `list()` (see `listWithRetry`).
  *
- * The simulator boots fast enough that `__diminaCustomApis.list()` can fire
- * its `sendToHost` request *before* the embedding main-window renderer has
- * attached its `ipc-message` proxy listener (`useCustomApiProxy`). `sendToHost`
- * is fire-and-forget — a request sent into that gap is lost, and the bridge
- * call would otherwise hang until `custom-api-boot.ts`'s 3s deadlock-breaker.
+ * `ipcRenderer.send` is fire-and-forget — a request sent before the main-side
+ * `ipcMain.on` listener is live (e.g. across a relaunch / re-attach cycle) is
+ * lost, and the bridge call would otherwise hang until `custom-api-boot.ts`'s
+ * 3s deadlock-breaker.
  *
  * `list` is an idempotent read, so it is safe to re-send until a response
- * arrives. The retry resolves within one embedder attach cycle (~200ms) in
- * practice; the ceiling only bounds the leak if the proxy never attaches at
- * all, and is kept below `custom-api-boot.ts`'s `CUSTOM_API_LIST_TIMEOUT_MS`
- * so the retry exhausts before — not after — that outer timeout would fire.
+ * arrives. The retry resolves quickly in practice; the ceiling only bounds the
+ * leak if the listener never answers, and is kept below `custom-api-boot.ts`'s
+ * `CUSTOM_API_LIST_TIMEOUT_MS` so the retry exhausts before — not after — that
+ * outer timeout would fire.
  */
 const LIST_RETRY_INTERVAL_MS = 150;
 const LIST_RETRY_CEILING_MS = 2500;
-// The simulator <webview> is intentionally kept off the workbench sender-policy
-// white-list, so it cannot reach `ipcMain.handle` directly. Instead the bridge
-// asks the trusted main-window renderer to proxy the call: webview sends via
-// `ipcRenderer.sendToHost`, host does the `ipcInvoke`, and posts the result
-// back through `<webview>.send`. Requests and responses are correlated by id
-// so concurrent invokes do not tangle.
+// native-host is the sole runtime: the simulator is a top-level
+// WebContentsView with no embedder to `sendToHost`, so it `ipcRenderer.send`s
+// the request straight to a `ctx.simulatorApis`-backed `ipcMain.on` listener
+// bound to this exact simWc (see view-manager `attachNativeCustomApiBridge`),
+// which posts the result back via `simWc.send`. Responses land on the
+// `ipcRenderer.on(Response)` handler and are correlated to requests by id, so
+// concurrent invokes do not tangle.
 function buildBridge() {
     let nextId = 1;
     const pending = new Map();
+    const sendRequest = (req) => {
+        ipcRenderer.send(SimulatorCustomApiBridgeChannel.Request, req);
+    };
     ipcRenderer.on(SimulatorCustomApiBridgeChannel.Response, (_event, payload) => {
         const entry = pending.get(payload.id);
         if (!entry)
@@ -45,7 +48,7 @@ function buildBridge() {
                 resolve: (value) => resolve(value),
                 reject,
             });
-            ipcRenderer.sendToHost(SimulatorCustomApiBridgeChannel.Request, req);
+            sendRequest(req);
         });
     };
     /**
@@ -90,7 +93,7 @@ function buildBridge() {
                         reject(reason);
                     },
                 });
-                ipcRenderer.sendToHost(SimulatorCustomApiBridgeChannel.Request, { id, op: 'list' });
+                sendRequest({ id, op: 'list' });
             };
             state.retryTimer = setInterval(attempt, LIST_RETRY_INTERVAL_MS);
             state.ceilingTimer = setTimeout(() => {

package/dist/preload/runtime/host-toolbar-advertiser.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Reverse size-advertiser preload for the host-controllable toolbar
+ * WebContentsView. Runs in that WCV's OWN renderer (the toolbar content's
+ * preload), measures the toolbar's intrinsic block (height) extent and sends it
+ * to the main process. Main pushes the value back to the main-window renderer as
+ * `HostToolbarHeightChanged`, which resizes the toolbar placeholder, re-measures
+ * the forward anchor, and re-overlays this WCV — closing the dynamic-height loop
+ * (see `@dimina-kit/view-anchor` `createSizeAdvertiser`).
+ */
+/**
+ * Attach the advertiser to the toolbar content's shrink-to-fit root
+ * (`[data-host-toolbar-root]`). That element MUST be shrink-to-fit on the block
+ * axis — its height must reflect the content, not the host-applied view height,
+ * or the cross-process loop never converges (`createSizeAdvertiser`'s footgun).
+ * If the element is missing we warn and no-op rather than measure `<body>`,
+ * whose block size IS the view size and would advertise nonsense.
+ *
+ * Returns a disposer that tears the advertiser down.
+ */
+export declare function installHostToolbarAdvertiser(): () => void;
+/**
+ * Install once the DOM is ready (the root element must exist before we query).
+ * Self-gating: if the document is already past `loading`, install synchronously;
+ * otherwise wait for `DOMContentLoaded`.
+ */
+export declare function installHostToolbarAdvertiserWhenReady(): void;
+//# sourceMappingURL=host-toolbar-advertiser.d.ts.map

package/dist/preload/runtime/host-toolbar-advertiser.js

@@ -0,0 +1,55 @@
+/**
+ * Reverse size-advertiser preload for the host-controllable toolbar
+ * WebContentsView. Runs in that WCV's OWN renderer (the toolbar content's
+ * preload), measures the toolbar's intrinsic block (height) extent and sends it
+ * to the main process. Main pushes the value back to the main-window renderer as
+ * `HostToolbarHeightChanged`, which resizes the toolbar placeholder, re-measures
+ * the forward anchor, and re-overlays this WCV — closing the dynamic-height loop
+ * (see `@dimina-kit/view-anchor` `createSizeAdvertiser`).
+ */
+import { ipcRenderer } from 'electron';
+import { createSizeAdvertiser } from '@dimina-kit/view-anchor';
+import { ViewChannel } from '../../shared/ipc-channels.js';
+/**
+ * Attach the advertiser to the toolbar content's shrink-to-fit root
+ * (`[data-host-toolbar-root]`). That element MUST be shrink-to-fit on the block
+ * axis — its height must reflect the content, not the host-applied view height,
+ * or the cross-process loop never converges (`createSizeAdvertiser`'s footgun).
+ * If the element is missing we warn and no-op rather than measure `<body>`,
+ * whose block size IS the view size and would advertise nonsense.
+ *
+ * Returns a disposer that tears the advertiser down.
+ */
+export function installHostToolbarAdvertiser() {
+    const root = document.querySelector('[data-host-toolbar-root]');
+    if (!root) {
+        console.warn('[host-toolbar-advertiser] no `[data-host-toolbar-root]` element found — ' +
+            'not advertising a height. The toolbar content must wrap itself in a ' +
+            'shrink-to-fit `[data-host-toolbar-root]` element so its block size is ' +
+            'the content height, not the host-given view size.');
+        return () => { };
+    }
+    const advertiser = createSizeAdvertiser(root, {
+        axis: 'block',
+        publish: (size) => {
+            ipcRenderer.send(ViewChannel.HostToolbarAdvertiseHeight, size);
+        },
+    });
+    return () => advertiser.dispose();
+}
+/**
+ * Install once the DOM is ready (the root element must exist before we query).
+ * Self-gating: if the document is already past `loading`, install synchronously;
+ * otherwise wait for `DOMContentLoaded`.
+ */
+export function installHostToolbarAdvertiserWhenReady() {
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', () => {
+            installHostToolbarAdvertiser();
+        }, { once: true });
+    }
+    else {
+        installHostToolbarAdvertiser();
+    }
+}
+//# sourceMappingURL=host-toolbar-advertiser.js.map

package/dist/preload/runtime/main-api-runner.d.ts

@@ -0,0 +1,9 @@
+type LooseApiHandler = (this: any, params?: unknown) => unknown | Promise<unknown>;
+export interface ApiRunVerdict {
+    ok: boolean;
+    result?: unknown;
+    errMsg?: string;
+}
+export declare function runApiAsync(handlers: Record<string, LooseApiHandler | undefined>, name: string, params: unknown): Promise<ApiRunVerdict>;
+export {};
+//# sourceMappingURL=main-api-runner.d.ts.map

package/dist/preload/runtime/main-api-runner.js

@@ -0,0 +1,85 @@
+function makeBaseContext() {
+    // Minimal viewport rect: enough for handlers that read
+    // `parent.el.querySelector('.dimina-native-webview__root').getBoundingClientRect()`
+    // (see simulator-api.ts readWindowMetrics).
+    const fakeRect = { width: 390, height: 844, x: 0, y: 0, top: 0, left: 0, right: 390, bottom: 844 };
+    const fakeRoot = {
+        getBoundingClientRect: () => fakeRect,
+    };
+    return {
+        appId: '',
+        createCallbackFunction: () => undefined,
+        parent: {
+            el: {
+                querySelector: () => fakeRoot,
+            },
+            getStatusBarRect: () => ({ height: 0 }),
+        },
+    };
+}
+export function runApiAsync(handlers, name, params) {
+    const handler = handlers[name];
+    if (!handler) {
+        return Promise.resolve({ ok: false, errMsg: `${name}:fail no handler` });
+    }
+    return new Promise((resolve) => {
+        let resolved = false;
+        const finish = (verdict) => {
+            if (resolved)
+                return;
+            resolved = true;
+            resolve(verdict);
+        };
+        const SUCCESS = Symbol('main-cb-success');
+        const FAIL = Symbol('main-cb-fail');
+        const COMPLETE = Symbol('main-cb-complete');
+        const base = makeBaseContext();
+        const ctx = {
+            ...base,
+            createCallbackFunction(id) {
+                if (id === undefined || id === null)
+                    return undefined;
+                return (...args) => {
+                    const arg = args[0];
+                    if (id === SUCCESS) {
+                        finish({ ok: true, result: arg });
+                    }
+                    else if (id === FAIL) {
+                        const errMsg = arg && typeof arg === 'object' && 'errMsg' in arg
+                            ? String(arg.errMsg)
+                            : `${name}:fail`;
+                        finish({ ok: false, errMsg, result: arg });
+                    }
+                };
+            },
+        };
+        const userParams = params && typeof params === 'object' && !Array.isArray(params)
+            ? { ...params }
+            : {};
+        const hadSuccess = userParams.success !== undefined && userParams.success !== null;
+        const hadFail = userParams.fail !== undefined && userParams.fail !== null;
+        const hadComplete = userParams.complete !== undefined && userParams.complete !== null;
+        userParams.success = SUCCESS;
+        userParams.fail = FAIL;
+        if (hadComplete)
+            userParams.complete = COMPLETE;
+        try {
+            const ret = handler.call(ctx, userParams);
+            if (ret && typeof ret.then === 'function') {
+                Promise.resolve(ret).then((r) => finish({ ok: true, result: r }), (err) => {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    finish({ ok: false, errMsg: `${name}:fail ${msg}` });
+                });
+                return;
+            }
+            if (!hadSuccess && !hadFail) {
+                finish({ ok: true, result: ret });
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            finish({ ok: false, errMsg: `${name}:fail ${msg}` });
+        }
+    });
+}
+//# sourceMappingURL=main-api-runner.js.map

package/dist/preload/runtime/native-host.d.ts

@@ -0,0 +1,43 @@
+import type { NativeDeviceInfo } from '../../shared/ipc-channels.js';
+import type { ActivePagePayload, ApiResponsePayload, NavCallbackPayload, PageLifecyclePayload, PageOpenRequest, PageOpenResult, PageStackPayload, SpawnRequest, SpawnResult } from '../../shared/bridge-channels.js';
+export interface RenderHostUrlOptions {
+    bridgeId: string;
+    appId: string;
+    pagePath: string;
+}
+export interface DiminaNativeHostBridge {
+    enabled: boolean;
+    spawn(opts: SpawnRequest): Promise<SpawnResult>;
+    dispose(bridgeId: string): void;
+    openPage(opts: PageOpenRequest): Promise<PageOpenResult>;
+    closePage(bridgeId: string): void;
+    notifyLifecycle(payload: PageLifecyclePayload): void;
+    notifyNavCallback(payload: NavCallbackPayload): void;
+    notifyApiResponse(payload: ApiResponsePayload): void;
+    /** Tell main which page is the visible top-of-stack (for panel/automation targeting). */
+    notifyActivePage(payload: ActivePagePayload): void;
+    /** Tell main the full ordered page stack (for automation's App.getPageStack). */
+    notifyPageStack(payload: PageStackPayload): void;
+    createRenderHostUrl(opts: RenderHostUrlOptions): string;
+    renderPreloadUrl: string;
+    /**
+     * The selected device at bridge-install time, if the renderer already pushed
+     * it (it does — SetDeviceInfo precedes AttachNative). DeviceShell reads this
+     * as its initial device; live changes arrive via the DEVICE_CHANGE event.
+     */
+    device?: NativeDeviceInfo;
+    /**
+     * Subscribe to a main→simulator event channel (SIMULATOR_EVENTS). Returns an
+     * unsubscribe fn. The simulator renderer (DeviceShell) runs in the webview
+     * main world with `nodeIntegration:false`, so it cannot `import 'electron'`;
+     * this bridge owns the `ipcRenderer` plumbing on its behalf.
+     */
+    onSimulatorEvent<T = unknown>(channel: string, listener: (payload: T) => void): () => void;
+}
+/**
+ * Install the native-host bridge on the simulator main world when native-host
+ * mode is on. Self-gating: a no-op disposer is returned when it's off, so the
+ * caller can install unconditionally.
+ */
+export declare function installNativeHostBridge(): () => void;
+//# sourceMappingURL=native-host.d.ts.map

package/dist/preload/runtime/native-host.js

@@ -0,0 +1,83 @@
+import { ipcRenderer } from 'electron';
+import { BRIDGE_CHANNELS as C } from '../../shared/bridge-channels.js';
+import { exposeOnMainWorld } from '../shared/expose.js';
+/**
+ * Ask the main process (synchronously, at install time) whether native-host is
+ * on and, if so, for the render-host file:// URLs. The simulator webview's
+ * preload can't read the launch `process.env`, and — crucially — can't use
+ * `node:path`/`node:url` to compute paths (the guest preload has no Node
+ * builtins), so the main process (which has both) supplies everything here.
+ */
+function queryNativeHostConfig() {
+    try {
+        const res = ipcRenderer.sendSync(C.NATIVE_HOST_ENABLED);
+        return res && res.enabled ? res : null;
+    }
+    catch {
+        return null;
+    }
+}
+function buildBridge(cfg) {
+    return {
+        enabled: true,
+        spawn(opts) {
+            return ipcRenderer.invoke(C.SPAWN, opts);
+        },
+        dispose(bridgeId) {
+            const payload = { bridgeId };
+            ipcRenderer.send(C.DISPOSE, payload);
+        },
+        openPage(opts) {
+            return ipcRenderer.invoke(C.PAGE_OPEN, opts);
+        },
+        closePage(bridgeId) {
+            const payload = { bridgeId };
+            ipcRenderer.send(C.PAGE_CLOSE, payload);
+        },
+        notifyLifecycle(payload) {
+            ipcRenderer.send(C.PAGE_LIFECYCLE, payload);
+        },
+        notifyNavCallback(payload) {
+            ipcRenderer.send(C.NAV_CALLBACK, payload);
+        },
+        notifyApiResponse(payload) {
+            ipcRenderer.send(C.API_RESPONSE, payload);
+        },
+        notifyActivePage(payload) {
+            ipcRenderer.send(C.ACTIVE_PAGE, payload);
+        },
+        notifyPageStack(payload) {
+            ipcRenderer.send(C.PAGE_STACK, payload);
+        },
+        createRenderHostUrl(opts) {
+            // `URL` + `URLSearchParams` are web globals — no node:url needed.
+            const url = new URL(cfg.renderHostHtmlUrl);
+            url.searchParams.set('bridgeId', opts.bridgeId);
+            url.searchParams.set('appId', opts.appId);
+            url.searchParams.set('pagePath', opts.pagePath);
+            return url.toString();
+        },
+        renderPreloadUrl: cfg.renderPreloadUrl,
+        device: cfg.device,
+        onSimulatorEvent(channel, listener) {
+            const wrapped = (_event, payload) => {
+                ;
+                listener(payload);
+            };
+            ipcRenderer.on(channel, wrapped);
+            return () => ipcRenderer.removeListener(channel, wrapped);
+        },
+    };
+}
+/**
+ * Install the native-host bridge on the simulator main world when native-host
+ * mode is on. Self-gating: a no-op disposer is returned when it's off, so the
+ * caller can install unconditionally.
+ */
+export function installNativeHostBridge() {
+    const cfg = queryNativeHostConfig();
+    if (!cfg)
+        return () => { };
+    return exposeOnMainWorld('__diminaNativeHost', buildBridge(cfg));
+}
+//# sourceMappingURL=native-host.js.map

package/dist/preload/shared/expose.d.ts

@@ -1,12 +1,17 @@
 /**
  * Expose `value` on the renderer's main world under `key`.
  *
- * Prefers Electron's `contextBridge` (the path that works with
- * `contextIsolation: true`). When `contextBridge` is unavailable — e.g. a
- * webview running without context isolation — it falls back to assigning
- * `value` directly onto the preload realm's `window`.
+ * Uses Electron's `contextBridge` only when `contextIsolation` is enabled
+ * (the path that reaches the renderer's `window` through the isolated world).
+ * When context isolation is OFF — e.g. the simulator/render-host/service-host
+ * frames — `contextBridge.exposeInMainWorld` would always throw, so we skip it
+ * entirely and assign `value` directly onto the preload realm's `window`.
  *
- * Returns a disposer. It can only undo the fallback assignment (a
+ * `process.contextIsolated` is Electron's renderer-side boolean for the current
+ * frame: `true` when context isolation is on, `false` when it's off. (It is
+ * `undefined` only in the main process, which never runs this preload helper.)
+ *
+ * Returns a disposer. It can only undo the direct-assignment path (a
  * `contextBridge` binding cannot be un-exposed); on the contextBridge path
  * the disposer is a no-op. The disposer never clobbers a `window[key]` that
  * something else has since reassigned.

package/dist/preload/shared/expose.js

@@ -2,28 +2,46 @@ import { contextBridge } from 'electron';
 /**
  * Expose `value` on the renderer's main world under `key`.
  *
- * Prefers Electron's `contextBridge` (the path that works with
- * `contextIsolation: true`). When `contextBridge` is unavailable — e.g. a
- * webview running without context isolation — it falls back to assigning
- * `value` directly onto the preload realm's `window`.
+ * Uses Electron's `contextBridge` only when `contextIsolation` is enabled
+ * (the path that reaches the renderer's `window` through the isolated world).
+ * When context isolation is OFF — e.g. the simulator/render-host/service-host
+ * frames — `contextBridge.exposeInMainWorld` would always throw, so we skip it
+ * entirely and assign `value` directly onto the preload realm's `window`.
  *
- * Returns a disposer. It can only undo the fallback assignment (a
+ * `process.contextIsolated` is Electron's renderer-side boolean for the current
+ * frame: `true` when context isolation is on, `false` when it's off. (It is
+ * `undefined` only in the main process, which never runs this preload helper.)
+ *
+ * Returns a disposer. It can only undo the direct-assignment path (a
  * `contextBridge` binding cannot be un-exposed); on the contextBridge path
  * the disposer is a no-op. The disposer never clobbers a `window[key]` that
  * something else has since reassigned.
  */
 export function exposeOnMainWorld(key, value) {
-    let fellBack = false;
-    try {
-        contextBridge.exposeInMainWorld(key, value);
+    let assignedToWindow = false;
+    if (process.contextIsolated) {
+        // Isolated world (main / settings / view-manager host windows): the only
+        // way to reach the renderer's `window` is via contextBridge. Keep the
+        // defensive fallback + warn for the genuinely-unexpected failure case.
+        try {
+            contextBridge.exposeInMainWorld(key, value);
+        }
+        catch (err) {
+            console.warn('[devtools/expose] contextBridge.exposeInMainWorld failed, falling back to direct window assignment:', err);
+            window[key] = value;
+            assignedToWindow = true;
+        }
     }
-    catch (err) {
-        console.warn('[devtools/expose] contextBridge.exposeInMainWorld failed, falling back to direct window assignment:', err);
+    else {
+        // Context isolation off (simulator <webview>, render-host, service-host):
+        // contextBridge is unusable here and would always throw, so assign the
+        // preload realm's `window` directly without the noisy failed attempt.
+        ;
         window[key] = value;
-        fellBack = true;
+        assignedToWindow = true;
     }
     return () => {
-        if (!fellBack)
+        if (!assignedToWindow)
             return;
         const w = window;
         if (w[key] === value)

package/dist/preload/shared/sid-registry.d.ts

@@ -0,0 +1,11 @@
+export interface WxmlNode {
+    tagName: string;
+    attrs: Record<string, string>;
+    children: WxmlNode[];
+    text?: string;
+    sid?: string;
+}
+export declare const SYNTHETIC_SID_PREFIX = "devtools-";
+export declare function registerSyntheticSid(el: HTMLElement): string;
+export declare function findElementBySid(doc: Document, sid: string): HTMLElement | null;
+//# sourceMappingURL=sid-registry.d.ts.map

package/dist/preload/shared/sid-registry.js

@@ -0,0 +1,38 @@
+// Stable-id registry for WXML nodes, shared by the iframe-path extractor
+// (preload/instrumentation/wxml-extract + runtime/bridge) and the native-host
+// render-guest inspector (render-host/render-inspect). It is dependency-free so
+// the render-inspect bundle injected into the guest main world stays small and
+// doesn't drag in the iframe/exposeOnMainWorld machinery from runtime/bridge.
+// 合成 sid 注册表：用 WeakMap 把元素 ↔ sid 双向绑定，避免在源 DOM 上写
+// `data-*` 属性（提取本应只读，且属性形式会污染用户的快照/选择器）。
+// elBySyntheticSid 为反向查找用 WeakRef，元素被 GC 后下次 lookup 自动清理。
+export const SYNTHETIC_SID_PREFIX = 'devtools-';
+const syntheticSidByEl = new WeakMap();
+const elBySyntheticSid = new Map();
+let nextSyntheticSid = 1;
+export function registerSyntheticSid(el) {
+    const existing = syntheticSidByEl.get(el);
+    if (existing)
+        return existing;
+    const synthetic = `${SYNTHETIC_SID_PREFIX}${nextSyntheticSid++}`;
+    syntheticSidByEl.set(el, synthetic);
+    elBySyntheticSid.set(synthetic, new WeakRef(el));
+    return synthetic;
+}
+export function findElementBySid(doc, sid) {
+    if (sid.startsWith(SYNTHETIC_SID_PREFIX)) {
+        const ref = elBySyntheticSid.get(sid);
+        if (!ref)
+            return null;
+        const el = ref.deref();
+        if (!el || !el.isConnected) {
+            elBySyntheticSid.delete(sid);
+            return null;
+        }
+        if (el.ownerDocument !== doc)
+            return null;
+        return el;
+    }
+    return doc.querySelector(`[data-sid="${CSS.escape(sid)}"]`);
+}
+//# sourceMappingURL=sid-registry.js.map