@silbercue/chrome 0.2.0

package/build/cdp/debug.d.ts

@@ -0,0 +1 @@
+export declare function debug(message: string, ...args: unknown[]): void;

package/build/cdp/debug.js

@@ -0,0 +1,6 @@
+const isDebug = (process.env.DEBUG ?? "").includes("silbercuechrome");
+export function debug(message, ...args) {
+    if (!isDebug)
+        return;
+    console.error(`[silbercuechrome] ${message}`, ...args);
+}

package/build/cdp/dialog-handler.d.ts

@@ -0,0 +1,54 @@
+import type { CdpClient } from "./cdp-client.js";
+export interface DialogEvent {
+    type: "alert" | "confirm" | "prompt" | "beforeunload";
+    message: string;
+    defaultPrompt?: string;
+    url: string;
+}
+export interface DialogHandlerConfig {
+    autoAccept: boolean;
+    promptText?: string;
+    timeoutMs: number;
+}
+export declare class DialogHandler {
+    private _cdpClient;
+    private _sessionId;
+    private _callback;
+    private _pendingNotifications;
+    private _handlerStack;
+    private _defaultTimeoutMs;
+    private _pendingTimers;
+    private _initialized;
+    constructor(cdpClient: CdpClient, sessionId: string, timeoutMs?: number);
+    /**
+     * Start listening for Page.javascriptDialogOpening events.
+     */
+    init(): void;
+    /**
+     * Remove event listener and clear handler stack.
+     */
+    detach(): void;
+    /**
+     * Re-initialize after reconnect or tab switch.
+     * Preserves pending notifications (tab-switch should not lose them).
+     */
+    reinit(cdpClient: CdpClient, sessionId: string): void;
+    /**
+     * Push a handler onto the stack. The topmost handler is used for the next dialog.
+     */
+    pushHandler(config: DialogHandlerConfig): void;
+    /**
+     * Remove and return the topmost handler from the stack.
+     */
+    popHandler(): DialogHandlerConfig | undefined;
+    /**
+     * Return buffered dialog notifications and clear the buffer.
+     */
+    consumeNotifications(): DialogEvent[];
+    /**
+     * Number of buffered notifications.
+     */
+    get pendingCount(): number;
+    private _onDialogOpening;
+    private _handleDialog;
+}

package/build/cdp/dialog-handler.js

@@ -0,0 +1,129 @@
+import { debug } from "./debug.js";
+// --- DialogHandler ---
+export class DialogHandler {
+    _cdpClient;
+    _sessionId;
+    _callback = null;
+    _pendingNotifications = [];
+    _handlerStack = [];
+    _defaultTimeoutMs = 3000;
+    _pendingTimers = new Set();
+    _initialized = false;
+    constructor(cdpClient, sessionId, timeoutMs) {
+        this._cdpClient = cdpClient;
+        this._sessionId = sessionId;
+        if (timeoutMs !== undefined) {
+            this._defaultTimeoutMs = timeoutMs;
+        }
+    }
+    /**
+     * Start listening for Page.javascriptDialogOpening events.
+     */
+    init() {
+        if (this._initialized)
+            return;
+        this._initialized = true;
+        this._callback = (params) => {
+            this._onDialogOpening(params);
+        };
+        this._cdpClient.on("Page.javascriptDialogOpening", this._callback, this._sessionId);
+        debug("DialogHandler initialized on session %s", this._sessionId);
+    }
+    /**
+     * Remove event listener and clear handler stack.
+     */
+    detach() {
+        this._initialized = false;
+        if (this._callback) {
+            this._cdpClient.off("Page.javascriptDialogOpening", this._callback);
+            this._callback = null;
+        }
+        // Clear any pending auto-dismiss timers
+        for (const timer of this._pendingTimers) {
+            clearTimeout(timer);
+        }
+        this._pendingTimers.clear();
+        this._handlerStack = [];
+        debug("DialogHandler detached");
+    }
+    /**
+     * Re-initialize after reconnect or tab switch.
+     * Preserves pending notifications (tab-switch should not lose them).
+     */
+    reinit(cdpClient, sessionId) {
+        this.detach();
+        this._cdpClient = cdpClient;
+        this._sessionId = sessionId;
+        this.init();
+    }
+    /**
+     * Push a handler onto the stack. The topmost handler is used for the next dialog.
+     */
+    pushHandler(config) {
+        this._handlerStack.push(config);
+    }
+    /**
+     * Remove and return the topmost handler from the stack.
+     */
+    popHandler() {
+        return this._handlerStack.pop();
+    }
+    /**
+     * Return buffered dialog notifications and clear the buffer.
+     */
+    consumeNotifications() {
+        const copy = [...this._pendingNotifications];
+        this._pendingNotifications = [];
+        return copy;
+    }
+    /**
+     * Number of buffered notifications.
+     */
+    get pendingCount() {
+        return this._pendingNotifications.length;
+    }
+    // --- Internal ---
+    _onDialogOpening(params) {
+        const p = params;
+        const event = {
+            type: p.type ?? "alert",
+            message: p.message ?? "",
+            defaultPrompt: p.defaultPrompt,
+            url: p.url ?? "",
+        };
+        // Buffer notification for next tool response
+        this._pendingNotifications.push(event);
+        // Check handler stack (topmost wins, pop after use — fire-and-forget)
+        const handler = this._handlerStack.pop();
+        if (handler) {
+            // Handler configured — respond immediately
+            const cdpParams = {
+                accept: handler.autoAccept,
+            };
+            // Only include promptText for prompt dialogs
+            if (event.type === "prompt" && handler.promptText !== undefined) {
+                cdpParams.promptText = handler.promptText;
+            }
+            this._handleDialog(cdpParams, event);
+        }
+        else {
+            // No handler configured — auto-dismiss after timeout
+            // beforeunload MUST always be accepted, otherwise navigation is blocked
+            const accept = event.type === "beforeunload";
+            const timer = setTimeout(() => {
+                this._pendingTimers.delete(timer);
+                this._handleDialog({ accept }, event);
+                debug("Dialog auto-dismissed after %dms: %s", this._defaultTimeoutMs, event.message);
+            }, this._defaultTimeoutMs);
+            this._pendingTimers.add(timer);
+        }
+    }
+    _handleDialog(cdpParams, event) {
+        // CRITICAL: try/catch — dialog may already have been handled by other code
+        this._cdpClient
+            .send("Page.handleJavaScriptDialog", cdpParams, this._sessionId)
+            .catch(() => {
+            debug("Dialog already handled or dismissed: %s (%s)", event.type, event.message);
+        });
+    }
+}

package/build/cdp/dom-watcher.d.ts

@@ -0,0 +1,45 @@
+import type { CdpClient } from "./cdp-client.js";
+export interface DomWatcherOptions {
+    debounceMs?: number;
+}
+export declare class DomWatcher {
+    private _cdpClient;
+    private _sessionId;
+    private _debounceMs;
+    private _debounceTimer;
+    private _onRefreshCallback;
+    private _onInvalidateCallback;
+    private _onMutationInvalidateCallback;
+    private _refreshInProgress;
+    private _axChangeWaiters;
+    private _onNodesUpdated;
+    private _onDocumentUpdated;
+    private _onChildCountUpdated;
+    private _onChildInserted;
+    private _onChildRemoved;
+    private _onFrameNavigated;
+    constructor(cdpClient: CdpClient, sessionId: string, options?: DomWatcherOptions);
+    /** Registriert den Callback der bei DOM-Aenderungen (nach Debounce) aufgerufen wird */
+    onRefresh(callback: () => Promise<void>): void;
+    /** Registriert den Callback fuer sofortige Cache-Invalidierung (bei Navigation) */
+    onInvalidate(callback: () => void): void;
+    /** Registriert den Callback fuer sofortige Precomputed-Cache-Invalidierung bei DOM-Mutationen (BUG-010) */
+    onMutationInvalidate(callback: () => void): void;
+    /**
+     * Story 13a.2: Wait for Accessibility.nodesUpdated event within timeout.
+     * Returns true if AX tree changed, false on timeout.
+     */
+    waitForAXChange(timeoutMs: number): Promise<boolean>;
+    /** Startet DOM-Beobachtung: DOM.enable + Event-Listener registrieren */
+    init(): Promise<void>;
+    /** Stoppt Beobachtung und raeumt auf */
+    detach(): void;
+    /** Reconnect: neuer CdpClient, neue SessionId */
+    reinit(cdpClient: CdpClient, sessionId: string): Promise<void>;
+    /** Debounce-Handler: Wird bei jeder DOM-Mutation aufgerufen */
+    private _scheduleMutationRefresh;
+    /** Navigation-Handler: Invalidiert Cache SOFORT (kein Debounce) */
+    private _handleNavigation;
+    /** Fuehrt den Refresh-Callback aus (mit Guard gegen parallele Refreshes) */
+    private _executeRefresh;
+}

package/build/cdp/dom-watcher.js

@@ -0,0 +1,195 @@
+import { debug } from "./debug.js";
+// --- DomWatcher ---
+export class DomWatcher {
+    _cdpClient;
+    _sessionId;
+    _debounceMs;
+    _debounceTimer = null;
+    _onRefreshCallback = null;
+    _onInvalidateCallback = null;
+    _onMutationInvalidateCallback = null;
+    _refreshInProgress = false;
+    // Story 13a.2: Accessibility.nodesUpdated — resolves pending waitForAXChange promises
+    // Each entry: { resolve(changed), cancel() to clear timeout }
+    _axChangeWaiters = [];
+    _onNodesUpdated = null;
+    // Bound callbacks for on/off
+    _onDocumentUpdated = null;
+    _onChildCountUpdated = null;
+    _onChildInserted = null;
+    _onChildRemoved = null;
+    _onFrameNavigated = null;
+    constructor(cdpClient, sessionId, options) {
+        this._cdpClient = cdpClient;
+        this._sessionId = sessionId;
+        this._debounceMs = options?.debounceMs ?? 500;
+    }
+    /** Registriert den Callback der bei DOM-Aenderungen (nach Debounce) aufgerufen wird */
+    onRefresh(callback) {
+        this._onRefreshCallback = callback;
+    }
+    /** Registriert den Callback fuer sofortige Cache-Invalidierung (bei Navigation) */
+    onInvalidate(callback) {
+        this._onInvalidateCallback = callback;
+    }
+    /** Registriert den Callback fuer sofortige Precomputed-Cache-Invalidierung bei DOM-Mutationen (BUG-010) */
+    onMutationInvalidate(callback) {
+        this._onMutationInvalidateCallback = callback;
+    }
+    /**
+     * Story 13a.2: Wait for Accessibility.nodesUpdated event within timeout.
+     * Returns true if AX tree changed, false on timeout.
+     */
+    waitForAXChange(timeoutMs) {
+        return new Promise((resolve) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (!settled) {
+                    settled = true;
+                    this._axChangeWaiters = this._axChangeWaiters.filter((w) => w.resolve !== resolve);
+                    resolve(false);
+                }
+            }, timeoutMs);
+            this._axChangeWaiters.push({
+                resolve: (changed) => { if (!settled) {
+                    settled = true;
+                    clearTimeout(timer);
+                    resolve(changed);
+                } },
+                cancel: () => clearTimeout(timer),
+            });
+        });
+    }
+    /** Startet DOM-Beobachtung: DOM.enable + Event-Listener registrieren */
+    async init() {
+        // DOM.enable ist idempotent — doppeltes Enable schadet nicht
+        await this._cdpClient.send("DOM.enable", {}, this._sessionId);
+        this._onDocumentUpdated = () => this._scheduleMutationRefresh();
+        this._onChildCountUpdated = () => this._scheduleMutationRefresh();
+        this._onChildInserted = () => this._scheduleMutationRefresh();
+        this._onChildRemoved = () => this._scheduleMutationRefresh();
+        this._onFrameNavigated = (params) => this._handleNavigation(params);
+        // Story 13a.2: Subscribe to Accessibility.nodesUpdated for post-click detection
+        this._onNodesUpdated = () => {
+            debug("DomWatcher: Accessibility.nodesUpdated received");
+            const waiters = [...this._axChangeWaiters];
+            this._axChangeWaiters = [];
+            for (const w of waiters)
+                w.resolve(true);
+        };
+        this._cdpClient.on("DOM.documentUpdated", this._onDocumentUpdated, this._sessionId);
+        this._cdpClient.on("DOM.childNodeCountUpdated", this._onChildCountUpdated, this._sessionId);
+        this._cdpClient.on("DOM.childNodeInserted", this._onChildInserted, this._sessionId);
+        this._cdpClient.on("DOM.childNodeRemoved", this._onChildRemoved, this._sessionId);
+        this._cdpClient.on("Page.frameNavigated", this._onFrameNavigated, this._sessionId);
+        this._cdpClient.on("Accessibility.nodesUpdated", this._onNodesUpdated, this._sessionId);
+        debug("DomWatcher initialized on session %s", this._sessionId);
+    }
+    /** Stoppt Beobachtung und raeumt auf */
+    detach() {
+        // Cancel pending debounce timer
+        if (this._debounceTimer) {
+            clearTimeout(this._debounceTimer);
+            this._debounceTimer = null;
+        }
+        // Remove all event listeners
+        if (this._onDocumentUpdated) {
+            this._cdpClient.off("DOM.documentUpdated", this._onDocumentUpdated);
+            this._onDocumentUpdated = null;
+        }
+        if (this._onChildCountUpdated) {
+            this._cdpClient.off("DOM.childNodeCountUpdated", this._onChildCountUpdated);
+            this._onChildCountUpdated = null;
+        }
+        if (this._onChildInserted) {
+            this._cdpClient.off("DOM.childNodeInserted", this._onChildInserted);
+            this._onChildInserted = null;
+        }
+        if (this._onChildRemoved) {
+            this._cdpClient.off("DOM.childNodeRemoved", this._onChildRemoved);
+            this._onChildRemoved = null;
+        }
+        if (this._onFrameNavigated) {
+            this._cdpClient.off("Page.frameNavigated", this._onFrameNavigated);
+            this._onFrameNavigated = null;
+        }
+        if (this._onNodesUpdated) {
+            this._cdpClient.off("Accessibility.nodesUpdated", this._onNodesUpdated);
+            this._onNodesUpdated = null;
+        }
+        // Story 13a.2: Resolve any pending AX change waiters as false (detach = no change)
+        const waiters = [...this._axChangeWaiters];
+        this._axChangeWaiters = [];
+        for (const w of waiters) {
+            w.cancel();
+            w.resolve(false);
+        }
+        // NICHT DOM.disable — andere Komponenten koennten es brauchen
+        debug("DomWatcher detached");
+    }
+    /** Reconnect: neuer CdpClient, neue SessionId */
+    async reinit(cdpClient, sessionId) {
+        this.detach();
+        this._cdpClient = cdpClient;
+        this._sessionId = sessionId;
+        await this.init();
+    }
+    /** Debounce-Handler: Wird bei jeder DOM-Mutation aufgerufen */
+    _scheduleMutationRefresh() {
+        // H2 fix: Do NOT invalidate selector cache immediately on DOM mutations.
+        // The debounced refresh will compute a new fingerprint, and any stale
+        // cache entries will self-heal via fingerprint mismatch on next access.
+        // BUG-010 fix: Immediately invalidate precomputed A11y-tree cache so the next
+        // getTree() call fetches fresh data from CDP instead of serving stale cache.
+        // This is idempotent and cheap (just nulls the cached nodes array).
+        if (this._onMutationInvalidateCallback) {
+            this._onMutationInvalidateCallback();
+        }
+        // Cancel existing timer
+        if (this._debounceTimer) {
+            clearTimeout(this._debounceTimer);
+        }
+        // Set new timer
+        this._debounceTimer = setTimeout(() => {
+            this._debounceTimer = null;
+            this._executeRefresh();
+        }, this._debounceMs);
+        debug("DomWatcher: DOM mutation detected, scheduling refresh");
+    }
+    /** Navigation-Handler: Invalidiert Cache SOFORT (kein Debounce) */
+    _handleNavigation(params) {
+        const p = params;
+        // Nur main-frame Navigation (parentId ist undefined/leer fuer main frame)
+        if (p.frame?.parentId)
+            return; // iframe navigation — ignorieren
+        // Cancel pending debounce timer
+        if (this._debounceTimer) {
+            clearTimeout(this._debounceTimer);
+            this._debounceTimer = null;
+        }
+        // Cache sofort invalidieren
+        if (this._onInvalidateCallback) {
+            this._onInvalidateCallback();
+        }
+        debug("DomWatcher: main frame navigation detected, cache invalidated");
+        // H2: Hintergrund-Refresh nach Navigation triggern (AC #4)
+        // Kurzer Delay damit die neue Seite settlen kann
+        this._scheduleMutationRefresh();
+    }
+    /** Fuehrt den Refresh-Callback aus (mit Guard gegen parallele Refreshes) */
+    async _executeRefresh() {
+        if (this._refreshInProgress)
+            return; // letzter Refresh laeuft noch
+        if (!this._onRefreshCallback)
+            return;
+        this._refreshInProgress = true;
+        try {
+            await this._onRefreshCallback();
+        }
+        catch {
+            // silent — Hintergrund-Refresh soll Server nicht lahmlegen
+            debug("DomWatcher: background refresh failed (ignored)");
+        }
+        this._refreshInProgress = false;
+    }
+}

package/build/cdp/emulation.d.ts

@@ -0,0 +1,12 @@
+export declare const EMULATED_WIDTH = 1280;
+export declare const EMULATED_HEIGHT = 800;
+export declare const DEVICE_SCALE_FACTOR = 1;
+export declare const MOBILE = false;
+export declare const DEVICE_METRICS_OVERRIDE: {
+    readonly width: 1280;
+    readonly height: 800;
+    readonly deviceScaleFactor: 1;
+    readonly mobile: false;
+};
+export declare function setHeadless(value: boolean): void;
+export declare function isHeadless(): boolean;

package/build/cdp/emulation.js

@@ -0,0 +1,17 @@
+export const EMULATED_WIDTH = 1280;
+export const EMULATED_HEIGHT = 800;
+export const DEVICE_SCALE_FACTOR = 1;
+export const MOBILE = false;
+export const DEVICE_METRICS_OVERRIDE = {
+    width: EMULATED_WIDTH,
+    height: EMULATED_HEIGHT,
+    deviceScaleFactor: DEVICE_SCALE_FACTOR,
+    mobile: MOBILE,
+};
+/**
+ * Runtime headless state, set once after connection is established.
+ * Used by tools (e.g. switch-tab) to decide emulation vs window-resize.
+ */
+let _headless = true;
+export function setHeadless(value) { _headless = value; }
+export function isHeadless() { return _headless; }

package/build/cdp/index.d.ts

@@ -0,0 +1,11 @@
+export { CdpClient } from "./cdp-client.js";
+export type { CdpClientOptions } from "./cdp-client.js";
+export type { CdpRequest, CdpResponse, CdpEvent, CdpError } from "./protocol.js";
+export { EMULATED_WIDTH, EMULATED_HEIGHT, DEVICE_SCALE_FACTOR, MOBILE, DEVICE_METRICS_OVERRIDE, } from "./emulation.js";
+export { ChromeLauncher, ChromeConnection, findChromePath, launchChrome, } from "./chrome-launcher.js";
+export type { ChromeConnectionOptions, LaunchOptions } from "./chrome-launcher.js";
+export { debug } from "./debug.js";
+export { settle } from "./settle.js";
+export type { SettleOptions, SettleResult } from "./settle.js";
+export { DomWatcher } from "./dom-watcher.js";
+export type { DomWatcherOptions } from "./dom-watcher.js";

package/build/cdp/index.js

@@ -0,0 +1,6 @@
+export { CdpClient } from "./cdp-client.js";
+export { EMULATED_WIDTH, EMULATED_HEIGHT, DEVICE_SCALE_FACTOR, MOBILE, DEVICE_METRICS_OVERRIDE, } from "./emulation.js";
+export { ChromeLauncher, ChromeConnection, findChromePath, launchChrome, } from "./chrome-launcher.js";
+export { debug } from "./debug.js";
+export { settle } from "./settle.js";
+export { DomWatcher } from "./dom-watcher.js";

package/build/cdp/network-collector.d.ts

@@ -0,0 +1,77 @@
+import type { CdpClient } from "./cdp-client.js";
+export interface NetworkRequestEntry {
+    url: string;
+    method: string;
+    status: number;
+    mimeType: string;
+    size: number;
+    duration: number;
+    initiator: string;
+    failed: boolean;
+    errorText?: string;
+}
+export interface NetworkCollectorOptions {
+    maxEntries?: number;
+    maxPending?: number;
+}
+export declare class NetworkCollector {
+    private _buffer;
+    private _pending;
+    private _maxEntries;
+    private _maxPending;
+    private _cdpClient;
+    private _sessionId;
+    private _monitoring;
+    private _monitoringSince;
+    private _callbacks;
+    constructor(cdpClient: CdpClient, sessionId: string, options?: NetworkCollectorOptions);
+    /**
+     * Start Network monitoring. Calls Network.enable and registers 4 event listeners.
+     * Idempotent — calling twice has no effect.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop Network monitoring. Returns collected requests, clears buffer, calls Network.disable.
+     * If not monitoring, returns empty array (graceful).
+     */
+    stop(): Promise<NetworkRequestEntry[]>;
+    /**
+     * Remove event listeners without calling Network.disable (for shutdown — sync, no CDP call).
+     */
+    detach(): void;
+    /**
+     * Re-initialize after reconnect or tab switch.
+     * Detaches, sets new client/session, clears buffer.
+     * Monitoring stays OFF — agent must call start() again.
+     */
+    reinit(cdpClient: CdpClient, sessionId: string): void;
+    /**
+     * Return a copy of all buffered request entries.
+     */
+    getAll(): NetworkRequestEntry[];
+    /**
+     * Return filtered request entries. Both filters are combined with AND.
+     * Throws if the regex pattern is invalid.
+     */
+    getFiltered(filter?: string, pattern?: string): NetworkRequestEntry[];
+    get isMonitoring(): boolean;
+    get monitoringSince(): number;
+    get count(): number;
+    private _removeListeners;
+    private _pushEntry;
+    /**
+     * H3: Flush all pending requests into the ring buffer as incomplete entries.
+     * Called by stop() so in-flight requests are not silently discarded.
+     */
+    private _flushPending;
+    /**
+     * H2: Evict oldest pending entries when the pending map exceeds _maxPending.
+     * Evicted entries are pushed into the ring buffer as incomplete.
+     */
+    private _evictOldestPending;
+    private _finishRequest;
+    private _onRequestWillBeSent;
+    private _onResponseReceived;
+    private _onLoadingFinished;
+    private _onLoadingFailed;
+}