cssprobe-cli 0.4.0 → 0.4.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, 170 tests).
+Test: `npm test` (= `tsx --test tests/*.test.ts` — Node.js built-in test runner, 173 tests).
 Dependencies: `playwright-core`, `zod`. Dev: `typescript`, `@types/node`, `tsx`, `esbuild`.
 
 ## Architecture
@@ -63,6 +63,7 @@ src/
 - **Output strategy**: `Output` interface → `TextOutput` (Markdown for inspect, tables for lists) / `JsonOutput` (machine-readable JSON).
 - **Config priority**: CLI flags → env vars → `~/.cssprobe-clirc` profiles. Switch with `-p <profile>`.
 - **State management**: `state-import` converts Netscape cookies; `state-save` persists the current session's cookies + localStorage after manual login. Session persists browser state until `close`.
+- **Iframe guidance**: pages may contain hidden helper iframes (`about:blank`); use `frames` to pick the real one and `state: "attached"` for hidden targets. Preview frames can render in 6–8s while analytics keep `networkIdle` busy — use a fixed `wait` plus an in-frame `waitFor` instead of `networkIdle`.
 - **Browser discovery**: `findBrowserExecutable()` scans the platform Playwright cache (macOS/Linux/Windows, `PLAYWRIGHT_BROWSERS_PATH` override), prefers the revision required by the bundled `playwright-core`, and falls back to the newest install. `doctor` reports expected vs installed revisions.
 - **Error format**: `Error: <message>` → JSON mode: `{ isError: true, error: "<message>" }` → `process.exit(1)`
 
@@ -116,14 +117,17 @@ src/
   - `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
+  - `--frame <index|name|url-substring>` — wait inside a frame (selector/js only; `networkIdle` is page-level)
 - `scenario run <file>` — Run a JSON scenario suite (fresh browser per case, assertions, artifacts, JUnit)
   - `--state <file>` — Fallback state file for cases without one
   - `--artifacts <dir>` — Artifact directory (default `~/.cssprobe-cli/scenario-runs/<suite>-<timestamp>`)
   - `--junit <file>` — Write a JUnit XML report
   - `--bail` — Stop after the first failing case
-  - Steps: `goto`, `reload`, `eval`, `sample`, `waitStable`, `click`, `waitFor`, `screenshot`, `assert`
+  - Steps: `goto`, `reload`, `wait`, `eval`, `sample`, `waitStable`, `click`, `waitFor`, `screenshot`, `assert`
+  - `wait` takes a fixed `ms`; `waitFor` accepts `frame` for in-iframe selector/js waits
 - `run <file>` — Run a multi-step flow script inside the daemon
   - Script default-exports an async function receiving the API object: `page`, `context`, `frames()`, `newPage()`, `click`, `hover`, `type`, `waitFor`, `inspect`, `screenshot`, `expect`, `log` (CJS also supported)
+  - `waitFor(target, { state, timeout, frame })`; `frame` targets iframe selector/js waits
   - Uncaught page errors are collected in the envelope as `pageErrors[]`
   - `--timeout <ms>` — whole-script guard (default 300000, 0 = unlimited); failure exits 1 and keeps the session alive
   - `screenshot` relative paths resolve against the script's directory; logs collected and returned

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.4.1] - 2026-10-23
+
+### Added
+- `wait-for --frame` (selector/js), scenario `waitFor.frame`, and flow `waitFor(target, { frame })`
+- Scenario `wait` step for fixed delays before slow-rendering preview frames
+
+### Documentation
+- Iframe/preview guidance: hidden helper frames need `state: "attached"`; prefer in-frame `waitFor` over `networkIdle` when analytics keep the page busy
+
 ## [0.4.0] - 2026-10-23
 
 ### Added

package/README.md

@@ -202,7 +202,8 @@ Inspection commands accept `--frame <index|name|url-substring>` to target an ifr
 | `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 |
+| `wait-for --network-idle` | Wait until the page is network-idle (page-level; no `--frame`) |
+| `wait-for ... --frame <spec>` | Wait inside an iframe (selector/js modes) |
 | `sample "<expr>"` | Sample an expression over time (`--interval`, `--duration`, `--key`, `--frame`); returns timeline + summary |
 | `wait-stable "<expr>"` | Wait until an expression stops changing (`--tolerance`, `--window`, `--timeout`) |
 | `run <file>` | Run a multi-step flow script |
@@ -269,7 +270,7 @@ export default async ({ page, context, frames, newPage, click, waitFor, type, in
 cssprobe-cli run ./flow.js        # --timeout ms for the whole script (default 300000, 0 = unlimited)
 ```
 
-Scripts must `default-export` an async function receiving the API object: `page`, `context`, `frames()`, `newPage()`, `click`, `hover`, `type`, `waitFor`, `inspect`, `screenshot`, `expect`, `log`. Uncaught page errors are collected into the result envelope as `pageErrors`. `screenshot` relative paths resolve against the script's directory; logs (`log()` and `console.*`) are collected and returned with the result. On failure the command exits `1`, prints the collected logs, and keeps the session alive.
+Scripts must `default-export` an async function receiving the API object: `page`, `context`, `frames()`, `newPage()`, `click`, `hover`, `type`, `waitFor`, `inspect`, `screenshot`, `expect`, `log`. `waitFor` accepts `{ state, timeout, frame }`. Uncaught page errors are collected into the result envelope as `pageErrors`. `screenshot` relative paths resolve against the script's directory; logs (`log()` and `console.*`) are collected and returned with the result. On failure the command exits `1`, prints the collected logs, and keeps the session alive.
 
 > Scripts are executed by the local daemon with full Node privileges — only run trusted scripts.
 
@@ -313,7 +314,9 @@ cssprobe-cli scenario run suites/ticket-26571394.json \
 }
 ```
 
-Steps: `goto`, `reload`, `eval`, `sample`, `waitStable`, `click`, `waitFor`, `screenshot`, `assert`. `sample` and `eval` save values with `save: "<name>"`; assertions read them with `on: "<name>"` + `path`, or check live `state` (`url`, `title`, `frames`), `url`, `globals`, `absent`. `sample` supports `key`, `tailFrom`, `ignoreErrors`; every run writes `summary.json`, per-case `case.json`, sample series and failure screenshots.
+Steps: `goto`, `reload`, `wait`, `eval`, `sample`, `waitStable`, `click`, `waitFor`, `screenshot`, `assert`. `wait` takes a fixed `ms`; `waitFor` supports `frame` for in-iframe selector/js waits. `sample` and `eval` save values with `save: "<name>"`; assertions read them with `on: "<name>"` + `path`, or check live `state` (`url`, `title`, `frames`), `url`, `globals`, `absent`. `sample` supports `key`, `tailFrom`, `ignoreErrors`; every run writes `summary.json`, per-case `case.json`, sample series and failure screenshots.
+
+**Iframe and preview pages.** A page can contain hidden helper iframes (`about:blank`); use `frames` to pick the real one, and `state: "attached"` when waiting for a frame element that is not visible. Preview frames can take 6–8s to render and analytics requests keep `networkIdle` busy — prefer a fixed `wait` step followed by a `waitFor` inside the frame (`frame: "i/preview"`) instead of `networkIdle`.
 
 ## Confidence Model
 

package/dist/browser/interactions.d.ts

@@ -1,4 +1,4 @@
-import type { Page } from 'playwright-core';
+import type { Frame, Page } from 'playwright-core';
 export interface ElementDescriptor {
     tag: string;
     classes: string[];
@@ -46,4 +46,4 @@ export declare function resolveWaitTarget(selector: string | undefined, opts: {
     state?: string;
 }): WaitTarget;
 export declare function normalizePredicateExpression(expression: string): string;
-export declare function waitForCondition(page: Page, target: WaitTarget, timeout: number): Promise<number>;
+export declare function waitForCondition(host: Page | Frame, target: WaitTarget, timeout: number): Promise<number>;

package/dist/browser/interactions.js

@@ -78,17 +78,21 @@ function normalizePredicateExpression(expression) {
         return trimmed;
     return `(${trimmed})()`;
 }
-async function waitForCondition(page, target, timeout) {
+async function waitForCondition(host, target, timeout) {
+    const isPage = typeof host.setViewportSize === 'function';
+    if (target.kind === 'networkIdle' && !isPage) {
+        throw new Error('networkIdle waits are page-level; remove the frame target');
+    }
     const started = Date.now();
     switch (target.kind) {
         case 'selector':
-            await page.waitForSelector(target.selector, { state: target.state, timeout });
+            await host.waitForSelector(target.selector, { state: target.state, timeout });
             break;
         case 'js':
-            await page.waitForFunction(normalizePredicateExpression(target.expression), null, { timeout });
+            await host.waitForFunction(normalizePredicateExpression(target.expression), null, { timeout });
             break;
         case 'networkIdle':
-            await page.waitForLoadState('networkidle', { timeout });
+            await host.waitForLoadState('networkidle', { timeout });
             break;
     }
     return Date.now() - started;

package/dist/cli/commands.js

@@ -259,6 +259,7 @@ const waitForCmd = (0, command_1.declareCommand)({
         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'),
+        frame: z.string().optional().describe('wait inside a frame: index, name, or URL substring'),
         timeout: numberArg.optional().describe('timeout in ms (default 30000)'),
     }),
 });

package/dist/daemon/daemon.js

@@ -278,9 +278,11 @@ async function executeCommand(launcher, args) {
                 networkIdle: args['network-idle'],
                 state: args.state,
             });
+            const page = requirePage(launcher);
+            const waitHost = args.frame ? (0, frames_1.resolveFrame)(page, args.frame) : page;
             let elapsedMs;
             try {
-                elapsedMs = await (0, interactions_1.waitForCondition)(requirePage(launcher), target, timeout);
+                elapsedMs = await (0, interactions_1.waitForCondition)(waitHost, target, timeout);
             }
             catch (e) {
                 throw new Error(`wait-for failed for ${(0, interactions_1.describeWaitTarget)(target)} within ${timeout}ms: ${e.message}`);

package/dist/daemon/flowRunner.d.ts

@@ -19,6 +19,7 @@ export interface FlowEnvelope {
 export interface WaitForOptions {
     state?: WaitState;
     timeout?: number;
+    frame?: string;
 }
 export interface WaitOutcome {
     waitedFor: 'selector' | 'js' | 'networkidle';

package/dist/daemon/flowRunner.js

@@ -66,20 +66,23 @@ function requirePage(launcher) {
     return page;
 }
 async function flowWaitFor(page, target, opts) {
+    const host = opts?.frame ? (0, frames_1.resolveFrame)(page, opts.frame) : page;
     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);
+        const elapsedMs = await (0, interactions_1.waitForCondition)(host, { 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);
+        const elapsedMs = await (0, interactions_1.waitForCondition)(host, { kind: 'js', expression: target.js }, timeout);
         return { waitedFor: 'js', elapsedMs };
     }
     if (target.networkIdle) {
+        if (opts?.frame)
+            throw new Error('networkIdle waits are page-level; remove opts.frame');
         const timeout = target.timeout ?? 30_000;
-        const elapsedMs = await (0, interactions_1.waitForCondition)(page, { kind: 'networkIdle' }, timeout);
+        const elapsedMs = await (0, interactions_1.waitForCondition)(host, { kind: 'networkIdle' }, timeout);
         return { waitedFor: 'networkidle', elapsedMs };
     }
     throw new Error('waitFor requires a selector string, { js }, or { networkIdle: true }');

package/dist/help.json

@@ -175,11 +175,12 @@
       ]
     },
     "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",
+      "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  --frame                     wait inside a frame: index, name, or url substring\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",
+        "frame": "string",
         "timeout": "string"
       },
       "args": [

package/dist/scenario/runner.js

@@ -207,20 +207,27 @@ async function executeStep(step, context) {
         }
         case 'waitFor': {
             const timeout = step.timeout ?? 30000;
+            const frameSpec = step.frame ?? context.frameSpec;
             if (step.networkIdle) {
+                if (frameSpec)
+                    throw new Error('networkIdle waits are page-level; remove frame');
                 await (0, interactions_1.waitForCondition)(page, { kind: 'networkIdle' }, timeout);
             }
             else if (step.js) {
-                await (0, interactions_1.waitForCondition)(page, { kind: 'js', expression: step.js }, timeout);
+                await (0, interactions_1.waitForCondition)(frameSpec ? (0, frames_1.resolveFrame)(page, frameSpec) : page, { kind: 'js', expression: step.js }, timeout);
             }
             else if (step.selector) {
-                await (0, interactions_1.waitForCondition)(page, { kind: 'selector', selector: step.selector, state: step.state ?? 'visible' }, timeout);
+                await (0, interactions_1.waitForCondition)(frameSpec ? (0, frames_1.resolveFrame)(page, frameSpec) : page, { kind: 'selector', selector: step.selector, state: step.state ?? 'visible' }, timeout);
             }
             else {
                 throw new Error('waitFor requires selector, js, or networkIdle');
             }
             return;
         }
+        case 'wait': {
+            await new Promise(resolve => setTimeout(resolve, step.ms));
+            return;
+        }
         case 'screenshot': {
             const buffer = await page.screenshot({ fullPage: step.fullPage });
             const out = path_1.default.resolve(caseDir, step.path ?? `step-${stepIndex + 1}-screenshot.png`);

package/dist/scenario/schema.d.ts

@@ -177,11 +177,13 @@ export declare const stepSchema: z.ZodDiscriminatedUnion<"do", [z.ZodObject<{
     js: z.ZodOptional<z.ZodString>;
     networkIdle: z.ZodOptional<z.ZodBoolean>;
     state: z.ZodOptional<z.ZodEnum<["visible", "hidden", "attached", "detached"]>>;
+    frame: z.ZodOptional<z.ZodString>;
     timeout: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     do: "waitFor";
     state?: "visible" | "hidden" | "attached" | "detached" | undefined;
     selector?: string | undefined;
+    frame?: string | undefined;
     timeout?: number | undefined;
     js?: string | undefined;
     networkIdle?: boolean | undefined;
@@ -189,9 +191,19 @@ export declare const stepSchema: z.ZodDiscriminatedUnion<"do", [z.ZodObject<{
     do: "waitFor";
     state?: "visible" | "hidden" | "attached" | "detached" | undefined;
     selector?: string | undefined;
+    frame?: string | undefined;
     timeout?: number | undefined;
     js?: string | undefined;
     networkIdle?: boolean | undefined;
+}>, z.ZodObject<{
+    do: z.ZodLiteral<"wait">;
+    ms: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    do: "wait";
+    ms: number;
+}, {
+    do: "wait";
+    ms: number;
 }>, z.ZodObject<{
     do: z.ZodLiteral<"screenshot">;
     path: z.ZodOptional<z.ZodString>;
@@ -387,11 +399,13 @@ export declare const caseSchema: z.ZodObject<{
         js: z.ZodOptional<z.ZodString>;
         networkIdle: z.ZodOptional<z.ZodBoolean>;
         state: z.ZodOptional<z.ZodEnum<["visible", "hidden", "attached", "detached"]>>;
+        frame: z.ZodOptional<z.ZodString>;
         timeout: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         do: "waitFor";
         state?: "visible" | "hidden" | "attached" | "detached" | undefined;
         selector?: string | undefined;
+        frame?: string | undefined;
         timeout?: number | undefined;
         js?: string | undefined;
         networkIdle?: boolean | undefined;
@@ -399,9 +413,19 @@ export declare const caseSchema: z.ZodObject<{
         do: "waitFor";
         state?: "visible" | "hidden" | "attached" | "detached" | undefined;
         selector?: string | undefined;
+        frame?: string | undefined;
         timeout?: number | undefined;
         js?: string | undefined;
         networkIdle?: boolean | undefined;
+    }>, z.ZodObject<{
+        do: z.ZodLiteral<"wait">;
+        ms: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        do: "wait";
+        ms: number;
+    }, {
+        do: "wait";
+        ms: number;
     }>, z.ZodObject<{
         do: z.ZodLiteral<"screenshot">;
         path: z.ZodOptional<z.ZodString>;
@@ -516,9 +540,13 @@ export declare const caseSchema: z.ZodObject<{
         do: "waitFor";
         state?: "visible" | "hidden" | "attached" | "detached" | undefined;
         selector?: string | undefined;
+        frame?: string | undefined;
         timeout?: number | undefined;
         js?: string | undefined;
         networkIdle?: boolean | undefined;
+    } | {
+        do: "wait";
+        ms: number;
     } | {
         do: "screenshot";
         path?: string | undefined;
@@ -588,9 +616,13 @@ export declare const caseSchema: z.ZodObject<{
         do: "waitFor";
         state?: "visible" | "hidden" | "attached" | "detached" | undefined;
         selector?: string | undefined;
+        frame?: string | undefined;
         timeout?: number | undefined;
         js?: string | undefined;
         networkIdle?: boolean | undefined;
+    } | {
+        do: "wait";
+        ms: number;
     } | {
         do: "screenshot";
         path?: string | undefined;
@@ -775,11 +807,13 @@ export declare const suiteSchema: z.ZodObject<{
             js: z.ZodOptional<z.ZodString>;
             networkIdle: z.ZodOptional<z.ZodBoolean>;
             state: z.ZodOptional<z.ZodEnum<["visible", "hidden", "attached", "detached"]>>;
+            frame: z.ZodOptional<z.ZodString>;
             timeout: z.ZodOptional<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
             do: "waitFor";
             state?: "visible" | "hidden" | "attached" | "detached" | undefined;
             selector?: string | undefined;
+            frame?: string | undefined;
             timeout?: number | undefined;
             js?: string | undefined;
             networkIdle?: boolean | undefined;
@@ -787,9 +821,19 @@ export declare const suiteSchema: z.ZodObject<{
             do: "waitFor";
             state?: "visible" | "hidden" | "attached" | "detached" | undefined;
             selector?: string | undefined;
+            frame?: string | undefined;
             timeout?: number | undefined;
             js?: string | undefined;
             networkIdle?: boolean | undefined;
+        }>, z.ZodObject<{
+            do: z.ZodLiteral<"wait">;
+            ms: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            do: "wait";
+            ms: number;
+        }, {
+            do: "wait";
+            ms: number;
         }>, z.ZodObject<{
             do: z.ZodLiteral<"screenshot">;
             path: z.ZodOptional<z.ZodString>;
@@ -904,9 +948,13 @@ export declare const suiteSchema: z.ZodObject<{
             do: "waitFor";
             state?: "visible" | "hidden" | "attached" | "detached" | undefined;
             selector?: string | undefined;
+            frame?: string | undefined;
             timeout?: number | undefined;
             js?: string | undefined;
             networkIdle?: boolean | undefined;
+        } | {
+            do: "wait";
+            ms: number;
         } | {
             do: "screenshot";
             path?: string | undefined;
@@ -976,9 +1024,13 @@ export declare const suiteSchema: z.ZodObject<{
             do: "waitFor";
             state?: "visible" | "hidden" | "attached" | "detached" | undefined;
             selector?: string | undefined;
+            frame?: string | undefined;
             timeout?: number | undefined;
             js?: string | undefined;
             networkIdle?: boolean | undefined;
+        } | {
+            do: "wait";
+            ms: number;
         } | {
             do: "screenshot";
             path?: string | undefined;
@@ -1051,9 +1103,13 @@ export declare const suiteSchema: z.ZodObject<{
             do: "waitFor";
             state?: "visible" | "hidden" | "attached" | "detached" | undefined;
             selector?: string | undefined;
+            frame?: string | undefined;
             timeout?: number | undefined;
             js?: string | undefined;
             networkIdle?: boolean | undefined;
+        } | {
+            do: "wait";
+            ms: number;
         } | {
             do: "screenshot";
             path?: string | undefined;
@@ -1135,9 +1191,13 @@ export declare const suiteSchema: z.ZodObject<{
             do: "waitFor";
             state?: "visible" | "hidden" | "attached" | "detached" | undefined;
             selector?: string | undefined;
+            frame?: string | undefined;
             timeout?: number | undefined;
             js?: string | undefined;
             networkIdle?: boolean | undefined;
+        } | {
+            do: "wait";
+            ms: number;
         } | {
             do: "screenshot";
             path?: string | undefined;

package/dist/scenario/schema.js

@@ -94,8 +94,13 @@ const waitForStep = z.object({
     js: z.string().optional(),
     networkIdle: z.boolean().optional(),
     state: z.enum(['visible', 'hidden', 'attached', 'detached']).optional(),
+    frame: z.string().optional(),
     timeout: z.number().optional(),
 });
+const waitStep = z.object({
+    do: z.literal('wait'),
+    ms: z.number().positive(),
+});
 const screenshotStep = z.object({
     do: z.literal('screenshot'),
     path: z.string().optional(),
@@ -119,6 +124,7 @@ exports.stepSchema = z.discriminatedUnion('do', [
     waitStableStep,
     clickStep,
     waitForStep,
+    waitStep,
     screenshotStep,
     assertStep,
 ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssprobe-cli",
-  "version": "0.4.0",
+  "version": "0.4.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": [