cssprobe-cli 0.1.0

package/dist/engine/analyzer.js

@@ -0,0 +1,385 @@
+"use strict";
+// Node-side analyzer. Pure functions: Snapshot → Finding[].
+// No browser or filesystem access — directly unit-testable.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyze = analyze;
+// ─── Confidence helpers ───
+/** Pick the winning declared value for a property (inline wins, else first rule). */
+function declaredFor(node, prop) {
+    const arr = node.declared && node.declared[prop];
+    if (!arr || arr.length === 0)
+        return null;
+    return arr.find(d => d.selector === 'inline') || arr[0];
+}
+/**
+ * Confidence of a declaration-backed claim:
+ * - accessible inline/rule value → DEFINITE
+ * - accessible value that is a % (resolves at runtime) → INDEFINITE
+ * - only inaccessible (blocked sheet) or missing declaration → UNVERIFIABLE
+ */
+function confidenceFor(node, props) {
+    let sawAccessible = false;
+    let sawPercent = false;
+    for (const prop of props) {
+        const d = declaredFor(node, prop);
+        if (!d)
+            continue;
+        if (!d.accessible)
+            return 'UNVERIFIABLE';
+        sawAccessible = true;
+        if (d.value.endsWith('%'))
+            sawPercent = true;
+    }
+    if (!sawAccessible)
+        return 'UNVERIFIABLE';
+    return sawPercent ? 'INDEFINITE' : 'DEFINITE';
+}
+function evDeclared(d) {
+    return {
+        type: 'declared',
+        property: 'height',
+        value: d.value,
+        source: `${d.selector} (${d.href || 'inline'})`,
+        accessible: d.accessible,
+    };
+}
+function evComputed(node, prop) {
+    return {
+        type: 'computed',
+        property: prop,
+        value: node.props[prop] ?? '',
+    };
+}
+const ABS_UNIT = /^(0|[1-9]\d*)(\.\d+)?(px|pt|cm|mm|in|vh|vw|vmin|vmax|rem|em)$/;
+function nodeLabel(n) {
+    const cls = (n.classes || []).join('.');
+    return `${n.tag}.${cls}`;
+}
+function makeFinding(partial) {
+    return {
+        id: partial.id,
+        level: partial.level,
+        message: partial.message,
+        confidence: partial.confidence ?? 'UNVERIFIABLE',
+        evidence: partial.evidence ?? [],
+        ...(partial.location ? { location: partial.location } : {}),
+    };
+}
+// ─── Ancestors ───
+function findAncestor(ancestors, predicate) {
+    return ancestors.find(predicate);
+}
+function allAncestorsContentSized(ancestors) {
+    return ancestors.length > 0 && ancestors.every(a => a.shape.heightStrategy === 'content');
+}
+function walkTree(root) {
+    const scrollNodes = [];
+    const constraintNodes = [];
+    const flexPairs = [];
+    const cbNodes = [];
+    const walk = (n, parent) => {
+        if (!n)
+            return;
+        if (n.flags.hasScrollY || n.props.overflowY === 'auto' || n.props.overflowY === 'scroll') {
+            scrollNodes.push(n);
+        }
+        const parentHealthy = parent && parent.metrics.clientHeight > 0;
+        if (n.flags.overflowsParent && !(n.props.overflowY === 'auto' || n.props.overflowY === 'scroll') && parentHealthy) {
+            constraintNodes.push(n);
+        }
+        if (parent && (parent.props.display === 'flex' || parent.props.display === 'inline-flex')) {
+            flexPairs.push({ parent, child: n });
+        }
+        if (n.containingBlockModifiers && n.containingBlockModifiers.length > 0) {
+            cbNodes.push(n);
+        }
+        for (const child of n.children)
+            walk(child, n);
+    };
+    walk(root, null);
+    if (root && root.flags.overflowsParent && !(root.props.overflowY === 'auto' || root.props.overflowY === 'scroll')) {
+        constraintNodes.push(root);
+    }
+    return { scrollNodes, constraintNodes, flexPairs, cbNodes };
+}
+// ─── Analyzers ───
+function analyzeAnchors(snapshot) {
+    const findings = [];
+    const ancestors = snapshot.ancestors;
+    const anchorInfo = ancestors.map(a => {
+        const dh = declaredFor(a, 'height');
+        const mh = declaredFor(a, 'max-height');
+        return {
+            node: a,
+            heightDeclared: dh,
+            maxHeightDeclared: mh,
+            computedHeight: a.props.height,
+            hasAbsolute: !!(dh && ABS_UNIT.test(dh.value)),
+            hasPercent: !!(dh && dh.value.endsWith('%')),
+        };
+    });
+    const anchored = anchorInfo.find(x => x.hasAbsolute);
+    // Main anchor claim
+    const message = anchored
+        ? `chain has absolute-unit height at ${anchored.node.label}: ${anchored.heightDeclared.value}`
+        : 'all heights are % or missing → chain depends on containing block runtime resolution (may resolve to auto)';
+    const anchorConf = anchored
+        ? confidenceFor(anchored.node, ['height'])
+        : (() => {
+            const confs = anchorInfo.map(x => x.heightDeclared ? (x.heightDeclared.accessible ? (x.hasPercent ? 'INDEFINITE' : 'DEFINITE') : 'UNVERIFIABLE') : 'UNVERIFIABLE');
+            return confs.includes('UNVERIFIABLE') ? 'UNVERIFIABLE' : (confs.includes('INDEFINITE') ? 'INDEFINITE' : 'DEFINITE');
+        })();
+    findings.push(makeFinding({
+        id: anchored ? 'anchor-present' : 'anchor-missing',
+        level: anchored ? 'info' : 'warning',
+        message,
+        confidence: anchorConf,
+        evidence: anchorInfo.slice(0, 6).flatMap(x => {
+            const ev = [];
+            if (x.heightDeclared)
+                ev.push({ type: 'declared', property: 'height', value: x.heightDeclared.value, source: `${x.heightDeclared.selector} (${x.heightDeclared.href || 'inline'})`, accessible: x.heightDeclared.accessible });
+            ev.push({ type: 'computed', property: 'height', value: x.computedHeight });
+            return ev;
+        }),
+        location: anchored ? anchored.node.label : ancestors[ancestors.length - 1]?.label,
+    }));
+    // max-height-only cap note
+    const maxOnly = anchorInfo.filter(x => !x.heightDeclared && x.maxHeightDeclared);
+    if (maxOnly.length) {
+        const evs = maxOnly.slice(0, 3).flatMap(x => x.maxHeightDeclared ? [evDeclared(x.maxHeightDeclared)] : []);
+        findings.push(makeFinding({
+            id: 'max-height-only',
+            level: 'warning',
+            message: `these nodes only declare max-height (cap, not anchor) → % children still resolve to auto: ${maxOnly.map(x => x.node.label).join(', ')}`,
+            confidence: 'DEFINITE',
+            evidence: evs,
+            location: maxOnly[0].node.label,
+        }));
+    }
+    return findings;
+}
+function analyzeScroll(snapshot) {
+    const findings = [];
+    const { scrollNodes, constraintNodes } = walkTree(snapshot.tree);
+    for (const n of constraintNodes.slice(0, 8)) {
+        findings.push(makeFinding({
+            id: 'constraint-candidate',
+            level: 'warning',
+            message: `${nodeLabel(n)} overflows parent but is not a scroll container → constraint candidate (flex child min-height:auto or parent height unconstrained)`,
+            confidence: 'DEFINITE',
+            evidence: [
+                evComputed(n, 'overflowY'),
+                { type: 'computed', property: 'scrollHeight', value: String(n.metrics.scrollHeight) },
+                { type: 'computed', property: 'clientHeight', value: String(n.metrics.clientHeight) },
+            ],
+            location: nodeLabel(n),
+        }));
+    }
+    for (const n of scrollNodes) {
+        const isScrollDeclared = n.props.overflowY === 'auto' || n.props.overflowY === 'scroll';
+        // Computed overflow-y is a fact from getComputedStyle — always DEFINITE
+        const conf = 'DEFINITE';
+        let id;
+        let message;
+        let level;
+        if (n.metrics.clientHeight === 0) {
+            id = 'scroll-collapsed';
+            message = `${nodeLabel(n)} height collapsed to 0 → overflow-y:${n.props.overflowY} has no viewport → height chain unconstrained (anchor issue)`;
+            level = 'error';
+        }
+        else if (n.flags.scrollable) {
+            id = 'scrollable';
+            message = `${nodeLabel(n)} scrollable (scrollHeight ${n.metrics.scrollHeight} > clientHeight ${n.metrics.clientHeight})`;
+            level = 'info';
+        }
+        else if (!n.flags.hasScrollY && isScrollDeclared && Math.abs(n.metrics.offsetHeight - n.metrics.scrollHeight) <= 1) {
+            id = 'scroll-content-sized';
+            message = `${nodeLabel(n)} content-sized (${n.metrics.offsetHeight}px, scrollHeight==clientHeight) → overflow-y:auto never triggers → height chain unconstrained (anchor issue)`;
+            level = 'warning';
+        }
+        else if (!n.flags.hasScrollY) {
+            id = 'no-overflow';
+            message = `${nodeLabel(n)} no overflow, no scroll needed`;
+            level = 'info';
+        }
+        else {
+            id = 'overflow-clipped';
+            message = `${nodeLabel(n)} content overflows (${n.metrics.scrollHeight}>${n.metrics.clientHeight}) clipped by overflow=${n.props.overflowY} → height chain unconstrained (anchor issue)`;
+            level = 'warning';
+        }
+        findings.push(makeFinding({
+            id,
+            level,
+            message,
+            confidence: conf,
+            evidence: [
+                evComputed(n, 'overflowY'),
+                { type: 'computed', property: 'scrollHeight', value: String(n.metrics.scrollHeight) },
+                { type: 'computed', property: 'clientHeight', value: String(n.metrics.clientHeight) },
+            ],
+            location: nodeLabel(n),
+        }));
+    }
+    return findings;
+}
+function analyzeFlex(snapshot) {
+    const findings = [];
+    const { flexPairs } = walkTree(snapshot.tree);
+    if (flexPairs.length === 0) {
+        findings.push(makeFinding({
+            id: 'no-flex',
+            level: 'info',
+            message: 'no flex parent-child relationships found in the tree',
+            confidence: 'DEFINITE',
+        }));
+        return findings;
+    }
+    for (const { parent, child } of flexPairs.slice(0, 10)) {
+        const pLabel = nodeLabel(parent);
+        const cLabel = nodeLabel(child);
+        const pDir = parent.props.flexDirection || 'row';
+        const cMinH = parent.props.minHeight;
+        const cMinW = child.props.minWidth;
+        const cFlexGrow = child.props.flexGrow;
+        const cFlexShrink = child.props.flexShrink;
+        if (pDir === 'column') {
+            if ((cMinH === 'auto' || cMinH === '0px') && child.metrics.scrollHeight > child.metrics.clientHeight + 1) {
+                findings.push(makeFinding({
+                    id: 'flex-col-overflow',
+                    level: 'warning',
+                    message: `${cLabel} is flex-col child with min-height:${cMinH} → content (${child.metrics.scrollHeight}px) may overflow parent (${parent.metrics.clientHeight}px)`,
+                    confidence: 'DEFINITE',
+                    evidence: [
+                        evComputed(parent, 'display'),
+                        evComputed(parent, 'flexDirection'),
+                        evComputed(child, 'minHeight'),
+                        { type: 'computed', property: 'scrollHeight', value: String(child.metrics.scrollHeight) },
+                        { type: 'computed', property: 'clientHeight', value: String(child.metrics.clientHeight) },
+                    ],
+                    location: cLabel,
+                }));
+            }
+            if (cFlexGrow === '0' && cFlexShrink === '0' && cMinH === 'auto') {
+                findings.push(makeFinding({
+                    id: 'flex-zero-auto',
+                    level: 'info',
+                    message: `${cLabel}: flex:0 0 auto in ${pLabel}(column) → height is content-driven, not constrained by flex`,
+                    confidence: 'DEFINITE',
+                    evidence: [evComputed(child, 'flexGrow'), evComputed(child, 'flexShrink'), evComputed(child, 'minHeight')],
+                    location: cLabel,
+                }));
+            }
+        }
+        else {
+            if ((cMinW === 'auto' || cMinW === '0px') && child.metrics.scrollWidth > child.metrics.clientWidth + 1) {
+                findings.push(makeFinding({
+                    id: 'flex-row-overflow',
+                    level: 'warning',
+                    message: `${cLabel} is flex-row child with min-width:${cMinW} → content (${child.metrics.scrollWidth}px) may overflow parent`,
+                    confidence: 'DEFINITE',
+                    evidence: [evComputed(parent, 'display'), evComputed(child, 'minWidth'), evComputed(child, 'overflowX')],
+                    location: cLabel,
+                }));
+            }
+        }
+    }
+    return findings;
+}
+function analyzeContainingBlock(snapshot) {
+    const findings = [];
+    const { cbNodes } = walkTree(snapshot.tree);
+    const ancestorsWithCB = snapshot.ancestors.filter(a => a.containingBlockModifiers.length > 0);
+    const allCB = [
+        ...cbNodes.slice(0, 5).map(n => ({ label: nodeLabel(n), mods: n.containingBlockModifiers, node: n })),
+        ...ancestorsWithCB.map(a => ({ label: a.label, mods: a.containingBlockModifiers, node: a })),
+    ];
+    if (allCB.length === 0) {
+        findings.push(makeFinding({
+            id: 'no-cb',
+            level: 'info',
+            message: 'no containing block modifiers found in the tree',
+            confidence: 'DEFINITE',
+        }));
+        return findings;
+    }
+    const hasFixed = snapshot.ancestors.some(a => a.shape.role === 'fixed') ||
+        (snapshot.tree && snapshot.tree.props.position === 'fixed');
+    for (const cb of allCB.slice(0, 5)) {
+        const isRootFixed = cb.node.props.position === 'fixed';
+        findings.push(makeFinding({
+            id: 'cb-modifier',
+            level: isRootFixed ? 'error' : 'info',
+            message: `${cb.label}: CB modifiers: ${cb.mods.join(', ')}${isRootFixed ? ' → fixed/absolute descendants resolve % against this ancestor (containing block hijack)' : ''}`,
+            confidence: 'DEFINITE',
+            evidence: cb.mods.map(m => ({ type: 'declared', property: m.split(':')[0].trim(), value: m.split(':').slice(1).join(':').trim(), accessible: true })),
+            location: cb.label,
+        }));
+    }
+    if (hasFixed && snapshot.ancestors.every(a => a.shape.heightStrategy === 'content')) {
+        findings.push(makeFinding({
+            id: 'fixed-no-anchor',
+            level: 'error',
+            message: 'fixed ancestor + no height anchor → children % resolve to auto → content-sized overflow',
+            confidence: 'DEFINITE',
+        }));
+    }
+    return findings;
+}
+function detectPatterns(snapshot) {
+    const findings = [];
+    const ancestors = snapshot.ancestors;
+    const { scrollNodes } = walkTree(snapshot.tree);
+    const anchored = ancestors.some(a => {
+        const dh = declaredFor(a, 'height');
+        return !!(dh && ABS_UNIT.test(dh.value));
+    });
+    const hasFlexCol = ancestors.some(a => a.shape.role === 'flex-col');
+    const hasFixed = ancestors.some(a => a.shape.role === 'fixed');
+    const scrollableExists = scrollNodes.some(n => n.flags.scrollable);
+    if (hasFixed && !anchored) {
+        findings.push(makeFinding({
+            id: 'pattern-fixed-no-anchor',
+            level: 'info',
+            message: 'Pattern: fixed ancestor + no height anchor → children % resolve to auto → content-sized overflow',
+            confidence: 'DEFINITE',
+        }));
+    }
+    if (hasFlexCol) {
+        const fc = ancestors.find(a => a.shape.role === 'flex-col');
+        findings.push(makeFinding({
+            id: 'pattern-flex-col',
+            level: 'info',
+            message: `Pattern: flex-col at ${fc.label} → children height governed by flex-grow/shrink/min-height`,
+            confidence: 'DEFINITE',
+        }));
+    }
+    if (scrollableExists && !anchored) {
+        findings.push(makeFinding({
+            id: 'pattern-scroll-no-anchor',
+            level: 'info',
+            message: 'Pattern: scroll container exists but no height anchor above → overflow:auto never triggers (content-sized)',
+            confidence: 'DEFINITE',
+        }));
+    }
+    if (allAncestorsContentSized(ancestors)) {
+        findings.push(makeFinding({
+            id: 'pattern-content-sized',
+            level: 'info',
+            message: 'Pattern: all ancestors are content-sized → height entirely depends on content, no constraints propagate',
+            confidence: 'DEFINITE',
+        }));
+    }
+    return findings;
+}
+// ─── Public entry ───
+function analyze(snapshot) {
+    const findings = [
+        ...analyzeAnchors(snapshot),
+        ...analyzeScroll(snapshot),
+        ...analyzeFlex(snapshot),
+        ...analyzeContainingBlock(snapshot),
+        ...detectPatterns(snapshot),
+    ];
+    return findings;
+}
+//# sourceMappingURL=analyzer.js.map

package/dist/engine/collector.d.ts

@@ -0,0 +1,3 @@
+import type { CollectConfig, Snapshot, DeclaredValue, ShapeInfo } from './types';
+export declare function classifyShape(cs: CSSStyleDeclaration, declared: Record<string, DeclaredValue[]>): ShapeInfo;
+export declare function collect(cfg: CollectConfig): Snapshot;

package/dist/engine/collector.js

@@ -0,0 +1,291 @@
+"use strict";
+// Browser-side collector. Bundled by esbuild into an IIFE (global `__cssprobe_cli`),
+// injected into the page via addScriptTag, then invoked with `window.__cssprobe_cli.collect(cfg)`.
+// This module runs entirely in the browser context — no Node imports at runtime.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyShape = classifyShape;
+exports.collect = collect;
+// ─── Declared-value scanning ───
+const WANTED_PROPS = [
+    // layout
+    'height', 'max-height', 'min-height', 'width', 'max-width', 'min-width',
+    'overflow', 'overflow-x', 'overflow-y',
+    'position', 'display', 'box-sizing',
+    'flex', 'flex-grow', 'flex-shrink', 'flex-basis', 'flex-direction',
+    'align-items', 'justify-content', 'align-self',
+    'grid-template-columns', 'grid-template-rows',
+    'top', 'left', 'right', 'bottom',
+    'margin', 'margin-top', 'margin-bottom', 'margin-left', 'margin-right',
+    'padding', 'padding-top', 'padding-bottom',
+    'transform', 'filter', 'perspective', 'will-change', 'contain',
+    'z-index', 'visibility', 'opacity',
+    // visual (colors / backgrounds / fonts)
+    'color', 'background', 'background-color', 'background-image',
+    'background-size', 'background-position', 'background-repeat',
+    'font-family', 'font-size', 'font-weight', 'font-style', 'line-height',
+    'text-align', 'letter-spacing', 'text-transform',
+];
+function matchDeclarations(el, wantedProps, crossOriginBlocked, blockedSheetUrls) {
+    const out = {};
+    let scanned = 0;
+    for (const sheet of Array.from(document.styleSheets)) {
+        let rules = null;
+        let accessible = true;
+        try {
+            rules = sheet.cssRules;
+        }
+        catch (_e) {
+            accessible = false;
+            crossOriginBlocked.count++;
+            const short = (sheet.href || 'unknown').split('/').pop() || 'unknown';
+            if (!blockedSheetUrls.includes(short))
+                blockedSheetUrls.push(short);
+            continue;
+        }
+        if (!rules)
+            continue;
+        for (const rule of Array.from(rules)) {
+            const styleRule = rule;
+            if (styleRule.selectorText && el.matches && el.matches(styleRule.selectorText)) {
+                const decls = styleRule.style;
+                for (const p of wantedProps) {
+                    const v = decls.getPropertyValue(p);
+                    if (v) {
+                        (out[p] = out[p] || []).push({
+                            selector: styleRule.selectorText,
+                            value: v.trim(),
+                            href: (sheet.href || '').split('/').slice(-2).join('/'),
+                            accessible,
+                        });
+                    }
+                }
+            }
+            scanned += 1;
+            if (scanned > 8000)
+                return out;
+        }
+    }
+    for (const p of wantedProps) {
+        const iv = el.style.getPropertyValue(p);
+        if (iv && !(out[p] || []).some(d => d.selector === 'inline')) {
+            (out[p] = out[p] || []).push({ selector: 'inline', value: iv.trim(), href: '', accessible: true });
+        }
+    }
+    return out;
+}
+// ─── Shape classification ───
+function classifyShape(cs, declared) {
+    const display = cs.display;
+    const position = cs.position;
+    const flexDir = cs.flexDirection;
+    const overflowY = cs.overflowY;
+    const overflowX = cs.overflowX;
+    let role = 'block';
+    if (position === 'fixed')
+        role = 'fixed';
+    else if (position === 'absolute')
+        role = 'absolute';
+    else if (position === 'sticky')
+        role = 'sticky';
+    else if (display === 'grid' || display === 'inline-grid')
+        role = 'grid';
+    else if (display === 'flex' || display === 'inline-flex') {
+        role = flexDir === 'column' ? 'flex-col' : 'flex-row';
+    }
+    else if (display === 'inline' || display === 'inline-block')
+        role = 'inline';
+    const isScrollY = overflowY === 'auto' || overflowY === 'scroll';
+    const isScrollX = overflowX === 'auto' || overflowX === 'scroll';
+    const scrollTag = isScrollY ? (isScrollX ? 'scroll-xy' : 'scroll-y') : (isScrollX ? 'scroll-x' : '');
+    const getDeclared = (prop) => {
+        const arr = declared && declared[prop];
+        if (!arr || arr.length === 0)
+            return null;
+        const inline = arr.find(d => d.selector === 'inline');
+        return inline ? inline.value : arr[0].value;
+    };
+    const sizeClass = (prop, maxProp) => {
+        const val = getDeclared(prop);
+        const maxVal = getDeclared(maxProp);
+        if (val) {
+            if (/^(0|[1-9]\d*)(\.\d+)?(px|pt|cm|mm|in)$/.test(val))
+                return 'fixed';
+            if (/^(0|[1-9]\d*)(\.\d+)?(vh|vw|vmin|vmax)$/.test(val))
+                return 'viewport';
+            if (val.endsWith('%'))
+                return 'percent';
+            if (/^calc\(/.test(val))
+                return 'calc';
+            if (val === 'min-content' || val === 'max-content' || val === 'fit-content')
+                return 'content';
+        }
+        if (maxVal && maxVal !== 'none' && maxVal !== 'auto')
+            return 'constrained';
+        return 'content';
+    };
+    const heightStrategy = sizeClass('height', 'max-height');
+    const widthStrategy = sizeClass('width', 'max-width');
+    const isFlexChild = !!(getDeclared('flex-grow') || getDeclared('flex-shrink') || getDeclared('flex-basis') || getDeclared('flex'));
+    return { role, scrollTag, heightStrategy, widthStrategy, isFlexChild };
+}
+// ─── Node collection ───
+const CB_PROPS = ['transform', 'filter', 'perspective', 'willChange', 'contain'];
+function collectNode(el, maxText, crossOriginBlocked, blockedSheetUrls) {
+    try {
+        const cs = getComputedStyle(el);
+        const rect = el.getBoundingClientRect();
+        if (!rect)
+            return null;
+        const props = {};
+        const LAYOUT_PROPS = [
+            'position', 'display', 'height', 'width', 'minHeight', 'maxHeight',
+            'overflowX', 'overflowY', 'boxSizing', 'margin', 'padding',
+            'flexDirection', 'flexGrow', 'flexShrink', 'flexBasis', 'alignItems', 'justifyContent',
+            'transform', 'filter', 'perspective', 'willChange', 'contain',
+            'zIndex', 'top', 'left', 'right', 'bottom', 'visibility', 'opacity',
+        ];
+        for (const p of LAYOUT_PROPS)
+            props[p] = cs[p] ?? '';
+        const text = (el.textContent || '').replace(/\s+/g, ' ').trim().slice(0, maxText);
+        const declared = matchDeclarations(el, WANTED_PROPS, crossOriginBlocked, blockedSheetUrls);
+        const shape = classifyShape(cs, declared);
+        const rawClass = el.getAttribute('class') || '';
+        return {
+            tag: el.tagName.toLowerCase(),
+            id: el.id || null,
+            classes: rawClass.split(/\s+/).filter(Boolean),
+            inlineStyle: el.getAttribute('style') || null,
+            text,
+            props,
+            declared,
+            shape,
+            metrics: {
+                rect: {
+                    x: +rect.x.toFixed(1),
+                    y: +rect.y.toFixed(1),
+                    width: +rect.width.toFixed(1),
+                    height: +rect.height.toFixed(1),
+                },
+                rectBottom: +rect.bottom.toFixed(1),
+                rectRight: +rect.right.toFixed(1),
+                offsetHeight: el.offsetHeight,
+                clientHeight: el.clientHeight,
+                scrollHeight: el.scrollHeight,
+                clientWidth: el.clientWidth,
+                scrollWidth: el.scrollWidth,
+            },
+            flags: {
+                overflowsViewport: rect.bottom > innerHeight + 1 || rect.right > innerWidth + 1,
+                overflowsParent: rect.bottom > (el.parentElement ? el.parentElement.getBoundingClientRect().bottom + 1 : innerHeight),
+                hasScrollY: el.scrollHeight > el.clientHeight + 1,
+                hasScrollX: el.scrollWidth > el.clientWidth + 1,
+                scrollable: (cs.overflowY === 'auto' || cs.overflowY === 'scroll') &&
+                    el.scrollHeight > el.clientHeight + 1 &&
+                    el.clientHeight > 0,
+            },
+            containingBlockModifiers: CB_PROPS.filter(p => {
+                const v = cs[p];
+                return v && v !== 'none' && v !== 'auto' && v !== 'normal' && v !== 'visible' && v !== 'false';
+            }).map(p => `${p}: ${cs[p]}`),
+        };
+    }
+    catch (_e) {
+        return null;
+    }
+}
+function isSameShape(a, b) {
+    return !!a && !!b && a.tagName === b.tagName && a.id === b.id &&
+        (a.getAttribute('class') || '') === (b.getAttribute('class') || '');
+}
+function buildTree(el, depth, state, maxNodes, crossOriginBlocked, blockedSheetUrls) {
+    if (!el || state.count >= maxNodes || depth < 0)
+        return null;
+    state.count += 1;
+    const collected = collectNode(el, 40, crossOriginBlocked, blockedSheetUrls);
+    if (!collected)
+        return null;
+    const node = { ...collected, children: [] };
+    const kids = Array.from(el.children);
+    if (depth > 0) {
+        let i = 0;
+        while (i < kids.length) {
+            const run = [kids[i]];
+            let j = i + 1;
+            while (j < kids.length && isSameShape(kids[i], kids[j])) {
+                run.push(kids[j]);
+                j += 1;
+            }
+            const rep = buildTree(run[0], depth - 1, state, maxNodes, crossOriginBlocked, blockedSheetUrls);
+            if (rep) {
+                node.children.push({ ...rep, repeat: run.length });
+            }
+            i = j;
+        }
+    }
+    return node;
+}
+function walkUp(el, stopTag) {
+    const chain = [];
+    let cur = el;
+    while (cur && cur.tagName.toLowerCase() !== stopTag) {
+        chain.unshift(cur);
+        cur = cur.parentElement;
+    }
+    if (cur)
+        chain.unshift(cur);
+    return chain;
+}
+// ─── Entry point (invoked from Node via window.__cssprobe_cli.collect) ───
+function collect(cfg) {
+    const crossOriginBlocked = { count: 0 };
+    const blockedSheetUrls = [];
+    const viewport = { width: window.innerWidth, height: window.innerHeight };
+    const root = document.querySelector(cfg.rootSelector);
+    if (!root) {
+        const candidates = Array.from(document.querySelectorAll('.s-kit-modal, [class*="dialog"], [class*="modal"], [class*="popup"]'))
+            .slice(0, 5)
+            .map(el => `${el.tagName}.${(el.getAttribute('class') || '').split(/\s+/).filter(Boolean).join('.')}`);
+        return {
+            rootSelector: cfg.rootSelector,
+            upTo: cfg.upTo,
+            downDepth: cfg.downDepth,
+            maxNodes: cfg.maxNodes,
+            nodeCount: 0,
+            viewport,
+            ancestors: [],
+            tree: null,
+            crossOriginBlocked: crossOriginBlocked.count,
+            blockedSheetUrls: blockedSheetUrls.slice(0, 5),
+            error: `未找到 ${cfg.rootSelector}`,
+            candidates,
+        };
+    }
+    const ancestors = walkUp(root, cfg.upTo)
+        .map(el => collectNode(el, 30, crossOriginBlocked, blockedSheetUrls))
+        .filter((n) => n !== null)
+        .map(n => ({
+        label: `${n.tag}.${n.classes.join('.')}`,
+        props: n.props,
+        metrics: n.metrics,
+        flags: n.flags,
+        declared: n.declared,
+        shape: n.shape,
+        containingBlockModifiers: n.containingBlockModifiers,
+        inlineStyle: n.inlineStyle,
+    }));
+    const state = { count: 0 };
+    const tree = buildTree(root, cfg.downDepth, state, cfg.maxNodes, crossOriginBlocked, blockedSheetUrls);
+    return {
+        rootSelector: cfg.rootSelector,
+        upTo: cfg.upTo,
+        downDepth: cfg.downDepth,
+        maxNodes: cfg.maxNodes,
+        nodeCount: state.count,
+        viewport,
+        ancestors,
+        tree,
+        crossOriginBlocked: crossOriginBlocked.count,
+        blockedSheetUrls: blockedSheetUrls.slice(0, 5),
+    };
+}
+//# sourceMappingURL=collector.js.map

package/dist/engine/renderer.d.ts

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