cssprobe-cli 0.3.1 → 0.4.0

package/dist/cli/state-check.d.ts

@@ -0,0 +1,17 @@
+export interface StorageCookie {
+    name: string;
+    domain: string;
+    expires?: number;
+}
+export interface StateReport {
+    cookies: number;
+    domains: string[];
+    expired: string[];
+    sessionCookies: number;
+    targetMatches: boolean | null;
+    warnings: string[];
+    ok: boolean;
+}
+export declare function analyzeState(state: {
+    cookies?: StorageCookie[];
+}, targetUrl?: string, nowMs?: number): StateReport;

package/dist/cli/state-check.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeState = analyzeState;
+function normalizeDomain(domain) {
+    return domain.replace(/^\./, '').toLowerCase();
+}
+function analyzeState(state, targetUrl, nowMs = Date.now()) {
+    const cookies = state.cookies ?? [];
+    const expired = [];
+    let sessionCookies = 0;
+    for (const cookie of cookies) {
+        if (cookie.expires === undefined || cookie.expires <= 0) {
+            sessionCookies++;
+        }
+        else if (cookie.expires * 1000 <= nowMs) {
+            expired.push(cookie.name);
+        }
+    }
+    const domains = Array.from(new Set(cookies.map(cookie => normalizeDomain(cookie.domain)))).sort();
+    let targetMatches = null;
+    if (targetUrl) {
+        try {
+            const host = new URL(targetUrl).hostname.toLowerCase();
+            targetMatches = cookies.some(cookie => {
+                const domain = normalizeDomain(cookie.domain);
+                return host === domain || host.endsWith(`.${domain}`);
+            });
+        }
+        catch {
+            throw new Error(`Invalid --url value: ${targetUrl}`);
+        }
+    }
+    const warnings = [];
+    if (!cookies.length)
+        warnings.push('no cookies in state file');
+    if (expired.length)
+        warnings.push(`expired cookies: ${expired.join(', ')}`);
+    if (targetMatches === false)
+        warnings.push(`no cookies match ${targetUrl}`);
+    const ok = cookies.length > 0 && expired.length === 0 && targetMatches !== false;
+    return { cookies: cookies.length, domains, expired, sessionCookies, targetMatches, warnings, ok };
+}
+//# sourceMappingURL=state-check.js.map

package/dist/cli/url-guard.d.ts

@@ -0,0 +1,2 @@
+export declare function looksLikeLoginUrl(raw: string): boolean;
+export declare function matchesUrlPattern(pattern: string, raw: string): boolean;

package/dist/cli/url-guard.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.looksLikeLoginUrl = looksLikeLoginUrl;
+exports.matchesUrlPattern = matchesUrlPattern;
+function looksLikeLoginUrl(raw) {
+    try {
+        const url = new URL(raw);
+        return /\/(?:s\/)?login(?:\/|$)/.test(url.pathname);
+    }
+    catch {
+        return false;
+    }
+}
+function matchesUrlPattern(pattern, raw) {
+    let regex;
+    try {
+        regex = new RegExp(pattern);
+    }
+    catch {
+        throw new Error(`Invalid --expect-url pattern: ${pattern}`);
+    }
+    return regex.test(raw);
+}
+//# sourceMappingURL=url-guard.js.map

package/dist/daemon/daemon.js

@@ -20,6 +20,8 @@ const dom_tree_1 = require("../engine/renderers/dom-tree");
 const interactions_1 = require("../browser/interactions");
 const evalSerializer_1 = require("../engine/evalSerializer");
 const flowRunner_1 = require("./flowRunner");
+const frames_1 = require("../browser/frames");
+const sampler_1 = require("../browser/sampler");
 const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
 async function startDaemon(sessionName, clientInfo, options) {
     const sessionConfig = createSessionConfig(clientInfo, sessionName, options);
@@ -77,6 +79,18 @@ async function executeCommand(launcher, args) {
     const command = args._[0];
     const params = args._.slice(1);
     switch (command) {
+        case 'frames': {
+            const frames = (0, frames_1.describeFrames)(requirePage(launcher));
+            if (args.json)
+                return { text: JSON.stringify(frames, null, 2) };
+            return { text: (0, frames_1.formatFrames)(frames) };
+        }
+        case 'page-info': {
+            const page = requirePage(launcher);
+            return {
+                text: JSON.stringify({ url: page.url(), title: await page.title(), frames: (0, frames_1.describeFrames)(page).length }, null, 2),
+            };
+        }
         case 'goto': {
             const url = params[0] || 'about:blank';
             await launcher.open(url);
@@ -91,7 +105,7 @@ async function executeCommand(launcher, args) {
                 downDepth: args.depth || 6,
                 maxNodes: 60,
                 upTo: 'html',
-            });
+            }, (0, frames_1.resolveFrame)(requirePage(launcher), args.frame));
             const findings = (0, analyzer_1.analyze)(snapshot);
             if (args.json) {
                 return { text: JSON.stringify((0, renderer_1.renderJSON)(snapshot, findings, args.brief), null, 2) };
@@ -109,7 +123,7 @@ async function executeCommand(launcher, args) {
                 downDepth: args.depth || 6,
                 maxNodes: 60,
                 upTo: 'html',
-            });
+            }, (0, frames_1.resolveFrame)(requirePage(launcher), args.frame));
             // Render tree only
             const lines = [];
             lines.push(`## DOM tree (${snapshot.downDepth} levels deep)`);
@@ -127,7 +141,7 @@ async function executeCommand(launcher, args) {
                 downDepth: 6,
                 maxNodes: 60,
                 upTo: 'html',
-            });
+            }, (0, frames_1.resolveFrame)(requirePage(launcher), args.frame));
             const findings = (0, analyzer_1.analyze)(snapshot);
             return { text: (0, renderer_1.renderMarkdown)(snapshot, findings, false, true) };
         }
@@ -140,7 +154,7 @@ async function executeCommand(launcher, args) {
                 downDepth: 6,
                 maxNodes: 60,
                 upTo: 'html',
-            });
+            }, (0, frames_1.resolveFrame)(requirePage(launcher), args.frame));
             const findings = (0, analyzer_1.analyze)(snapshot);
             const important = findings.filter(f => f.level === 'warning' || f.level === 'error');
             if (important.length === 0) {
@@ -155,11 +169,9 @@ async function executeCommand(launcher, args) {
             const css = params[0];
             if (!css)
                 throw new Error('CSS is required for inject-css command');
-            const page = launcher.getPage();
-            if (!page)
-                throw new Error('Browser is not open. Run: cssprobe-cli open <url>');
-            await page.addStyleTag({ content: css });
-            return { text: JSON.stringify({ success: true }) };
+            const frame = (0, frames_1.resolveFrame)(requirePage(launcher), args.frame);
+            await frame.addStyleTag({ content: css });
+            return { text: JSON.stringify({ success: true, frame: frame.name() || frame.url() }) };
         }
         case 'screenshot': {
             const page = launcher.getPage();
@@ -173,17 +185,21 @@ async function executeCommand(launcher, args) {
             const expression = params[0];
             if (!expression)
                 throw new Error('Expression is required for eval command');
-            const page = launcher.getPage();
-            if (!page)
-                throw new Error('Browser is not open. Run: cssprobe-cli open <url>');
-            const handle = await page.evaluateHandle(expression);
+            const frame = (0, frames_1.resolveFrame)(requirePage(launcher), args.frame);
+            const handle = await frame.evaluateHandle(expression);
             try {
-                const result = await handle.evaluate(evalSerializer_1.serializeEvalResult);
-                if (typeof result === 'string')
-                    return { text: result };
-                if (result === undefined)
-                    return { text: 'undefined' };
-                return { text: JSON.stringify(result, null, 2) };
+                const resolved = await handle.evaluateHandle((value) => Promise.resolve(value));
+                try {
+                    const result = await resolved.evaluate(evalSerializer_1.serializeEvalResult);
+                    if (typeof result === 'string')
+                        return { text: result };
+                    if (result === undefined)
+                        return { text: 'undefined' };
+                    return { text: JSON.stringify(result, null, 2) };
+                }
+                finally {
+                    await resolved.dispose();
+                }
             }
             finally {
                 await handle.dispose();
@@ -282,6 +298,38 @@ async function executeCommand(launcher, args) {
             const label = target.kind === 'selector' ? `${selector} (${target.state})` : (0, interactions_1.describeWaitTarget)(target);
             return { text: `Wait satisfied: ${label} (${elapsedMs}ms)` };
         }
+        case 'sample': {
+            const expression = params[0];
+            if (!expression)
+                throw new Error('Expression is required for sample command');
+            const interval = args.interval ?? 250;
+            const duration = args.duration ?? 5000;
+            if (duration <= 0)
+                throw new Error('--duration must be greater than 0');
+            if (interval <= 0)
+                throw new Error('--interval must be greater than 0');
+            const frame = (0, frames_1.resolveFrame)(requirePage(launcher), args.frame);
+            const points = await (0, sampler_1.sampleFrame)(frame, expression, {
+                intervalMs: interval,
+                durationMs: duration,
+                ignoreErrors: !!args['ignore-errors'],
+            });
+            const summary = (0, sampler_1.summarizeSamples)(points, args.key, 5000, args['tail-from']);
+            return { text: JSON.stringify({ expression, intervalMs: interval, summary, series: points }, null, 2) };
+        }
+        case 'wait-stable': {
+            const expression = params[0];
+            if (!expression)
+                throw new Error('Expression is required for wait-stable command');
+            const frame = (0, frames_1.resolveFrame)(requirePage(launcher), args.frame);
+            const result = await (0, sampler_1.waitForStableValue)(frame, expression, {
+                tolerance: args.tolerance,
+                windowMs: args.window,
+                timeoutMs: args.timeout,
+                intervalMs: args.interval,
+            });
+            return { text: JSON.stringify({ ok: true, expression, ...result }, null, 2) };
+        }
         case 'run': {
             const absPath = params[0];
             if (!absPath)

package/dist/daemon/expect.d.ts

@@ -0,0 +1,8 @@
+export interface Matchers {
+    toBe(expected: unknown, label?: string): void;
+    toBeWithin(expected: number, tolerance: number, label?: string): void;
+    toMatch(pattern: RegExp | string, label?: string): void;
+    toHaveHash(hash: string, label?: string): void;
+    toBeSelected(index: number, label?: string): void;
+}
+export declare function expect(actual: unknown): Matchers;

package/dist/daemon/expect.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expect = expect;
+function labelSuffix(label) {
+    return label ? ` (${label})` : '';
+}
+function fail(label, message) {
+    throw new Error(`expect${labelSuffix(label)}: ${message}`);
+}
+function expect(actual) {
+    return {
+        toBe(expected, label) {
+            if (actual !== expected) {
+                fail(label, `expected ${JSON.stringify(expected)}, received ${JSON.stringify(actual)}`);
+            }
+        },
+        toBeWithin(expected, tolerance, label) {
+            if (typeof actual !== 'number' || !Number.isFinite(actual)) {
+                fail(label, `expected a finite number near ${expected}, received ${JSON.stringify(actual)}`);
+            }
+            if (Math.abs(actual - expected) > tolerance) {
+                fail(label, `expected ${expected} ±${tolerance}, received ${actual}`);
+            }
+        },
+        toMatch(pattern, label) {
+            if (typeof actual !== 'string') {
+                fail(label, `expected a string, received ${JSON.stringify(actual)}`);
+            }
+            const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+            if (!regex.test(actual)) {
+                fail(label, `expected ${JSON.stringify(actual)} to match ${regex}`);
+            }
+        },
+        toHaveHash(hash, label) {
+            const expected = hash.startsWith('#') ? hash : `#${hash}`;
+            if (actual !== expected) {
+                fail(label, `expected hash ${expected}, received ${JSON.stringify(actual)}`);
+            }
+        },
+        toBeSelected(index, label) {
+            if (actual !== index) {
+                fail(label, `expected selected index ${index}, received ${JSON.stringify(actual)}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=expect.js.map

package/dist/daemon/flowRunner.d.ts

@@ -1,13 +1,20 @@
-import type { Page } from 'playwright-core';
+import type { BrowserContext, Page } from 'playwright-core';
 import type { BrowserLauncher } from '../browser/launcher';
 import { type TargetResult, type TypeOptions, type WaitState } from '../browser/interactions';
 import type { Finding, Snapshot } from '../engine/types';
+import { type FrameInfo } from '../browser/frames';
+import { type Matchers } from './expect';
+export interface FlowPageError {
+    message: string;
+    stack?: string;
+}
 export interface FlowEnvelope {
     ok: boolean;
     logs: string[];
     result?: unknown;
     error?: string;
     elapsedMs: number;
+    pageErrors?: FlowPageError[];
 }
 export interface WaitForOptions {
     state?: WaitState;
@@ -20,6 +27,10 @@ export interface WaitOutcome {
 }
 export interface FlowApi {
     page: Page;
+    context: BrowserContext;
+    frames(): FrameInfo[];
+    newPage(): Promise<Page>;
+    expect(actual: unknown): Matchers;
     click(selector: string, opts?: {
         nth?: number;
         force?: boolean;

package/dist/daemon/flowRunner.js

@@ -15,6 +15,8 @@ const analyzer_1 = require("../engine/analyzer");
 const renderer_1 = require("../engine/renderer");
 const evalSerializer_1 = require("../engine/evalSerializer");
 const screenshot_1 = require("../utils/screenshot");
+const frames_1 = require("../browser/frames");
+const expect_1 = require("./expect");
 const FLOW_DEFAULT_TIMEOUT = 300_000;
 const CAPTURED_CONSOLE_METHODS = ['log', 'info', 'warn', 'error'];
 // tsc compiles `import()` to `require()` under module=commonjs, which cannot
@@ -102,6 +104,10 @@ function buildFlowApi(launcher, logs, baseDir) {
                 return (0, renderer_1.renderMarkdown)(snapshot, findings);
             return { snapshot, findings };
         },
+        context: page.context(),
+        frames: () => (0, frames_1.describeFrames)(page),
+        newPage: () => page.context().newPage(),
+        expect: (actual) => (0, expect_1.expect)(actual),
         screenshot: async (opts) => {
             const buffer = await page.screenshot({ fullPage: opts?.fullPage });
             const out = opts?.path ? path_1.default.resolve(baseDir, opts.path) : undefined;
@@ -122,6 +128,10 @@ function renderEnvelope(env) {
     else {
         lines.push(`Flow failed in ${env.elapsedMs}ms: ${env.error}`);
     }
+    if (env.pageErrors?.length) {
+        lines.push('', `Page errors (${env.pageErrors.length}):`);
+        lines.push(...env.pageErrors.map(error => `  - ${error.message}`));
+    }
     if (env.logs.length) {
         lines.push('', 'Logs:');
         lines.push(...env.logs.map(line => `  ${line}`));
@@ -132,6 +142,15 @@ async function runFlow(launcher, absPath, opts = {}) {
     const logs = [];
     const started = Date.now();
     const restore = captureConsole(logs);
+    const pageErrors = [];
+    const page = launcher.getPage();
+    const onPageError = (error) => {
+        pageErrors.push({
+            message: error.message,
+            stack: error.stack?.split('\n').slice(0, 6).join('\n'),
+        });
+    };
+    page?.on('pageerror', onPageError);
     let env;
     try {
         const fn = await loadFlowScript(absPath);
@@ -145,8 +164,11 @@ async function runFlow(launcher, absPath, opts = {}) {
         env = { ok: false, logs, error: e.message, elapsedMs: Date.now() - started };
     }
     finally {
+        page?.off('pageerror', onPageError);
         restore();
     }
+    if (pageErrors.length)
+        env.pageErrors = pageErrors;
     return {
         text: opts.json ? JSON.stringify(env, null, 2) : renderEnvelope(env),
         exitCode: env.ok ? 0 : 1,

package/dist/engine/evalSerializer.js

@@ -32,10 +32,10 @@ function serializeEvalResult(value) {
             return '[Depth limit]';
         seen.add(v);
         if (Array.isArray(v))
-            return v.map(item => walk(item, depth + 1));
+            return Array.from(v, item => (item === undefined ? null : walk(item, depth + 1)));
         const out = {};
         for (const [key, val] of Object.entries(v))
-            out[key] = walk(val, depth + 1);
+            out[key] = val === undefined ? null : walk(val, depth + 1);
         return out;
     };
     return walk(value, 0);

package/dist/help.json

@@ -1,13 +1,15 @@
 {
-  "global": "Usage: cssprobe-cli <command> [args] [options]\n\n\nSession Management:\n  open [url]                  open browser in session mode (non-blocking)\n  close                       close the browser session\n  status                      show current session status\n  resize <width> <height>     resize the browser viewport\n  eval <expression>           evaluate javascript expression on the page (browser context)\n  playwright <call>           execute playwright api call (node.js context)\n  click <selector>            click an element with real mouse events (works with custom react components)\n  hover <selector>            hover an element with real mouse events\n  type <selector> <text>      type text into an element (fill by default; --sequential for real key events)\n  wait-for [selector]         wait for a condition: selector state, js predicate, or network idle\n  run <file>                  run a multi-step flow script (default-exports an async function receiving the api object)\n  state-import [file]         import cookies from netscape format file\n  state-save                  save current browser session state (cookies + localstorage)\n  mcp                         start mcp server (stdio transport) for ai clients\n  mcp-install                 install mcp server config into ai client configs\n  mcp-uninstall               remove mcp server config from ai client configs\n\nCSS Inspection:\n  inspect <selector>          inspect the runtime css of a page element\n  tree <selector>             show dom tree structure\n  layout <selector>           show ascii layout diagram\n  findings <selector>         show only issues/warnings/errors\n  inject-css <css>            inject css into the current page\n\nExport:\n  screenshot                  take a screenshot of the current page\n\nConfiguration:\n  config-show                 show current configuration\n  config-set <key> <value>    set a configuration value\n  config-list                 list all profiles\n  config-use <name>           switch active profile\n  config-new <name>           create a new profile\n  config-path                 show configuration file path\n\nAgent Skills:\n  skill-install               install agent skill for cssprobe-cli\n  skill-uninstall             remove agent skill for cssprobe-cli\n\nGlobal options:\n  --help [command]            print help\n  --json                      output response as JSON\n  --raw                       output only the result value\n  --version                   print version\n  -p, --profile <name>        use named profile (or CSSPROBE_PROFILE env)",
+  "global": "Usage: cssprobe-cli <command> [args] [options]\n\n\nSession Management:\n  open [url]                  open browser in session mode (non-blocking)\n  close                       close the browser session\n  status                      show current session status\n  frames                      list frames in the current page\n  doctor                      diagnose browser installation and playwright revision mismatch\n  scenario <action> <file>    run a json scenario suite (regression cases, artifacts, junit)\n  resize <width> <height>     resize the browser viewport\n  eval <expression>           evaluate javascript expression on the page (browser context)\n  playwright <call>           execute playwright api call (node.js context)\n  click <selector>            click an element with real mouse events (works with custom react components)\n  hover <selector>            hover an element with real mouse events\n  type <selector> <text>      type text into an element (fill by default; --sequential for real key events)\n  wait-for [selector]         wait for a condition: selector state, js predicate, or network idle\n  sample <expression>         sample a js expression over time and return a timeline with summary stats\n  wait-stable <expression>    wait until a js expression stops changing (tolerance + stable window)\n  run <file>                  run a multi-step flow script (default-exports an async function receiving the api object)\n  state-import [file]         import cookies from netscape format file\n  state-save                  save current browser session state (cookies + localstorage)\n  state-check                 validate a saved state file: cookies, expiry, and target domain coverage\n  mcp                         start mcp server (stdio transport) for ai clients\n  mcp-install                 install mcp server config into ai client configs\n  mcp-uninstall               remove mcp server config from ai client configs\n\nCSS Inspection:\n  inspect <selector>          inspect the runtime css of a page element\n  tree <selector>             show dom tree structure\n  layout <selector>           show ascii layout diagram\n  findings <selector>         show only issues/warnings/errors\n  inject-css <css>            inject css into the current page\n\nExport:\n  screenshot                  take a screenshot of the current page\n\nConfiguration:\n  config-show                 show current configuration\n  config-set <key> <value>    set a configuration value\n  config-list                 list all profiles\n  config-use <name>           switch active profile\n  config-new <name>           create a new profile\n  config-path                 show configuration file path\n\nAgent Skills:\n  skill-install               install agent skill for cssprobe-cli\n  skill-uninstall             remove agent skill for cssprobe-cli\n\nGlobal options:\n  --help [command]            print help\n  --json                      output response as JSON\n  --raw                       output only the result value\n  --version                   print version\n  -p, --profile <name>        use named profile (or CSSPROBE_PROFILE env)",
   "commands": {
     "open": {
-      "help": "cssprobe-cli open [url]\n\nOpen browser in session mode (non-blocking)\n\nArguments:\n  [url]                       url, file:// path, or local html file path\nOptions:\n  --browser                   browser engine (default chromium)\n  --headed                    show the browser window\n  --viewport                  viewport size as wxh (e.g. 1280x720)\n  --state                     path to saved state file (cookies + localstorage)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli open [url]\n\nOpen browser in session mode (non-blocking)\n\nArguments:\n  [url]                       url, file:// path, or local html file path\nOptions:\n  --browser                   browser engine (default chromium)\n  --headed                    show the browser window\n  --viewport                  viewport size as wxh (e.g. 1280x720)\n  --state                     path to saved state file (cookies + localstorage)\n  --expect-url                regex the final page url must match\n  --fail-on-login             fail when the page redirects to a login url\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
         "browser": "string",
         "headed": "boolean",
         "viewport": "string",
-        "state": "string"
+        "state": "string",
+        "expect-url": "string",
+        "fail-on-login": "boolean"
       },
       "args": [
         "url"
@@ -25,44 +27,80 @@
       "flags": {},
       "args": []
     },
+    "frames": {
+      "help": "cssprobe-cli frames \n\nList frames in the current page\n\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {},
+      "args": []
+    },
+    "doctor": {
+      "help": "cssprobe-cli doctor \n\nDiagnose browser installation and Playwright revision mismatch\n\nOptions:\n  --engine                    browser engine: chromium, firefox, webkit (default: chromium)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "engine": "string"
+      },
+      "args": []
+    },
+    "scenario": {
+      "help": "cssprobe-cli scenario <action> <file>\n\nRun a JSON scenario suite (regression cases, artifacts, JUnit)\n\nArguments:\n  <action>                    only \"run\" is supported\n  <file>                      scenario suite json path\nOptions:\n  --state                     fallback state file when the suite/case does not set one\n  --artifacts                 artifact directory (default: ~/.cssprobe-cli/scenario-runs/<suite>-<timestamp>)\n  --junit                     write a junit xml report to this path\n  --bail                      stop after the first failing case\n  --headed                    show the browser window\n  --browser                   browser engine (default chromium)\n  --viewport                  viewport size as wxh (default: suite defaults or 1280x720)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "state": "string",
+        "artifacts": "string",
+        "junit": "string",
+        "bail": "boolean",
+        "headed": "boolean",
+        "browser": "string",
+        "viewport": "string"
+      },
+      "args": [
+        "action",
+        "file"
+      ]
+    },
     "inspect": {
-      "help": "cssprobe-cli inspect <selector>\n\nInspect the runtime CSS of a page element\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --json                      output structured json instead of markdown\n  --brief                     compact output: tree sketch + warnings/errors only\n  --layout                    ascii layout diagram showing element positions and sizes\n  --depth                     dom tree depth (default: auto, max 20)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli inspect <selector>\n\nInspect the runtime CSS of a page element\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --json                      output structured json instead of markdown\n  --brief                     compact output: tree sketch + warnings/errors only\n  --layout                    ascii layout diagram showing element positions and sizes\n  --depth                     dom tree depth (default: auto, max 20)\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
         "json": "boolean",
         "brief": "boolean",
         "layout": "boolean",
-        "depth": "string"
+        "depth": "string",
+        "frame": "string"
       },
       "args": [
         "selector"
       ]
     },
     "tree": {
-      "help": "cssprobe-cli tree <selector>\n\nShow DOM tree structure\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --depth                     tree depth (default: auto, max 20)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli tree <selector>\n\nShow DOM tree structure\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --depth                     tree depth (default: auto, max 20)\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
-        "depth": "string"
+        "depth": "string",
+        "frame": "string"
       },
       "args": [
         "selector"
       ]
     },
     "layout": {
-      "help": "cssprobe-cli layout <selector>\n\nShow ASCII layout diagram\n\nArguments:\n  <selector>                  css selector for the root element\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
-      "flags": {},
+      "help": "cssprobe-cli layout <selector>\n\nShow ASCII layout diagram\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "frame": "string"
+      },
       "args": [
         "selector"
       ]
     },
     "findings": {
-      "help": "cssprobe-cli findings <selector>\n\nShow only issues/warnings/errors\n\nArguments:\n  <selector>                  css selector for the root element\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
-      "flags": {},
+      "help": "cssprobe-cli findings <selector>\n\nShow only issues/warnings/errors\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "frame": "string"
+      },
       "args": [
         "selector"
       ]
     },
     "inject-css": {
-      "help": "cssprobe-cli inject-css <css>\n\nInject CSS into the current page\n\nArguments:\n  <css>                       css code to inject\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
-      "flags": {},
+      "help": "cssprobe-cli inject-css <css>\n\nInject CSS into the current page\n\nArguments:\n  <css>                       css code to inject\nOptions:\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "frame": "string"
+      },
       "args": [
         "css"
       ]
@@ -76,14 +114,16 @@
       ]
     },
     "eval": {
-      "help": "cssprobe-cli eval <expression>\n\nEvaluate JavaScript expression on the page (browser context)\n\nArguments:\n  <expression>                javascript expression to evaluate\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
-      "flags": {},
+      "help": "cssprobe-cli eval <expression>\n\nEvaluate JavaScript expression on the page (browser context)\n\nArguments:\n  <expression>                javascript expression, or @file / - (stdin) for long scripts\nOptions:\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "frame": "string"
+      },
       "args": [
         "expression"
       ]
     },
     "playwright": {
-      "help": "cssprobe-cli playwright <call>\n\nExecute Playwright API call (Node.js context)\n\nArguments:\n  <call>                      playwright api call, e.g. \"page.setviewportsize({width: 1280, height: 720})\"\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli playwright <call>\n\nExecute Playwright API call (Node.js context)\n\nArguments:\n  <call>                      playwright api call, or @file / - (stdin); e.g. \"page.setviewportsize({width: 1280, height: 720})\"\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {},
       "args": [
         "call"
@@ -146,6 +186,33 @@
         "selector"
       ]
     },
+    "sample": {
+      "help": "cssprobe-cli sample <expression>\n\nSample a JS expression over time and return a timeline with summary stats\n\nArguments:\n  <expression>                js expression sampled on an interval\nOptions:\n  --interval                  sampling interval in ms (default 250)\n  --duration                  total sampling duration in ms (default 5000)\n  --key                       dot path for numeric extraction, e.g. \"top\" or \"box.y\"\n  --tail-from                 tail starts at this elapsed ms (default: last 5000ms)\n  --ignore-errors             record evaluation errors as sample points instead of aborting\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "interval": "string",
+        "duration": "string",
+        "key": "string",
+        "tail-from": "string",
+        "ignore-errors": "boolean",
+        "frame": "string"
+      },
+      "args": [
+        "expression"
+      ]
+    },
+    "wait-stable": {
+      "help": "cssprobe-cli wait-stable <expression>\n\nWait until a JS expression stops changing (tolerance + stable window)\n\nArguments:\n  <expression>                js expression polled until stable\nOptions:\n  --tolerance                 absolute tolerance for numeric values (default 0)\n  --window                    stable window in ms (default 1500)\n  --timeout                   timeout in ms (default 30000)\n  --interval                  polling interval in ms (default 200)\n  --frame                     target frame: index, name, or url substring (default: main frame)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "tolerance": "string",
+        "window": "string",
+        "timeout": "string",
+        "interval": "string",
+        "frame": "string"
+      },
+      "args": [
+        "expression"
+      ]
+    },
     "run": {
       "help": "cssprobe-cli run <file>\n\nRun a multi-step flow script (default-exports an async function receiving the API object)\n\nArguments:\n  <file>                      flow script path (.js / .mjs / .cjs)\nOptions:\n  --timeout                   whole-script timeout in ms (default 300000, 0 = unlimited)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
@@ -173,6 +240,14 @@
       },
       "args": []
     },
+    "state-check": {
+      "help": "cssprobe-cli state-check \n\nValidate a saved state file: cookies, expiry, and target domain coverage\n\nOptions:\n  --state                     state file path (default: ~/.cssprobe-cli/states/session.json)\n  --url                       target url whose hostname must be covered by the cookies\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "state": "string",
+        "url": "string"
+      },
+      "args": []
+    },
     "config-show": {
       "help": "cssprobe-cli config-show \n\nShow current configuration\n\nOptions:\n  --profile                   profile name",
       "flags": {
@@ -256,7 +331,9 @@
   },
   "booleanOptions": [
     "headed",
+    "fail-on-login",
     "all",
+    "bail",
     "json",
     "brief",
     "layout",
@@ -265,6 +342,7 @@
     "sequential",
     "clear",
     "network-idle",
+    "ignore-errors",
     "local"
   ]
 }

package/dist/scenario/assertions.d.ts

@@ -0,0 +1,13 @@
+import type { AssertStep } from './schema';
+export interface AssertionState {
+    url: string;
+    title: string;
+    frames: number;
+}
+export interface AssertionContext {
+    vars: Record<string, unknown>;
+    state: AssertionState;
+    globals: Record<string, string>;
+}
+export declare function resolvePath(value: unknown, path?: string): unknown;
+export declare function evaluateAssertion(assertion: AssertStep, context: AssertionContext): string | null;