@dimina-kit/devtools 0.4.0-dev.20260701083540 → 0.4.0-dev.20260702145840

package/dist/main/services/automation/wait-active-page.d.ts

@@ -22,9 +22,11 @@
  *   - Resolve exactly once; later events are inert and the subscription is torn
  *     down on resolve.
  */
-/** The render-event shape `waitForActivePage` reads (subset of `RenderEvent`). */
+/** The render-event shape `waitForActivePage` reads (subset of `RenderEvent`).
+ * Only `activePage` events end the wait; other kinds (`domReady`/`domMutated`)
+ * are inert but included so a full `RenderEvent` is assignable here. */
 export interface ActivePageEventLike {
-    kind: 'domReady' | 'activePage';
+    kind: 'domReady' | 'activePage' | 'domMutated';
     appId: string;
     bridgeId: string;
     pagePath?: string;

package/dist/main/services/elements-forward/index.js

@@ -49,6 +49,7 @@
  * hook + dispatch scripts) as self-contained code.
  */
 import { webContents as electronWebContents } from 'electron';
+import { isFrontendSettled } from '../views/inject-when-ready.js';
 /**
  * CDP domains that target the RENDER GUEST'S document tree. A command in one of
  * these is intercepted and sent to the active render guest's debugger instead of
@@ -274,6 +275,12 @@ export function installElementsForward(deps) {
     function dispatchToFrontend(message) {
         if (disposed || devtoolsWc.isDestroyed())
             return;
+        // Unified settled gate (same predicate as the reconcile tick): an unsettled
+        // front-end wipes its state on load anyway, so the message is meaningless
+        // there — and the executeJavaScript would queue one did-stop-loading waiter
+        // per push (an activePage burst piles them). The post-settle tick re-primes.
+        if (!isFrontendSettled(devtoolsWc))
+            return;
         let json;
         try {
             json = JSON.stringify(message);
@@ -309,6 +316,10 @@ export function installElementsForward(deps) {
     function pushDocumentUpdated() {
         if (disposed || devtoolsWc.isDestroyed())
             return;
+        // Same unified settled gate as dispatchToFrontend — render events (the
+        // activePage burst) drive this during churn.
+        if (!isFrontendSettled(devtoolsWc))
+            return;
         let script;
         try {
             script = buildDocumentUpdatedScript();
@@ -594,6 +605,14 @@ export function installElementsForward(deps) {
                 stop();
                 return;
             }
+            // An unsettled front-end can't run the script anyway, and executeJavaScript
+            // against it queues one did-stop-loading waiter PER TICK on the emitter
+            // (150ms × a seconds-long reload piles past the MaxListeners ceiling).
+            // MUST be the shared Electron-aligned predicate — a bare isLoading()
+            // probe diverges from Electron's internal isLoadingMainFrame gate and
+            // keeps piling. Skip; the first post-settle tick re-establishes the hook.
+            if (!isFrontendSettled(devtoolsWc))
+                return;
             devtoolsWc
                 .executeJavaScript(buildReconcileScript())
                 .then((res) => {

package/dist/main/services/network-forward/index.js

@@ -1,4 +1,5 @@
 import { DisposableRegistry, toDisposable } from '@dimina-kit/electron-deck/main';
+import { isFrontendSettled } from '../views/inject-when-ready.js';
 // ── requestId namespacing (pure, testable) ──────────────────────────────────
 /**
  * CDP events whose `params.requestId` we rewrite into the virtual namespace.
@@ -359,6 +360,18 @@ export function createNetworkForwarder(bridge) {
             trimQueue();
             return;
         }
+        if (!isFrontendSettled(wc)) {
+            // An unsettled front-end can't run the dispatch script anyway — and every
+            // executeJavaScript against it queues one did-stop-loading waiter on the
+            // emitter, so a relaunch's network burst piles them past the MaxListeners
+            // ceiling. MUST be the shared Electron-aligned predicate (a bare
+            // isLoading() probe diverges from the internal isLoadingMainFrame gate).
+            // Hold the (bounded) queue; the next event's flush or the ready-retry
+            // delivers after the load.
+            trimQueue();
+            scheduleReadyRetry();
+            return;
+        }
         if (sink === 'idle')
             beginProbing();
         // Pack greedily up to MAX_BATCH_CHARS so one executeJavaScript stays sized;

package/dist/main/services/render-inspect/index.d.ts

@@ -24,6 +24,15 @@ export interface RenderInspector {
     highlight(wc: WebContents, sid: string): Promise<ElementInspection | null>;
     /** Clear any highlight overlay in the guest. */
     unhighlight(wc: WebContents): Promise<void>;
+    /**
+     * Toggle the guest-side WXML MutationObserver. When on, the injected IIFE
+     * watches `document.body` and posts a debounced `wxmlChanged` over
+     * `DiminaRenderBridge` on every DOM mutation (setData), which bridge-router
+     * turns into a `domMutated` render event so the WXML panel re-pulls. Only
+     * enabled while the WXML panel is visible, so an unseen panel never drives a
+     * full Vue-tree walk. Injects the IIFE first if needed; no-op on a dead guest.
+     */
+    setWxmlObserving(wc: WebContents, on: boolean): Promise<void>;
 }
 export interface RenderInspectorOptions {
     /** Override the injected IIFE source (default: read the built bundle). Test seam. */

package/dist/main/services/render-inspect/index.js

@@ -259,6 +259,18 @@ export function createRenderInspector(options = {}) {
             // best-effort
         }
     }
-    return { getWxml, highlight, unhighlight };
+    async function setWxmlObserving(wc, on) {
+        if (wc.isDestroyed())
+            return;
+        if (!(await ensureInjected(wc)))
+            return;
+        try {
+            await wc.executeJavaScript(`window.__diminaRenderInspect && window.__diminaRenderInspect.setWxmlObserving(${on ? 'true' : 'false'})`);
+        }
+        catch {
+            // best-effort: a guest mid-teardown just stops observing on its own.
+        }
+    }
+    return { getWxml, highlight, unhighlight, setWxmlObserving };
 }
 //# sourceMappingURL=index.js.map

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

@@ -15,6 +15,7 @@
  */
 import { type WebContents } from 'electron';
 import { type ConnectionRegistry, type Disposable } from '@dimina-kit/electron-deck/main';
+import { type SyncStorageChange } from '../../../shared/ipc-channels.js';
 import { type SenderPolicy } from '../../utils/ipc-registry.js';
 import type { BridgeRouterHandle } from '../../ipc/bridge-router.js';
 import type { RenderInspector } from '../render-inspect/index.js';
@@ -34,6 +35,14 @@ export declare const STORAGE_API_NAMES: Set<string>;
 export interface SimulatorStorageHandle extends Disposable {
     /** Present only under native-host; wired to ctx.storageApi for bridge-router. */
     storageApi: StorageApi | null;
+    /**
+     * Native-host SYNC-storage liveness: bridge-router calls this on each
+     * `storageChanged` container message the service-host posts after a
+     * `setStorageSync`/`removeStorageSync`/`clearStorageSync`. Those write the
+     * service-host `localStorage` directly (bypassing main), so they'd otherwise
+     * leave the panel stale until reload — this pushes the matching `StorageEvent`.
+     */
+    onSyncStorageChange(appId: string, change: SyncStorageChange): void;
 }
 export interface SimulatorStorageOptions {
     /**

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

@@ -573,7 +573,32 @@ export function setupSimulatorStorage(host, options) {
     const storageApi = options.bridge?.isNativeHost()
         ? { invoke: runtimeInvoke }
         : null;
-    return { dispose: () => registry.dispose(), storageApi };
+    /**
+     * SYNC wx storage APIs run inside the service-host window and write
+     * `localStorage` directly, so they never reach `setItem`/`runtimeInvoke` here.
+     * The service-host posts the change over `DiminaServiceBridge` and bridge-router
+     * routes it here so the panel stays live. Only the ACTIVE app's changes are
+     * surfaced (the panel shows one app); the key already carries the `${appId}_`
+     * prefix, matching the CDP / async event shape.
+     */
+    function onSyncStorageChange(appId, change) {
+        if (appId !== getActiveAppId())
+            return;
+        if (host.isDestroyed())
+            return;
+        switch (change.op) {
+            case 'set':
+                pushSyntheticEvent({ type: 'added', key: change.key, newValue: change.value });
+                break;
+            case 'remove':
+                pushSyntheticEvent({ type: 'removed', key: change.key });
+                break;
+            case 'clear':
+                host.send(SimulatorStorageChannel.Event, { type: 'cleared' });
+                break;
+        }
+    }
+    return { dispose: () => registry.dispose(), storageApi, onSyncStorageChange };
 }
 // Element inspection delegates to the simulator preload's __simulatorData
 // bridge via executeJavaScript. Looked up independently from `attachedWc` so

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

@@ -4,25 +4,131 @@ import { IpcRegistry } from '../../utils/ipc-registry.js';
 export function setupSimulatorWxml(host, options) {
     const { bridge, inspector, getActiveAppId } = options;
     const registry = new DisposableRegistry();
-    /** Read the WXML tree of the visible page of the active app, or null. */
-    async function pull() {
-        const wc = bridge.getActiveRenderWc(getActiveAppId() ?? undefined);
+    // Whether the WXML panel is currently visible (renderer drives this via
+    // SetActive). Live tree pushes + the render-guest DOM observer only run while
+    // active, so an unseen panel never triggers a full Vue-tree walk.
+    let active = false;
+    // latest-wins: only the newest pull's result is pushed (a slow walk that
+    // resolves after a newer one must not clobber the fresher tree).
+    let seq = 0;
+    // in-flight coalescing: at most one pull runs at a time; a request that lands
+    // mid-pull sets `again` so exactly one follow-up pull runs after it settles.
+    let pulling = false;
+    let again = false;
+    // The render guest currently being observed, so we can stop it on page change
+    // / deactivation (single owner).
+    let observedWc = null;
+    /** The visible page's render WebContents of the active app, or null. */
+    function activeWc() {
+        return bridge.getActiveRenderWc(getActiveAppId() ?? undefined);
+    }
+    /** Read the WXML tree of a render guest, or null when there is none. */
+    async function pull(wc) {
         if (!wc)
             return null;
         return inspector.getWxml(wc);
     }
+    /**
+     * Pull the active tree and push it, gated by `active` and reconciled by
+     * latest-wins + in-flight coalescing so a burst of render events (setData)
+     * collapses to a single fresh push instead of a pile of overlapping walks.
+     */
+    function schedulePull() {
+        if (!active)
+            return;
+        const mySeq = ++seq;
+        if (pulling) {
+            again = true;
+            return;
+        }
+        pulling = true;
+        void pull(activeWc())
+            .then((tree) => {
+            // Re-check `active` at send time: a pull started while visible must NOT
+            // push after the panel was hidden / disposed (deactivate bumps `seq`, so
+            // `mySeq === seq` also guards, but the explicit `active` check is the
+            // clear invariant).
+            if (mySeq === seq && active && !host.isDestroyed()) {
+                host.send(SimulatorWxmlChannel.Event, tree);
+            }
+        })
+            .finally(() => {
+            pulling = false;
+            if (again) {
+                again = false;
+                schedulePull();
+            }
+        });
+    }
+    function startObserving(wc) {
+        if (!wc)
+            return;
+        observedWc = wc;
+        // The guest IIFE defers observe() until document.body exists, so a wc whose
+        // DOM isn't up yet still starts observing once it loads — no retry needed here.
+        void inspector.setWxmlObserving(wc, true);
+    }
+    function stopObserving() {
+        const wc = observedWc;
+        observedWc = null;
+        if (wc)
+            void inspector.setWxmlObserving(wc, false);
+    }
+    /**
+     * Point the DOM observer at the CURRENT active render guest. Called on every
+     * render event while active, so the observer installs even when SetActive fired
+     * before the guest existed (the guest appears on `domReady`) and follows the
+     * active page across navigation (`activePage`).
+     */
+    function reconcileObserving() {
+        if (!active)
+            return;
+        const wc = activeWc();
+        if (wc !== observedWc) {
+            stopObserving();
+            startObserving(wc);
+        }
+    }
+    /** Invalidate any in-flight pull + queued re-pull so nothing pushes post-hide. */
+    function cancelPending() {
+        seq++;
+        again = false;
+    }
     const ipc = new IpcRegistry(options.senderPolicy);
-    ipc.handle(SimulatorWxmlChannel.GetSnapshot, () => pull());
+    ipc.handle(SimulatorWxmlChannel.GetSnapshot, () => pull(activeWc()));
+    ipc.handle(SimulatorWxmlChannel.SetActive, (_event, on) => {
+        if (on) {
+            active = true;
+            reconcileObserving();
+            schedulePull(); // seed the now-visible panel
+        }
+        else {
+            active = false;
+            cancelPending();
+            stopObserving();
+        }
+    });
     registry.add(ipc);
-    // Re-read + push when a page's DOM mounts or the visible page changes.
-    const unsubscribe = bridge.onRenderEvent(() => {
-        void pull().then((tree) => {
-            if (host.isDestroyed())
-                return;
-            host.send(SimulatorWxmlChannel.Event, tree);
-        });
+    // Re-read + push on render-side activity: a page's DOM mounted (`domReady`),
+    // the visible page changed (`activePage`), or the active page's DOM mutated in
+    // place (`domMutated`, from the render-guest observer). Gated by `active` and
+    // scoped to the ACTIVE app so a background app's / stale bridge's event never
+    // drives a spurious full walk of the visible page.
+    const unsubscribe = bridge.onRenderEvent((event) => {
+        if (!active)
+            return;
+        const appId = getActiveAppId();
+        if (appId && event.appId !== appId)
+            return;
+        // domReady: the guest may have just appeared → (re)install the observer.
+        // activePage: the active guest changed → move the observer.
+        // domMutated: same guest → reconcile is a no-op, then pull.
+        reconcileObserving();
+        schedulePull();
     });
     registry.add(unsubscribe);
+    // Stop observing + invalidate in-flight pulls on teardown (best-effort).
+    registry.add(() => { active = false; cancelPending(); stopObserving(); });
     return registry;
 }
 //# sourceMappingURL=index.js.map

package/dist/main/services/views/apply-view-ops.d.ts

@@ -0,0 +1,11 @@
+import type { Bounds, ViewOp } from '@dimina-kit/electron-deck/layout';
+import type { DevtoolsExtra } from '../../../shared/view-ids.js';
+export interface ViewOpTarget {
+    attach(viewId: string): void;
+    detach(viewId: string): void;
+    setBounds(viewId: string, bounds: Bounds, extra?: DevtoolsExtra): void;
+    setVisible(viewId: string, visible: boolean): void;
+    reorder(order: string[]): void;
+}
+export declare function applyViewOps(ops: ViewOp<DevtoolsExtra>[], target: ViewOpTarget): void;
+//# sourceMappingURL=apply-view-ops.d.ts.map

package/dist/main/services/views/apply-view-ops.js

@@ -0,0 +1,22 @@
+export function applyViewOps(ops, target) {
+    for (const op of ops) {
+        switch (op.kind) {
+            case 'detach':
+                target.detach(op.viewId);
+                break;
+            case 'setVisible':
+                target.setVisible(op.viewId, op.visible);
+                break;
+            case 'setBounds':
+                target.setBounds(op.viewId, op.bounds, op.extra);
+                break;
+            case 'attach':
+                target.attach(op.viewId);
+                break;
+            case 'reorder':
+                target.reorder(op.order);
+                break;
+        }
+    }
+}
+//# sourceMappingURL=apply-view-ops.js.map

package/dist/main/services/views/destroy-child-view.d.ts

@@ -0,0 +1,9 @@
+import type { BrowserWindow, WebContentsView } from 'electron';
+/**
+ * Detach a child overlay WebContentsView from the main window's contentView and
+ * close its webContents. Tolerates an already-removed view and a destroyed
+ * webContents (best-effort teardown). The single low-level view-destroy path
+ * shared by every overlay domain.
+ */
+export declare function destroyChildView(mainWindow: BrowserWindow, view: WebContentsView | null): void;
+//# sourceMappingURL=destroy-child-view.d.ts.map

package/dist/main/services/views/destroy-child-view.js

@@ -0,0 +1,23 @@
+/**
+ * Detach a child overlay WebContentsView from the main window's contentView and
+ * close its webContents. Tolerates an already-removed view and a destroyed
+ * webContents (best-effort teardown). The single low-level view-destroy path
+ * shared by every overlay domain.
+ */
+export function destroyChildView(mainWindow, view) {
+    if (!view)
+        return;
+    if (!mainWindow.isDestroyed()) {
+        try {
+            mainWindow.contentView.removeChildView(view);
+        }
+        catch { /* already removed */ }
+    }
+    try {
+        if (!view.webContents.isDestroyed()) {
+            view.webContents.close();
+        }
+    }
+    catch { /* ignore */ }
+}
+//# sourceMappingURL=destroy-child-view.js.map

package/dist/main/services/views/host-toolbar-view.d.ts

@@ -0,0 +1,21 @@
+import type { PlacementReconciler } from './placement-reconciler.js';
+import type { HostToolbarControl, ViewManagerContext } from './view-manager.js';
+/**
+ * A strip above the devtools header that the downstream host loads its own
+ * content into and fully controls. Bounds come from a renderer DOM anchor
+ * (forward anchor, like the simulator DevTools overlay); its height is dynamic
+ * via a reverse size-advertiser the toolbar's own renderer drives.
+ */
+export interface HostToolbarView {
+    readonly control: HostToolbarControl;
+    setHostToolbarHeight(extent: number): void;
+    getHostToolbarHeight(): number;
+    getHostToolbarWebContentsId(): number | null;
+    /** Teardown for `disposeAll`: sweep the port, destroy the view, release the runtime ref. */
+    dispose(): void;
+}
+export declare function createHostToolbarView(ctx: ViewManagerContext, reconciler: PlacementReconciler, deps: {
+    /** Re-apply the settings/popover overlays whose height depends on the toolbar strip. */
+    reapplyPresentOverlays(): void;
+}): HostToolbarView;
+//# sourceMappingURL=host-toolbar-view.d.ts.map