cssprobe-cli 0.2.0 → 0.2.6

package/README.md

@@ -142,6 +142,7 @@ Options:
   --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)
+  --viewport <WxH>            Viewport size (e.g. 375x812, default 1280x720)
 ```
 
 ---
@@ -189,6 +190,7 @@ The report header shows: `confidence: DEFINITE 8 | INDEFINITE 0 | UNVERIFIABLE 1
 # Set values
 cssprobe-cli config-set browser chromium
 cssprobe-cli config-set depth 8
+cssprobe-cli config-set viewport 375x812
 
 # Show current config
 cssprobe-cli config-show
@@ -206,6 +208,7 @@ Priority: CLI flags > Environment variables > Config file
 --browser       CSSPROBE_BROWSER
 --depth         CSSPROBE_DEPTH
 --headed        CSSPROBE_HEADED
+--viewport      CSSPROBE_VIEWPORT
 -p, --profile   CSSPROBE_PROFILE
 ```
 

package/dist/browser/launcher.d.ts

@@ -4,6 +4,11 @@ export interface LauncherOptions {
     headed?: boolean;
     /** Path to a Playwright storage state file (cookies + localStorage). */
     state?: string;
+    /** Custom viewport size. Defaults to 1280×720. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
 }
 export declare class BrowserLauncher {
     private options;

package/dist/browser/launcher.js

@@ -75,7 +75,8 @@ class BrowserLauncher {
         }
         this.browser = await factory.launch(launchOptions);
         // Load saved state if provided
-        const contextOptions = { viewport: { width: 1280, height: 720 } };
+        const vp = this.options.viewport || { width: 1280, height: 720 };
+        const contextOptions = { viewport: vp };
         if (this.options.state && fs_1.default.existsSync(this.options.state)) {
             contextOptions.storageState = this.options.state;
         }
@@ -212,7 +213,8 @@ class BrowserLauncher {
         if (execPath)
             launchOptions.executablePath = execPath;
         this.browser = await factory.launch(launchOptions);
-        this.context = await this.browser.newContext({ viewport: { width: 1280, height: 720 } });
+        const vp = this.options.viewport || { width: 1280, height: 720 };
+        this.context = await this.browser.newContext({ viewport: vp });
         this.page = await this.context.newPage();
         // Navigate to the target URL
         if (url.startsWith('http://') || url.startsWith('https://')) {

package/dist/cli/commands.d.ts

@@ -24,6 +24,7 @@ export declare const inspectCommand: import("./command").CommandSchema<z.ZodObje
     brief: z.ZodOptional<z.ZodBoolean>;
     layout: z.ZodOptional<z.ZodBoolean>;
     wait: z.ZodOptional<z.ZodBoolean>;
+    viewport: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     json?: boolean | undefined;
     headed?: boolean | undefined;
@@ -36,6 +37,7 @@ export declare const inspectCommand: import("./command").CommandSchema<z.ZodObje
     brief?: boolean | undefined;
     layout?: boolean | undefined;
     wait?: boolean | undefined;
+    viewport?: string | undefined;
 }, {
     json?: boolean | undefined;
     headed?: boolean | undefined;
@@ -48,4 +50,5 @@ export declare const inspectCommand: import("./command").CommandSchema<z.ZodObje
     brief?: boolean | undefined;
     layout?: boolean | undefined;
     wait?: boolean | undefined;
+    viewport?: string | undefined;
 }>>;

package/dist/cli/commands.js

@@ -65,6 +65,7 @@ const inspect = (0, command_1.declareCommand)({
         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)'),
+        viewport: z.string().optional().describe('viewport size as WxH (e.g. 375x812, default 1280x720)'),
     }),
 });
 const login = (0, command_1.declareCommand)({
@@ -93,7 +94,7 @@ const configSet = (0, command_1.declareCommand)({
     category: 'config',
     description: 'Set a configuration value',
     args: z.object({
-        key: z.string().describe('Config key (browser, depth, headed)'),
+        key: z.string().describe('Config key (browser, depth, headed, viewport)'),
         value: z.string().describe('Config value'),
     }),
     options: z.object({
@@ -170,6 +171,7 @@ const interactive = (0, command_1.declareCommand)({
         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)'),
+        viewport: z.string().optional().describe('viewport size as WxH (e.g. 375x812, default 1280x720)'),
     }),
 });
 const commandsArray = [

package/dist/cli/program.js

@@ -114,22 +114,18 @@ 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;
-        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
         let rootSelector = selector;
         if (!rootSelector) {
-            const detected = await autoDetectRoot(url, { browser, headed, state });
+            const detected = await autoDetectRoot(url, { browser, headed, state, viewport: config.viewport });
             if (!detected) {
                 output.error('Could not auto-detect a root element. Please provide a selector: cssprobe-cli inspect <url> <selector>');
                 return;
@@ -137,7 +133,7 @@ async function handleInspect(command, cmdEntry, args, output) {
             rootSelector = detected;
             console.error(`Auto-detected root: ${rootSelector}`);
         }
-        const launcher = new launcher_1.BrowserLauncher({ browser, headed, state });
+        const launcher = new launcher_1.BrowserLauncher({ browser, headed, state, viewport: config.viewport });
         await launcher.open(url);
         // Wait for user interaction if --wait
         if (wait) {
@@ -431,7 +427,8 @@ async function handleInteractive(command, cmdEntry, args, _output) {
         console.error('Error: URL is required. Usage: cssprobe-cli interactive <url>');
         process.exit(1);
     }
-    const launcher = new launcher_1.BrowserLauncher({ browser, headed: true, state });
+    const config = (0, config_1.loadConfig)(args);
+    const launcher = new launcher_1.BrowserLauncher({ browser, headed: true, state, viewport: config.viewport });
     await launcher.open(url);
     let currentUrl = url;
     // Resolve auto depth

package/dist/config/config.d.ts

@@ -3,11 +3,16 @@ export interface ProfileConfig {
     browser?: string;
     depth?: string;
     headed?: string;
+    viewport?: string;
 }
 export interface Config {
     browser: string;
     depth: number;
     headed: boolean;
+    viewport?: {
+        width: number;
+        height: number;
+    };
     output: 'text' | 'json';
     raw: boolean;
 }

package/dist/config/config.js

@@ -77,16 +77,29 @@ function resolveProfile(args) {
     const rc = readRcFile();
     return rc.profiles[name] || {};
 }
+function parseViewport(raw) {
+    const match = raw.match(/^(\d+)\s*[xX*](\d+)$/);
+    if (!match)
+        return undefined;
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    if (width > 0 && height > 0)
+        return { width, height };
+    return undefined;
+}
 function loadConfig(args) {
     const profile = resolveProfile(args);
     const browser = args.browser || process.env.CSSPROBE_BROWSER || profile.browser || 'chromium';
     const depthRaw = args.depth ?? process.env.CSSPROBE_DEPTH ?? profile.depth;
     const depth = depthRaw ? Number(depthRaw) : 6;
     const headed = !!(args.headed || process.env.CSSPROBE_HEADED === 'true' || profile.headed === 'true');
+    const viewportRaw = args.viewport || process.env.CSSPROBE_VIEWPORT || profile.viewport;
+    const viewport = viewportRaw ? parseViewport(viewportRaw) : undefined;
     return {
         browser,
         depth: Number.isNaN(depth) ? 6 : depth,
         headed,
+        viewport,
         output: args.json ? 'json' : 'text',
         raw: !!args.raw,
     };
@@ -96,6 +109,7 @@ function maskConfig(config) {
         browser: config.browser,
         depth: String(config.depth),
         headed: String(config.headed),
+        ...(config.viewport ? { viewport: `${config.viewport.width}x${config.viewport.height}` } : {}),
     };
 }
 function writeRcConfig(key, value, profileName) {

package/dist/engine/renderer.js

@@ -4,277 +4,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderMarkdown = renderMarkdown;
 exports.renderJSON = renderJSON;
-// ─── Node label (matches analyzer.ts nodeLabel) ───
-function nodeLabel(node) {
-    const cls = node.classes.length ? `.${node.classes.join('.')}` : '';
-    const id = node.id ? `#${node.id}` : '';
-    return `${node.tag}${id}${cls}`;
-}
-// ─── Node rendering (DOM tree) ───
-function renderNode(node, indent) {
-    const lines = [];
-    if (!node)
-        return lines;
-    const cls = node.classes.length ? `.${node.classes.join('.')}` : '';
-    const id = node.id ? `#${node.id}` : '';
-    const repeat = node.repeat ? ` \u00D7${node.repeat}` : '';
-    const m = node.metrics;
-    const s = node.shape || {};
-    const flag = [];
-    if (node.flags.overflowsViewport)
-        flag.push('\u26A0viewport-overflow');
-    if (node.flags.overflowsParent)
-        flag.push('\u26A0parent-overflow');
-    if (m.clientHeight === 0 && m.offsetHeight === 0)
-        flag.push('\u26A0collapsed(0px)');
-    if (node.flags.scrollable)
-        flag.push('\u2714scrollable');
-    if (node.flags.hasScrollY && !node.flags.scrollable) {
-        flag.push(`\u26A0overflow(${m.scrollHeight}>${m.clientHeight})but-overflow=${node.props.overflowY}`);
-    }
-    if (node.containingBlockModifiers.length) {
-        flag.push(`CB:${node.containingBlockModifiers.join(' ')}`);
-    }
-    const styleHint = node.inlineStyle ? ` style="${node.inlineStyle}"` : '';
-    const h = node.props.height;
-    const heightStr = h === 'auto' ? `auto\u2192${m.offsetHeight}px` : `${h}`;
-    const w = node.props.width;
-    const widthStr = w === 'auto' ? `auto\u2192${m.clientWidth}px` : `${w}`;
-    const mhStr = node.declared && node.declared['max-height'] ? ` maxH:${node.declared['max-height'].map(x => x.value).join(';')}` : '';
-    const shapeStr = s.role ? `[${s.role}${s.scrollTag ? ' ' + s.scrollTag : ''} h:${s.heightStrategy} w:${s.widthStrategy}]` : '';
-    lines.push(`${'  '.repeat(indent)}<${node.tag}${id}${cls}${styleHint}${repeat}> ${shapeStr} [${node.props.position},${node.props.display},h:${heightStr},w:${widthStr}${mhStr}] rect(${m.rect.width}\u00D7${m.rect.height}) bottom=${m.rectBottom} scroll=${m.clientHeight}/${m.scrollHeight}` +
-        (flag.length ? ` ${flag.join(' ')}` : '') +
-        (node.text ? ` \u300C${node.text.slice(0, 30)}\u300D` : ''));
-    for (const child of node.children) {
-        lines.push(...renderNode(child, indent + 1));
-    }
-    return lines;
-}
-function renderAncestors(chain) {
-    return chain.map(a => {
-        const dh = a.declared && a.declared.height ? a.declared.height.map(x => `${x.selector}\u2192${x.value}`).join('; ') : 'auto';
-        const dw = a.declared && a.declared.width ? a.declared.width.map(x => `${x.selector}\u2192${x.value}`).join('; ') : 'auto';
-        const mh = a.declared && a.declared['max-height'] ? a.declared['max-height'].map(x => `${x.selector}\u2192${x.value}`).join('; ') : null;
-        const maxPart = mh ? ` max-height:${mh}` : '';
-        const s = a.shape || {};
-        const shapeStr = s.role ? `[${s.role}${s.scrollTag ? ' ' + s.scrollTag : ''} h:${s.heightStrategy} w:${s.widthStrategy}]` : '';
-        return `${a.label} ${shapeStr} [${a.props.position},${a.props.display}] h:${dh}${maxPart} w:${dw} \u2192 ${a.metrics.clientWidth}\u00D7${a.metrics.offsetHeight}` +
-            (a.containingBlockModifiers.length ? ` CB:${a.containingBlockModifiers.join(' ')}` : '') +
-            (a.inlineStyle ? ` style="${a.inlineStyle}"` : '');
-    });
-}
-function buildSketchTree(node, issueLabels) {
-    if (!node)
-        return null;
-    const label = nodeLabel(node);
-    const s = node.shape || {};
-    const shapeStr = s.role ? `[${s.role} h:${s.heightStrategy} w:${s.widthStrategy}]` : '';
-    const flags = [];
-    if (node.flags.overflowsParent)
-        flags.push('\u26A0parent-overflow');
-    if (node.flags.overflowsViewport)
-        flags.push('\u26A0viewport-overflow');
-    if (node.metrics.clientHeight === 0 && node.metrics.offsetHeight === 0)
-        flags.push('\u26A0collapsed');
-    if (node.flags.scrollable)
-        flags.push('\u2714scrollable');
-    if (node.containingBlockModifiers.length)
-        flags.push(`CB:${node.containingBlockModifiers.join(' ')}`);
-    const hasIssue = issueLabels.has(label) || flags.length > 0;
-    const children = [];
-    let omitted = 0;
-    for (const child of node.children) {
-        const sketchChild = buildSketchTree(child, issueLabels);
-        if (!sketchChild)
-            continue;
-        if (sketchChild.hasIssue || hasDescendantIssue(sketchChild)) {
-            children.push(sketchChild);
-        }
-        else {
-            omitted++;
-        }
-    }
-    return { label, shape: shapeStr, flags, children, hasIssue, omitted };
-}
-function hasDescendantIssue(node) {
-    if (node.hasIssue)
-        return true;
-    return node.children.some(c => hasDescendantIssue(c));
-}
-function renderSketchNode(node, prefix, isLast) {
-    const lines = [];
-    const connector = isLast ? '\u2514\u2500 ' : '\u251C\u2500 ';
-    const flagStr = node.flags.length ? ` ${node.flags.join(' ')}` : '';
-    const issueMark = node.hasIssue && node.flags.length === 0 ? ' \u26A0' : '';
-    lines.push(`${prefix}${connector}${node.label} ${node.shape}${flagStr}${issueMark}`);
-    const childPrefix = prefix + (isLast ? '   ' : '\u2502  ');
-    const totalChildren = node.children.length + (node.omitted > 0 ? 1 : 0);
-    for (let i = 0; i < node.children.length; i++) {
-        lines.push(...renderSketchNode(node.children[i], childPrefix, i === totalChildren - 1));
-    }
-    if (node.omitted > 0) {
-        const omConnector = '\u2514\u2500 ';
-        lines.push(`${childPrefix}${omConnector}... (${node.omitted} subtrees omitted)`);
-    }
-    return lines;
-}
-function renderSketch(tree, findings) {
-    if (!tree)
-        return ['(empty tree)'];
-    const issueLabels = new Set();
-    for (const f of findings) {
-        if (f.level === 'warning' || f.level === 'error') {
-            if (f.location)
-                issueLabels.add(f.location);
-        }
-    }
-    const sketchRoot = buildSketchTree(tree, issueLabels);
-    if (!sketchRoot)
-        return ['(empty tree)'];
-    if (!hasDescendantIssue(sketchRoot) && !sketchRoot.hasIssue) {
-        return [`${sketchRoot.label} ${sketchRoot.shape} (no issues found in tree)`];
-    }
-    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',
-    INDEFINITE: 'INDEFINITE',
-    UNVERIFIABLE: 'UNVERIFIABLE',
-};
-function renderFindings(findings) {
-    const lines = [];
-    lines.push('## Findings');
-    if (findings.length === 0) {
-        lines.push('- 无异常发现');
-        return lines;
-    }
-    for (const f of findings) {
-        const badge = `[${CONF_BADGE[f.confidence]}]`;
-        const loc = f.location ? ` @ ${f.location}` : '';
-        lines.push(`- ${f.level === 'error' ? '\u26A0' : f.level === 'warning' ? '\u26A0' : '\u2714'} ${f.message} ${badge}${loc}`);
-        for (const ev of f.evidence.slice(0, 3)) {
-            if (ev.type === 'computed') {
-                lines.push(`    - computed ${ev.property}: ${ev.value}`);
-            }
-            else if (ev.type === 'declared') {
-                lines.push(`    - declared ${ev.property}: ${ev.value} (${ev.source || '?'})${ev.accessible ? '' : ' [inaccessible]'}`);
-            }
-        }
-    }
-    return lines;
-}
-function renderBriefFindings(findings) {
-    const lines = [];
-    lines.push('## Findings');
-    const important = findings.filter(f => f.level === 'warning' || f.level === 'error');
-    if (important.length === 0) {
-        lines.push('- No warnings or errors');
-        return lines;
-    }
-    for (const f of important) {
-        const badge = `[${CONF_BADGE[f.confidence]}]`;
-        const loc = f.location ? ` @ ${f.location}` : '';
-        const icon = f.level === 'error' ? '\u26A0' : '\u26A0';
-        lines.push(`- ${icon} ${f.message} ${badge}${loc}`);
-    }
-    return lines;
-}
-function confidenceSummary(findings) {
-    const counts = findings.reduce((acc, f) => {
-        acc[f.confidence] = (acc[f.confidence] || 0) + 1;
-        return acc;
-    }, {});
-    const parts = [
-        `DEFINITE ${counts.DEFINITE || 0}`,
-        `INDEFINITE ${counts.INDEFINITE || 0}`,
-        `UNVERIFIABLE ${counts.UNVERIFIABLE || 0}`,
-    ];
-    return parts.join(' | ');
-}
+const utils_1 = require("./renderers/utils");
+const dom_tree_1 = require("./renderers/dom-tree");
+const ancestors_1 = require("./renderers/ancestors");
+const sketch_1 = require("./renderers/sketch");
+const layout_1 = require("./renderers/layout");
+const findings_1 = require("./renderers/findings");
 // ─── Markdown ───
 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');
     lines.push(`viewport: ${vp} | root: ${snapshot.rootSelector} | nodes: ${snapshot.nodeCount}`);
-    lines.push(`confidence: ${confidenceSummary(findings)}`);
+    lines.push(`confidence: ${(0, utils_1.confidenceSummary)(findings)}`);
     if (snapshot.error) {
         lines.push('');
         lines.push(`\u26A0 ${snapshot.error}`);
@@ -286,28 +28,28 @@ function renderMarkdown(snapshot, findings, brief = false, layout = false) {
     lines.push('');
     lines.push(`## Ancestor chain (root\u2192${snapshot.upTo})`);
     lines.push('```');
-    lines.push(...renderAncestors(snapshot.ancestors));
+    lines.push(...(0, ancestors_1.renderAncestors)(snapshot.ancestors));
     lines.push('```');
     if (layout) {
         lines.push('');
-        lines.push(...renderLayout(snapshot, findings));
+        lines.push(...(0, layout_1.renderLayout)(snapshot, findings));
     }
     if (brief) {
         lines.push('');
         lines.push('## Tree Sketch (issues only)');
         lines.push('```');
-        lines.push(...renderSketch(snapshot.tree, findings));
+        lines.push(...(0, sketch_1.renderSketch)(snapshot.tree, findings));
         lines.push('```');
     }
     else if (!layout) {
         lines.push('');
         lines.push(`## DOM tree (${snapshot.downDepth} levels deep)`);
         lines.push('```');
-        lines.push(...renderNode(snapshot.tree, 0));
+        lines.push(...(0, dom_tree_1.renderNode)(snapshot.tree, 0));
         lines.push('```');
     }
     lines.push('');
-    lines.push(...(brief ? renderBriefFindings(findings) : renderFindings(findings)));
+    lines.push(...(brief ? (0, findings_1.renderBriefFindings)(findings) : (0, findings_1.renderFindings)(findings)));
     if (snapshot.crossOriginBlocked && snapshot.crossOriginBlocked > 0) {
         lines.push('');
         lines.push('## Cross-origin limitation');

package/dist/engine/renderers/ancestors.d.ts

@@ -0,0 +1,2 @@
+import type { AncestorNode } from '../types';
+export declare function renderAncestors(chain: AncestorNode[]): string[];

package/dist/engine/renderers/ancestors.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderAncestors = renderAncestors;
+function renderAncestors(chain) {
+    return chain.map(a => {
+        const dh = a.declared && a.declared.height ? a.declared.height.map(x => `${x.selector}\u2192${x.value}`).join('; ') : 'auto';
+        const dw = a.declared && a.declared.width ? a.declared.width.map(x => `${x.selector}\u2192${x.value}`).join('; ') : 'auto';
+        const mh = a.declared && a.declared['max-height'] ? a.declared['max-height'].map(x => `${x.selector}\u2192${x.value}`).join('; ') : null;
+        const maxPart = mh ? ` max-height:${mh}` : '';
+        const s = a.shape || {};
+        const shapeStr = s.role ? `[${s.role}${s.scrollTag ? ' ' + s.scrollTag : ''} h:${s.heightStrategy} w:${s.widthStrategy}]` : '';
+        return `${a.label} ${shapeStr} [${a.props.position},${a.props.display}] h:${dh}${maxPart} w:${dw} \u2192 ${a.metrics.clientWidth}\u00D7${a.metrics.offsetHeight}` +
+            (a.containingBlockModifiers.length ? ` CB:${a.containingBlockModifiers.join(' ')}` : '') +
+            (a.inlineStyle ? ` style="${a.inlineStyle}"` : '');
+    });
+}
+//# sourceMappingURL=ancestors.js.map

package/dist/engine/renderers/dom-tree.d.ts

@@ -0,0 +1,2 @@
+import type { TreeNode } from '../types';
+export declare function renderNode(node: TreeNode, indent: number): string[];

package/dist/engine/renderers/dom-tree.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderNode = renderNode;
+function renderNode(node, indent) {
+    const lines = [];
+    if (!node)
+        return lines;
+    const cls = node.classes.length ? `.${node.classes.join('.')}` : '';
+    const id = node.id ? `#${node.id}` : '';
+    const repeat = node.repeat ? ` \u00D7${node.repeat}` : '';
+    const m = node.metrics;
+    const s = node.shape || {};
+    const flag = [];
+    if (node.flags.overflowsViewport)
+        flag.push('\u26A0viewport-overflow');
+    if (node.flags.overflowsParent)
+        flag.push('\u26A0parent-overflow');
+    if (m.clientHeight === 0 && m.offsetHeight === 0)
+        flag.push('\u26A0collapsed(0px)');
+    if (node.flags.scrollable)
+        flag.push('\u2714scrollable');
+    if (node.flags.hasScrollY && !node.flags.scrollable) {
+        flag.push(`\u26A0overflow(${m.scrollHeight}>${m.clientHeight})but-overflow=${node.props.overflowY}`);
+    }
+    if (node.containingBlockModifiers.length) {
+        flag.push(`CB:${node.containingBlockModifiers.join(' ')}`);
+    }
+    const styleHint = node.inlineStyle ? ` style="${node.inlineStyle}"` : '';
+    const h = node.props.height;
+    const heightStr = h === 'auto' ? `auto\u2192${m.offsetHeight}px` : `${h}`;
+    const w = node.props.width;
+    const widthStr = w === 'auto' ? `auto\u2192${m.clientWidth}px` : `${w}`;
+    const mhStr = node.declared && node.declared['max-height'] ? ` maxH:${node.declared['max-height'].map(x => x.value).join(';')}` : '';
+    const shapeStr = s.role ? `[${s.role}${s.scrollTag ? ' ' + s.scrollTag : ''} h:${s.heightStrategy} w:${s.widthStrategy}]` : '';
+    lines.push(`${'  '.repeat(indent)}<${node.tag}${id}${cls}${styleHint}${repeat}> ${shapeStr} [${node.props.position},${node.props.display},h:${heightStr},w:${widthStr}${mhStr}] rect(${m.rect.width}\u00D7${m.rect.height}) bottom=${m.rectBottom} scroll=${m.clientHeight}/${m.scrollHeight}` +
+        (flag.length ? ` ${flag.join(' ')}` : '') +
+        (node.text ? ` \u300C${node.text.slice(0, 30)}\u300D` : ''));
+    for (const child of node.children) {
+        lines.push(...renderNode(child, indent + 1));
+    }
+    return lines;
+}
+//# sourceMappingURL=dom-tree.js.map

package/dist/engine/renderers/findings.d.ts

@@ -0,0 +1,3 @@
+import type { Finding } from '../types';
+export declare function renderFindings(findings: Finding[]): string[];
+export declare function renderBriefFindings(findings: Finding[]): string[];

package/dist/engine/renderers/findings.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderFindings = renderFindings;
+exports.renderBriefFindings = renderBriefFindings;
+const utils_1 = require("./utils");
+function renderFindings(findings) {
+    const lines = [];
+    lines.push('## Findings');
+    if (findings.length === 0) {
+        lines.push('- 无异常发现');
+        return lines;
+    }
+    for (const f of findings) {
+        const badge = `[${utils_1.CONF_BADGE[f.confidence]}]`;
+        const loc = f.location ? ` @ ${f.location}` : '';
+        lines.push(`- ${f.level === 'error' ? '\u26A0' : f.level === 'warning' ? '\u26A0' : '\u2714'} ${f.message} ${badge}${loc}`);
+        for (const ev of f.evidence.slice(0, 3)) {
+            if (ev.type === 'computed') {
+                lines.push(`    - computed ${ev.property}: ${ev.value}`);
+            }
+            else if (ev.type === 'declared') {
+                lines.push(`    - declared ${ev.property}: ${ev.value} (${ev.source || '?'})${ev.accessible ? '' : ' [inaccessible]'}`);
+            }
+        }
+    }
+    return lines;
+}
+function renderBriefFindings(findings) {
+    const lines = [];
+    lines.push('## Findings');
+    const important = findings.filter(f => f.level === 'warning' || f.level === 'error');
+    if (important.length === 0) {
+        lines.push('- No warnings or errors');
+        return lines;
+    }
+    for (const f of important) {
+        const badge = `[${utils_1.CONF_BADGE[f.confidence]}]`;
+        const loc = f.location ? ` @ ${f.location}` : '';
+        const icon = f.level === 'error' ? '\u26A0' : '\u26A0';
+        lines.push(`- ${icon} ${f.message} ${badge}${loc}`);
+    }
+    return lines;
+}
+//# sourceMappingURL=findings.js.map

package/dist/engine/renderers/layout.d.ts

@@ -0,0 +1,2 @@
+import type { Snapshot, Finding } from '../types';
+export declare function renderLayout(snapshot: Snapshot, findings: Finding[]): string[];

package/dist/engine/renderers/layout.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderLayout = renderLayout;
+const utils_1 = require("./utils");
+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;
+    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 renderBox(node, charW, depth, flat = false) {
+        const m = node.metrics.rect;
+        const dimStr = `${Math.round(m.width)}\u00D7${Math.round(m.height)}`;
+        const innerW = Math.max(charW - 2, 1);
+        const label = (0, utils_1.smartLabel)(node, innerW - 4);
+        const hasIssue = issueLocations.has(label);
+        const issueMark = hasIssue ? ' \u26A0' : '';
+        const repeat = node.repeat && node.repeat > 1 ? node.repeat : 1;
+        const boxLines = [];
+        if (innerW < 3) {
+            boxLines.push(`${utils_1.BOX.v} ${label.slice(0, Math.max(charW - 3, 0))}... ${dimStr}`);
+            return boxLines;
+        }
+        const labelPart = ` ${label}${repeat > 1 ? ` \u00D7${repeat}` : ''} `;
+        const dimPart = ` ${dimStr} `;
+        const topFillLen = Math.max(0, innerW - labelPart.length - dimPart.length);
+        boxLines.push(`${utils_1.BOX.tl}${utils_1.BOX.h}${labelPart}${utils_1.BOX.h.repeat(topFillLen)}${utils_1.BOX.tr}${dimPart}${issueMark}`);
+        // Children
+        const children = node.children.filter(c => !(c.metrics.rect.width < 1 && c.metrics.rect.height < 1));
+        if (children.length === 0) {
+            boxLines.push(`${utils_1.BOX.v}${' '.repeat(innerW)}${utils_1.BOX.v}`);
+        }
+        else if (flat) {
+            for (const child of children) {
+                const childLabel = (0, utils_1.nodeLabel)(child);
+                const childRepeat = child.repeat && child.repeat > 1 ? ` \u00D7${child.repeat}` : '';
+                const childDim = `${Math.round(child.metrics.rect.width)}\u00D7${Math.round(child.metrics.rect.height)}`;
+                const childLine = ` ${childLabel}${childRepeat} ${childDim} `;
+                if (childLine.length <= innerW) {
+                    boxLines.push(`${utils_1.BOX.v}${childLine}${' '.repeat(innerW - childLine.length)}${utils_1.BOX.v}`);
+                }
+                else {
+                    boxLines.push(`${utils_1.BOX.v}${childLine.slice(0, innerW)}${utils_1.BOX.v}`);
+                }
+            }
+        }
+        else if ((0, utils_1.isMultiColumn)(node)) {
+            // Calculate expanded count (considering repeat)
+            const expandedCount = children.reduce((sum, c) => sum + (c.repeat && c.repeat > 1 ? c.repeat : 1), 0);
+            if (expandedCount > 1) {
+                const isGrid = node.props.display === 'grid' || node.props.display === 'inline-grid';
+                const childLines = renderFlexChildren(children, innerW, depth + 1, m.width, isGrid);
+                for (const cl of childLines) {
+                    boxLines.push(`${utils_1.BOX.v}${cl}${utils_1.BOX.v}`);
+                }
+            }
+            else {
+                for (const child of children) {
+                    const childBox = renderBox(child, Math.min(boxCharW(child.metrics.rect.width, depth + 1), innerW - 2), depth + 1);
+                    for (const cl of childBox) {
+                        const line = ` ${cl}`;
+                        if (line.length <= innerW + 1) {
+                            boxLines.push(`${utils_1.BOX.v}${line}${' '.repeat(Math.max(0, innerW - line.length + 1))}${utils_1.BOX.v}`);
+                        }
+                        else {
+                            boxLines.push(`${utils_1.BOX.v}${line.slice(0, innerW)}${utils_1.BOX.v}`);
+                        }
+                    }
+                }
+            }
+        }
+        else {
+            for (const child of children) {
+                const childBox = renderBox(child, Math.min(boxCharW(child.metrics.rect.width, depth + 1), innerW - 2), depth + 1);
+                for (const cl of childBox) {
+                    const line = ` ${cl}`;
+                    if (line.length <= innerW + 1) {
+                        boxLines.push(`${utils_1.BOX.v}${line}${' '.repeat(Math.max(0, innerW - line.length + 1))}${utils_1.BOX.v}`);
+                    }
+                    else {
+                        boxLines.push(`${utils_1.BOX.v}${line.slice(0, innerW)}${utils_1.BOX.v}`);
+                    }
+                }
+            }
+        }
+        boxLines.push(`${utils_1.BOX.bl}${utils_1.BOX.h.repeat(innerW)}${utils_1.BOX.br}`);
+        return boxLines;
+    }
+    function renderFlexChildren(children, availW, depth, parentPxW, isGrid) {
+        // Expand repeat nodes into multiple copies
+        const expanded = [];
+        for (const child of children) {
+            const repeat = child.repeat && child.repeat > 1 ? child.repeat : 1;
+            for (let r = 0; r < repeat; r++) {
+                expanded.push({ ...child, repeat: 1, children: child.children });
+            }
+        }
+        // For grid: group into rows based on column count
+        let rows;
+        if (isGrid && expanded.length > 1) {
+            const childW = expanded[0].metrics.rect.width;
+            const cols = Math.max(1, Math.floor(parentPxW / childW));
+            rows = [];
+            for (let i = 0; i < expanded.length; i += cols) {
+                rows.push(expanded.slice(i, i + cols));
+            }
+        }
+        else {
+            rows = [expanded];
+        }
+        const allResult = [];
+        for (const row of rows) {
+            const gap = 1;
+            const totalGaps = (row.length - 1) * gap;
+            const minPerChild = 10;
+            const usableW = Math.max(availW - totalGaps, row.length * minPerChild);
+            const childWidths = [];
+            let totalUsed = 0;
+            for (let i = 0; i < row.length; i++) {
+                const ratio = row[i].metrics.rect.width / parentPxW;
+                const w = Math.max(Math.round(usableW * ratio), minPerChild);
+                childWidths.push(w);
+                totalUsed += w;
+            }
+            if (childWidths.length > 0 && usableW > totalUsed) {
+                childWidths[childWidths.length - 1] += usableW - totalUsed;
+            }
+            const childBoxes = [];
+            let maxLines = 0;
+            for (let i = 0; i < row.length; i++) {
+                const box = renderBox(row[i], childWidths[i], depth, true);
+                childBoxes.push(box);
+                if (box.length > maxLines)
+                    maxLines = box.length;
+            }
+            for (let lineIdx = 0; lineIdx < maxLines; lineIdx++) {
+                let merged = '';
+                for (let i = 0; i < childBoxes.length; i++) {
+                    const w = childWidths[i];
+                    if (i > 0)
+                        merged += ' ';
+                    if (lineIdx < childBoxes[i].length) {
+                        const line = childBoxes[i][lineIdx];
+                        if (line.length < w) {
+                            merged += line + ' '.repeat(w - line.length);
+                        }
+                        else {
+                            merged += line.slice(0, w);
+                        }
+                    }
+                    else {
+                        merged += ' '.repeat(w);
+                    }
+                }
+                allResult.push(merged);
+            }
+        }
+        return allResult;
+    }
+    function renderEl(node, depth, parentW) {
+        if (depth > maxDepth) {
+            lines.push('  '.repeat(depth) + '... (depth limit)');
+            return;
+        }
+        const m = node.metrics.rect;
+        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 charW = boxCharW(m.width, depth);
+        const indent = '  '.repeat(depth);
+        const box = renderBox(node, charW, depth);
+        for (const line of box) {
+            lines.push(`${indent}${line}`);
+        }
+    }
+    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;
+}
+//# sourceMappingURL=layout.js.map

package/dist/engine/renderers/sketch.d.ts

@@ -0,0 +1,2 @@
+import type { TreeNode, Finding } from '../types';
+export declare function renderSketch(tree: TreeNode | null, findings: Finding[]): string[];

package/dist/engine/renderers/sketch.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderSketch = renderSketch;
+const utils_1 = require("./utils");
+function buildSketchTree(node, issueLabels) {
+    if (!node)
+        return null;
+    const label = (0, utils_1.nodeLabel)(node);
+    const s = node.shape || {};
+    const shapeStr = s.role ? `[${s.role} h:${s.heightStrategy} w:${s.widthStrategy}]` : '';
+    const flags = [];
+    if (node.flags.overflowsParent)
+        flags.push('\u26A0parent-overflow');
+    if (node.flags.overflowsViewport)
+        flags.push('\u26A0viewport-overflow');
+    if (node.metrics.clientHeight === 0 && node.metrics.offsetHeight === 0)
+        flags.push('\u26A0collapsed');
+    if (node.flags.scrollable)
+        flags.push('\u2714scrollable');
+    if (node.containingBlockModifiers.length)
+        flags.push(`CB:${node.containingBlockModifiers.join(' ')}`);
+    const hasIssue = issueLabels.has(label) || flags.length > 0;
+    const children = [];
+    let omitted = 0;
+    for (const child of node.children) {
+        const sketchChild = buildSketchTree(child, issueLabels);
+        if (!sketchChild)
+            continue;
+        if (sketchChild.hasIssue || hasDescendantIssue(sketchChild)) {
+            children.push(sketchChild);
+        }
+        else {
+            omitted++;
+        }
+    }
+    return { label, shape: shapeStr, flags, children, hasIssue, omitted };
+}
+function hasDescendantIssue(node) {
+    if (node.hasIssue)
+        return true;
+    return node.children.some(c => hasDescendantIssue(c));
+}
+function renderSketchNode(node, prefix, isLast) {
+    const lines = [];
+    const connector = isLast ? '\u2514\u2500 ' : '\u251C\u2500 ';
+    const flagStr = node.flags.length ? ` ${node.flags.join(' ')}` : '';
+    const issueMark = node.hasIssue && node.flags.length === 0 ? ' \u26A0' : '';
+    lines.push(`${prefix}${connector}${node.label} ${node.shape}${flagStr}${issueMark}`);
+    const childPrefix = prefix + (isLast ? '   ' : '\u2502  ');
+    const totalChildren = node.children.length + (node.omitted > 0 ? 1 : 0);
+    for (let i = 0; i < node.children.length; i++) {
+        lines.push(...renderSketchNode(node.children[i], childPrefix, i === totalChildren - 1));
+    }
+    if (node.omitted > 0) {
+        const omConnector = '\u2514\u2500 ';
+        lines.push(`${childPrefix}${omConnector}... (${node.omitted} subtrees omitted)`);
+    }
+    return lines;
+}
+function renderSketch(tree, findings) {
+    if (!tree)
+        return ['(empty tree)'];
+    const issueLabels = new Set();
+    for (const f of findings) {
+        if (f.level === 'warning' || f.level === 'error') {
+            if (f.location)
+                issueLabels.add(f.location);
+        }
+    }
+    const sketchRoot = buildSketchTree(tree, issueLabels);
+    if (!sketchRoot)
+        return ['(empty tree)'];
+    if (!hasDescendantIssue(sketchRoot) && !sketchRoot.hasIssue) {
+        return [`${sketchRoot.label} ${sketchRoot.shape} (no issues found in tree)`];
+    }
+    return renderSketchNode(sketchRoot, '', true);
+}
+//# sourceMappingURL=sketch.js.map

package/dist/engine/renderers/utils.d.ts

@@ -0,0 +1,16 @@
+import type { TreeNode, Confidence } from '../types';
+export declare function nodeLabel(node: TreeNode): string;
+export declare function smartLabel(node: TreeNode, maxLen: number): string;
+export declare function isMultiColumn(node: TreeNode): boolean;
+export declare const BOX: {
+    readonly tl: "┌";
+    readonly tr: "┐";
+    readonly bl: "└";
+    readonly br: "┘";
+    readonly h: "─";
+    readonly v: "│";
+};
+export declare const CONF_BADGE: Record<Confidence, string>;
+export declare function confidenceSummary(findings: {
+    confidence: Confidence;
+}[]): string;

package/dist/engine/renderers/utils.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONF_BADGE = exports.BOX = void 0;
+exports.nodeLabel = nodeLabel;
+exports.smartLabel = smartLabel;
+exports.isMultiColumn = isMultiColumn;
+exports.confidenceSummary = confidenceSummary;
+function nodeLabel(node) {
+    const cls = node.classes.length ? `.${node.classes.join('.')}` : '';
+    const id = node.id ? `#${node.id}` : '';
+    return `${node.tag}${id}${cls}`;
+}
+function smartLabel(node, maxLen) {
+    const full = nodeLabel(node);
+    if (full.length <= maxLen)
+        return full;
+    const id = node.id ? `#${node.id}` : '';
+    const firstCls = node.classes.length > 0 ? `.${node.classes[0]}` : '';
+    const short = `${node.tag}${id}${firstCls}`;
+    if (short.length <= maxLen)
+        return short;
+    const tagId = `${node.tag}${id}`;
+    if (tagId.length <= maxLen)
+        return tagId;
+    if (node.tag.length <= maxLen)
+        return node.tag;
+    return node.tag.slice(0, Math.max(maxLen - 3, 1)) + '...';
+}
+function isMultiColumn(node) {
+    const display = node.props.display;
+    return (node.shape?.role === 'flex-row' ||
+        (display === 'flex' && node.props.flexDirection !== 'column') ||
+        display === 'grid' ||
+        display === 'inline-grid');
+}
+exports.BOX = { tl: '\u250C', tr: '\u2510', bl: '\u2514', br: '\u2518', h: '\u2500', v: '\u2502' };
+exports.CONF_BADGE = {
+    DEFINITE: 'DEFINITE',
+    INDEFINITE: 'INDEFINITE',
+    UNVERIFIABLE: 'UNVERIFIABLE',
+};
+function confidenceSummary(findings) {
+    const counts = findings.reduce((acc, f) => {
+        acc[f.confidence] = (acc[f.confidence] || 0) + 1;
+        return acc;
+    }, {});
+    const parts = [
+        `DEFINITE ${counts.DEFINITE || 0}`,
+        `INDEFINITE ${counts.INDEFINITE || 0}`,
+        `UNVERIFIABLE ${counts.UNVERIFIABLE || 0}`,
+    ];
+    return parts.join(' | ');
+}
+//# sourceMappingURL=utils.js.map

package/dist/help.json

@@ -2,7 +2,7 @@
   "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  --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",
+      "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  --viewport                  viewport size as wxh (e.g. 375x812, default 1280x720)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
         "json": "boolean",
         "headed": "boolean",
@@ -14,7 +14,8 @@
         "state": "string",
         "brief": "boolean",
         "layout": "boolean",
-        "wait": "boolean"
+        "wait": "boolean",
+        "viewport": "string"
       },
       "args": [
         "url",
@@ -42,11 +43,12 @@
       ]
     },
     "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",
+      "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  --viewport                  viewport size as wxh (e.g. 375x812, default 1280x720)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
         "browser": "string",
         "state": "string",
-        "depth": "string"
+        "depth": "string",
+        "viewport": "string"
       },
       "args": [
         "url"
@@ -60,7 +62,7 @@
       "args": []
     },
     "config-set": {
-      "help": "cssprobe-cli config-set <key> <value>\n\nSet a configuration value\n\nArguments:\n  <key>                       config key (browser, depth, headed)\n  <value>                     config value\nOptions:\n  --profile                   profile name",
+      "help": "cssprobe-cli config-set <key> <value>\n\nSet a configuration value\n\nArguments:\n  <key>                       config key (browser, depth, headed, viewport)\n  <value>                     config value\nOptions:\n  --profile                   profile name",
       "flags": {
         "profile": "string"
       },

package/docs/guide/installation.md

@@ -238,12 +238,13 @@ confidence: DEFINITE 8 | INDEFINITE 0 | UNVERIFIABLE 1
 export CSSPROBE_BROWSER=chromium
 export CSSPROBE_DEPTH=6
 export CSSPROBE_HEADED=true
+export CSSPROBE_VIEWPORT=375x812
 export CSSPROBE_PROFILE=default
 ```
 
 Priority (highest to lowest):
-1. CLI flags: `--browser`, `--depth`, `--headed`
-2. Environment variables: `CSSPROBE_BROWSER`, `CSSPROBE_DEPTH`, `CSSPROBE_HEADED`
+1. CLI flags: `--browser`, `--depth`, `--headed`, `--viewport`
+2. Environment variables: `CSSPROBE_BROWSER`, `CSSPROBE_DEPTH`, `CSSPROBE_HEADED`, `CSSPROBE_VIEWPORT`
 3. Config file: `~/.cssprobe-clirc`
 
 ---

package/package.json

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