@silbercue/chrome 0.2.0

package/build/cache/index.d.ts

@@ -0,0 +1,8 @@
+export { A11yTreeProcessor, a11yTree, RefNotFoundError } from "./a11y-tree.js";
+export type { TreeOptions, TreeResult, AXNode } from "./a11y-tree.js";
+export { TabStateCache } from "./tab-state-cache.js";
+export type { TabState, TabStateCacheOptions } from "./tab-state-cache.js";
+export { SessionDefaults } from "./session-defaults.js";
+export type { SessionDefaultsOptions, PromoteSuggestion } from "./session-defaults.js";
+export { SelectorCache, selectorCache } from "./selector-cache.js";
+export type { SelectorCacheEntry, SelectorCacheOptions } from "./selector-cache.js";

package/build/cache/index.js

@@ -0,0 +1,4 @@
+export { A11yTreeProcessor, a11yTree, RefNotFoundError } from "./a11y-tree.js";
+export { TabStateCache } from "./tab-state-cache.js";
+export { SessionDefaults } from "./session-defaults.js";
+export { SelectorCache, selectorCache } from "./selector-cache.js";

package/build/cache/selector-cache.d.ts

@@ -0,0 +1,47 @@
+export interface SelectorCacheEntry {
+    backendNodeId: number;
+    fingerprint: string;
+    sessionId: string;
+    cachedAt: number;
+}
+export interface SelectorCacheOptions {
+    maxEntries?: number;
+    ttlMs?: number;
+}
+export declare class SelectorCache {
+    private _cache;
+    private _currentFingerprint;
+    private _maxEntries;
+    private _ttlMs;
+    constructor(options?: SelectorCacheOptions);
+    /**
+     * Compute a DOM fingerprint from URL and node count.
+     * Lightweight — no DOMSnapshot, no A11y-Tree.
+     */
+    computeFingerprint(url: string, nodeCount: number): string;
+    /** Set the current DOM fingerprint (called after each ref resolution or tree refresh) */
+    updateFingerprint(fingerprint: string): void;
+    /**
+     * Lookup: Check if a cached selector for this ref exists.
+     * Returns entry if cache hit AND fingerprint matches.
+     * Returns undefined on miss or fingerprint mismatch.
+     */
+    get(ref: string): SelectorCacheEntry | undefined;
+    /**
+     * Store a resolved ref in the cache.
+     * Called after successful ref resolution.
+     * When url and nodeCount are provided, computes an on-the-fly fingerprint
+     * if none is active yet (fixes cold-cache after navigation — H1).
+     */
+    set(ref: string, backendNodeId: number, sessionId: string, url?: string, nodeCount?: number): void;
+    /** Invalidate the entire cache (e.g. on navigation, reconnect) */
+    invalidate(): void;
+    /** Remove only entries that don't match the current fingerprint */
+    pruneStale(): void;
+    /** Cache statistics for debugging */
+    getStats(): {
+        size: number;
+        fingerprint: string;
+    };
+}
+export declare const selectorCache: SelectorCache;

package/build/cache/selector-cache.js

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+import { debug } from "../cdp/debug.js";
+// --- SelectorCache ---
+export class SelectorCache {
+    _cache = new Map();
+    _currentFingerprint = "";
+    _maxEntries;
+    _ttlMs;
+    constructor(options) {
+        this._maxEntries = options?.maxEntries ?? 200;
+        this._ttlMs = options?.ttlMs ?? 300_000;
+    }
+    /**
+     * Compute a DOM fingerprint from URL and node count.
+     * Lightweight — no DOMSnapshot, no A11y-Tree.
+     */
+    computeFingerprint(url, nodeCount) {
+        // Strip hash/fragment from URL for normalization
+        const normalizedUrl = url.split("#")[0];
+        return createHash("sha256")
+            .update(normalizedUrl + "|" + nodeCount)
+            .digest("hex")
+            .substring(0, 16);
+    }
+    /** Set the current DOM fingerprint (called after each ref resolution or tree refresh) */
+    updateFingerprint(fingerprint) {
+        if (fingerprint !== this._currentFingerprint) {
+            this._currentFingerprint = fingerprint;
+            debug("SelectorCache: fingerprint updated: %s", fingerprint);
+        }
+    }
+    /**
+     * Lookup: Check if a cached selector for this ref exists.
+     * Returns entry if cache hit AND fingerprint matches.
+     * Returns undefined on miss or fingerprint mismatch.
+     */
+    get(ref) {
+        const entry = this._cache.get(ref);
+        if (!entry) {
+            return undefined;
+        }
+        // Fingerprint mismatch — DOM has changed
+        if (entry.fingerprint !== this._currentFingerprint) {
+            this._cache.delete(ref);
+            debug("SelectorCache: fingerprint mismatch for %s, invalidating entry", ref);
+            return undefined;
+        }
+        // TTL expired
+        if (Date.now() - entry.cachedAt >= this._ttlMs) {
+            this._cache.delete(ref);
+            debug("SelectorCache: TTL expired for %s", ref);
+            return undefined;
+        }
+        return entry;
+    }
+    /**
+     * Store a resolved ref in the cache.
+     * Called after successful ref resolution.
+     * When url and nodeCount are provided, computes an on-the-fly fingerprint
+     * if none is active yet (fixes cold-cache after navigation — H1).
+     */
+    set(ref, backendNodeId, sessionId, url, nodeCount) {
+        // Compute on-the-fly fingerprint if none active but URL is known (H1 fix)
+        if (!this._currentFingerprint && url !== undefined && nodeCount !== undefined) {
+            const fp = this.computeFingerprint(url, nodeCount);
+            this.updateFingerprint(fp);
+            debug("SelectorCache: on-the-fly fingerprint from set(): %s", fp);
+        }
+        // Still no fingerprint — can't cache
+        if (!this._currentFingerprint)
+            return;
+        // Evict oldest entry if at capacity
+        if (this._cache.size >= this._maxEntries && !this._cache.has(ref)) {
+            let oldestKey = null;
+            let oldestTime = Infinity;
+            for (const [key, entry] of this._cache) {
+                if (entry.cachedAt < oldestTime) {
+                    oldestTime = entry.cachedAt;
+                    oldestKey = key;
+                }
+            }
+            if (oldestKey !== null) {
+                this._cache.delete(oldestKey);
+            }
+        }
+        this._cache.set(ref, {
+            backendNodeId,
+            fingerprint: this._currentFingerprint,
+            sessionId,
+            cachedAt: Date.now(),
+        });
+    }
+    /** Invalidate the entire cache (e.g. on navigation, reconnect) */
+    invalidate() {
+        const count = this._cache.size;
+        this._cache.clear();
+        this._currentFingerprint = "";
+        if (count > 0) {
+            debug("SelectorCache: invalidated (%d entries cleared)", count);
+        }
+    }
+    /** Remove only entries that don't match the current fingerprint */
+    pruneStale() {
+        for (const [key, entry] of this._cache) {
+            if (entry.fingerprint !== this._currentFingerprint) {
+                this._cache.delete(key);
+            }
+        }
+    }
+    /** Cache statistics for debugging */
+    getStats() {
+        return {
+            size: this._cache.size,
+            fingerprint: this._currentFingerprint,
+        };
+    }
+}
+// --- Singleton ---
+export const selectorCache = new SelectorCache();

package/build/cache/session-defaults.d.ts

@@ -0,0 +1,27 @@
+export interface SessionDefaultsOptions {
+    promoteThreshold?: number;
+    slidingWindowSize?: number;
+}
+export interface PromoteSuggestion {
+    param: string;
+    value: unknown;
+    count: number;
+    tool: string;
+}
+export declare class SessionDefaults {
+    private _defaults;
+    private _callHistory;
+    private _promoteThreshold;
+    private _slidingWindowSize;
+    private _pendingSuggestions;
+    constructor(options?: SessionDefaultsOptions);
+    setDefault(param: string, value: unknown): void;
+    getDefault(param: string): unknown | undefined;
+    getAllDefaults(): Record<string, unknown>;
+    clearAll(): void;
+    resolveParams(tool: string, params: Record<string, unknown>): Record<string, unknown>;
+    trackCall(tool: string, params: Record<string, unknown>): void;
+    getSuggestions(): PromoteSuggestion[];
+    applyAllSuggestions(): Record<string, unknown>;
+    private _analyzeForPromotions;
+}

package/build/cache/session-defaults.js

@@ -0,0 +1,130 @@
+export class SessionDefaults {
+    _defaults;
+    _callHistory;
+    _promoteThreshold;
+    _slidingWindowSize;
+    _pendingSuggestions;
+    constructor(options) {
+        this._defaults = new Map();
+        this._callHistory = [];
+        this._promoteThreshold = options?.promoteThreshold ?? 3;
+        this._slidingWindowSize = options?.slidingWindowSize ?? 10;
+        this._pendingSuggestions = [];
+    }
+    // --- Default-Verwaltung ---
+    setDefault(param, value) {
+        if (value === null) {
+            this._defaults.delete(param);
+        }
+        else {
+            this._defaults.set(param, value);
+        }
+    }
+    getDefault(param) {
+        return this._defaults.get(param);
+    }
+    getAllDefaults() {
+        const result = {};
+        for (const [key, value] of this._defaults) {
+            result[key] = value;
+        }
+        return result;
+    }
+    clearAll() {
+        this._defaults.clear();
+        this._callHistory = [];
+        this._pendingSuggestions = [];
+    }
+    // --- Default-Resolution (Kernmethode) ---
+    resolveParams(tool, params) {
+        const resolved = { ...params };
+        for (const [key, defaultValue] of this._defaults) {
+            if (resolved[key] === undefined) {
+                resolved[key] = defaultValue;
+            }
+        }
+        return resolved;
+    }
+    // --- Auto-Promote-Tracking ---
+    trackCall(tool, params) {
+        this._callHistory.push({ tool, params });
+        // Front-trunc: keep only the last _slidingWindowSize entries
+        if (this._callHistory.length > this._slidingWindowSize) {
+            this._callHistory = this._callHistory.slice(-this._slidingWindowSize);
+        }
+        this._analyzeForPromotions();
+    }
+    getSuggestions() {
+        return [...this._pendingSuggestions];
+    }
+    applyAllSuggestions() {
+        const applied = {};
+        for (const suggestion of this._pendingSuggestions) {
+            this.setDefault(suggestion.param, suggestion.value);
+            applied[suggestion.param] = suggestion.value;
+        }
+        this._pendingSuggestions = [];
+        return applied;
+    }
+    // --- Private ---
+    _analyzeForPromotions() {
+        // Collect all param names from the call history
+        const paramNames = new Set();
+        for (const call of this._callHistory) {
+            for (const key of Object.keys(call.params)) {
+                paramNames.add(key);
+            }
+        }
+        const newSuggestions = [];
+        for (const param of paramNames) {
+            // Skip if already a default
+            if (this._defaults.has(param))
+                continue;
+            // Count consecutive identical values from the END of the history
+            let count = 0;
+            let lastValue = undefined;
+            let lastTool = "";
+            for (let i = this._callHistory.length - 1; i >= 0; i--) {
+                const call = this._callHistory[i];
+                const value = call.params[param];
+                // Skip calls that don't have this param
+                if (value === undefined)
+                    break;
+                // Only compare primitives (string, number, boolean)
+                if (typeof value === "object" || typeof value === "function" || typeof value === "symbol")
+                    break;
+                if (count === 0) {
+                    lastValue = value;
+                    lastTool = call.tool;
+                    count = 1;
+                }
+                else if (value === lastValue) {
+                    count++;
+                }
+                else {
+                    break;
+                }
+            }
+            if (count >= this._promoteThreshold) {
+                newSuggestions.push({
+                    param,
+                    value: lastValue,
+                    count,
+                    tool: lastTool,
+                });
+            }
+        }
+        // Merge new suggestions into pending (update count for existing param, add new ones)
+        for (const newSugg of newSuggestions) {
+            const existingIdx = this._pendingSuggestions.findIndex((s) => s.param === newSugg.param);
+            if (existingIdx >= 0) {
+                this._pendingSuggestions[existingIdx] = newSugg;
+            }
+            else {
+                this._pendingSuggestions.push(newSugg);
+            }
+        }
+        // Remove suggestions for params that dropped below threshold or changed value
+        this._pendingSuggestions = this._pendingSuggestions.filter((s) => newSuggestions.some((n) => n.param === s.param));
+    }
+}

package/build/cache/tab-state-cache.d.ts

@@ -0,0 +1,39 @@
+import type { CdpClient } from "../cdp/cdp-client.js";
+export interface TabState {
+    url: string;
+    title: string;
+    domReady: boolean;
+    consoleErrors: string[];
+    loadingState: "loading" | "ready";
+    lastUpdated: number;
+}
+export interface TabStateCacheOptions {
+    ttlMs?: number;
+    maxConsoleErrors?: number;
+}
+export declare class TabStateCache {
+    private readonly _cache;
+    private readonly _pendingErrors;
+    private readonly _ttlMs;
+    private readonly _maxConsoleErrors;
+    private _activeTargetId;
+    private _listeners;
+    private _cdpClient;
+    constructor(options?: TabStateCacheOptions);
+    get activeTargetId(): string | null;
+    setActiveTarget(targetId: string): void;
+    get(targetId: string): TabState | null;
+    set(targetId: string, state: Partial<TabState>): void;
+    invalidate(targetId: string): void;
+    invalidateAll(): void;
+    addConsoleError(targetId: string, error: string): void;
+    has(targetId: string): boolean;
+    size(): number;
+    attachToClient(cdpClient: CdpClient, sessionId?: string): void;
+    detachFromClient(): void;
+    getOrFetch(cdpClient: CdpClient, targetId: string, sessionId?: string): Promise<{
+        state: TabState;
+        cacheHit: boolean;
+    }>;
+    private _fetchFromCdp;
+}

package/build/cache/tab-state-cache.js

@@ -0,0 +1,171 @@
+export class TabStateCache {
+    _cache = new Map();
+    _pendingErrors = new Map();
+    _ttlMs;
+    _maxConsoleErrors;
+    _activeTargetId = null;
+    _listeners = [];
+    _cdpClient = null;
+    constructor(options) {
+        this._ttlMs = options?.ttlMs ?? 30_000;
+        this._maxConsoleErrors = options?.maxConsoleErrors ?? 10;
+    }
+    get activeTargetId() {
+        return this._activeTargetId;
+    }
+    setActiveTarget(targetId) {
+        this._activeTargetId = targetId;
+    }
+    get(targetId) {
+        const entry = this._cache.get(targetId);
+        if (!entry)
+            return null;
+        if (Date.now() - entry.lastUpdated > this._ttlMs)
+            return null;
+        return entry;
+    }
+    set(targetId, state) {
+        const existing = this._cache.get(targetId);
+        if (existing) {
+            this._cache.set(targetId, {
+                ...existing,
+                ...state,
+                lastUpdated: Date.now(),
+            });
+        }
+        else {
+            this._cache.set(targetId, {
+                url: "",
+                title: "",
+                domReady: false,
+                consoleErrors: [],
+                loadingState: "loading",
+                ...state,
+                lastUpdated: Date.now(),
+            });
+        }
+    }
+    invalidate(targetId) {
+        this._cache.delete(targetId);
+    }
+    invalidateAll() {
+        this._cache.clear();
+    }
+    addConsoleError(targetId, error) {
+        const entry = this._cache.get(targetId);
+        if (entry) {
+            entry.consoleErrors.push(error);
+            if (entry.consoleErrors.length > this._maxConsoleErrors) {
+                entry.consoleErrors = entry.consoleErrors.slice(entry.consoleErrors.length - this._maxConsoleErrors);
+            }
+        }
+        else {
+            // No full cache entry yet — buffer errors for later merge during CDP fetch
+            let pending = this._pendingErrors.get(targetId);
+            if (!pending) {
+                pending = [];
+                this._pendingErrors.set(targetId, pending);
+            }
+            pending.push(error);
+            if (pending.length > this._maxConsoleErrors) {
+                this._pendingErrors.set(targetId, pending.slice(pending.length - this._maxConsoleErrors));
+            }
+        }
+    }
+    has(targetId) {
+        return this.get(targetId) !== null;
+    }
+    size() {
+        return this._cache.size;
+    }
+    attachToClient(cdpClient, sessionId) {
+        this._cdpClient = cdpClient;
+        const onFrameNavigated = (params) => {
+            const p = params;
+            if (!p.frame.parentId && this._activeTargetId) {
+                const targetId = this._activeTargetId;
+                this.invalidate(targetId);
+                // H3: Auto-prefill cache after invalidation (fire-and-forget)
+                this._fetchFromCdp(cdpClient, targetId, sessionId)
+                    .then((state) => this._cache.set(targetId, state))
+                    .catch(() => {
+                    /* prefill is best-effort */
+                });
+            }
+        };
+        const onNavigatedWithinDocument = () => {
+            if (this._activeTargetId) {
+                this.invalidate(this._activeTargetId);
+            }
+        };
+        const onDomContentEventFired = () => {
+            if (this._activeTargetId) {
+                const existing = this._cache.get(this._activeTargetId);
+                if (existing) {
+                    existing.domReady = true;
+                }
+            }
+        };
+        const onExceptionThrown = (params) => {
+            const p = params;
+            const msg = p.exceptionDetails.exception?.description || p.exceptionDetails.text;
+            if (this._activeTargetId) {
+                this.addConsoleError(this._activeTargetId, msg);
+            }
+        };
+        cdpClient.on("Page.frameNavigated", onFrameNavigated, sessionId);
+        cdpClient.on("Page.navigatedWithinDocument", onNavigatedWithinDocument, sessionId);
+        cdpClient.on("Page.domContentEventFired", onDomContentEventFired, sessionId);
+        cdpClient.on("Runtime.exceptionThrown", onExceptionThrown, sessionId);
+        this._listeners = [
+            { method: "Page.frameNavigated", callback: onFrameNavigated },
+            { method: "Page.navigatedWithinDocument", callback: onNavigatedWithinDocument },
+            { method: "Page.domContentEventFired", callback: onDomContentEventFired },
+            { method: "Runtime.exceptionThrown", callback: onExceptionThrown },
+        ];
+    }
+    detachFromClient() {
+        if (this._cdpClient) {
+            for (const { method, callback } of this._listeners) {
+                this._cdpClient.off(method, callback);
+            }
+        }
+        this._listeners = [];
+        this._cdpClient = null;
+    }
+    async getOrFetch(cdpClient, targetId, sessionId) {
+        const cached = this.get(targetId);
+        if (cached) {
+            return { state: cached, cacheHit: true };
+        }
+        const state = await this._fetchFromCdp(cdpClient, targetId, sessionId);
+        this._cache.set(targetId, state);
+        return { state, cacheHit: false };
+    }
+    async _fetchFromCdp(cdpClient, targetId, sessionId) {
+        const [navHistory, readyState] = await Promise.all([
+            cdpClient.send("Page.getNavigationHistory", {}, sessionId),
+            cdpClient.send("Runtime.evaluate", { expression: "document.readyState", returnByValue: true }, sessionId),
+        ]);
+        const currentEntry = navHistory.entries[navHistory.currentIndex];
+        // Merge console errors: existing (stale) cache entry + pending (buffered) errors
+        const existingErrors = this._cache.get(targetId)?.consoleErrors ?? [];
+        const pendingErrors = this._pendingErrors.get(targetId) ?? [];
+        const mergedErrors = [...existingErrors, ...pendingErrors];
+        // Cap at maxConsoleErrors (keep most recent)
+        const consoleErrors = mergedErrors.length > this._maxConsoleErrors
+            ? mergedErrors.slice(mergedErrors.length - this._maxConsoleErrors)
+            : mergedErrors;
+        // H1: Consume pending errors — prevent memory leak
+        this._pendingErrors.delete(targetId);
+        return {
+            url: currentEntry.url,
+            title: currentEntry.title,
+            domReady: readyState.result.value === "interactive" ||
+                readyState.result.value === "complete",
+            consoleErrors,
+            loadingState: readyState.result.value === "complete" ? "ready" : "loading",
+            lastUpdated: Date.now(),
+        };
+    }
+}

package/build/cdp/cdp-client.d.ts

@@ -0,0 +1,25 @@
+import type { CdpTransport } from "../transport/transport.js";
+export interface CdpClientOptions {
+    timeoutMs?: number;
+}
+type EventCallback = (params: unknown, sessionId?: string) => void;
+export declare class CdpClient {
+    private readonly transport;
+    private _nextId;
+    private readonly _pending;
+    private readonly _listeners;
+    private readonly _onceListeners;
+    private readonly _timeoutMs;
+    private _closed;
+    private _onCloseCallback;
+    constructor(transport: CdpTransport, options?: CdpClientOptions);
+    send<T = unknown>(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<T>;
+    on(method: string, callback: EventCallback, sessionId?: string): void;
+    once(method: string, callback: EventCallback, sessionId?: string): void;
+    off(method: string, callback: EventCallback): void;
+    onClose(callback: () => void): void;
+    close(): Promise<void>;
+    private _dispatch;
+    private _rejectAll;
+}
+export {};