@silbercue/chrome 0.2.0

package/build/cdp/network-collector.js

@@ -0,0 +1,257 @@
+import { debug } from "./debug.js";
+// --- NetworkCollector ---
+export class NetworkCollector {
+    _buffer = [];
+    _pending = new Map();
+    _maxEntries;
+    _maxPending;
+    _cdpClient;
+    _sessionId;
+    _monitoring = false;
+    _monitoringSince = 0; // performance.now() beim Start
+    _callbacks = null;
+    constructor(cdpClient, sessionId, options) {
+        this._cdpClient = cdpClient;
+        this._sessionId = sessionId;
+        this._maxEntries = options?.maxEntries ?? 500;
+        this._maxPending = options?.maxPending ?? 200;
+    }
+    /**
+     * Start Network monitoring. Calls Network.enable and registers 4 event listeners.
+     * Idempotent — calling twice has no effect.
+     */
+    async start() {
+        if (this._monitoring)
+            return;
+        await this._cdpClient.send("Network.enable", {}, this._sessionId);
+        this._callbacks = {
+            requestWillBeSent: (params) => this._onRequestWillBeSent(params),
+            responseReceived: (params) => this._onResponseReceived(params),
+            loadingFinished: (params) => this._onLoadingFinished(params),
+            loadingFailed: (params) => this._onLoadingFailed(params),
+        };
+        this._cdpClient.on("Network.requestWillBeSent", this._callbacks.requestWillBeSent, this._sessionId);
+        this._cdpClient.on("Network.responseReceived", this._callbacks.responseReceived, this._sessionId);
+        this._cdpClient.on("Network.loadingFinished", this._callbacks.loadingFinished, this._sessionId);
+        this._cdpClient.on("Network.loadingFailed", this._callbacks.loadingFailed, this._sessionId);
+        this._monitoring = true;
+        this._monitoringSince = performance.now();
+        this._buffer = [];
+        this._pending = new Map();
+        debug("NetworkCollector started on session %s", this._sessionId);
+    }
+    /**
+     * Stop Network monitoring. Returns collected requests, clears buffer, calls Network.disable.
+     * If not monitoring, returns empty array (graceful).
+     */
+    async stop() {
+        if (!this._monitoring)
+            return [];
+        this._removeListeners();
+        // H1: Wrap Network.disable in try/catch — even if CDP is disconnected,
+        // the collector must reset cleanly so start() can be called again.
+        try {
+            await this._cdpClient.send("Network.disable", {}, this._sessionId);
+        }
+        catch (err) {
+            debug("NetworkCollector: Network.disable failed (ignored): %O", err);
+        }
+        // H3: Flush all in-flight pending requests into the buffer before clearing.
+        // They are marked as incomplete (status 0, size 0) so the caller can distinguish them.
+        this._flushPending();
+        this._monitoring = false;
+        const result = [...this._buffer];
+        this._buffer = [];
+        this._pending.clear();
+        debug("NetworkCollector stopped, returning %d requests", result.length);
+        return result;
+    }
+    /**
+     * Remove event listeners without calling Network.disable (for shutdown — sync, no CDP call).
+     */
+    detach() {
+        this._removeListeners();
+        this._monitoring = false;
+        debug("NetworkCollector detached");
+    }
+    /**
+     * Re-initialize after reconnect or tab switch.
+     * Detaches, sets new client/session, clears buffer.
+     * Monitoring stays OFF — agent must call start() again.
+     */
+    reinit(cdpClient, sessionId) {
+        this.detach();
+        this._cdpClient = cdpClient;
+        this._sessionId = sessionId;
+        this._buffer = [];
+        this._pending = new Map();
+        debug("NetworkCollector reinit on session %s", sessionId);
+    }
+    /**
+     * Return a copy of all buffered request entries.
+     */
+    getAll() {
+        return [...this._buffer];
+    }
+    /**
+     * Return filtered request entries. Both filters are combined with AND.
+     * Throws if the regex pattern is invalid.
+     */
+    getFiltered(filter, pattern) {
+        if (!filter && !pattern)
+            return this.getAll();
+        let regex;
+        if (pattern) {
+            regex = new RegExp(pattern);
+        }
+        return this._buffer.filter((entry) => {
+            if (filter === "failed" && !(entry.failed || entry.status >= 400))
+                return false;
+            if (regex && !regex.test(entry.url))
+                return false;
+            return true;
+        });
+    }
+    get isMonitoring() {
+        return this._monitoring;
+    }
+    get monitoringSince() {
+        return this._monitoringSince;
+    }
+    get count() {
+        return this._buffer.length;
+    }
+    // --- Internal ---
+    _removeListeners() {
+        if (this._callbacks) {
+            this._cdpClient.off("Network.requestWillBeSent", this._callbacks.requestWillBeSent);
+            this._cdpClient.off("Network.responseReceived", this._callbacks.responseReceived);
+            this._cdpClient.off("Network.loadingFinished", this._callbacks.loadingFinished);
+            this._cdpClient.off("Network.loadingFailed", this._callbacks.loadingFailed);
+            this._callbacks = null;
+        }
+    }
+    _pushEntry(entry) {
+        if (this._buffer.length >= this._maxEntries) {
+            this._buffer.shift();
+        }
+        this._buffer.push(entry);
+    }
+    /**
+     * H3: Flush all pending requests into the ring buffer as incomplete entries.
+     * Called by stop() so in-flight requests are not silently discarded.
+     */
+    _flushPending() {
+        for (const [, pending] of this._pending) {
+            this._pushEntry({
+                url: pending.url,
+                method: pending.method,
+                status: pending.status ?? 0,
+                mimeType: pending.mimeType ?? "",
+                size: pending.encodedDataLength ?? 0,
+                duration: 0,
+                initiator: pending.initiator,
+                failed: false,
+            });
+        }
+    }
+    /**
+     * H2: Evict oldest pending entries when the pending map exceeds _maxPending.
+     * Evicted entries are pushed into the ring buffer as incomplete.
+     */
+    _evictOldestPending() {
+        if (this._pending.size <= this._maxPending)
+            return;
+        const excess = this._pending.size - this._maxPending;
+        const keys = this._pending.keys();
+        for (let i = 0; i < excess; i++) {
+            const { value: key, done } = keys.next();
+            if (done)
+                break;
+            const pending = this._pending.get(key);
+            this._pushEntry({
+                url: pending.url,
+                method: pending.method,
+                status: pending.status ?? 0,
+                mimeType: pending.mimeType ?? "",
+                size: pending.encodedDataLength ?? 0,
+                duration: 0,
+                initiator: pending.initiator,
+                failed: false,
+            });
+            this._pending.delete(key);
+        }
+    }
+    _finishRequest(requestId) {
+        const pending = this._pending.get(requestId);
+        if (!pending)
+            return;
+        this._pending.delete(requestId);
+        const entry = {
+            url: pending.url,
+            method: pending.method,
+            status: pending.status ?? 0,
+            mimeType: pending.mimeType ?? "",
+            size: pending.encodedDataLength ?? 0,
+            duration: Math.round(((pending.endTimestamp ?? pending.startTimestamp) - pending.startTimestamp) * 1000),
+            initiator: pending.initiator,
+            failed: pending.failed ?? false,
+        };
+        if (pending.errorText) {
+            entry.errorText = pending.errorText;
+        }
+        this._pushEntry(entry);
+    }
+    _onRequestWillBeSent(params) {
+        const p = params;
+        const requestId = p.requestId;
+        if (!requestId)
+            return;
+        // Redirect handling: overwrite existing pending request with same requestId
+        // Only the final URL matters
+        this._pending.set(requestId, {
+            url: p.request?.url ?? "",
+            method: p.request?.method ?? "GET",
+            initiator: p.initiator?.type ?? "other",
+            startTimestamp: p.timestamp ?? 0,
+        });
+        // H2: Enforce pending limit — evict oldest if exceeded
+        this._evictOldestPending();
+    }
+    _onResponseReceived(params) {
+        const p = params;
+        const requestId = p.requestId;
+        if (!requestId)
+            return;
+        const pending = this._pending.get(requestId);
+        if (!pending)
+            return; // Unknown requestId — ignore (data URIs, pre-flight)
+        pending.status = p.response?.status;
+        pending.mimeType = p.response?.mimeType;
+    }
+    _onLoadingFinished(params) {
+        const p = params;
+        const requestId = p.requestId;
+        if (!requestId)
+            return;
+        const pending = this._pending.get(requestId);
+        if (!pending)
+            return;
+        pending.endTimestamp = p.timestamp;
+        pending.encodedDataLength = p.encodedDataLength;
+        this._finishRequest(requestId);
+    }
+    _onLoadingFailed(params) {
+        const p = params;
+        const requestId = p.requestId;
+        if (!requestId)
+            return;
+        const pending = this._pending.get(requestId);
+        if (!pending)
+            return;
+        pending.endTimestamp = p.timestamp;
+        pending.failed = true;
+        pending.errorText = p.errorText;
+        this._finishRequest(requestId);
+    }
+}

package/build/cdp/protocol.d.ts

@@ -0,0 +1,20 @@
+export interface CdpRequest {
+    id: number;
+    method: string;
+    params?: Record<string, unknown>;
+    sessionId?: string;
+}
+export interface CdpResponse {
+    id: number;
+    result?: unknown;
+    error?: CdpError;
+}
+export interface CdpEvent {
+    method: string;
+    params?: unknown;
+    sessionId?: string;
+}
+export interface CdpError {
+    code: number;
+    message: string;
+}

package/build/cdp/protocol.js

@@ -0,0 +1 @@
+export {};

package/build/cdp/session-manager.d.ts

@@ -0,0 +1,62 @@
+import type { CdpClient } from "./cdp-client.js";
+export interface SessionInfo {
+    sessionId: string;
+    frameId: string;
+    url: string;
+    isMain: boolean;
+}
+export declare class SessionManager {
+    private _frameToSession;
+    private _sessionToFrame;
+    private _sessionToUrl;
+    private _nodeToSession;
+    private _mainSessionId;
+    private _cdpClient;
+    private _onOopifDetachCallback;
+    private _onAttachedBound;
+    private _onDetachedBound;
+    constructor(cdpClient: CdpClient, mainSessionId: string);
+    get mainSessionId(): string;
+    /**
+     * Register a callback to be invoked when an OOPIF session is detached.
+     * Used by A11yTreeProcessor to clean up ref-maps (H1).
+     */
+    onOopifDetach(callback: (sessionId: string) => void): void;
+    /**
+     * Returns the session for a given backendNodeId.
+     * Searches all registered composite keys for this backendNodeId.
+     * Falls back to main session if node is not registered (graceful degradation).
+     */
+    getSessionForNode(backendNodeId: number): string;
+    /**
+     * Register a node's session association using composite key.
+     * Key format: "${sessionId}:${backendNodeId}" to avoid collisions between OOPIF sessions.
+     * Called by A11yTreeProcessor when building the tree.
+     */
+    registerNode(backendNodeId: number, sessionId: string): void;
+    /**
+     * Returns all active sessions (main + OOPIFs).
+     */
+    getAllSessions(): SessionInfo[];
+    /**
+     * Initialize auto-attach and discover existing iFrames.
+     * H3: Also discovers already-existing OOPIF targets on startup.
+     */
+    init(): Promise<void>;
+    /**
+     * Handle Target.attachedToTarget event.
+     */
+    private _onAttached;
+    /**
+     * Handle Target.detachedFromTarget event.
+     */
+    private _onDetached;
+    /**
+     * Clean up event listeners and clear all state.
+     */
+    detach(): void;
+    /**
+     * Re-initialize after reconnect with new CDP client and session.
+     */
+    reinit(cdpClient: CdpClient, mainSessionId: string): Promise<void>;
+}

package/build/cdp/session-manager.js

@@ -0,0 +1,205 @@
+import { debug } from "./debug.js";
+import { wrapCdpError } from "../tools/error-utils.js";
+// --- SessionManager ---
+export class SessionManager {
+    _frameToSession = new Map(); // frameId → sessionId
+    _sessionToFrame = new Map(); // sessionId → frameId
+    _sessionToUrl = new Map(); // sessionId → url
+    _nodeToSession = new Map(); // "${sessionId}:${backendNodeId}" → sessionId
+    _mainSessionId;
+    _cdpClient;
+    _onOopifDetachCallback = null;
+    // Store bound callbacks for cleanup
+    _onAttachedBound = null;
+    _onDetachedBound = null;
+    constructor(cdpClient, mainSessionId) {
+        this._cdpClient = cdpClient;
+        this._mainSessionId = mainSessionId;
+    }
+    get mainSessionId() {
+        return this._mainSessionId;
+    }
+    /**
+     * Register a callback to be invoked when an OOPIF session is detached.
+     * Used by A11yTreeProcessor to clean up ref-maps (H1).
+     */
+    onOopifDetach(callback) {
+        this._onOopifDetachCallback = callback;
+    }
+    /**
+     * Returns the session for a given backendNodeId.
+     * Searches all registered composite keys for this backendNodeId.
+     * Falls back to main session if node is not registered (graceful degradation).
+     */
+    getSessionForNode(backendNodeId) {
+        // Search for any key ending with `:${backendNodeId}`
+        for (const [key, sid] of this._nodeToSession.entries()) {
+            const colonIdx = key.lastIndexOf(":");
+            if (colonIdx !== -1 && parseInt(key.slice(colonIdx + 1), 10) === backendNodeId) {
+                return sid;
+            }
+        }
+        return this._mainSessionId;
+    }
+    /**
+     * Register a node's session association using composite key.
+     * Key format: "${sessionId}:${backendNodeId}" to avoid collisions between OOPIF sessions.
+     * Called by A11yTreeProcessor when building the tree.
+     */
+    registerNode(backendNodeId, sessionId) {
+        this._nodeToSession.set(`${sessionId}:${backendNodeId}`, sessionId);
+    }
+    /**
+     * Returns all active sessions (main + OOPIFs).
+     */
+    getAllSessions() {
+        const sessions = [
+            {
+                sessionId: this._mainSessionId,
+                frameId: "main",
+                url: "",
+                isMain: true,
+            },
+        ];
+        for (const [sessionId, frameId] of this._sessionToFrame.entries()) {
+            sessions.push({
+                sessionId,
+                frameId,
+                url: this._sessionToUrl.get(sessionId) ?? "",
+                isMain: false,
+            });
+        }
+        return sessions;
+    }
+    /**
+     * Initialize auto-attach and discover existing iFrames.
+     * H3: Also discovers already-existing OOPIF targets on startup.
+     */
+    async init() {
+        // Register event listeners
+        this._onAttachedBound = (params) => this._onAttached(params);
+        this._onDetachedBound = (params) => this._onDetached(params);
+        this._cdpClient.on("Target.attachedToTarget", this._onAttachedBound);
+        this._cdpClient.on("Target.detachedFromTarget", this._onDetachedBound);
+        // Enable auto-attach on the page session — only iFrames of THIS page
+        try {
+            await this._cdpClient.send("Target.setAutoAttach", {
+                autoAttach: true,
+                waitForDebuggerOnStart: false,
+                flatten: true,
+            }, this._mainSessionId);
+        }
+        catch (err) {
+            debug("SessionManager: setAutoAttach failed: %s", wrapCdpError(err, "SessionManager.init"));
+            throw err;
+        }
+        // H3: Discover already-existing iframe targets and attach to them
+        try {
+            const { targetInfos } = await this._cdpClient.send("Target.getTargets");
+            const existingIframes = targetInfos.filter((t) => t.type === "iframe");
+            for (const iframe of existingIframes) {
+                // Check if we already have this target attached (auto-attach may have fired)
+                if (this._frameToSession.has(iframe.targetId))
+                    continue;
+                try {
+                    const { sessionId } = await this._cdpClient.send("Target.attachToTarget", { targetId: iframe.targetId, flatten: true });
+                    // Process as if it were an auto-attach event
+                    await this._onAttached({
+                        sessionId,
+                        targetInfo: iframe,
+                        waitingForDebugger: false,
+                    });
+                }
+                catch (err) {
+                    debug("SessionManager: failed to attach existing iframe %s: %s", iframe.url, err);
+                }
+            }
+        }
+        catch (err) {
+            // Non-fatal: auto-attach will still catch new iframes
+            debug("SessionManager: Target.getTargets failed during init: %s", wrapCdpError(err, "SessionManager.init"));
+        }
+        debug("SessionManager initialized (auto-attach enabled on session %s, %d existing OOPIFs)", this._mainSessionId, this._sessionToFrame.size);
+    }
+    /**
+     * Handle Target.attachedToTarget event.
+     */
+    async _onAttached(params) {
+        const { sessionId, targetInfo } = params;
+        // Only handle iframe targets
+        if (targetInfo.type !== "iframe") {
+            debug("SessionManager ignoring non-iframe target: %s (type: %s)", targetInfo.url, targetInfo.type);
+            return;
+        }
+        // Store session mapping
+        this._sessionToFrame.set(sessionId, targetInfo.targetId);
+        this._frameToSession.set(targetInfo.targetId, sessionId);
+        this._sessionToUrl.set(sessionId, targetInfo.url);
+        // Enable required CDP domains on the OOPIF session
+        try {
+            await Promise.all([
+                this._cdpClient.send("Accessibility.enable", {}, sessionId),
+                this._cdpClient.send("DOM.enable", {}, sessionId),
+                this._cdpClient.send("Runtime.enable", {}, sessionId),
+            ]);
+            debug("OOPIF attached: %s (session: %s)", targetInfo.url, sessionId);
+        }
+        catch (err) {
+            debug("OOPIF domain enable failed for %s: %s", targetInfo.url, wrapCdpError(err, "SessionManager._onAttached"));
+            // Clean up on failure
+            this._sessionToFrame.delete(sessionId);
+            this._frameToSession.delete(targetInfo.targetId);
+            this._sessionToUrl.delete(sessionId);
+        }
+    }
+    /**
+     * Handle Target.detachedFromTarget event.
+     */
+    _onDetached(params) {
+        const { sessionId } = params;
+        // Remove all nodes associated with this session from nodeToSession map
+        for (const [key, sid] of this._nodeToSession.entries()) {
+            if (sid === sessionId) {
+                this._nodeToSession.delete(key);
+            }
+        }
+        // Notify cleanup callback (H1: allows A11yTreeProcessor to clean ref-maps)
+        if (this._onOopifDetachCallback) {
+            this._onOopifDetachCallback(sessionId);
+        }
+        // Remove session from frame maps
+        const frameId = this._sessionToFrame.get(sessionId);
+        if (frameId) {
+            this._frameToSession.delete(frameId);
+        }
+        this._sessionToFrame.delete(sessionId);
+        this._sessionToUrl.delete(sessionId);
+        debug("OOPIF detached: %s", sessionId);
+    }
+    /**
+     * Clean up event listeners and clear all state.
+     */
+    detach() {
+        if (this._onAttachedBound) {
+            this._cdpClient.off("Target.attachedToTarget", this._onAttachedBound);
+            this._onAttachedBound = null;
+        }
+        if (this._onDetachedBound) {
+            this._cdpClient.off("Target.detachedFromTarget", this._onDetachedBound);
+            this._onDetachedBound = null;
+        }
+        this._frameToSession.clear();
+        this._sessionToFrame.clear();
+        this._sessionToUrl.clear();
+        this._nodeToSession.clear();
+    }
+    /**
+     * Re-initialize after reconnect with new CDP client and session.
+     */
+    async reinit(cdpClient, mainSessionId) {
+        this.detach();
+        this._cdpClient = cdpClient;
+        this._mainSessionId = mainSessionId;
+        await this.init();
+    }
+}

package/build/cdp/settle.d.ts

@@ -0,0 +1,16 @@
+import type { CdpClient } from "./cdp-client.js";
+export interface SettleOptions {
+    cdpClient: CdpClient;
+    sessionId: string;
+    frameId: string;
+    loaderId?: string;
+    spaNavigation?: boolean;
+    settleMs?: number;
+    timeoutMs?: number;
+}
+export interface SettleResult {
+    settled: boolean;
+    signal?: "networkIdle" | "networkAlmostIdle" | "timeout" | "spa";
+    elapsedMs: number;
+}
+export declare function settle(options: SettleOptions): Promise<SettleResult>;

package/build/cdp/settle.js

@@ -0,0 +1,71 @@
+const DEFAULT_SETTLE_MS = 500;
+const DEFAULT_TIMEOUT_MS = 15_000;
+export async function settle(options) {
+    const { cdpClient, sessionId, frameId, loaderId, spaNavigation = false, settleMs = DEFAULT_SETTLE_MS, timeoutMs = DEFAULT_TIMEOUT_MS, } = options;
+    const start = performance.now();
+    // SPA path: same-document navigation — just wait settle_ms, no lifecycle events expected
+    if (spaNavigation) {
+        await delay(Math.min(settleMs, timeoutMs));
+        return {
+            settled: true,
+            signal: "spa",
+            elapsedMs: Math.round(performance.now() - start),
+        };
+    }
+    // Cross-document navigation: wait for lifecycle events
+    return new Promise((resolve) => {
+        let resolved = false;
+        let settleTimer;
+        const cleanup = () => {
+            if (overallTimer !== undefined)
+                clearTimeout(overallTimer);
+            if (settleTimer !== undefined)
+                clearTimeout(settleTimer);
+            cdpClient.off("Page.lifecycleEvent", onLifecycleEvent);
+        };
+        const finish = (result) => {
+            if (resolved)
+                return;
+            resolved = true;
+            cleanup();
+            resolve(result);
+        };
+        const onLifecycleEvent = (params) => {
+            const event = params;
+            // Only listen to main frame events
+            if (event.frameId !== frameId)
+                return;
+            // Filter by loaderId to avoid stale events from previous navigations
+            if (loaderId && event.loaderId !== loaderId)
+                return;
+            if (event.name === "networkIdle" || event.name === "networkAlmostIdle") {
+                // Prefer networkIdle over networkAlmostIdle
+                const signal = event.name;
+                // If we already have a settleTimer running (from networkAlmostIdle)
+                // and now networkIdle arrives, upgrade the signal
+                if (settleTimer !== undefined) {
+                    clearTimeout(settleTimer);
+                }
+                settleTimer = setTimeout(() => {
+                    finish({
+                        settled: true,
+                        signal,
+                        elapsedMs: Math.round(performance.now() - start),
+                    });
+                }, settleMs);
+            }
+        };
+        cdpClient.on("Page.lifecycleEvent", onLifecycleEvent, sessionId);
+        // Overall timeout to prevent hanging
+        const overallTimer = setTimeout(() => {
+            finish({
+                settled: false,
+                signal: "timeout",
+                elapsedMs: Math.round(performance.now() - start),
+            });
+        }, timeoutMs);
+    });
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/build/cli/license-commands.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Parses CLI args and dispatches to the correct subcommand.
+ * Exported for testability — `src/index.ts` calls this.
+ */
+export declare function runLicenseCommand(args: string[]): Promise<void>;
+/**
+ * Parses CLI arguments and returns the parsed command.
+ * Pure function — exported for unit-testing the routing logic
+ * without side effects.
+ */
+export declare function parseLicenseCommand(argv: string[]): {
+    subcommand: string | undefined;
+    key?: string;
+};
+/**
+ * Masks a license key for display: first 4 + "..." + last 4.
+ * Keys shorter than 10 characters are fully masked.
+ */
+export declare function maskKey(key: string): string;