claw-browser-automation 0.2.0

package/dist/pool/browser-pool.d.ts

@@ -0,0 +1,48 @@
+import type { LaunchOptions } from "playwright-core";
+import type { Logger } from "../observe/logger.js";
+import { BrowserSession } from "../session/session.js";
+export interface PoolConfig {
+    maxContexts?: number;
+    launchOptions?: LaunchOptions;
+    healthCheckIntervalMs?: number;
+    logger?: Logger;
+}
+export interface PoolStatus {
+    running: boolean;
+    activeSessions: number;
+    maxContexts: number;
+    sessions: Array<{
+        id: string;
+        url: string;
+        healthy: boolean;
+        profile: string | undefined;
+    }>;
+}
+export interface AcquireOptions {
+    profile?: string;
+    url?: string;
+}
+export declare class BrowserPool {
+    private _browser;
+    private _sessions;
+    private _health;
+    private _maxContexts;
+    private _launchOptions;
+    private _log;
+    private _launching;
+    private _shuttingDown;
+    constructor(config?: PoolConfig);
+    acquire(opts?: AcquireOptions): Promise<BrowserSession>;
+    release(session: BrowserSession): Promise<void>;
+    destroy(sessionId: string): Promise<void>;
+    getSession(sessionId: string): BrowserSession | undefined;
+    listSessions(): BrowserSession[];
+    status(): PoolStatus;
+    shutdown(): Promise<void>;
+    private _ensureBrowser;
+    private _launchBrowser;
+    private _persistProfileSnapshot;
+    private _handleUnhealthy;
+    private _recoverUnhealthy;
+}
+//# sourceMappingURL=browser-pool.d.ts.map

package/dist/pool/browser-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-pool.d.ts","sourceRoot":"","sources":["../../src/pool/browser-pool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAGnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAKvD,MAAM,WAAW,UAAU;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC,CAAC;CAC5F;AAED,MAAM,WAAW,cAAc;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,qBAAa,WAAW;IACvB,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,SAAS,CAA0C;IAC3D,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,UAAU,CAAiC;IACnD,OAAO,CAAC,aAAa,CAAS;gBAElB,MAAM,GAAE,UAAe;IAc7B,OAAO,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;IAyC3D,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ/C,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa/C,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIzD,YAAY,IAAI,cAAc,EAAE;IAIhC,MAAM,IAAI,UAAU;IAcd,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;YA2BjB,cAAc;YAkBd,cAAc;YAuBd,uBAAuB;IAerC,OAAO,CAAC,gBAAgB;YAMV,iBAAiB;CAmD/B"}

package/dist/pool/browser-pool.js

@@ -0,0 +1,216 @@
+import { chromium } from "playwright-core";
+import { createLogger } from "../observe/logger.js";
+import { ensureProfileDir, loadProfileSnapshot, saveProfileSnapshot } from "../session/profiles.js";
+import { BrowserSession } from "../session/session.js";
+import { HealthMonitor } from "./health.js";
+export class BrowserPool {
+    _browser = null;
+    _sessions = new Map();
+    _health;
+    _maxContexts;
+    _launchOptions;
+    _log;
+    _launching = null;
+    _shuttingDown = false;
+    constructor(config = {}) {
+        this._maxContexts = config.maxContexts ?? 4;
+        this._launchOptions = config.launchOptions ?? {};
+        this._log = config.logger ?? createLogger("browser-pool");
+        const healthOpts = {
+            onUnhealthy: (session) => this._handleUnhealthy(session),
+        };
+        if (config.healthCheckIntervalMs !== undefined) {
+            healthOpts.intervalMs = config.healthCheckIntervalMs;
+        }
+        this._health = new HealthMonitor(this._log, healthOpts);
+    }
+    async acquire(opts = {}) {
+        if (this._sessions.size >= this._maxContexts) {
+            throw new Error(`pool limit reached: ${this._sessions.size}/${this._maxContexts} contexts in use`);
+        }
+        let profileSnapshot;
+        if (opts.profile) {
+            ensureProfileDir(opts.profile);
+            profileSnapshot = loadProfileSnapshot(opts.profile);
+        }
+        const browser = await this._ensureBrowser();
+        const context = await browser.newContext();
+        const page = await context.newPage();
+        const session = new BrowserSession({
+            context,
+            page,
+            profile: opts.profile,
+            logger: this._log,
+        });
+        if (profileSnapshot) {
+            await session.restore(profileSnapshot);
+        }
+        if (opts.url) {
+            await page.goto(opts.url, { waitUntil: "domcontentloaded" });
+        }
+        this._sessions.set(session.id, session);
+        this._health.track(session);
+        this._log.info({ sessionId: session.id, profile: opts.profile, url: opts.url }, "session acquired");
+        return session;
+    }
+    async release(session) {
+        await this._persistProfileSnapshot(session);
+        this._health.untrack(session.id);
+        this._sessions.delete(session.id);
+        await session.close();
+        this._log.info({ sessionId: session.id }, "session released");
+    }
+    async destroy(sessionId) {
+        const session = this._sessions.get(sessionId);
+        if (!session) {
+            this._log.warn({ sessionId }, "destroy called on unknown session");
+            return;
+        }
+        await this._persistProfileSnapshot(session);
+        this._health.untrack(sessionId);
+        this._sessions.delete(sessionId);
+        await session.close();
+        this._log.info({ sessionId }, "session destroyed");
+    }
+    getSession(sessionId) {
+        return this._sessions.get(sessionId);
+    }
+    listSessions() {
+        return [...this._sessions.values()];
+    }
+    status() {
+        return {
+            running: this._browser !== null,
+            activeSessions: this._sessions.size,
+            maxContexts: this._maxContexts,
+            sessions: [...this._sessions.values()].map((s) => ({
+                id: s.id,
+                url: s.currentUrl(),
+                healthy: s.isHealthy(),
+                profile: s.profile,
+            })),
+        };
+    }
+    async shutdown() {
+        this._shuttingDown = true;
+        this._log.info("shutting down browser pool");
+        this._health.stop();
+        const closeTasks = [...this._sessions.values()].map((session) => session.close().catch((err) => {
+            this._log.warn({ sessionId: session.id, err }, "error closing session during shutdown");
+        }));
+        await Promise.allSettled(closeTasks);
+        this._sessions.clear();
+        if (this._browser) {
+            try {
+                await this._browser.close();
+            }
+            catch (err) {
+                this._log.warn({ err }, "error closing browser during shutdown");
+            }
+            this._browser = null;
+        }
+        this._launching = null;
+        this._shuttingDown = false;
+        this._log.info("browser pool shut down");
+    }
+    async _ensureBrowser() {
+        if (this._browser?.isConnected()) {
+            return this._browser;
+        }
+        if (this._launching) {
+            return this._launching;
+        }
+        this._launching = this._launchBrowser();
+        try {
+            const browser = await this._launching;
+            return browser;
+        }
+        finally {
+            this._launching = null;
+        }
+    }
+    async _launchBrowser() {
+        this._log.info("launching browser");
+        const browser = await chromium.launch({
+            ...this._launchOptions,
+            handleSIGINT: false,
+            handleSIGTERM: false,
+            handleSIGHUP: false,
+        });
+        browser.on("disconnected", () => {
+            this._log.warn("browser disconnected");
+            this._browser = null;
+            for (const session of this._sessions.values()) {
+                session.markUnhealthy();
+                this._handleUnhealthy(session);
+            }
+        });
+        this._browser = browser;
+        this._log.info("browser launched");
+        return browser;
+    }
+    async _persistProfileSnapshot(session) {
+        if (!session.profile) {
+            return;
+        }
+        try {
+            const snapshot = await session.snapshot();
+            saveProfileSnapshot(session.profile, snapshot);
+        }
+        catch (err) {
+            this._log.warn({ sessionId: session.id, profile: session.profile, err }, "failed to persist profile snapshot");
+        }
+    }
+    _handleUnhealthy(session) {
+        this._recoverUnhealthy(session).catch((err) => {
+            this._log.error({ sessionId: session.id, err }, "unhealthy session recovery failed");
+        });
+    }
+    async _recoverUnhealthy(session) {
+        if (this._shuttingDown) {
+            return;
+        }
+        if (!this._sessions.has(session.id)) {
+            return;
+        }
+        this._log.error({ sessionId: session.id }, "session unhealthy — recreating context");
+        let snapshot;
+        try {
+            snapshot = await session.snapshot();
+        }
+        catch {
+            if (session.profile) {
+                snapshot = loadProfileSnapshot(session.profile);
+            }
+        }
+        this._health.untrack(session.id);
+        this._sessions.delete(session.id);
+        try {
+            await session.close();
+        }
+        catch (err) {
+            this._log.warn({ sessionId: session.id, err }, "error closing unhealthy session");
+        }
+        try {
+            const browser = await this._ensureBrowser();
+            const context = await browser.newContext();
+            const page = await context.newPage();
+            const replacement = new BrowserSession({
+                context,
+                page,
+                profile: session.profile,
+                logger: this._log,
+            });
+            if (snapshot) {
+                await replacement.restore(snapshot);
+            }
+            this._sessions.set(replacement.id, replacement);
+            this._health.track(replacement);
+            this._log.info({ oldSessionId: session.id, sessionId: replacement.id }, "unhealthy session recovered");
+        }
+        catch (err) {
+            this._log.error({ sessionId: session.id, err }, "failed to recover unhealthy session");
+        }
+    }
+}
+//# sourceMappingURL=browser-pool.js.map

package/dist/pool/browser-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-pool.js","sourceRoot":"","sources":["../../src/pool/browser-pool.ts"],"names":[],"mappings":"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"}

package/dist/pool/health.d.ts

@@ -0,0 +1,28 @@
+import type { Logger } from "../observe/logger.js";
+import type { BrowserSession } from "../session/session.js";
+export interface HealthProbeOptions {
+    intervalMs?: number;
+    timeoutMs?: number;
+    maxFailures?: number;
+    onUnhealthy: (session: BrowserSession) => void;
+}
+export declare class HealthMonitor {
+    private _tracked;
+    private _timer;
+    private _intervalMs;
+    private _timeoutMs;
+    private _maxFailures;
+    private _onUnhealthy;
+    private _log;
+    constructor(logger: Logger, opts: HealthProbeOptions);
+    track(session: BrowserSession): void;
+    untrack(sessionId: string): void;
+    checkOne(sessionId: string): Promise<boolean>;
+    stop(): void;
+    private _ensureRunning;
+    private _stop;
+    private _checkAll;
+    private _probe;
+    private _recordFailure;
+}
+//# sourceMappingURL=health.d.ts.map

package/dist/pool/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/pool/health.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAM5D,MAAM,WAAW,kBAAkB;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAC;CAC/C;AAOD,qBAAa,aAAa;IACzB,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,MAAM,CAA+C;IAC7D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,IAAI,CAAS;gBAET,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB;IAQpD,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAKpC,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAO1B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQnD,IAAI,IAAI,IAAI;IAKZ,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,KAAK;YAOC,SAAS;YAKT,MAAM;IAyBpB,OAAO,CAAC,cAAc;CAsBtB"}

package/dist/pool/health.js

@@ -0,0 +1,96 @@
+const HEALTH_CHECK_INTERVAL_MS = 30_000;
+const HEALTH_CHECK_TIMEOUT_MS = 5_000;
+const MAX_CONSECUTIVE_FAILURES = 3;
+export class HealthMonitor {
+    _tracked = new Map();
+    _timer = null;
+    _intervalMs;
+    _timeoutMs;
+    _maxFailures;
+    _onUnhealthy;
+    _log;
+    constructor(logger, opts) {
+        this._intervalMs = opts.intervalMs ?? HEALTH_CHECK_INTERVAL_MS;
+        this._timeoutMs = opts.timeoutMs ?? HEALTH_CHECK_TIMEOUT_MS;
+        this._maxFailures = opts.maxFailures ?? MAX_CONSECUTIVE_FAILURES;
+        this._onUnhealthy = opts.onUnhealthy;
+        this._log = logger.child({ component: "health" });
+    }
+    track(session) {
+        this._tracked.set(session.id, { session, consecutiveFailures: 0 });
+        this._ensureRunning();
+    }
+    untrack(sessionId) {
+        this._tracked.delete(sessionId);
+        if (this._tracked.size === 0) {
+            this._stop();
+        }
+    }
+    async checkOne(sessionId) {
+        const tracked = this._tracked.get(sessionId);
+        if (!tracked) {
+            return false;
+        }
+        return this._probe(tracked);
+    }
+    stop() {
+        this._stop();
+        this._tracked.clear();
+    }
+    _ensureRunning() {
+        if (this._timer !== null) {
+            return;
+        }
+        this._timer = setInterval(() => {
+            this._checkAll().catch((err) => {
+                this._log.error({ err }, "health check cycle failed");
+            });
+        }, this._intervalMs);
+    }
+    _stop() {
+        if (this._timer !== null) {
+            clearInterval(this._timer);
+            this._timer = null;
+        }
+    }
+    async _checkAll() {
+        const checks = [...this._tracked.values()].map((tracked) => this._probe(tracked));
+        await Promise.allSettled(checks);
+    }
+    async _probe(tracked) {
+        const { session } = tracked;
+        if (!session.isHealthy()) {
+            return false;
+        }
+        try {
+            const result = await Promise.race([
+                session.page.evaluate(() => document.readyState),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("health check timeout")), this._timeoutMs)),
+            ]);
+            if (result === "complete" || result === "interactive" || result === "loading") {
+                tracked.consecutiveFailures = 0;
+                return true;
+            }
+            return this._recordFailure(tracked, "unexpected readyState");
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "unknown error";
+            return this._recordFailure(tracked, message);
+        }
+    }
+    _recordFailure(tracked, reason) {
+        tracked.consecutiveFailures++;
+        this._log.warn({
+            sessionId: tracked.session.id,
+            failures: tracked.consecutiveFailures,
+            reason,
+        }, "health check failed");
+        if (tracked.consecutiveFailures >= this._maxFailures) {
+            this._log.error({ sessionId: tracked.session.id }, `${this._maxFailures} consecutive failures — marking unhealthy`);
+            tracked.session.markUnhealthy();
+            this._onUnhealthy(tracked.session);
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=health.js.map

package/dist/pool/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/pool/health.ts"],"names":[],"mappings":"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"}

package/dist/selectors/strategy.d.ts

@@ -0,0 +1,37 @@
+import type { Locator, Page } from "playwright-core";
+export interface SelectorResolution {
+    locator: Locator;
+    strategy: SelectorStrategy;
+    strategyIndex: number;
+    resolutionMs: number;
+    chainLength: number;
+}
+export type SelectorStrategy = {
+    type: "aria";
+    role: string;
+    name: string;
+} | {
+    type: "text";
+    text: string;
+    exact?: boolean;
+} | {
+    type: "label";
+    text: string;
+} | {
+    type: "testid";
+    id: string;
+} | {
+    type: "css";
+    selector: string;
+} | {
+    type: "xpath";
+    expression: string;
+};
+export type Selector = string | SelectorStrategy | SelectorStrategy[];
+export type SelectorWaitState = "visible" | "hidden" | "attached" | "detached";
+export declare function resolveSelector(page: Page, selector: Selector): Locator;
+export declare function resolveFirstVisible(page: Page, selector: Selector, timeoutMs: number): Promise<Locator>;
+export declare function resolveWithConfidence(page: Page, selector: Selector, state: SelectorWaitState, timeoutMs: number): Promise<SelectorResolution>;
+/** @deprecated Use resolveWithConfidence — this wrapper extracts .locator for backward compat */
+export declare function resolveBestSelector(page: Page, selector: Selector, state: SelectorWaitState, timeoutMs: number): Promise<Locator>;
+//# sourceMappingURL=strategy.d.ts.map

package/dist/selectors/strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../src/selectors/strategy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAGrD,MAAM,WAAW,kBAAkB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,gBAAgB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,gBAAgB,GAAG,gBAAgB,EAAE,CAAC;AACtE,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAE/E,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAcvE;AAED,wBAAsB,mBAAmB,CACxC,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED,wBAAsB,qBAAqB,CAC1C,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,iBAAiB,EACxB,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,kBAAkB,CAAC,CA0E7B;AAED,iGAAiG;AACjG,wBAAsB,mBAAmB,CACxC,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,iBAAiB,EACxB,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/dist/selectors/strategy.js

@@ -0,0 +1,111 @@
+import { TargetNotFoundError } from "../errors.js";
+export function resolveSelector(page, selector) {
+    if (typeof selector === "string") {
+        return page.locator(selector);
+    }
+    if (Array.isArray(selector)) {
+        const first = selector[0];
+        if (!first) {
+            throw new TargetNotFoundError("empty selector strategy array");
+        }
+        return resolveOne(page, first);
+    }
+    return resolveOne(page, selector);
+}
+export async function resolveFirstVisible(page, selector, timeoutMs) {
+    const resolution = await resolveWithConfidence(page, selector, "visible", timeoutMs);
+    return resolution.locator.first();
+}
+export async function resolveWithConfidence(page, selector, state, timeoutMs) {
+    const start = performance.now();
+    if (typeof selector === "string") {
+        const locator = page.locator(selector);
+        const strategy = { type: "css", selector };
+        return {
+            locator,
+            strategy,
+            strategyIndex: 0,
+            resolutionMs: Math.round(performance.now() - start),
+            chainLength: 1,
+        };
+    }
+    if (!Array.isArray(selector)) {
+        const locator = resolveOne(page, selector);
+        return {
+            locator,
+            strategy: selector,
+            strategyIndex: 0,
+            resolutionMs: Math.round(performance.now() - start),
+            chainLength: 1,
+        };
+    }
+    if (selector.length === 0) {
+        throw new TargetNotFoundError("empty selector strategy array");
+    }
+    // Hidden/detached semantics can pass on missing elements, so fallback probing is not meaningful.
+    if (state === "hidden" || state === "detached") {
+        const first = selector[0];
+        if (!first) {
+            throw new TargetNotFoundError("empty selector strategy array");
+        }
+        return {
+            locator: resolveOne(page, first),
+            strategy: first,
+            strategyIndex: 0,
+            resolutionMs: Math.round(performance.now() - start),
+            chainLength: selector.length,
+        };
+    }
+    const deadline = Date.now() + timeoutMs;
+    for (let i = 0; i < selector.length; i++) {
+        const strategy = selector[i];
+        if (!strategy) {
+            continue;
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            break;
+        }
+        try {
+            const locator = resolveOne(page, strategy);
+            await locator.first().waitFor({ state, timeout: Math.min(remaining, 2000) });
+            return {
+                locator,
+                strategy,
+                strategyIndex: i,
+                resolutionMs: Math.round(performance.now() - start),
+                chainLength: selector.length,
+            };
+        }
+        catch {
+            // Strategy didn't match — try next one
+        }
+    }
+    throw new TargetNotFoundError(`no selector strategy matched within ${timeoutMs}ms for state ${state}`, "Try a different selector strategy or increase the timeout.");
+}
+/** @deprecated Use resolveWithConfidence — this wrapper extracts .locator for backward compat */
+export async function resolveBestSelector(page, selector, state, timeoutMs) {
+    const resolution = await resolveWithConfidence(page, selector, state, timeoutMs);
+    return resolution.locator;
+}
+function resolveOne(page, strategy) {
+    switch (strategy.type) {
+        case "aria":
+            return page.getByRole(strategy.role, {
+                name: strategy.name,
+            });
+        case "text":
+            return strategy.exact !== undefined
+                ? page.getByText(strategy.text, { exact: strategy.exact })
+                : page.getByText(strategy.text);
+        case "label":
+            return page.getByLabel(strategy.text);
+        case "testid":
+            return page.getByTestId(strategy.id);
+        case "css":
+            return page.locator(strategy.selector);
+        case "xpath":
+            return page.locator(`xpath=${strategy.expression}`);
+    }
+}
+//# sourceMappingURL=strategy.js.map

package/dist/selectors/strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.js","sourceRoot":"","sources":["../../src/selectors/strategy.ts"],"names":[],"mappings":"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"}

package/dist/session/handle-registry.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Stable element handle registry.
+ *
+ * Maps agent-friendly handle IDs to selector strategies so elements
+ * can be referenced across multiple action steps without re-specifying
+ * the selector. Re-resolution happens lazily on each `resolve()` call,
+ * tracking remaps when the winning strategy changes.
+ */
+import type { Locator, Page } from "playwright-core";
+import type { SelectorResolution, SelectorStrategy } from "../selectors/strategy.js";
+export interface ElementHandle {
+    handleId: string;
+    selector: SelectorStrategy | SelectorStrategy[];
+    /** The strategy that last successfully resolved. */
+    lastStrategy: SelectorStrategy;
+    /** How many times the winning strategy changed since registration. */
+    remapCount: number;
+}
+export interface HandleResolution {
+    locator: Locator;
+    handle: ElementHandle;
+    resolution: SelectorResolution;
+    remapped: boolean;
+}
+export declare class HandleRegistry {
+    private _handles;
+    get size(): number;
+    /**
+     * Register an element by resolving its selector and assigning a stable ID.
+     */
+    register(page: Page, selector: SelectorStrategy | SelectorStrategy[], timeoutMs?: number): Promise<ElementHandle>;
+    /**
+     * Resolve a handle to a live locator. Re-resolves via the original selector
+     * strategy, trying the last successful strategy first for speed.
+     */
+    resolve(page: Page, handleId: string, timeoutMs?: number): Promise<HandleResolution>;
+    /**
+     * Release a single handle.
+     */
+    release(handleId: string): boolean;
+    /**
+     * Release all handles.
+     */
+    clear(): void;
+    /**
+     * Get a handle by ID without resolving it.
+     */
+    get(handleId: string): ElementHandle | undefined;
+    /**
+     * List all registered handles.
+     */
+    list(): ElementHandle[];
+    /**
+     * Build a strategy array with the last successful strategy first,
+     * followed by the remaining strategies in original order.
+     */
+    private _buildPrioritizedStrategies;
+}
+//# sourceMappingURL=handle-registry.d.ts.map

package/dist/session/handle-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-registry.d.ts","sourceRoot":"","sources":["../../src/session/handle-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAErD,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGrF,MAAM,WAAW,aAAa;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAAC;IAChD,oDAAoD;IACpD,YAAY,EAAE,gBAAgB,CAAC;IAC/B,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,kBAAkB,CAAC;IAC/B,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,cAAc;IAC1B,OAAO,CAAC,QAAQ,CAAoC;IAEpD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACG,QAAQ,CACb,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,EAC/C,SAAS,SAAO,GACd,OAAO,CAAC,aAAa,CAAC;IAczB;;;OAGG;IACG,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAyBxF;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIlC;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAIhD;;OAEG;IACH,IAAI,IAAI,aAAa,EAAE;IAIvB;;;OAGG;IACH,OAAO,CAAC,2BAA2B;CAQnC"}