cssprobe-cli 0.3.0 → 0.4.0

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;

package/dist/browser/sampler.d.ts

@@ -0,0 +1,43 @@
+import type { Frame } from 'playwright-core';
+export interface SamplePoint {
+    t: number;
+    value: unknown;
+    visibility: string;
+    error?: string;
+}
+export interface SampleSummary {
+    samples: number;
+    durationMs: number;
+    first: SamplePoint | null;
+    last: SamplePoint | null;
+    min: number | null;
+    max: number | null;
+    numeric: Array<[number, number]>;
+    changes: number;
+    hiddenMs: number;
+    tail: {
+        fromT: number;
+        min: number | null;
+        max: number | null;
+        windowMs: number;
+    };
+}
+export declare function extractNumber(value: unknown, key?: string): number | null;
+export declare function summarizeSamples(points: SamplePoint[], key?: string, tailWindowMs?: number, tailFromMs?: number): SampleSummary;
+export declare function isWithinTolerance(previous: unknown, next: unknown, tolerance: number): boolean;
+export declare function sampleFrame(frame: Frame, expression: string, opts: {
+    intervalMs: number;
+    durationMs: number;
+    ignoreErrors?: boolean;
+}): Promise<SamplePoint[]>;
+export declare function waitForStableValue(frame: Frame, expression: string, opts: {
+    toleranceMs?: number;
+    windowMs?: number;
+    timeoutMs?: number;
+    intervalMs?: number;
+    tolerance?: number;
+}): Promise<{
+    elapsedMs: number;
+    value: unknown;
+    samples: number;
+}>;

package/dist/browser/sampler.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractNumber = extractNumber;
+exports.summarizeSamples = summarizeSamples;
+exports.isWithinTolerance = isWithinTolerance;
+exports.sampleFrame = sampleFrame;
+exports.waitForStableValue = waitForStableValue;
+function extractNumber(value, key) {
+    if (key) {
+        let current = value;
+        for (const part of key.split('.')) {
+            if (current === null || current === undefined)
+                return null;
+            current = current[part];
+        }
+        return typeof current === 'number' && Number.isFinite(current) ? current : null;
+    }
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function summarizeSamples(points, key, tailWindowMs = 5000, tailFromMs) {
+    const numeric = [];
+    for (const point of points) {
+        const n = extractNumber(point.value, key);
+        if (n !== null)
+            numeric.push([point.t, n]);
+    }
+    const tailFrom = Math.max(0, tailFromMs ?? (points.length ? points[points.length - 1].t - tailWindowMs : 0));
+    const tailNumeric = numeric.filter(([t]) => t >= tailFrom).map(([, value]) => value);
+    let changes = 0;
+    let hiddenMs = 0;
+    for (let i = 0; i < points.length; i++) {
+        if (i > 0 && JSON.stringify(points[i].value) !== JSON.stringify(points[i - 1].value))
+            changes++;
+        if (i < points.length - 1 && points[i].visibility !== 'visible') {
+            hiddenMs += points[i + 1].t - points[i].t;
+        }
+    }
+    return {
+        samples: points.length,
+        durationMs: points.length ? points[points.length - 1].t : 0,
+        first: points[0] ?? null,
+        last: points[points.length - 1] ?? null,
+        min: numeric.length ? Math.min(...numeric.map(item => item[1])) : null,
+        max: numeric.length ? Math.max(...numeric.map(item => item[1])) : null,
+        numeric,
+        changes,
+        hiddenMs,
+        tail: {
+            fromT: tailFrom,
+            min: tailNumeric.length ? Math.min(...tailNumeric) : null,
+            max: tailNumeric.length ? Math.max(...tailNumeric) : null,
+            windowMs: tailWindowMs,
+        },
+    };
+}
+function isWithinTolerance(previous, next, tolerance) {
+    if (typeof previous === 'number' && typeof next === 'number') {
+        if (Number.isNaN(previous) || Number.isNaN(next))
+            return false;
+        return Math.abs(next - previous) <= tolerance;
+    }
+    return JSON.stringify(previous) === JSON.stringify(next);
+}
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+async function readValue(frame, expression) {
+    return frame.evaluate(`(async () => ({ value: await (${expression}), visibility: document.visibilityState }))()`);
+}
+async function sampleFrame(frame, expression, opts) {
+    const intervalMs = Math.max(1, Math.floor(opts.intervalMs));
+    const started = Date.now();
+    const points = [];
+    while (Date.now() - started < opts.durationMs) {
+        const t = Date.now() - started;
+        try {
+            const { value, visibility } = await readValue(frame, expression);
+            points.push({ t, value, visibility });
+        }
+        catch (error) {
+            if (!opts.ignoreErrors)
+                throw error;
+            points.push({ t, value: null, visibility: 'unknown', error: error.message });
+        }
+        await sleep(intervalMs);
+    }
+    return points;
+}
+async function waitForStableValue(frame, expression, opts) {
+    const intervalMs = Math.max(1, opts.intervalMs ?? 200);
+    const windowMs = Math.max(1, opts.windowMs ?? 1500);
+    const timeoutMs = Math.max(1, opts.timeoutMs ?? 30000);
+    const tolerance = opts.tolerance ?? 0;
+    const started = Date.now();
+    let previous;
+    let stableSince = started;
+    let samples = 0;
+    while (Date.now() - started < timeoutMs) {
+        const { value } = await readValue(frame, expression);
+        samples++;
+        const now = Date.now();
+        if (samples === 1 || !isWithinTolerance(previous, value, tolerance)) {
+            previous = value;
+            stableSince = now;
+        }
+        else if (now - stableSince >= windowMs) {
+            return { elapsedMs: now - started, value, samples };
+        }
+        await sleep(intervalMs);
+    }
+    throw new Error(`wait-stable timed out after ${timeoutMs}ms; last value: ${JSON.stringify(previous)}`);
+}
+//# sourceMappingURL=sampler.js.map

package/dist/cli/commands.d.ts

@@ -14,14 +14,17 @@ export declare const inspectCommand: import("./command").CommandSchema<z.ZodObje
     brief: z.ZodOptional<z.ZodBoolean>;
     layout: z.ZodOptional<z.ZodBoolean>;
     depth: z.ZodOptional<z.ZodEffects<z.ZodNumber, number, unknown>>;
+    frame: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     json?: boolean | undefined;
     brief?: boolean | undefined;
     layout?: boolean | undefined;
     depth?: number | undefined;
+    frame?: string | undefined;
 }, {
     json?: boolean | undefined;
     brief?: boolean | undefined;
     layout?: boolean | undefined;
     depth?: unknown;
+    frame?: string | undefined;
 }>>;

package/dist/cli/commands.js

@@ -57,6 +57,8 @@ const open = (0, command_1.declareCommand)({
         headed: z.boolean().optional().describe('show the browser window'),
         viewport: z.string().optional().describe('viewport size as WxH (e.g. 1280x720)'),
         state: z.string().optional().describe('path to saved state file (cookies + localStorage)'),
+        'expect-url': z.string().optional().describe('regex the final page URL must match'),
+        'fail-on-login': z.boolean().optional().describe('fail when the page redirects to a login URL'),
     }),
 });
 const close = (0, command_1.declareCommand)({
@@ -72,6 +74,37 @@ const status = (0, command_1.declareCommand)({
     category: 'core',
     description: 'Show current session status',
 });
+const framesCmd = (0, command_1.declareCommand)({
+    name: 'frames',
+    category: 'core',
+    description: 'List frames in the current page',
+});
+const scenarioCmd = (0, command_1.declareCommand)({
+    name: 'scenario',
+    category: 'core',
+    description: 'Run a JSON scenario suite (regression cases, artifacts, JUnit)',
+    args: z.object({
+        action: z.literal('run').describe('only "run" is supported'),
+        file: z.string().describe('scenario suite JSON path'),
+    }),
+    options: z.object({
+        state: z.string().optional().describe('fallback state file when the suite/case does not set one'),
+        artifacts: z.string().optional().describe('artifact directory (default: ~/.cssprobe-cli/scenario-runs/<suite>-<timestamp>)'),
+        junit: z.string().optional().describe('write a JUnit XML report to this path'),
+        bail: z.boolean().optional().describe('stop after the first failing case'),
+        headed: z.boolean().optional().describe('show the browser window'),
+        browser: z.enum(['chromium', 'firefox', 'webkit']).optional().describe('browser engine (default chromium)'),
+        viewport: z.string().optional().describe('viewport size as WxH (default: suite defaults or 1280x720)'),
+    }),
+});
+const doctor = (0, command_1.declareCommand)({
+    name: 'doctor',
+    category: 'core',
+    description: 'Diagnose browser installation and Playwright revision mismatch',
+    options: z.object({
+        engine: z.string().optional().describe('browser engine: chromium, firefox, webkit (default: chromium)'),
+    }),
+});
 // ── cssprobe commands ──
 const inspect = (0, command_1.declareCommand)({
     name: 'inspect',
@@ -85,6 +118,7 @@ const inspect = (0, command_1.declareCommand)({
         brief: z.boolean().optional().describe('compact output: tree sketch + warnings/errors only'),
         layout: z.boolean().optional().describe('ASCII layout diagram showing element positions and sizes'),
         depth: numberArg.optional().describe('DOM tree depth (default: auto, max 20)'),
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
     }),
 });
 const tree = (0, command_1.declareCommand)({
@@ -96,6 +130,7 @@ const tree = (0, command_1.declareCommand)({
     }),
     options: z.object({
         depth: numberArg.optional().describe('tree depth (default: auto, max 20)'),
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
     }),
 });
 const layout = (0, command_1.declareCommand)({
@@ -105,6 +140,9 @@ const layout = (0, command_1.declareCommand)({
     args: z.object({
         selector: z.string().describe('CSS selector for the root element'),
     }),
+    options: z.object({
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
+    }),
 });
 const findings = (0, command_1.declareCommand)({
     name: 'findings',
@@ -113,6 +151,9 @@ const findings = (0, command_1.declareCommand)({
     args: z.object({
         selector: z.string().describe('CSS selector for the root element'),
     }),
+    options: z.object({
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
+    }),
 });
 const injectCss = (0, command_1.declareCommand)({
     name: 'inject-css',
@@ -121,6 +162,9 @@ const injectCss = (0, command_1.declareCommand)({
     args: z.object({
         css: z.string().describe('CSS code to inject'),
     }),
+    options: z.object({
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
+    }),
 });
 // ── browser commands ──
 const screenshot = (0, command_1.declareCommand)({
@@ -146,7 +190,10 @@ const evalCmd = (0, command_1.declareCommand)({
     category: 'core',
     description: 'Evaluate JavaScript expression on the page (browser context)',
     args: z.object({
-        expression: z.string().describe('JavaScript expression to evaluate'),
+        expression: z.string().describe('JavaScript expression, or @file / - (stdin) for long scripts'),
+    }),
+    options: z.object({
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
     }),
 });
 const playwrightCmd = (0, command_1.declareCommand)({
@@ -154,7 +201,107 @@ const playwrightCmd = (0, command_1.declareCommand)({
     category: 'core',
     description: 'Execute Playwright API call (Node.js context)',
     args: z.object({
-        call: z.string().describe('Playwright API call, e.g. "page.setViewportSize({width: 1280, height: 720})"'),
+        call: z.string().describe('Playwright API call, or @file / - (stdin); e.g. "page.setViewportSize({width: 1280, height: 720})"'),
+    }),
+});
+// ── interaction ──
+const click = (0, command_1.declareCommand)({
+    name: 'click',
+    category: 'core',
+    description: 'Click an element with real mouse events (works with custom React components)',
+    args: z.object({
+        selector: z.string().describe('CSS selector'),
+    }),
+    options: z.object({
+        nth: numberArg.optional().describe('1-based match index (default: first match)'),
+        force: z.boolean().optional().describe('skip actionability checks'),
+        timeout: numberArg.optional().describe('action timeout in ms (default 30000)'),
+    }),
+});
+const hover = (0, command_1.declareCommand)({
+    name: 'hover',
+    category: 'core',
+    description: 'Hover an element with real mouse events',
+    args: z.object({
+        selector: z.string().describe('CSS selector'),
+    }),
+    options: z.object({
+        nth: numberArg.optional().describe('1-based match index (default: first match)'),
+        force: z.boolean().optional().describe('skip actionability checks'),
+        timeout: numberArg.optional().describe('action timeout in ms (default 30000)'),
+    }),
+});
+const typeCmd = (0, command_1.declareCommand)({
+    name: 'type',
+    category: 'core',
+    description: 'Type text into an element (fill by default; --sequential for real key events)',
+    args: z.object({
+        selector: z.string().describe('CSS selector'),
+        text: z.string().describe('text to type'),
+    }),
+    options: z.object({
+        press: z.string().optional().describe('key to press after typing (e.g. Enter, Tab, Control+A)'),
+        sequential: z.boolean().optional().describe('type with real key events (for custom editors)'),
+        clear: z.boolean().optional().describe('clear existing content before sequential typing'),
+        delay: numberArg.optional().describe('delay between keystrokes in ms (--sequential, default 0)'),
+        nth: numberArg.optional().describe('1-based match index (default: first match)'),
+        timeout: numberArg.optional().describe('action timeout in ms (default 30000)'),
+    }),
+});
+const waitForCmd = (0, command_1.declareCommand)({
+    name: 'wait-for',
+    category: 'core',
+    description: 'Wait for a condition: selector state, JS predicate, or network idle',
+    args: z.object({
+        selector: z.string().optional().describe('CSS selector to wait for'),
+    }),
+    options: z.object({
+        state: z.enum(['visible', 'hidden', 'attached', 'detached']).optional().describe('selector state to wait for (default visible)'),
+        js: z.string().optional().describe('JS predicate, e.g. "() => document.querySelector(\'.x\')?.offsetHeight > 100"'),
+        'network-idle': z.boolean().optional().describe('wait until the page is network-idle'),
+        timeout: numberArg.optional().describe('timeout in ms (default 30000)'),
+    }),
+});
+const sampleCmd = (0, command_1.declareCommand)({
+    name: 'sample',
+    category: 'core',
+    description: 'Sample a JS expression over time and return a timeline with summary stats',
+    args: z.object({
+        expression: z.string().describe('JS expression sampled on an interval'),
+    }),
+    options: z.object({
+        interval: numberArg.optional().describe('sampling interval in ms (default 250)'),
+        duration: numberArg.optional().describe('total sampling duration in ms (default 5000)'),
+        key: z.string().optional().describe('dot path for numeric extraction, e.g. "top" or "box.y"'),
+        'tail-from': numberArg.optional().describe('tail starts at this elapsed ms (default: last 5000ms)'),
+        'ignore-errors': z.boolean().optional().describe('record evaluation errors as sample points instead of aborting'),
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
+    }),
+});
+const waitStableCmd = (0, command_1.declareCommand)({
+    name: 'wait-stable',
+    category: 'core',
+    description: 'Wait until a JS expression stops changing (tolerance + stable window)',
+    args: z.object({
+        expression: z.string().describe('JS expression polled until stable'),
+    }),
+    options: z.object({
+        tolerance: numberArg.optional().describe('absolute tolerance for numeric values (default 0)'),
+        window: numberArg.optional().describe('stable window in ms (default 1500)'),
+        timeout: numberArg.optional().describe('timeout in ms (default 30000)'),
+        interval: numberArg.optional().describe('polling interval in ms (default 200)'),
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
+    }),
+});
+const runCmd = (0, command_1.declareCommand)({
+    name: 'run',
+    category: 'core',
+    description: 'Run a multi-step flow script (default-exports an async function receiving the API object)',
+    args: z.object({
+        file: z.string().describe('flow script path (.js / .mjs / .cjs)'),
+    }),
+    options: z.object({
+        timeout: numberArg.optional().describe('whole-script timeout in ms (default 300000, 0 = unlimited)'),
     }),
 });
 // ── state management ──
@@ -179,6 +326,15 @@ const stateSave = (0, command_1.declareCommand)({
         name: z.string().optional().describe('state file name (default: session)'),
     }),
 });
+const stateCheck = (0, command_1.declareCommand)({
+    name: 'state-check',
+    category: 'core',
+    description: 'Validate a saved state file: cookies, expiry, and target domain coverage',
+    options: z.object({
+        state: z.string().optional().describe('state file path (default: ~/.cssprobe-cli/states/session.json)'),
+        url: z.string().optional().describe('target URL whose hostname must be covered by the cookies'),
+    }),
+});
 // ── config ──
 const configShow = (0, command_1.declareCommand)({
     name: 'config-show',
@@ -274,13 +430,15 @@ const mcpUninstall = (0, command_1.declareCommand)({
 // ── export ──
 const commandsArray = [
     // session management
-    open, close, status,
+    open, close, status, framesCmd, doctor, scenarioCmd,
     // cssprobe
     inspect, tree, layout, findings, injectCss,
     // browser
     resize, evalCmd, playwrightCmd, screenshot,
+    // interaction
+    click, hover, typeCmd, waitForCmd, sampleCmd, waitStableCmd, runCmd,
     // state
-    stateImport, stateSave,
+    stateImport, stateSave, stateCheck,
     // config
     configShow, configSet, configList, configUse, configNew, configPath,
     // skill

package/dist/cli/input.d.ts

@@ -0,0 +1,6 @@
+export interface InputSource {
+    readFile?: (file: string) => string;
+    readStdin?: () => string;
+    exists?: (file: string) => boolean;
+}
+export declare function resolveInputArg(value: string, source?: InputSource): string;

package/dist/cli/input.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveInputArg = resolveInputArg;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function resolveInputArg(value, source = {}) {
+    const exists = source.exists ?? fs_1.default.existsSync;
+    const readFile = source.readFile ?? ((file) => fs_1.default.readFileSync(file, 'utf-8'));
+    if (value === '-') {
+        const readStdin = source.readStdin ?? (() => fs_1.default.readFileSync(0, 'utf-8'));
+        return readStdin();
+    }
+    if (value.startsWith('@')) {
+        const file = path_1.default.resolve(value.slice(1));
+        if (!exists(file))
+            throw new Error(`File not found: ${file}`);
+        return readFile(file);
+    }
+    return value;
+}
+//# sourceMappingURL=input.js.map