cssprobe-cli 0.1.2 → 0.2.0

package/README.md

@@ -44,9 +44,34 @@ cssprobe-cli login https://mysite.com
 
 # Then inspect with state
 cssprobe-cli inspect https://mysite.com/page ".target" --state ~/.cssprobe-cli/states/mysite.json
+
+# Wait for user interaction before collecting (e.g. click a button to open a dialog)
+cssprobe-cli inspect https://mysite.com/page ".dialog" --state ~/.cssprobe-cli/states/mysite.json --wait
+```
+
+### 3. Interactive Mode
+
+```bash
+# Open browser and inspect interactively (REPL mode)
+cssprobe-cli interactive https://mysite.com --state ~/.cssprobe-cli/states/mysite.json
+```
+
+Runtime commands:
+```
+inspect> tree .dialog-A               # DOM tree
+inspect> layout .sidebar-B            # ASCII layout diagram
+inspect> sketch .content              # Tree sketch (issues only)
+inspect> findings .modal              # Findings only
+inspect> json .dialog-A               # JSON output
+inspect> report .dialog-A             # Full report
+inspect> .dialog-A                    # Shorthand for report
+inspect> navigate https://other.com   # Navigate to new URL
+inspect> depth 10                     # Set depth
+inspect> help                         # Show help
+inspect> quit                         # Exit
 ```
 
-### 3. JSON Output
+### 4. JSON Output
 
 ```bash
 cssprobe-cli inspect https://getbootstrap.com/docs/5.3/examples/checkout body --json
@@ -61,6 +86,8 @@ cssprobe-cli inspect https://getbootstrap.com/docs/5.3/examples/checkout body --
 |------|--------|----------|
 | (default) | Markdown report with ancestor chain, DOM tree, findings | Terminal viewing |
 | `--json` | Structured JSON with snapshot, findings, confidence summary | Scripts, `jq` pipes, AI agent consumption |
+| `--brief` | Compact output: tree sketch + warnings/errors only | Quick overview |
+| `--layout` | ASCII layout diagram showing element positions and sizes | Visual layout inspection |
 
 ---
 
@@ -70,6 +97,7 @@ cssprobe-cli inspect https://getbootstrap.com/docs/5.3/examples/checkout body --
 
 ```bash
 cssprobe-cli inspect <url> [selector]    # Inspect CSS layout
+cssprobe-cli interactive <url>           # Interactive REPL mode
 cssprobe-cli login <url>                 # Interactive login, save state
 cssprobe-cli state-import [file]         # Import cookies from Netscape format
 ```
@@ -112,6 +140,8 @@ Options:
   --up-to <tag>               Ancestor stop tag (default html)
   --state <file>              Load saved state (cookies + localStorage)
   --brief                     Compact output: tree sketch + warnings/errors only
+  --layout                    ASCII layout diagram showing element positions and sizes
+  --wait                      Wait for user interaction before collecting (implies --headed)
 ```
 
 ---

package/dist/browser/launcher.d.ts

@@ -15,6 +15,10 @@ export declare class BrowserLauncher {
     collect(cfg: CollectConfig): Promise<Snapshot>;
     /** Measure the DOM tree depth from a root selector to the deepest leaf. */
     measureDepth(selector: string): Promise<number>;
+    /** Wait for user to interact with the page. Press Enter to continue. */
+    waitForUser(): Promise<void>;
+    /** Navigate to a new URL in the existing page. */
+    navigate(url: string): Promise<void>;
     /** Scan the page for likely root elements (modals, dialogs, scroll containers). */
     autoDetectRoot(): Promise<string[]>;
     /**

package/dist/browser/launcher.js

@@ -125,6 +125,33 @@ class BrowserLauncher {
             return maxDepth;
         }, selector);
     }
+    /** Wait for user to interact with the page. Press Enter to continue. */
+    async waitForUser() {
+        console.error('');
+        console.error('  Browser is open. Perform your actions (login, click buttons, open dialogs, etc.).');
+        console.error('  Press Enter here when ready to inspect...');
+        console.error('');
+        await new Promise(resolve => {
+            process.stdin.once('data', () => resolve());
+        });
+    }
+    /** Navigate to a new URL in the existing page. */
+    async navigate(url) {
+        if (!this.page)
+            throw new Error('Browser not opened. Call open() first.');
+        if (url.startsWith('http://') || url.startsWith('https://')) {
+            await this.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60000 });
+        }
+        else if (url.startsWith('file://')) {
+            await this.page.goto(url, { waitUntil: 'load', timeout: 30000 });
+        }
+        else {
+            const resolved = path_1.default.resolve(url);
+            if (!fs_1.default.existsSync(resolved))
+                throw new Error(`File not found: ${resolved}`);
+            await this.page.goto(`file://${resolved}`, { waitUntil: 'load', timeout: 30000 });
+        }
+    }
     /** Scan the page for likely root elements (modals, dialogs, scroll containers). */
     async autoDetectRoot() {
         if (!this.page)

package/dist/cli/commands.d.ts

@@ -22,6 +22,8 @@ export declare const inspectCommand: import("./command").CommandSchema<z.ZodObje
     'up-to': z.ZodOptional<z.ZodString>;
     state: z.ZodOptional<z.ZodString>;
     brief: z.ZodOptional<z.ZodBoolean>;
+    layout: z.ZodOptional<z.ZodBoolean>;
+    wait: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     json?: boolean | undefined;
     headed?: boolean | undefined;
@@ -32,6 +34,8 @@ export declare const inspectCommand: import("./command").CommandSchema<z.ZodObje
     'up-to'?: string | undefined;
     state?: string | undefined;
     brief?: boolean | undefined;
+    layout?: boolean | undefined;
+    wait?: boolean | undefined;
 }, {
     json?: boolean | undefined;
     headed?: boolean | undefined;
@@ -42,4 +46,6 @@ export declare const inspectCommand: import("./command").CommandSchema<z.ZodObje
     'up-to'?: string | undefined;
     state?: string | undefined;
     brief?: boolean | undefined;
+    layout?: boolean | undefined;
+    wait?: boolean | undefined;
 }>>;

package/dist/cli/commands.js

@@ -63,6 +63,8 @@ const inspect = (0, command_1.declareCommand)({
         'up-to': z.string().optional().describe('ancestor stop tag (default html)'),
         state: z.string().optional().describe('path to saved state file (cookies + localStorage)'),
         brief: z.boolean().optional().describe('compact output: tree sketch + warnings/errors only'),
+        layout: z.boolean().optional().describe('ASCII layout diagram showing element positions and sizes'),
+        wait: z.boolean().optional().describe('wait for user interaction before collecting (implies --headed)'),
     }),
 });
 const login = (0, command_1.declareCommand)({
@@ -157,8 +159,21 @@ const stateImport = (0, command_1.declareCommand)({
         merge: z.string().optional().describe('existing state file to merge into'),
     }),
 });
+const interactive = (0, command_1.declareCommand)({
+    name: 'interactive',
+    category: 'core',
+    description: 'Open browser and inspect interactively (REPL mode)',
+    args: z.object({
+        url: urlArg,
+    }),
+    options: z.object({
+        browser: z.enum(['chromium', 'firefox', 'webkit']).optional().describe('browser engine (default chromium)'),
+        state: z.string().optional().describe('path to saved state file (cookies + localStorage)'),
+        depth: numberArg.optional().describe('DOM tree depth (default: auto, max 20)'),
+    }),
+});
 const commandsArray = [
-    inspect, login, stateImport,
+    inspect, login, stateImport, interactive,
     configShow, configSet, configList, configUse, configNew, configPath,
     skillInstall, skillUninstall,
 ];

package/dist/cli/program.js

@@ -47,6 +47,10 @@ async function program() {
         await handleStateImport(command, cmdEntry, rawArgs, output);
         return;
     }
+    if (commandName === 'interactive') {
+        await handleInteractive(command, cmdEntry, rawArgs, output);
+        return;
+    }
     await handleInspect(command, cmdEntry, rawArgs, output);
 }
 function parseArgs(help) {
@@ -114,6 +118,12 @@ async function handleInspect(command, cmdEntry, args, output) {
         const browser = parsed.browser || config.browser;
         const state = parsed.state || undefined;
         const brief = !!parsed.brief;
+        const layout = !!parsed.layout;
+        const wait = !!parsed.wait;
+        // --wait implies --headed
+        if (wait) {
+            args.headed = true;
+        }
         if (!url)
             output.error('URL is required. Usage: cssprobe-cli inspect <url> [selector]');
         // Auto-detect root selector if not provided
@@ -129,6 +139,10 @@ async function handleInspect(command, cmdEntry, args, output) {
         }
         const launcher = new launcher_1.BrowserLauncher({ browser, headed, state });
         await launcher.open(url);
+        // Wait for user interaction if --wait
+        if (wait) {
+            await launcher.waitForUser();
+        }
         // Resolve auto depth
         if (depth === 0) {
             const measured = await launcher.measureDepth(rootSelector);
@@ -148,7 +162,7 @@ async function handleInspect(command, cmdEntry, args, output) {
             console.log(output.format((0, renderer_1.renderJSON)(snapshot, findings, brief)));
         }
         else {
-            console.log((0, renderer_1.renderMarkdown)(snapshot, findings, brief));
+            console.log((0, renderer_1.renderMarkdown)(snapshot, findings, brief, layout));
         }
     }
     catch (e) {
@@ -392,4 +406,274 @@ async function handleStateImport(command, cmdEntry, args, output) {
         output.error(e instanceof Error ? e.message : String(e));
     }
 }
+// ── interactive ──
+const REPL_COMMANDS = {
+    tree: '<selector>           Show DOM tree',
+    layout: '<selector>           Show ASCII layout diagram',
+    sketch: '<selector>           Show tree sketch (issues only)',
+    findings: '<selector>           Show findings only',
+    json: '<selector>           Show JSON output',
+    report: '<selector>           Show full report',
+    navigate: '<url>                Navigate to a new URL',
+    depth: '<n>                  Set depth (default: auto)',
+    help: '                     Show this help',
+    quit: '                     Close browser and exit',
+};
+async function handleInteractive(command, cmdEntry, args, _output) {
+    const cmdArgs = splitArgs(args);
+    const parsed = (0, command_1.parseCommand)(command, cmdArgs);
+    const url = parsed.url;
+    const browser = parsed.browser || 'chromium';
+    const state = parsed.state || undefined;
+    const depthRaw = parsed.depth;
+    let depth = depthRaw === 'auto' || depthRaw === undefined ? 0 : Number(depthRaw);
+    if (!url) {
+        console.error('Error: URL is required. Usage: cssprobe-cli interactive <url>');
+        process.exit(1);
+    }
+    const launcher = new launcher_1.BrowserLauncher({ browser, headed: true, state });
+    await launcher.open(url);
+    let currentUrl = url;
+    // Resolve auto depth
+    if (depth === 0) {
+        try {
+            const candidates = await launcher.autoDetectRoot();
+            const selector = candidates[0] || 'body';
+            const measured = await launcher.measureDepth(selector);
+            depth = Math.min(measured, 20) || 6;
+            console.error(`Auto-detected depth: ${measured} (using ${depth})`);
+        }
+        catch {
+            depth = 6;
+        }
+    }
+    console.error('');
+    console.error(`Browser opened at ${currentUrl}`);
+    console.error("Type 'help' for available commands, 'quit' to exit.");
+    console.error('');
+    const rl = require('readline').createInterface({
+        input: process.stdin,
+        output: process.stderr,
+        prompt: 'inspect> ',
+    });
+    rl.prompt();
+    rl.on('line', async (line) => {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            rl.prompt();
+            return;
+        }
+        // Parse: command [selector] [--options]
+        const parts = trimmed.split(/\s+/);
+        const cmd = parts[0];
+        const rest = parts.slice(1);
+        try {
+            switch (cmd) {
+                case 'help': {
+                    console.error('');
+                    console.error('Commands:');
+                    for (const [name, desc] of Object.entries(REPL_COMMANDS)) {
+                        console.error(`  ${name.padEnd(12)} ${desc}`);
+                    }
+                    console.error('');
+                    break;
+                }
+                case 'quit':
+                case 'exit': {
+                    await launcher.close();
+                    console.error('Browser closed.');
+                    rl.close();
+                    process.exit(0);
+                }
+                case 'navigate': {
+                    const newUrl = rest[0];
+                    if (!newUrl) {
+                        console.error('Usage: navigate <url>');
+                        break;
+                    }
+                    await launcher.navigate(newUrl);
+                    currentUrl = newUrl;
+                    console.error(`Navigated to ${currentUrl}`);
+                    break;
+                }
+                case 'depth': {
+                    const n = parseInt(rest[0], 10);
+                    if (isNaN(n) || n < 1) {
+                        console.error('Usage: depth <n>');
+                        break;
+                    }
+                    depth = Math.min(n, 20);
+                    console.error(`Depth set to ${depth}`);
+                    break;
+                }
+                case 'tree':
+                case 'layout':
+                case 'sketch':
+                case 'findings':
+                case 'json':
+                case 'report': {
+                    // Parse selector + options from remaining args
+                    let selector = '';
+                    let useBrief = false;
+                    let useLayout = false;
+                    let useJson = false;
+                    for (const arg of rest) {
+                        if (arg === '--brief')
+                            useBrief = true;
+                        else if (arg === '--layout')
+                            useLayout = true;
+                        else if (arg === '--json')
+                            useJson = true;
+                        else if (!arg.startsWith('-') && !selector)
+                            selector = arg;
+                    }
+                    // Command-specific defaults
+                    if (cmd === 'layout')
+                        useLayout = true;
+                    if (cmd === 'sketch')
+                        useBrief = true;
+                    if (cmd === 'json')
+                        useJson = true;
+                    if (!selector) {
+                        console.error('Usage: ' + cmd + ' <selector> [--brief] [--layout] [--json]');
+                        break;
+                    }
+                    // Measure depth if needed
+                    let useDepth = depth;
+                    if (useDepth === 0) {
+                        try {
+                            const measured = await launcher.measureDepth(selector);
+                            useDepth = Math.min(measured, 20) || 6;
+                        }
+                        catch {
+                            useDepth = 6;
+                        }
+                    }
+                    const collectCfg = {
+                        rootSelector: selector,
+                        upTo: 'html',
+                        downDepth: useDepth,
+                        maxNodes: 60,
+                    };
+                    const snapshot = await launcher.collect(collectCfg);
+                    if (snapshot.error) {
+                        console.error(`Error: ${snapshot.error}`);
+                        if (snapshot.candidates?.length) {
+                            console.error(`Similar nodes: ${snapshot.candidates.join(', ')}`);
+                        }
+                        break;
+                    }
+                    const findings = (0, analyzer_1.analyze)(snapshot);
+                    if (cmd === 'findings') {
+                        // Only show findings section
+                        const important = findings.filter(f => f.level === 'warning' || f.level === 'error');
+                        if (important.length === 0) {
+                            console.log('No warnings or errors');
+                        }
+                        else {
+                            for (const f of important) {
+                                const icon = f.level === 'error' ? '\u26A0' : '\u26A0';
+                                console.log(`- ${icon} ${f.message} [${f.confidence}]${f.location ? ` @ ${f.location}` : ''}`);
+                            }
+                        }
+                    }
+                    else if (useJson) {
+                        console.log(JSON.stringify((0, renderer_1.renderJSON)(snapshot, findings, useBrief), null, 2));
+                    }
+                    else if (cmd === 'tree') {
+                        // Only DOM tree
+                        const lines = [];
+                        lines.push(`## DOM tree (${snapshot.downDepth} levels deep)`);
+                        lines.push('```');
+                        // Inline renderNode
+                        const renderNodeLocal = (node, indent) => {
+                            if (!node)
+                                return;
+                            const cls = node.classes?.length ? `.${node.classes.join('.')}` : '';
+                            const id = node.id ? `#${node.id}` : '';
+                            const m = node.metrics;
+                            const s = node.shape || {};
+                            const shapeStr = s.role ? `[${s.role} h:${s.heightStrategy} w:${s.widthStrategy}]` : '';
+                            const flag = [];
+                            if (node.flags?.overflowsParent)
+                                flag.push('\u26A0parent-overflow');
+                            if (node.flags?.overflowsViewport)
+                                flag.push('\u26A0viewport-overflow');
+                            if (m?.clientHeight === 0 && m?.offsetHeight === 0)
+                                flag.push('\u26A0collapsed');
+                            lines.push(`${'  '.repeat(indent)}<${node.tag}${id}${cls}> ${shapeStr} [${node.props?.position},${node.props?.display}] rect(${m?.rect?.width}\u00D7${m?.rect?.height})${flag.length ? ' ' + flag.join(' ') : ''}`);
+                            for (const child of node.children || [])
+                                renderNodeLocal(child, indent + 1);
+                        };
+                        renderNodeLocal(snapshot.tree, 0);
+                        lines.push('```');
+                        console.log(lines.join('\n'));
+                    }
+                    else {
+                        console.log((0, renderer_1.renderMarkdown)(snapshot, findings, useBrief, useLayout));
+                    }
+                    break;
+                }
+                default: {
+                    // Try as a direct selector (shorthand for 'report <selector>')
+                    if (!cmd.startsWith('-')) {
+                        const selector = cmd;
+                        let useBrief = false;
+                        let useLayout = false;
+                        for (const arg of rest) {
+                            if (arg === '--brief')
+                                useBrief = true;
+                            if (arg === '--layout')
+                                useLayout = true;
+                        }
+                        let useDepth = depth;
+                        if (useDepth === 0) {
+                            try {
+                                const measured = await launcher.measureDepth(selector);
+                                useDepth = Math.min(measured, 20) || 6;
+                            }
+                            catch {
+                                useDepth = 6;
+                            }
+                        }
+                        const collectCfg = {
+                            rootSelector: selector,
+                            upTo: 'html',
+                            downDepth: useDepth,
+                            maxNodes: 60,
+                        };
+                        const snapshot = await launcher.collect(collectCfg);
+                        if (snapshot.error) {
+                            console.error(`Error: ${snapshot.error}`);
+                            if (snapshot.candidates?.length) {
+                                console.error(`Similar nodes: ${snapshot.candidates.join(', ')}`);
+                            }
+                        }
+                        else {
+                            const findings = (0, analyzer_1.analyze)(snapshot);
+                            console.log((0, renderer_1.renderMarkdown)(snapshot, findings, useBrief, useLayout));
+                        }
+                    }
+                    else {
+                        console.error(`Unknown command: ${cmd}. Type 'help' for available commands.`);
+                    }
+                }
+            }
+        }
+        catch (e) {
+            console.error(`Error: ${e.message || e}`);
+        }
+        rl.prompt();
+    });
+    rl.on('close', async () => {
+        await launcher.close().catch(() => { });
+        process.exit(0);
+    });
+    // Handle SIGINT gracefully
+    process.on('SIGINT', async () => {
+        console.error('\nClosing browser...');
+        await launcher.close().catch(() => { });
+        process.exit(0);
+    });
+}
 //# sourceMappingURL=program.js.map

package/dist/engine/renderer.d.ts

@@ -1,3 +1,3 @@
 import type { Snapshot, Finding } from './types';
-export declare function renderMarkdown(snapshot: Snapshot, findings: Finding[], brief?: boolean): string;
+export declare function renderMarkdown(snapshot: Snapshot, findings: Finding[], brief?: boolean, layout?: boolean): string;
 export declare function renderJSON(snapshot: Snapshot, findings: Finding[], brief?: boolean): object;

package/dist/engine/renderer.js

@@ -136,6 +136,82 @@ function renderSketch(tree, findings) {
     }
     return renderSketchNode(sketchRoot, '', true);
 }
+// ─── Layout diagram (ASCII box layout) ───
+const BOX = { tl: '\u250C', tr: '\u2510', bl: '\u2514', br: '\u2518', h: '\u2500', v: '\u2502' };
+function renderLayout(snapshot, findings) {
+    if (!snapshot.tree)
+        return ['(empty tree)'];
+    const vpW = snapshot.viewport.width;
+    const termWidth = Math.min(Math.max(process.stdout?.columns || 80, 60), 120);
+    const indentUnit = 2;
+    const maxDepth = 8;
+    const boxPad = 4; // '│ ' prefix per depth level
+    const issueLocations = new Set();
+    for (const f of findings) {
+        if (f.location && (f.level === 'warning' || f.level === 'error'))
+            issueLocations.add(f.location);
+    }
+    function boxCharW(nodeW, depth) {
+        const usedIndent = depth * indentUnit;
+        const available = termWidth - usedIndent - boxPad;
+        const ratio = nodeW / vpW;
+        return Math.max(Math.round(available * ratio), 14);
+    }
+    const lines = [];
+    function renderEl(node, depth, parentW) {
+        if (depth > maxDepth) {
+            lines.push('  '.repeat(depth) + '... (depth limit)');
+            return;
+        }
+        const m = node.metrics.rect;
+        // Skip zero-size elements (SVG symbols, hidden elements)
+        if (m.width < 1 && m.height < 1 && node.children.length > 0) {
+            for (const child of node.children)
+                renderEl(child, depth, parentW);
+            return;
+        }
+        if (m.width < 1 && m.height < 1)
+            return;
+        const label = nodeLabel(node);
+        const hasIssue = issueLocations.has(label);
+        const dimStr = `${Math.round(m.width)}\u00D7${Math.round(m.height)}`;
+        const charW = boxCharW(m.width, depth);
+        const innerW = charW - 2;
+        const indent = '  '.repeat(depth);
+        const issueMark = hasIssue ? ' \u26A0' : '';
+        if (innerW < 3) {
+            // Too narrow for a proper box
+            lines.push(`${indent}${BOX.v} ${label.slice(0, charW - 3)}... ${dimStr}`);
+            for (const child of node.children)
+                renderEl(child, depth + 1, m.width);
+            return;
+        }
+        // Top border: ┌─ label ────────┐ WxH
+        const labelPart = ` ${label} `;
+        const dimPart = ` ${dimStr} `;
+        const topFillLen = Math.max(0, innerW - labelPart.length);
+        lines.push(`${indent}${BOX.tl}${BOX.h}${labelPart}${BOX.h.repeat(topFillLen)}${BOX.tr}${dimPart}${issueMark}`);
+        // Content
+        if (node.children.length === 0) {
+            // Empty box
+            lines.push(`${indent}${BOX.v}${' '.repeat(innerW)}${BOX.v}`);
+        }
+        else {
+            for (const child of node.children)
+                renderEl(child, depth + 1, m.width);
+        }
+        // Bottom border: └───────────────┘
+        lines.push(`${indent}${BOX.bl}${BOX.h.repeat(innerW)}${BOX.br}`);
+    }
+    renderEl(snapshot.tree, 0, vpW);
+    const scaleStr = `${Math.round(vpW / termWidth)}px/char`;
+    const result = [];
+    result.push(`## Layout (${vpW}\u00D7${snapshot.viewport.height} viewport, scale: ${scaleStr})`);
+    result.push('```');
+    result.push(...lines);
+    result.push('```');
+    return result;
+}
 // ─── Findings rendering ───
 const CONF_BADGE = {
     DEFINITE: 'DEFINITE',
@@ -193,7 +269,7 @@ function confidenceSummary(findings) {
     return parts.join(' | ');
 }
 // ─── Markdown ───
-function renderMarkdown(snapshot, findings, brief = false) {
+function renderMarkdown(snapshot, findings, brief = false, layout = false) {
     const lines = [];
     const vp = snapshot.viewport ? `${snapshot.viewport.width}\u00D7${snapshot.viewport.height}` : 'unknown';
     lines.push('# cssprobe-cli report');
@@ -212,6 +288,10 @@ function renderMarkdown(snapshot, findings, brief = false) {
     lines.push('```');
     lines.push(...renderAncestors(snapshot.ancestors));
     lines.push('```');
+    if (layout) {
+        lines.push('');
+        lines.push(...renderLayout(snapshot, findings));
+    }
     if (brief) {
         lines.push('');
         lines.push('## Tree Sketch (issues only)');
@@ -219,7 +299,7 @@ function renderMarkdown(snapshot, findings, brief = false) {
         lines.push(...renderSketch(snapshot.tree, findings));
         lines.push('```');
     }
-    else {
+    else if (!layout) {
         lines.push('');
         lines.push(`## DOM tree (${snapshot.downDepth} levels deep)`);
         lines.push('```');

package/dist/help.json

@@ -1,8 +1,8 @@
 {
-  "global": "Usage: cssprobe-cli <command> [args] [options]\n\n\nInspection:\n  inspect <url> [selector]    inspect the runtime css of a page (layout, scroll, colors, fonts, backgrounds)\n  login <url>                 open browser for interactive login, then save state for later use\n  state-import [file]         import cookies from netscape format file into a playwright state file\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 (teaches agents how to use the 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\nInspection:\n  inspect <url> [selector]    inspect the runtime css of a page (layout, scroll, colors, fonts, backgrounds)\n  login <url>                 open browser for interactive login, then save state for later use\n  state-import [file]         import cookies from netscape format file into a playwright state file\n  interactive <url>           open browser and inspect interactively (repl mode)\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 (teaches agents how to use the 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": {
     "inspect": {
-      "help": "cssprobe-cli inspect <url> [selector]\n\nInspect the runtime CSS of a page (layout, scroll, colors, fonts, backgrounds)\n\nArguments:\n  <url>                       url, file:// path, or local html file path\n  [selector]                  css selector for the root element (auto-detected if omitted)\nOptions:\n  --json                      output structured json instead of markdown\n  --headed                    show the browser window\n  --browser                   browser engine (default chromium)\n  --zoom                      run 1x/0.5x viewport diagnosis\n  --depth                     dom tree depth (default: auto, max 20)\n  --max-nodes                 node count cap (default 60)\n  --up-to                     ancestor stop tag (default html)\n  --state                     path to saved state file (cookies + localstorage)\n  --brief                     compact output: tree sketch + warnings/errors only\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli inspect <url> [selector]\n\nInspect the runtime CSS of a page (layout, scroll, colors, fonts, backgrounds)\n\nArguments:\n  <url>                       url, file:// path, or local html file path\n  [selector]                  css selector for the root element (auto-detected if omitted)\nOptions:\n  --json                      output structured json instead of markdown\n  --headed                    show the browser window\n  --browser                   browser engine (default chromium)\n  --zoom                      run 1x/0.5x viewport diagnosis\n  --depth                     dom tree depth (default: auto, max 20)\n  --max-nodes                 node count cap (default 60)\n  --up-to                     ancestor stop tag (default html)\n  --state                     path to saved state file (cookies + localstorage)\n  --brief                     compact output: tree sketch + warnings/errors only\n  --layout                    ascii layout diagram showing element positions and sizes\n  --wait                      wait for user interaction before collecting (implies --headed)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
         "json": "boolean",
         "headed": "boolean",
@@ -12,7 +12,9 @@
         "max-nodes": "string",
         "up-to": "string",
         "state": "string",
-        "brief": "boolean"
+        "brief": "boolean",
+        "layout": "boolean",
+        "wait": "boolean"
       },
       "args": [
         "url",
@@ -39,6 +41,17 @@
         "file"
       ]
     },
+    "interactive": {
+      "help": "cssprobe-cli interactive <url>\n\nOpen browser and inspect interactively (REPL mode)\n\nArguments:\n  <url>                       url, file:// path, or local html file path\nOptions:\n  --browser                   browser engine (default chromium)\n  --state                     path to saved state file (cookies + localstorage)\n  --depth                     dom tree depth (default: auto, max 20)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "browser": "string",
+        "state": "string",
+        "depth": "string"
+      },
+      "args": [
+        "url"
+      ]
+    },
     "config-show": {
       "help": "cssprobe-cli config-show \n\nShow current configuration\n\nOptions:\n  --profile                   profile name",
       "flags": {
@@ -104,6 +117,8 @@
     "headed",
     "zoom",
     "brief",
+    "layout",
+    "wait",
     "local"
   ]
 }

package/dist/installer/skill-template.js

@@ -96,6 +96,39 @@ function buildSkillMd() {
         'cssprobe-cli state-import new-cookies.txt --merge existing.json --out merged.json',
         BT3,
         '',
+        '## Wait for User Interaction',
+        '',
+        'For pages that require clicking a button or opening a dialog before inspection:',
+        '',
+        BT3 + 'bash',
+        'cssprobe-cli inspect https://mysite.com/page ".dialog" --state ~/.cssprobe-cli/states/mysite.json --wait',
+        '# Browser opens -> perform actions (click, open dialog) -> press Enter -> inspect',
+        BT3,
+        '',
+        '## Interactive Mode (REPL)',
+        '',
+        'For inspecting multiple areas of the same page:',
+        '',
+        BT3 + 'bash',
+        'cssprobe-cli interactive https://mysite.com --state ~/.cssprobe-cli/states/mysite.json',
+        BT3,
+        '',
+        'Runtime commands:',
+        '',
+        BT3,
+        'inspect> tree .dialog-A               # DOM tree',
+        'inspect> layout .sidebar-B            # ASCII layout diagram',
+        'inspect> sketch .content              # Tree sketch (issues only)',
+        'inspect> findings .modal              # Findings only',
+        'inspect> json .dialog-A               # JSON output',
+        'inspect> report .dialog-A             # Full report',
+        'inspect> .dialog-A                    # Shorthand for report',
+        'inspect> navigate https://other.com   # Navigate to new URL',
+        'inspect> depth 10                     # Set depth',
+        'inspect> help                         # Show help',
+        'inspect> quit                         # Exit',
+        BT3,
+        '',
         '## Output Modes',
         '',
         'Always pass ' + BT + '--json' + BT + ' when consuming output programmatically:',
@@ -138,6 +171,9 @@ function buildSkillMd() {
         '  --max-nodes <n>             Node count cap (default 60)',
         '  --up-to <tag>               Ancestor stop tag (default html)',
         '  --state <file>              Load saved state (cookies + localStorage)',
+        '  --brief                     Compact output: tree sketch + warnings/errors only',
+        '  --layout                    ASCII layout diagram showing element positions and sizes',
+        '  --wait                      Wait for user interaction before collecting (implies --headed)',
         BT3,
         '',
         '## state-import: Netscape Cookie Format',

package/docs/guide/installation.md

@@ -125,9 +125,44 @@ cssprobe-cli inspect https://mysite.com/page ".target" --state ~/.cssprobe-cli/s
 cssprobe-cli state-import new-cookies.txt --merge existing-state.json --out updated.json
 ```
 
+### Option D: Wait for User Interaction
+
+For pages that require clicking a button or opening a dialog before inspection:
+
+```bash
+cssprobe-cli inspect https://mysite.com/page ".dialog" --state ~/.cssprobe-cli/states/mysite.json --wait
+# Browser opens -> perform actions (click, open dialog) -> press Enter -> inspect
+```
+
+---
+
+## Step 5: Interactive Mode (REPL)
+
+For inspecting multiple areas of the same page without re-opening the browser:
+
+```bash
+cssprobe-cli interactive https://mysite.com --state ~/.cssprobe-cli/states/mysite.json
+```
+
+Runtime commands:
+
+```
+inspect> tree .dialog-A               # DOM tree
+inspect> layout .sidebar-B            # ASCII layout diagram
+inspect> sketch .content              # Tree sketch (issues only)
+inspect> findings .modal              # Findings only
+inspect> json .dialog-A               # JSON output
+inspect> report .dialog-A             # Full report
+inspect> .dialog-A                    # Shorthand for report
+inspect> navigate https://other.com   # Navigate to new URL
+inspect> depth 10                     # Set depth
+inspect> help                         # Show help
+inspect> quit                         # Exit
+```
+
 ---
 
-## Step 5: Understand the Output
+## Step 6: Understand the Output
 
 ### Markdown Report (default)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssprobe-cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Runtime CSS probe — inspect layout, colors, backgrounds, fonts and more in a live browser. AI agents and shell automation.",
   "keywords": [
     "css",