bee-ladybug 0.5.1 → 0.5.3

package/README.MD

@@ -134,6 +134,7 @@ bee.subscribe((packet) => {
 | `F3` | slow-motion del tempo fittizio (`0.25x` / `1x`) |
 | `F4` | freeze / run del tempo fittizio |
 | `F6` | CSS hunt, se `CSSAdapter` è attaccato |
+| `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.
@@ -194,13 +195,13 @@ 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>`)
+- regole `!important` che gli corrispondono. Un foglio cross-origin è una nota grigia, una volta sola: `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`
+- `<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 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.
+`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. **Issues** raggruppa per causa: `body::after blocks clicks on 10 elements` è una riga rossa, e il click la apre sull'elenco degli elementi. In cima alla sezione, la legenda dice rosso = bug e grigio = info. Un foglio illeggibile è una riga grigia, una per foglio, e non entra tra i bug. L'overlay resta alto al massimo metà schermo, scorre al suo interno, e le sezioni Status, Issues, Inspect ed Events si chiudono. 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.1",
+  "version": "0.5.3",
   "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,19 +33,26 @@ 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;
         this.#rules = [];
-        this.#unreadable = [];
         this.#sheetsDirty = true;
         this.#x = 0;
         this.#y = 0;
         this.#rafId = 0;
         this.#lastEl = null;
         this.#pinned = null;
+        this.#panelLock = false;
+        this.#issues = [];
+        this.#notes = [];
+        this.#seenSheets = new Set();
+        this.#issueLog = new Map();
         this.#hoverBox = null;
         this.#pinBox = null;
         this.#observer = null;
@@ -63,13 +73,17 @@ export class CSSAdapter {
     #attached;
     #active;
     #rules;
-    #unreadable;
     #sheetsDirty;
     #x;
     #y;
     #rafId;
     #lastEl;
     #pinned;
+    #panelLock;
+    #issues;
+    #notes;
+    #seenSheets;
+    #issueLog;
     #hoverBox;
     #pinBox;
     #observer;
@@ -94,7 +108,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,
@@ -146,8 +160,14 @@ export class CSSAdapter {
                 score: cause.score
             });
         }
-        const groups = groupIssues(rows).slice(0, this.maxScan);
-        const items = groups.map((group) => ({
+        const groups = groupIssues(rows);
+        for (let i = 0; i < rows.length; i++) {
+            const row = rows[i];
+            this.#rememberCause(row.el, row.selector, row.kind);
+        }
+        this.#publishIssues();
+        const shown = groups.slice(0, this.maxScan);
+        const items = shown.map((group) => ({
             level: group.level,
             text: formatIssue(group),
             onSelect: () => this.#pin(group.el)
@@ -157,13 +177,13 @@ export class CSSAdapter {
         this.core?.sendData('state', {
             source: this.source,
             key: 'css.scan',
-            value: String(groups.length)
+            value: String(shown.length)
         });
-        if (groups.length || isVerbose(this.core)) {
+        if (shown.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.`
+                message: shown.length
+                    ? `scan ${shown.length} issue(s). Click a row to outline it.`
                     : 'scan clean: no causes found.'
             });
         }
@@ -193,7 +213,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.'
         });
     }
 
@@ -212,17 +232,29 @@ export class CSSAdapter {
         this.#observer = null;
         this.#lastEl = null;
         this.#pinned = null;
+        this.#panelLock = false;
+        this.#issues = [];
+        this.#notes = [];
+        this.#seenSheets.clear();
+        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();
     }
 
@@ -240,18 +272,14 @@ export class CSSAdapter {
         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]}`
-            });
-        }
+        for (let i = 0; i < built.unreadable.length; i++) this.#rememberSheet(built.unreadable[i]);
+        this.#publishIssues();
     }
 
     #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) {
@@ -265,13 +293,6 @@ export class CSSAdapter {
         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', {
@@ -284,19 +305,98 @@ export class CSSAdapter {
             text: `${path}  ${hit.text}`,
             onSelect: () => this.#pin(el)
         })));
+        this.#stickFindings(el, path, findings);
         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', {
+        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 || text.startsWith('unreadable sheet:')) 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) {
+        let changed = false;
+        for (let i = 0; i < findings.length; i++) {
+            const hit = findings[i];
+            if (hit.kind === 'overflows viewport' && !elementCausesOverflow(el)) continue;
+            if (this.#rememberCause(el, path, hit.kind)) changed = true;
+        }
+        if (changed) this.#publishIssues();
+    }
+
+    #rememberCause(el, path, kind) {
+        const next = addCause(this.#issues, { kind, path, el }, this.maxIssues);
+        if (next === this.#issues) return false;
+        this.#issues = next;
+        return true;
+    }
+
+    #rememberSheet(href) {
+        const label = String(href || '');
+        if (!label || this.#seenSheets.has(label)) return;
+        this.#seenSheets.add(label);
+        this.#notes.push({ text: `unreadable sheet: ${label}` });
+        this.core?.sendData('log', {
             source: this.source,
-            message: `${path}  ${lead.text}`
+            level: 'info',
+            message: `unreadable sheet: ${label}`
         });
     }
 
+    #publishIssues() {
+        const bugs = this.#issues.map((entry) => ({
+            level: 'error',
+            key: entry.key,
+            text: formatCause(entry),
+            targets: entry.targets.map((target) => ({
+                text: target.text,
+                onSelect: () => this.#pin(target.el)
+            }))
+        }));
+        const notes = this.#notes.map((note) => ({
+            level: 'info',
+            key: note.text,
+            text: note.text
+        }));
+        this.core?.publishIssues(bugs.concat(notes));
+    }
+
     #pin(el) {
         this.#pinned = el;
         placeBox(this.#pinBox, el);
@@ -568,23 +668,140 @@ 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',
         rank: ISSUE_RANK.image,
-        score: diff * 100,
+        score: gap * 100,
         kind: 'distorted image',
-        text: `distorted image ${Math.round(diff * 100)}% (object-fit: fill)`
+        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);
+}
+
+export function describeCause(kind, path) {
+    if (kind === 'overflows viewport') {
+        return { key: `overflow\0${path}`, type: 'overflow', cause: path };
+    }
+    const prefix = 'click blocked by ';
+    if (typeof kind === 'string' && kind.startsWith(prefix)) {
+        const cause = kind.slice(prefix.length);
+        return { key: `block\0${cause}`, type: 'block', cause };
+    }
+    return null;
+}
+
+/**
+ * One row per cause. A blocker that covers many nodes stays a single row.
+ * @param {Array<{ key: string, type: string, cause: string, targets: Array<{ text: string, el?: Element }> }>} list
+ * @param {{ kind?: string, path: string, el?: Element }} entry
+ */
+export function addCause(list, entry, max = 10) {
+    const described = describeCause(entry.kind, entry.path);
+    if (!described) return list;
+    const target = { text: entry.path, el: entry.el };
+    const rest = [];
+    let prev = null;
+    for (let i = 0; i < list.length; i++) {
+        if (list[i].key === described.key) prev = list[i];
+        else rest.push(list[i]);
+    }
+    const targets = prev ? prev.targets.filter((item) => !sameTarget(item, target)) : [];
+    targets.unshift(target);
+    rest.unshift({
+        key: described.key,
+        type: described.type,
+        cause: described.cause,
+        targets
+    });
+    return rest.slice(0, max);
+}
+
+export function formatCause(entry) {
+    const count = entry.targets.length;
+    if (entry.type === 'block') {
+        const noun = count === 1 ? 'element' : 'elements';
+        return `${entry.cause} blocks clicks on ${count} ${noun}`;
+    }
+    if (count <= 1) return `${entry.cause} overflows viewport`;
+    return `${entry.cause} overflows viewport · ${count} elements`;
+}
+
+function sameTarget(a, b) {
+    if (a.el && b.el) return a.el === b.el;
+    return a.text === b.text;
+}
+
+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 };
 }

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.1';
+export const BEE_LADYBUG_VERSION = '0.5.3';
 
 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 : [];
+        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

@@ -35,6 +35,9 @@ const STYLES = `
   top: 12px;
   left: 12px;
   width: 360px;
+  max-height: 50vh;
+  display: flex;
+  flex-direction: column;
   background: rgba(7, 8, 12, 0.94);
   border: 1px solid rgba(255, 59, 78, 0.55);
   box-sizing: border-box;
@@ -62,6 +65,7 @@ const STYLES = `
   display: flex;
   align-items: center;
   gap: 8px;
+  flex: 0 0 auto;
   padding: 10px 12px 8px;
   border-bottom: 1px solid rgba(255, 59, 78, 0.28);
 }
@@ -201,7 +205,7 @@ const STYLES = `
 .bl-k { color: #8b91a3; }
 .bl-v { color: #e9edf5; }
 .bl-console {
-  height: 168px;
+  max-height: 140px;
   overflow: auto;
   padding: 6px 10px 8px;
   background: #05060a;
@@ -212,13 +216,14 @@ const STYLES = `
 .bl-line { white-space: normal; word-break: break-word; }
 .bl-line .t { color: #8b91a3; margin-right: 8px; }
 .bl-line .s { color: #6ee7ff; margin-right: 8px; }
-.bl-line.info .m { color: #d8dce6; }
+.bl-line.info .m { color: #8b91a3; }
 .bl-line.warn .m { color: #ffd36a; }
 .bl-line.error .m { color: #ff6b7d; }
 .bl-line.debug .m { color: #8b91a3; }
 .bl-foot {
   display: flex;
   align-items: center;
+  flex: 0 0 auto;
   flex-wrap: wrap;
   gap: 6px;
   padding: 8px 10px;
@@ -263,6 +268,72 @@ const STYLES = `
 .bl-hotkeys:empty {
   display: none;
 }
+.bl-scroll {
+  overflow: auto;
+  min-height: 0;
+  flex: 1 1 auto;
+}
+.bl-section[hidden] { display: none; }
+.bl-section-toggle {
+  display: block;
+  width: 100%;
+  margin: 0;
+  padding: 5px 10px;
+  border: 0;
+  border-top: 1px solid rgba(255, 59, 78, 0.28);
+  background: #101218;
+  color: #ffd36a;
+  font: 700 9px ui-monospace, Consolas, monospace;
+  letter-spacing: 0.14em;
+  text-align: left;
+  cursor: pointer;
+}
+.bl-section-toggle::before { content: "▾  "; }
+.bl-section[data-open="false"] > .bl-section-toggle::before { content: "▸  "; }
+.bl-section[data-open="false"] > .bl-section-body { display: none; }
+.bl-issues {
+  background: #07080c;
+}
+.bl-legend {
+  display: flex;
+  gap: 14px;
+  padding: 4px 10px 2px;
+  color: #8b91a3;
+  font-size: 10px;
+}
+.bl-dot {
+  display: inline-block;
+  width: 7px;
+  height: 7px;
+  margin-right: 5px;
+  border-radius: 50%;
+  vertical-align: baseline;
+}
+.bl-dot.bug { background: #ff3b4e; }
+.bl-dot.info { background: #8b91a3; }
+.bl-cause > button,
+.bl-cause-kids button,
+.bl-note {
+  display: block;
+  width: 100%;
+  margin: 0;
+  padding: 3px 10px;
+  border: 0;
+  background: transparent;
+  font: 11px ui-monospace, Consolas, monospace;
+  line-height: 1.4;
+  text-align: left;
+}
+.bl-cause > button,
+.bl-cause-kids button {
+  color: #ff6b7d;
+  cursor: pointer;
+}
+.bl-cause-kids[hidden] { display: none; }
+.bl-cause-kids button { padding-left: 22px; }
+.bl-cause > button:hover,
+.bl-cause-kids button:hover { background: rgba(255, 59, 78, 0.08); }
+.bl-note { color: #8b91a3; }
 .bl-detail {
   max-height: 132px;
   overflow: auto;
@@ -366,6 +437,9 @@ export class UIOverlay {
         this.#adapterSig = '';
         this.#hotkeySig = '';
         this.#detail = [];
+        this.#issues = [];
+        this.#issueNotes = [];
+        this.#openCauses = new Set();
         this.#flashAt = new Map();
         this.#flashTimers = new Map();
     }
@@ -380,6 +454,9 @@ export class UIOverlay {
     #adapterSig;
     #hotkeySig;
     #detail;
+    #issues;
+    #issueNotes;
+    #openCauses;
     #flashAt;
     #flashTimers;
 
@@ -416,6 +493,10 @@ export class UIOverlay {
                     </button>
                   </span>
                 </div>
+                <div class="bl-scroll">
+                <section class="bl-section" data-section="status" data-open="true">
+                  <button class="bl-section-toggle" type="button" data-section-toggle aria-expanded="true">STATUS</button>
+                  <div class="bl-section-body">
                 <div class="bl-stats">
                   <div>HOST <b data-el="hostFps">—</b></div>
                   <div>CORE <b data-el="coreFps">—</b></div>
@@ -430,8 +511,32 @@ 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>
+                </section>
+                <section class="bl-section" data-el="issues" data-section="issues" data-open="true" hidden>
+                  <button class="bl-section-toggle" type="button" data-section-toggle aria-expanded="true">ISSUES</button>
+                  <div class="bl-section-body">
+                    <div class="bl-legend">
+                      <span><i class="bl-dot bug"></i>bug</span>
+                      <span><i class="bl-dot info"></i>info</span>
+                    </div>
+                    <div data-el="issues-list"></div>
+                    <div data-el="notes"></div>
+                  </div>
+                </section>
+                <section class="bl-section" data-el="inspect" data-section="inspect" data-open="true" hidden>
+                  <button class="bl-section-toggle" type="button" data-section-toggle aria-expanded="true">INSPECT</button>
+                  <div class="bl-section-body">
+                    <div class="bl-detail" data-el="detail" hidden></div>
+                  </div>
+                </section>
+                <section class="bl-section" data-section="events" data-open="true">
+                  <button class="bl-section-toggle" type="button" data-section-toggle aria-expanded="true">EVENTS</button>
+                  <div class="bl-section-body">
+                    <div class="bl-console" data-el="console" role="log" aria-live="polite"></div>
+                  </div>
+                </section>
+                </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>
@@ -459,6 +564,10 @@ export class UIOverlay {
             hud: this.#root.querySelector('[data-el="hud"]'),
             console: this.#root.querySelector('[data-el="console"]'),
             detail: this.#root.querySelector('[data-el="detail"]'),
+            inspect: this.#root.querySelector('[data-el="inspect"]'),
+            issues: this.#root.querySelector('[data-el="issues"]'),
+            issuesList: this.#root.querySelector('[data-el="issues-list"]'),
+            notes: this.#root.querySelector('[data-el="notes"]'),
             providers: this.#root.querySelector('[data-el="providers"]'),
             adapters: this.#root.querySelector('[data-el="adapters"]'),
             hotkeys: this.#root.querySelector('[data-el="hotkeys"]')
@@ -476,6 +585,42 @@ export class UIOverlay {
             else if (act === 'adapter') this.core.toggleAdapter(btn.getAttribute('data-name'));
         });
 
+        this.#root.querySelector('.bl-scroll')?.addEventListener('click', (event) => {
+            const toggle = event.target.closest('[data-section-toggle]');
+            if (!toggle) return;
+            const section = toggle.closest('.bl-section');
+            if (!section) return;
+            const open = section.dataset.open === 'false';
+            section.dataset.open = open ? 'true' : 'false';
+            toggle.setAttribute('aria-expanded', open ? 'true' : 'false');
+        });
+
+        this.#els.issues?.addEventListener('click', (event) => {
+            if (event.target.closest('[data-section-toggle]')) return;
+            const childBtn = event.target.closest('[data-target]');
+            if (childBtn) {
+                const item = this.#issues[Number(childBtn.getAttribute('data-issue'))];
+                const child = item?.targets?.[Number(childBtn.getAttribute('data-target'))];
+                if (child && typeof child.onSelect === 'function') child.onSelect();
+                return;
+            }
+            const row = event.target.closest('[data-issue]');
+            if (!row) return;
+            const item = this.#issues[Number(row.getAttribute('data-issue'))];
+            if (!item) return;
+            const many = Array.isArray(item.targets) && item.targets.length > 1;
+            if (many) {
+                const key = item.key || item.text;
+                if (this.#openCauses.has(key)) this.#openCauses.delete(key);
+                else this.#openCauses.add(key);
+                this.setIssues(this.#issues.concat(this.#issueNotes));
+                return;
+            }
+            const only = item.targets?.[0];
+            if (only && typeof only.onSelect === 'function') only.onSelect();
+            else if (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 +651,9 @@ export class UIOverlay {
         this.#adapterSig = '';
         this.#hotkeySig = '';
         this.#detail = [];
+        this.#issues = [];
+        this.#issueNotes = [];
+        this.#openCauses.clear();
         this.#clearFlashTimers();
         this.#flashAt.clear();
         return this;
@@ -531,9 +679,11 @@ export class UIOverlay {
         const list = Array.isArray(items) ? items : [];
         this.#detail = list;
         const box = this.#els.detail;
+        const section = this.#els.inspect;
         if (!list.length) {
             box.innerHTML = '';
             box.hidden = true;
+            if (section) section.hidden = true;
             return this;
         }
         let html = '';
@@ -542,10 +692,61 @@ export class UIOverlay {
             html += `<button type="button" data-detail="${i}" data-level="${level}">${escapeHtml(list[i].text)}</button>`;
         }
         box.hidden = false;
+        if (section) section.hidden = false;
         box.innerHTML = html;
         return this;
     }
 
+    /**
+     * Cause rows plus grey info notes. Bugs are red and expand; info stays grey.
+     * @param {Array<{ text: string, level?: string, key?: string, onSelect?: () => void, targets?: Array<{ text: string, onSelect?: () => void }> }>} items
+     */
+    setIssues(items) {
+        if (!this.#els?.issues || !this.#els.issuesList || !this.#els.notes) return this;
+        const list = Array.isArray(items) ? items : [];
+        const bugs = [];
+        const notes = [];
+        for (let i = 0; i < list.length; i++) {
+            if (list[i].level === 'info') notes.push(list[i]);
+            else bugs.push(list[i]);
+        }
+        const capped = bugs.slice(0, 10);
+        this.#issues = capped;
+        this.#issueNotes = notes;
+        const section = this.#els.issues;
+        if (!capped.length && !notes.length) {
+            this.#els.issuesList.innerHTML = '';
+            this.#els.notes.innerHTML = '';
+            section.hidden = true;
+            return this;
+        }
+        let html = '';
+        for (let i = 0; i < capped.length; i++) {
+            const item = capped[i];
+            const targets = Array.isArray(item.targets) ? item.targets : [];
+            const many = targets.length > 1;
+            const open = many && this.#openCauses.has(item.key || item.text);
+            html += `<div class="bl-cause" data-open="${open ? 'true' : 'false'}">`;
+            html += `<button type="button" data-issue="${i}">${many ? (open ? '▾ ' : '▸ ') : ''}${escapeHtml(item.text)}</button>`;
+            if (many) {
+                html += `<div class="bl-cause-kids"${open ? '' : ' hidden'}>`;
+                for (let j = 0; j < targets.length; j++) {
+                    html += `<button type="button" data-issue="${i}" data-target="${j}">${escapeHtml(targets[j].text)}</button>`;
+                }
+                html += '</div>';
+            }
+            html += '</div>';
+        }
+        this.#els.issuesList.innerHTML = html;
+        let noteHtml = '';
+        for (let i = 0; i < notes.length; i++) {
+            noteHtml += `<div class="bl-note">${escapeHtml(notes[i].text)}</div>`;
+        }
+        this.#els.notes.innerHTML = noteHtml;
+        section.hidden = false;
+        return this;
+    }
+
     onPacket(packet) {
         if (!this.#els || !packet) return;
         if (packet.type === 'sys') return;

package/src/index.d.ts

@@ -178,12 +178,15 @@ export class BeeLadybugCore {
     toggleAdapter(name: string): this;
     setAdapterEnabled(name: string, enabled: boolean): this;
     publishDetail(items: DetailItem[]): this;
+    publishIssues(items: DetailItem[]): this;
 }
 
 export interface DetailItem {
     text: string;
     level?: 'info' | 'warn' | 'error';
     onSelect?: () => void;
+    key?: string;
+    targets?: Array<{ text: string; onSelect?: () => void }>;
 }
 
 export class UIOverlay {
@@ -197,6 +200,7 @@ export class UIOverlay {
     onClear(channel?: string): void;
     render(): void;
     setDetail(items: DetailItem[]): this;
+    setIssues(items: DetailItem[]): this;
 }
 
 export interface CanvasEntity {
@@ -287,8 +291,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 +305,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;