cssprobe-cli 0.3.0 → 0.4.0

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, 58 tests).
+Test: `npm test` (= `tsx --test tests/*.test.ts` — Node.js built-in test runner, 170 tests).
 Dependencies: `playwright-core`, `zod`. Dev: `typescript`, `@types/node`, `tsx`, `esbuild`.
 
 ## Architecture
@@ -17,23 +17,38 @@ 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/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
 │   ├── collector.ts           # Browser-side: DOM traversal, computed styles, declared values
 │   ├── analyzer.ts            # Node-side: pure functions, confidence model, pattern detection
+│   ├── 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
 └── utils/
-    └── socketConnection.ts    # Socket communication (adapted from playwright-cli)
+    ├── socketConnection.ts    # Socket communication (adapted from playwright-cli)
+    └── screenshot.ts          # Screenshot data-URL → file saving (shared by CLI + flow runner)
 ```
 
 ## Key Patterns
@@ -48,7 +63,7 @@ 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.
+- **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
@@ -58,7 +73,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
@@ -73,11 +90,44 @@ src/
 - `resize <width> <height>` — Resize browser viewport
 - `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
   - `--out <path>` — Output file path (default: `~/.cssprobe-cli/screenshots/<timestamp>.png`)
 
+### Interaction
+- `click <selector>` — Real mouse click (auto-scroll + actionability wait, works with custom React components)
+  - `--nth <n>` — 1-based match index (default: first match; multiple matches without `--nth` fail — strict)
+  - `--force` — skip actionability checks
+  - `--timeout <ms>` — action timeout (default 30000)
+- `hover <selector>` — Real mouse hover (`--nth` / `--force` / `--timeout` as above)
+- `type <selector> <text>` — Type text
+  - 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`
+- `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
+- `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`, `eval`, `sample`, `waitStable`, `click`, `waitFor`, `screenshot`, `assert`
+- `run <file>` — Run a multi-step flow script inside the daemon
+  - 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)
+  - 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
+
 ### State
 - `state-import [file]` — Import cookies from Netscape format
   - `--out <file>` — Output state file path (default: `~/.cssprobe-cli/states/imported.json`)
@@ -85,6 +135,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`
@@ -151,6 +204,6 @@ cssprobe-cli close
 | Output | Single markdown string | Markdown (default) / JSON (--json) |
 | Config | `window.__DOM_REPORT_CFG` global + eval two-step | CLI flags → env → rc file, one command |
 | ROOT_SELECTOR | Manual or eval probe | `--auto-root` auto-detection |
-| Tests | None | 45 unit tests (command, analyzer, output, renderer) |
+| Tests | None | 45+ unit tests (command, analyzer, output, renderer) |
 | Build | Regex stripping CJS module.exports | esbuild IIFE + CJS bundle, clean build |
 | Session | None (blocking commands) | Session-based daemon architecture |

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [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,16 +188,34 @@ Exposes 10 tools: `cssprobe_open`, `cssprobe_inspect`, `cssprobe_tree`, `cssprob
 | Command | Description |
 |---------|-------------|
 | `resize <width> <height>` | Resize browser viewport |
-| `eval <expression>` | Evaluate JavaScript (browser context) |
+| `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) |
 
+### Interaction
+
+| Command | Description |
+|---------|-------------|
+| `click <selector>` | Real mouse click (auto-scroll + actionability wait; works with custom React components) |
+| `hover <selector>` | Real mouse hover |
+| `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 |
+| `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.
+
 ### State
 
 | Command | Description |
 |---------|-------------|
 | `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
 
@@ -206,6 +230,91 @@ Exposes 10 tools: `cssprobe_open`, `cssprobe_inspect`, `cssprobe_tree`, `cssprob
 
 ---
 
+## Multi-step Flows
+
+The interaction commands drive a page step by step; `run` turns a sequence into a versionable script:
+
+```bash
+cssprobe-cli open https://example.com/editor
+cssprobe-cli wait-for .editor-canvas
+cssprobe-cli click ".layout-switch" --nth 1
+cssprobe-cli type ".block-title input" "Hello" --press Enter
+cssprobe-cli inspect .block-grid --json
+cssprobe-cli close
+```
+
+For repeatable flows, write a script and run it with one command. The script runs inside the daemon session (full Playwright `page` access):
+
+```js
+// flow.js
+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 });
+
+  await click('.layout-switch', { nth: 1 });
+  await waitFor({ js: "() => document.body.dataset.layout === 'two-col'" });
+
+  await type('.block-title input', 'Hello', { press: 'Enter', sequential: true, clear: true });
+  await waitFor({ networkIdle: true });
+
+  const { findings } = await inspect('.block-grid', { format: 'json' });
+  log('findings:', findings.length);
+  await screenshot({ path: './after-layout-switch.png' });
+
+  return { findings: findings.length };
+};
+```
+
+```bash
+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`, `context`, `frames()`, `newPage()`, `click`, `hover`, `type`, `waitFor`, `inspect`, `screenshot`, `expect`, `log`. 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`, `eval`, `sample`, `waitStable`, `click`, `waitFor`, `screenshot`, `assert`. `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.
+
 ## 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

@@ -0,0 +1,49 @@
+import type { Page } from 'playwright-core';
+export interface ElementDescriptor {
+    tag: string;
+    classes: string[];
+    text: string;
+}
+export interface TargetResult {
+    matches: number;
+    nth: number;
+    descriptor: ElementDescriptor | null;
+}
+export type WaitState = 'visible' | 'hidden' | 'attached' | 'detached';
+export type WaitTarget = {
+    kind: 'selector';
+    selector: string;
+    state: WaitState;
+} | {
+    kind: 'js';
+    expression: string;
+} | {
+    kind: 'networkIdle';
+};
+export declare function clickElement(page: Page, selector: string, opts?: {
+    nth?: number;
+    force?: boolean;
+    timeout?: number;
+}): Promise<TargetResult>;
+export declare function hoverElement(page: Page, selector: string, opts?: {
+    nth?: number;
+    force?: boolean;
+    timeout?: number;
+}): Promise<TargetResult>;
+export interface TypeOptions {
+    press?: string;
+    sequential?: boolean;
+    clear?: boolean;
+    delay?: number;
+    nth?: number;
+    timeout?: number;
+}
+export declare function typeInto(page: Page, selector: string, text: string, opts?: TypeOptions): Promise<void>;
+export declare function describeWaitTarget(target: WaitTarget): string;
+export declare function resolveWaitTarget(selector: string | undefined, opts: {
+    js?: string;
+    networkIdle?: boolean;
+    state?: string;
+}): WaitTarget;
+export declare function normalizePredicateExpression(expression: string): string;
+export declare function waitForCondition(page: Page, target: WaitTarget, timeout: number): Promise<number>;

package/dist/browser/interactions.js

@@ -0,0 +1,96 @@
+"use strict";
+// Interaction primitives shared by daemon commands and the run-script API.
+// Strict mode is preserved when no nth is given: multiple matches fail the action.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clickElement = clickElement;
+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) {
+    const base = page.locator(selector);
+    return nth ? base.nth(nth - 1) : base;
+}
+async function describeTarget(locator) {
+    return await locator
+        .evaluate(el => ({
+        tag: el.tagName.toLowerCase(),
+        classes: Array.from(el.classList),
+        text: (el.textContent ?? '').trim().slice(0, 60),
+    }))
+        .catch(() => null);
+}
+async function interactTarget(page, selector, opts, action) {
+    const base = page.locator(selector);
+    const locator = resolveLocator(page, selector, opts.nth);
+    const matches = await base.count();
+    const descriptor = await describeTarget(locator);
+    await action(locator, { force: opts.force, timeout: opts.timeout ?? DEFAULT_TIMEOUT });
+    return { matches, nth: opts.nth ?? 1, descriptor };
+}
+async function clickElement(page, selector, opts = {}) {
+    return interactTarget(page, selector, opts, (locator, o) => locator.click({ force: o.force, timeout: o.timeout }));
+}
+async function hoverElement(page, selector, opts = {}) {
+    return interactTarget(page, selector, opts, (locator, o) => locator.hover({ force: o.force, timeout: o.timeout }));
+}
+async function typeInto(page, selector, text, opts = {}) {
+    const locator = resolveLocator(page, selector, opts.nth);
+    const timeout = opts.timeout ?? DEFAULT_TIMEOUT;
+    if (opts.sequential) {
+        if (opts.clear)
+            await locator.fill('', { timeout });
+        await locator.pressSequentially(text, { delay: opts.delay ?? 0, timeout });
+    }
+    else {
+        await locator.fill(text, { timeout });
+    }
+    if (opts.press)
+        await locator.press(opts.press, { timeout });
+}
+function describeWaitTarget(target) {
+    switch (target.kind) {
+        case 'selector':
+            return `${target.selector} (state: ${target.state})`;
+        case 'js':
+            return `JS predicate: ${target.expression.slice(0, 80)}`;
+        case 'networkIdle':
+            return 'network idle';
+    }
+}
+function resolveWaitTarget(selector, opts) {
+    const modeCount = [selector, opts.js, opts.networkIdle].filter(Boolean).length;
+    if (modeCount !== 1)
+        throw new Error('wait-for requires exactly one of: <selector>, --js "<expression>", --network-idle');
+    if (selector)
+        return { kind: 'selector', selector, state: (opts.state ?? 'visible') };
+    if (opts.js)
+        return { kind: 'js', expression: opts.js };
+    return { kind: 'networkIdle' };
+}
+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(page, target, timeout) {
+    const started = Date.now();
+    switch (target.kind) {
+        case 'selector':
+            await page.waitForSelector(target.selector, { state: target.state, timeout });
+            break;
+        case 'js':
+            await page.waitForFunction(normalizePredicateExpression(target.expression), null, { timeout });
+            break;
+        case 'networkIdle':
+            await page.waitForLoadState('networkidle', { timeout });
+            break;
+    }
+    return Date.now() - started;
+}
+//# sourceMappingURL=interactions.js.map

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. */