@e2e-dev/web 0.12.0 → 0.14.0-nightly-20261008205824

package/dist/install.js

@@ -1,29 +1,45 @@
 /** First-run browser provisioning for the Playwright engine. */
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import os from 'node:os';
 import path from 'node:path';
 import { EngineError, InfrastructureError } from 'e2e/engine';
 import { browserType } from './browser-connection.js';
+/** Whether `chromium_headless_shell-<revision>` under `browsersPath` finished installing and holds its executable. */
+function headlessShellInstalled(browsersPath, revision) {
+    const shellRoot = path.join(browsersPath, `chromium_headless_shell-${revision}`);
+    if (!existsSync(path.join(shellRoot, 'INSTALLATION_COMPLETE')))
+        return false;
+    const executable = process.platform === 'win32' ? 'chrome-headless-shell.exe' : 'chrome-headless-shell';
+    return readdirSync(shellRoot, { withFileTypes: true }).some((entry) => entry.isDirectory() && existsSync(path.join(shellRoot, entry.name, executable)));
+}
 /**
- * Whether the browser's executable exists on disk, or undefined when this
- * process cannot tell. Playwright resolves its browser cache from
- * `PLAYWRIGHT_BROWSERS_PATH` at module load, so the in-process check is only
- * authoritative when the run's environment agrees with this process's. A run
- * pointed at another cache is left to the CLI, which resolves against the
- * environment it is spawned with and is a no-op when nothing is missing.
+ * Whether the build the run launches (headless shell for headless chromium, else the full build)
+ * is on disk, or undefined when `env` points at another cache than this process loaded.
  */
-function isBrowserInstalled(name, env) {
+function isBrowserInstalled(name, env, headed) {
     if (env['PLAYWRIGHT_BROWSERS_PATH'] !== process.env['PLAYWRIGHT_BROWSERS_PATH'])
         return undefined;
     try {
-        return existsSync(browserType(name).executablePath());
+        const executable = browserType(name).executablePath();
+        if (headed || name !== 'chromium')
+            return existsSync(executable);
+        return headlessShellAt(executable);
     }
     catch {
         return false;
     }
 }
+/** Whether the shell beside `executable`'s full build is installed. */
+function headlessShellAt(executable) {
+    const marker = `${path.sep}chromium-`;
+    const at = executable.lastIndexOf(marker);
+    if (at === -1)
+        return false;
+    const revision = executable.slice(at + marker.length).split(path.sep)[0] ?? '';
+    return revision !== '' && headlessShellInstalled(executable.slice(0, at), revision);
+}
 /** The `node` arguments that run the pinned `playwright-core` CLI with `args`. */
 function playwrightCliArgs(args) {
     const require = createRequire(import.meta.url);
@@ -37,7 +53,10 @@ function playwrightCliArgs(args) {
  */
 export function runPlaywrightCli(args) {
     return new Promise((resolve, reject) => {
-        const child = spawn(process.execPath, playwrightCliArgs(args), { stdio: 'inherit' });
+        const child = spawn(process.execPath, playwrightCliArgs(args), {
+            stdio: 'inherit',
+            env: installEnvironment(),
+        });
         const forward = (signal) => child.kill(signal);
         process.on('SIGINT', forward);
         process.on('SIGTERM', forward);
@@ -55,6 +74,16 @@ export function runPlaywrightCli(args) {
         });
     });
 }
+/** The `playwright install` arguments for `names`: `--only-shell` on a headless chromium run. */
+export function installArgs(names, headed) {
+    if (headed || !names.includes('chromium'))
+        return [...names];
+    return ['--only-shell', ...names];
+}
+/** `env` with `PLAYWRIGHT_SKIP_BROWSER_GC=1` unless already set, so an install keeps other tools' browsers. */
+function installEnvironment(env = process.env) {
+    return { ...env, PLAYWRIGHT_SKIP_BROWSER_GC: env['PLAYWRIGHT_SKIP_BROWSER_GC'] ?? '1' };
+}
 /**
  * Ensures the given Playwright browsers are installed, downloading any
  * missing ones via `playwright-core install`. Called from the engine's `prepare`,
@@ -65,7 +94,8 @@ export function runPlaywrightCli(args) {
  */
 export async function ensureBrowsersInstalled(names, options = {}) {
     const env = options.env ?? process.env;
-    const isInstalled = options.isInstalled ?? ((name) => isBrowserInstalled(name, env));
+    const headed = options.headed ?? false;
+    const isInstalled = options.isInstalled ?? ((name) => isBrowserInstalled(name, env, headed));
     const verdicts = new Map([...new Set(names)].map((name) => [name, isInstalled(name)]));
     const missing = [...verdicts.keys()].filter((name) => verdicts.get(name) !== true);
     if (missing.length === 0)
@@ -78,7 +108,7 @@ export async function ensureBrowsersInstalled(names, options = {}) {
     if (knownMissing)
         log(`Downloading missing Playwright browsers (first run): ${missing.join(', ')}...`);
     const install = options.install ?? runPlaywrightInstall;
-    await install(missing, { log, signal: options.signal, env });
+    await install(missing, { log, signal: options.signal, env: installEnvironment(env), headed });
     if (knownMissing)
         log('Browser download complete.');
 }
@@ -109,13 +139,13 @@ function forwardLines(stream, log) {
     stream.on('end', () => flush(pending));
 }
 /** Spawns `node <playwright-core>/cli.js install <names>`, narrating its output through `log`. */
-function runPlaywrightInstall(names, { log, signal, env }) {
+function runPlaywrightInstall(names, { log, signal, env, headed }) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted === true) {
             reject(new EngineError('CANCELLED', 'browser install cancelled', { retryable: false }));
             return;
         }
-        const child = spawn(process.execPath, playwrightCliArgs(['install', ...names]), {
+        const child = spawn(process.execPath, playwrightCliArgs(['install', ...installArgs(names, headed)]), {
             stdio: ['ignore', 'pipe', 'pipe'],
             env,
         });

package/dist/observation-capture.d.ts

@@ -2,10 +2,9 @@
 import type { Page } from 'playwright-core';
 import { type EngineObserveOptions, type OperationContext } from 'e2e/engine';
 import { RefRegistry, type CapturedObservation } from './refs.ts';
-interface CaptureSettings {
+export interface CaptureSettings {
     readonly testIdAttribute: string;
     readonly site: string | undefined;
 }
 /** Captures under one deadline, retaining no refs from a failed or abandoned document. */
 export declare function captureObservation(page: Page, refs: RefRegistry, settings: CaptureSettings, operation: OperationContext, options: EngineObserveOptions | undefined): Promise<CapturedObservation>;
-export {};

package/dist/observation.d.ts

@@ -59,4 +59,20 @@ export interface CapturedDocument {
  * observation. The node budget is shared across all documents.
  */
 export declare function captureDocument(deps: CaptureDeps, host: DocumentHost, options: CaptureOptions): Promise<CapturedDocument>;
+type Rect = NonNullable<SemanticNode['rect']>;
+/**
+ * Where a frame element's content box, the box its document's viewport
+ * fills, sits inside its border box: past the border and the padding. Runs in
+ * the page.
+ */
+export declare function frameContentInset(element: Element): Rect;
+/** A frame element's content box, from its border box and `frameContentInset`. */
+export declare function contentBox(border: Rect, inset: Rect): Rect;
+/**
+ * A box a child document measured against its own viewport, in the top-level
+ * viewport's space: shifted by the frame's box and clipped to it; undefined
+ * when nothing of it is inside the frame.
+ */
+export declare function placeRectInFrame(rect: Rect, frame: Rect): Rect | undefined;
 export declare function toSemanticNode(ref: NodeRef, raw: RawNodeData, children?: readonly SemanticNode[], framePath?: readonly string[]): SemanticNode;
+export {};

package/dist/observation.js

@@ -129,6 +129,11 @@ async function captureInto(deps, scope, stage, host, framePath, budget, signal)
             truncated = true;
             continue;
         }
+        const inset = await scope.read(() => elements[index].evaluate(frameContentInset).catch(() => undefined));
+        if (inset === undefined) {
+            truncated = true;
+            continue;
+        }
         const child = await scope.read(() => captureDocument({ ...deps, commit: stage }, frame, {
             framePath: [...framePath, selector],
             budget: remaining,
@@ -139,7 +144,7 @@ async function captureInto(deps, scope, stage, host, framePath, budget, signal)
             truncated = true;
             continue;
         }
-        frameChildren.set(index, child.tree);
+        frameChildren.set(index, { tree: child.tree, inset });
         nodeCount += child.nodeCount;
         truncated ||= child.truncated;
     }
@@ -205,16 +210,16 @@ function assembleTree(nodes, ids, framePath, frameChildren) {
     for (let index = nodes.length - 1; index >= 0; index -= 1) {
         const raw = nodes[index];
         const embedded = frameChildren.get(index);
-        // A child document measured its nodes against its own viewport. Shifted by
-        // the boundary element's box and clipped to it, every box in the tree is
-        // in the top-level viewport's CSS pixels, the space the screenshot and a
-        // point tap share, and a child that overflows its frame cannot claim a
-        // point over the page around it. The shift is the frame's border box; a
-        // bordered iframe is off by its border width, which is within a tap
-        // target. A frame under a CSS transform is not unwound: its boxes are
-        // where the untransformed frame would put them.
-        if (embedded !== undefined && raw.rect !== null)
-            childLists[index].unshift(placeInFrame(embedded, raw.rect));
+        // A child document measured its nodes against its own viewport, which
+        // starts at the frame element's content box. Shifted by that box and
+        // clipped to it, every box in the tree is in the top-level viewport's CSS
+        // pixels, the space the screenshot and a point tap share, and a child that
+        // overflows its frame cannot claim a point over the page around it. A
+        // frame under a CSS transform is not unwound: its boxes are where the
+        // untransformed frame would put them.
+        if (embedded !== undefined && raw.rect !== null) {
+            childLists[index].unshift(placeInFrame(embedded.tree, contentBox(raw.rect, embedded.inset)));
+        }
         const node = toSemanticNode({ id: ids[index], revision: '' }, raw, childLists[index], framePath);
         built[index] = node;
         if (raw.parent >= 0)
@@ -222,16 +227,46 @@ function assembleTree(nodes, ids, framePath, frameChildren) {
     }
     return built[0];
 }
+/**
+ * Where a frame element's content box, the box its document's viewport
+ * fills, sits inside its border box: past the border and the padding. Runs in
+ * the page.
+ */
+export function frameContentInset(element) {
+    const style = getComputedStyle(element);
+    const left = Number.parseFloat(style.paddingLeft) || 0;
+    const top = Number.parseFloat(style.paddingTop) || 0;
+    const right = Number.parseFloat(style.paddingRight) || 0;
+    const bottom = Number.parseFloat(style.paddingBottom) || 0;
+    return {
+        x: element.clientLeft + left,
+        y: element.clientTop + top,
+        width: Math.max(0, element.clientWidth - left - right),
+        height: Math.max(0, element.clientHeight - top - bottom),
+    };
+}
+/** A frame element's content box, from its border box and `frameContentInset`. */
+export function contentBox(border, inset) {
+    return { x: border.x + inset.x, y: border.y + inset.y, width: inset.width, height: inset.height };
+}
 /** The tree with every box translated into the frame's space and clipped to its box; a box left empty by the clip is dropped. */
 function placeInFrame(node, frame) {
     const { rect, ...rest } = node;
-    const placed = rect === undefined ? undefined : clipRect(offsetRect(rect, frame), frame);
+    const placed = rect === undefined ? undefined : placeRectInFrame(rect, frame);
     return {
         ...rest,
         ...(placed === undefined ? {} : { rect: placed }),
         ...(node.children === undefined ? {} : { children: node.children.map((child) => placeInFrame(child, frame)) }),
     };
 }
+/**
+ * A box a child document measured against its own viewport, in the top-level
+ * viewport's space: shifted by the frame's box and clipped to it; undefined
+ * when nothing of it is inside the frame.
+ */
+export function placeRectInFrame(rect, frame) {
+    return clipRect(offsetRect(rect, frame), frame);
+}
 function offsetRect(rect, by) {
     return { x: rect.x + by.x, y: rect.y + by.y, width: rect.width, height: rect.height };
 }

package/dist/operation-budget.d.ts

@@ -6,5 +6,19 @@ export interface ConnectionBudget {
 }
 /** Preserves the reason for an engine-owned deadline without relabeling caller cancellation. */
 export declare function connectionAbort(signal: AbortSignal, label: string): EngineError;
+/**
+ * Whether the operation's deadline may end it. `test-code` is for an
+ * operation that runs the test's own code (a download trigger): that code
+ * keeps its own steps and their budgets, so the operation is not cut under
+ * it, and only cancellation ends the wait.
+ */
+export type OperationBound = 'deadline' | 'test-code';
+/**
+ * Bounds one operation by its budget: a call still pending at the deadline
+ * is abandoned as `OPERATION_TIMEOUT` instead of holding the test until its
+ * own timeout. `remaining` hands `work` the time left before Playwright's
+ * own timeout, the one to pass Playwright.
+ */
+export declare function withOperationDeadline<T>(budget: ConnectionBudget, label: string, work: (remaining: () => ConnectionBudget) => Promise<T>, bound?: OperationBound): Promise<T>;
 /** Bounds the entire transition, aborts abandoned work, and never grants a fresh dispatch budget. */
 export declare function withConnectionBudget<T>(budget: ConnectionBudget, label: string, work: (remaining: () => ConnectionBudget) => Promise<T>): Promise<T>;

package/dist/operation-budget.js

@@ -6,6 +6,37 @@ export function connectionAbort(signal, label) {
         ? signal.reason
         : new EngineError('CANCELLED', `${label} cancelled`, { retryable: false });
 }
+/**
+ * How much sooner than an operation's deadline Playwright's own timeout
+ * fires: its error names what blocked an action, or that the input was
+ * already dispatched, and this lead lets that answer arrive before the
+ * deadline does. The deadline is for the calls Playwright never answers: an
+ * evaluate, which takes no timeout, and a point tap on a page whose renderer
+ * is stuck in a script. A budget shorter than twice the
+ * lead splits in half.
+ */
+const PLAYWRIGHT_TIMEOUT_LEAD_MS = 250;
+/**
+ * Bounds one operation by its budget: a call still pending at the deadline
+ * is abandoned as `OPERATION_TIMEOUT` instead of holding the test until its
+ * own timeout. `remaining` hands `work` the time left before Playwright's
+ * own timeout, the one to pass Playwright.
+ */
+export function withOperationDeadline(budget, label, work, bound = 'deadline') {
+    if (bound === 'test-code') {
+        const endsAt = Date.now() + budget.timeoutMs;
+        return raceAbort(() => work(() => {
+            if (budget.signal.aborted)
+                throw connectionAbort(budget.signal, label);
+            return { signal: budget.signal, timeoutMs: Math.max(1, endsAt - Date.now()) };
+        }), budget.signal, label);
+    }
+    return withConnectionBudget(budget, label, (remaining) => work(() => {
+        const current = remaining();
+        const lead = Math.min(PLAYWRIGHT_TIMEOUT_LEAD_MS, current.timeoutMs / 2);
+        return { signal: current.signal, timeoutMs: Math.ceil(current.timeoutMs - lead) };
+    }));
+}
 /** Bounds the entire transition, aborts abandoned work, and never grants a fresh dispatch budget. */
 export async function withConnectionBudget(budget, label, work) {
     const controller = new AbortController();

package/dist/provider-video.d.ts

@@ -13,8 +13,6 @@ export declare class ProviderVideo implements AttemptVideo {
     private readonly artifactsDir;
     /** The recording covers the browser, so no page starts a segment of its own. */
     readonly isArmed = false;
-    /** The provider records the browser from outside; the page's screencast stays the trace's. */
-    readonly startsScreencast = false;
     private started;
     /** The stop in flight, shared: a close that retries while a timed-out stop is still running waits for it instead of stopping twice. */
     private stopping;

package/dist/provider-video.js

@@ -13,8 +13,6 @@ export class ProviderVideo {
     artifactsDir;
     /** The recording covers the browser, so no page starts a segment of its own. */
     isArmed = false;
-    /** The provider records the browser from outside; the page's screencast stays the trace's. */
-    startsScreencast = false;
     started;
     /** The stop in flight, shared: a close that retries while a timed-out stop is still running waits for it instead of stopping twice. */
     stopping;

package/dist/support.d.ts

@@ -102,19 +102,23 @@ export declare function isTestErrorCode(cause: unknown, code: string): cause is
  * | `TimeoutError` on a read, navigation, or artifact call          | OPERATION_TIMEOUT         |
  * | `TimeoutError` on an action, log ends before the input dispatch | NOT_ACTIONABLE            |
  * | `TimeoutError` on an action, log shows the dispatch started     | ACTION_MAY_HAVE_COMMITTED |
+ * | operation deadline cut off an action, pointer, or keyboard call | ACTION_MAY_HAVE_COMMITTED |
  * | element detached / not attached / no element / resolved hidden  | NODE_STALE (retryable)    |
  * | execution context destroyed / frame detached by a navigation    | NODE_STALE (retryable)    |
+ * | strict mode violation, log ends before the input dispatch       | NODE_STALE (retryable)    |
+ * | strict mode violation, log shows the dispatch started           | ACTION_MAY_HAVE_COMMITTED |
  * | not an input / not editable / not checkable                     | NOT_ACTIONABLE            |
- * | strict mode violation, anything else                            | ENGINE_FAILURE           |
+ * | anything else                                                   | ENGINE_FAILURE            |
  *
  * The action split is read from the call log Playwright appends to a timeout
- * message: `performing <x> action`, `<x> action done`, and `waiting for
- * scheduled navigations to finish` are only logged once the input is being (or
- * has been) dispatched, so a timeout whose log reaches them is uncertain and
- * the harness must not blindly repeat it. Every earlier line (`waiting for
- * element to be visible, enabled and stable`, `scrolling into view if
- * needed`, `retrying <x> action`) precedes dispatch and is a plain
- * actionability miss.
+ * or strict mode message: `performing <x> action`, `<x> action done`, and
+ * `waiting for scheduled navigations to finish` are only logged once the input
+ * is being (or has been) dispatched, so a failure whose log reaches them is
+ * uncertain and the harness must not blindly repeat it. Every earlier line
+ * (`waiting for element to be visible, enabled and stable`, `scrolling into
+ * view if needed`, `retrying <x> action`) precedes dispatch and is a plain
+ * actionability miss. Only whole `- ` log lines count, so a locator or element
+ * text quoting those words never does.
  */
 export declare const POST_DISPATCH_PATTERN: RegExp;
 /** Translates an unexpected Playwright error at the contract boundary. */
@@ -142,7 +146,7 @@ export declare function performViewportSwipe(page: Page, direction: ScrollDirect
  * CSS pixel instead.
  */
 export declare function nearestPixel(point: ViewportPoint): ViewportPoint;
-/** A pointer drag from one viewport point to another, on whole pixels, with an intermediate move so drag handlers see motion. */
-export declare function performPointDrag(mouse: Mouse, start: ViewportPoint, end: ViewportPoint): Promise<void>;
+/** A pointer drag from one viewport point to another, on whole pixels, with an intermediate move so drag handlers see motion; paced over `durationMs` when given. */
+export declare function performPointDrag(mouse: Mouse, start: ViewportPoint, end: ViewportPoint, durationMs?: number, signal?: AbortSignal): Promise<void>;
 export declare function performElementSwipe(target: ActionTarget, direction: ScrollDirection, momentum: Momentum, timeout: number): Promise<void>;
 export {};

package/dist/support.js

@@ -1,4 +1,5 @@
 /** Shared error translation, filename, and swipe helpers for the Playwright engine. */
+import { setTimeout } from 'node:timers/promises';
 import { EngineError, withinCleanupBudget } from 'e2e/engine';
 import { ConfigurationError, InfrastructureError, TestError } from 'e2e/engine';
 export const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
@@ -193,11 +194,12 @@ export class ErrorLatch {
     }
 }
 /**
- * The runner error classes as their `name` reads. A project loads this engine
- * from its config file in one module realm (tsx) while the runner's core runs
- * in another, so a runner error reaching the engine is often a `TestError`
- * from a copy of `e2e` this module never imported: `instanceof` says no while
- * `name` and `code` still tell the truth.
+ * The runner error classes as their `name` reads. A project can load this
+ * engine against a copy of `e2e` other than the one the runner's core runs
+ * from (and e2e before 0.17 always loaded config in a module realm of its
+ * own), so a runner error reaching the engine can be a `TestError` this
+ * module never imported: `instanceof` says no while `name` and `code` still
+ * tell the truth.
  */
 const CLASSIFIED_NAMES = new Set([
     'EngineError',
@@ -236,21 +238,25 @@ export function isTestErrorCode(cause, code) {
  * | `TimeoutError` on a read, navigation, or artifact call          | OPERATION_TIMEOUT         |
  * | `TimeoutError` on an action, log ends before the input dispatch | NOT_ACTIONABLE            |
  * | `TimeoutError` on an action, log shows the dispatch started     | ACTION_MAY_HAVE_COMMITTED |
+ * | operation deadline cut off an action, pointer, or keyboard call | ACTION_MAY_HAVE_COMMITTED |
  * | element detached / not attached / no element / resolved hidden  | NODE_STALE (retryable)    |
  * | execution context destroyed / frame detached by a navigation    | NODE_STALE (retryable)    |
+ * | strict mode violation, log ends before the input dispatch       | NODE_STALE (retryable)    |
+ * | strict mode violation, log shows the dispatch started           | ACTION_MAY_HAVE_COMMITTED |
  * | not an input / not editable / not checkable                     | NOT_ACTIONABLE            |
- * | strict mode violation, anything else                            | ENGINE_FAILURE           |
+ * | anything else                                                   | ENGINE_FAILURE            |
  *
  * The action split is read from the call log Playwright appends to a timeout
- * message: `performing <x> action`, `<x> action done`, and `waiting for
- * scheduled navigations to finish` are only logged once the input is being (or
- * has been) dispatched, so a timeout whose log reaches them is uncertain and
- * the harness must not blindly repeat it. Every earlier line (`waiting for
- * element to be visible, enabled and stable`, `scrolling into view if
- * needed`, `retrying <x> action`) precedes dispatch and is a plain
- * actionability miss.
+ * or strict mode message: `performing <x> action`, `<x> action done`, and
+ * `waiting for scheduled navigations to finish` are only logged once the input
+ * is being (or has been) dispatched, so a failure whose log reaches them is
+ * uncertain and the harness must not blindly repeat it. Every earlier line
+ * (`waiting for element to be visible, enabled and stable`, `scrolling into
+ * view if needed`, `retrying <x> action`) precedes dispatch and is a plain
+ * actionability miss. Only whole `- ` log lines count, so a locator or element
+ * text quoting those words never does.
  */
-export const POST_DISPATCH_PATTERN = /performing \w+ action|\w+ action done|waiting for scheduled navigations to finish/i;
+export const POST_DISPATCH_PATTERN = /^\s*- (performing \w+ action|[\w ]+ action done|waiting for scheduled navigations to finish)\s*$/im;
 /** Translates an unexpected Playwright error at the contract boundary. */
 export function translatePwError(cause, operation) {
     if (isClassified(cause))
@@ -321,16 +327,31 @@ export async function performViewportSwipe(page, direction, momentum) {
 export function nearestPixel(point) {
     return { x: Math.round(point.x), y: Math.round(point.y) };
 }
-/** A pointer drag from one viewport point to another, on whole pixels, with an intermediate move so drag handlers see motion. */
-export async function performPointDrag(mouse, start, end) {
+/** A pointer drag from one viewport point to another, on whole pixels, with an intermediate move so drag handlers see motion; paced over `durationMs` when given. */
+export async function performPointDrag(mouse, start, end, durationMs, signal) {
     const from = nearestPixel(start);
     const to = nearestPixel(end);
     const middle = nearestPixel({ x: (from.x + to.x) / 2, y: (from.y + to.y) / 2 });
     await mouse.move(from.x, from.y);
     await mouse.down();
-    await mouse.move(middle.x, middle.y);
-    await mouse.move(to.x, to.y);
-    await mouse.up();
+    try {
+        if (durationMs !== undefined) {
+            const steps = Math.max(2, Math.round(durationMs / 16));
+            const startedAt = performance.now();
+            for (let step = 1; step <= steps; step += 1) {
+                const due = startedAt + (durationMs * step) / steps;
+                await setTimeout(Math.max(0, due - performance.now()), undefined, { signal });
+                await mouse.move(from.x + ((to.x - from.x) * step) / steps, from.y + ((to.y - from.y) * step) / steps);
+            }
+        }
+        else {
+            await mouse.move(middle.x, middle.y);
+            await mouse.move(to.x, to.y);
+        }
+    }
+    finally {
+        await mouse.up();
+    }
 }
 export async function performElementSwipe(target, direction, momentum, timeout) {
     // Hover first: it auto-waits for visibility on both target kinds, so the

package/dist/surface.d.ts

@@ -11,6 +11,7 @@ import { type EngineAttemptContext, type EngineCleanupContext, type EngineInitIn
 import { type BrowserName } from './browser-connection.ts';
 import { type BrowserProvider, type LeaseDownloads } from './provider.ts';
 import { DialogRouter } from './dialogs.ts';
+import { type OperationBound } from './operation-budget.ts';
 import { type WebInitScript } from './init-scripts.ts';
 import { ErrorLatch } from './support.ts';
 type RoutePredicate = (url: URL) => boolean;
@@ -106,8 +107,7 @@ export interface WebOptions {
      * page, deterministic and agent-driven alike. Injecting headers routes
      * every request of the attempt, which turns the browser's HTTP cache off
      * and blocks service workers (a worker's requests bypass routing, so a
-     * page it controlled would reach the gate bare), and a Playwright trace
-     * records request headers.
+     * page it controlled would reach the gate bare).
      */
     readonly headers?: Readonly<Record<string, string>>;
     /**
@@ -186,6 +186,10 @@ export declare class PlaywrightSurface {
     private projectRoot;
     private headed;
     private artifactsDir;
+    /** Navigations the engine has in flight, which the app log leaves to the step that started them. */
+    private ownNavigations;
+    /** What the attempt tells its trace beside the app log; absent between attempts. */
+    private trace;
     private artifactCounter;
     /**
      * Attempt-scoped network routes. Registered on the
@@ -260,8 +264,8 @@ export declare class PlaywrightSurface {
      * Releases attempt resources, the worker's shared browser process, and a
      * lease the worker acquired for itself: three independent tasks, in that
      * order, every one attempted whatever the earlier ones did, and the first
-     * failure reported once all ran. A billed browser outlives a failed trace
-     * flush otherwise.
+     * failure reported once all ran. A billed browser outlives a failed
+     * recording flush otherwise.
      */
     dispose(context: EngineCleanupContext): Promise<void>;
     /** Returns the active attempt, including its connection generation and references. */
@@ -276,6 +280,12 @@ export declare class PlaywrightSurface {
     projectPath(file: string): string;
     /** Removes one registered route from the attempt and the current context. */
     unroute(predicate: RoutePredicate, handler: RouteHandler): Promise<void>;
+    /**
+     * The attempt's open page, or undefined, for a reader beside the test (the
+     * trace): unlike `requirePage`, it leaves an error a handler latched for
+     * the test's next operation to throw.
+     */
+    private openPage;
     requirePage(): Page;
     requireContext(): BrowserContext;
     /**
@@ -297,14 +307,20 @@ export declare class PlaywrightSurface {
      * The single entry of every operation: rethrows an error latched on an
      * unawaited path, refuses a cancelled operation, races `fn` against the
      * operation signal so an abort mid-call surfaces as `CANCELLED` instead of
-     * waiting out Playwright, and translates raw errors at the contract
+     * waiting out Playwright, bounds it by the operation's budget so a call a
+     * hung page never answers is `OPERATION_TIMEOUT`, and translates raw errors at the contract
      * boundary. `translate` overrides the default translation for operations
-     * with a documented retryable failure mode.
+     * with a documented retryable failure mode; `bound` is `test-code` for an
+     * operation that runs the test's own code, which the deadline never cuts.
      */
-    guard<T>(operation: OperationContext, label: string, fn: (operation: OperationContext) => Promise<T>, translate?: (cause: unknown, label: string) => Error): Promise<T>;
+    guard<T>(operation: OperationContext, label: string, fn: (operation: OperationContext) => Promise<T>, translate?: (cause: unknown, label: string) => Error, bound?: OperationBound): Promise<T>;
     /** Opens one URL the harness resolved; the attempt's page is created on first use. */
     open(url: string, operation: OperationContext): Promise<void>;
     back(operation: OperationContext): Promise<void>;
+    /** Runs one navigation the engine itself makes, so the app log leaves it to the step that asked for it. */
+    navigating<T>(work: () => Promise<T>): Promise<T>;
+    /** Resolves with what an action resolved with once the trace has the screen it left (`TraceFeed.screenAfterAction`); an action that failed leaves none. */
+    private acted;
     /** Restarts the document while retaining this attempt's context and storage. */
     restart(operation: OperationContext): Promise<void>;
     /** Replaces the context with a clean one and opens its blank page. */
@@ -353,9 +369,12 @@ export declare class PlaywrightSurface {
      * Checks that every frame selector along the expression matches exactly one
      * element, each counted inside the frame before it, the way `project` walks
      * the same chain; a frame-scoped `count` is 0 until that frame's document
-     * has loaded, which is what makes `FRAME_NOT_FOUND` worth retrying.
+     * has loaded, which is what makes `FRAME_NOT_FOUND` worth retrying. Returns
+     * the innermost frame's content box in the top-level viewport, where its
+     * document's viewport starts: undefined for an expression in the main
+     * document, null for a frame with no box.
      */
-    private validateFrames;
+    private frameBox;
     /**
      * Reserves one artifact path under the attempt directory: a per-attempt
      * counter keeps names unique, the label keeps them readable.
@@ -366,11 +385,7 @@ export declare class PlaywrightSurface {
     };
     /** Redacted at the source: secure fields in every frame are masked, as in observation pixels. */
     screenshot(label: string | undefined, operation: OperationContext): Promise<string>;
-    /** Starts tracing the current attempt. */
-    startTrace(operation: OperationContext): Promise<void>;
-    /** Returns every trace segment finalized by the current attempt. */
-    stopTrace(operation: OperationContext): Promise<string | readonly string[]>;
-    /** Starts the attempt's video before a trace chooses its screencast dimensions. */
+    /** Starts the attempt's video. */
     startVideo(operation: OperationContext): Promise<void>;
     /** Finishes the attempt's recording and returns its finalized segments. */
     stopVideo(operation: OperationContext): Promise<readonly VideoSegment[]>;