@dimina-kit/devtools 0.4.0 → 0.5.0-dev.20260908120530

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

@@ -1,61 +1,13 @@
-/**
- * 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, no broker) ────────────────────────────────────────
- * 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. Commands whose method is in the RENDER domain set
- *     (DOM/CSS/Overlay/DOMSnapshot/DOMDebugger) are NOT passed to the original
- *     embedder channel — they're pushed onto `globalThis.__diminaElementsOutbound`
- *     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).
- *
- * ── Why no broker / no safe-area changes ─────────────────────────────────────
- * `webContents.debugger` is single-owner per wc, and the safe-area service has
- * already `attach('1.3')`-ed each render guest. We REUSE that already-attached
- * session (`sendCommand` + an extra `on('message')` listener on the SAME
- * `wc.debugger`); we never attach a second session and never detach one we don't
- * own. `DOM.enable`/`CSS.enable`/`Overlay.enable` do not reset the safe-area
- * `Emulation` override, so this is purely additive. ONLY when a guest's debugger
- * is NOT attached (safe-area degraded) do we `attach('1.3')` ourselves — tracked
- * in a `Set<wc.id>` so dispose/guest-destroy detaches ONLY the sessions we own;
- * safe-area's are never touched.
- *
- * ── 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).
- * It deliberately re-implements the small pure helpers it needs (routing table,
- * hook + dispatch scripts) as self-contained code.
- */
-import { webContents as electronWebContents } from 'electron';
 import { isFrontendSettled } from '../views/inject-when-ready.js';
+import { BODY_REQUEST_ID_PREFIXES } from '../network-forward/request-ids.js';
+import { buildSingleDispatchScript, createFrontendReplyChannel, answerNetworkBodyCommand, drainOutboundBatch } from '../network-forward/frontend-dispatch.js';
+import { createCdpSessionBroker } from '../cdp-session/index.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
  * the service host the front-end nominally inspects.
  */
-const RENDER_DOMAIN_PREFIXES = [
+export const RENDER_DOMAIN_PREFIXES = [
     'DOM.',
     'CSS.',
     'Overlay.',
@@ -87,40 +39,89 @@ export function routeByDomain(method) {
 export function isRenderEventMethod(method) {
     return routeByDomain(method) === 'render';
 }
+/**
+ * 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 const NETWORK_BODY_METHODS = [
+    'Network.getResponseBody',
+    'Network.getRequestPostData',
+];
+/**
+ * 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
+ * simulator and native HTTP namespaces is ours to answer, and the real backend is the
+ * correct authority for its own ids.
+ */
+export function routeOutboundCommand(method, params) {
+    if (routeByDomain(method) === 'render')
+        return 'render';
+    if (NETWORK_BODY_METHODS.includes(method)) {
+        const requestId = params?.requestId;
+        if (typeof requestId === 'string' && BODY_REQUEST_ID_PREFIXES.some((prefix) => requestId.startsWith(prefix))) {
+            return 'network';
+        }
+    }
+    return 'service';
+}
 // ── front-end injection (the front-end → main half of the bridge) ────────────
 /**
  * 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.
  */
 export function buildElementsHookScript() {
     const prefixes = JSON.stringify(RENDER_DOMAIN_PREFIXES);
+    const netMethods = JSON.stringify(NETWORK_BODY_METHODS);
+    const vprefix = JSON.stringify(BODY_REQUEST_ID_PREFIXES);
     return `(function(){try{
     if (globalThis.__diminaElementsHookInstalled) return 'already';
     var OUT = (globalThis.__diminaElementsOutbound = globalThis.__diminaElementsOutbound || []);
     var PREFIXES = ${prefixes};
+    var NET_METHODS = ${netMethods};
+    var VPREFIXES = ${vprefix};
     function isRender(method){
       if (!method) return false;
       for (var i=0;i<PREFIXES.length;i++){ if (method.indexOf(PREFIXES[i])===0) return true; }
       return false;
     }
+    function routeOf(m){
+      if (!m || !m.method) return 'service';
+      if (isRender(m.method)) return 'render';
+      if (NET_METHODS.indexOf(m.method) >= 0 && m.params
+          && typeof m.params.requestId === 'string'
+          && VPREFIXES.some(function(prefix){ return m.params.requestId.indexOf(prefix) === 0; })) return 'network';
+      return 'service';
+    }
     var IFH = globalThis.InspectorFrontendHost;
     if (IFH && typeof IFH.sendMessageToBackend === 'function' && !IFH.__diminaElementsWrapped){
       var origSend = IFH.sendMessageToBackend.bind(IFH);
       IFH.sendMessageToBackend = function(message){
         try {
           var m = (typeof message === 'string') ? JSON.parse(message) : message;
-          if (m && isRender(m.method)){
-            // Intercept: hand it to main to route at the render guest. Do NOT
-            // call the original embedder channel (would hit the service host).
+          var route = routeOf(m);
+          if (route !== 'service'){
+            // Intercept: hand it to main to answer (render guest / network
+            // cache). Do NOT call the original embedder channel — the service
+            // host either has the wrong tree or has never heard of the id.
             OUT.push({ id: (m && typeof m.id === 'number') ? m.id : null,
               method: m.method, params: m.params || {},
-              sessionId: (m && m.sessionId) ? m.sessionId : null });
+              sessionId: (m && m.sessionId) ? m.sessionId : null,
+              route: route });
             return;
           }
         } catch(_){ /* fall through to original on any parse hiccup */ }
@@ -151,53 +152,24 @@ function buildReconcileScript() {
         + `return { status: status, batch: batch };`
         + `})()`;
 }
-// ── main → front-end dispatch (mirrored from network-forward/index.ts) ────────
-// network-forward keeps these file-private and the task forbids touching it, so
-// they're re-implemented here. Keep the chunk contract in sync if that changes.
-const PROBE_DEVTOOLS_API = `(window.DevToolsAPI && typeof window.DevToolsAPI.dispatchMessage === 'function')`;
-/** A single dispatch payload may not exceed this many UTF-16 chars; chunk above. */
-const MAX_SINGLE_DISPATCH_CHARS = 1_000_000;
-const CHUNK_CHARS = 256 * 1024;
-/** Dispatch ONE small CDP message (response or event) into the front-end. */
-function buildDispatchScript(message) {
-    return `(()=>{try{`
-        + `if(!${PROBE_DEVTOOLS_API})return false;`
-        + `window.DevToolsAPI.dispatchMessage(JSON.parse(${JSON.stringify(message)}));`
-        + `return true;`
-        + `}catch(_){return false}})()`;
-}
-/**
- * Dispatch one LARGE message via `dispatchMessageChunk`: the FIRST chunk carries
- * the total size, every SUBSEQUENT chunk omits the second arg (Chromium's
- * continuation contract). Returns false when the chunk API isn't present yet.
- */
-function buildChunkedDispatchScript(chunks, totalSize) {
-    const arr = JSON.stringify(chunks);
-    return `(()=>{try{`
-        + `if(!(window.DevToolsAPI&&typeof window.DevToolsAPI.dispatchMessageChunk==='function'))return false;`
-        + `const cs=JSON.parse(${JSON.stringify(arr)});`
-        + `for(let i=0;i<cs.length;i++){`
-        + `try{`
-        + `if(i===0){window.DevToolsAPI.dispatchMessageChunk(cs[i], ${totalSize})}`
-        + `else{window.DevToolsAPI.dispatchMessageChunk(cs[i])}`
-        + `}catch(_){}`
-        + `}`
-        + `return true;`
-        + `}catch(_){return false}})()`;
-}
+// ── main → front-end dispatch (shared transport with network-forward) ───────
 /** Script that nudges the front-end to discard its document and lazily re-pull. */
 function buildDocumentUpdatedScript() {
     const msg = JSON.stringify({ method: 'DOM.documentUpdated', params: {} });
-    return buildDispatchScript(msg);
+    return buildSingleDispatchScript(msg);
 }
 // Reconcile cadence: each tick re-asserts the hook (idempotent) and drains the
 // outbound queue. Fast enough that a freshly reloaded front-end is re-hooked
 // within a tick, cheap because the install script short-circuits to 'already'.
 const DRAIN_INTERVAL_MS = 150;
 /**
- * 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
@@ -206,6 +178,10 @@ const DRAIN_INTERVAL_MS = 150;
  */
 export function installElementsForward(deps) {
     const { devtoolsWc, bridge } = deps;
+    // Own (and tear down on stop()) a private broker only when the caller didn't
+    // supply a shared one — see ElementsForwardDeps.broker.
+    const ownsBroker = !deps.broker;
+    const broker = deps.broker ?? createCdpSessionBroker({ connections: deps.connections });
     let disposed = false;
     // A single self-healing loop drives BOTH hook (re)install and outbound drain;
     // it never self-terminates so a front-end reload (respawn) is re-hooked.
@@ -227,26 +203,26 @@ export function installElementsForward(deps) {
         const a = activeRenderWc();
         return a != null && a.id === id;
     };
-    // Render guests we've added our `on('message')` listener to (keyed wc.id →
-    // cleanup) so a re-resolve of the same guest doesn't double-subscribe.
-    const wiredGuests = new Map();
-    // Debugger sessions THIS feature attached (safe-area was degraded). dispose /
-    // guest-destroy detaches ONLY these; sessions safe-area owns are never touched.
-    const selfAttached = new Set();
+    // Render guests we've acquired a broker lease for (keyed wc.id) so a
+    // re-resolve of the same guest doesn't double-subscribe.
+    const guestLeases = new Map();
     const stop = () => {
         disposed = true;
         if (reconcileTimer) {
             clearInterval(reconcileTimer);
             reconcileTimer = null;
         }
-        for (const cleanup of wiredGuests.values()) {
+        for (const lease of guestLeases.values()) {
             try {
-                cleanup();
+                lease.dispose();
             }
-            catch { /* guest gone */ }
+            catch { /* already gone */ }
         }
-        wiredGuests.clear();
-        detachSelfAttached();
+        guestLeases.clear();
+        // Only detach sessions we self-attached if we own the broker's lifecycle —
+        // a shared/injected broker keeps serving other consumers past our stop().
+        if (ownsBroker)
+            broker.dispose();
         // Run the late-wired teardown once (render events, dom-ready, 'closed' sub).
         if (lateCleanup) {
             const c = lateCleanup;
@@ -257,61 +233,12 @@ export function installElementsForward(deps) {
             catch { /* already gone */ }
         }
     };
-    /** Detach every session we own; leave safe-area's alone. */
-    function detachSelfAttached() {
-        for (const wcId of selfAttached) {
-            const wc = wcFromId(wcId);
-            if (!wc)
-                continue;
-            try {
-                if (!wc.isDestroyed() && wc.debugger.isAttached())
-                    wc.debugger.detach();
-            }
-            catch { /* already detached / destroyed */ }
-        }
-        selfAttached.clear();
-    }
-    // ── main → front-end dispatch ──────────────────────────────────────────────
-    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);
-        }
-        catch {
-            return;
-        }
-        if (json.length > MAX_SINGLE_DISPATCH_CHARS) {
-            const chunks = [];
-            for (let i = 0; i < json.length; i += CHUNK_CHARS) {
-                chunks.push(json.slice(i, i + CHUNK_CHARS));
-            }
-            let script;
-            try {
-                script = buildChunkedDispatchScript(chunks, json.length);
-            }
-            catch {
-                return;
-            }
-            devtoolsWc.executeJavaScript(script, true).catch(() => { });
-            return;
-        }
-        let script;
-        try {
-            script = buildDispatchScript(json);
-        }
-        catch {
-            return;
-        }
-        devtoolsWc.executeJavaScript(script, true).catch(() => { });
-    }
+    // ── main → front-end dispatch (shared transport, see frontend-dispatch.js) ──
+    // Reply to a front-end command id, passing the ORIGINAL id + sessionId
+    // straight through (no mapping) — the same settled-gate + chunking +
+    // reply-shape contract network-forward's global body gate uses, so the two
+    // outbound-gate features can never drift.
+    const { dispatchToFrontend, replyResult, replyError } = createFrontendReplyChannel(devtoolsWc, () => disposed);
     /** Tell the front-end its document is stale → it re-pulls lazily (routed). */
     function pushDocumentUpdated() {
         if (disposed || devtoolsWc.isDestroyed())
@@ -329,32 +256,7 @@ export function installElementsForward(deps) {
         }
         devtoolsWc.executeJavaScript(script, true).catch(() => { });
     }
-    /**
-     * Reply to a front-end command id, passing the ORIGINAL id + sessionId straight
-     * through (no mapping). Only the front-end-supplied sessionId is echoed back.
-     */
-    function replyResult(cmd, result) {
-        const msg = { id: cmd.id, result };
-        if (cmd.sessionId)
-            msg.sessionId = cmd.sessionId;
-        dispatchToFrontend(msg);
-    }
-    function replyError(cmd, message) {
-        const msg = { id: cmd.id, error: { code: -32000, message } };
-        if (cmd.sessionId)
-            msg.sessionId = cmd.sessionId;
-        dispatchToFrontend(msg);
-    }
-    // ── webContents lookup (id → wc), tolerant of fakes/teardown ────────────────
-    function wcFromId(id) {
-        try {
-            return electronWebContents?.fromId?.(id) ?? null;
-        }
-        catch {
-            return null;
-        }
-    }
-    // ── render-guest CDP session (reuse safe-area's; self-attach only if needed) ─
+    // ── render-guest CDP session (via the shared broker) ────────────────────────
     /** The active render guest, re-resolved fresh (pool/page swaps go stale). */
     function activeRenderWc() {
         try {
@@ -366,107 +268,42 @@ export function installElementsForward(deps) {
         }
     }
     /**
-     * Ensure the guest's debugger is usable. Reuse the already-attached session if
-     * safe-area attached it; only `attach('1.3')` ourselves when nobody has — and
-     * record that wc in `selfAttached` so we (and only we) detach it later. Returns
-     * false when the debugger can't be made usable.
-     */
-    function ensureGuestDebugger(wc) {
-        try {
-            if (wc.debugger.isAttached())
-                return true;
-        }
-        catch {
-            return false;
-        }
-        try {
-            wc.debugger.attach('1.3');
-            selfAttached.add(wc.id);
-            return true;
-        }
-        catch {
-            // Either someone else just attached (race → it IS usable) or attach truly
-            // failed. Treat "already attached" as success, anything else as failure.
-            try {
-                return wc.debugger.isAttached();
-            }
-            catch {
-                return false;
-            }
-        }
-    }
-    /**
-     * Add our render-event re-injection listener to a guest's debugger ONCE. DOM./
-     * CSS./Overlay./DOMSnapshot./DOMDebugger. EVENTS (no id) from the CURRENT
-     * generation are dispatched into the front-end so the Elements panel updates
-     * live; events arriving after the generation moved on are dropped. The listener
-     * is removed when the guest wc is destroyed (and on stop()).
+     * Get-or-create this guest's broker lease and wire our render-event
+     * re-injection listener on it ONCE. DOM./CSS./Overlay./DOMSnapshot./
+     * DOMDebugger. EVENTS (no id) from the CURRENT generation are dispatched
+     * into the front-end so the Elements panel updates live; events arriving
+     * after the generation moved on are dropped. `lease.onDetach` — which fires
+     * on an external detach OR the guest being destroyed (see cdp-session's
+     * design doc) — drops our cache entry so the NEXT call re-acquires fresh
+     * instead of operating on a dead lease forever.
      */
-    function wireGuestEvents(wc) {
-        if (wiredGuests.has(wc.id))
-            return;
-        const onMessage = (_event, method, params) => {
+    function ensureGuestLease(wc) {
+        const existing = guestLeases.get(wc.id);
+        if (existing)
+            return existing;
+        const lease = broker.acquire(wc);
+        if (!lease)
+            return null;
+        lease.onMessage((method, params) => {
             if (disposed)
                 return;
-            // Honour events only while this guest is STILL the active one — checked per
-            // event, so re-activating a previously-wired guest resumes forwarding.
+            // Honour events only while this guest is STILL the active one — checked
+            // per event, so re-activating a previously-wired guest resumes forwarding.
             if (!isActiveWcId(wc.id))
                 return;
             if (isRenderEventMethod(method)) {
                 dispatchToFrontend({ method, params });
             }
-        };
-        try {
-            wc.debugger.on('message', onMessage);
-        }
-        catch {
-            return;
-        }
-        const onDestroyed = () => {
-            const cleanup = wiredGuests.get(wc.id);
-            if (cleanup) {
-                wiredGuests.delete(wc.id);
-                try {
-                    cleanup();
-                }
-                catch { /* gone */ }
-            }
-            // A destroyed guest is no longer the active one, so its in-flight commands
-            // fail `isActiveWcId` and settle as errors on their own — no global bump
-            // (which would wrongly stale OTHER, still-active guests' commands).
-            // If we own this wc's session there is nothing left to detach; drop it.
-            selfAttached.delete(wc.id);
-        };
-        let closedSub;
-        try {
-            // Route the guest teardown through the connection registry's `'closed'`
-            // event when present. Render guests are NEVER pool-reset, so `'closed'`
-            // (fires only on real wc destroy) is the correct lifetime — and crucially
-            // `on('closed')` returns a handle whose `dispose()` REMOVES the listener
-            // WITHOUT firing it, matching the original `removeListener` semantics.
-            // (`own()` would fire `onDestroyed` on release AND mutate `wiredGuests`
-            // mid-drain in stop() — wrong here; see foundation.md §4.3.) Same
-            // try/catch guards a fake/minimal wc that lacks once/emitter wiring.
-            if (deps.connections)
-                closedSub = deps.connections.acquire(wc).on('closed', onDestroyed);
-            else
-                wc.once('destroyed', onDestroyed);
-        }
-        catch { /* fake/minimal wc */ }
-        wiredGuests.set(wc.id, () => {
-            try {
-                wc.debugger.removeListener('message', onMessage);
-            }
-            catch { /* gone */ }
-            try {
-                closedSub?.dispose();
-            }
-            catch { /* gone */ }
-            try {
-                wc.removeListener('destroyed', onDestroyed);
-            }
-            catch { /* gone */ }
         });
+        lease.onDetach(() => {
+            // A destroyed/detached guest is no longer the active one, so its
+            // in-flight commands fail `isActiveWcId` and settle as errors on their
+            // own — no global bump (which would wrongly stale OTHER, still-active
+            // guests' commands).
+            guestLeases.delete(wc.id);
+        });
+        guestLeases.set(wc.id, lease);
+        return lease;
     }
     /**
      * enable DOM/CSS/Overlay + wire events on a guest. Best-effort (never throws).
@@ -478,18 +315,24 @@ export function installElementsForward(deps) {
      * the Elements-panel hover highlight never paints. Awaiting DOM.enable first
      * guarantees the correct enable order. CSS.enable has no such dependency and is
      * fire-and-forget alongside.
+     *
+     * This does NOT delegate to `lease.ensureRenderDomains()`: that helper has no
+     * concept of "active guest", but a priming sequence started on a guest that
+     * stops being active mid-flight must NOT arm Overlay on the now-abandoned
+     * tree (checked again below) — a per-consumer concern only elements-forward
+     * has, so it keeps its own sequence, just dispatched through the lease.
      */
     function primeGuest(wc) {
-        if (!ensureGuestDebugger(wc))
+        const lease = ensureGuestLease(wc);
+        if (!lease)
             return;
-        wireGuestEvents(wc);
-        void enableGuestDomains(wc);
+        void enableGuestDomains(wc, lease);
     }
     /** Enable the render domains in dependency order. Resolves; never rejects. */
-    async function enableGuestDomains(wc) {
-        wc.debugger.sendCommand('CSS.enable').catch(() => { });
+    async function enableGuestDomains(wc, lease) {
+        lease.send('CSS.enable').catch(() => { });
         try {
-            await wc.debugger.sendCommand('DOM.enable');
+            await lease.send('DOM.enable');
         }
         catch {
             // Guest mid-destroy or DOM domain unavailable; Overlay.enable would only
@@ -501,7 +344,7 @@ export function installElementsForward(deps) {
         // arming Overlay so a stale/dead guest is left untouched.
         if (disposed || !isActiveWcId(wc.id))
             return;
-        wc.debugger.sendCommand('Overlay.enable').catch(() => { });
+        lease.send('Overlay.enable').catch(() => { });
     }
     // ── front-end → render command routing ─────────────────────────────────────
     function routeCommand(cmd) {
@@ -510,18 +353,18 @@ export function installElementsForward(deps) {
             replyError(cmd, 'no active render guest');
             return;
         }
-        if (!ensureGuestDebugger(wc)) {
+        const lease = ensureGuestLease(wc);
+        if (!lease) {
             replyError(cmd, 'render guest debugger unavailable');
             return;
         }
-        wireGuestEvents(wc);
         // The wc this command is dispatched to. A response that resolves after the
         // active guest changed (this wc is no longer active) is for a tree the
         // front-end has abandoned: settle the id with an error (no pending leak) but
         // do NOT feed its result into the new tree.
         const cmdWcId = wc.id;
-        wc.debugger
-            .sendCommand(cmd.method, (cmd.params ?? {}))
+        lease
+            .send(cmd.method, (cmd.params ?? {}))
             .then((result) => {
             if (disposed)
                 return;
@@ -535,7 +378,7 @@ export function installElementsForward(deps) {
             // enabled" and the hover highlight stops painting. Re-arm it so the next
             // hover paints — only while this guest is still the active one.
             if (cmd.method === 'Overlay.disable' && isActiveWcId(cmdWcId)) {
-                wc.debugger.sendCommand('Overlay.enable').catch(() => { });
+                lease.send('Overlay.enable').catch(() => { });
             }
             replyResult(cmd, result);
         })
@@ -545,18 +388,26 @@ export function installElementsForward(deps) {
             replyError(cmd, err instanceof Error ? err.message : String(err));
         });
     }
-    /** Process a drained batch of front-end commands. */
+    /**
+     * Answer a network-routed command from the provider. Never touches the render
+     * guest: the body lives in the network forwarder's prefetch cache (or
+     * nowhere). Shared with network-forward's dedicated global body gate — see
+     * answerNetworkBodyCommand's doc comment for the not-found/reply contract.
+     */
+    function answerNetworkCommand(cmd) {
+        answerNetworkBodyCommand(cmd, deps.network, { replyResult, replyError });
+    }
+    /** Process a drained batch of front-end commands, splitting by route tag. */
     function handleOutbound(batch) {
-        if (!Array.isArray(batch))
-            return;
-        for (const raw of batch) {
-            if (!raw || typeof raw !== 'object')
-                continue;
-            const cmd = raw;
-            if (typeof cmd.method !== 'string')
-                continue;
+        drainOutboundBatch(batch, (cmd) => {
+            if (cmd.route === 'network') {
+                answerNetworkCommand(cmd);
+                return;
+            }
+            // 'render' — and any untagged legacy payload, which only ever carried
+            // render-domain commands.
             routeCommand(cmd);
-        }
+        });
     }
     // ── follow the active guest across page switches ───────────────────────────
     const onRenderEvent = (event) => {