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

package/dist/main/services/dimina-resource-server.js

@@ -1,99 +1,2 @@
-import http from 'node:http';
-import fs from 'node:fs';
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-const MIME_TYPES = {
-    '.css': 'text/css; charset=utf-8',
-    '.html': 'text/html; charset=utf-8',
-    '.js': 'text/javascript; charset=utf-8',
-    '.json': 'application/json; charset=utf-8',
-    '.map': 'application/json; charset=utf-8',
-    '.svg': 'image/svg+xml',
-    '.png': 'image/png',
-    '.jpg': 'image/jpeg',
-    '.jpeg': 'image/jpeg',
-    '.gif': 'image/gif',
-    '.webp': 'image/webp',
-    '.wasm': 'application/wasm',
-};
-export async function startDiminaResourceServer(rootDir) {
-    const root = path.resolve(rootDir);
-    const server = http.createServer((req, res) => {
-        void handleRequest(root, req, res);
-    });
-    await new Promise((resolve, reject) => {
-        server.once('error', reject);
-        server.listen(0, '127.0.0.1', () => {
-            server.off('error', reject);
-            resolve();
-        });
-    });
-    const address = server.address();
-    return {
-        baseUrl: `http://127.0.0.1:${address.port}/`,
-        close() {
-            return new Promise((resolve, reject) => {
-                server.close((err) => err ? reject(err) : resolve());
-            });
-        },
-    };
-}
-async function handleRequest(root, req, res) {
-    setCorsHeaders(res);
-    if (req.method === 'OPTIONS') {
-        res.writeHead(204);
-        res.end();
-        return;
-    }
-    if (req.method !== 'GET' && req.method !== 'HEAD') {
-        res.writeHead(405);
-        res.end('Method Not Allowed');
-        return;
-    }
-    const url = new URL(req.url ?? '/', 'http://127.0.0.1');
-    const filePath = resolveContainedPath(root, decodeURIComponent(url.pathname));
-    if (!filePath) {
-        res.writeHead(403);
-        res.end('Forbidden');
-        return;
-    }
-    try {
-        const stat = await fs.promises.stat(filePath);
-        if (!stat.isFile()) {
-            res.writeHead(404);
-            res.end('Not Found');
-            return;
-        }
-        res.writeHead(200, {
-            'content-type': MIME_TYPES[path.extname(filePath)] ?? 'application/octet-stream',
-            'content-length': stat.size,
-            'cache-control': 'no-store',
-        });
-        if (req.method === 'HEAD') {
-            res.end();
-            return;
-        }
-        fs.createReadStream(filePath).pipe(res);
-    }
-    catch {
-        res.writeHead(404);
-        res.end('Not Found');
-    }
-}
-function resolveContainedPath(root, pathname) {
-    const relative = pathname.replace(/^\/+/, '') || 'index.html';
-    const resolved = path.resolve(root, relative);
-    if (resolved !== root && !resolved.startsWith(root + path.sep))
-        return null;
-    return resolved;
-}
-function setCorsHeaders(res) {
-    res.setHeader('access-control-allow-origin', '*');
-    res.setHeader('access-control-allow-headers', '*');
-    res.setHeader('access-control-allow-methods', 'GET,HEAD,OPTIONS');
-    res.setHeader('cross-origin-resource-policy', 'cross-origin');
-}
-export function toSourceUrl(filePath) {
-    return pathToFileURL(filePath).toString();
-}
+export * from '@dimina-kit/electron-runtime/main/dimina-resource-server';
 //# sourceMappingURL=dimina-resource-server.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
+ * simulator and native HTTP namespaces 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