bee-ladybug 0.4.1 → 0.5.1

package/README.MD

@@ -39,6 +39,7 @@ bee-ladybug/
 │   └── adapters/
 │       ├── CanvasAdapter.js
 │       ├── WebDOMAdapter.js
+│       ├── CSSAdapter.js
 │       ├── AntAdapter.js
 │       ├── SpiderAdapter.js
 │       └── python/PythonBridge.js
@@ -46,10 +47,12 @@ bee-ladybug/
 │   ├── core.html
 │   ├── canvas-sandbox.js
 │   ├── dom.html
+│   ├── css-hunt.html
 │   ├── python.html
 │   └── python/sender.py
 ├── tsconfig.json
 ├── package.json
+├── CHANGELOG.md
 ├── LICENSE
 ├── index.html
 └── README.md
@@ -130,6 +133,8 @@ bee.subscribe((packet) => {
 | `F2` | mostra / nascondi overlay (e hitbox canvas) |
 | `F3` | slow-motion del tempo fittizio (`0.25x` / `1x`) |
 | `F4` | freeze / run del tempo fittizio |
+| `F6` | CSS hunt, se `CSSAdapter` è attaccato |
+| `S` | scansione CSS, solo con la hunt accesa |
 
 Niente `F12`, niente tilde: sui layout italiani la tilde non è un tasto unico.
 
@@ -177,6 +182,28 @@ adapter.attach();
 
 Traduce il DOM in pacchetti: nodo sotto il puntatore, box model (margin / padding / content), conteggio nodi, mutazioni (`+n -n attr`). `F4` congela l'hover. `F2` nasconde overlay e highlight. Il Core non sa che esiste HTML.
 
+## CSS hunt (F6)
+
+```js
+import { BeeLadybugCore, CSSAdapter } from './src/index.js';
+
+const bee = new BeeLadybugCore();
+const css = new CSSAdapter(bee);
+css.attach();
+```
+
+`F6` (pulsante **F6 CSS** accanto a F3/F4) accende la caccia. Sull'elemento sotto il puntatore l'overlay elenca:
+
+- regole `!important` che gli corrispondono (fogli cross-origin: `unreadable sheet: <href>`)
+- overflow del viewport e margini negativi
+- testo trasparente, `opacity: 0`, o colore uguale allo sfondo
+- chi intercetta il click al centro, inclusi `::before` / `::after` fissi su `html` / `body`
+- `<img>` con rapporto stirato oltre il 5% e `object-fit: fill`
+
+`S` con la hunt accesa percorre la pagina. L'overflow resta solo sull'elemento che lo causa: un antenato si salta se un discendente sfora della stessa quantità (±2px), oppure se la larghezza del box ci sta nel viewport e a uscire è un figlio. Righe uguali (stesso selettore e stesso problema) diventano una sola, con il conteggio (`article overflows viewport ×4`). L'ordine è: causa di overflow, click bloccato, testo invisibile, immagine distorta, `!important`. Un click sulla riga disegna il contorno rosso. In console un elemento pulito non viene scritto, a meno che `F3` SLOW sia acceso. I fogli di stile restano in cache finché un `MutationObserver` non vede un cambio a `<style>` o `<link>`. Hover è limitato a un frame.
+
+Demo: `examples/css-hunt.html`.
+
 ## Registro adapter (overlay)
 
 Il Core non conosce ANT/SPIDER. Gli adapter si iscrivono con hook propri; l'overlay disegna un toggle per ciascuno.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bee-ladybug",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Universal telemetry and visual inspection overlay for Canvas, DOM, Python and AI flows.",
   "type": "module",
   "main": "src/index.js",

package/src/adapters/CSSAdapter.js

@@ -0,0 +1,773 @@
+/**
+ * CSSAdapter — CSS hunt.
+ *
+ * Hover an element to list !important hits, viewport overflow, negative
+ * margins, invisible text, click blockers and stretched images. The core
+ * only receives packets and detail rows; it does not parse CSS.
+ *
+ * @example
+ * const css = new CSSAdapter(core);
+ * css.attach();
+ * // F6 toggles hunt. S scans the page while hunt is on.
+ */
+
+export const CSS_ADAPTER_DEFAULTS = Object.freeze({
+    source: 'css',
+    hotkey: 'F6',
+    scanKey: 'KeyS',
+    label: 'F6 CSS',
+    maxScan: 8
+});
+
+export class CSSAdapter {
+    /**
+     * @param {import('../core/BeeLadybugCore.js').BeeLadybugCore} core
+     * @param {Partial<typeof CSS_ADAPTER_DEFAULTS>} [options]
+     */
+    constructor(core, options = {}) {
+        const cfg = { ...CSS_ADAPTER_DEFAULTS, ...options };
+        this.core = core;
+        this.source = cfg.source;
+        this.hotkey = cfg.hotkey;
+        this.scanKey = cfg.scanKey;
+        this.label = cfg.label;
+        this.maxScan = cfg.maxScan;
+
+        this.#attached = false;
+        this.#active = false;
+        this.#rules = [];
+        this.#unreadable = [];
+        this.#sheetsDirty = true;
+        this.#x = 0;
+        this.#y = 0;
+        this.#rafId = 0;
+        this.#lastEl = null;
+        this.#pinned = null;
+        this.#hoverBox = null;
+        this.#pinBox = null;
+        this.#observer = null;
+        this.#onMove = (event) => {
+            this.#x = event.clientX;
+            this.#y = event.clientY;
+            this.#schedule();
+        };
+        this.#onKey = (event) => this.#handleKey(event);
+        this.#onScroll = () => this.#placeBoxes();
+        this.#onMutate = (records) => {
+            if (!records.some(touchesSheet)) return;
+            this.#sheetsDirty = true;
+            this.#schedule();
+        };
+    }
+
+    #attached;
+    #active;
+    #rules;
+    #unreadable;
+    #sheetsDirty;
+    #x;
+    #y;
+    #rafId;
+    #lastEl;
+    #pinned;
+    #hoverBox;
+    #pinBox;
+    #observer;
+    #onMove;
+    #onKey;
+    #onScroll;
+    #onMutate;
+
+    get active() {
+        return this.#active;
+    }
+
+    attach() {
+        if (this.#attached) return this;
+        this.#attached = true;
+        this.core?.registerAdapter('css', {
+            label: this.label,
+            hotkey: this.hotkey,
+            enabled: false,
+            enable: () => this.#enable(),
+            disable: () => this.#disable()
+        });
+        this.core?.sendData('log', {
+            source: this.source,
+            message: 'CSSAdapter attached. F6 CSS hunt. S scans the page while hunt is on.'
+        });
+        this.core?.sendData('state', {
+            source: this.source,
+            key: 'css.hunt',
+            value: 'off'
+        });
+        return this;
+    }
+
+    detach() {
+        if (!this.#attached) return this;
+        this.#disable();
+        this.#attached = false;
+        this.core?.unregisterAdapter('css');
+        return this;
+    }
+
+    /** Page scan. Click a row to outline one element of that group. */
+    scan() {
+        if (!this.#active || typeof document === 'undefined') return this;
+        if (this.#sheetsDirty) this.#rebuildSheets();
+        const nodes = document.body ? document.body.querySelectorAll('*') : [];
+        const overflow = [];
+        const rows = [];
+        for (let i = 0; i < nodes.length; i++) {
+            const el = nodes[i];
+            if (!el || isBeeChrome(el) || isSkippedTag(el)) continue;
+            const measured = measureViewportOverflow(el);
+            if (measured) overflow.push(measured);
+            const findings = [];
+            pushNegativeMargins(el, findings);
+            pushInvisible(el, findings);
+            pushBlockers(el, findings);
+            pushImage(el, findings);
+            pushImportant(el, this.#rules, findings);
+            for (let j = 0; j < findings.length; j++) {
+                rows.push({ el, selector: cssPath(el), ...findings[j] });
+            }
+        }
+        const causes = keepOverflowCauses(overflow);
+        for (let i = 0; i < causes.length; i++) {
+            const cause = causes[i];
+            rows.push({
+                el: cause.el,
+                selector: cssPath(cause.el),
+                kind: 'overflows viewport',
+                rank: 0,
+                level: 'error',
+                score: cause.score
+            });
+        }
+        const groups = groupIssues(rows).slice(0, this.maxScan);
+        const items = groups.map((group) => ({
+            level: group.level,
+            text: formatIssue(group),
+            onSelect: () => this.#pin(group.el)
+        }));
+        this.#lastEl = null;
+        this.core?.publishDetail(items);
+        this.core?.sendData('state', {
+            source: this.source,
+            key: 'css.scan',
+            value: String(groups.length)
+        });
+        if (groups.length || isVerbose(this.core)) {
+            this.core?.sendData('warn', {
+                source: this.source,
+                message: groups.length
+                    ? `scan ${groups.length} issue(s). Click a row to outline it.`
+                    : 'scan clean: no causes found.'
+            });
+        }
+        return this;
+    }
+
+    #enable() {
+        if (this.#active || typeof document === 'undefined' || typeof window === 'undefined') return;
+        this.#active = true;
+        this.#sheetsDirty = true;
+        this.#mountBoxes();
+        window.addEventListener('mousemove', this.#onMove, true);
+        window.addEventListener('keydown', this.#onKey);
+        window.addEventListener('scroll', this.#onScroll, true);
+        window.addEventListener('resize', this.#onScroll);
+        if (typeof MutationObserver !== 'undefined' && document.documentElement) {
+            this.#observer = new MutationObserver(this.#onMutate);
+            this.#observer.observe(document.documentElement, {
+                childList: true,
+                subtree: true,
+                attributes: true,
+                attributeFilter: ['href', 'rel', 'media', 'disabled', 'type'],
+                characterData: true
+            });
+        }
+        this.#rebuildSheets();
+        this.core?.sendData('state', { source: this.source, key: 'css.hunt', value: 'on' });
+        this.core?.sendData('log', {
+            source: this.source,
+            message: 'CSS hunt on. Hover an element, or press S to scan.'
+        });
+    }
+
+    #disable() {
+        if (!this.#active) return;
+        this.#active = false;
+        if (typeof window !== 'undefined') {
+            window.removeEventListener('mousemove', this.#onMove, true);
+            window.removeEventListener('keydown', this.#onKey);
+            window.removeEventListener('scroll', this.#onScroll, true);
+            window.removeEventListener('resize', this.#onScroll);
+        }
+        if (this.#rafId && typeof cancelAnimationFrame === 'function') cancelAnimationFrame(this.#rafId);
+        this.#rafId = 0;
+        if (this.#observer) this.#observer.disconnect();
+        this.#observer = null;
+        this.#lastEl = null;
+        this.#pinned = null;
+        this.#unmountBoxes();
+        this.core?.publishDetail([]);
+        this.core?.sendData('state', { source: this.source, key: 'css.hunt', value: 'off' });
+        this.core?.sendData('log', { source: this.source, message: 'CSS hunt off.' });
+    }
+
+    #handleKey(event) {
+        if (!this.#active || event.repeat) return;
+        if (event.code !== this.scanKey) return;
+        if (isTypingTarget(event.target)) return;
+        event.preventDefault();
+        this.scan();
+    }
+
+    #schedule() {
+        if (!this.#active || this.#rafId || typeof requestAnimationFrame !== 'function') return;
+        this.#rafId = requestAnimationFrame(() => {
+            this.#rafId = 0;
+            if (!this.#active) return;
+            if (this.#sheetsDirty) this.#rebuildSheets();
+            this.#inspect(this.#x, this.#y);
+        });
+    }
+
+    #rebuildSheets() {
+        this.#sheetsDirty = false;
+        const built = collectImportantRules();
+        this.#rules = built.rules;
+        this.#unreadable = built.unreadable;
+        for (let i = 0; i < built.unreadable.length; i++) {
+            this.core?.sendData('warn', {
+                source: this.source,
+                message: `unreadable sheet: ${built.unreadable[i]}`
+            });
+        }
+    }
+
+    #inspect(x, y) {
+        const el = pickElement(x, y);
+        placeBox(this.#hoverBox, el);
+        if (el === this.#lastEl) return;
+        this.#lastEl = el;
+        if (!el) {
+            this.core?.publishDetail([]);
+            this.core?.sendData('state', { source: this.source, key: 'css.target', value: '—' });
+            return;
+        }
+        const findings = [];
+        pushImportant(el, this.#rules, findings);
+        pushOverflow(el, findings);
+        pushInvisible(el, findings);
+        pushBlockers(el, findings);
+        pushImage(el, findings);
+        for (let i = 0; i < this.#unreadable.length; i++) {
+            findings.push({
+                level: 'warn',
+                text: `unreadable sheet: ${this.#unreadable[i]}`,
+                score: 0
+            });
+        }
+        const path = cssPath(el);
+        this.core?.sendData('state', { source: this.source, key: 'css.target', value: path });
+        this.core?.sendData('state', {
+            source: this.source,
+            key: 'css.hits',
+            value: String(findings.length)
+        });
+        this.core?.publishDetail(findings.map((hit) => ({
+            level: hit.level,
+            text: `${path}  ${hit.text}`,
+            onSelect: () => this.#pin(el)
+        })));
+        if (!findings.length) {
+            if (isVerbose(this.core)) {
+                this.core?.sendData('log', { source: this.source, message: `${path}  clean` });
+            }
+            return;
+        }
+        const lead = findings.find((hit) => hit.level === 'error') || findings[0];
+        this.core?.sendData(lead.level === 'error' ? 'error' : 'warn', {
+            source: this.source,
+            message: `${path}  ${lead.text}`
+        });
+    }
+
+    #pin(el) {
+        this.#pinned = el;
+        placeBox(this.#pinBox, el);
+        if (el && typeof el.scrollIntoView === 'function') {
+            el.scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'smooth' });
+        }
+    }
+
+    #placeBoxes() {
+        placeBox(this.#hoverBox, this.#lastEl);
+        placeBox(this.#pinBox, this.#pinned);
+    }
+
+    #mountBoxes() {
+        if (typeof document === 'undefined' || this.#hoverBox) return;
+        this.#hoverBox = makeBox('hover', '1px solid #ffd36a', 'transparent');
+        this.#pinBox = makeBox('pin', '2px solid #ff3b4e', 'rgba(255, 59, 78, 0.12)');
+        document.body.appendChild(this.#hoverBox);
+        document.body.appendChild(this.#pinBox);
+    }
+
+    #unmountBoxes() {
+        this.#hoverBox?.remove();
+        this.#pinBox?.remove();
+        this.#hoverBox = null;
+        this.#pinBox = null;
+    }
+}
+
+function collectImportantRules() {
+    const rules = [];
+    const unreadable = [];
+    if (typeof document === 'undefined') return { rules, unreadable };
+    const sheets = document.styleSheets;
+    for (let i = 0; i < sheets.length; i++) {
+        const sheet = sheets[i];
+        let list = null;
+        try {
+            list = sheet.cssRules;
+        } catch {
+            unreadable.push(sheet.href || '<style> inline');
+            continue;
+        }
+        walkRules(list, sheetLabel(sheet), rules);
+    }
+    return { rules, unreadable };
+}
+
+function walkRules(list, source, into) {
+    if (!list) return;
+    for (let i = 0; i < list.length; i++) {
+        const rule = list[i];
+        if (!rule) continue;
+        if (rule.type === 4 && rule.media) {
+            let active = true;
+            try {
+                active = typeof matchMedia === 'function'
+                    ? matchMedia(rule.media.mediaText).matches
+                    : true;
+            } catch {
+                active = true;
+            }
+            if (active) walkRules(rule.cssRules, source, into);
+            continue;
+        }
+        if (rule.type === 1 && rule.selectorText && rule.style) {
+            const props = importantProps(rule.style);
+            if (props.length) into.push({ selector: rule.selectorText, source, props });
+        } else if (rule.cssRules) {
+            walkRules(rule.cssRules, source, into);
+        }
+    }
+}
+
+function importantProps(style) {
+    const props = [];
+    for (let i = 0; i < style.length; i++) {
+        const property = style.item(i);
+        if (style.getPropertyPriority(property) !== 'important') continue;
+        props.push({ property, value: style.getPropertyValue(property).trim() });
+    }
+    return props;
+}
+
+function sheetLabel(sheet) {
+    if (sheet.href) return sheet.href;
+    return '<style> inline';
+}
+
+function pushImportant(el, rules, findings) {
+    for (let i = 0; i < rules.length; i++) {
+        const rule = rules[i];
+        let matched = false;
+        try {
+            matched = el.matches(rule.selector);
+        } catch {
+            continue;
+        }
+        if (!matched) continue;
+        for (let j = 0; j < rule.props.length; j++) {
+            const prop = rule.props[j];
+            findings.push({
+                level: 'warn',
+                rank: 4,
+                score: 5,
+                kind: `!important ${rule.selector} { ${prop.property}: ${prop.value} }`,
+                text: `!important ${rule.selector} { ${prop.property}: ${prop.value} } @ ${rule.source}`
+            });
+        }
+    }
+}
+
+function pushOverflow(el, findings) {
+    const measured = measureViewportOverflow(el);
+    if (measured) {
+        const past = measured.left > 1
+            ? `left ${Math.round(-measured.left)}px`
+            : `right +${Math.round(measured.right)}px`;
+        findings.push({
+            level: 'error',
+            rank: 0,
+            score: measured.score,
+            kind: 'overflows viewport',
+            text: `overflows viewport (${past})`
+        });
+    }
+    pushNegativeMargins(el, findings);
+}
+
+function measureViewportOverflow(el) {
+    if (!el || typeof el.getBoundingClientRect !== 'function') return null;
+    if (typeof document === 'undefined') return null;
+    if (el === document.documentElement || el === document.body) return null;
+    const rect = el.getBoundingClientRect();
+    const view = document.documentElement.clientWidth;
+    const left = rect.left < -1 ? -rect.left : 0;
+    const right = rect.right > view + 1 ? rect.right - view : 0;
+    if (left <= 1 && right <= 1) return null;
+    return { el, left, right, width: rect.width, view, score: Math.max(left, right) };
+}
+
+/**
+ * Keep the node that actually sticks out.
+ * Drop a parent when a descendant overflows by the same amount (±2px),
+ * and drop a box whose own width fits the viewport when a child is the one overflowing.
+ * @param {Array<{ el: Element, left: number, right: number, width: number, view: number, score: number }>} items
+ */
+export function keepOverflowCauses(items) {
+    return items.filter((item) => !echoedByDescendant(item, items) && !fitsOnlyBecauseOfChild(item, items));
+}
+
+function echoedByDescendant(item, items) {
+    for (let i = 0; i < items.length; i++) {
+        const other = items[i];
+        if (other.el === item.el || typeof item.el.contains !== 'function' || !item.el.contains(other.el)) continue;
+        const leftEcho = item.left <= 1 || Math.abs(item.left - other.left) <= 2;
+        const rightEcho = item.right <= 1 || Math.abs(item.right - other.right) <= 2;
+        const matched = (item.left > 1 && Math.abs(item.left - other.left) <= 2)
+            || (item.right > 1 && Math.abs(item.right - other.right) <= 2);
+        if (matched && leftEcho && rightEcho) return true;
+    }
+    return false;
+}
+
+function fitsOnlyBecauseOfChild(item, items) {
+    if (item.width > item.view + 2) return false;
+    if (item.left <= 1 && item.right <= 1) return false;
+    let leftOk = item.left <= 1;
+    let rightOk = item.right <= 1;
+    let childOverflows = false;
+    for (let i = 0; i < items.length; i++) {
+        const other = items[i];
+        if (other.el === item.el || typeof item.el.contains !== 'function' || !item.el.contains(other.el)) continue;
+        if (other.left > 1 || other.right > 1) childOverflows = true;
+        if (item.left > 1 && other.left + 2 >= item.left) leftOk = true;
+        if (item.right > 1 && other.right + 2 >= item.right) rightOk = true;
+    }
+    return childOverflows && leftOk && rightOk;
+}
+
+function pushNegativeMargins(el, findings) {
+    if (typeof getComputedStyle !== 'function') return;
+    const style = getComputedStyle(el);
+    const sides = ['top', 'right', 'bottom', 'left'];
+    for (let i = 0; i < sides.length; i++) {
+        const raw = style.getPropertyValue(`margin-${sides[i]}`);
+        const value = parseFloat(raw);
+        if (!Number.isFinite(value) || value >= 0) continue;
+        findings.push({
+            level: 'warn',
+            rank: 5,
+            score: Math.abs(value),
+            kind: `negative margin margin-${sides[i]}: ${raw.trim()}`,
+            text: `negative margin margin-${sides[i]}: ${raw.trim()}`
+        });
+    }
+}
+
+const ISSUE_RANK = Object.freeze({
+    overflow: 0,
+    blocker: 1,
+    invisible: 2,
+    image: 3,
+    important: 4
+});
+
+/**
+ * @param {Array<{ selector: string, kind: string, rank: number, level: string, score: number, el?: Element }>} rows
+ */
+export function groupIssues(rows) {
+    const map = new Map();
+    for (let i = 0; i < rows.length; i++) {
+        const row = rows[i];
+        const kind = row.kind || row.text;
+        const key = `${row.selector}\0${kind}`;
+        const prev = map.get(key);
+        if (!prev) {
+            map.set(key, { ...row, kind, count: 1 });
+            continue;
+        }
+        prev.count += 1;
+        if (row.score > prev.score) {
+            prev.score = row.score;
+            prev.el = row.el;
+        }
+    }
+    return [...map.values()].sort((a, b) => a.rank - b.rank || b.score - a.score || b.count - a.count);
+}
+
+export function formatIssue(group) {
+    const count = group.count > 1 ? ` ×${group.count}` : '';
+    return `${group.selector} ${group.kind}${count}`;
+}
+
+function pushInvisible(el, findings) {
+    if (!hasOwnText(el)) return;
+    const style = getComputedStyle(el);
+    if (opacityZero(el)) {
+        findings.push(issue('invisible text (opacity 0)', ISSUE_RANK.invisible, 30));
+    }
+    const color = parseColor(style.color);
+    if (!color || color.a === 0) {
+        findings.push(issue('invisible text (transparent color)', ISSUE_RANK.invisible, 30));
+        return;
+    }
+    const behind = paintBehind(el);
+    if (behind && nearlySame(color, behind)) {
+        findings.push(issue('invisible text (color matches background)', ISSUE_RANK.invisible, 30));
+    }
+}
+
+function pushBlockers(el, findings) {
+    if (!el.getBoundingClientRect || typeof document.elementFromPoint !== 'function') return;
+    const rect = el.getBoundingClientRect();
+    const x = rect.left + rect.width / 2;
+    const y = rect.top + rect.height / 2;
+    if (x < 0 || y < 0 || x > window.innerWidth || y > window.innerHeight) return;
+    const pseudo = coveringPseudo(x, y);
+    if (pseudo) {
+        findings.push(issue(`click blocked by ${pseudo}`, ISSUE_RANK.blocker, 40));
+    }
+    const hit = document.elementFromPoint(x, y);
+    if (!hit || isBeeChrome(hit) || hit === el || el.contains(hit)) return;
+    if (pseudo && (hit === document.documentElement || hit === document.body)) return;
+    findings.push(issue(`click blocked by ${cssPath(hit)}`, ISSUE_RANK.blocker, 40));
+}
+
+function pushImage(el, findings) {
+    if (!el || el.tagName !== 'IMG') return;
+    const naturalW = el.naturalWidth;
+    const naturalH = el.naturalHeight;
+    const shownW = el.clientWidth;
+    const shownH = el.clientHeight;
+    if (!naturalW || !naturalH || !shownW || !shownH) return;
+    const natural = naturalW / naturalH;
+    const shown = shownW / shownH;
+    const diff = Math.abs(natural - shown) / natural;
+    const fit = getComputedStyle(el).objectFit;
+    if (diff <= 0.05 || fit !== 'fill') return;
+    findings.push({
+        level: 'error',
+        rank: ISSUE_RANK.image,
+        score: diff * 100,
+        kind: 'distorted image',
+        text: `distorted image ${Math.round(diff * 100)}% (object-fit: fill)`
+    });
+}
+
+function issue(kind, rank, score) {
+    return { level: 'error', rank, score, kind, text: kind };
+}
+
+function isVerbose(core) {
+    return Boolean(core) && !core.frozen && core.timeScale !== 1;
+}
+
+function coveringPseudo(x, y) {
+    const hosts = [document.documentElement, document.body];
+    const names = ['::before', '::after'];
+    for (let i = 0; i < hosts.length; i++) {
+        const host = hosts[i];
+        if (!host) continue;
+        for (let j = 0; j < names.length; j++) {
+            const box = pseudoBox(host, names[j]);
+            if (!box || box.pointerEvents === 'none') continue;
+            if (x < box.x || y < box.y || x > box.x + box.w || y > box.y + box.h) continue;
+            return `${host.tagName.toLowerCase()}${names[j]}`;
+        }
+    }
+    return '';
+}
+
+function pseudoBox(el, pseudo) {
+    const style = getComputedStyle(el, pseudo);
+    const content = style.content;
+    if (!content || content === 'none' || content === 'normal') return null;
+    if (style.position !== 'fixed' && style.position !== 'absolute') return null;
+    const width = parseFloat(style.width);
+    const height = parseFloat(style.height);
+    if (!width || !height || width < 2 || height < 2) return null;
+    let x = parseFloat(style.left);
+    let y = parseFloat(style.top);
+    if (!Number.isFinite(x)) x = 0;
+    if (!Number.isFinite(y)) y = 0;
+    if (style.position === 'absolute') {
+        const host = el.getBoundingClientRect();
+        x = host.left + x;
+        y = host.top + y;
+    }
+    return { x, y, w: width, h: height, pointerEvents: style.pointerEvents };
+}
+
+function pickElement(x, y) {
+    if (typeof document === 'undefined' || typeof document.elementsFromPoint !== 'function') return null;
+    const stack = document.elementsFromPoint(x, y);
+    for (let i = 0; i < stack.length; i++) {
+        const el = stack[i];
+        if (!el || isBeeChrome(el)) continue;
+        if (el === document.documentElement || el === document.body) continue;
+        return el;
+    }
+    return null;
+}
+
+function paintBehind(el) {
+    const own = parseColor(getComputedStyle(el).backgroundColor);
+    if (own && own.a > 0.04) return own;
+    let node = el.parentElement;
+    while (node) {
+        const bg = parseColor(getComputedStyle(node).backgroundColor);
+        if (bg && bg.a > 0.04) return bg;
+        node = node.parentElement;
+    }
+    return null;
+}
+
+function opacityZero(el) {
+    let node = el;
+    while (node && node.nodeType === 1) {
+        const value = parseFloat(getComputedStyle(node).opacity);
+        if (value === 0) return true;
+        node = node.parentElement;
+    }
+    return false;
+}
+
+function parseColor(value) {
+    const text = String(value || '').trim();
+    if (text === 'transparent') return { r: 0, g: 0, b: 0, a: 0 };
+    const match = text.match(/rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)(?:[,\s/]+([\d.]+%?))?\s*\)/);
+    if (!match) return null;
+    let alpha = 1;
+    if (match[4] != null) {
+        alpha = match[4].endsWith('%') ? parseFloat(match[4]) / 100 : parseFloat(match[4]);
+    }
+    return { r: Number(match[1]), g: Number(match[2]), b: Number(match[3]), a: alpha };
+}
+
+function nearlySame(a, b) {
+    return Math.abs(a.r - b.r) < 2
+        && Math.abs(a.g - b.g) < 2
+        && Math.abs(a.b - b.b) < 2
+        && Math.abs(a.a - b.a) < 0.05;
+}
+
+function hasOwnText(el) {
+    const tag = el.tagName;
+    if (tag === 'BUTTON' || tag === 'A' || tag === 'LABEL' || tag === 'INPUT' || tag === 'TEXTAREA') return true;
+    if (el.childElementCount > 0) return false;
+    return Boolean((el.textContent || '').trim());
+}
+
+function cssPath(el) {
+    if (!el || !el.tagName) return 'node';
+    const tag = el.tagName.toLowerCase();
+    if (el.id) return `${tag}#${el.id}`;
+    const classes = el.classList ? [...el.classList].slice(0, 2) : [];
+    if (classes.length) return `${tag}.${classes.join('.')}`;
+    return tag;
+}
+
+function isSkippedTag(el) {
+    const tag = el.tagName;
+    return tag === 'SCRIPT' || tag === 'STYLE' || tag === 'LINK' || tag === 'META';
+}
+
+function isTypingTarget(target) {
+    if (!target || !target.tagName) return false;
+    const tag = target.tagName;
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return true;
+    return Boolean(target.isContentEditable);
+}
+
+function touchesSheet(record) {
+    if (!record) return false;
+    if (record.type === 'characterData') return record.target?.parentElement?.nodeName === 'STYLE';
+    if (record.type === 'attributes') {
+        const name = record.target?.nodeName;
+        return name === 'STYLE' || name === 'LINK';
+    }
+    const nodes = [record.target];
+    if (record.addedNodes) {
+        for (let i = 0; i < record.addedNodes.length; i++) nodes.push(record.addedNodes[i]);
+    }
+    if (record.removedNodes) {
+        for (let i = 0; i < record.removedNodes.length; i++) nodes.push(record.removedNodes[i]);
+    }
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        if (!node || node.nodeType !== 1) continue;
+        if (node.nodeName === 'STYLE' || node.nodeName === 'LINK') return true;
+        if (typeof node.querySelector === 'function' && node.querySelector('style, link')) return true;
+    }
+    return false;
+}
+
+function isBeeChrome(node) {
+    let el = node && node.nodeType === 1 ? node : node?.parentElement;
+    while (el) {
+        if (el.tagName === 'BEE-LADYBUG-OVERLAY') return true;
+        if (el.hasAttribute?.('data-bee-ladybug-dom')) return true;
+        if (el.hasAttribute?.('data-bee-ladybug-canvas')) return true;
+        if (el.hasAttribute?.('data-bee-ladybug-css')) return true;
+        el = el.parentElement;
+    }
+    return false;
+}
+
+function makeBox(kind, border, fill) {
+    const node = document.createElement('div');
+    node.setAttribute('data-bee-ladybug-css', kind);
+    node.style.position = 'fixed';
+    node.style.pointerEvents = 'none';
+    node.style.zIndex = '2147483644';
+    node.style.display = 'none';
+    node.style.boxSizing = 'border-box';
+    node.style.border = border;
+    node.style.background = fill;
+    return node;
+}
+
+function placeBox(node, el) {
+    if (!node) return;
+    if (!el || typeof el.getBoundingClientRect !== 'function' || isBeeChrome(el)) {
+        node.style.display = 'none';
+        return;
+    }
+    const rect = el.getBoundingClientRect();
+    node.style.display = 'block';
+    node.style.left = `${rect.left}px`;
+    node.style.top = `${rect.top}px`;
+    node.style.width = `${rect.width}px`;
+    node.style.height = `${rect.height}px`;
+}

package/src/core/BeeLadybugCore.js

@@ -9,7 +9,7 @@
 import { UIOverlay } from './UIOverlay.js';
 import { buildAssistantSnapshot, normalizeAssistant } from './AiAssistant.js';
 
-export const BEE_LADYBUG_VERSION = '0.4.1';
+export const BEE_LADYBUG_VERSION = '0.5.1';
 
 export const CORE_DEFAULTS = Object.freeze({
     toggleKey: 'F2',
@@ -98,6 +98,7 @@ export class BeeLadybugCore {
         this.#activeAssistant = null;
         this.#askBusy = false;
         this.#adapters = new Map();
+        this.#detail = [];
 
         this.ui = null;
         if (cfg.ui !== false && typeof document !== 'undefined') {
@@ -132,6 +133,8 @@ export class BeeLadybugCore {
     /** @type {string | null} */
     #activeAssistant;
     #askBusy;
+    /** @type {Array<{ text: string, level?: string, onSelect?: () => void }>} */
+    #detail;
     /** @type {Map<string, { name: string, label: string, enabled: boolean, enable: Function, disable: Function }>} */
     #adapters;
 
@@ -289,7 +292,7 @@ export class BeeLadybugCore {
      * Register a toggleable diagnostic adapter. The core stores hooks only —
      * it does not import or special-case adapter modules.
      * @param {string} name
-     * @param {{ enable: () => void, disable: () => void, label?: string }} hooks
+     * @param {{ enable: () => void, disable: () => void, label?: string, hotkey?: string, enabled?: boolean }} hooks
      */
     registerAdapter(name, hooks = {}) {
         const key = String(name || '').trim();
@@ -301,14 +304,24 @@ export class BeeLadybugCore {
             return this;
         }
         const label = String(hooks.label || key).trim() || key;
+        const hotkey = typeof hooks.hotkey === 'string' ? hooks.hotkey : '';
+        const enabled = hooks.enabled !== false;
         this.#adapters.set(key, {
             name: key,
             label,
-            enabled: true,
+            hotkey,
+            enabled,
             enable: hooks.enable,
             disable: hooks.disable
         });
-        this.sendData('sys', { op: 'adapter', name: key, registered: true, label, enabled: true });
+        this.sendData('sys', {
+            op: 'adapter',
+            name: key,
+            registered: true,
+            label,
+            hotkey,
+            enabled
+        });
         return this;
     }
 
@@ -328,10 +341,21 @@ export class BeeLadybugCore {
         return [...this.#adapters.values()].map((entry) => ({
             name: entry.name,
             label: entry.label,
+            hotkey: entry.hotkey || '',
             enabled: entry.enabled
         }));
     }
 
+    /**
+     * Clickable rows inside the overlay. The core does not interpret them.
+     * @param {Array<{ text: string, level?: string, onSelect?: () => void }>} items
+     */
+    publishDetail(items) {
+        this.#detail = Array.isArray(items) ? items : [];
+        this.ui?.setDetail(this.#detail);
+        return this;
+    }
+
     /**
      * @param {string} name
      */
@@ -438,6 +462,7 @@ export class BeeLadybugCore {
         this.#activeAssistant = null;
         this.#askBusy = false;
         this.#adapters.clear();
+        this.#detail = [];
         this.ui?.destroy();
         this.ui = null;
         return this;
@@ -720,10 +745,27 @@ export class BeeLadybugCore {
         if (code === this.freezeKey) {
             event.preventDefault();
             this.toggleFreeze();
+            return;
+        }
+
+        if (isTypingTarget(event.target)) return;
+
+        for (const entry of this.#adapters.values()) {
+            if (!entry.hotkey || code !== entry.hotkey) continue;
+            event.preventDefault();
+            this.toggleAdapter(entry.name);
+            return;
         }
     }
 }
 
+function isTypingTarget(target) {
+    if (!target || typeof target !== 'object') return false;
+    const tag = target.tagName;
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return true;
+    return Boolean(target.isContentEditable);
+}
+
 function asObject(payload) {
     if (payload == null) return {};
     if (typeof payload !== 'object') return { value: payload, message: String(payload) };

package/src/core/UIOverlay.js

@@ -255,6 +255,39 @@ const STYLES = `
 .bl-adapters:empty {
   display: none;
 }
+.bl-hotkeys {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+}
+.bl-hotkeys:empty {
+  display: none;
+}
+.bl-detail {
+  max-height: 132px;
+  overflow: auto;
+  background: #07080c;
+  border-top: 1px solid rgba(255, 59, 78, 0.22);
+}
+.bl-detail[hidden] {
+  display: none;
+}
+.bl-detail button {
+  display: block;
+  width: 100%;
+  margin: 0;
+  padding: 4px 10px;
+  border: 0;
+  background: transparent;
+  color: #d8dce6;
+  font: 11px ui-monospace, Consolas, monospace;
+  line-height: 1.4;
+  text-align: left;
+  cursor: pointer;
+}
+.bl-detail button[data-level="warn"] { color: #ffd36a; }
+.bl-detail button[data-level="error"] { color: #ff6b7d; }
+.bl-detail button:hover { background: rgba(255, 255, 255, 0.04); }
 .bl-adapter {
   appearance: none;
   background: #16181f;
@@ -331,6 +364,8 @@ export class UIOverlay {
         this.#mounted = false;
         this.#providerSig = '';
         this.#adapterSig = '';
+        this.#hotkeySig = '';
+        this.#detail = [];
         this.#flashAt = new Map();
         this.#flashTimers = new Map();
     }
@@ -343,6 +378,8 @@ export class UIOverlay {
     #mounted;
     #providerSig;
     #adapterSig;
+    #hotkeySig;
+    #detail;
     #flashAt;
     #flashTimers;
 
@@ -393,11 +430,13 @@ export class UIOverlay {
                   </div>
                 </div>
                 <div class="bl-hud" data-el="hud"></div>
+                <div class="bl-detail" data-el="detail" hidden></div>
                 <div class="bl-console" data-el="console" role="log" aria-live="polite"></div>
                 <div class="bl-foot">
                   <button class="bl-btn" data-act="slow" type="button">F3 SLOW</button>
                   <button class="bl-btn" data-act="freeze" type="button">F4 STOP</button>
                   <button class="bl-btn" data-act="live" type="button">1x LIVE</button>
+                  <span class="bl-hotkeys" data-el="hotkeys"></span>
                   <button class="bl-btn" data-act="ask" type="button">ASK AI</button>
                   <span class="bl-providers" data-el="providers"></span>
                   <span class="bl-adapters" data-el="adapters"></span>
@@ -419,8 +458,10 @@ export class UIOverlay {
             graphStats: this.#root.querySelector('[data-el="graphStats"]'),
             hud: this.#root.querySelector('[data-el="hud"]'),
             console: this.#root.querySelector('[data-el="console"]'),
+            detail: this.#root.querySelector('[data-el="detail"]'),
             providers: this.#root.querySelector('[data-el="providers"]'),
-            adapters: this.#root.querySelector('[data-el="adapters"]')
+            adapters: this.#root.querySelector('[data-el="adapters"]'),
+            hotkeys: this.#root.querySelector('[data-el="hotkeys"]')
         };
 
         this.#root.querySelector('.bl-foot').addEventListener('click', (event) => {
@@ -435,6 +476,13 @@ export class UIOverlay {
             else if (act === 'adapter') this.core.toggleAdapter(btn.getAttribute('data-name'));
         });
 
+        this.#root.querySelector('.bl-detail')?.addEventListener('click', (event) => {
+            const row = event.target.closest('[data-detail]');
+            if (!row) return;
+            const item = this.#detail[Number(row.getAttribute('data-detail'))];
+            if (item && typeof item.onSelect === 'function') item.onSelect();
+        });
+
         this.#els.console.addEventListener('scroll', () => {
             const el = this.#els.console;
             this.#stickBottom = el.scrollHeight - el.scrollTop - el.clientHeight < 24;
@@ -456,6 +504,8 @@ export class UIOverlay {
         this.#mounted = false;
         this.#providerSig = '';
         this.#adapterSig = '';
+        this.#hotkeySig = '';
+        this.#detail = [];
         this.#clearFlashTimers();
         this.#flashAt.clear();
         return this;
@@ -473,6 +523,29 @@ export class UIOverlay {
         return this;
     }
 
+    /**
+     * @param {Array<{ text: string, level?: string, onSelect?: () => void }>} items
+     */
+    setDetail(items) {
+        if (!this.#els?.detail) return this;
+        const list = Array.isArray(items) ? items : [];
+        this.#detail = list;
+        const box = this.#els.detail;
+        if (!list.length) {
+            box.innerHTML = '';
+            box.hidden = true;
+            return this;
+        }
+        let html = '';
+        for (let i = 0; i < list.length; i++) {
+            const level = list[i].level === 'error' || list[i].level === 'warn' ? list[i].level : 'info';
+            html += `<button type="button" data-detail="${i}" data-level="${level}">${escapeHtml(list[i].text)}</button>`;
+        }
+        box.hidden = false;
+        box.innerHTML = html;
+        return this;
+    }
+
     onPacket(packet) {
         if (!this.#els || !packet) return;
         if (packet.type === 'sys') return;
@@ -508,6 +581,7 @@ export class UIOverlay {
         this.#renderHud(state.hud);
         this.#syncButtons(state);
         this.#syncProviders(state);
+        this.#syncHotkeys(state);
         this.#syncAdapters(state);
 
         if (this.#stickBottom) {
@@ -584,10 +658,26 @@ export class UIOverlay {
         wrap.innerHTML = html;
     }
 
+    #syncHotkeys(state) {
+        const wrap = this.#els.hotkeys;
+        if (!wrap) return;
+        const list = (Array.isArray(state.adapters) ? state.adapters : []).filter((entry) => entry.hotkey);
+        const sig = list.map((entry) => `${entry.name}\0${entry.label}\0${entry.enabled ? 1 : 0}`).join('\n');
+        if (sig === this.#hotkeySig) return;
+        this.#hotkeySig = sig;
+        let html = '';
+        for (let i = 0; i < list.length; i++) {
+            const entry = list[i];
+            const hot = entry.enabled ? 'true' : 'false';
+            html += `<button class="bl-btn" data-act="adapter" data-name="${escapeHtml(entry.name)}" data-hot="${hot}" type="button">${escapeHtml(entry.label)}</button>`;
+        }
+        wrap.innerHTML = html;
+    }
+
     #syncAdapters(state) {
         const wrap = this.#els.adapters;
         if (!wrap) return;
-        const list = Array.isArray(state.adapters) ? state.adapters : [];
+        const list = (Array.isArray(state.adapters) ? state.adapters : []).filter((entry) => !entry.hotkey);
         const sig = list.map((entry) => `${entry.name}\0${entry.label}\0${entry.enabled ? 1 : 0}`).join('\n');
         if (sig === this.#adapterSig) return;
         this.#adapterSig = sig;

package/src/index.d.ts

@@ -112,11 +112,14 @@ export interface AdapterHooks {
     enable(): void;
     disable(): void;
     label?: string;
+    hotkey?: string;
+    enabled?: boolean;
 }
 
 export interface AdapterInfo {
     name: string;
     label: string;
+    hotkey: string;
     enabled: boolean;
 }
 
@@ -174,6 +177,13 @@ export class BeeLadybugCore {
     getAdapters(): AdapterInfo[];
     toggleAdapter(name: string): this;
     setAdapterEnabled(name: string, enabled: boolean): this;
+    publishDetail(items: DetailItem[]): this;
+}
+
+export interface DetailItem {
+    text: string;
+    level?: 'info' | 'warn' | 'error';
+    onSelect?: () => void;
 }
 
 export class UIOverlay {
@@ -186,6 +196,7 @@ export class UIOverlay {
     onPacket(packet: BeePacket): void;
     onClear(channel?: string): void;
     render(): void;
+    setDetail(items: DetailItem[]): this;
 }
 
 export interface CanvasEntity {
@@ -272,6 +283,30 @@ export class WebDOMAdapter {
     pump(): this;
 }
 
+export interface CSSAdapterOptions {
+    source?: string;
+    hotkey?: string;
+    scanKey?: string;
+    label?: string;
+    maxScan?: number;
+}
+
+export const CSS_ADAPTER_DEFAULTS: Required<CSSAdapterOptions>;
+
+export class CSSAdapter {
+    core: BeeLadybugCore | null;
+    source: string;
+    hotkey: string;
+    scanKey: string;
+    label: string;
+    maxScan: number;
+    readonly active: boolean;
+    constructor(core: BeeLadybugCore, options?: CSSAdapterOptions);
+    attach(): this;
+    detach(): this;
+    scan(): this;
+}
+
 export interface AntAdapterOptions {
     root?: ParentNode | null;
     threshold?: number;

package/src/index.js

@@ -2,6 +2,7 @@ export { BeeLadybugCore, BEE_LADYBUG_VERSION, CORE_DEFAULTS, WELL_KNOWN_TYPES, f
 export { UIOverlay } from './core/UIOverlay.js';
 export { CanvasAdapter, CANVAS_ADAPTER_DEFAULTS } from './adapters/CanvasAdapter.js';
 export { WebDOMAdapter, WEB_DOM_ADAPTER_DEFAULTS } from './adapters/WebDOMAdapter.js';
+export { CSSAdapter, CSS_ADAPTER_DEFAULTS } from './adapters/CSSAdapter.js';
 export { AntAdapter, ANT_ADAPTER_DEFAULTS } from './adapters/AntAdapter.js';
 export { SpiderAdapter, SPIDER_ADAPTER_DEFAULTS } from './adapters/SpiderAdapter.js';
 export { PythonBridge, PYTHON_BRIDGE_DEFAULTS } from './adapters/python/PythonBridge.js';