cssprobe-cli 0.3.1 → 0.4.1

package/dist/cli/program.js

@@ -9,11 +9,17 @@ const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const minimist_1 = require("./minimist");
 const command_1 = require("./command");
+const input_1 = require("./input");
 const commands_1 = require("./commands");
 const output_1 = require("./output");
 const config_1 = require("../config/config");
 const session_1 = require("../daemon/session");
 const session_ops_1 = require("./session-ops");
+const state_check_1 = require("./state-check");
+const launcher_1 = require("../browser/launcher");
+const schema_1 = require("../scenario/schema");
+const runner_1 = require("../scenario/runner");
+const reporters_1 = require("../scenario/reporters");
 const mcp_1 = require("../mcp");
 const globalOptions = ['json', 'raw', 'help', 'h', 'version', 'v', 'p', 'profile'];
 const booleanGlobalOptions = ['help', 'json', 'raw', 'version', 'v', 'h'];
@@ -52,15 +58,25 @@ async function program() {
         case 'close':
             await handleClose(command, rawArgs, output);
             return;
+        case 'doctor':
+            handleDoctor(command, rawArgs, output);
+            return;
+        case 'scenario':
+            await handleScenario(command, rawArgs, output);
+            return;
         case 'status':
             await handleStatus(output);
             return;
         case 'state-import':
             await handleStateImport(command, rawArgs, output);
             return;
+        case 'state-check':
+            handleStateCheck(command, rawArgs, output);
+            return;
         case 'state-save':
             await handleStateSave(command, rawArgs, output);
             return;
+        case 'frames':
         case 'inspect':
         case 'tree':
         case 'layout':
@@ -74,6 +90,8 @@ async function program() {
         case 'hover':
         case 'type':
         case 'wait-for':
+        case 'sample':
+        case 'wait-stable':
             await handleSessionCommand(commandName, command, rawArgs, output);
             return;
         case 'run':
@@ -148,6 +166,8 @@ async function handleOpen(command, args, output) {
             headed: !!parsed.headed,
             viewport,
             state: parsed.state,
+            expectUrl: parsed['expect-url'],
+            failOnLogin: !!parsed['fail-on-login'],
         });
         if (output.json) {
             console.log(JSON.stringify(result, null, 2));
@@ -183,11 +203,100 @@ async function handleClose(command, args, output) {
         output.error(e instanceof Error ? e.message : String(e));
     }
 }
+async function handleScenario(command, args, output) {
+    try {
+        const cmdArgs = splitArgs(args);
+        const parsed = (0, command_1.parseCommand)(command, cmdArgs);
+        const file = path_1.default.resolve(parsed.file);
+        if (!fs_1.default.existsSync(file))
+            output.error(`Scenario suite not found: ${file}`);
+        const raw = JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+        const validation = schema_1.suiteSchema.safeParse(raw);
+        if (!validation.success) {
+            const issues = validation.error.issues
+                .map(issue => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+                .join('\n');
+            output.error(`Invalid scenario suite:\n${issues}`);
+        }
+        let viewport;
+        const viewportStr = parsed.viewport;
+        if (viewportStr) {
+            const parts = viewportStr.split('x');
+            const width = parseInt(parts[0], 10);
+            const height = parseInt(parts[1], 10);
+            if (parts.length !== 2 || isNaN(width) || isNaN(height)) {
+                output.error('Invalid viewport format. Use WxH (e.g. 1280x720)');
+            }
+            viewport = { width, height };
+        }
+        const result = await (0, runner_1.runScenario)(validation.data, file, {
+            artifactsDir: parsed.artifacts,
+            junitPath: parsed.junit,
+            bail: !!parsed.bail,
+            headed: !!parsed.headed,
+            browser: parsed.browser,
+            viewport,
+            state: parsed.state,
+        });
+        if (output.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log((0, reporters_1.formatConsole)(result.suite, result.results));
+            console.log(`Artifacts: ${result.artifactsDir}`);
+            if (parsed.junit)
+                console.log(`JUnit: ${path_1.default.resolve(parsed.junit)}`);
+        }
+        if (!result.ok)
+            process.exit(1);
+    }
+    catch (e) {
+        output.error(e instanceof Error ? e.message : String(e));
+    }
+}
+function handleDoctor(command, args, output) {
+    try {
+        const cmdArgs = splitArgs(args);
+        const parsed = (0, command_1.parseCommand)(command, cmdArgs);
+        const diagnosis = (0, launcher_1.diagnoseBrowser)(parsed.engine);
+        if (output.json) {
+            console.log(JSON.stringify(diagnosis, null, 2));
+            return;
+        }
+        console.log(`Platform: ${diagnosis.platform}`);
+        console.log(`Cache roots: ${diagnosis.cacheRoots.join(', ')}`);
+        console.log(`Expected: chromium ${diagnosis.expected.chromium ?? 'unknown'}, headless-shell ${diagnosis.expected.headlessShell ?? 'unknown'} (playwright-core ${diagnosis.expected.playwrightVersion ?? 'unknown'})`);
+        if (diagnosis.installs.length) {
+            console.log('Installed:');
+            for (const install of diagnosis.installs) {
+                console.log(`  ${install.kind}-${install.revision}${install.executable ? '' : ' (no executable)'} ${install.dir}`);
+            }
+        }
+        else {
+            console.log('Installed: none');
+        }
+        console.log(`Status: ${diagnosis.status}`);
+        if (diagnosis.hint)
+            console.log(`Hint: ${diagnosis.hint}`);
+    }
+    catch (e) {
+        output.error(e instanceof Error ? e.message : String(e));
+    }
+}
 async function handleStatus(output) {
     try {
         const result = await (0, session_ops_1.getSessionStatus)();
+        let page = null;
+        if (result.alive) {
+            try {
+                page = await (0, session_ops_1.getPageInfo)();
+            }
+            catch {
+                page = null;
+            }
+        }
         if (output.json) {
-            console.log(JSON.stringify(result, null, 2));
+            console.log(JSON.stringify({ ...result, page }, null, 2));
             return;
         }
         if (!result.config) {
@@ -198,7 +307,42 @@ async function handleStatus(output) {
         console.log(`Status: ${result.alive ? 'alive' : 'dead'}`);
         if (result.alive) {
             console.log(`Browser: ${result.config.browser.browserName}`);
+            if (page) {
+                console.log(`URL: ${page.url}`);
+                console.log(`Title: ${page.title}`);
+                console.log(`Frames: ${page.frames}`);
+            }
+        }
+    }
+    catch (e) {
+        output.error(e instanceof Error ? e.message : String(e));
+    }
+}
+function handleStateCheck(command, args, output) {
+    try {
+        const cmdArgs = splitArgs(args);
+        const parsed = (0, command_1.parseCommand)(command, cmdArgs);
+        const file = path_1.default.resolve(parsed.state ??
+            path_1.default.join(os_1.default.homedir(), '.cssprobe-cli', 'states', 'session.json'));
+        if (!fs_1.default.existsSync(file))
+            output.error(`State file not found: ${file}`);
+        const raw = JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+        if (!raw || !Array.isArray(raw.cookies))
+            throw new Error(`Invalid state file (missing cookies): ${file}`);
+        const report = (0, state_check_1.analyzeState)(raw, parsed.url);
+        if (output.json) {
+            console.log(JSON.stringify({ file, ...report }, null, 2));
+            return;
+        }
+        console.log(`State: ${file}`);
+        console.log(`Cookies: ${report.cookies} (${report.sessionCookies} session)`);
+        console.log(`Domains: ${report.domains.join(', ') || '(none)'}`);
+        if (report.targetMatches !== null) {
+            console.log(`Target match: ${report.targetMatches ? 'yes' : 'no'}`);
         }
+        console.log(`Status: ${report.ok ? 'ok' : 'attention'}`);
+        for (const warning of report.warnings)
+            console.log(`Warning: ${warning}`);
     }
     catch (e) {
         output.error(e instanceof Error ? e.message : String(e));
@@ -217,6 +361,13 @@ async function handleRun(command, args, output) {
 async function handleSessionCommand(commandName, command, args, output) {
     try {
         const cmdArgs = splitArgs(args);
+        if (commandName === 'eval' || commandName === 'playwright') {
+            const input = cmdArgs._[1];
+            if (typeof input === 'string') {
+                cmdArgs._ = cmdArgs._.slice();
+                cmdArgs._[1] = (0, input_1.resolveInputArg)(input);
+            }
+        }
         const parsed = (0, command_1.parseCommand)(command, cmdArgs);
         const result = await (0, session_ops_1.runSessionCommand)(commandName, command, parsed, !!args.json);
         // Screenshot: save the base64 data URL to a file and report the path

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

@@ -11,6 +11,8 @@ export interface OpenOptions {
         height: number;
     };
     state?: string;
+    expectUrl?: string;
+    failOnLogin?: boolean;
 }
 export interface OpenResult {
     sessionId: string;
@@ -21,6 +23,12 @@ export interface OpenResult {
         height: number;
     };
 }
+export interface PageInfo {
+    url: string;
+    title: string;
+    frames: number;
+}
+export declare function getPageInfo(): Promise<PageInfo>;
 export declare function openSession(opts: OpenOptions): Promise<OpenResult>;
 export declare function waitForSession(timeoutMs: number): Promise<Session | undefined>;
 export interface CloseResult {

package/dist/cli/session-ops.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.saveScreenshotFile = void 0;
+exports.getPageInfo = getPageInfo;
 exports.openSession = openSession;
 exports.waitForSession = waitForSession;
 exports.closeSession = closeSession;
@@ -8,8 +9,16 @@ exports.getSessionStatus = getSessionStatus;
 exports.buildDaemonArgs = buildDaemonArgs;
 exports.runSessionCommand = runSessionCommand;
 const session_1 = require("../daemon/session");
+const url_guard_1 = require("./url-guard");
 var screenshot_1 = require("../utils/screenshot");
 Object.defineProperty(exports, "saveScreenshotFile", { enumerable: true, get: function () { return screenshot_1.saveScreenshotFile; } });
+async function getPageInfo() {
+    const session = await (0, session_1.loadSession)();
+    if (!session)
+        throw new Error('No active session. Run: cssprobe-cli open <url>');
+    const result = await session.run({ _: ['page-info'] });
+    return JSON.parse(result.text);
+}
 async function openSession(opts) {
     const url = opts.url || 'about:blank';
     const browser = opts.browser || 'chromium';
@@ -24,10 +33,24 @@ async function openSession(opts) {
     if (!session)
         throw new Error('Daemon failed to become ready within 5s. Check the daemon log for errors.');
     await session.run({ _: ['goto', url] });
+    const info = await getPageInfo();
+    const guardError = (() => {
+        if (opts.failOnLogin && (0, url_guard_1.looksLikeLoginUrl)(info.url)) {
+            return `Login required: page redirected to ${info.url}. Refresh the state file or log in manually.`;
+        }
+        if (opts.expectUrl && !(0, url_guard_1.matchesUrlPattern)(opts.expectUrl, info.url)) {
+            return `Expected URL to match ${opts.expectUrl}, got ${info.url}`;
+        }
+        return null;
+    })();
+    if (guardError) {
+        await closeSession();
+        throw new Error(guardError);
+    }
     return {
         sessionId: 'default',
         pid,
-        url,
+        url: info.url,
         viewport: opts.viewport || { width: 1280, height: 720 },
     };
 }

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

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

package/dist/cli/state-check.js

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

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

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

package/dist/cli/url-guard.js

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

package/dist/daemon/daemon.js

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

package/dist/daemon/expect.d.ts

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

package/dist/daemon/expect.js

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

package/dist/daemon/flowRunner.d.ts

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