craftdriver 0.1.0 → 0.2.0

package/dist/lib/browser.d.ts

@@ -1,12 +1,19 @@
 import { ChromeService } from './chrome.js';
-import { Driver } from './driver.js';
+import { FirefoxService } from './firefox.js';
 import { By } from './by.js';
 import { Condition, WaitOptions } from './wait.js';
 import { ElementHandle } from './elementHandle.js';
-import { KeyboardController } from './keyboard.js';
-import { MouseController } from './mouse.js';
+import { Locator } from './locator.js';
+import { Keyboard } from './keyboard.js';
+import { Mouse } from './mouse.js';
 import { ActionsBuilder } from './actions.js';
-import { NetworkInterceptor, LogMonitor, SessionStateManager, type SessionState, type StorageStateOptions } from './bidi/index.js';
+import { NetworkInterceptor, LogMonitor, SessionStateManager, type SessionState, type StorageStateOptions, type InterceptedRequest, type InterceptedResponse } from './bidi/index.js';
+import { Frame } from './frame.js';
+import { Page } from './page.js';
+import { BrowserContext } from './browserContext.js';
+import { type TraceStartOptions } from './tracing.js';
+import { A11y } from './a11y.js';
+import { Clock } from './clock.js';
 /** Device metrics for custom mobile emulation */
 export interface DeviceMetrics {
     width: number;
@@ -24,6 +31,25 @@ export interface MobileEmulation {
     /** Custom user agent string */
     userAgent?: string;
 }
+/**
+ * Options for {@link Browser.emulate}. Every field is independent; only the
+ * keys you pass are applied, others stay at their previous value. Passing
+ * `null` for a field clears the override for that field.
+ */
+export interface EmulateOptions {
+    /** `prefers-color-scheme` media query value. Chromium only. */
+    colorScheme?: 'light' | 'dark' | 'no-preference' | null;
+    /** `prefers-reduced-motion` media query value. Chromium only. */
+    reducedMotion?: 'reduce' | 'no-preference' | null;
+    /** `forced-colors` media query value. Chromium only. */
+    forcedColors?: 'active' | 'none' | null;
+    /** BCP-47 language tag, e.g. `'de-DE'`. Affects `navigator.language` and `Intl.*`. */
+    locale?: string | null;
+    /** IANA timezone, e.g. `'Europe/Berlin'`. Affects `Intl.DateTimeFormat` and `Date`. */
+    timezoneId?: string | null;
+    /** When `true`, network requests fail and `navigator.onLine === false`. Chromium only. */
+    offline?: boolean;
+}
 /** Common mobile device presets */
 export declare const devices: {
     readonly 'iPhone 14': {
@@ -109,22 +135,93 @@ export declare const devices: {
 };
 export type DeviceName = keyof typeof devices;
 export interface LaunchOptions {
-    browserName?: 'chrome' | 'chromium' | 'firefox' | 'edge' | 'safari';
+    browserName?: 'chrome' | 'chromium' | 'firefox';
     chromeService?: ChromeService;
-    /** Enable BiDi features (network interception, logs, etc.) */
+    firefoxService?: FirefoxService;
+    /**
+     * Enable WebDriver BiDi for network interception, logs, load events, etc.
+     * **Defaults to `true`** — BiDi is the primary protocol; Classic WebDriver
+     * is used only as a fallback when a capability is not yet available via BiDi.
+     * Set `false` only if your environment cannot negotiate a BiDi WebSocket.
+     */
     enableBiDi?: boolean;
-    /** Load session state from file on launch */
+    /** Load session state from file on launch. BiDi is always used when this is set. */
     storageState?: string;
     /** Enable mobile device emulation (Chrome/Chromium only) */
     mobileEmulation?: MobileEmulation | DeviceName;
+    /**
+     * Directory where downloaded files are saved.
+     * Defaults to a temporary directory unique to this browser session.
+     */
+    downloadsDir?: string;
+}
+/**
+ * When to consider a navigation complete.
+ * - `'load'` — page `load` event has fired (default)
+ * - `'domcontentloaded'` — `DOMContentLoaded` has fired (faster, no waiting for images/fonts)
+ * - `'networkidle'` — `load` + no in-flight requests for 500 ms
+ * - `'none'` — do not wait; return as soon as the navigation is initiated
+ */
+export type LoadState = 'load' | 'domcontentloaded' | 'networkidle' | 'none';
+/** The type of a browser dialog. */
+export type DialogType = 'alert' | 'confirm' | 'prompt' | 'beforeunload';
+/**
+ * Represents an open browser dialog (alert / confirm / prompt).
+ * Passed to handlers registered with `browser.onDialog()`.
+ */
+export interface Dialog {
+    /** Returns the dialog type: `'alert'`, `'confirm'`, `'prompt'`, or `'beforeunload'`. */
+    type(): DialogType;
+    /** Returns the message text shown in the dialog. */
+    message(): string;
+    /** Returns the default text pre-filled in a prompt dialog (empty string for non-prompt dialogs). */
+    defaultValue(): string;
+    /** Accept the dialog (OK button). For prompts, optionally pass `text` to fill the input first. */
+    accept(text?: string): Promise<void>;
+    /** Dismiss the dialog (Cancel button / close). */
+    dismiss(): Promise<void>;
+}
+/** A file downloaded during a `waitForDownload()` call. */
+export interface Download {
+    /** Absolute path to the downloaded file on disk. */
+    path: string;
+    /** The filename as suggested by the server (from Content-Disposition or URL). */
+    suggestedFilename: string;
+    /** Copy the file to `targetPath`. */
+    saveAs(targetPath: string): Promise<void>;
 }
 export declare class Browser {
     private driver;
     private bidiSession?;
     private _network?;
+    private _defaultContext?;
+    /** Cache of {@link BrowserContext} wrappers keyed by user-context id. */
+    private _contextsById;
     private _logs?;
+    private _tracer?;
     private _storage?;
+    private _a11y?;
+    private _clock?;
+    private _downloadsDir?;
+    private _driverService?;
+    private _browserName;
+    /** Active emulation overrides, re-applied to new top-level contexts. */
+    private _emulation;
+    /** Mutable browser-level defaults. Use setDefaultTimeout() / setDefaultNavigationTimeout() to change. */
+    private defaults;
     private constructor();
+    /**
+     * Set the default timeout (ms) used by all element actions, waits, and assertions
+     * when no per-call `{ timeout }` option is provided. Default: 5000.
+     */
+    setDefaultTimeout(ms: number): void;
+    /**
+     * Set the default navigation timeout (ms) used by navigateTo and load-state waits.
+     * Default: 30000.
+     */
+    setDefaultNavigationTimeout(ms: number): void;
+    /** Returns the current default timeout. Used as a live getter passed to ElementHandle / expectSelector. */
+    private getDefaultTimeout;
     static launch(options?: LaunchOptions): Promise<Browser>;
     /**
      * Initialize BiDi WebSocket connection
@@ -148,6 +245,26 @@ export declare class Browser {
      * Works with both BiDi and Classic WebDriver
      */
     get storage(): SessionStateManager;
+    /**
+     * Virtual clock control — freeze or advance `Date`, `setTimeout`, and
+     * `setInterval` inside the page.  Requires BiDi (enabled by default).
+     *
+     * ```ts
+     * await browser.clock.install({ time: '2026-01-01T09:00:00Z' });
+     * await browser.clock.fastForward('15:01');
+     * ```
+     */
+    get clock(): Clock;
+    /**
+     * Accessibility audits via axe-core (optional peer dependency).
+     *
+     * ```ts
+     * await browser.a11y.check({ disableRules: ['color-contrast'] });
+     * ```
+     *
+     * Requires `axe-core` to be installed: `npm install --save-dev axe-core`.
+     */
+    get a11y(): A11y;
     /**
      * Save current session state (cookies + localStorage) to file
      */
@@ -156,7 +273,152 @@ export declare class Browser {
      * Load session state from file
      */
     loadState(path: string): Promise<void>;
-    navigateTo(url: string): Promise<void>;
+    navigateTo(url: string, opts?: {
+        waitUntil?: LoadState;
+    }): Promise<void>;
+    /**
+     * Navigate the active page back one step in its session history.
+     * Proxies to {@link Page.goBack} on {@link activePage}.
+     */
+    goBack(): Promise<void>;
+    /**
+     * Navigate the active page forward one step in its session history.
+     * Proxies to {@link Page.goForward} on {@link activePage}.
+     */
+    goForward(): Promise<void>;
+    /**
+     * Reload the active page. Proxies to {@link Page.reload} on
+     * {@link activePage}.
+     */
+    reload(): Promise<void>;
+    /**
+     * Return the full HTML serialization of the active page.
+     * Proxies to {@link Page.content}.
+     */
+    content(): Promise<string>;
+    /**
+     * Replace the active page contents with the given HTML.
+     * Proxies to {@link Page.setContent}.
+     */
+    setContent(html: string, opts?: {
+        waitUntil?: Exclude<LoadState, 'networkidle'>;
+    }): Promise<void>;
+    /**
+     * Resize the viewport at runtime.
+     *
+     * - **BiDi** path uses `browsingContext.setViewport` on the active page,
+     *   which resizes the *layout* viewport without changing the OS window.
+     * - **Classic** fallback uses `POST /session/{id}/window/rect`, which
+     *   resizes the OS window — the inner viewport may end up a few pixels
+     *   smaller than `width`/`height` because of browser chrome.
+     *
+     * For full mobile emulation (DPR, user-agent, touch), pass
+     * `mobileEmulation` to {@link Browser.launch}; this method only changes
+     * the viewport box.
+     */
+    setViewportSize(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    /**
+     * Override one or more permissions for an origin (or for every origin
+     * if `origin` is omitted).
+     *
+     * Uses BiDi `permissions.setPermission` (W3C Permissions module).
+     * Each name in `permissions` corresponds to a `PermissionDescriptor.name`,
+     * for example: `'geolocation'`, `'notifications'`, `'clipboard-read'`,
+     * `'clipboard-write'`, `'camera'`, `'microphone'`, `'midi'`,
+     * `'background-sync'`, `'persistent-storage'`.
+     *
+     * @example
+     * await browser.grantPermissions(['geolocation', 'notifications']);
+     * await browser.grantPermissions(['clipboard-read'], { origin: 'https://example.com' });
+     */
+    grantPermissions(permissions: string[], opts?: {
+        origin?: string;
+        state?: 'granted' | 'denied' | 'prompt';
+    }): Promise<void>;
+    /**
+     * Reset all permissions for an origin (or every origin) back to the
+     * browser default of `'prompt'`. Convenience wrapper around
+     * {@link grantPermissions} with `state: 'prompt'`.
+     */
+    clearPermissions(permissions: string[], opts?: {
+        origin?: string;
+    }): Promise<void>;
+    /**
+     * Override the geolocation reported by `navigator.geolocation`.
+     *
+     * Uses BiDi `emulation.setGeolocationOverride` (W3C BiDi
+     * `emulation` module). Pass `null` to clear the override and return
+     * to the real device location.
+     *
+     * @example
+     * await browser.setGeolocation({ latitude: 51.5074, longitude: -0.1278 });
+     * await browser.setGeolocation(null); // clear
+     */
+    setGeolocation(coords: {
+        latitude: number;
+        longitude: number;
+        accuracy?: number;
+    } | null): Promise<void>;
+    /**
+     * Override what the page sees from `matchMedia`, `navigator.language`,
+     * `Intl.*`, and the network stack.
+     *
+     * Pass `null` for any field to clear that override; pass `{}` for a no-op.
+     * Settings persist across navigations and are re-applied to new top-level
+     * pages opened in the same session.
+     *
+     * | Field | Transport | Cross-browser |
+     * |---|---|---|
+     * | `locale` | BiDi `emulation.setLocaleOverride` | yes |
+     * | `timezoneId` | BiDi `emulation.setTimezoneOverride` | yes |
+     * | `colorScheme` / `reducedMotion` / `forcedColors` | CDP `Emulation.setEmulatedMedia` | Chromium only |
+     * | `offline` | CDP `Network.emulateNetworkConditions` | Chromium only |
+     *
+     * Throws with a clear message if a Chromium-only field is requested on
+     * Firefox, or if BiDi negotiation failed at launch.
+     *
+     * @example
+     * ```ts
+     * // Dark mode + German formatting + Berlin time
+     * await browser.emulate({
+     *   colorScheme: 'dark',
+     *   locale: 'de-DE',
+     *   timezoneId: 'Europe/Berlin',
+     * });
+     *
+     * // Offline PWA UI
+     * await browser.emulate({ offline: true });
+     * await browser.click('#refresh');
+     *
+     * // Clear a single override
+     * await browser.emulate({ locale: null });
+     * ```
+     */
+    emulate(options: EmulateOptions): Promise<void>;
+    /**
+     * Send a CDP command scoped to a single top-level browsing context.
+     * Uses the chromium-bidi `goog:cdp` vendor extension. Wraps protocol
+     * errors so callers see an actionable message.
+     */
+    private _cdpForContext;
+    /** Best-effort: derive the active page's origin (`scheme://host[:port]`). */
+    private _currentOrigin;
+    /**
+     * Wait for the page to reach a given load state.
+     * Call this after an action that triggers navigation (clicking a link, submitting a form).
+     *
+     * - `'load'` — page `load` event (default)
+     * - `'domcontentloaded'` — DOMContentLoaded (faster)
+     * - `'networkidle'` — load + no in-flight requests for 500 ms
+     *
+     * Uses BiDi events when available, falls back to polling `document.readyState`.
+     */
+    waitForLoadState(state?: Exclude<LoadState, 'none'>, opts?: {
+        timeout?: number;
+    }): Promise<void>;
     url(): Promise<string>;
     title(): Promise<string>;
     wait<T>(condition: Condition<T>, options?: WaitOptions & {
@@ -164,7 +426,324 @@ export declare class Browser {
     }): Promise<T>;
     wait<T>(condition: Condition<T>, timeoutMs?: number, intervalMs?: number, message?: string): Promise<T>;
     quit(): Promise<void>;
-    click(selector: string | By): Promise<void>;
+    /**
+     * Start a streaming trace session. Writes every event synchronously to
+     * `<outDir>/trace.ndjson` so a thrown `expect` on the next line cannot
+     * lose data. Screenshots, when enabled, land in `<outDir>/screenshots/`.
+     *
+     * **BiDi-only.** Call `stopTrace()` to write the closing marker and
+     * close the file.
+     *
+     * @example
+     * await browser.startTrace({ outDir: './artefacts/login' });
+     * try {
+     *   await browser.navigateTo('/checkout');
+     *   await browser.click('#pay');
+     * } finally {
+     *   await browser.stopTrace();
+     * }
+     */
+    startTrace(opts: TraceStartOptions): Promise<void>;
+    /**
+     * Stop the active trace: drain in-flight screenshots, write the closing
+     * `meta` line, and close the file. If your test threw and never reached
+     * here, the file is still valid NDJSON — just without the closing line.
+     */
+    stopTrace(): Promise<void>;
+    /**
+     * Execute JavaScript in the page and return the result.
+     *
+     * Accepts a function (with optional args) or a script string:
+     * ```ts
+     * await browser.evaluate(() => document.title);
+     * await browser.evaluate((a, b) => a + b, 2, 3); // 5
+     * await browser.evaluate('return document.title');
+     * ```
+     *
+     * Uses BiDi `script.callFunction` / `script.evaluate` when available,
+     * falls back to Classic WebDriver `executeScript`.
+     * Only JSON-serializable return values are supported.
+     */
+    evaluate<T = unknown>(fn: ((...args: unknown[]) => T) | string, ...args: unknown[]): Promise<T>;
+    /**
+     * Register a script that runs before any page script on every navigation.
+     * Returns a handle with a `remove()` method to unregister it.
+     *
+     * Requires BiDi (enabled by default). Throws a clear error otherwise.
+     *
+     * ```ts
+     * const script = await browser.addInitScript(() => {
+     *   window.__flags = { darkMode: true };
+     * });
+     * await browser.navigateTo(url); // __flags is available
+     * await script.remove();         // unregister
+     * ```
+     */
+    addInitScript(fnOrSrc: ((...args: unknown[]) => unknown) | string): Promise<{
+        remove(): Promise<void>;
+    }>;
+    /**
+     * Wait for the first network request matching a URL glob or predicate.
+     * Register **before** the action that triggers the request.
+     */
+    waitForRequest(pattern: string | ((req: InterceptedRequest) => boolean), opts?: {
+        timeout?: number;
+    }): Promise<InterceptedRequest>;
+    /**
+     * Wait for the first completed response matching a URL glob or predicate.
+     * Register **before** the action that triggers the request.
+     *
+     * @example
+     * ```ts
+     * const [res] = await Promise.all([
+     *   browser.waitForResponse('/api/users'),
+     *   browser.click('#load-btn'),
+     * ]);
+     * expect(res.status).toBe(200);
+     * ```
+     */
+    waitForResponse(pattern: string | ((res: InterceptedResponse) => boolean), opts?: {
+        timeout?: number;
+    }): Promise<InterceptedResponse>;
+    /**
+     * Subscribe to **every** network request or response. Returns an
+     * `off()` function that unsubscribes the listener.
+     *
+     * Use this for fire-and-forget logging, tracing, or assertion-on-every
+     * patterns where you do not know in advance which request you care
+     * about. For one-shot waits prefer {@link waitForRequest} /
+     * {@link waitForResponse}.
+     *
+     * @example
+     * ```ts
+     * const off = browser.on('response', (res) => {
+     *   console.log(res.status, res.url);
+     * });
+     * await browser.click('#load');
+     * off();
+     * ```
+     */
+    on(event: 'request', listener: (req: InterceptedRequest) => void): () => void;
+    on(event: 'response', listener: (res: InterceptedResponse) => void): () => void;
+    /**
+     * Run `action`, then wait until a new file appears in the downloads directory.
+     * Returns a `Download` handle with `path`, `suggestedFilename`, and `saveAs()`.
+     *
+     * @example
+     * const dl = await browser.waitForDownload(() => browser.click('#download-btn'));
+     * expect(dl.suggestedFilename).toBe('report.csv');
+     * await dl.saveAs('/tmp/report.csv');
+     */
+    waitForDownload(action: () => Promise<void> | void, opts?: {
+        timeout?: number;
+    }): Promise<Download>;
+    /**
+     * Register a handler called every time a browser dialog opens (alert / confirm / prompt).
+     * The handler receives a `Dialog` object with `accept()` and `dismiss()` methods.
+     * Returns an unsubscribe function — call it to stop listening.
+     *
+     * If no handler is registered, dialogs are auto-dismissed so they don't hang the test.
+     *
+     * @example
+     * const off = browser.onDialog(async dialog => {
+     *   expect(dialog.message).toBe('Are you sure?');
+     *   await dialog.accept();
+     * });
+     * await browser.click('#confirm-btn');
+     * off(); // stop listening
+     */
+    onDialog(handler: (dialog: Dialog) => Promise<void> | void): () => void;
+    /**
+     * Accept the currently open dialog (OK / confirm).
+     * For prompt dialogs, pass `text` to type into the input first.
+     * Uses BiDi when available, Classic WebDriver otherwise.
+     */
+    acceptDialog(text?: string): Promise<void>;
+    /**
+     * Dismiss the currently open dialog (Cancel / close).
+     * Uses BiDi when available, Classic WebDriver otherwise.
+     */
+    dismissDialog(): Promise<void>;
+    /**
+     * Get the message text of the currently open dialog.
+     * Uses BiDi when available, Classic WebDriver otherwise.
+     */
+    getDialogMessage(): Promise<string>;
+    /**
+     * Wait for the next dialog (alert / confirm / prompt) to open and return it.
+     * The dialog object has `accept()` and `dismiss()` methods — call one of them
+     * or the page will be frozen waiting for the dialog.
+     *
+     * Matches Playwright's `page.waitForEvent('dialog')` pattern:
+     * ```ts
+     * const [, dialog] = await Promise.all([
+     *   browser.click('#confirm-btn'),
+     *   browser.waitForDialog(),
+     * ]);
+     * await dialog.accept();
+     * ```
+     */
+    waitForDialog(opts?: {
+        timeout?: number;
+    }): Promise<Dialog>;
+    private _buildDialog;
+    /**
+     * Return a `Frame` object scoped to the first iframe matching `selector`.
+     * All element methods on the returned `Frame` are automatically targeted
+     * inside that iframe's browsing context.
+     *
+     * @example
+     * const frame = await browser.frame('#stripe-iframe');
+     * await frame.fill('#card-number', '4242 4242 4242 4242');
+     */
+    frame(selector: string | By, opts?: {
+        timeout?: number;
+    }): Promise<Frame>;
+    /**
+     * Return `Frame` objects for all iframes on the current page.
+     */
+    frames(opts?: {
+        timeout?: number;
+    }): Promise<Frame[]>;
+    /**
+     * Return `Page` objects for all open top-level browsing contexts
+     * (tabs and popup windows).
+     */
+    pages(): Promise<Page[]>;
+    /**
+     * Open a new top-level browsing context (a tab or a window).
+     *
+     * Maps to BiDi `browsingContext.create`. **BiDi-only** — throws in Classic
+     * mode because WebDriver Classic has no spec-level command for creating
+     * top-level browsing contexts.
+     *
+     * @example
+     * const page = await browser.openPage({ url: 'https://example.com', type: 'tab' });
+     * await page.waitForLoadState();
+     */
+    openPage(opts?: {
+        url?: string;
+        type?: 'tab' | 'window';
+    }): Promise<Page>;
+    /**
+     * Run `action` and wait for a new top-level browsing context (tab / popup)
+     * to open. Returns a `Page` bound to the new context.
+     *
+     * @example
+     * const popup = await browser.waitForPage(() => browser.click('#open-popup'));
+     * await popup.waitForLoadState();
+     * const title = await popup.title();
+     */
+    waitForPage(action: () => Promise<void>, opts?: {
+        timeout?: number;
+    }): Promise<Page>;
+    /**
+     * Create a new isolated user context (an "incognito profile"). Each
+     * context has its own cookies, localStorage, and IndexedDB.
+     *
+     * Maps to BiDi `browser.createUserContext`. **BiDi-only** — throws in
+     * Classic mode because WebDriver Classic has no equivalent.
+     *
+     * Optionally pre-seed the context with a previously-saved
+     * `storageState` snapshot (object or path to JSON) — cookies are
+     * applied immediately and localStorage entries land on first
+     * navigation to each captured origin.
+     *
+     * @example
+     * const alice = await browser.newContext();
+     * const bob = await browser.newContext();
+     * const aPage = await alice.newPage({ url: 'https://app.example.com/login' });
+     * const bPage = await bob.newPage({ url: 'https://app.example.com/login' });
+     * // logging in as Alice in aPage does not leak into bPage.
+     *
+     * @example
+     * // Skip the login UI in every test by reusing a saved session.
+     * const ctx = await browser.newContext({ storageState: 'auth/alice.json' });
+     * const page = await ctx.newPage({ url: 'https://app.example.com/dashboard' });
+     *
+     * @example
+     * // Pre-configure a context for a staging tenant: every relative URL
+     * // resolves against staging, every request carries the tenant header.
+     * const ctx = await browser.newContext({
+     *   baseURL: 'https://staging.example.com',
+     *   extraHTTPHeaders: { 'X-Tenant': 'acme' },
+     * });
+     * const page = await ctx.newPage({ url: '/dashboard' });  // → staging.example.com/dashboard
+     */
+    /**
+     * Return the {@link BrowserContext} wrapper for a given BiDi user-context
+     * id, constructing it on first access and caching it thereafter. Stable
+     * across {@link defaultContext}, {@link newContext}, and {@link contexts}
+     * so route handlers, event listeners, and init scripts always live on
+     * the same instance the user holds.
+     *
+     * Caller must guarantee BiDi is connected (`bidiSession.isConnected()`).
+     */
+    private _wrapContext;
+    newContext(opts?: {
+        storageState?: SessionState | string;
+        baseURL?: string;
+        extraHTTPHeaders?: Record<string, string>;
+        /**
+         * Locale reported by `navigator.language`, `Intl.*`, and the
+         * `Accept-Language` header. Cross-browser via BiDi
+         * `emulation.setLocaleOverride`. Applies to every page in this
+         * context, including pages opened later.
+         */
+        locale?: string;
+        /**
+         * IANA timezone applied to `Date` and `Intl.DateTimeFormat`.
+         * Cross-browser via BiDi `emulation.setTimezoneOverride`. Applies to
+         * every page in this context, including pages opened later.
+         */
+        timezoneId?: string;
+        /**
+         * Coordinates returned by `navigator.geolocation`. Cross-browser via
+         * BiDi `emulation.setGeolocationOverride`. The page still needs the
+         * `geolocation` permission \u2014 use {@link BrowserContext.grantPermissions}
+         * once the origin is known.
+         */
+        geolocation?: {
+            latitude: number;
+            longitude: number;
+            accuracy?: number;
+        };
+    }): Promise<BrowserContext>;
+    /**
+     * Return all open user contexts, including the default one.
+     *
+     * Maps to BiDi `browser.getUserContexts`. **BiDi-only.**
+     */
+    contexts(): Promise<BrowserContext[]>;
+    /**
+     * The implicit default user context the browser started in (id `'default'`).
+     * Pages opened via `browser.openPage()` / `browser.waitForPage()` belong
+     * to this context. **BiDi-only.**
+     */
+    get defaultContext(): BrowserContext;
+    /**
+     * Return the currently focused top-level page in `defaultContext`.
+     *
+     * This is the page that `browser.click()`, `browser.find()`,
+     * `browser.evaluate()` and the other `Browser`-level DOM shortcuts
+     * implicitly target. It **never** crosses into pages inside a
+     * non-default `BrowserContext`.
+     *
+     * Use it to make multi-tab tests explicit:
+     *
+     * @example
+     * const page = await browser.activePage();
+     * await page.click('#submit');   // identical to browser.click('#submit')
+     *
+     * @example
+     * const popup = await browser.openPage({ url: '/help' });
+     * // browser.activePage() still returns the original page —
+     * // openPage() does not steal focus.
+     */
+    activePage(): Promise<Page>;
+    click(selector: string | By, opts?: {
+        timeout?: number;
+    }): Promise<void>;
     fill(selector: string | By, text: string, opts?: {
         timeout?: number;
     }): Promise<void>;
@@ -190,10 +769,41 @@ export declare class Browser {
             durationMs?: number;
         }) => Promise<void>;
     };
-    screenshot(selectorOrBy?: string | By): Promise<Buffer>;
-    saveScreenshot(path: string, selectorOrBy?: string | By): Promise<Buffer>;
+    /**
+     * Capture a screenshot of the active page (viewport by default), the
+     * full scrollable document (`fullPage: true`), or an element matching
+     * `selector`. Optionally write the PNG to `path`. Returns the raw PNG
+     * buffer.
+     *
+     * Full-page capture uses BiDi `browsingContext.captureScreenshot` with
+     * `origin: 'document'` and therefore requires `enableBiDi: true`
+     * (the default). Element capture composes auto-waiting via the same
+     * resolution as `find()`.
+     *
+     * @example
+     * const buf = await browser.screenshot();
+     * await browser.screenshot({ path: 'viewport.png' });
+     * await browser.screenshot({ fullPage: true, path: 'full.png' });
+     * await browser.screenshot({ selector: '#chart', path: 'chart.png' });
+     */
+    screenshot(opts?: {
+        path?: string;
+        selector?: string | By;
+        fullPage?: boolean;
+        timeout?: number;
+    }): Promise<Buffer>;
     expect(selector: string | By): import("./expect.js").ExpectApi;
     find(selector: string | By): ElementHandle;
+    /**
+     * Return a lazy, chainable `Locator` for the given selector.
+     * Prefer `locator()` over `find()` when you need composition, filtering, or indexed access.
+     */
+    locator(selector: string | By): Locator;
+    /**
+     * Return snapshot `ElementHandle`s for all elements matching `selector` at call time.
+     * Use `locator().all()` when you need filtering; use `findAll()` for the simple array case.
+     */
+    findAll(selector: string | By): Promise<ElementHandle[]>;
     getByRole(role: string, opts?: {
         name?: string;
         exact?: boolean;
@@ -209,8 +819,8 @@ export declare class Browser {
         exact?: boolean;
     }): ElementHandle;
     getByTestId(id: string): ElementHandle;
-    keyboard: KeyboardController;
-    mouse: MouseController;
+    keyboard: Keyboard;
+    mouse: Mouse;
     static Key: {
         readonly Null: string;
         readonly Cancel: string;
@@ -250,9 +860,6 @@ export declare class Browser {
         readonly F12: string;
         readonly Meta: string;
     };
-    waitFor(check: ((driver: Driver) => Promise<any> | any) | (() => Promise<any> | any), options?: WaitOptions & {
-        message?: string;
-    }): Promise<any>;
     waitForVisible(selector: string | By, opts?: {
         timeout?: number;
     }): Promise<void>;
@@ -265,6 +872,20 @@ export declare class Browser {
     waitForDetached(selector: string | By, opts?: {
         timeout?: number;
     }): Promise<void>;
+    /**
+     * Wait for an element to reach the given state.
+     *
+     * Canonical wait API; the four `waitForVisible/Hidden/Attached/Detached`
+     * methods are kept as one-line shortcuts.
+     *
+     * @example
+     * await browser.waitFor('#spinner', { state: 'hidden' });
+     * await browser.waitFor('#toast', { state: 'visible', timeout: 2000 });
+     */
+    waitFor(selector: string | By, opts: {
+        state: 'visible' | 'hidden' | 'attached' | 'detached';
+        timeout?: number;
+    }): Promise<void>;
     actions(): ActionsBuilder;
     pause(ms: number): Promise<void>;
 }