bee-ladybug 0.5.0 → 0.5.2

package/README.MD

@@ -134,7 +134,8 @@ bee.subscribe((packet) => {
 | `F3` | slow-motion del tempo fittizio (`0.25x` / `1x`) |
 | `F4` | freeze / run del tempo fittizio |
 | `F6` | CSS hunt, se `CSSAdapter` è attaccato |
-| `S` | scansione overflow / immagini, solo con la hunt accesa |
+| `P` | blocca il pannello CSS sull'elemento corrente, solo con la hunt accesa |
+| `S` | scansione CSS, solo con la hunt accesa |
 
 Niente `F12`, niente tilde: sui layout italiani la tilde non è un tasto unico.
 
@@ -198,9 +199,9 @@ css.attach();
 - 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`
+- `<img>` con rapporto del file diverso di oltre il 5% dal riquadro disegnato (`getBoundingClientRect`), solo se `object-fit` calcolato è `fill` (il default)
 
-`S` con la hunt accesa esegue overflow e immagini su tutta la pagina e lista i casi peggiori. Un click sulla riga disegna il contorno rosso. I fogli di stile restano in cache finché un `MutationObserver` non vede un cambio a `<style>` o `<link>`. Hover è limitato a un frame.
+`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. `P` ferma il pannello sull'elemento corrente, così si può leggere. In cima all'overlay, la lista **Issues** tiene gli avvisi rossi (click bloccato e causa di overflow): al massimo 10, il più recente in alto, e non scorre via con la console. In console un elemento pulito non viene scritto, e con la hunt accesa restano fuori anche `hover` e `mutate attr` del DOM, a meno che `F3` SLOW sia acceso. Ogni problema CSS viene scritto una sola volta per elemento ogni 5 secondi. 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`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bee-ladybug",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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

@@ -15,8 +15,11 @@ export const CSS_ADAPTER_DEFAULTS = Object.freeze({
     source: 'css',
     hotkey: 'F6',
     scanKey: 'KeyS',
+    pinKey: 'KeyP',
     label: 'F6 CSS',
-    maxScan: 8
+    maxScan: 8,
+    issueWindow: 5000,
+    maxIssues: 10
 });
 
 export class CSSAdapter {
@@ -30,8 +33,11 @@ export class CSSAdapter {
         this.source = cfg.source;
         this.hotkey = cfg.hotkey;
         this.scanKey = cfg.scanKey;
+        this.pinKey = cfg.pinKey;
         this.label = cfg.label;
         this.maxScan = cfg.maxScan;
+        this.issueWindow = cfg.issueWindow;
+        this.maxIssues = cfg.maxIssues;
 
         this.#attached = false;
         this.#active = false;
@@ -43,6 +49,9 @@ export class CSSAdapter {
         this.#rafId = 0;
         this.#lastEl = null;
         this.#pinned = null;
+        this.#panelLock = false;
+        this.#issues = [];
+        this.#issueLog = new Map();
         this.#hoverBox = null;
         this.#pinBox = null;
         this.#observer = null;
@@ -70,6 +79,9 @@ export class CSSAdapter {
     #rafId;
     #lastEl;
     #pinned;
+    #panelLock;
+    #issues;
+    #issueLog;
     #hoverBox;
     #pinBox;
     #observer;
@@ -94,7 +106,7 @@ export class CSSAdapter {
         });
         this.core?.sendData('log', {
             source: this.source,
-            message: 'CSSAdapter attached. F6 CSS hunt. S scans the page while hunt is on.'
+            message: 'CSSAdapter attached. F6 CSS hunt. S scans. P pins the panel.'
         });
         this.core?.sendData('state', {
             source: this.source,
@@ -112,43 +124,63 @@ export class CSSAdapter {
         return this;
     }
 
-    /** Checks 2 and 5 across the document. Click a row to outline it. */
+    /** 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 offenders = [];
+        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 = [];
-            pushOverflow(el, findings);
+            pushNegativeMargins(el, findings);
+            pushInvisible(el, findings);
+            pushBlockers(el, findings);
             pushImage(el, findings);
-            if (!findings.length) continue;
-            let score = 0;
-            for (let j = 0; j < findings.length; j++) score += findings[j].score;
-            offenders.push({ el, findings, score });
+            pushImportant(el, this.#rules, findings);
+            for (let j = 0; j < findings.length; j++) {
+                rows.push({ el, selector: cssPath(el), ...findings[j] });
+            }
         }
-        offenders.sort((a, b) => b.score - a.score);
-        const top = offenders.slice(0, this.maxScan);
-        const items = top.map((entry) => ({
-            level: 'error',
-            text: `${cssPath(entry.el)} — ${entry.findings.map((hit) => hit.text).join('; ')}`,
-            onSelect: () => this.#pin(entry.el)
+        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);
+        for (let i = groups.length - 1; i >= 0; i--) this.#stickGroup(groups[i]);
+        const shown = groups.slice(0, this.maxScan);
+        const items = shown.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(top.length)
-        });
-        this.core?.sendData('warn', {
-            source: this.source,
-            message: top.length
-                ? `scan ${top.length} offender(s). Click a row to outline it.`
-                : 'scan clean: no overflow or distorted images.'
+            value: String(shown.length)
         });
+        if (shown.length || isVerbose(this.core)) {
+            this.core?.sendData('warn', {
+                source: this.source,
+                message: shown.length
+                    ? `scan ${shown.length} issue(s). Click a row to outline it.`
+                    : 'scan clean: no causes found.'
+            });
+        }
         return this;
     }
 
@@ -175,7 +207,7 @@ export class CSSAdapter {
         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.'
+            message: 'CSS hunt on. Hover an element, P pins the panel, S scans.'
         });
     }
 
@@ -194,17 +226,27 @@ export class CSSAdapter {
         this.#observer = null;
         this.#lastEl = null;
         this.#pinned = null;
+        this.#panelLock = false;
+        this.#issues = [];
+        this.#issueLog.clear();
         this.#unmountBoxes();
         this.core?.publishDetail([]);
+        this.core?.publishIssues([]);
         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;
+        if (event.code === this.pinKey) {
+            event.preventDefault();
+            this.#togglePanelPin();
+            return;
+        }
+        if (event.code !== this.scanKey) return;
         event.preventDefault();
+        this.#panelLock = false;
         this.scan();
     }
 
@@ -234,6 +276,7 @@ export class CSSAdapter {
     #inspect(x, y) {
         const el = pickElement(x, y);
         placeBox(this.#hoverBox, el);
+        if (this.#panelLock) return;
         if (el === this.#lastEl) return;
         this.#lastEl = el;
         if (!el) {
@@ -266,15 +309,80 @@ export class CSSAdapter {
             text: `${path}  ${hit.text}`,
             onSelect: () => this.#pin(el)
         })));
+        this.#stickFindings(el, path, findings);
         if (!findings.length) {
-            this.core?.sendData('log', { source: this.source, message: `${path}  clean` });
+            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}`
-        });
+        this.#logFindings(path, findings);
+    }
+
+    #togglePanelPin() {
+        if (this.#panelLock) {
+            this.#panelLock = false;
+            this.#pinned = null;
+            placeBox(this.#pinBox, null);
+            this.core?.sendData('state', { source: this.source, key: 'css.pin', value: 'off' });
+            this.core?.sendData('log', { source: this.source, message: 'CSS pin off.' });
+            this.#lastEl = null;
+            this.#schedule();
+            return;
+        }
+        const el = this.#lastEl;
+        if (!el) return;
+        this.#panelLock = true;
+        this.#pin(el);
+        const path = cssPath(el);
+        this.core?.sendData('state', { source: this.source, key: 'css.pin', value: path });
+        this.core?.sendData('log', { source: this.source, message: `CSS pin ${path}` });
+    }
+
+    #logFindings(path, findings) {
+        const now = nowMs();
+        for (let i = 0; i < findings.length; i++) {
+            const hit = findings[i];
+            const text = hit.text || hit.kind || '';
+            if (!text) continue;
+            if (!rememberIssue(this.#issueLog, `${path}\0${text}`, now, this.issueWindow)) continue;
+            const level = hit.level === 'error' ? 'error' : 'warn';
+            this.core?.sendData(level, {
+                source: this.source,
+                message: `${path}  ${text}`
+            });
+        }
+    }
+
+    #stickFindings(el, path, findings) {
+        for (let i = 0; i < findings.length; i++) {
+            const hit = findings[i];
+            if (!isStickyKind(hit.kind)) continue;
+            if (hit.kind === 'overflows viewport' && !elementCausesOverflow(el)) continue;
+            this.#issues = pushStickyIssue(this.#issues, {
+                text: `${path} ${hit.kind}`,
+                el
+            }, this.maxIssues);
+        }
+        this.#publishIssues();
+    }
+
+    #stickGroup(group) {
+        if (!isStickyKind(group.kind)) return;
+        const count = group.count > 1 ? ` ×${group.count}` : '';
+        this.#issues = pushStickyIssue(this.#issues, {
+            text: `${group.selector} ${group.kind}${count}`,
+            el: group.el
+        }, this.maxIssues);
+        this.#publishIssues();
+    }
+
+    #publishIssues() {
+        this.core?.publishIssues(this.#issues.map((item) => ({
+            level: 'error',
+            text: item.text,
+            onSelect: () => this.#pin(item.el)
+        })));
     }
 
     #pin(el) {
@@ -380,7 +488,9 @@ function pushImportant(el, rules, findings) {
             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}`
             });
         }
@@ -388,19 +498,75 @@ function pushImportant(el, rules, findings) {
 }
 
 function pushOverflow(el, findings) {
-    if (!el.getBoundingClientRect || el === document.documentElement || el === document.body) return;
-    const rect = el.getBoundingClientRect();
-    const view = document.documentElement.clientWidth;
-    if (rect.left < -1 || rect.right > view + 1) {
-        const past = rect.left < -1
-            ? `left ${Math.round(rect.left)}px`
-            : `right +${Math.round(rect.right - view)}px`;
+    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',
-            score: Math.abs(rect.left < -1 ? rect.left : rect.right - view),
+            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++) {
@@ -409,26 +575,64 @@ function pushOverflow(el, findings) {
         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({ level: 'error', score: 30, text: 'invisible text (opacity 0)' });
+        findings.push(issue('invisible text (opacity 0)', ISSUE_RANK.invisible, 30));
     }
     const color = parseColor(style.color);
     if (!color || color.a === 0) {
-        findings.push({ level: 'error', score: 30, text: 'invisible text (transparent color)' });
+        findings.push(issue('invisible text (transparent color)', ISSUE_RANK.invisible, 30));
         return;
     }
     const behind = paintBehind(el);
     if (behind && nearlySame(color, behind)) {
-        findings.push({ level: 'error', score: 30, text: 'invisible text (color matches background)' });
+        findings.push(issue('invisible text (color matches background)', ISSUE_RANK.invisible, 30));
     }
 }
 
@@ -440,33 +644,111 @@ function pushBlockers(el, findings) {
     if (x < 0 || y < 0 || x > window.innerWidth || y > window.innerHeight) return;
     const pseudo = coveringPseudo(x, y);
     if (pseudo) {
-        findings.push({ level: 'error', score: 40, text: `click blocked by ${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({ level: 'error', score: 40, text: `click blocked by ${cssPath(hit)}` });
+    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;
+    if (!naturalW || !naturalH || typeof el.getBoundingClientRect !== 'function') return;
+    const rect = el.getBoundingClientRect();
+    const fit = (typeof getComputedStyle === 'function' ? getComputedStyle(el).objectFit : '') || 'fill';
+    if (!isDistortedImage(naturalW, naturalH, rect.width, rect.height, fit)) return;
+    const gap = renderedRatioGap(naturalW, naturalH, rect.width, rect.height);
     findings.push({
         level: 'error',
-        score: diff * 100,
-        text: `distorted image ${Math.round(diff * 100)}% (object-fit: fill)`
+        rank: ISSUE_RANK.image,
+        score: gap * 100,
+        kind: 'distorted image',
+        text: `distorted image ${Math.round(gap * 100)}% (object-fit: fill)`
     });
 }
 
+/**
+ * Rendered box versus the file. Attributes and clientWidth are ignored.
+ * `object-fit` defaults to fill. Flag when the ratios differ by more than 5%.
+ */
+export function isDistortedImage(naturalW, naturalH, renderedW, renderedH, objectFit) {
+    const fit = objectFit || 'fill';
+    if (fit !== 'fill') return false;
+    return renderedRatioGap(naturalW, naturalH, renderedW, renderedH) > 0.05;
+}
+
+export function renderedRatioGap(naturalW, naturalH, renderedW, renderedH) {
+    if (!naturalW || !naturalH || !renderedW || !renderedH) return 0;
+    const natural = naturalW / naturalH;
+    const rendered = renderedW / renderedH;
+    return Math.abs(natural - rendered) / natural;
+}
+
+/** @returns {boolean} true when this issue should be written to the event list */
+export function rememberIssue(seen, key, now, windowMs = 5000) {
+    const prev = seen.get(key);
+    if (typeof prev === 'number' && now - prev < windowMs) return false;
+    seen.set(key, now);
+    if (seen.size > 64) {
+        for (const [name, at] of seen) {
+            if (now - at >= windowMs) seen.delete(name);
+        }
+    }
+    return true;
+}
+
+/**
+ * Newest first, duplicates move to the top, capped at `max`.
+ * @param {Array<{ text: string, el?: Element }>} list
+ * @param {{ text: string, el?: Element }} entry
+ */
+export function pushStickyIssue(list, entry, max = 10) {
+    const next = [entry];
+    for (let i = 0; i < list.length; i++) {
+        if (list[i].text === entry.text) continue;
+        next.push(list[i]);
+        if (next.length >= max) break;
+    }
+    return next.slice(0, max);
+}
+
+function isStickyKind(kind) {
+    return kind === 'overflows viewport' || (typeof kind === 'string' && kind.startsWith('click blocked'));
+}
+
+function elementCausesOverflow(el) {
+    const self = measureViewportOverflow(el);
+    if (!self) return false;
+    const items = [self];
+    if (typeof el.querySelectorAll === 'function') {
+        const nodes = el.querySelectorAll('*');
+        for (let i = 0; i < nodes.length; i++) {
+            const measured = measureViewportOverflow(nodes[i]);
+            if (measured) items.push(measured);
+        }
+    }
+    const causes = keepOverflowCauses(items);
+    for (let i = 0; i < causes.length; i++) {
+        if (causes[i].el === el) return true;
+    }
+    return false;
+}
+
+function nowMs() {
+    return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}
+
+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'];

package/src/adapters/WebDOMAdapter.js

@@ -279,10 +279,12 @@ export class WebDOMAdapter {
 
         if (key !== this.#lastHoverKey) {
             this.#lastHoverKey = key;
-            this.core.sendData('log', {
-                source: this.source,
-                message: `hover ${key}  ${Math.round(model.border.w)}×${Math.round(model.border.h)}  ${model.display}`
-            });
+            if (!domNoiseQuiet(cssHuntEnabled(this.core), this.frozen, this.timeScale)) {
+                this.core.sendData('log', {
+                    source: this.source,
+                    message: `hover ${key}  ${Math.round(model.border.w)}×${Math.round(model.border.h)}  ${model.display}`
+                });
+            }
         }
     }
 
@@ -313,14 +315,17 @@ export class WebDOMAdapter {
         this.#mutRemoved = 0;
         this.#mutAttr = 0;
         if (!added && !removed && !attr) return;
+        const quiet = domNoiseQuiet(cssHuntEnabled(this.core), this.frozen, this.timeScale);
         const parts = [];
         if (added) parts.push(`+${added}`);
         if (removed) parts.push(`-${removed}`);
-        if (attr) parts.push(`attr ${attr}`);
-        this.core?.sendData('warn', {
-            source: this.source,
-            message: `mutate ${parts.join(' ')}`
-        });
+        if (attr && !quiet) parts.push(`attr ${attr}`);
+        if (parts.length) {
+            this.core?.sendData('warn', {
+                source: this.source,
+                message: `mutate ${parts.join(' ')}`
+            });
+        }
         this.core?.sendData('metric', {
             name: 'mutations',
             value: added + removed + attr,
@@ -504,3 +509,21 @@ function countElements(root) {
     if (root.nodeType === 1) return 1 + (root.getElementsByTagName?.('*').length ?? 0);
     return root.getElementsByTagName?.('*').length ?? 0;
 }
+
+/**
+ * While CSS hunt is on, hover and attribute-mutation lines stay quiet
+ * unless F3 SLOW is running.
+ */
+export function domNoiseQuiet(cssEnabled, frozen, timeScale) {
+    if (!cssEnabled) return false;
+    return Boolean(frozen) || timeScale === 1;
+}
+
+function cssHuntEnabled(core) {
+    if (!core || typeof core.getAdapters !== 'function') return false;
+    const list = core.getAdapters();
+    for (let i = 0; i < list.length; i++) {
+        if (list[i].name === 'css' && list[i].enabled) return true;
+    }
+    return false;
+}

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.5.0';
+export const BEE_LADYBUG_VERSION = '0.5.2';
 
 export const CORE_DEFAULTS = Object.freeze({
     toggleKey: 'F2',
@@ -99,6 +99,7 @@ export class BeeLadybugCore {
         this.#askBusy = false;
         this.#adapters = new Map();
         this.#detail = [];
+        this.#issues = [];
 
         this.ui = null;
         if (cfg.ui !== false && typeof document !== 'undefined') {
@@ -135,6 +136,8 @@ export class BeeLadybugCore {
     #askBusy;
     /** @type {Array<{ text: string, level?: string, onSelect?: () => void }>} */
     #detail;
+    /** @type {Array<{ text: string, level?: string, onSelect?: () => void }>} */
+    #issues;
     /** @type {Map<string, { name: string, label: string, enabled: boolean, enable: Function, disable: Function }>} */
     #adapters;
 
@@ -356,6 +359,17 @@ export class BeeLadybugCore {
         return this;
     }
 
+    /**
+     * Sticky red warnings. The core does not interpret them.
+     * @param {Array<{ text: string, level?: string, onSelect?: () => void }>} items
+     */
+    publishIssues(items) {
+        const list = Array.isArray(items) ? items.slice(0, 10) : [];
+        this.#issues = list;
+        this.ui?.setIssues(this.#issues);
+        return this;
+    }
+
     /**
      * @param {string} name
      */
@@ -463,6 +477,7 @@ export class BeeLadybugCore {
         this.#askBusy = false;
         this.#adapters.clear();
         this.#detail = [];
+        this.#issues = [];
         this.ui?.destroy();
         this.ui = null;
         return this;

package/src/core/UIOverlay.js

@@ -263,6 +263,35 @@ const STYLES = `
 .bl-hotkeys:empty {
   display: none;
 }
+.bl-issues {
+  overflow: hidden;
+  background: #07080c;
+  border-top: 1px solid rgba(255, 59, 78, 0.55);
+}
+.bl-issues[hidden] {
+  display: none;
+}
+.bl-issues-label {
+  padding: 5px 10px 0;
+  color: #ff3b4e;
+  font-size: 9px;
+  font-weight: 700;
+  letter-spacing: 0.14em;
+}
+.bl-issues button {
+  display: block;
+  width: 100%;
+  margin: 0;
+  padding: 3px 10px;
+  border: 0;
+  background: transparent;
+  color: #ff6b7d;
+  font: 11px ui-monospace, Consolas, monospace;
+  line-height: 1.4;
+  text-align: left;
+  cursor: pointer;
+}
+.bl-issues button:hover { background: rgba(255, 59, 78, 0.08); }
 .bl-detail {
   max-height: 132px;
   overflow: auto;
@@ -366,6 +395,7 @@ export class UIOverlay {
         this.#adapterSig = '';
         this.#hotkeySig = '';
         this.#detail = [];
+        this.#issues = [];
         this.#flashAt = new Map();
         this.#flashTimers = new Map();
     }
@@ -380,6 +410,7 @@ export class UIOverlay {
     #adapterSig;
     #hotkeySig;
     #detail;
+    #issues;
     #flashAt;
     #flashTimers;
 
@@ -430,6 +461,10 @@ export class UIOverlay {
                   </div>
                 </div>
                 <div class="bl-hud" data-el="hud"></div>
+                <div class="bl-issues" data-el="issues" hidden>
+                  <div class="bl-issues-label">ISSUES</div>
+                  <div data-el="issues-list"></div>
+                </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">
@@ -459,6 +494,8 @@ export class UIOverlay {
             hud: this.#root.querySelector('[data-el="hud"]'),
             console: this.#root.querySelector('[data-el="console"]'),
             detail: this.#root.querySelector('[data-el="detail"]'),
+            issues: this.#root.querySelector('[data-el="issues"]'),
+            issuesList: this.#root.querySelector('[data-el="issues-list"]'),
             providers: this.#root.querySelector('[data-el="providers"]'),
             adapters: this.#root.querySelector('[data-el="adapters"]'),
             hotkeys: this.#root.querySelector('[data-el="hotkeys"]')
@@ -476,6 +513,13 @@ export class UIOverlay {
             else if (act === 'adapter') this.core.toggleAdapter(btn.getAttribute('data-name'));
         });
 
+        this.#root.querySelector('.bl-issues')?.addEventListener('click', (event) => {
+            const row = event.target.closest('[data-issue]');
+            if (!row) return;
+            const item = this.#issues[Number(row.getAttribute('data-issue'))];
+            if (item && typeof item.onSelect === 'function') item.onSelect();
+        });
+
         this.#root.querySelector('.bl-detail')?.addEventListener('click', (event) => {
             const row = event.target.closest('[data-detail]');
             if (!row) return;
@@ -506,6 +550,7 @@ export class UIOverlay {
         this.#adapterSig = '';
         this.#hotkeySig = '';
         this.#detail = [];
+        this.#issues = [];
         this.#clearFlashTimers();
         this.#flashAt.clear();
         return this;
@@ -546,6 +591,29 @@ export class UIOverlay {
         return this;
     }
 
+    /**
+     * Red warnings pinned above the scrolling console. Newest first.
+     * @param {Array<{ text: string, level?: string, onSelect?: () => void }>} items
+     */
+    setIssues(items) {
+        if (!this.#els?.issues || !this.#els.issuesList) return this;
+        const list = Array.isArray(items) ? items.slice(0, 10) : [];
+        this.#issues = list;
+        const box = this.#els.issues;
+        if (!list.length) {
+            this.#els.issuesList.innerHTML = '';
+            box.hidden = true;
+            return this;
+        }
+        let html = '';
+        for (let i = 0; i < list.length; i++) {
+            html += `<button type="button" data-issue="${i}">${escapeHtml(list[i].text)}</button>`;
+        }
+        box.hidden = false;
+        this.#els.issuesList.innerHTML = html;
+        return this;
+    }
+
     onPacket(packet) {
         if (!this.#els || !packet) return;
         if (packet.type === 'sys') return;

package/src/index.d.ts

@@ -178,6 +178,7 @@ export class BeeLadybugCore {
     toggleAdapter(name: string): this;
     setAdapterEnabled(name: string, enabled: boolean): this;
     publishDetail(items: DetailItem[]): this;
+    publishIssues(items: DetailItem[]): this;
 }
 
 export interface DetailItem {
@@ -197,6 +198,7 @@ export class UIOverlay {
     onClear(channel?: string): void;
     render(): void;
     setDetail(items: DetailItem[]): this;
+    setIssues(items: DetailItem[]): this;
 }
 
 export interface CanvasEntity {
@@ -287,8 +289,11 @@ export interface CSSAdapterOptions {
     source?: string;
     hotkey?: string;
     scanKey?: string;
+    pinKey?: string;
     label?: string;
     maxScan?: number;
+    issueWindow?: number;
+    maxIssues?: number;
 }
 
 export const CSS_ADAPTER_DEFAULTS: Required<CSSAdapterOptions>;
@@ -298,8 +303,11 @@ export class CSSAdapter {
     source: string;
     hotkey: string;
     scanKey: string;
+    pinKey: string;
     label: string;
     maxScan: number;
+    issueWindow: number;
+    maxIssues: number;
     readonly active: boolean;
     constructor(core: BeeLadybugCore, options?: CSSAdapterOptions);
     attach(): this;