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

package/dist/main/services/network-forward/body-cache.js

@@ -0,0 +1,175 @@
+/**
+ * PrefetchCache — a bounded, TTL'd "prime now / read later" promise cache.
+ *
+ * The network forwarder prefetches `Network.getResponseBody` /
+ * `Network.getRequestPostData` from the simulator's CDP session the moment a
+ * request finishes (the renderer may evict the resource soon after), keyed by
+ * the namespaced virtual requestId. A later Response-tab click resolves from
+ * here instead of re-issuing a debugger round-trip against a session that may
+ * have moved on.
+ *
+ * Contract:
+ *  - `prime(id, fetch)` is idempotent per id: while an entry is pending or a
+ *    settled entry is still live, later primes are ignored.
+ *  - A fetch rejection — or a resolved value whose `sizeOf` exceeds
+ *    `perEntryMaxChars` — becomes an ERROR SENTINEL: the id stays known but
+ *    every lookup rejects with the canonical not-found message (the same
+ *    answer a real CDP backend gives for an unknown requestId, so the
+ *    front-end renders its normal failure state).
+ *  - `lookup(id)` resolves the cached value, awaits a still-pending fetch (a
+ *    panel click can land before the prefetch settles), and rejects
+ *    not-found for unknown / expired / evicted / sentinel entries.
+ *  - Bounds apply to SETTLED entries only: LRU by settle/lookup recency up to
+ *    `maxEntries`, plus a `maxTotalChars` budget over `sizeOf`. A pending
+ *    entry counts 0 and is never evicted — evicting an in-flight prefetch
+ *    would strand its waiters.
+ *  - TTL is anchored to the SETTLE time (not the prime() call time) and is
+ *    enforced lazily on the next prime/lookup.
+ */
+const NOT_FOUND = 'No resource with given identifier found';
+/**
+ * Default per-entry size ceiling (chars). Exported so callers that need to
+ * pre-screen a fetch BEFORE issuing it (e.g. skipping a CDP round-trip for a
+ * response already known to be oversized) reference the exact same number
+ * `PrefetchCache`'s own default enforces — one source of truth, not two
+ * independently-configured limits that could silently drift apart.
+ */
+export const DEFAULT_PER_ENTRY_MAX_CHARS = 16 * 1024 * 1024;
+export class PrefetchCache {
+    sizeOf;
+    map = new Map();
+    maxEntries;
+    maxTotalChars;
+    perEntryMaxChars;
+    ttlMs;
+    now;
+    constructor(sizeOf, opts = {}) {
+        this.sizeOf = sizeOf;
+        this.maxEntries = opts.maxEntries ?? 256;
+        this.maxTotalChars = opts.maxTotalChars ?? 64 * 1024 * 1024;
+        this.perEntryMaxChars = opts.perEntryMaxChars ?? DEFAULT_PER_ENTRY_MAX_CHARS;
+        this.ttlMs = opts.ttlMs ?? 5 * 60_000;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /**
+     * Returns `true` when this call actually started a new fetch, `false` when
+     * it was a no-op (idempotent re-prime of an id that's already pending or
+     * still live). Callers that admission-gate priming (a concurrency cap) need
+     * this to know whether they actually consumed a slot — incrementing a
+     * counter unconditionally would leak a slot on every no-op re-prime.
+     */
+    prime(id, fetch) {
+        this.sweepExpired();
+        const existing = this.map.get(id);
+        if (existing && (existing.pending || !this.isExpired(existing)))
+            return false;
+        if (existing)
+            this.map.delete(id);
+        // A synchronously-throwing fetch (destroyed webContents) is a rejection.
+        let fetched;
+        try {
+            fetched = fetch();
+        }
+        catch (err) {
+            fetched = Promise.reject(err instanceof Error ? err : new Error(String(err)));
+        }
+        const entry = {
+            promise: fetched,
+            pending: true,
+            failed: false,
+            value: null,
+            size: 0,
+            settledAt: 0,
+        };
+        entry.promise = fetched.then((v) => {
+            entry.pending = false;
+            entry.settledAt = this.now();
+            const size = this.sizeOf(v);
+            if (size > this.perEntryMaxChars) {
+                entry.failed = true;
+                throw new Error(NOT_FOUND);
+            }
+            entry.value = v;
+            entry.size = size;
+            // Refresh recency at settle time (identity-checked: a clear() while
+            // pending must not resurrect the entry) and enforce the bounds now
+            // that this entry's real size is known.
+            if (this.map.get(id) === entry) {
+                this.map.delete(id);
+                this.map.set(id, entry);
+                this.evict();
+            }
+            return v;
+        }, () => {
+            entry.pending = false;
+            entry.failed = true;
+            entry.settledAt = this.now();
+            throw new Error(NOT_FOUND);
+        });
+        // A never-looked-up sentinel must not surface as an unhandled rejection.
+        entry.promise.catch(() => { });
+        this.map.set(id, entry);
+        return true;
+    }
+    lookup(id) {
+        this.sweepExpired();
+        const e = this.map.get(id);
+        if (!e)
+            return Promise.reject(new Error(NOT_FOUND));
+        // A pending entry's normalized promise already carries the outcome the
+        // waiter needs (value, sentinel, or size overflow) — hand it out directly
+        // so the answer never races the map bookkeeping.
+        if (e.pending)
+            return e.promise;
+        if (e.failed || this.isExpired(e)) {
+            if (!e.failed)
+                this.map.delete(id);
+            return Promise.reject(new Error(NOT_FOUND));
+        }
+        const v = e.value;
+        if (v === null)
+            return Promise.reject(new Error(NOT_FOUND));
+        // A hit refreshes LRU recency.
+        this.map.delete(id);
+        this.map.set(id, e);
+        return Promise.resolve(v);
+    }
+    clear() {
+        this.map.clear();
+    }
+    get size() {
+        return this.map.size;
+    }
+    isExpired(e) {
+        return !e.pending && this.now() - e.settledAt > this.ttlMs;
+    }
+    sweepExpired() {
+        for (const [k, e] of this.map) {
+            if (this.isExpired(e))
+                this.map.delete(k);
+        }
+    }
+    /** Evict oldest SETTLED entries until both bounds hold; pending are exempt. */
+    evict() {
+        let settled = 0;
+        let total = 0;
+        for (const e of this.map.values()) {
+            if (!e.pending) {
+                settled++;
+                total += e.size;
+            }
+        }
+        if (settled <= this.maxEntries && total <= this.maxTotalChars)
+            return;
+        for (const [k, e] of this.map) {
+            if (settled <= this.maxEntries && total <= this.maxTotalChars)
+                break;
+            if (e.pending)
+                continue;
+            this.map.delete(k);
+            settled--;
+            total -= e.size;
+        }
+    }
+}
+//# sourceMappingURL=body-cache.js.map

package/dist/main/services/network-forward/frontend-dispatch.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared `executeJavaScript` builders for pushing raw CDP messages into the
+ * embedded Chrome DevTools front-end via `window.DevToolsAPI.dispatchMessage`
+ * / `dispatchMessageChunk`. Both network-forward (Network tab injection) and
+ * elements-forward (Elements tab / render-event re-injection) need the exact
+ * same transport contract; a single copy means the two can never drift on the
+ * chunk-continuation protocol.
+ */
+/** Probe the front-end realm exposes `DevToolsAPI.dispatchMessage`. */
+export declare 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. */
+export declare const MAX_SINGLE_DISPATCH_CHARS = 1000000;
+export declare const CHUNK_CHARS: number;
+/**
+ * Build the `executeJavaScript` source for a chunked dispatch of one large CDP
+ * message — DevTools' own transport caps a single `dispatchMessage` payload, so
+ * the front-end exposes `dispatchMessageChunk(messageChunk, messageSize)` where
+ * the FIRST chunk carries the total size and EVERY SUBSEQUENT chunk is called
+ * with the chunk ONLY (second arg omitted). This matches Chromium's
+ * `devtools_ui_bindings.cc` DispatchProtocolMessage, whose front-end treats a
+ * call with a second argument as the start of a new message and a call without
+ * one as a continuation. Passing 0 (the previous behaviour) risked the
+ * front-end mis-reading a continuation as a fresh 0-size message. Returns false
+ * when the API isn't available.
+ */
+export declare function buildChunkedDispatchScript(chunks: string[], totalSize: number): string;
+//# sourceMappingURL=frontend-dispatch.d.ts.map

package/dist/main/services/network-forward/frontend-dispatch.js

@@ -0,0 +1,42 @@
+/**
+ * Shared `executeJavaScript` builders for pushing raw CDP messages into the
+ * embedded Chrome DevTools front-end via `window.DevToolsAPI.dispatchMessage`
+ * / `dispatchMessageChunk`. Both network-forward (Network tab injection) and
+ * elements-forward (Elements tab / render-event re-injection) need the exact
+ * same transport contract; a single copy means the two can never drift on the
+ * chunk-continuation protocol.
+ */
+/** Probe the front-end realm exposes `DevToolsAPI.dispatchMessage`. */
+export 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. */
+export const MAX_SINGLE_DISPATCH_CHARS = 1_000_000;
+export const CHUNK_CHARS = 256 * 1024;
+/**
+ * Build the `executeJavaScript` source for a chunked dispatch of one large CDP
+ * message — DevTools' own transport caps a single `dispatchMessage` payload, so
+ * the front-end exposes `dispatchMessageChunk(messageChunk, messageSize)` where
+ * the FIRST chunk carries the total size and EVERY SUBSEQUENT chunk is called
+ * with the chunk ONLY (second arg omitted). This matches Chromium's
+ * `devtools_ui_bindings.cc` DispatchProtocolMessage, whose front-end treats a
+ * call with a second argument as the start of a new message and a call without
+ * one as a continuation. Passing 0 (the previous behaviour) risked the
+ * front-end mis-reading a continuation as a fresh 0-size message. Returns false
+ * when the API isn't available.
+ */
+export 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{`
+        // First chunk: (chunk, totalSize). Subsequent chunks: (chunk) — second arg
+        // omitted, NOT 0, per Chromium's continuation contract.
+        + `if(i===0){window.DevToolsAPI.dispatchMessageChunk(cs[i], ${totalSize})}`
+        + `else{window.DevToolsAPI.dispatchMessageChunk(cs[i])}`
+        + `}catch(_){}`
+        + `}`
+        + `return true;`
+        + `}catch(_){return false}})()`;
+}
+//# sourceMappingURL=frontend-dispatch.js.map

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

@@ -49,21 +49,59 @@
  *  ✅ Forwarded to the native Network tab: requestWillBeSent, responseReceived,
  *     loadingFinished, loadingFailed (+ requestWillBeSentExtraInfo /
  *     responseReceivedExtraInfo when present, for accurate headers/status).
- *  ⏳ TODO (二期): `dataReceived` per-chunk forwarding (skipped to avoid an
- *     executeJavaScript per chunk), and response body / preview (needs hooking
- *     `InspectorFrontendHost.sendMessageToBackend` + a prefetched body cache so
- *     the front-end's `Network.getResponseBody` round-trip resolves).
- *  ⚠️ NOT captured here: requests issued from inside a render-host `<webview>`
- *     guest (page-level resource loads / page `fetch`). The safe-area service
- *     already owns each guest's `wc.debugger`, and `debugger.attach` is
- *     single-owner — bringing those in needs a shared CDP broker. `source:'render'`
- *     is reserved for when that's added (later).
+ *  ✅ Response body / preview and request post data: prefetched from the
+ *     simulator's CDP session at loadingFinished into a bounded cache keyed by
+ *     the VIRTUAL id (`bodies`, see NetworkBodyProvider). The front-end's
+ *     `Network.getResponseBody` / `Network.getRequestPostData` round-trips for
+ *     `dimina:sim:` ids are intercepted by the outbound CDP gate that
+ *     elements-forward installs on `InspectorFrontendHost.sendMessageToBackend`
+ *     and answered from that cache — the service-host backend the front-end
+ *     natively talks to has never heard of these ids.
+ *  ⏳ TODO: `dataReceived` per-chunk forwarding (skipped to avoid an
+ *     executeJavaScript per chunk).
+ *  ✅ Requests issued from inside a render-host `<webview>` guest (page-level
+ *     resource loads / page `fetch`, tagged `source: 'render'`) — `attachRenderGuest`
+ *     acquires a lease from the shared `CdpSessionBroker` (cdp-session/index.ts),
+ *     which is single owner of every render-guest `wc.debugger` session across
+ *     this forwarder, safe-area, elements-forward and render-inspect. An
+ *     external detach (another owner releasing the shared session, or a real
+ *     Chrome DevTools window) self-heals via the lease's `onDetach` — capture
+ *     re-wires itself even though `attachRenderGuest` is only ever called ONCE
+ *     per guest (at webview creation).
  *  ⚠️ NOT observable by any `webContents.debugger`: a request a host module issues
  *     directly from the MAIN process. Those need an explicit `report()` call
  *     (exposed below; it uses the console fallback path).
  */
 import type { WebContents } from 'electron';
 import { type ConnectionRegistry, type Disposable } from '@dimina-kit/electron-deck/main';
+import { type CdpSessionBroker } from '../cdp-session/index.js';
+/**
+ * Namespace prefix of every virtual requestId this forwarder injects into the
+ * DevTools front-end. SINGLE SOURCE for the literal: the front-end outbound
+ * gate (elements-forward) keys its `Network.getResponseBody` /
+ * `Network.getRequestPostData` interception on this exact prefix, so the two
+ * modules can never drift apart on what counts as "one of ours".
+ */
+export declare const VIRTUAL_REQUEST_ID_PREFIX = "dimina:sim:";
+/** CDP `Network.getResponseBody` result shape (served from the prefetch cache). */
+export interface CdpResponseBody {
+    body: string;
+    base64Encoded: boolean;
+}
+/**
+ * Answers the front-end's body/post-data lookups for virtual requestIds. The
+ * outbound CDP gate (elements-forward) consumes this: it intercepts the
+ * front-end's `Network.getResponseBody` / `Network.getRequestPostData` for
+ * `dimina:sim:` ids (the service-host backend has never heard of them) and
+ * replies from here instead. Rejections carry the same not-found message a
+ * real CDP backend produces for an unknown requestId.
+ */
+export interface NetworkBodyProvider {
+    getResponseBody(requestId: string): Promise<CdpResponseBody>;
+    getRequestPostData(requestId: string): Promise<{
+        postData: string;
+    }>;
+}
 /** Which layer a captured request came from (tags the fallback log line). */
 export type NetworkSource = 'service' | 'render';
 /** A normalized completed network request, used only by the console fallback. */
@@ -98,6 +136,18 @@ export interface NetworkForwarderBridge {
      * `once('destroyed')` fallback is used, so existing callers compile unchanged.
      */
     connections?: ConnectionRegistry;
+    /**
+     * Shared CDP session broker (see cdp-session/index.ts) that owns every
+     * render-guest AND simulator debugger session's attach/detach lifecycle —
+     * safe-area, elements-forward, render-inspect and simulator-storage acquire
+     * leases from the same instance. Absent → a private broker is created and
+     * owned for this forwarder's lifetime (torn down on `dispose()`), so
+     * existing standalone callers/tests compile and behave unchanged, just
+     * without cross-module session sharing. Both `attachRenderGuest` and
+     * `attachSimulator` go through it — see detachSimulator's docstring for why
+     * the simulator path never forces a physical detach either.
+     */
+    broker?: CdpSessionBroker;
 }
 export interface NetworkForwarder extends Disposable {
     /**
@@ -109,6 +159,20 @@ export interface NetworkForwarder extends Disposable {
     attachSimulator(wc: WebContents): void;
     /** Detach from the current simulator WCV (without disposing the forwarder). */
     detachSimulator(): void;
+    /**
+     * Wire a render-host guest wc (pageFrame) for Network capture — page-level
+     * resource loads (images/fonts/page fetch) that never touch the simulator's
+     * network stack. Idempotent per wc. Acquires a lease from the shared
+     * `CdpSessionBroker` (cdp-session/index.ts) — reuses an already-attached
+     * session (safe-area / elements-forward / render-inspect may have attached
+     * first) or self-attaches when no one has; the broker alone decides who may
+     * detach. Self-heals after an external detach (the lease's `onDetach`
+     * re-wires automatically) even though this is only ever called ONCE per
+     * guest, at webview creation. Events share the simulator capture's
+     * virtual-id namespace prefix (distinct epochs keep them collision-free) and
+     * the same body prefetch cache.
+     */
+    attachRenderGuest(wc: WebContents): void;
     /**
      * Point the forwarder at the WebContents hosting the DevTools FRONT-END (the
      * primary, native-Network-tab sink). Pass null when that view is torn down so
@@ -120,6 +184,13 @@ export interface NetworkForwarder extends Disposable {
      * (e.g. a main-process direct send). Uses the console fallback sink.
      */
     report(record: NetworkRequestRecord): void;
+    /**
+     * Body/post-data lookups for the virtual requestIds this forwarder injected,
+     * backed by the loadingFinished-time prefetch cache. Keyed by virtual id, so
+     * entries stay valid across detach/re-attach (each attach epoch mints
+     * non-colliding ids); dispose() drops them all.
+     */
+    readonly bodies: NetworkBodyProvider;
 }
 /**
  * CDP events whose `params.requestId` we rewrite into the virtual namespace.