cssprobe-cli 0.3.0 → 0.3.1

package/AGENTS.md

@@ -4,7 +4,7 @@
 
 `cssprobe-cli` — Runtime CSS probe for layout/scroll/overflow/color/font inspection with session-based browser management. Entrypoint: `bin/cssprobe-cli.js` → `require('../dist/index')`.
 Build: `npm run build` (= `tsc` + `esbuild` collector IIFE bundle + `esbuild` daemon entry + `tsx scripts/generate-help.ts`).
-Test: `npm test` (= `tsx --test tests/*.test.ts` — Node.js built-in test runner, 58 tests).
+Test: `npm test` (= `tsx --test tests/*.test.ts` — Node.js built-in test runner, 108 tests).
 Dependencies: `playwright-core`, `zod`. Dev: `typescript`, `@types/node`, `tsx`, `esbuild`.
 
 ## Architecture
@@ -21,19 +21,23 @@ src/
 ├── 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
 │   └── daemonEntry.ts         # Daemon entry point (spawned as child process)
 ├── engine/
 │   ├── types.ts               # Shared types: Snapshot, TreeNode, Finding, Confidence
 │   ├── collector.ts           # Browser-side: DOM traversal, computed styles, declared values
 │   ├── analyzer.ts            # Node-side: pure functions, confidence model, pattern detection
+│   ├── evalSerializer.ts      # Self-contained serializer for eval results (runs in-page via JSHandle.evaluate)
 │   └── renderer.ts            # Markdown / JSON rendering
 ├── browser/
-│   └── launcher.ts            # Playwright wrapper: launch, navigate, inject collector
+│   ├── launcher.ts            # Playwright wrapper: launch, navigate, inject collector
+│   └── interactions.ts        # Interaction primitives: click/hover/type/wait-for (shared by daemon + run API)
 ├── config/
 │   ├── config.ts              # Config loader (CLI → env → ~/.cssprobe-clirc profiles)
 │   └── helpGenerator.ts       # Build-time: Zod schemas → dist/help.json
 └── utils/
-    └── socketConnection.ts    # Socket communication (adapted from playwright-cli)
+    ├── socketConnection.ts    # Socket communication (adapted from playwright-cli)
+    └── screenshot.ts          # Screenshot data-URL → file saving (shared by CLI + flow runner)
 ```
 
 ## Key Patterns
@@ -73,11 +77,32 @@ src/
 - `resize <width> <height>` — Resize browser viewport
 - `eval <expression>` — Evaluate JavaScript (browser context)
   - Returns raw string values (not JSON-quoted) for string results
+  - DOM nodes / circular structures are auto-serialized (descriptors, `[Circular]`, `[Function: name]`, depth cap 6)
 - `playwright <call>` — Execute Playwright API call (Node.js context)
   - Returns `{ ok: true, value: null, note: ... }` when the call returns no value; throws a clear error message on failure
 - `screenshot` — Take a screenshot
   - `--out <path>` — Output file path (default: `~/.cssprobe-cli/screenshots/<timestamp>.png`)
 
+### Interaction
+- `click <selector>` — Real mouse click (auto-scroll + actionability wait, works with custom React components)
+  - `--nth <n>` — 1-based match index (default: first match; multiple matches without `--nth` fail — strict)
+  - `--force` — skip actionability checks
+  - `--timeout <ms>` — action timeout (default 30000)
+- `hover <selector>` — Real mouse hover (`--nth` / `--force` / `--timeout` as above)
+- `type <selector> <text>` — Type text
+  - Default: `fill()` (replaces the value); `--sequential` for real key events (custom editors), `--clear` clears first
+  - `--press <key>` — press a key after typing (e.g. `Enter`)
+  - `--delay <ms>` — keystroke delay for `--sequential`
+- `wait-for` — Wait for a condition (three mutually exclusive modes)
+  - `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
+- `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)
+  - `--timeout <ms>` — whole-script guard (default 300000, 0 = unlimited); failure exits 1 and keeps the session alive
+  - `screenshot` relative paths resolve against the script's directory; logs collected and returned
+
 ### State
 - `state-import [file]` — Import cookies from Netscape format
   - `--out <file>` — Output state file path (default: `~/.cssprobe-cli/states/imported.json`)
@@ -151,6 +176,6 @@ cssprobe-cli close
 | Output | Single markdown string | Markdown (default) / JSON (--json) |
 | Config | `window.__DOM_REPORT_CFG` global + eval two-step | CLI flags → env → rc file, one command |
 | ROOT_SELECTOR | Manual or eval probe | `--auto-root` auto-detection |
-| Tests | None | 45 unit tests (command, analyzer, output, renderer) |
+| Tests | None | 45+ unit tests (command, analyzer, output, renderer) |
 | Build | Regex stripping CJS module.exports | esbuild IIFE + CJS bundle, clean build |
 | Session | None (blocking commands) | Session-based daemon architecture |

package/README.md

@@ -182,10 +182,24 @@ Exposes 10 tools: `cssprobe_open`, `cssprobe_inspect`, `cssprobe_tree`, `cssprob
 | Command | Description |
 |---------|-------------|
 | `resize <width> <height>` | Resize browser viewport |
-| `eval <expression>` | Evaluate JavaScript (browser context) |
+| `eval <expression>` | Evaluate JavaScript (browser context); DOM nodes are auto-serialized |
 | `playwright <call>` | Execute Playwright API (Node.js context) |
 | `screenshot` | Take screenshot (saves to ~/.cssprobe-cli/screenshots/, --out to override) |
 
+### Interaction
+
+| Command | Description |
+|---------|-------------|
+| `click <selector>` | Real mouse click (auto-scroll + actionability wait; works with custom React components) |
+| `hover <selector>` | Real mouse hover |
+| `type <selector> <text>` | Fill text (replaces value); `--press Enter` to submit; `--sequential` for real key events |
+| `wait-for <selector>` | Wait for selector state (`--state visible\|hidden\|attached\|detached`, `--timeout ms`) |
+| `wait-for --js "<predicate>"` | Wait until a JS predicate is truthy |
+| `wait-for --network-idle` | Wait until the page is network-idle |
+| `run <file>` | Run a multi-step flow script |
+
+`click` / `hover` support `--nth N` (1-based, default first match), `--force` (skip actionability checks) and `--timeout ms`. Without `--nth`, multiple matches fail (strict) to prevent wrong-target clicks.
+
 ### State
 
 | Command | Description |
@@ -206,6 +220,51 @@ Exposes 10 tools: `cssprobe_open`, `cssprobe_inspect`, `cssprobe_tree`, `cssprob
 
 ---
 
+## Multi-step Flows
+
+The interaction commands drive a page step by step; `run` turns a sequence into a versionable script:
+
+```bash
+cssprobe-cli open https://example.com/editor
+cssprobe-cli wait-for .editor-canvas
+cssprobe-cli click ".layout-switch" --nth 1
+cssprobe-cli type ".block-title input" "Hello" --press Enter
+cssprobe-cli inspect .block-grid --json
+cssprobe-cli close
+```
+
+For repeatable flows, write a script and run it with one command. The script runs inside the daemon session (full Playwright `page` access):
+
+```js
+// flow.js
+export default async ({ page, click, waitFor, type, inspect, screenshot, log }) => {
+  await page.goto('https://example.com/editor', { waitUntil: 'domcontentloaded' });
+  await waitFor('.editor-canvas', { state: 'visible', timeout: 10000 });
+
+  await click('.layout-switch', { nth: 1 });
+  await waitFor({ js: "() => document.body.dataset.layout === 'two-col'" });
+
+  await type('.block-title input', 'Hello', { press: 'Enter', sequential: true, clear: true });
+  await waitFor({ networkIdle: true });
+
+  const { findings } = await inspect('.block-grid', { format: 'json' });
+  log('findings:', findings.length);
+  await screenshot({ path: './after-layout-switch.png' });
+
+  return { findings: findings.length };
+};
+```
+
+```bash
+cssprobe-cli run ./flow.js        # --timeout ms for the whole script (default 300000, 0 = unlimited)
+```
+
+Scripts must `default-export` an async function receiving the API object: `page`, `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 are executed by the local daemon with full Node privileges — only run trusted scripts.
+
+---
+
 ## Confidence Model
 
 Every finding carries a confidence level:

package/dist/browser/interactions.d.ts

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

package/dist/browser/interactions.js

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

package/dist/cli/commands.js

@@ -157,6 +157,75 @@ const playwrightCmd = (0, command_1.declareCommand)({
         call: z.string().describe('Playwright API call, 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 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 ──
 const stateImport = (0, command_1.declareCommand)({
     name: 'state-import',
@@ -279,6 +348,8 @@ const commandsArray = [
     inspect, tree, layout, findings, injectCss,
     // browser
     resize, evalCmd, playwrightCmd, screenshot,
+    // interaction
+    click, hover, typeCmd, waitForCmd, runCmd,
     // state
     stateImport, stateSave,
     // config

package/dist/cli/program.js

@@ -70,8 +70,15 @@ async function program() {
         case 'eval':
         case 'resize':
         case 'playwright':
+        case 'click':
+        case 'hover':
+        case 'type':
+        case 'wait-for':
             await handleSessionCommand(commandName, command, rawArgs, output);
             return;
+        case 'run':
+            await handleRun(command, rawArgs, output);
+            return;
     }
     output.error(`Unknown command: ${commandName}. Run 'cssprobe-cli --help' for usage.`);
 }
@@ -197,6 +204,16 @@ async function handleStatus(output) {
         output.error(e instanceof Error ? e.message : String(e));
     }
 }
+async function handleRun(command, args, output) {
+    const fileArg = args._[1];
+    if (!fileArg)
+        output.error('Usage: cssprobe-cli run <file>');
+    const file = path_1.default.resolve(fileArg);
+    if (!fs_1.default.existsSync(file))
+        output.error(`Flow script not found: ${file}`);
+    args._ = ['run', file];
+    await handleSessionCommand('run', command, args, output);
+}
 async function handleSessionCommand(commandName, command, args, output) {
     try {
         const cmdArgs = splitArgs(args);
@@ -214,6 +231,8 @@ async function handleSessionCommand(commandName, command, args, output) {
             return;
         }
         console.log(result.text);
+        if (typeof result.exitCode === 'number' && result.exitCode !== 0)
+            process.exit(result.exitCode);
     }
     catch (e) {
         output.error(e instanceof Error ? e.message : String(e));

package/dist/cli/session-ops.d.ts

@@ -1,6 +1,7 @@
 import { Session } from '../daemon/session';
 import type { SessionConfig } from '../daemon/session';
 import type { AnyCommandSchema } from './command';
+export { saveScreenshotFile } from '../utils/screenshot';
 export interface OpenOptions {
     url?: string;
     browser?: string;
@@ -39,5 +40,5 @@ export declare function getSessionStatus(): Promise<StatusResult>;
 export declare function buildDaemonArgs(commandName: string, command: AnyCommandSchema, parsed: Record<string, unknown>): string[];
 export declare function runSessionCommand(commandName: string, command: AnyCommandSchema, parsed: Record<string, unknown>, json?: boolean): Promise<{
     text: string;
+    exitCode?: number;
 }>;
-export declare function saveScreenshotFile(dataUrl: string, out?: string): string;

package/dist/cli/session-ops.js

@@ -1,49 +1,15 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveScreenshotFile = void 0;
 exports.openSession = openSession;
 exports.waitForSession = waitForSession;
 exports.closeSession = closeSession;
 exports.getSessionStatus = getSessionStatus;
 exports.buildDaemonArgs = buildDaemonArgs;
 exports.runSessionCommand = runSessionCommand;
-exports.saveScreenshotFile = saveScreenshotFile;
-const fs = __importStar(require("fs"));
-const os = __importStar(require("os"));
-const path = __importStar(require("path"));
 const session_1 = require("../daemon/session");
+var screenshot_1 = require("../utils/screenshot");
+Object.defineProperty(exports, "saveScreenshotFile", { enumerable: true, get: function () { return screenshot_1.saveScreenshotFile; } });
 async function openSession(opts) {
     const url = opts.url || 'about:blank';
     const browser = opts.browser || 'chromium';
@@ -142,22 +108,4 @@ async function runSessionCommand(commandName, command, parsed, json = false) {
         runArgs.json = true;
     return await session.run(runArgs);
 }
-function saveScreenshotFile(dataUrl, out) {
-    const base64 = dataUrl.replace(/^data:image\/png;base64,/, '');
-    const buffer = Buffer.from(base64, 'base64');
-    const resolvedOut = out
-        ? path.resolve(out)
-        : (() => {
-            const dir = path.join(os.homedir(), '.cssprobe-cli', 'screenshots');
-            if (!fs.existsSync(dir))
-                fs.mkdirSync(dir, { recursive: true });
-            const ts = new Date().toISOString().replace(/[:.]/g, '-');
-            return path.join(dir, `screenshot-${ts}.png`);
-        })();
-    const dir = path.dirname(resolvedOut);
-    if (!fs.existsSync(dir))
-        fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(resolvedOut, buffer);
-    return resolvedOut;
-}
 //# sourceMappingURL=session-ops.js.map

package/dist/daemon/daemon.js

@@ -17,6 +17,9 @@ const launcher_1 = require("../browser/launcher");
 const analyzer_1 = require("../engine/analyzer");
 const renderer_1 = require("../engine/renderer");
 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 AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
 async function startDaemon(sessionName, clientInfo, options) {
     const sessionConfig = createSessionConfig(clientInfo, sessionName, options);
@@ -173,12 +176,18 @@ async function executeCommand(launcher, args) {
             const page = launcher.getPage();
             if (!page)
                 throw new Error('Browser is not open. Run: cssprobe-cli open <url>');
-            const result = await page.evaluate(expression);
-            if (typeof result === 'string')
-                return { text: result };
-            if (result === undefined)
-                return { text: 'undefined' };
-            return { text: JSON.stringify(result, null, 2) };
+            const handle = await page.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) };
+            }
+            finally {
+                await handle.dispose();
+            }
         }
         case 'resize': {
             const width = parseInt(params[0], 10);
@@ -206,6 +215,79 @@ async function executeCommand(launcher, args) {
                 return { text: JSON.stringify({ ok: true, value: null, note: 'call returned no value' }) };
             return { text: JSON.stringify(result, null, 2) };
         }
+        case 'click':
+        case 'hover': {
+            const selector = params[0];
+            if (!selector)
+                throw new Error(`Selector is required for ${command} command`);
+            const page = requirePage(launcher);
+            const opts = { nth: args.nth, force: args.force, timeout: args.timeout };
+            const result = command === 'click'
+                ? await (0, interactions_1.clickElement)(page, selector, opts)
+                : await (0, interactions_1.hoverElement)(page, selector, opts);
+            if (args.json) {
+                return { text: JSON.stringify({ ok: true, selector, matches: result.matches, nth: result.nth }, null, 2) };
+            }
+            return { text: formatTargetAction(command === 'click' ? 'Clicked' : 'Hovered', selector, result) };
+        }
+        case 'type': {
+            const selector = params[0];
+            const text = params[1];
+            if (!selector || text === undefined)
+                throw new Error('Usage: type <selector> <text>');
+            await (0, interactions_1.typeInto)(requirePage(launcher), selector, text, {
+                press: args.press,
+                sequential: args.sequential,
+                clear: args.clear,
+                delay: args.delay,
+                nth: args.nth,
+                timeout: args.timeout,
+            });
+            if (args.json) {
+                const payload = { ok: true, selector, length: text.length };
+                if (args.press)
+                    payload.pressed = args.press;
+                return { text: JSON.stringify(payload, null, 2) };
+            }
+            const pressedNote = args.press ? ` then pressed ${args.press}` : '';
+            return { text: `Typed ${text.length} chars into ${selector}${pressedNote}` };
+        }
+        case 'wait-for': {
+            // selector is read from the parsed object: option flags are appended to
+            // the argv array after positional args, so params[0] is not reliable here.
+            const selector = args.selector;
+            const timeout = args.timeout ?? 30000;
+            const target = (0, interactions_1.resolveWaitTarget)(selector, {
+                js: args.js,
+                networkIdle: args['network-idle'],
+                state: args.state,
+            });
+            let elapsedMs;
+            try {
+                elapsedMs = await (0, interactions_1.waitForCondition)(requirePage(launcher), target, timeout);
+            }
+            catch (e) {
+                throw new Error(`wait-for failed for ${(0, interactions_1.describeWaitTarget)(target)} within ${timeout}ms: ${e.message}`);
+            }
+            if (args.json) {
+                const payload = {
+                    ok: true,
+                    waitedFor: target.kind === 'networkIdle' ? 'networkidle' : target.kind,
+                    elapsedMs,
+                };
+                if (target.kind === 'selector')
+                    payload.state = target.state;
+                return { text: JSON.stringify(payload, null, 2) };
+            }
+            const label = target.kind === 'selector' ? `${selector} (${target.state})` : (0, interactions_1.describeWaitTarget)(target);
+            return { text: `Wait satisfied: ${label} (${elapsedMs}ms)` };
+        }
+        case 'run': {
+            const absPath = params[0];
+            if (!absPath)
+                throw new Error('Flow script path is required');
+            return await (0, flowRunner_1.runFlow)(launcher, absPath, { timeout: args.timeout, json: !!args.json });
+        }
         case 'state-save': {
             const context = launcher.getContext();
             if (!context)
@@ -217,6 +299,20 @@ async function executeCommand(launcher, args) {
             throw new Error(`Unknown command: ${command}`);
     }
 }
+function requirePage(launcher) {
+    const page = launcher.getPage();
+    if (!page)
+        throw new Error('Browser is not open. Run: cssprobe-cli open <url>');
+    return page;
+}
+function formatTargetAction(verb, selector, result) {
+    const descriptor = result.descriptor
+        ? ` → ${result.descriptor.tag}${result.descriptor.classes.map(c => `.${c}`).join('')}${result.descriptor.text ? ` "${result.descriptor.text}"` : ''}`
+        : '';
+    const matchNote = result.matches === 1 ? '1 match' : `${result.matches} matches`;
+    const nthNote = result.matches > 1 ? `, used #${result.nth}` : '';
+    return `${verb} ${selector}${descriptor} (${matchNote}${nthNote})`;
+}
 async function socketExists(socketPath) {
     try {
         const stat = await fs_1.default.promises.stat(socketPath);

package/dist/daemon/flowRunner.d.ts

@@ -0,0 +1,62 @@
+import type { 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';
+export interface FlowEnvelope {
+    ok: boolean;
+    logs: string[];
+    result?: unknown;
+    error?: string;
+    elapsedMs: number;
+}
+export interface WaitForOptions {
+    state?: WaitState;
+    timeout?: number;
+}
+export interface WaitOutcome {
+    waitedFor: 'selector' | 'js' | 'networkidle';
+    state?: WaitState;
+    elapsedMs: number;
+}
+export interface FlowApi {
+    page: Page;
+    click(selector: string, opts?: {
+        nth?: number;
+        force?: boolean;
+        timeout?: number;
+    }): Promise<TargetResult>;
+    hover(selector: string, opts?: {
+        nth?: number;
+        force?: boolean;
+        timeout?: number;
+    }): Promise<TargetResult>;
+    type(selector: string, text: string, opts?: TypeOptions): Promise<void>;
+    waitFor(target: string | {
+        js: string;
+        timeout?: number;
+    } | {
+        networkIdle: true;
+        timeout?: number;
+    }, opts?: WaitForOptions): Promise<WaitOutcome>;
+    inspect(selector: string, opts?: {
+        format?: 'json' | 'markdown';
+    }): Promise<{
+        snapshot: Snapshot;
+        findings: Finding[];
+    } | string>;
+    screenshot(opts?: {
+        path?: string;
+        fullPage?: boolean;
+    }): Promise<string>;
+    log(...args: unknown[]): void;
+}
+type FlowFn = (api: FlowApi) => Promise<unknown> | unknown;
+export declare function loadFlowScript(absPath: string): Promise<FlowFn>;
+export declare function runFlow(launcher: BrowserLauncher, absPath: string, opts?: {
+    timeout?: number;
+    json?: boolean;
+}): Promise<{
+    text: string;
+    exitCode: number;
+}>;
+export {};

package/dist/daemon/flowRunner.js

@@ -0,0 +1,155 @@
+"use strict";
+// Flow script runner: loads a user script in the daemon process, injects the
+// interaction API, captures console output and returns a result envelope.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadFlowScript = loadFlowScript;
+exports.runFlow = runFlow;
+const path_1 = __importDefault(require("path"));
+const util_1 = __importDefault(require("util"));
+const url_1 = require("url");
+const interactions_1 = require("../browser/interactions");
+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 FLOW_DEFAULT_TIMEOUT = 300_000;
+const CAPTURED_CONSOLE_METHODS = ['log', 'info', 'warn', 'error'];
+// tsc compiles `import()` to `require()` under module=commonjs, which cannot
+// load ESM scripts; a Function-constructed import keeps the native loader.
+const nativeImport = new Function('p', 'return import(p)');
+async function loadFlowScript(absPath) {
+    const mod = await nativeImport(`${(0, url_1.pathToFileURL)(absPath).href}?v=${Date.now()}`);
+    const fn = mod?.default;
+    if (typeof fn !== 'function')
+        throw new Error(`Flow script must default-export an async function: ${absPath}`);
+    return fn;
+}
+function captureConsole(logs) {
+    const originals = new Map();
+    for (const method of CAPTURED_CONSOLE_METHODS) {
+        originals.set(method, console[method]);
+        console[method] = (...args) => {
+            logs.push(`[${method}] ${util_1.default.format(...args)}`);
+        };
+    }
+    return () => {
+        for (const [method, original] of originals) {
+            console[method] = original;
+        }
+    };
+}
+async function withTimeout(promise, timeoutMs) {
+    if (!timeoutMs || timeoutMs <= 0)
+        return promise;
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Flow timed out after ${timeoutMs}ms (best-effort abort)`)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function requirePage(launcher) {
+    const page = launcher.getPage();
+    if (!page)
+        throw new Error('Browser is not open. Run: cssprobe-cli open <url>');
+    return page;
+}
+async function flowWaitFor(page, target, opts) {
+    if (typeof target === 'string') {
+        const state = opts?.state ?? 'visible';
+        const timeout = opts?.timeout ?? 30_000;
+        const elapsedMs = await (0, interactions_1.waitForCondition)(page, { kind: 'selector', selector: target, state }, timeout);
+        return { waitedFor: 'selector', state, elapsedMs };
+    }
+    if ('js' in target) {
+        const timeout = target.timeout ?? 30_000;
+        const elapsedMs = await (0, interactions_1.waitForCondition)(page, { kind: 'js', expression: target.js }, timeout);
+        return { waitedFor: 'js', elapsedMs };
+    }
+    if (target.networkIdle) {
+        const timeout = target.timeout ?? 30_000;
+        const elapsedMs = await (0, interactions_1.waitForCondition)(page, { kind: 'networkIdle' }, timeout);
+        return { waitedFor: 'networkidle', elapsedMs };
+    }
+    throw new Error('waitFor requires a selector string, { js }, or { networkIdle: true }');
+}
+function buildFlowApi(launcher, logs, baseDir) {
+    const page = requirePage(launcher);
+    return {
+        page,
+        click: (selector, opts) => (0, interactions_1.clickElement)(page, selector, opts),
+        hover: (selector, opts) => (0, interactions_1.hoverElement)(page, selector, opts),
+        type: (selector, text, opts) => (0, interactions_1.typeInto)(page, selector, text, opts),
+        waitFor: (target, opts) => flowWaitFor(page, target, opts),
+        inspect: async (selector, opts) => {
+            const snapshot = await launcher.collect({
+                rootSelector: selector,
+                downDepth: 6,
+                maxNodes: 60,
+                upTo: 'html',
+            });
+            const findings = (0, analyzer_1.analyze)(snapshot);
+            if (opts?.format === 'markdown')
+                return (0, renderer_1.renderMarkdown)(snapshot, findings);
+            return { snapshot, findings };
+        },
+        screenshot: async (opts) => {
+            const buffer = await page.screenshot({ fullPage: opts?.fullPage });
+            const out = opts?.path ? path_1.default.resolve(baseDir, opts.path) : undefined;
+            return (0, screenshot_1.saveScreenshotFile)(`data:image/png;base64,${buffer.toString('base64')}`, out);
+        },
+        log: (...args) => {
+            logs.push(util_1.default.format(...args));
+        },
+    };
+}
+function renderEnvelope(env) {
+    const lines = [];
+    if (env.ok) {
+        lines.push(`Flow completed in ${env.elapsedMs}ms`);
+        if (env.result !== undefined)
+            lines.push(`Result: ${JSON.stringify(env.result, null, 2)}`);
+    }
+    else {
+        lines.push(`Flow failed in ${env.elapsedMs}ms: ${env.error}`);
+    }
+    if (env.logs.length) {
+        lines.push('', 'Logs:');
+        lines.push(...env.logs.map(line => `  ${line}`));
+    }
+    return lines.join('\n');
+}
+async function runFlow(launcher, absPath, opts = {}) {
+    const logs = [];
+    const started = Date.now();
+    const restore = captureConsole(logs);
+    let env;
+    try {
+        const fn = await loadFlowScript(absPath);
+        const api = buildFlowApi(launcher, logs, path_1.default.dirname(absPath));
+        const result = await withTimeout(Promise.resolve(fn(api)), opts.timeout ?? FLOW_DEFAULT_TIMEOUT);
+        env = { ok: true, logs, elapsedMs: Date.now() - started };
+        if (result !== undefined)
+            env.result = (0, evalSerializer_1.serializeEvalResult)(result);
+    }
+    catch (e) {
+        env = { ok: false, logs, error: e.message, elapsedMs: Date.now() - started };
+    }
+    finally {
+        restore();
+    }
+    return {
+        text: opts.json ? JSON.stringify(env, null, 2) : renderEnvelope(env),
+        exitCode: env.ok ? 0 : 1,
+    };
+}
+//# sourceMappingURL=flowRunner.js.map

package/dist/engine/evalSerializer.d.ts

@@ -0,0 +1 @@
+export declare function serializeEvalResult(value: unknown): unknown;

package/dist/engine/evalSerializer.js

@@ -0,0 +1,43 @@
+"use strict";
+// Self-contained serializer for eval results.
+// Runs inside the page via JSHandle.evaluate (function source is transferred),
+// and is unit-testable in Node — keep it free of external references.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeEvalResult = serializeEvalResult;
+function serializeEvalResult(value) {
+    const seen = new WeakSet();
+    const walk = (v, depth) => {
+        if (v === null || typeof v !== 'object') {
+            if (typeof v === 'function')
+                return `[Function: ${v.name || 'anonymous'}]`;
+            if (typeof v === 'bigint')
+                return `${v}n`;
+            return v;
+        }
+        if (typeof Node !== 'undefined' && v instanceof Node) {
+            if (v.nodeType === 1) {
+                const el = v;
+                return {
+                    tag: el.tagName.toLowerCase(),
+                    id: el.id,
+                    classes: Array.from(el.classList),
+                    text: (el.textContent ?? '').trim().slice(0, 120),
+                };
+            }
+            return `[${v.nodeName}]`;
+        }
+        if (seen.has(v))
+            return '[Circular]';
+        if (depth >= 6)
+            return '[Depth limit]';
+        seen.add(v);
+        if (Array.isArray(v))
+            return v.map(item => walk(item, depth + 1));
+        const out = {};
+        for (const [key, val] of Object.entries(v))
+            out[key] = walk(val, depth + 1);
+        return out;
+    };
+    return walk(value, 0);
+}
+//# sourceMappingURL=evalSerializer.js.map

package/dist/help.json

@@ -1,5 +1,5 @@
 {
-  "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  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  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)",
   "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",
@@ -97,6 +97,64 @@
       },
       "args": []
     },
+    "click": {
+      "help": "cssprobe-cli click <selector>\n\nClick an element with real mouse events (works with custom React components)\n\nArguments:\n  <selector>                  css selector\nOptions:\n  --nth                       1-based match index (default: first match)\n  --force                     skip actionability checks\n  --timeout                   action timeout in ms (default 30000)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "nth": "string",
+        "force": "boolean",
+        "timeout": "string"
+      },
+      "args": [
+        "selector"
+      ]
+    },
+    "hover": {
+      "help": "cssprobe-cli hover <selector>\n\nHover an element with real mouse events\n\nArguments:\n  <selector>                  css selector\nOptions:\n  --nth                       1-based match index (default: first match)\n  --force                     skip actionability checks\n  --timeout                   action timeout in ms (default 30000)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "nth": "string",
+        "force": "boolean",
+        "timeout": "string"
+      },
+      "args": [
+        "selector"
+      ]
+    },
+    "type": {
+      "help": "cssprobe-cli type <selector> <text>\n\nType text into an element (fill by default; --sequential for real key events)\n\nArguments:\n  <selector>                  css selector\n  <text>                      text to type\nOptions:\n  --press                     key to press after typing (e.g. enter, tab, control+a)\n  --sequential                type with real key events (for custom editors)\n  --clear                     clear existing content before sequential typing\n  --delay                     delay between keystrokes in ms (--sequential, default 0)\n  --nth                       1-based match index (default: first match)\n  --timeout                   action timeout in ms (default 30000)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "press": "string",
+        "sequential": "boolean",
+        "clear": "boolean",
+        "delay": "string",
+        "nth": "string",
+        "timeout": "string"
+      },
+      "args": [
+        "selector",
+        "text"
+      ]
+    },
+    "wait-for": {
+      "help": "cssprobe-cli wait-for [selector]\n\nWait for a condition: selector state, JS predicate, or network idle\n\nArguments:\n  [selector]                  css selector to wait for\nOptions:\n  --state                     selector state to wait for (default visible)\n  --js                        js predicate, e.g. \"() => document.queryselector('.x')?.offsetheight > 100\"\n  --network-idle              wait until the page is network-idle\n  --timeout                   timeout in ms (default 30000)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "state": "string",
+        "js": "string",
+        "network-idle": "boolean",
+        "timeout": "string"
+      },
+      "args": [
+        "selector"
+      ]
+    },
+    "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": {
+        "timeout": "string"
+      },
+      "args": [
+        "file"
+      ]
+    },
     "state-import": {
       "help": "cssprobe-cli state-import [file]\n\nImport cookies from Netscape format file\n\nArguments:\n  [file]                      netscape cookie file path (reads from stdin if omitted)\nOptions:\n  --out                       output state file path (default: ~/.cssprobe-cli/states/imported.json)\n  --name                      custom name for the state file (e.g. mysite or mysite.json)\n  --merge                     existing state file to merge into\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
@@ -203,6 +261,10 @@
     "brief",
     "layout",
     "full-page",
+    "force",
+    "sequential",
+    "clear",
+    "network-idle",
     "local"
   ]
 }

package/dist/installer/skill-template.js

@@ -127,6 +127,49 @@ function buildSkillMd() {
         'cssprobe-cli close                         # stop browser + daemon',
         BT3,
         '',
+        '## Multi-step UI Flows',
+        '',
+        'Beyond inspection, cssprobe-cli drives the page: click, hover, type, wait, and',
+        'run scripted flows -- all in the same session.',
+        '',
+        BT3 + 'bash',
+        'cssprobe-cli click ".layout-switch"            # real mouse click (auto-scroll + actionability wait)',
+        'cssprobe-cli click ".item" --nth 2             # 1-based match index; multi-match without --nth fails (strict)',
+        'cssprobe-cli hover ".menu-item"',
+        'cssprobe-cli type ".block-title input" "Hi" --press Enter    # fill by default',
+        'cssprobe-cli type ".editor" "text" --sequential --clear      # real key events for custom editors',
+        'cssprobe-cli wait-for ".modal" --state visible --timeout 5000',
+        'cssprobe-cli wait-for --js "() => ready === true"',
+        'cssprobe-cli wait-for --network-idle',
+        BT3,
+        '',
+        '### Scripted flows: ' + BT + 'run <file>' + BT,
+        '',
+        'A flow script default-exports an async function receiving the API object and',
+        'runs inside the daemon session:',
+        '',
+        BT3 + 'js',
+        'export default async ({ page, click, hover, type, waitFor, inspect, screenshot, log }) => {',
+        '  await waitFor(".editor-canvas");',
+        '  await click(".layout-switch", { nth: 1 });',
+        '  await type(".block-title input", "Hello", { press: "Enter", sequential: true, clear: true });',
+        '  await waitFor({ networkIdle: true });',
+        '  const { findings } = await inspect(".block-grid", { format: "json" });',
+        '  await screenshot({ path: "./after.png" });',
+        '  return { findings: findings.length };',
+        '};',
+        BT3,
+        '',
+        BT3 + 'bash',
+        'cssprobe-cli run ./flow.js        # --timeout ms (default 300000, 0 = unlimited)',
+        BT3,
+        '',
+        'Notes:',
+        '',
+        '- Scripts run on your machine with full Node privileges -- only run trusted scripts.',
+        '- ' + BT + 'screenshot' + BT + ' relative paths resolve against the script directory.',
+        '- On failure the command exits 1, prints collected logs, and keeps the session alive.',
+        '',
         '## Output Modes',
         '',
         'Pass ' + BT + '--json' + BT + ' when consuming output programmatically:',

package/dist/utils/screenshot.d.ts

@@ -0,0 +1 @@
+export declare function saveScreenshotFile(dataUrl: string, out?: string): string;

package/dist/utils/screenshot.js

@@ -0,0 +1,58 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveScreenshotFile = saveScreenshotFile;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+function saveScreenshotFile(dataUrl, out) {
+    const base64 = dataUrl.replace(/^data:image\/png;base64,/, '');
+    const buffer = Buffer.from(base64, 'base64');
+    const resolvedOut = out
+        ? path.resolve(out)
+        : (() => {
+            const dir = path.join(os.homedir(), '.cssprobe-cli', 'screenshots');
+            if (!fs.existsSync(dir))
+                fs.mkdirSync(dir, { recursive: true });
+            const ts = new Date().toISOString().replace(/[:.]/g, '-');
+            return path.join(dir, `screenshot-${ts}.png`);
+        })();
+    const dir = path.dirname(resolvedOut);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(resolvedOut, buffer);
+    return resolvedOut;
+}
+//# sourceMappingURL=screenshot.js.map

package/llms.txt

@@ -1,6 +1,6 @@
 # cssprobe-cli
 
-> Runtime CSS probe — inspect layout, scroll, colors, backgrounds, fonts in a live browser. Returns DOM tree, ASCII layout diagram and confidence-classified findings for humans and AI agents.
+> Runtime CSS probe — inspect layout, scroll, colors, backgrounds, fonts in a live browser. Returns DOM tree, ASCII layout diagram and confidence-classified findings for humans and AI agents. Interaction commands (click / hover / type / wait-for) drive the page; `run <file>` executes scripted multi-step flows.
 
 ## Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssprobe-cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "mcpName": "io.github.mack-peng/cssprobe-cli",
   "description": "Runtime CSS probe — inspect layout, colors, backgrounds, fonts and more in a live browser. AI agents and shell automation.",
   "keywords": [