cssprobe-cli 0.3.1 → 0.4.1

package/AGENTS.md

@@ -4,7 +4,7 @@
 
 `cssprobe-cli` — Runtime CSS probe for layout/scroll/overflow/color/font inspection with session-based browser management. Entrypoint: `bin/cssprobe-cli.js` → `require('../dist/index')`.
 Build: `npm run build` (= `tsc` + `esbuild` collector IIFE bundle + `esbuild` daemon entry + `tsx scripts/generate-help.ts`).
-Test: `npm test` (= `tsx --test tests/*.test.ts` — Node.js built-in test runner, 108 tests).
+Test: `npm test` (= `tsx --test tests/*.test.ts` — Node.js built-in test runner, 173 tests).
 Dependencies: `playwright-core`, `zod`. Dev: `typescript`, `@types/node`, `tsx`, `esbuild`.
 
 ## Architecture
@@ -17,11 +17,15 @@ src/
 │   ├── commands.ts            # Command definitions — all Zod schemas
 │   ├── command.ts             # declareCommand(), parseCommand() (Zod validation)
 │   ├── output.ts              # TextOutput / JsonOutput strategy pattern
+│   ├── input.ts               # @file / stdin argument expansion for eval and playwright
+│   ├── state-check.ts         # State file validation (cookie expiry, target domain)
+│   ├── url-guard.ts           # Login-redirect detection + --expect-url matching
 │   └── minimist.ts            # Arguments parser (forked from playwright-cli)
 ├── daemon/
 │   ├── session.ts             # Session management (single session, Unix socket)
 │   ├── daemon.ts              # Daemon process: browser lifecycle + command execution
-│   ├── flowRunner.ts          # Flow script loader/runner (run command): dynamic import, API injection, console capture
+│   ├── flowRunner.ts          # Flow script loader/runner (run command): dynamic import, API injection, console/pageerror capture
+│   ├── expect.ts              # Assertion matchers for flow scripts
 │   └── daemonEntry.ts         # Daemon entry point (spawned as child process)
 ├── engine/
 │   ├── types.ts               # Shared types: Snapshot, TreeNode, Finding, Confidence
@@ -30,8 +34,15 @@ src/
 │   ├── evalSerializer.ts      # Self-contained serializer for eval results (runs in-page via JSHandle.evaluate)
 │   └── renderer.ts            # Markdown / JSON rendering
 ├── browser/
-│   ├── launcher.ts            # Playwright wrapper: launch, navigate, inject collector
+│   ├── launcher.ts            # Playwright wrapper: launch, navigate, browser discovery/doctor
+│   ├── frames.ts              # Frame listing + resolution (index/name/URL substring)
+│   ├── sampler.ts             # Timeline sampling + wait-stable (pure aggregation)
 │   └── interactions.ts        # Interaction primitives: click/hover/type/wait-for (shared by daemon + run API)
+├── scenario/
+│   ├── schema.ts              # Zod schemas for JSON suites, cases and steps
+│   ├── runner.ts              # Suite execution: browser per case, vars, artifacts, JUnit
+│   ├── assertions.ts          # Pure assertion evaluation (paths, matchers, globals, URL)
+│   └── reporters.ts           # Console summary + JUnit XML
 ├── config/
 │   ├── config.ts              # Config loader (CLI → env → ~/.cssprobe-clirc profiles)
 │   └── helpGenerator.ts       # Build-time: Zod schemas → dist/help.json
@@ -52,7 +63,8 @@ src/
 - **Output strategy**: `Output` interface → `TextOutput` (Markdown for inspect, tables for lists) / `JsonOutput` (machine-readable JSON).
 - **Config priority**: CLI flags → env vars → `~/.cssprobe-clirc` profiles. Switch with `-p <profile>`.
 - **State management**: `state-import` converts Netscape cookies; `state-save` persists the current session's cookies + localStorage after manual login. Session persists browser state until `close`.
-- **Browser discovery**: `findBrowserExecutable()` scans `~/Library/Caches/ms-playwright/chromium-*` for existing Chrome installations.
+- **Iframe guidance**: pages may contain hidden helper iframes (`about:blank`); use `frames` to pick the real one and `state: "attached"` for hidden targets. Preview frames can render in 6–8s while analytics keep `networkIdle` busy — use a fixed `wait` plus an in-frame `waitFor` instead of `networkIdle`.
+- **Browser discovery**: `findBrowserExecutable()` scans the platform Playwright cache (macOS/Linux/Windows, `PLAYWRIGHT_BROWSERS_PATH` override), prefers the revision required by the bundled `playwright-core`, and falls back to the newest install. `doctor` reports expected vs installed revisions.
 - **Error format**: `Error: <message>` → JSON mode: `{ isError: true, error: "<message>" }` → `process.exit(1)`
 
 ## Commands
@@ -62,7 +74,9 @@ src/
   - `--viewport <WxH>` — Set viewport size (e.g. `--viewport 1280x720`)
   - `--state <file>` — Load saved state (cookies + localStorage)
 - `close` — Close the browser session
-- `status` — Show current session status
+- `status` — Show current session status (URL, title, frame count)
+- `frames` — List frames: index, name, URL, main marker
+- `doctor` — Diagnose browser installation vs expected Playwright revision
 
 ### CSS Inspection
 - `inspect <selector>` — Inspect runtime CSS of a page element
@@ -78,6 +92,9 @@ src/
 - `eval <expression>` — Evaluate JavaScript (browser context)
   - Returns raw string values (not JSON-quoted) for string results
   - DOM nodes / circular structures are auto-serialized (descriptors, `[Circular]`, `[Function: name]`, depth cap 6)
+  - Promises are awaited; `undefined` object/array values become `null`
+  - `@file` / `-` (stdin) reads long expressions from disk or stdin
+  - `--frame <index|name|url-substring>` evaluates inside an iframe
 - `playwright <call>` — Execute Playwright API call (Node.js context)
   - Returns `{ ok: true, value: null, note: ... }` when the call returns no value; throws a clear error message on failure
 - `screenshot` — Take a screenshot
@@ -93,13 +110,25 @@ src/
   - Default: `fill()` (replaces the value); `--sequential` for real key events (custom editors), `--clear` clears first
   - `--press <key>` — press a key after typing (e.g. `Enter`)
   - `--delay <ms>` — keystroke delay for `--sequential`
-- `wait-for` — Wait for a condition (three mutually exclusive modes)
+- `sample "<expr>"` — Sample an expression on an interval (`--interval`, `--duration`, `--key`, `--frame`), returning `summary` + `series`
+- `wait-stable "<expr>"` — Wait until the expression stops changing (`--tolerance`, `--window`, `--timeout`, `--interval`, `--frame`)
+- `wait-for` — Wait for a condition (three mutually exclusive modes); arrow-function/function predicates are invoked, bare expressions are evaluated as-is
   - `wait-for <selector>` — selector state: `--state visible|hidden|attached|detached` (default visible)
   - `wait-for --js "<predicate>"` — wait until a JS predicate is truthy
   - `wait-for --network-idle` — wait until the page is network-idle
   - `--timeout <ms>` — default 30000; timeout errors name the target
+  - `--frame <index|name|url-substring>` — wait inside a frame (selector/js only; `networkIdle` is page-level)
+- `scenario run <file>` — Run a JSON scenario suite (fresh browser per case, assertions, artifacts, JUnit)
+  - `--state <file>` — Fallback state file for cases without one
+  - `--artifacts <dir>` — Artifact directory (default `~/.cssprobe-cli/scenario-runs/<suite>-<timestamp>`)
+  - `--junit <file>` — Write a JUnit XML report
+  - `--bail` — Stop after the first failing case
+  - Steps: `goto`, `reload`, `wait`, `eval`, `sample`, `waitStable`, `click`, `waitFor`, `screenshot`, `assert`
+  - `wait` takes a fixed `ms`; `waitFor` accepts `frame` for in-iframe selector/js waits
 - `run <file>` — Run a multi-step flow script inside the daemon
-  - Script default-exports an async function receiving the API object: `page`, `click`, `hover`, `type`, `waitFor`, `inspect`, `screenshot`, `log` (CJS also supported)
+  - Script default-exports an async function receiving the API object: `page`, `context`, `frames()`, `newPage()`, `click`, `hover`, `type`, `waitFor`, `inspect`, `screenshot`, `expect`, `log` (CJS also supported)
+  - `waitFor(target, { state, timeout, frame })`; `frame` targets iframe selector/js waits
+  - Uncaught page errors are collected in the envelope as `pageErrors[]`
   - `--timeout <ms>` — whole-script guard (default 300000, 0 = unlimited); failure exits 1 and keeps the session alive
   - `screenshot` relative paths resolve against the script's directory; logs collected and returned
 
@@ -110,6 +139,9 @@ src/
   - `--merge <file>` — Existing state file to merge into
 - `state-save` — Save current browser session state (cookies + localStorage)
   - `--name <name>` — State file name (default: `session`)
+- `state-check` — Validate a saved state file (cookie count, expiry, target domain coverage)
+  - `--state <file>` — State file (default: `~/.cssprobe-cli/states/session.json`)
+  - `--url <url>` — Require the cookies to cover this hostname
 
 ### Config
 - `config-show` / `config-set` / `config-list` / `config-use` / `config-new` / `config-path`

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.4.1] - 2026-10-23
+
+### Added
+- `wait-for --frame` (selector/js), scenario `waitFor.frame`, and flow `waitFor(target, { frame })`
+- Scenario `wait` step for fixed delays before slow-rendering preview frames
+
+### Documentation
+- Iframe/preview guidance: hidden helper frames need `state: "attached"`; prefer in-frame `waitFor` over `networkIdle` when analytics keep the page busy
+
+## [0.4.0] - 2026-10-23
+
+### Added
+- `frames` command and `--frame <index|name|url-substring>` on `eval` / `inspect` / `tree` / `layout` / `findings` / `inject-css`
+- `sample "<expr>"` (interval timeline + summary) and `wait-stable "<expr>"` (tolerance + stable window)
+- `doctor` command: platform-aware browser cache discovery, expected vs installed Playwright revisions and install hint
+- `state-check` command: cookie expiry and target-domain coverage for saved state files
+- `open --expect-url <regex>` and `open --fail-on-login` guards
+- Flow API: `context`, `frames()`, `newPage()`, `expect` matchers; `pageErrors` in the result envelope
+- `scenario run <suite.json>`: JSON regression suites with steps (goto/reload/eval/sample/waitStable/click/waitFor/screenshot/assert), per-case variables, artifacts and JUnit output
+- `sample --tail-from` and per-step `tailFrom` / `ignoreErrors`
+
+### Fixed
+- `wait-for --js` (and flow `waitFor({ js })`) now invokes arrow-function/function predicates instead of treating the function source as a truthy expression
+
+### Changed
+- `eval` / `playwright` accept `@file` and `-` (stdin)
+- `eval` awaits promise results and preserves `undefined` object/array fields as `null`
+- `status` now reports the current URL, title and frame count
+- Browser discovery supports macOS, Linux and Windows cache roots and prefers the revision expected by `playwright-core`
+
 All notable changes are documented on the [GitHub Releases](https://github.com/mack-peng/cssprobe-cli/releases) page.
 
 ## [0.3.0] - 2026-09-16

package/README.md

@@ -155,9 +155,13 @@ Exposes 10 tools: `cssprobe_open`, `cssprobe_inspect`, `cssprobe_tree`, `cssprob
 | `open [url] --headed` | Show browser window |
 | `open [url] --state <file>` | Open with saved cookies + localStorage |
 | `open [url] --viewport 1280x720` | Custom viewport size |
+| `open [url] --expect-url <regex>` | Fail unless the final URL matches the pattern |
+| `open [url] --fail-on-login` | Fail fast when redirected to a login URL |
 | `close` | Close browser session |
 | `close --all` | Close all sessions across all workspaces |
-| `status` | Show session status |
+| `status` | Show session status (URL, title, frame count) |
+| `frames` | List frames: index, name, URL, main marker |
+| `doctor` | Diagnose browser install vs Playwright expected revision |
 
 ### CSS Inspection
 
@@ -171,6 +175,8 @@ Exposes 10 tools: `cssprobe_open`, `cssprobe_inspect`, `cssprobe_tree`, `cssprob
 | `layout <selector>` | ASCII layout diagram |
 | `findings <selector>` | Only issues/warnings/errors |
 
+Inspection commands accept `--frame <index|name|url-substring>` to target an iframe; the default is the main frame.
+
 ### CSS Injection
 
 | Command | Description |
@@ -182,7 +188,8 @@ Exposes 10 tools: `cssprobe_open`, `cssprobe_inspect`, `cssprobe_tree`, `cssprob
 | Command | Description |
 |---------|-------------|
 | `resize <width> <height>` | Resize browser viewport |
-| `eval <expression>` | Evaluate JavaScript (browser context); DOM nodes are auto-serialized |
+| `eval <expression>` | Evaluate JavaScript (browser context); DOM nodes are auto-serialized; promises are awaited, `undefined` fields become `null` |
+| `eval @file` / `eval -` | Read the expression from a file or stdin |
 | `playwright <call>` | Execute Playwright API (Node.js context) |
 | `screenshot` | Take screenshot (saves to ~/.cssprobe-cli/screenshots/, --out to override) |
 
@@ -195,7 +202,10 @@ Exposes 10 tools: `cssprobe_open`, `cssprobe_inspect`, `cssprobe_tree`, `cssprob
 | `type <selector> <text>` | Fill text (replaces value); `--press Enter` to submit; `--sequential` for real key events |
 | `wait-for <selector>` | Wait for selector state (`--state visible\|hidden\|attached\|detached`, `--timeout ms`) |
 | `wait-for --js "<predicate>"` | Wait until a JS predicate is truthy |
-| `wait-for --network-idle` | Wait until the page is network-idle |
+| `wait-for --network-idle` | Wait until the page is network-idle (page-level; no `--frame`) |
+| `wait-for ... --frame <spec>` | Wait inside an iframe (selector/js modes) |
+| `sample "<expr>"` | Sample an expression over time (`--interval`, `--duration`, `--key`, `--frame`); returns timeline + summary |
+| `wait-stable "<expr>"` | Wait until an expression stops changing (`--tolerance`, `--window`, `--timeout`) |
 | `run <file>` | Run a multi-step flow script |
 
 `click` / `hover` support `--nth N` (1-based, default first match), `--force` (skip actionability checks) and `--timeout ms`. Without `--nth`, multiple matches fail (strict) to prevent wrong-target clicks.
@@ -206,6 +216,7 @@ Exposes 10 tools: `cssprobe_open`, `cssprobe_inspect`, `cssprobe_tree`, `cssprob
 |---------|-------------|
 | `state-import <file>` | Import cookies from Netscape format |
 | `state-save` | Save current browser session state (cookies + localStorage) |
+| `state-check` | Validate a state file: cookie count, expiry, target domain coverage (`--state`, `--url`) |
 
 ### Configuration
 
@@ -237,7 +248,7 @@ For repeatable flows, write a script and run it with one command. The script run
 
 ```js
 // flow.js
-export default async ({ page, click, waitFor, type, inspect, screenshot, log }) => {
+export default async ({ page, context, frames, newPage, click, waitFor, type, inspect, screenshot, expect, log }) => {
   await page.goto('https://example.com/editor', { waitUntil: 'domcontentloaded' });
   await waitFor('.editor-canvas', { state: 'visible', timeout: 10000 });
 
@@ -259,12 +270,54 @@ export default async ({ page, click, waitFor, type, inspect, screenshot, log })
 cssprobe-cli run ./flow.js        # --timeout ms for the whole script (default 300000, 0 = unlimited)
 ```
 
-Scripts must `default-export` an async function receiving the API object: `page`, `click`, `hover`, `type`, `waitFor`, `inspect`, `screenshot`, `log`. `screenshot` relative paths resolve against the script's directory; logs (`log()` and `console.*`) are collected and returned with the result. On failure the command exits `1`, prints the collected logs, and keeps the session alive.
+Scripts must `default-export` an async function receiving the API object: `page`, `context`, `frames()`, `newPage()`, `click`, `hover`, `type`, `waitFor`, `inspect`, `screenshot`, `expect`, `log`. `waitFor` accepts `{ state, timeout, frame }`. Uncaught page errors are collected into the result envelope as `pageErrors`. `screenshot` relative paths resolve against the script's directory; logs (`log()` and `console.*`) are collected and returned with the result. On failure the command exits `1`, prints the collected logs, and keeps the session alive.
 
 > Scripts are executed by the local daemon with full Node privileges — only run trusted scripts.
 
 ---
 
+## Scenario Suites (Regression)
+
+Run repeatable regression cases from a JSON suite: each case opens a fresh browser, executes steps, asserts on saved values, and writes artifacts + an optional JUnit report.
+
+```bash
+cssprobe-cli scenario run suites/ticket-26571394.json \
+  --state ~/.cssprobe-cli/states/preprod.json \
+  --artifacts out/ticket-26571394 \
+  --junit out/junit.xml
+```
+
+```json
+{
+  "name": "ticket 26571394 preprod",
+  "defaults": { "viewport": { "width": 1280, "height": 800 } },
+  "cases": [
+    {
+      "name": "refresh keeps the hash section aligned",
+      "url": "https://example.com/#listen-to-tcmi",
+      "steps": [
+        { "do": "sample", "expression": "({ hash: location.hash, top: Math.round(document.querySelector('#listen-to-tcmi')?.getBoundingClientRect().top ?? -1) })", "interval": 250, "duration": 12000, "key": "top", "tailFrom": 9500, "save": "timeline" },
+        { "do": "assert", "label": "hash retained", "on": "timeline", "path": "summary.last.value.hash", "eq": "#listen-to-tcmi" },
+        { "do": "assert", "label": "anchor stable", "on": "timeline", "path": "summary.tail.min", "min": 70 },
+        { "do": "assert", "label": "anchor stable", "on": "timeline", "path": "summary.tail.max", "max": 90 }
+      ]
+    },
+    {
+      "name": "deployment fingerprint",
+      "url": "https://example.com/",
+      "steps": [
+        { "do": "waitFor", "js": "() => !!window.DEBUG?.NavigatorStore", "timeout": 20000 },
+        { "do": "assert", "globals": { "DEBUG.NavigatorStore.setHashRestoreProtected": "function" }, "absent": ["DEBUG.NavigatorStore.navigateToSectionId"] }
+      ]
+    }
+  ]
+}
+```
+
+Steps: `goto`, `reload`, `wait`, `eval`, `sample`, `waitStable`, `click`, `waitFor`, `screenshot`, `assert`. `wait` takes a fixed `ms`; `waitFor` supports `frame` for in-iframe selector/js waits. `sample` and `eval` save values with `save: "<name>"`; assertions read them with `on: "<name>"` + `path`, or check live `state` (`url`, `title`, `frames`), `url`, `globals`, `absent`. `sample` supports `key`, `tailFrom`, `ignoreErrors`; every run writes `summary.json`, per-case `case.json`, sample series and failure screenshots.
+
+**Iframe and preview pages.** A page can contain hidden helper iframes (`about:blank`); use `frames` to pick the real one, and `state: "attached"` when waiting for a frame element that is not visible. Preview frames can take 6–8s to render and analytics requests keep `networkIdle` busy — prefer a fixed `wait` step followed by a `waitFor` inside the frame (`frame: "i/preview"`) instead of `networkIdle`.
+
 ## Confidence Model
 
 Every finding carries a confidence level:

package/dist/browser/frames.d.ts

@@ -0,0 +1,15 @@
+import type { Frame, Page } from 'playwright-core';
+export interface FrameInfo {
+    index: number;
+    name: string;
+    url: string;
+    isMain: boolean;
+}
+export interface FrameLike {
+    name(): string;
+    url(): string;
+}
+export declare function describeFrames(page: Page): FrameInfo[];
+export declare function selectFrame<T extends FrameLike>(frames: T[], spec: string): T;
+export declare function resolveFrame(page: Page, spec?: string): Frame;
+export declare function formatFrames(frames: FrameInfo[]): string;

package/dist/browser/frames.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeFrames = describeFrames;
+exports.selectFrame = selectFrame;
+exports.resolveFrame = resolveFrame;
+exports.formatFrames = formatFrames;
+function describeFrames(page) {
+    const main = page.mainFrame();
+    return page.frames().map((frame, index) => ({
+        index,
+        name: frame.name(),
+        url: frame.url(),
+        isMain: frame === main,
+    }));
+}
+function renderAvailable(frames) {
+    return frames
+        .map((frame, index) => `[${index}] name="${frame.name()}" url=${frame.url()}`)
+        .join('\n');
+}
+function selectFrame(frames, spec) {
+    const raw = spec.trim();
+    if (!raw)
+        throw new Error('Frame spec is empty');
+    if (/^\d+$/.test(raw)) {
+        const index = parseInt(raw, 10);
+        if (index >= frames.length) {
+            throw new Error(`Frame index ${index} is out of range (${frames.length} frame(s)).\n${renderAvailable(frames)}`);
+        }
+        return frames[index];
+    }
+    const byName = frames.filter(frame => frame.name() === raw);
+    if (byName.length === 1)
+        return byName[0];
+    if (byName.length > 1) {
+        throw new Error(`Frame name "${raw}" is ambiguous.\n${renderAvailable(byName)}`);
+    }
+    const byUrl = frames.filter(frame => frame.url().includes(raw));
+    if (byUrl.length === 1)
+        return byUrl[0];
+    if (byUrl.length > 1) {
+        throw new Error(`Frame spec "${raw}" matches multiple frames.\n${renderAvailable(byUrl)}`);
+    }
+    throw new Error(`No frame matches "${raw}".\n${renderAvailable(frames)}`);
+}
+function resolveFrame(page, spec) {
+    if (spec === undefined)
+        return page.mainFrame();
+    return selectFrame(page.frames(), spec);
+}
+function formatFrames(frames) {
+    return frames
+        .map(frame => {
+        const marker = frame.isMain ? ' (main)' : '';
+        const name = frame.name ? ` name="${frame.name}"` : '';
+        return `[${frame.index}]${marker}${name} ${frame.url}`;
+    })
+        .join('\n');
+}
+//# sourceMappingURL=frames.js.map

package/dist/browser/interactions.d.ts

@@ -1,4 +1,4 @@
-import type { Page } from 'playwright-core';
+import type { Frame, Page } from 'playwright-core';
 export interface ElementDescriptor {
     tag: string;
     classes: string[];
@@ -45,4 +45,5 @@ export declare function resolveWaitTarget(selector: string | undefined, opts: {
     networkIdle?: boolean;
     state?: string;
 }): WaitTarget;
-export declare function waitForCondition(page: Page, target: WaitTarget, timeout: number): Promise<number>;
+export declare function normalizePredicateExpression(expression: string): string;
+export declare function waitForCondition(host: Page | Frame, target: WaitTarget, timeout: number): Promise<number>;

package/dist/browser/interactions.js

@@ -7,6 +7,7 @@ exports.hoverElement = hoverElement;
 exports.typeInto = typeInto;
 exports.describeWaitTarget = describeWaitTarget;
 exports.resolveWaitTarget = resolveWaitTarget;
+exports.normalizePredicateExpression = normalizePredicateExpression;
 exports.waitForCondition = waitForCondition;
 const DEFAULT_TIMEOUT = 30_000;
 function resolveLocator(page, selector, nth) {
@@ -70,17 +71,28 @@ function resolveWaitTarget(selector, opts) {
         return { kind: 'js', expression: opts.js };
     return { kind: 'networkIdle' };
 }
-async function waitForCondition(page, target, timeout) {
+const FUNCTION_LIKE_PREDICATE = /^\s*(async\s+)?(function\b|\([^)]*\)\s*=>|[A-Za-z_$][\w$]*\s*=>)/;
+function normalizePredicateExpression(expression) {
+    const trimmed = expression.trim();
+    if (!FUNCTION_LIKE_PREDICATE.test(trimmed))
+        return trimmed;
+    return `(${trimmed})()`;
+}
+async function waitForCondition(host, target, timeout) {
+    const isPage = typeof host.setViewportSize === 'function';
+    if (target.kind === 'networkIdle' && !isPage) {
+        throw new Error('networkIdle waits are page-level; remove the frame target');
+    }
     const started = Date.now();
     switch (target.kind) {
         case 'selector':
-            await page.waitForSelector(target.selector, { state: target.state, timeout });
+            await host.waitForSelector(target.selector, { state: target.state, timeout });
             break;
         case 'js':
-            await page.waitForFunction(target.expression, null, { timeout });
+            await host.waitForFunction(normalizePredicateExpression(target.expression), null, { timeout });
             break;
         case 'networkIdle':
-            await page.waitForLoadState('networkidle', { timeout });
+            await host.waitForLoadState('networkidle', { timeout });
             break;
     }
     return Date.now() - started;

package/dist/browser/launcher.d.ts

@@ -1,4 +1,4 @@
-import { type BrowserContext, type Page } from 'playwright-core';
+import { type BrowserContext, type Frame, type Page } from 'playwright-core';
 import type { Snapshot, CollectConfig } from '../engine/types';
 export interface LauncherOptions {
     browser?: string;
@@ -11,6 +11,34 @@ export interface LauncherOptions {
         height: number;
     };
 }
+export type BrowserKind = 'chromium' | 'chromium-headless-shell';
+export interface BrowserInstall {
+    kind: BrowserKind;
+    revision: number;
+    dir: string;
+    executable: string | null;
+}
+export interface BrowserExpectation {
+    chromium?: number;
+    headlessShell?: number;
+    playwrightVersion?: string;
+}
+export type BrowserDiagnosisStatus = 'exact' | 'fallback' | 'missing';
+export interface BrowserDiagnosis {
+    platform: string;
+    cacheRoots: string[];
+    expected: BrowserExpectation;
+    installs: BrowserInstall[];
+    status: BrowserDiagnosisStatus;
+    hint: string | null;
+}
+export declare function browserCacheRoots(): string[];
+export declare function resolveExecutableIn(dir: string, platform: string): string | null;
+export declare function listBrowserInstalls(cacheRoots?: string[]): BrowserInstall[];
+export declare function expectedBrowsers(): BrowserExpectation;
+export declare function diagnoseBrowser(engine?: string, cacheRoots?: string[]): BrowserDiagnosis;
+/** Try to find an existing browser executable in the Playwright cache. */
+export declare function findBrowserExecutable(engine: string, cacheRoots?: string[]): string | null;
 export declare class BrowserLauncher {
     private options;
     private browser;
@@ -18,7 +46,7 @@ export declare class BrowserLauncher {
     private page;
     constructor(options?: LauncherOptions);
     open(url: string): Promise<void>;
-    collect(cfg: CollectConfig): Promise<Snapshot>;
+    collect(cfg: CollectConfig, target?: Page | Frame): Promise<Snapshot>;
     /** Navigate to a new URL in the existing page. */
     navigate(url: string): Promise<void>;
     /** Get the current page object. */