cssprobe-cli 0.1.2 → 0.2.5

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) {
@@ -110,10 +114,12 @@ async function handleInspect(command, cmdEntry, args, output) {
         }
         const maxNodes = parsed['max-nodes'] || 60;
         const upTo = parsed['up-to'] || 'html';
-        const headed = !!parsed.headed || config.headed;
+        const wait = !!parsed.wait;
+        const headed = !!parsed.headed || config.headed || wait;
         const browser = parsed.browser || config.browser;
         const state = parsed.state || undefined;
         const brief = !!parsed.brief;
+        const layout = !!parsed.layout;
         if (!url)
             output.error('URL is required. Usage: cssprobe-cli inspect <url> [selector]');
         // Auto-detect root selector if not provided
@@ -129,6 +135,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 +158,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 +402,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;