@e2edev/web 0.11.0-canary-20260921180210

package/dist/attempt-session.js

@@ -0,0 +1,290 @@
+/** Owns one attempt's live binding, recovery, references, and recordings. */
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { EngineError, raceAbort, withinCleanupBudget } from 'e2e/engine';
+import { attachPersistent, recoveryFailed, targetIdentity } from './cdp-recovery.js';
+import { connectionAbort, withConnectionBudget } from './operation-budget.js';
+import { RefRegistry } from './refs.js';
+import { invalidState, translatePwError } from './support.js';
+import { VideoRecorder } from './video.js';
+const TRACE_OPTIONS = { screenshots: true, snapshots: true };
+export class AttemptSession {
+    options;
+    refs = new RefRegistry();
+    lifetime = new AbortController();
+    video;
+    state = { kind: 'empty' };
+    generation = {};
+    observed = true;
+    tracing = false;
+    traceSegments = 0;
+    traceParts = [];
+    constructor(options) {
+        this.options = options;
+        this.video = new VideoRecorder(options.viewport, options.artifactsDir);
+    }
+    /** Captures an immutable connection generation for publication after asynchronous reads. */
+    token() { return this.generation; }
+    /** Rejects work belonging to a superseded connection or an ended attempt. */
+    check(token) {
+        if (this.generation !== token || this.state.kind !== 'ready') {
+            throw new EngineError('NODE_STALE', 'the connection changed while reading the screen', { retryable: true });
+        }
+    }
+    /** An observation commits its references and freshness together against the same generation. */
+    observedGeneration(token) {
+        this.check(token);
+        this.observed = true;
+    }
+    /** Observation-backed pointer and keyboard input needs evidence captured after recovery. */
+    requireObservation() {
+        if (!this.observed)
+            throw new EngineError('NODE_STALE', 'observe the screen again after CDP recovery before acting', { retryable: true });
+    }
+    /** Reads the only published binding. Pending work never replaces it halfway through setup. */
+    current() {
+        if (this.state.kind === 'failed')
+            throw this.state.error;
+        if (this.state.kind !== 'ready')
+            throw invalidState('no attempt connection is ready');
+        return this.state.binding;
+    }
+    /** Invalidates every asynchronous read and reference at a connection or page transition. */
+    invalidate() {
+        this.generation = {};
+        this.refs.clear();
+    }
+    /** Opens a context for this attempt, publishing only after its handlers are installed. */
+    start(signal) {
+        return withConnectionBudget({ signal: AbortSignal.any([signal, this.lifetime.signal]), timeoutMs: 60_000 }, 'connection', (remaining) => this.transition(undefined, remaining(), async () => {
+            const persistent = this.options.persistent;
+            if (persistent === undefined) {
+                const browser = await this.options.acquire(remaining().signal);
+                remaining();
+                const context = await browser.newContext(this.options.contextOptions);
+                return { browser, context, page: null };
+            }
+            const binding = await attachPersistent(persistent.provision, remaining());
+            const contextId = binding.identity.contextId;
+            if (persistent.usedContexts.has(contextId)) {
+                await binding.browser.close().catch(() => undefined);
+                throw recoveryFailed('cdpEndpoint reused a browser from a previous attempt; provision a fresh browser');
+            }
+            persistent.usedContexts.add(contextId);
+            return binding;
+        }));
+    }
+    /** Shares one reconnect, then dispatches once with the time that remains. */
+    async run(operation, label, work) {
+        const signal = AbortSignal.any([operation.signal, this.lifetime.signal]);
+        if (signal.aborted)
+            throw connectionAbort(signal, label);
+        if (this.state.kind === 'failed')
+            throw this.state.error;
+        const persistent = this.options.persistent;
+        const reconnect = (this.state.kind === 'pending' || (this.state.kind === 'ready' && !this.state.binding.browser.isConnected()));
+        if (persistent === undefined || !reconnect)
+            return raceAbort(() => work({ ...operation, signal }), signal, label);
+        return withConnectionBudget({ ...operation, signal }, label, async (remaining) => {
+            if (this.state.kind === 'pending') {
+                await raceAbort(this.state.work, remaining().signal, 'CDP recovery');
+            }
+            else {
+                const previous = this.current();
+                this.observed = false;
+                await this.transition(previous, remaining(), async () => {
+                    await this.video.pageClosing();
+                    return attachPersistent(persistent.reconnect, remaining(), previous.identity);
+                }, true);
+            }
+            const current = remaining();
+            return raceAbort(() => work({ ...operation, ...current }), current.signal, label);
+        });
+    }
+    /** Owns a candidate through configuration and recording setup, then publishes it once. */
+    async transition(previous, budget, open, recover = false) {
+        if (budget.signal.aborted)
+            throw connectionAbort(budget.signal, 'connection');
+        this.invalidate();
+        const resumeTrace = recover && this.tracing;
+        if (recover)
+            this.tracing = false;
+        const running = Promise.resolve().then(async () => {
+            if (budget.signal.aborted)
+                throw connectionAbort(budget.signal, 'connection');
+            const candidate = await open();
+            const close = () => { void this.release(candidate).catch(() => undefined); };
+            budget.signal.addEventListener('abort', close, { once: true });
+            try {
+                if (budget.signal.aborted)
+                    throw connectionAbort(budget.signal, 'connection');
+                await this.options.configure(candidate.context);
+                if (recover && candidate.page !== null) {
+                    await candidate.page.setViewportSize(previous?.page?.viewportSize() ?? this.options.viewport);
+                    await this.video.pageOpened(candidate.page);
+                }
+                if (resumeTrace)
+                    await candidate.context.tracing.start(TRACE_OPTIONS);
+                if (budget.signal.aborted)
+                    throw connectionAbort(budget.signal, 'connection');
+                if (this.state !== pending)
+                    throw connectionAbort(this.lifetime.signal, 'connection');
+                this.tracing = resumeTrace;
+                this.state = { kind: 'ready', binding: candidate };
+            }
+            catch (cause) {
+                await this.release(candidate).catch(() => undefined);
+                throw cause;
+            }
+            finally {
+                budget.signal.removeEventListener('abort', close);
+            }
+        });
+        const work = raceAbort(running, budget.signal, 'connection').catch((cause) => {
+            const error = budget.signal.aborted ? connectionAbort(budget.signal, 'connection') : translatePwError(cause, 'connection');
+            if (this.state === pending)
+                this.state = { kind: 'failed', binding: previous, error };
+            throw error;
+        });
+        const pending = { kind: 'pending', binding: previous, work };
+        this.state = pending;
+        await work;
+    }
+    /** Creates the attempt's active page and records its exact target before exposing it. */
+    async ensurePage() {
+        const binding = this.current();
+        if (binding.page !== null && !binding.page.isClosed())
+            return binding.page;
+        this.invalidate();
+        const token = this.token();
+        const page = await binding.context.newPage();
+        try {
+            let identity = binding.identity;
+            if (identity !== undefined) {
+                await page.setViewportSize(this.options.viewport);
+                identity = { ...identity, target: await targetIdentity(page) };
+            }
+            this.check(token);
+            await this.video.pageOpened(page);
+            this.check(token);
+            this.state = { kind: 'ready', binding: { ...binding, page, ...(identity === undefined ? {} : { identity }) } };
+            return page;
+        }
+        catch (cause) {
+            await page.close().catch(() => undefined);
+            throw cause;
+        }
+    }
+    /** Restarts the document while retaining this context's storage. */
+    async restart() {
+        const binding = this.current();
+        this.invalidate();
+        const token = this.token();
+        await this.video.pageClosing();
+        const resume = this.video.isArmed ? await this.closeTraceSegment(binding.context) : false;
+        for (const page of binding.context.pages())
+            await page.close();
+        this.check(token);
+        this.state = { kind: 'ready', binding: { ...binding, page: null } };
+        await this.ensurePage();
+        if (resume)
+            await this.startTrace();
+    }
+    /** Replaces an ordinary context; persistent recovery never advertises this capability. */
+    async replace(storageState, operation) {
+        const previous = this.current();
+        const resume = await this.closeTraceSegment(previous.context);
+        await this.video.pageClosing();
+        await this.transition(previous, operation, async () => {
+            await previous.context.close();
+            const context = await previous.browser.newContext({ ...this.options.contextOptions, ...(storageState === undefined ? {} : { storageState }) });
+            return { browser: previous.browser, context, page: null };
+        });
+        if (this.video.isArmed)
+            await this.ensurePage();
+        if (resume)
+            await this.startTrace();
+    }
+    /** Ends this attempt immediately; late work can only access this retired owner. */
+    async close(budget) {
+        const state = this.state;
+        this.state = { kind: 'closed' };
+        this.lifetime.abort();
+        this.invalidate();
+        if (state.kind === 'pending')
+            await withinCleanupBudget(state.work, budget);
+        const binding = 'binding' in state ? state.binding : undefined;
+        if (binding === undefined)
+            return;
+        if (this.video.isRecording)
+            await withinCleanupBudget(this.video.pageClosing(), budget);
+        if (this.tracing)
+            await withinCleanupBudget(binding.context.tracing.stop(), budget);
+        await withinCleanupBudget(this.release(binding), budget);
+    }
+    /** Ordinary contexts are engine-owned; persistent browser processes belong to the host. */
+    release(binding) {
+        return this.options.persistent === undefined ? binding.context.close() : binding.browser.close();
+    }
+    /** Allocates trace paths inside this attempt's immutable artifact directory. */
+    tracePath(name) {
+        const relative = path.posix.join('trace', `${name}.zip`);
+        const absolute = path.join(this.options.artifactsDir, relative);
+        mkdirSync(path.dirname(absolute), { recursive: true });
+        return { relative, absolute };
+    }
+    /** Saves a replaced context's trace when it can still flush it. */
+    async closeTraceSegment(context) {
+        if (!this.tracing)
+            return false;
+        this.tracing = false;
+        this.traceSegments += 1;
+        const { relative, absolute } = this.tracePath(`trace-part${this.traceSegments}`);
+        try {
+            await context.tracing.stop({ path: absolute });
+            this.traceParts.push(relative);
+        }
+        catch { /* A disconnected context may have lost its final trace segment. */ }
+        return true;
+    }
+    /** Begins tracing the currently committed context. */
+    async startTrace() {
+        const token = this.token();
+        await this.current().context.tracing.start(TRACE_OPTIONS);
+        this.check(token);
+        this.tracing = true;
+    }
+    /** Returns finalized segments, including any retained before context replacement failed. */
+    async stopTrace() {
+        const parts = this.traceParts;
+        this.traceParts = [];
+        if (parts.length > 0 && !this.tracing)
+            return parts;
+        const { relative, absolute } = this.tracePath('trace');
+        await this.current().context.tracing.stop({ path: absolute });
+        this.tracing = false;
+        return parts.length === 0 ? relative : [...parts, relative];
+    }
+    /** Starts video before tracing can choose the page's screencast size. */
+    async startVideo() { await this.video.arm(await this.ensurePage()); }
+    /** Collects finalized trace segments even when connection replacement failed. */
+    collectTrace(operation) {
+        return this.finalize(operation, 'trace', () => this.stopTrace());
+    }
+    /** Collects this attempt's video independently of a failed connection. */
+    collectVideo(operation) {
+        return this.finalize(operation, 'video', () => this.video.stop());
+    }
+    /** Terminal artifact collection needs its own budget, but no successful UI dispatch. */
+    async finalize(operation, label, collect) {
+        try {
+            return this.state.kind === 'failed' || this.state.kind === 'closed'
+                ? await withConnectionBudget(operation, label, (remaining) => raceAbort(collect, remaining().signal, label))
+                : await this.run(operation, label, collect);
+        }
+        catch (cause) {
+            throw translatePwError(cause, label);
+        }
+    }
+}
+//# sourceMappingURL=attempt-session.js.map

package/dist/attempt-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt-session.js","sourceRoot":"","sources":["../src/attempt-session.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,mBAAmB,EAA0F,MAAM,YAAY,CAAC;AACjK,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,cAAc,EAAiD,MAAM,mBAAmB,CAAC;AACpI,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAyB,MAAM,uBAAuB,CAAC;AACrG,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAwB3C,MAAM,aAAa,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAW,CAAC;AAEtE,MAAM,OAAO,cAAc;IAWI,OAAO;IAV3B,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;IACjB,QAAQ,GAAG,IAAI,eAAe,EAAE,CAAC;IACjC,KAAK,CAAgB;IAC9B,KAAK,GAAiB,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACxC,UAAU,GAAG,EAAE,CAAC;IAChB,QAAQ,GAAG,IAAI,CAAC;IAChB,OAAO,GAAG,KAAK,CAAC;IAChB,aAAa,GAAG,CAAC,CAAC;IAClB,UAAU,GAAa,EAAE,CAAC;IAElC,YAA6B,OAAuB;uBAAvB,OAAO;QAClC,IAAI,CAAC,KAAK,GAAG,IAAI,aAAa,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IACzE,CAAC;IAED,4FAA4F;IAC5F,KAAK,KAAa,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IAE3C,6EAA6E;IAC7E,KAAK,CAAC,KAAa;QACjB,IAAI,IAAI,CAAC,UAAU,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC7D,MAAM,IAAI,WAAW,CAAC,YAAY,EAAE,iDAAiD,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9G,CAAC;IACH,CAAC;IAED,gGAAgG;IAChG,kBAAkB,CAAC,KAAa;QAC9B,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAClB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;IACvB,CAAC;IAED,4FAA4F;IAC5F,kBAAkB;QAChB,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,WAAW,CAAC,YAAY,EAAE,2DAA2D,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5I,CAAC;IAED,8FAA8F;IAC9F,OAAO;QACL,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QACzD,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO;YAAE,MAAM,YAAY,CAAC,gCAAgC,CAAC,CAAC;QACtF,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;IAC5B,CAAC;IAED,4FAA4F;IACpF,UAAU;QAChB,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;IAED,0FAA0F;IAC1F,KAAK,CAAC,MAAmB;QACvB,OAAO,oBAAoB,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,YAAY,EACtH,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,SAAS,EAAE,EAAE,KAAK,IAAI,EAAE;YAChE,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;YAC3C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC;gBAC/D,SAAS,EAAE,CAAC;gBACZ,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;gBACtE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YAC1C,CAAC;YACD,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,UAAU,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC;YAC1E,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;YAC7C,IAAI,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC3C,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;gBACrD,MAAM,cAAc,CAAC,iFAAiF,CAAC,CAAC;YAC1G,CAAC;YACD,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACvC,OAAO,OAAO,CAAC;QACjB,CAAC,CAAC,CAAC,CAAC;IACR,CAAC;IAED,6EAA6E;IAC7E,KAAK,CAAC,GAAG,CAAI,SAA2B,EAAE,KAAa,EAAE,IAAiD;QACxG,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACzE,IAAI,MAAM,CAAC,OAAO;YAAE,MAAM,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACzD,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QACzD,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;QAC3C,MAAM,SAAS,GAAG,CAChB,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAC5G,CAAC;QACF,IAAI,UAAU,KAAK,SAAS,IAAI,CAAC,SAAS;YAAE,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,GAAG,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QAClH,OAAO,oBAAoB,CAAC,EAAE,GAAG,SAAS,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE;YAC/E,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAClC,MAAM,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;YACvE,CAAC;iBAAM,CAAC;gBACN,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;gBAChC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;gBACtB,MAAM,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,SAAS,EAAE,EAAE,KAAK,IAAI,EAAE;oBACtD,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;oBAC/B,OAAO,gBAAgB,CAAC,UAAU,CAAC,SAAS,EAAE,SAAS,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;gBAChF,CAAC,EAAE,IAAI,CAAC,CAAC;YACX,CAAC;YACD,MAAM,OAAO,GAAG,SAAS,EAAE,CAAC;YAC5B,OAAO,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,GAAG,SAAS,EAAE,GAAG,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACpF,CAAC,CAAC,CAAC;IACL,CAAC;IAED,0FAA0F;IAClF,KAAK,CAAC,UAAU,CACtB,QAAoC,EACpC,MAAwB,EACxB,IAAmC,EACnC,OAAO,GAAG,KAAK;QAEf,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO;YAAE,MAAM,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC9E,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,MAAM,WAAW,GAAG,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC;QAC5C,IAAI,OAAO;YAAE,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QAClC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE;YAChD,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO;gBAAE,MAAM,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;YAC9E,MAAM,SAAS,GAAG,MAAM,IAAI,EAAE,CAAC;YAC/B,MAAM,KAAK,GAAG,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;YAC7E,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/D,IAAI,CAAC;gBACH,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO;oBAAE,MAAM,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;gBAC9E,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;gBAChD,IAAI,OAAO,IAAI,SAAS,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;oBACvC,MAAM,SAAS,CAAC,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;oBAC9F,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;gBAC9C,CAAC;gBACD,IAAI,WAAW;oBAAE,MAAM,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;gBACtE,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO;oBAAE,MAAM,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;gBAC9E,IAAI,IAAI,CAAC,KAAK,KAAK,OAAO;oBAAE,MAAM,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;gBACtF,IAAI,CAAC,OAAO,GAAG,WAAW,CAAC;gBAC3B,IAAI,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;YACrD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;gBACrD,MAAM,KAAK,CAAC;YACd,CAAC;oBAAS,CAAC;gBACT,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACpD,CAAC;QACH,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACpF,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;YAC3H,IAAI,IAAI,CAAC,KAAK,KAAK,OAAO;gBAAE,IAAI,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;YACtF,MAAM,KAAK,CAAC;QACd,CAAC,CAAC,CAAC;QACH,MAAM,OAAO,GAAiB,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAC3E,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC;QACrB,MAAM,IAAI,CAAC;IACb,CAAC;IAED,yFAAyF;IACzF,KAAK,CAAC,UAAU;QACd,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE;YAAE,OAAO,OAAO,CAAC,IAAI,CAAC;QAC3E,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAC7C,IAAI,CAAC;YACH,IAAI,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;YAChC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,MAAM,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAClD,QAAQ,GAAG,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;YACjE,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAClB,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YAClC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAClB,IAAI,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/G,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC1C,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,oEAAoE;IACpE,KAAK,CAAC,OAAO;QACX,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC/B,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC3B,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAC1F,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE;YAAE,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QAC/D,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;QACpE,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QACxB,IAAI,MAAM;YAAE,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;IACtC,CAAC;IAED,0FAA0F;IAC1F,KAAK,CAAC,OAAO,CAAC,YAAsC,EAAE,SAA2B;QAC/E,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC9D,MAAM,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;QAC/B,MAAM,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,IAAI,EAAE;YACpD,MAAM,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YAC/B,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC,CAAC;YAC/I,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAC5D,CAAC,CAAC,CAAC;QACH,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO;YAAE,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QAChD,IAAI,MAAM;YAAE,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;IACtC,CAAC;IAED,mFAAmF;IACnF,KAAK,CAAC,KAAK,CAAC,MAA4B;QACtC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAChC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;YAAE,MAAM,mBAAmB,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC5E,MAAM,OAAO,GAAG,SAAS,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;QAC/D,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO;QAClC,IAAI,IAAI,CAAC,KAAK,CAAC,WAAW;YAAE,MAAM,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,MAAM,CAAC,CAAC;QACxF,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,mBAAmB,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;QACpF,MAAM,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3D,CAAC;IAED,2FAA2F;IACnF,OAAO,CAAC,OAAuB;QACrC,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACnG,CAAC;IAED,gFAAgF;IACxE,SAAS,CAAC,IAAY;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,MAAM,CAAC,CAAC;QACzD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QAChE,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;IAChC,CAAC;IAED,mEAAmE;IAC3D,KAAK,CAAC,iBAAiB,CAAC,OAAuB;QACrD,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAChC,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC;QACxB,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,aAAa,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC;QACjF,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC/C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC,CAAC,mEAAmE,CAAC,CAAC;QAC/E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,sDAAsD;IACtD,KAAK,CAAC,UAAU;QACd,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC3B,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAC1D,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAClB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;IAED,4FAA4F;IACpF,KAAK,CAAC,SAAS;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;QACrB,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QACpD,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACvD,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC9D,CAAC;IAED,yEAAyE;IACzE,KAAK,CAAC,UAAU,KAAoB,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC;IAEpF,iFAAiF;IACjF,YAAY,CAAC,SAA2B;QACtC,OAAO,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,0EAA0E;IAC1E,YAAY,CAAC,SAA2B;QACtC,OAAO,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,wFAAwF;IAChF,KAAK,CAAC,QAAQ,CAAI,SAA2B,EAAE,KAAa,EAAE,OAAyB;QAC7F,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ;gBACjE,CAAC,CAAC,MAAM,oBAAoB,CAAC,SAAS,EAAE,KAAK,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;gBAC5G,CAAC,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;CACF"}

package/dist/browser-connection.d.ts

@@ -0,0 +1,34 @@
+/** Shares one browser process connection across a worker's attempts. */
+import type { Browser } from 'playwright';
+import { chromium } from 'playwright';
+export type BrowserName = 'chromium' | 'firefox' | 'webkit';
+/**
+ * Launching a browser process costs hundreds of milliseconds; per-attempt
+ * isolation lives in browser contexts, so every attempt a worker runs can
+ * share the process. The connection relaunches a browser that crashed or
+ * disconnected and is emptied by `dispose` (wired to the engine `dispose`
+ * hook).
+ */
+export declare class BrowserConnection {
+    private pending;
+    /**
+     * Returns a connected shared browser, launching or relaunching as needed.
+     * When `connect` is given the connection attaches to a remote browser through it
+     * instead of launching a local one; `connect` is re-invoked on a relaunch,
+     * so a caller that resolves a fresh per-run endpoint reconnects cleanly
+     * after a dropped session.
+     */
+    acquire(name: BrowserName, headed: boolean, timeoutMs: number, connect?: () => Promise<Browser>): Promise<Browser>;
+    /** Closes the connection, including a launch still in flight; idempotent and best-effort. */
+    dispose(): Promise<void>;
+}
+/** Maps a browser name to its Playwright BrowserType. */
+export declare function browserType(name: BrowserName): typeof chromium;
+/**
+ * Attaches to a remote browser over the Chrome DevTools Protocol. CDP attach
+ * is chromium-only; a hosted-browser engine (a per-run cloud session) resolves
+ * the endpoint itself and hands it here. `browser.close()` on the result
+ * detaches the CDP session without killing the remote process the host owns.
+ */
+export declare function connectCdp(endpoint: string, timeoutMs: number): Promise<Browser>;
+//# sourceMappingURL=browser-connection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"browser-connection.d.ts","sourceRoot":"","sources":["../src/browser-connection.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAExE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAA8B,MAAM,YAAY,CAAC;AAGlE,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE5D;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAA+B;IAE9C;;;;;;OAMG;IACG,OAAO,CACX,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAC/B,OAAO,CAAC,OAAO,CAAC,CAkBlB;IAED,6FAA6F;IACvF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAQ7B;CACF;AAED,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,QAAQ,CAI9D;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGtF"}

package/dist/browser-connection.js

@@ -0,0 +1,87 @@
+/** Shares one browser process connection across a worker's attempts. */
+import { chromium, firefox, selectors, webkit } from 'playwright';
+import { CLOSED_SHADOW_SELECTOR_ENGINE, CLOSED_SHADOW_SELECTOR_ENGINE_SOURCE } from './read-node.js';
+/**
+ * Launching a browser process costs hundreds of milliseconds; per-attempt
+ * isolation lives in browser contexts, so every attempt a worker runs can
+ * share the process. The connection relaunches a browser that crashed or
+ * disconnected and is emptied by `dispose` (wired to the engine `dispose`
+ * hook).
+ */
+export class BrowserConnection {
+    pending;
+    /**
+     * Returns a connected shared browser, launching or relaunching as needed.
+     * When `connect` is given the connection attaches to a remote browser through it
+     * instead of launching a local one; `connect` is re-invoked on a relaunch,
+     * so a caller that resolves a fresh per-run endpoint reconnects cleanly
+     * after a dropped session.
+     */
+    async acquire(name, headed, timeoutMs, connect) {
+        const cached = this.pending;
+        if (cached !== undefined) {
+            const browser = await cached.catch(() => null);
+            if (browser !== null && browser.isConnected())
+                return browser;
+            if (this.pending !== cached)
+                return this.acquire(name, headed, timeoutMs, connect);
+            this.pending = undefined;
+        }
+        await registerSelectorEngines();
+        const launching = connect !== undefined ? connect() : browserType(name).launch({ headless: !headed, timeout: timeoutMs });
+        this.pending = launching;
+        try {
+            return await launching;
+        }
+        catch (cause) {
+            if (this.pending === launching)
+                this.pending = undefined;
+            throw cause;
+        }
+    }
+    /** Closes the connection, including a launch still in flight; idempotent and best-effort. */
+    async dispose() {
+        const pending = this.pending;
+        this.pending = undefined;
+        try {
+            await (await pending)?.close();
+        }
+        catch {
+            // Disposal still owns a failed or abandoned launch.
+        }
+    }
+}
+/** Maps a browser name to its Playwright BrowserType. */
+export function browserType(name) {
+    if (name === 'firefox')
+        return firefox;
+    if (name === 'webkit')
+        return webkit;
+    return chromium;
+}
+/**
+ * Attaches to a remote browser over the Chrome DevTools Protocol. CDP attach
+ * is chromium-only; a hosted-browser engine (a per-run cloud session) resolves
+ * the endpoint itself and hands it here. `browser.close()` on the result
+ * detaches the CDP session without killing the remote process the host owns.
+ */
+export async function connectCdp(endpoint, timeoutMs) {
+    await registerSelectorEngines();
+    return chromium.connectOverCDP(endpoint, { timeout: timeoutMs });
+}
+/** Registration is process-wide and rejected twice; one shared promise serves every connection. */
+let selectorEngines;
+/**
+ * Registers the engine's selector engines. Playwright requires it before the
+ * first page of the process exists, and a name registers once, so every
+ * acquire awaits the same registration.
+ */
+function registerSelectorEngines() {
+    // Playwright serializes a function argument with `toString()` and invokes it
+    // in the page, so the factory is materialized from its source here to keep the
+    // in-page code self-contained, the same way the reader is assembled.
+    const factory = new Function(`return ${CLOSED_SHADOW_SELECTOR_ENGINE_SOURCE};`)();
+    selectorEngines ??= selectors.register(CLOSED_SHADOW_SELECTOR_ENGINE, factory);
+    return selectorEngines;
+}
+//# sourceMappingURL=browser-connection.js.map

package/dist/browser-connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-connection.js","sourceRoot":"","sources":["../src/browser-connection.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAGxE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,EAAE,6BAA6B,EAAE,oCAAoC,EAAE,MAAM,gBAAgB,CAAC;AAIrG;;;;;;GAMG;AACH,MAAM,OAAO,iBAAiB;IACpB,OAAO,CAA+B;IAE9C;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CACX,IAAiB,EACjB,MAAe,EACf,SAAiB,EACjB,OAAgC;QAEhC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC;QAC5B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;YAC/C,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE;gBAAE,OAAO,OAAO,CAAC;YAC9D,IAAI,IAAI,CAAC,OAAO,KAAK,MAAM;gBAAE,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;YACnF,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QAC3B,CAAC;QACD,MAAM,uBAAuB,EAAE,CAAC;QAChC,MAAM,SAAS,GACb,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;QAC1G,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QACzB,IAAI,CAAC;YACH,OAAO,MAAM,SAAS,CAAC;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;gBAAE,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;YACzD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,6FAA6F;IAC7F,KAAK,CAAC,OAAO;QACX,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,CAAC,MAAM,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,oDAAoD;QACtD,CAAC;IACH,CAAC;CACF;AAED,yDAAyD;AACzD,MAAM,UAAU,WAAW,CAAC,IAAiB;IAC3C,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IACvC,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC;IACrC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB,EAAE,SAAiB;IAClE,MAAM,uBAAuB,EAAE,CAAC;IAChC,OAAO,QAAQ,CAAC,cAAc,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;AACnE,CAAC;AAED,mGAAmG;AACnG,IAAI,eAA0C,CAAC;AAE/C;;;;GAIG;AACH,SAAS,uBAAuB;IAC9B,6EAA6E;IAC7E,+EAA+E;IAC/E,qEAAqE;IACrE,MAAM,OAAO,GAAG,IAAI,QAAQ,CAAC,UAAU,oCAAoC,GAAG,CAAC,EAAmB,CAAC;IACnG,eAAe,KAAK,SAAS,CAAC,QAAQ,CAAC,6BAA6B,EAAE,OAAO,CAAC,CAAC;IAC/E,OAAO,eAAe,CAAC;AACzB,CAAC"}

package/dist/capture-scope.d.ts

@@ -0,0 +1,21 @@
+/** Deadline and handle ownership for one observation capture operation. */
+import type { JSHandle } from 'playwright';
+/** Releases acquired and late-arriving handles without waiting on the transport. */
+export declare class CaptureScope {
+    readonly deadline: number;
+    private readonly signal;
+    private active;
+    private readonly handles;
+    constructor(deadline: number, signal: AbortSignal);
+    /** Runs the complete operation, including readback, within one absolute deadline. */
+    run<T>(work: () => Promise<T>): Promise<T>;
+    /** Stops abandoned work before its next read or mutation; receives late handles for disposal. */
+    read<T>(work: () => Promise<T>, receive?: (value: T) => void): Promise<T>;
+    /** Takes ownership even when the operation ended before the handle arrived. */
+    own(handle: JSHandle): boolean;
+    /** Transfers a successfully captured element to the enclosing capture or published generation. */
+    release(handle: JSHandle): void;
+    /** Refuses further work after cancellation, expiry, or completion. */
+    check(): void;
+}
+//# sourceMappingURL=capture-scope.d.ts.map

package/dist/capture-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-scope.d.ts","sourceRoot":"","sources":["../src/capture-scope.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAE3E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C,oFAAoF;AACpF,qBAAa,YAAY;IAIX,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAAE,OAAO,CAAC,QAAQ,CAAC,MAAM;IAH9D,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAE/C,YAAqB,QAAQ,EAAE,MAAM,EAAmB,MAAM,EAAE,WAAW,EAAI;IAE/E,qFAAqF;IAC/E,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAe/C;IAED,iGAAiG;IAC3F,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAM9E;IAED,+EAA+E;IAC/E,GAAG,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAI7B;IAED,kGAAkG;IAClG,OAAO,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAE9B;IAED,sEAAsE;IACtE,KAAK,IAAI,IAAI,CAGZ;CACF"}

package/dist/capture-scope.js

@@ -0,0 +1,61 @@
+/** Deadline and handle ownership for one observation capture operation. */
+import { EngineError, raceAbort, withTimeout } from 'e2e/engine';
+import { cancelled } from './support.js';
+/** Releases acquired and late-arriving handles without waiting on the transport. */
+export class CaptureScope {
+    deadline;
+    signal;
+    active = true;
+    handles = new Set();
+    constructor(deadline, signal) {
+        this.deadline = deadline;
+        this.signal = signal;
+    }
+    /** Runs the complete operation, including readback, within one absolute deadline. */
+    async run(work) {
+        try {
+            this.check();
+            const result = await withTimeout(raceAbort(work, this.signal, 'observe'), this.deadline - Date.now(), captureTimeout);
+            this.check();
+            return result;
+        }
+        finally {
+            this.active = false;
+            for (const handle of this.handles)
+                void handle.dispose().catch(() => undefined);
+            this.handles.clear();
+        }
+    }
+    /** Stops abandoned work before its next read or mutation; receives late handles for disposal. */
+    async read(work, receive) {
+        this.check();
+        const value = await work();
+        receive?.(value);
+        this.check();
+        return value;
+    }
+    /** Takes ownership even when the operation ended before the handle arrived. */
+    own(handle) {
+        if (this.active)
+            this.handles.add(handle);
+        else
+            void handle.dispose().catch(() => undefined);
+        return this.active;
+    }
+    /** Transfers a successfully captured element to the enclosing capture or published generation. */
+    release(handle) {
+        this.handles.delete(handle);
+    }
+    /** Refuses further work after cancellation, expiry, or completion. */
+    check() {
+        if (this.signal.aborted)
+            throw cancelled('observe cancelled');
+        if (!this.active || Date.now() >= this.deadline)
+            throw captureTimeout();
+    }
+}
+/** A capture timeout is recoverable only through the caller's explicit pixel policy. */
+function captureTimeout() {
+    return new EngineError('OPERATION_TIMEOUT', 'observation capture timed out', { retryable: false });
+}
+//# sourceMappingURL=capture-scope.js.map

package/dist/capture-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-scope.js","sourceRoot":"","sources":["../src/capture-scope.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAG3E,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,oFAAoF;AACpF,MAAM,OAAO,YAAY;IAIF,QAAQ;IAA2B,MAAM;IAHtD,MAAM,GAAG,IAAI,CAAC;IACL,OAAO,GAAG,IAAI,GAAG,EAAY,CAAC;IAE/C,YAAqB,QAAgB,EAAmB,MAAmB;wBAAtD,QAAQ;sBAA2B,MAAM;IAAgB,CAAC;IAE/E,qFAAqF;IACrF,KAAK,CAAC,GAAG,CAAI,IAAsB;QACjC,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,MAAM,WAAW,CAC9B,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,EACvC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,EAC1B,cAAc,CACf,CAAC;YACF,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,OAAO,MAAM,CAAC;QAChB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;YACpB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO;gBAAE,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAChF,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;IACH,CAAC;IAED,iGAAiG;IACjG,KAAK,CAAC,IAAI,CAAI,IAAsB,EAAE,OAA4B;QAChE,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,MAAM,IAAI,EAAE,CAAC;QAC3B,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;QACjB,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,KAAK,CAAC;IACf,CAAC;IAED,+EAA+E;IAC/E,GAAG,CAAC,MAAgB;QAClB,IAAI,IAAI,CAAC,MAAM;YAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;;YACrC,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,kGAAkG;IAClG,OAAO,CAAC,MAAgB;QACtB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAED,sEAAsE;IACtE,KAAK;QACH,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,MAAM,SAAS,CAAC,mBAAmB,CAAC,CAAC;QAC9D,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,QAAQ;YAAE,MAAM,cAAc,EAAE,CAAC;IAC1E,CAAC;CACF;AAED,wFAAwF;AACxF,SAAS,cAAc;IACrB,OAAO,IAAI,WAAW,CAAC,mBAAmB,EAAE,+BAA+B,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;AACrG,CAAC"}

package/dist/cdp-recovery.d.ts

@@ -0,0 +1,29 @@
+/** Validates a persistent CDP binding without publishing or retaining it. */
+import type { Browser, BrowserContext, Page } from 'playwright';
+import { EngineError } from 'e2e/engine';
+import { type ConnectionBudget } from './operation-budget.ts';
+export type CdpEndpointResolver = (signal: AbortSignal) => string | Promise<string>;
+interface TargetIdentity {
+    readonly targetId: string;
+    readonly browserContextId?: string;
+}
+export interface PersistentIdentity {
+    readonly contextId: string;
+    readonly target?: TargetIdentity;
+}
+export interface SessionBinding {
+    readonly browser: Browser;
+    readonly context: BrowserContext;
+    readonly page: Page | null;
+    readonly identity?: PersistentIdentity;
+}
+/** A failed reconnect must never quietly provision another session. */
+export declare function recoveryFailed(detail: string): EngineError;
+/** Reads protocol identity, independent of URL, document contents, and tab order. */
+export declare function targetIdentity(page: Page): Promise<TargetIdentity>;
+/** Owns an uncommitted connection until its identity is proven; aborted and late connections detach. */
+export declare function attachPersistent(resolve: CdpEndpointResolver, budget: ConnectionBudget, previous?: PersistentIdentity): Promise<SessionBinding & {
+    readonly identity: PersistentIdentity;
+}>;
+export {};
+//# sourceMappingURL=cdp-recovery.d.ts.map

package/dist/cdp-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp-recovery.d.ts","sourceRoot":"","sources":["../src/cdp-recovery.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE/E,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,WAAW,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAEpF,UAAU,cAAc;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CACxC;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAE1D;AAED,qFAAqF;AACrF,wBAAsB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,cAAc,CAAC,CAOxE;AAED,wGAAwG;AACxG,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,gBAAgB,EACxB,QAAQ,CAAC,EAAE,kBAAkB,GAC5B,OAAO,CAAC,cAAc,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAqDrE"}