cssprobe-cli 0.3.1 → 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, 108 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,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,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
@@ -62,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
@@ -78,6 +91,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 +109,22 @@ 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
+- `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`, `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)
+  - 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 +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`

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,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) |
 
@@ -196,6 +203,8 @@ Exposes 10 tools: `cssprobe_open`, `cssprobe_inspect`, `cssprobe_tree`, `cssprob
 | `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.
@@ -206,6 +215,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 +247,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 +269,52 @@ 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`. 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

@@ -45,4 +45,5 @@ export declare function resolveWaitTarget(selector: string | undefined, opts: {
     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

@@ -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,6 +71,13 @@ function resolveWaitTarget(selector, opts) {
         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) {
@@ -77,7 +85,7 @@ async function waitForCondition(page, target, timeout) {
             await page.waitForSelector(target.selector, { state: target.state, timeout });
             break;
         case 'js':
-            await page.waitForFunction(target.expression, null, { timeout });
+            await page.waitForFunction(normalizePredicateExpression(target.expression), null, { timeout });
             break;
         case 'networkIdle':
             await page.waitForLoadState('networkidle', { timeout });

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

package/dist/browser/launcher.js

@@ -6,6 +6,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BrowserLauncher = void 0;
+exports.browserCacheRoots = browserCacheRoots;
+exports.resolveExecutableIn = resolveExecutableIn;
+exports.listBrowserInstalls = listBrowserInstalls;
+exports.expectedBrowsers = expectedBrowsers;
+exports.diagnoseBrowser = diagnoseBrowser;
+exports.findBrowserExecutable = findBrowserExecutable;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
@@ -21,39 +27,133 @@ function loadBundle() {
     bundleContent = fs_1.default.readFileSync(COLLECTOR_BUNDLE_PATH, 'utf-8');
     return bundleContent;
 }
-/** Try to find an existing browser executable in the Playwright cache. */
-function findBrowserExecutable(engine) {
-    const cacheDir = path_1.default.join(os_1.default.homedir(), 'Library', 'Caches', 'ms-playwright');
-    if (!fs_1.default.existsSync(cacheDir))
-        return null;
-    const platform = process.platform;
-    if (engine === 'chromium') {
-        // Look for chromium-* directories (sorted newest first)
-        const dirs = fs_1.default.readdirSync(cacheDir)
-            .filter(d => d.startsWith('chromium-'))
-            .sort((a, b) => {
-            const na = parseInt(a.split('-')[1]) || 0;
-            const nb = parseInt(b.split('-')[1]) || 0;
-            return nb - na;
-        });
-        for (const dir of dirs) {
-            if (platform === 'darwin') {
-                const app = path_1.default.join(cacheDir, dir, 'chrome-mac-arm64', 'Google Chrome for Testing.app', 'Contents', 'MacOS', 'Google Chrome for Testing');
-                if (fs_1.default.existsSync(app))
-                    return app;
-                const appIntel = path_1.default.join(cacheDir, dir, 'chrome-mac', 'Google Chrome for Testing.app', 'Contents', 'MacOS', 'Google Chrome for Testing');
-                if (fs_1.default.existsSync(appIntel))
-                    return appIntel;
-            }
-            else if (platform === 'linux') {
-                const bin = path_1.default.join(cacheDir, dir, 'chrome-linux', 'chrome');
-                if (fs_1.default.existsSync(bin))
-                    return bin;
-            }
-        }
+function browserCacheRoots() {
+    const fromEnv = process.env.PLAYWRIGHT_BROWSERS_PATH;
+    if (fromEnv)
+        return [fromEnv];
+    if (process.platform === 'darwin') {
+        return [path_1.default.join(os_1.default.homedir(), 'Library', 'Caches', 'ms-playwright')];
+    }
+    if (process.platform === 'win32') {
+        const localAppData = process.env.LOCALAPPDATA || path_1.default.join(os_1.default.homedir(), 'AppData', 'Local');
+        return [path_1.default.join(localAppData, 'ms-playwright')];
+    }
+    return [path_1.default.join(os_1.default.homedir(), '.cache', 'ms-playwright')];
+}
+function resolveExecutableIn(dir, platform) {
+    const candidates = [];
+    if (platform === 'darwin') {
+        candidates.push(path_1.default.join(dir, 'chrome-mac-arm64', 'Google Chrome for Testing.app', 'Contents', 'MacOS', 'Google Chrome for Testing'));
+        candidates.push(path_1.default.join(dir, 'chrome-mac', 'Google Chrome for Testing.app', 'Contents', 'MacOS', 'Google Chrome for Testing'));
+    }
+    else if (platform === 'linux') {
+        candidates.push(path_1.default.join(dir, 'chrome-linux', 'chrome'));
+        candidates.push(path_1.default.join(dir, 'chrome-linux64', 'chrome'));
+    }
+    else if (platform === 'win32') {
+        candidates.push(path_1.default.join(dir, 'chrome-win', 'chrome.exe'));
+        candidates.push(path_1.default.join(dir, 'chrome-win64', 'chrome.exe'));
+    }
+    for (const candidate of candidates) {
+        if (fs_1.default.existsSync(candidate))
+            return candidate;
     }
     return null;
 }
+function listBrowserInstalls(cacheRoots = browserCacheRoots()) {
+    const installs = [];
+    for (const root of cacheRoots) {
+        if (!fs_1.default.existsSync(root))
+            continue;
+        for (const entry of fs_1.default.readdirSync(root)) {
+            const match = /^(chromium|chromium_headless_shell)-(\d+)$/.exec(entry);
+            if (!match)
+                continue;
+            const dir = path_1.default.join(root, entry);
+            installs.push({
+                kind: match[1] === 'chromium' ? 'chromium' : 'chromium-headless-shell',
+                revision: parseInt(match[2], 10),
+                dir,
+                executable: resolveExecutableIn(dir, process.platform),
+            });
+        }
+    }
+    return installs.sort((a, b) => b.revision - a.revision);
+}
+function expectedBrowsers() {
+    try {
+        const pkgPath = require.resolve('playwright-core/package.json');
+        const pkg = JSON.parse(fs_1.default.readFileSync(pkgPath, 'utf-8'));
+        const browsersPath = path_1.default.join(path_1.default.dirname(pkgPath), 'browsers.json');
+        const browsers = JSON.parse(fs_1.default.readFileSync(browsersPath, 'utf-8'));
+        const chromium = browsers.browsers?.find(browser => browser.name === 'chromium');
+        const headlessShell = browsers.browsers?.find(browser => browser.name === 'chromium-headless-shell');
+        return {
+            chromium: chromium ? parseInt(chromium.revision, 10) : undefined,
+            headlessShell: headlessShell ? parseInt(headlessShell.revision, 10) : undefined,
+            playwrightVersion: pkg.version,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function installCommand(expected) {
+    return expected.playwrightVersion
+        ? `npx playwright@${expected.playwrightVersion} install chromium`
+        : 'npx playwright install chromium';
+}
+function diagnoseBrowser(engine = 'chromium', cacheRoots = browserCacheRoots()) {
+    const expected = expectedBrowsers();
+    const installs = listBrowserInstalls(cacheRoots);
+    const chromiumInstalls = installs.filter(install => install.kind === 'chromium' && install.executable);
+    const exact = expected.chromium
+        ? chromiumInstalls.some(install => install.revision === expected.chromium)
+        : chromiumInstalls.length > 0;
+    if (engine !== 'chromium') {
+        return {
+            platform: process.platform,
+            cacheRoots,
+            expected,
+            installs,
+            status: 'missing',
+            hint: `Automatic discovery only covers chromium; run "npx playwright install ${engine}" if launch fails.`,
+        };
+    }
+    if (exact) {
+        return { platform: process.platform, cacheRoots, expected, installs, status: 'exact', hint: null };
+    }
+    if (chromiumInstalls.length > 0) {
+        const found = chromiumInstalls.map(install => install.revision).join(', ');
+        return {
+            platform: process.platform,
+            cacheRoots,
+            expected,
+            installs,
+            status: 'fallback',
+            hint: `Found chromium revision(s) ${found}, expected ${expected.chromium ?? 'unknown'}. Launch may work through the fallback. To install the expected build: ${installCommand(expected)}`,
+        };
+    }
+    return {
+        platform: process.platform,
+        cacheRoots,
+        expected,
+        installs,
+        status: 'missing',
+        hint: `No chromium install found. Install it with: ${installCommand(expected)}`,
+    };
+}
+/** Try to find an existing browser executable in the Playwright cache. */
+function findBrowserExecutable(engine, cacheRoots = browserCacheRoots()) {
+    if (engine !== 'chromium')
+        return null;
+    const installs = listBrowserInstalls(cacheRoots).filter(install => install.kind === 'chromium' && install.executable);
+    if (!installs.length)
+        return null;
+    const expected = expectedBrowsers().chromium;
+    const exact = installs.find(install => install.revision === expected);
+    return (exact ?? installs[0]).executable;
+}
 class BrowserLauncher {
     options;
     browser = null;
@@ -74,7 +174,13 @@ class BrowserLauncher {
         if (execPath) {
             launchOptions.executablePath = execPath;
         }
-        this.browser = await factory.launch(launchOptions);
+        try {
+            this.browser = await factory.launch(launchOptions);
+        }
+        catch (error) {
+            const diagnosis = diagnoseBrowser(engine);
+            throw new Error(`${error.message}\nBrowser diagnosis: ${diagnosis.status}. Run "cssprobe-cli doctor" for details.`);
+        }
         // Load saved state if provided
         const vp = this.options.viewport || { width: 1280, height: 720 };
         const contextOptions = { viewport: vp };
@@ -98,12 +204,13 @@ class BrowserLauncher {
             await this.page.goto(`file://${resolved}`, { waitUntil: 'load', timeout: 30000 });
         }
     }
-    async collect(cfg) {
+    async collect(cfg, target) {
         if (!this.page)
             throw new Error('Browser not opened. Call open() first.');
+        const host = target ?? this.page;
         const bundle = loadBundle();
-        await this.page.addScriptTag({ content: bundle });
-        const snapshot = await this.page.evaluate((config) => {
+        await host.addScriptTag({ content: bundle });
+        const snapshot = await host.evaluate((config) => {
             return window.__cssprobe_cli.collect(config);
         }, cfg);
         return snapshot;