@dimina-kit/devtools 0.4.0-dev.20260717120050 → 0.4.0-dev.20260718085557

package/dist/main/services/cdp-session/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared `wc.debugger` (CDP) session broker for render-host guest WebContents.
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────
+ * `webContents.debugger` is exclusive per wc (only one `attach()` owner at a
+ * time). Four independent modules — safe-area, elements-forward, render-inspect
+ * and network-forward — each hand-roll the same "reuse if already attached,
+ * self-attach only if nobody has, track what I self-attached so I only detach
+ * my own" bookkeeping, and each installs its OWN `wc.debugger.on('message', …)`
+ * listener. That duplication caused two real bugs:
+ *
+ *  1. network-forward's `attachRenderGuest` runs ONCE per guest (at webview
+ *     creation). If some OTHER module later detaches the shared session it
+ *     happened to self-attach, network-forward's capture dies permanently —
+ *     nothing re-attaches it (unlike safe-area/elements-forward/render-inspect,
+ *     which lazily re-`ensure` the debugger on every use and so self-heal).
+ *  2. On the simulator wc, two modules each do "detach if attached" with no
+ *     notion of the other — whichever runs last steals the other's session.
+ *
+ * This broker is the single owner of "who attached, who may detach": callers
+ * `acquire(wc)` a lease instead of touching `wc.debugger` directly. A session's
+ * lifetime tracks the wc, not any one lease — the last lease releasing does
+ * NOT detach (another consumer may `acquire` again at any time); only the
+ * broker's own top-level `dispose()` detaches sessions IT self-attached. An
+ * external detach (another owner, or a real Chrome DevTools window stealing the
+ * session) notifies every lease's `onDetach` and drops the session's
+ * bookkeeping so the NEXT `acquire()` attaches from scratch — closing bug #1
+ * structurally instead of requiring every consumer to remember to re-ensure.
+ */
+import type { WebContents } from 'electron';
+import type { ConnectionRegistry, Disposable } from '@dimina-kit/electron-deck/main';
+export interface CdpSessionLease {
+    /** Send one CDP command on this wc's session. Rejects if the session/wc is gone. */
+    send(method: string, params?: object): Promise<unknown>;
+    /**
+     * Subscribe to every CDP `message` event this session receives. Multiple
+     * leases (from the same or different `acquire()` calls) share ONE real
+     * `wc.debugger.on('message', …)` listener, fanned out to every subscriber.
+     */
+    onMessage(cb: (method: string, params: unknown) => void): Disposable;
+    /**
+     * Subscribe to this session becoming unusable for any reason OTHER than the
+     * broker's own top-level `dispose()`: an external detach (another owner
+     * releasing it, or a real Chrome DevTools window stealing it) OR the wc
+     * itself being destroyed. Either way the broker has already dropped its
+     * bookkeeping for this session by the time this fires — a consumer that
+     * caches its lease should drop the cache entry here so its NEXT `acquire()`
+     * gets a fresh one instead of operating on a dead lease. The broker's own
+     * `dispose()` detaching a session it self-attached does NOT fire this: that
+     * is an intentional, expected teardown, not a surprise the caller needs to
+     * react to.
+     */
+    onDetach(cb: () => void): Disposable;
+    /**
+     * Enable DOM + CSS + Overlay (the render-inspection domains) once per
+     * session, in dependency order (`Overlay.enable` must follow `DOM.enable`'s
+     * resolution — Chromium rejects it otherwise; `CSS.enable` has no such
+     * dependency). Memoized PER SESSION (not per lease): concurrent callers on
+     * the same wc share one in-flight/completed handshake. Invalidated on any
+     * detach (self or external) so a later session re-runs it fresh.
+     */
+    ensureRenderDomains(): Promise<void>;
+    /**
+     * Release every subscription THIS lease registered via `onMessage`/
+     * `onDetach`. Idempotent. Never detaches the underlying session — that
+     * follows the wc's lifetime, not any one lease's.
+     */
+    dispose(): void;
+}
+export interface CdpSessionBroker {
+    /**
+     * Get-or-create a lease for `wc`'s debugger session. Returns `null` when the
+     * wc is already destroyed, or when the debugger is exclusively held
+     * elsewhere and unavailable to attach (e.g. a real Chrome DevTools window).
+     */
+    acquire(wc: WebContents): CdpSessionLease | null;
+    /**
+     * Project-level teardown: detach every session this broker itself
+     * self-attached (never one it merely reused). Sessions owned by someone
+     * else are left untouched.
+     */
+    dispose(): void;
+}
+export declare function createCdpSessionBroker(opts?: {
+    connections?: ConnectionRegistry;
+}): CdpSessionBroker;
+//# sourceMappingURL=index.d.ts.map

package/dist/main/services/cdp-session/index.js

@@ -0,0 +1,173 @@
+export function createCdpSessionBroker(opts = {}) {
+    const sessions = new Map();
+    function removeDebuggerListeners(session) {
+        try {
+            session.wc.debugger.removeListener('message', session.onDbgMessage);
+        }
+        catch { /* wc gone */ }
+        try {
+            session.wc.debugger.removeListener('detach', session.onDbgDetach);
+        }
+        catch { /* wc gone */ }
+    }
+    function notifyDetach(session) {
+        for (const cb of [...session.detachSubs]) {
+            try {
+                cb();
+            }
+            catch { /* subscriber error is not our problem */ }
+        }
+    }
+    function ensureSession(wc) {
+        const existing = sessions.get(wc);
+        if (existing)
+            return existing;
+        let selfAttached = false;
+        try {
+            if (!wc.debugger.isAttached()) {
+                wc.debugger.attach('1.3');
+                selfAttached = true;
+            }
+        }
+        catch {
+            // Exclusively held elsewhere (e.g. a real Chrome DevTools window) and
+            // refused to share — degrade to "unavailable", same as every existing
+            // per-module implementation this broker replaces.
+            return null;
+        }
+        const session = {
+            wc,
+            selfAttached,
+            selfDetaching: false,
+            messageSubs: new Set(),
+            detachSubs: new Set(),
+            enablePromise: null,
+            onDbgMessage: (...args) => {
+                const [, method, params] = args;
+                for (const cb of [...session.messageSubs])
+                    cb(method, params);
+            },
+            onDbgDetach: () => {
+                const wasSelfInitiated = session.selfDetaching;
+                session.selfDetaching = false;
+                session.enablePromise = null;
+                sessions.delete(wc);
+                removeDebuggerListeners(session);
+                try {
+                    session.destroyedSub?.dispose();
+                }
+                catch { /* already gone */ }
+                if (!wasSelfInitiated)
+                    notifyDetach(session);
+            },
+            onWcDestroyed: () => {
+                sessions.delete(wc);
+                removeDebuggerListeners(session);
+                // Deliberately does NOT call wc.debugger.detach(), even for a
+                // self-attached session: a destroyed wc's debugger is torn down by
+                // Electron itself, there is nothing left for us to usefully detach,
+                // and attempting it is an unnecessary risk (the underlying native
+                // objects may already be gone). Dropping our bookkeeping is enough.
+                // Not a broker-initiated detach — same "your lease is dead, re-acquire
+                // next time" signal as an external debugger detach, just for a
+                // different reason (the wc itself is gone, not merely the session).
+                notifyDetach(session);
+            },
+        };
+        wc.debugger.on('message', session.onDbgMessage);
+        wc.debugger.on('detach', session.onDbgDetach);
+        if (opts.connections) {
+            session.destroyedSub = opts.connections.acquire(wc).on('closed', session.onWcDestroyed);
+        }
+        else {
+            try {
+                wc.once('destroyed', session.onWcDestroyed);
+            }
+            catch { /* fake/minimal wc */ }
+        }
+        sessions.set(wc, session);
+        return session;
+    }
+    function ensureRenderDomains(session) {
+        if (session.enablePromise)
+            return session.enablePromise;
+        session.wc.debugger.sendCommand('CSS.enable').catch(() => { });
+        const p = session.wc.debugger
+            .sendCommand('DOM.enable')
+            .then(() => session.wc.debugger.sendCommand('Overlay.enable'))
+            .then(() => undefined)
+            .catch(() => {
+            // Guest mid-teardown or domain unavailable — drop the memo so a later
+            // call (e.g. after the session recovers) can retry instead of being
+            // stuck on a permanently-failed handshake.
+            session.enablePromise = null;
+        });
+        session.enablePromise = p;
+        return p;
+    }
+    function createLease(session) {
+        const ownMessageSubs = new Set();
+        const ownDetachSubs = new Set();
+        return {
+            // Echo the caller's exact arity through to sendCommand — a caller that
+            // omits params (many CDP commands take none, e.g. 'Network.enable')
+            // gets the identical call Electron's own API expects, not a synthetic
+            // `{}` second argument.
+            send: (method, params) => params === undefined
+                ? session.wc.debugger.sendCommand(method)
+                : session.wc.debugger.sendCommand(method, params),
+            onMessage: (cb) => {
+                session.messageSubs.add(cb);
+                ownMessageSubs.add(cb);
+                return { dispose: () => { session.messageSubs.delete(cb); ownMessageSubs.delete(cb); } };
+            },
+            onDetach: (cb) => {
+                session.detachSubs.add(cb);
+                ownDetachSubs.add(cb);
+                return { dispose: () => { session.detachSubs.delete(cb); ownDetachSubs.delete(cb); } };
+            },
+            ensureRenderDomains: () => ensureRenderDomains(session),
+            dispose: () => {
+                for (const cb of ownMessageSubs)
+                    session.messageSubs.delete(cb);
+                for (const cb of ownDetachSubs)
+                    session.detachSubs.delete(cb);
+                ownMessageSubs.clear();
+                ownDetachSubs.clear();
+            },
+        };
+    }
+    return {
+        acquire(wc) {
+            if (wc.isDestroyed())
+                return null;
+            const session = ensureSession(wc);
+            if (!session)
+                return null;
+            return createLease(session);
+        },
+        dispose() {
+            for (const session of [...sessions.values()]) {
+                if (session.selfAttached) {
+                    session.selfDetaching = true;
+                    try {
+                        if (!session.wc.isDestroyed() && session.wc.debugger.isAttached()) {
+                            session.wc.debugger.detach();
+                        }
+                    }
+                    catch { /* already detached / destroyed */ }
+                }
+                // Whether detach ran above (which already self-cleans via onDbgDetach)
+                // or this session was externally-owned (never touched), make sure
+                // broker-side bookkeeping is gone either way.
+                sessions.delete(session.wc);
+                removeDebuggerListeners(session);
+                try {
+                    session.destroyedSub?.dispose();
+                }
+                catch { /* already gone */ }
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/main/services/elements-forward/index.d.ts

@@ -1,8 +1,82 @@
+/**
+ * Elements-panel forwarding — reflect the ACTIVE RENDER GUEST's live DOM tree in
+ * the right-panel Chrome DevTools front-end, which natively inspects the
+ * service-host (logic layer).
+ *
+ * ── Mechanism (no preload) ───────────────────────────────────────────────────
+ * The DevTools front-end is a `devtools://` page with NO dimina preload, so we
+ * drive it through the same two-way poll bridge the network-forward path uses:
+ *   • front-end → main : we wrap `InspectorFrontendHost.sendMessageToBackend` in
+ *     the front-end realm — the ONE outbound CDP gate every injected-panel
+ *     feature routes through (`routeOutboundCommand` is the single decision
+ *     table). Commands whose method is in the RENDER domain set
+ *     (DOM/CSS/Overlay/DOMSnapshot/DOMDebugger), plus `Network.getResponseBody`
+ *     / `Network.getRequestPostData` for `dimina:sim:` virtual requestIds
+ *     (which only the network forwarder's prefetch cache can answer — the
+ *     natively-inspected service host has never heard of them), are NOT passed
+ *     to the original embedder channel — they're pushed onto
+ *     `globalThis.__diminaElementsOutbound` tagged with their route and main
+ *     drains that array (splice) on a poll. EVERY OTHER method
+ *     (Runtime/Console/Page/Target/Emulation/…) calls through to the original, so
+ *     the service-host inspection (Console, Sources) and crucially the safe-area
+ *     `Emulation.setSafeAreaInsetsOverride` are untouched.
+ *   • main → front-end : we re-inject responses + render-side EVENTS via
+ *     `window.DevToolsAPI.dispatchMessage(json)` (chunked for large payloads —
+ *     `DOM.getDocument` can be big — mirroring network-forward/index.ts).
+ *
+ * ── Render-guest CDP session (via the shared broker) ─────────────────────────
+ * `webContents.debugger` is single-owner per wc, so this and every other
+ * feature that needs a render guest's session (safe-area, render-inspect,
+ * network-forward) `acquire()` a lease from the shared `CdpSessionBroker`
+ * (see cdp-session/index.ts) instead of each hand-rolling its own attach/
+ * reuse/detach bookkeeping — that duplication used to mean whichever module
+ * happened to attach first was the de facto owner, and any other module's
+ * `detach()` could steal the session out from under the others. The broker is
+ * the single owner of "who attached, who may detach"; `DOM.enable`/
+ * `CSS.enable`/`Overlay.enable` never touch the safe-area `Emulation`
+ * override, so sharing a session this way is purely additive.
+ *
+ * ── Staleness (active-guest, NOT a generation counter) ───────────────────────
+ * A response/event is honoured only while its originating guest is STILL the
+ * active render guest — resolved fresh from the bridge per check (`isActiveWcId`),
+ * not snapshotted. So a late response or stray render EVENT from a guest that is
+ * no longer active is dropped (its in-flight command id is settled with an error
+ * so the front-end never leaks a pending request, and stale nodes never bleed into
+ * the new tree); and switching away and BACK to a previously-wired guest RESUMES
+ * its forwarding (a snapshot would strand it).
+ *
+ * ── Degradation ──────────────────────────────────────────────────────────────
+ * Hook unavailable / `DevToolsAPI` missing / no active guest → routing is simply
+ * inert; the Elements panel falls back to the front-end's native service-host
+ * DOM (the prior behaviour). Everything is try/catch + feature-detect + bounded
+ * polling: it never throws, never blocks, never disturbs Console/Network/safe-area.
+ *
+ * This is a production feature (no env gate, default on for the native simulator).
+ * The routing table (below) is self-contained; the front-end dispatch transport
+ * (`buildChunkedDispatchScript` + its size constants) is shared with
+ * network-forward via `../network-forward/frontend-dispatch.js` so the two
+ * can never drift on the chunk-continuation protocol.
+ */
 import type { WebContents } from 'electron';
 import type { ConnectionRegistry } from '@dimina-kit/electron-deck/main';
 import type { BridgeRouterHandle } from '../../ipc/bridge-router.js';
-/** Which target a front-end CDP command is routed to. */
-export type CdpRoute = 'render' | 'service';
+import { type NetworkBodyProvider } from '../network-forward/index.js';
+import { type CdpSessionBroker } from '../cdp-session/index.js';
+/**
+ * Which target a front-end CDP command is routed to.
+ *  render  — the active render guest's debugger (the Elements tree).
+ *  network — the network forwarder's prefetch cache (body/post-data lookups
+ *            for `dimina:sim:` virtual requestIds that only exist there).
+ *  service — the original embedder channel (the service host the front-end
+ *            natively inspects).
+ */
+export type CdpRoute = 'render' | 'network' | 'service';
+/**
+ * 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
+ * the service host the front-end nominally inspects.
+ */
+export declare const RENDER_DOMAIN_PREFIXES: readonly string[];
 /**
  * Decide where a front-end CDP `method` is routed.
  *
@@ -20,12 +94,33 @@ export type CdpRoute = 'render' | 'service';
 export declare function routeByDomain(method: string): CdpRoute;
 /** True for an event method we re-inject from the render guest into the panel. */
 export declare function isRenderEventMethod(method: string): boolean;
+/**
+ * The Network commands answered from the network forwarder's prefetch cache
+ * when they target a virtual requestId. Only these two: they're the panel's
+ * body/post-data round-trips. Every other Network.* stays on the service path
+ * (a virtual id there errors exactly like an unknown id would — harmless).
+ */
+export declare const NETWORK_BODY_METHODS: readonly string[];
+/**
+ * Full outbound routing decision — the SINGLE authority for where a front-end
+ * CDP command goes. `routeByDomain` covers the method-only render split; this
+ * adds the params-dependent network split. The hook script inlines an
+ * equivalent test driven by the same literals, so the two cannot drift.
+ *
+ * A non-string / missing requestId routes to 'service': only the
+ * `dimina:sim:` namespace is ours to answer, and the real backend is the
+ * correct authority for its own ids.
+ */
+export declare function routeOutboundCommand(method: string, params: unknown): CdpRoute;
 /**
  * The JS injected into the DevTools front-end realm. Idempotent (sentinel guard).
- * Wraps `InspectorFrontendHost.sendMessageToBackend`: a RENDER-domain command is
- * pushed onto `globalThis.__diminaElementsOutbound` (drained by main) and NOT
- * forwarded to the original embedder channel (main answers it from the render
- * guest); every other command calls through to the original (service-host path).
+ * Wraps `InspectorFrontendHost.sendMessageToBackend` — the ONE outbound CDP
+ * gate for every command the front-end emits. A command that routes 'render'
+ * or 'network' (same decision table as {@link routeOutboundCommand}) is pushed
+ * onto `globalThis.__diminaElementsOutbound` tagged with its route and NOT
+ * forwarded to the original embedder channel (main answers it — from the
+ * render guest or the network prefetch cache respectively); every other
+ * command calls through to the original (service-host path).
  *
  * Returns `'installed'` / `'already'` on success, `'partial'` while the embedder
  * global is not yet present (so the caller retries), `'error:…'` on a real fault.
@@ -43,19 +138,41 @@ export interface ElementsForwardDeps {
      */
     appId?: string;
     /**
-     * Optional connection registry. When present, per-webContents teardowns
-     * (the devtools front-end wc's `stop`, and each render guest's `onDestroyed`)
-     * are routed through `connections.acquire(wc).own(cleanup)` so they fire
-     * deterministically on wc destroy / connection reset — replacing the bespoke
-     * `wc.once('destroyed', cleanup)` hook. Optional so existing callers compile
-     * unchanged; absent → the `once('destroyed')` fallback is used.
+     * Optional connection registry. When present, the devtools front-end wc's
+     * own `stop` teardown is routed through `connections.acquire(wc).own(cleanup)`
+     * so it fires deterministically on wc destroy / connection reset — replacing
+     * the bespoke `wc.once('destroyed', cleanup)` hook. Optional so existing
+     * callers compile unchanged; absent → the `once('destroyed')` fallback is
+     * used. Also threaded into the PRIVATE fallback broker (see `broker` below)
+     * when no shared broker is supplied, so that broker's own render-guest
+     * wc-destroy tracking is connection-routed too.
      */
     connections?: ConnectionRegistry;
+    /**
+     * Answers intercepted `Network.getResponseBody` / `Network.getRequestPostData`
+     * lookups for `dimina:sim:` virtual requestIds (the network forwarder's
+     * prefetch cache). Absent → those commands settle with the standard CDP
+     * not-found error, the same answer the mis-routed service-host backend gave.
+     */
+    network?: NetworkBodyProvider;
+    /**
+     * Shared CDP session broker (see cdp-session/index.ts) that owns every
+     * render-guest debugger session's attach/detach lifecycle — safe-area,
+     * render-inspect and network-forward acquire leases from the same instance.
+     * Absent → a private broker is created and owned for this call's lifetime
+     * (torn down on `stop()`), so existing standalone callers/tests compile and
+     * behave unchanged, just without cross-module session sharing.
+     */
+    broker?: CdpSessionBroker;
 }
 /**
- * Install Elements forwarding on a DevTools front-end host wc. Returns a disposer
- * (`stop`) that clears timers, unsubscribes render events, detaches ONLY the
- * debugger sessions this feature attached, and removes every listener it added.
+ * Install Elements forwarding on a DevTools front-end host wc. Returns a
+ * disposer (`stop`) that clears timers, unsubscribes render events, releases
+ * every broker lease this call acquired, and — only when no `deps.broker` was
+ * supplied (this call owns its private broker) — disposes that broker too
+ * (which detaches ONLY the sessions it self-attached). When `deps.broker` IS
+ * supplied (the shared, app-wide instance), `stop()` never disposes it: other
+ * consumers may still be using it.
  *
  * Best-effort + defensive throughout: a destroyed wc ends the feature; every
  * executeJavaScript / sendCommand is wrapped so a torn-down guest never throws