juce-webview-agent-bridge 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mateusz Siwiński
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# juce_webview_agent_bridge
+
+[![tests](https://github.com/mateusz28011/juce-webview-agent-bridge/actions/workflows/tests.yml/badge.svg)](https://github.com/mateusz28011/juce-webview-agent-bridge/actions/workflows/tests.yml)
+
+A **debug-only** JUCE module that lets an external agent (or script) drive a live
+`juce::WebBrowserComponent` over a loopback TCP socket — a "mini-CDP" giving you a
+browser-like toolkit on the **real** embedded WebView:
+
+- **eval** arbitrary JavaScript and read the result;
+- **stream** `console.*`, uncaught errors, and network — `fetch`/`XHR`,
+  `WebSocket` / `EventSource` (SSE) frames, `navigator.sendBeacon`, plus
+  `PerformanceObserver` resource timing;
+- **DOM / click / fill** (React-safe synthetic input);
+- **screenshot** the host window — or a cropped UI region — via the OS compositor
+  (captures WebGL/canvas, which in-WebView snapshot APIs can miss) on **macOS and
+  Windows 11**; Linux capture is a TODO.
+
+No Chrome DevTools Protocol is required. **WKWebView** (macOS) exposes no CDP at all
+for an embedded view; **WebView2** (Windows) can expose CDP, but only behind a
+remote-debugging flag you don't want in a shipping build. This bridge gives you one
+path that works the same on both without depending on that flag —
+eval/console/network/DOM ride on `evaluateJavascript`, which every JUCE backend
+already provides. macOS is the daily-use platform; Windows/WebView2 has also been
+verified against the home project's real Debug standalone. See **Status** below.
+
+> ⚠️ **Security.** The bridge evaluates arbitrary JS. Access is gated only by the
+> loopback (`127.0.0.1`) bind plus a per-session token — and the token sits in
+> plaintext in the discovery file, so **loopback is the real trust boundary** (there
+> is no TLS; anything that can reach localhost + read your home dir is trusted). It is
+> gated to `JUCE_DEBUG` by default (`WEB_AGENT_BRIDGE_ENABLED`). **Never ship it
+> enabled in a release build.**
+
+## Why
+
+This started in *Better Message Mycelia*, a JUCE app with a dense React +
+PixiJS/WebGL plugin UI. A browser copy could not reproduce native state or timing,
+WKWebView had no CDP, and in-page screenshots missed GPU content. The bridge made
+the running plugin observable and controllable, which enabled:
+
+- agent debugging against the real UI and C++ engine;
+- live e2e tests for controls, presets and native state;
+- performance probes using event streams and rAF frame-gap measurements.
+
+### Why not just Playwright?
+
+Playwright cannot attach to WKWebView and needs an explicitly enabled CDP endpoint
+for WebView2. This bridge instead uses JUCE's existing `evaluateJavascript` and
+native-function surfaces. It can also capture compositor-rendered WebGL and assert
+on real C++ state through `backend()`.
+
+It is not a Playwright replacement: input is synthetic, network is observe-only,
+and there is one page. You can still use the `@playwright/test` runner as a harness;
+see [`examples/playwright-test`](examples/playwright-test).
+
+## Status — what's actually been exercised
+
+Honest test coverage, so you know what you're getting:
+
+| Area | macOS (WKWebView) | Windows (WebView2) | Linux |
+|---|---|---|---|
+| eval / console / network / DOM / e2e | ✅ used daily against a real plugin | ✅ verified against a real WebView2 Debug standalone | ⚠️ untested against a real app |
+| Native screenshot (`shot`) | ✅ (macOS 14+, ScreenCaptureKit) | ✅ (Windows 11, Windows.Graphics.Capture + D3D11) | ❌ TODO |
+| C++ + JS test suites | ✅ CI | ✅ CI | ✅ CI |
+
+The Windows real-app verification covers discovery/auth, Unicode eval, console and
+fetch capture, DOM locators, React-safe fill/click, accessibility snapshots, large
+chunked reads, sink replay, and native full-window/region screenshots. WebKit layer
+inspection remains macOS-only. Linux real-app reports and fixes are very welcome.
+
+## Install
+
+**Requirements:** JUCE 8, C++17, a `juce::WebBrowserComponent`-based UI; the
+clients need Node ≥ 18 (zero runtime dependencies).
+
+It's a standard JUCE module. Get the repo — as a submodule:
+
+```bash
+git submodule add https://github.com/mateusz28011/juce-webview-agent-bridge.git modules/juce-webview-agent-bridge
+```
+
+or with CMake `FetchContent` (after JUCE has been added, so
+`juce_add_module` is available):
+
+```cmake
+include(FetchContent)
+FetchContent_Declare(juce_webview_agent_bridge
+    GIT_REPOSITORY https://github.com/mateusz28011/juce-webview-agent-bridge.git
+    GIT_TAG        v0.3.0)
+FetchContent_MakeAvailable(juce_webview_agent_bridge)
+```
+
+The module itself lives in the `juce_webview_agent_bridge/` subdirectory (JUCE requires the
+module directory to be named exactly like the module ID). Register and link it:
+
+```cmake
+# Submodule/manual checkout:
+juce_add_module(path/to/juce-webview-agent-bridge/juce_webview_agent_bridge)
+
+# FetchContent_MakeAvailable registers the module through the repo's root CMakeLists.
+target_link_libraries(MyPlugin PRIVATE juce_webview_agent_bridge)
+```
+
+Install the zero-runtime-dependency Node client separately in the project that
+owns your e2e tests. The npm package is independent of how the C++ module was
+fetched and includes strict TypeScript declarations:
+
+```bash
+npm install --save-dev juce-webview-agent-bridge
+npx juce-webview-agent-bridge ping
+```
+
+## Integrate (3 steps)
+
+```cpp
+#include <juce_webview_agent_bridge/juce_webview_agent_bridge.h>
+
+// 1. Fold capture into the WebView Options (before creating the WebView):
+auto bridge = std::make_shared<web_agent::WebAgentBridge>();
+options = web_agent::withCapture (std::move (options), bridge);   // no-op if disabled
+
+// 2. After the WebView exists, wire eval + bounds and start listening:
+web_agent::connect (*bridge, *webView, *this /* component for screen bounds */);
+bridge->start();                                                  // 127.0.0.1:8930
+
+// 3. On teardown, before the WebView is destroyed:
+bridge->stop();
+```
+
+Wrap the calls in `#if WEB_AGENT_BRIDGE_ENABLED` if you keep the `bridge` member
+unconditionally (a `std::shared_ptr` to a forward-declared type is fine).
+
+## Agent skill
+
+`skills/juce-webview-agent-bridge/` is a [skill](https://skills.sh) that teaches a coding agent
+(e.g. Claude Code) to drive the bridge — commands, the e2e client, diagnostic
+techniques, and the gotchas below in agent-digestible form:
+
+```bash
+npx skills add mateusz28011/juce-webview-agent-bridge
+```
+
+## CLI client
+
+With the npm package installed, use `npx juce-webview-agent-bridge`. A checkout can run the committed
+`tools/web-agent.mjs` build directly without installing dependencies:
+
+```bash
+npx juce-webview-agent-bridge ping
+npx juce-webview-agent-bridge eval "document.title"
+npx juce-webview-agent-bridge logs                     # live console + network stream
+npx juce-webview-agent-bridge shot /tmp/ui.png         # native compositor shot of the host window
+npx juce-webview-agent-bridge shot /tmp/panel.png "#panel"  # crop to an element
+```
+
+Other commands: `hello`, `dom`, `click`, `fill`, `capture`, `backlog`,
+`layerdebug`, and `layertree`. Port and token are normally auto-discovered.
+
+## E2E (Playwright-style)
+
+The package root exports a Playwright-shaped client with client-side auto-waiting:
+
+```js
+import { connect, expect } from 'juce-webview-agent-bridge';
+
+const page = await connect({ activate: 'My App' });
+await page.getByTestId('patch-name').fill('warm pad', { enter: true });
+await page.locator('text=Save').click();
+await expect(page.locator('.patch-row')).toHaveCount(1);
+await expect.poll(() => page.backend('getPatchCount')).toBe(1);
+page.close();
+```
+
+The client includes CSS/text/role locators, click/fill/type/drag actions,
+auto-retrying assertions, accessibility snapshots, native screenshots, live
+console/network/error events, large-value reads, render-performance probes and
+JUCE native calls. Full API and operational guidance: [docs/e2e.md](docs/e2e.md).
+
+## Discovery & auth
+
+On `start()` the host binds `127.0.0.1:8930` (scanning upward on collision) and
+publishes `{port, token}` to `~/.web_agent_bridge.json` (plus a per-instance file
+under `~/.web_agent_bridge.d/` so several hosts coexist). Clients read it
+automatically; a random per-session **token** gates every connection. The wire is
+newline-delimited JSON over TCP (`hello` / `ping` / `auth` / `eval` / `bounds` /
+`shot` / `layerdebug` / `layertree` / `sink_replay` + the unsolicited `sink` event stream) — the full op table,
+sink-frame format, and discovery details are in [docs/protocol.md](docs/protocol.md).
+
+## Known limits
+
+- Native screenshots require macOS 14+ or Windows 11 and a compositor-capturable,
+  non-minimized window. macOS permission/signing setup is in
+  [docs/screen-recording.md](docs/screen-recording.md). Linux capture is a TODO.
+- **Synthetic input** dispatched from JS has `isTrusted === false`, so APIs gated
+  behind a user gesture (file pickers, some clipboard/fullscreen) are out of reach.
+- **eval errors** are only reported on WKWebView; on WebView2 a failed eval looks
+  like a `null` result — rely on the console/error stream there.
+
+## Testing
+
+Both suites live in `tests/` and run **independently of any host app**, so they
+keep working after this module is extracted into its own repo.
+
+```bash
+# JS client — zero dependencies, Node >= 18
+npm test                     # or: node --test tests/*.test.mjs
+
+# Maintainer build — strict TypeScript source -> committed .mjs + .d.mts
+npm ci --ignore-scripts
+npm run build
+npm run test:types
+
+# C++ bridge — fetches JUCE + Catch2 on first configure
+cmake -S tests -B build/test
+cmake --build build/test
+ctest --test-dir build/test --output-on-failure
+
+# reuse a local JUCE checkout instead of downloading it:
+cmake -S tests -B build/test -DWAB_JUCE_DIR=/path/to/JUCE
+```
+
+The JS tests drive the real clients against a mock bridge; the C++ suite drives
+the real loopback server. Neither requires a host app.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) — ground rules (app-agnostic, zero client
+deps, debug-only), how to run both test suites, and the release flow. Linux capture
+support and Linux real-app verification are the most wanted contributions.
+
+## License
+
+MIT — see `LICENSE`.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "juce-webview-agent-bridge",
+  "version": "0.3.0",
+  "description": "CLI + protocol client for the juce_webview_agent_bridge debug WebView bridge (eval/console/network/click/fill/screenshot over a loopback socket, no CDP).",
+  "type": "module",
+  "types": "./tools/e2e.d.mts",
+  "exports": {
+    ".": {
+      "types": "./tools/e2e.d.mts",
+      "import": "./tools/e2e.mjs"
+    },
+    "./e2e": {
+      "types": "./tools/e2e.d.mts",
+      "import": "./tools/e2e.mjs"
+    },
+    "./shared": {
+      "types": "./tools/shared.d.mts",
+      "import": "./tools/shared.mjs"
+    }
+  },
+  "bin": {
+    "juce-webview-agent-bridge": "tools/web-agent.mjs"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test tests/*.test.mjs",
+    "test:types": "tsc -p tests/types/tsconfig.json",
+    "prepublishOnly": "npm run build && npm test && npm run test:types",
+    "release": "bash scripts/release.sh"
+  },
+  "files": [
+    "tools/",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mateusz28011/juce-webview-agent-bridge.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/tools/e2e.d.mts

@@ -0,0 +1,359 @@
+import type { Socket } from 'node:net';
+type ProtocolMessage = Record<string, any>;
+type LogFn = (message: string) => void;
+type TimeoutOptions = {
+    timeout?: number;
+};
+type RequestOptions = {
+    timeoutMs?: number;
+};
+type PollOptions = TimeoutOptions & {
+    interval?: number;
+};
+export type LayerBounds = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type ClipRect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export type AriaNode = {
+    role: string;
+    name?: string;
+    value?: string;
+    checked?: boolean;
+    disabled?: boolean;
+    children?: AriaNode[];
+};
+export type SinkEvent<T = unknown> = {
+    kind: string;
+    t: number;
+    data: T;
+    seq?: number;
+};
+export type NetworkEventData = {
+    kind?: string;
+    url?: string;
+    method?: string;
+    status?: number;
+    [key: string]: unknown;
+};
+export type Capabilities = {
+    protocolVersion: number;
+    platform: string;
+    ops: string[];
+    screenshotAvailable: boolean;
+    authRequired: boolean;
+};
+export type RenderPerfResult = {
+    durMs: number;
+    commitsPerSec: number;
+    p50gap: number;
+    p95gap: number;
+    p99gap: number;
+    maxGap: number;
+    framesOver24: number;
+    framesOver50: number;
+    measuredHz: number;
+    frameBudgetMs: number;
+    framesDroppedRel: number;
+    framesDropped2x: number;
+    p99Frames: number;
+    motion: boolean;
+};
+export type ConnectOptions = {
+    host?: string;
+    port?: number;
+    token?: string;
+    timeout?: number;
+    interval?: number;
+    log?: LogFn;
+    logFile?: string;
+    logEcho?: boolean;
+    backendTimeoutMs?: number;
+    activate?: string;
+};
+export type LocatorState = {
+    visible: boolean;
+    enabled: boolean;
+    editable: boolean;
+    hit: boolean;
+    box: ClipRect;
+    text: string;
+    value: string | null;
+    checked: boolean;
+};
+export type LocatorProbe = {
+    n: number;
+    state: LocatorState | null;
+};
+export type ActionOptions = TimeoutOptions & {
+    force?: boolean;
+};
+export type FillOptions = TimeoutOptions & {
+    enter?: boolean;
+};
+export type DragOptions = TimeoutOptions & {
+    dx?: number;
+    dy?: number;
+    steps?: number;
+    settleMs?: number;
+    stepMs?: number;
+    pointer?: boolean;
+};
+export type WaitForOptions = TimeoutOptions & {
+    state?: 'attached' | 'detached' | 'visible' | 'hidden';
+};
+export type PollExpectOptions = PollOptions & {
+    message?: string;
+};
+/** Bring the host app's window to the foreground (macOS, best-effort; resolves
+ *  false elsewhere). A backgrounded WebView reports document.hidden === true and
+ *  many apps pause timers/polling/state-sync — an agent then reads stale or empty
+ *  state even though eval works. Foregrounding the REAL window (not faking the
+ *  visibility signal) reproduces the user-visible condition, so tests assert on
+ *  live state. connect({ activate: '<App Name>' }) calls this for you. */
+export declare function activateApp(appName?: string): Promise<boolean>;
+/** A logger that appends timestamped action lines to ONE file and (by default)
+ *  echoes them to stderr so a live run shows progress instead of going silent.
+ *  Generic/agnostic: it records whatever the caller logs. connect() wires one up
+ *  automatically (override via { log } or { logFile }, or $WAE_LOG_FILE). */
+/** Parse a `layertree` op dump (the `_caLayerTreeAsText` format) into a flat
+    array of layer bounds `{ x, y, width, height }` — the programmatic
+    compositing-layer census. Pure; pairs with `page.layerTree()`:
+
+      const layers = parseLayerTree(await page.layerTree());
+      const canvases = layers.filter(l => l.width === 398 && l.height === 209);
+
+    The dump nests layers as parenthesized blocks; for a census the flat list
+    of `(layer bounds [x: … y: … width: … height: …])` entries is what counts,
+    so nesting is deliberately ignored. */
+export declare function parseLayerTree(text: string): LayerBounds[];
+export declare function fileLogger(file: string, { echo }?: {
+    echo?: boolean;
+}): LogFn;
+export declare const PAGE_HELPERS: string;
+declare class Session {
+    readonly sock: Socket;
+    readonly token: string;
+    readonly pending: Map<number, {
+        resolve: (value: ProtocolMessage) => void;
+        reject: (error: unknown) => void;
+    }>;
+    private _id;
+    readonly sinkListeners: Set<(event: SinkEvent<any>) => void>;
+    constructor(sock: Socket, token: string);
+    onSink(fn: (event: SinkEvent<any>) => void): () => void;
+    _emitSink(event: SinkEvent<any>): void;
+    _failAll(err: unknown): void;
+    request(obj: ProtocolMessage, { timeoutMs }?: RequestOptions): Promise<ProtocolMessage>;
+    evalRaw<T = unknown>(code: string, opts?: RequestOptions): Promise<T>;
+    close(): void;
+}
+export declare function connect({ host, port, token, timeout, interval, log, logFile, logEcho, backendTimeoutMs, activate }?: ConnectOptions): Promise<Page>;
+export declare class Page {
+    readonly session: Session;
+    readonly defaultTimeout: number;
+    readonly interval: number;
+    readonly backendTimeoutMs: number;
+    readonly log: LogFn;
+    logFile: string | null;
+    constructor(session: Session, { defaultTimeout, interval, log, backendTimeoutMs }: {
+        defaultTimeout: number;
+        interval: number;
+        log: LogFn;
+        backendTimeoutMs?: number;
+    });
+    locator(selector: string): Locator;
+    getByTestId(id: string): Locator;
+    /** Escape hatch: run arbitrary JS in the page and get the result (small results). */
+    evaluate<T = unknown>(code: string, opts?: RequestOptions): Promise<T>;
+    /** Read a string-valued JS expression in <=chunk slices. WKWebView's
+        evaluateJavascript stalls on large (>~100KB) returns, so big values are
+        pulled in pieces. `expr` must evaluate to (or stringify to) a string. */
+    readBig(expr: string, { chunk, timeoutMs }?: {
+        chunk?: number;
+        timeoutMs?: number;
+    }): Promise<string>;
+    /** Structured accessibility snapshot of the page (or a subtree) — a compact
+        role/name tree with value/checked/disabled, generic containers flattened away.
+        Token-cheap vs outerHTML. Read via readBig so a large tree doesn't stall. */
+    ariaSnapshot(): Promise<AriaNode | AriaNode[]>;
+    /** Invoke a JUCE native function (registered via withNativeFunction) by name and
+        await its result. Good for small/medium results. Very large results (>~100KB)
+        stall JUCE's C->JS completion delivery regardless of timeout — that ceiling is
+        WKWebView's, not the bridge's, so a longer wait will not help. For bulk state,
+        read the juce:// resource route instead (e.g. juce://juce.backend/sequencerState.json
+        or dialogueGroups.json), or stash the value in a page variable and pull it with
+        readBig(). Requires a JUCE WebView host. The completion-poll deadline is the
+        connect() `backendTimeoutMs` option (default 10s). */
+    backend<T = unknown>(name: string, ...params: unknown[]): Promise<T>;
+    /** Fire a JUCE native function without awaiting a result (resultId = -1). */
+    fireBackend(name: string, ...params: unknown[]): Promise<boolean>;
+    /** Subscribe to live page events. kind: 'console' | 'error' | 'net' | '*'.
+        The handler receives the raw sink event { kind, t, data }. Returns an
+        unsubscribe fn. (data shapes mirror the CLI `logs` output.) */
+    on<T = unknown>(kind: 'console' | 'error' | 'net' | '*', handler: (event: SinkEvent<T>) => void): () => void;
+    /** Resolve with the first sink event of `kind` (optionally matching predicate),
+        or reject on timeout. predicate receives the raw event { kind, t, data }. */
+    waitForEvent<T = unknown>(kind: 'console' | 'error' | 'net' | '*', predicate?: ((event: SinkEvent<T>) => boolean) | TimeoutOptions, { timeout }?: TimeoutOptions): Promise<SinkEvent<T>>;
+    /** Resolve with the network event `data` for the first fetch/XHR whose URL
+        contains `urlOrPredicate` (string) or for which predicate(data) is true.
+        Mirrors Playwright's page.waitForResponse over the observe-only net stream. */
+    waitForResponse<T extends NetworkEventData = NetworkEventData>(urlOrPredicate: string | ((data: T) => boolean), opts?: TimeoutOptions): Promise<T>;
+    /** Ask the host to re-send buffered sink events with seq > since (default 0) on
+        THIS socket — catch-up without the read-backlog / open-stream race. Replayed
+        events flow through the same on()/waitForEvent listeners (each carries a
+        monotonic `seq` for dedup). Resolves with the number of events replayed. */
+    replayEvents({ since }?: {
+        since?: number;
+    }): Promise<number>;
+    /** Poll a JS boolean expression in the page until it is truthy (or time out).
+        `expr` is evaluated as `!!(expr)`; exceptions count as not-yet-true. */
+    waitForFunction(expr: string, { timeout, interval }?: PollOptions): Promise<void>;
+    /** Evaluate a small JS expression repeatedly until pred(value) holds (or timeout).
+        Settle primitive — replaces fixed sleeps after an action. Unlike waitForFunction
+        it returns the LAST VALUE seen (never throws on timeout), so the caller asserts
+        on it and a timeout surfaces as a normal assertion failure with the real value. */
+    poll<T = unknown>(expr: string, pred: (value: T) => boolean, { timeout, interval }?: PollOptions): Promise<T>;
+    /** Read a small expression until it stops changing (`settles` equal reads in a row)
+        or timeout — for values that ramp over several frames (a knob drag updates via
+        rAF + a native round-trip), so assertions see the SETTLED value, not a mid-ramp
+        one. Returns the last value read. */
+    pollStable<T = unknown>(expr: string, { timeout, interval, settles }?: PollOptions & {
+        settles?: number;
+    }): Promise<T>;
+    /** Main-thread render-perf probe. Over durationMs, measures React commit rate
+        (via the DevTools onCommitFiberRoot hook, when present) and rAF frame-gap
+        percentiles — the UI thread any canvas/Pixi/WebGL animation shares, so a high
+        p99 gap IS a visible stutter. Gap thresholds are refresh-relative (median gap
+        = the monitor's frame period), so numbers are valid on 60/120/144Hz alike.
+        Pass { motionSelector } (a querySelectorAll selector) to also report `motion`:
+        whether any matched element's `d`/`transform`/`style` changed during the
+        window (e.g. "did the modulated knobs actually move"). */
+    measureRenderPerf({ durationMs, motionSelector }?: {
+        durationMs?: number;
+        motionSelector?: string | null;
+    }): Promise<RenderPerfResult>;
+    /** Capabilities handshake: { protocolVersion, platform, ops, screenshotAvailable,
+        authRequired }. Lets a caller branch on what the host supports (e.g. skip
+        screenshots when screenshotAvailable is false) without probing op-by-op. */
+    capabilities(): Promise<Capabilities>;
+    /** Toggle WebKit's compositing debug overlays (layer borders + repaint
+        counters) on the host's WKWebView via the bridge `layerdebug` op. The
+        overlays render into the window, so `screenshot()` captures them — count
+        layers / attribute repaints from a script, no Web Inspector session.
+        macOS-only; throws where the backend has no such SPI. Remember to turn it
+        OFF before any pixel-comparison capture: the overlays are pixels too. */
+    layerDebug(enabled?: boolean): Promise<true>;
+    /** Dump the WKWebView's remote CALayer tree as text via the bridge
+        `layertree` op — the programmatic counterpart of layerDebug(): parse it
+        to census compositing layers (count, geometry) from a script instead of
+        reading overlay pixels off a screenshot. macOS-only; throws elsewhere. */
+    layerTree(): Promise<string>;
+    /** Native screenshot of the host window (incl. WebGL) via the bridge `shot` op.
+        Writes a PNG host-side and returns its path. Pass { path } to choose where, and
+        { clip: {x,y,w,h} } (CSS px) to crop to a UI region for a much smaller PNG. */
+    screenshot({ path, clip }?: {
+        path?: string;
+        clip?: ClipRect;
+    }): Promise<string>;
+    close(): void;
+}
+export declare class Locator {
+    readonly page: Page;
+    readonly selector: string;
+    readonly index: number | null;
+    constructor(page: Page, selector: string, index?: number | null);
+    /** Narrow to the i-th match (0-based); negative or null = last match. */
+    nth(i: number): Locator;
+    first(): Locator;
+    _probe(opts?: RequestOptions): Promise<LocatorProbe>;
+    count(): Promise<number>;
+    isVisible(): Promise<boolean>;
+    textContent(): Promise<string | null>;
+    getAttribute(name: string): Promise<string | null>;
+    _waitStable({ needEnabled, force, timeout, what }: ActionOptions & {
+        needEnabled?: boolean;
+        what: string;
+    }): Promise<LocatorProbe>;
+    click({ timeout, force }?: ActionOptions): Promise<void>;
+    fill(value: string | number, { timeout, enter }?: FillOptions): Promise<void>;
+    /** Hover the element centre (pointerover/mouseover) — opens hover menus/tooltips.
+        Hover doesn't require enabled: tooltips on disabled controls are legitimate. */
+    hover({ timeout, force }?: ActionOptions): Promise<void>;
+    /** Double click (full single-click sequence twice + dblclick). */
+    dblclick({ timeout, force }?: ActionOptions): Promise<void>;
+    /** Type char-by-char (per-key events) — for inputs that react to keydown, not
+        just value changes. Use fill() for a one-shot set; type() for keystroke fidelity. */
+    type(value: string | number, { timeout }?: TimeoutOptions): Promise<void>;
+    /** Press a single key on the element (keydown+keyup), keeping focus. */
+    press(key: string, { timeout }?: TimeoutOptions): Promise<void>;
+    /** Select an <option> by value (then by visible label/text). */
+    selectOption(value: string, { timeout }?: TimeoutOptions): Promise<void>;
+    /** Ensure a checkbox/radio is checked (no-op if already). */
+    check({ timeout }?: TimeoutOptions): Promise<void>;
+    /** Ensure a checkbox is unchecked (no-op if already). */
+    uncheck({ timeout }?: TimeoutOptions): Promise<void>;
+    _setChecked(desired: boolean, timeout?: number): Promise<void>;
+    /** Focus the element. */
+    focus({ timeout }?: TimeoutOptions): Promise<void>;
+    /** Structured accessibility snapshot rooted at this element (see Page.ariaSnapshot). */
+    ariaSnapshot({ timeout }?: TimeoutOptions): Promise<AriaNode | AriaNode[] | null>;
+    /** Native screenshot cropped to this element's bounding box (a small PNG — only
+        the element's pixels, so far cheaper to read back than a full-window shot). */
+    screenshot({ path, timeout }?: TimeoutOptions & {
+        path?: string;
+    }): Promise<string>;
+    /** Press at the element's centre and drag by (dx, dy) px (default vertical, for
+        knobs/sliders). steps interpolates the move; settleMs lets the component
+        attach its document move/up listeners (a React effect) after mousedown. */
+    drag({ dx, dy, steps, settleMs, stepMs, pointer, timeout }?: DragOptions): Promise<void>;
+    waitFor({ state, timeout }?: WaitForOptions): Promise<void>;
+    _waitUntil(pred: (probe: LocatorProbe) => boolean, timeout: number | undefined, what: string): Promise<LocatorProbe>;
+}
+export interface LocatorAssertionMatchers {
+    toBeVisible(options?: TimeoutOptions): Promise<LocatorProbe>;
+    toBeHidden(options?: TimeoutOptions): Promise<LocatorProbe>;
+    toBeEnabled(options?: TimeoutOptions): Promise<LocatorProbe>;
+    toBeDisabled(options?: TimeoutOptions): Promise<LocatorProbe>;
+    toBeChecked(options?: TimeoutOptions): Promise<LocatorProbe>;
+    toHaveCount(count: number, options?: TimeoutOptions): Promise<LocatorProbe>;
+    toHaveText(expected: string | RegExp, options?: TimeoutOptions): Promise<LocatorProbe>;
+    toContainText(expected: string, options?: TimeoutOptions): Promise<LocatorProbe>;
+    toHaveValue(expected: string | RegExp, options?: TimeoutOptions): Promise<LocatorProbe>;
+}
+export interface LocatorAssertions extends LocatorAssertionMatchers {
+    readonly not: LocatorAssertionMatchers;
+}
+/** Value-level polling assertion (escape hatch for app state, e.g. over backend()):
+      await expect.poll(() => page.backend('getBpm')).toBe(128);
+      await expect.poll(async () => (await page.backend('getRows')).length).toBeGreaterThan(0);
+    `fn` is re-invoked every `interval` ms until the matcher holds or `timeout` ms
+    elapse; a throwing `fn` counts as "not yet". `.not` inverts any matcher. */
+export interface PollAssertionMatchers<T> {
+    toBe(expected: T): Promise<T>;
+    toEqual(expected: T): Promise<T>;
+    toBeTruthy(): Promise<T>;
+    toBeFalsy(): Promise<T>;
+    toContain(expected: unknown): Promise<T>;
+    toBeGreaterThan(expected: number): Promise<T>;
+    toBeGreaterThanOrEqual(expected: number): Promise<T>;
+    toBeLessThan(expected: number): Promise<T>;
+    toBeLessThanOrEqual(expected: number): Promise<T>;
+    toSatisfy(predicate: (value: T) => boolean): Promise<T>;
+}
+export interface PollAssertions<T> extends PollAssertionMatchers<T> {
+    readonly not: PollAssertionMatchers<T>;
+}
+export interface ExpectFunction {
+    (locator: Locator): LocatorAssertions;
+    poll<T>(fn: () => T | Promise<T>, options?: PollExpectOptions): PollAssertions<T>;
+}
+export declare const expect: ExpectFunction;
+export {};