bee-ladybug 0.5.2 → 0.5.4

package/README.MD

@@ -195,13 +195,14 @@ 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`
+- un antenato che crea uno stacking context (`transform`, `opacity` sotto 1, `filter`, oppure `position` non static con `z-index`). I figli si raggruppano sulla causa: `div.hero creates stacking context (transform) - z-index of 3 children is trapped`. `will-change: transform` o `opacity` è una riga grigia, con la nota sullo `z-index` sulla stessa riga
 - `<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. `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.
+`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.2",
+  "version": "0.5.4",
   "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

@@ -42,7 +42,6 @@ export class CSSAdapter {
         this.#attached = false;
         this.#active = false;
         this.#rules = [];
-        this.#unreadable = [];
         this.#sheetsDirty = true;
         this.#x = 0;
         this.#y = 0;
@@ -51,6 +50,8 @@ export class CSSAdapter {
         this.#pinned = null;
         this.#panelLock = false;
         this.#issues = [];
+        this.#notes = [];
+        this.#seenSheets = new Set();
         this.#issueLog = new Map();
         this.#hoverBox = null;
         this.#pinBox = null;
@@ -72,7 +73,6 @@ export class CSSAdapter {
     #attached;
     #active;
     #rules;
-    #unreadable;
     #sheetsDirty;
     #x;
     #y;
@@ -81,6 +81,8 @@ export class CSSAdapter {
     #pinned;
     #panelLock;
     #issues;
+    #notes;
+    #seenSheets;
     #issueLog;
     #hoverBox;
     #pinBox;
@@ -141,6 +143,7 @@ export class CSSAdapter {
             pushInvisible(el, findings);
             pushBlockers(el, findings);
             pushImage(el, findings);
+            pushStacking(el, findings);
             pushImportant(el, this.#rules, findings);
             for (let j = 0; j < findings.length; j++) {
                 rows.push({ el, selector: cssPath(el), ...findings[j] });
@@ -159,7 +162,11 @@ export class CSSAdapter {
             });
         }
         const groups = groupIssues(rows);
-        for (let i = groups.length - 1; i >= 0; i--) this.#stickGroup(groups[i]);
+        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,
@@ -228,6 +235,8 @@ export class CSSAdapter {
         this.#pinned = null;
         this.#panelLock = false;
         this.#issues = [];
+        this.#notes = [];
+        this.#seenSheets.clear();
         this.#issueLog.clear();
         this.#unmountBoxes();
         this.core?.publishDetail([]);
@@ -264,13 +273,8 @@ 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) {
@@ -290,13 +294,7 @@ 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
-            });
-        }
+        pushStacking(el, findings);
         const path = cssPath(el);
         this.core?.sendData('state', { source: this.source, key: 'css.target', value: path });
         this.core?.sendData('state', {
@@ -344,7 +342,7 @@ export class CSSAdapter {
         for (let i = 0; i < findings.length; i++) {
             const hit = findings[i];
             const text = hit.text || hit.kind || '';
-            if (!text) continue;
+            if (!text || text.startsWith('unreadable sheet:') || hit.level === 'info') continue;
             if (!rememberIssue(this.#issueLog, `${path}\0${text}`, now, this.issueWindow)) continue;
             const level = hit.level === 'error' ? 'error' : 'warn';
             this.core?.sendData(level, {
@@ -355,34 +353,55 @@ export class CSSAdapter {
     }
 
     #stickFindings(el, path, findings) {
+        let changed = false;
         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);
+            if (this.#rememberCause(el, path, hit.kind)) changed = true;
         }
-        this.#publishIssues();
+        if (changed) 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();
+    #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,
+            level: 'info',
+            message: `unreadable sheet: ${label}`
+        });
     }
 
     #publishIssues() {
-        this.core?.publishIssues(this.#issues.map((item) => ({
-            level: 'error',
-            text: item.text,
-            onSelect: () => this.#pin(item.el)
-        })));
+        const bugs = [];
+        const notes = this.#notes.map((note) => ({
+            level: 'info',
+            key: note.text,
+            text: note.text
+        }));
+        for (let i = 0; i < this.#issues.length; i++) {
+            const entry = this.#issues[i];
+            const item = {
+                key: entry.key,
+                text: formatCause(entry),
+                targets: entry.targets.map((target) => ({
+                    text: target.text,
+                    onSelect: () => this.#pin(target.el)
+                }))
+            };
+            if (entry.level === 'info') notes.push({ ...item, level: 'info' });
+            else bugs.push({ ...item, level: 'error' });
+        }
+        this.core?.publishIssues(bugs.concat(notes));
     }
 
     #pin(el) {
@@ -586,9 +605,11 @@ function pushNegativeMargins(el, findings) {
 const ISSUE_RANK = Object.freeze({
     overflow: 0,
     blocker: 1,
+    stack: 1,
     invisible: 2,
     image: 3,
-    important: 4
+    important: 4,
+    hint: 6
 });
 
 /**
@@ -715,8 +736,165 @@ export function pushStickyIssue(list, entry, max = 10) {
     return next.slice(0, max);
 }
 
-function isStickyKind(kind) {
-    return kind === 'overflows viewport' || (typeof kind === 'string' && kind.startsWith('click blocked'));
+export function describeCause(kind, path) {
+    if (kind === 'overflows viewport') {
+        return { key: `overflow\0${path}`, type: 'overflow', cause: path, reason: '', level: 'error' };
+    }
+    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, reason: '', level: 'error' };
+    }
+    const stack = typeof kind === 'string' ? kind.match(/^stacking context \(([^)]+)\) by (.+)$/) : null;
+    if (stack) {
+        return {
+            key: `stack\0${stack[2]}\0${stack[1]}`,
+            type: 'stack',
+            cause: stack[2],
+            reason: stack[1],
+            level: 'error'
+        };
+    }
+    const hint = typeof kind === 'string' ? kind.match(/^will-change (.+?) by (.+)$/) : null;
+    if (hint) {
+        return {
+            key: `will\0${hint[2]}\0${hint[1]}`,
+            type: 'stack-hint',
+            cause: hint[2],
+            reason: hint[1],
+            level: 'info'
+        };
+    }
+    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,
+        reason: described.reason || '',
+        level: described.level || 'error',
+        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 (entry.type === 'stack') {
+        const noun = count === 1 ? 'child' : 'children';
+        return `${entry.cause} creates stacking context (${entry.reason}) - z-index of ${count} ${noun} is trapped`;
+    }
+    if (entry.type === 'stack-hint') {
+        const noun = count === 1 ? 'child' : 'children';
+        return `${entry.cause} will-change: ${entry.reason} — z-index of ${count} ${noun} stays in this layer`;
+    }
+    if (count <= 1) return `${entry.cause} overflows viewport`;
+    return `${entry.cause} overflows viewport · ${count} elements`;
+}
+
+/**
+ * Properties that create a stacking context. `will-change` for transform or
+ * opacity is only a hint: it may promote a layer, it is not reported as a bug.
+ * @param {{ transform?: string, opacity?: string, filter?: string, position?: string, zIndex?: string, willChange?: string, getPropertyValue?: (name: string) => string }} style
+ */
+export function stackingReasons(style) {
+    const read = (prop, camel) => {
+        if (style && typeof style.getPropertyValue === 'function') {
+            const raw = style.getPropertyValue(prop);
+            if (raw) return String(raw).trim();
+        }
+        if (style && style[camel] != null && style[camel] !== '') return String(style[camel]).trim();
+        return '';
+    };
+    const bugs = [];
+    const transform = read('transform', 'transform');
+    if (transform && transform !== 'none') bugs.push('transform');
+    const opacity = parseFloat(read('opacity', 'opacity'));
+    if (Number.isFinite(opacity) && opacity < 1) bugs.push('opacity');
+    const filter = read('filter', 'filter');
+    if (filter && filter !== 'none') bugs.push('filter');
+    const position = read('position', 'position') || 'static';
+    const zIndex = read('z-index', 'zIndex') || 'auto';
+    if (position !== 'static' && zIndex !== 'auto') bugs.push('z-index');
+    const hint = willChangeHint(read('will-change', 'willChange'));
+    return { bugs, hint };
+}
+
+function willChangeHint(value) {
+    if (!value || value === 'auto') return '';
+    const parts = value.split(',').map((part) => part.trim().toLowerCase());
+    const hit = [];
+    for (let i = 0; i < parts.length; i++) {
+        if ((parts[i] === 'transform' || parts[i] === 'opacity') && !hit.includes(parts[i])) hit.push(parts[i]);
+    }
+    return hit.join(', ');
+}
+
+function pushStacking(el, findings) {
+    if (!el || typeof getComputedStyle !== 'function' || !el.parentElement) return;
+    const own = getComputedStyle(el);
+    const ownZ = own.zIndex || own.getPropertyValue?.('z-index') || 'auto';
+    if (!ownZ || ownZ === 'auto') return;
+    let node = el.parentElement;
+    while (node && node.nodeType === 1) {
+        if (isBeeChrome(node)) return;
+        const found = stackingReasons(getComputedStyle(node));
+        const ancestor = cssPath(node);
+        if (found.bugs.length) {
+            const reason = found.bugs[0];
+            findings.push({
+                level: 'error',
+                rank: ISSUE_RANK.stack,
+                score: 35,
+                kind: `stacking context (${reason}) by ${ancestor}`,
+                text: `z-index trapped by ${ancestor} (${reason})`
+            });
+            if (found.hint) findings.push(stackHint(ancestor, found.hint));
+            return;
+        }
+        if (found.hint) {
+            findings.push(stackHint(ancestor, found.hint));
+            return;
+        }
+        node = node.parentElement;
+    }
+}
+
+function stackHint(ancestor, hint) {
+    return {
+        level: 'info',
+        rank: ISSUE_RANK.hint,
+        score: 1,
+        kind: `will-change ${hint} by ${ancestor}`,
+        text: `will-change: ${hint} on ${ancestor}`
+    };
+}
+
+function sameTarget(a, b) {
+    if (a.el && b.el) return a.el === b.el;
+    return a.text === b.text;
 }
 
 function elementCausesOverflow(el) {

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.2';
+export const BEE_LADYBUG_VERSION = '0.5.4';
 
 export const CORE_DEFAULTS = Object.freeze({
     toggleKey: 'F2',
@@ -364,7 +364,7 @@ export class BeeLadybugCore {
      * @param {Array<{ text: string, level?: string, onSelect?: () => void }>} items
      */
     publishIssues(items) {
-        const list = Array.isArray(items) ? items.slice(0, 10) : [];
+        const list = Array.isArray(items) ? items : [];
         this.#issues = list;
         this.ui?.setIssues(this.#issues);
         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,35 +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 {
-  overflow: hidden;
   background: #07080c;
-  border-top: 1px solid rgba(255, 59, 78, 0.55);
 }
-.bl-issues[hidden] {
-  display: none;
+.bl-legend {
+  display: flex;
+  gap: 14px;
+  padding: 4px 10px 2px;
+  color: #8b91a3;
+  font-size: 10px;
 }
-.bl-issues-label {
-  padding: 5px 10px 0;
-  color: #ff3b4e;
-  font-size: 9px;
-  font-weight: 700;
-  letter-spacing: 0.14em;
+.bl-dot {
+  display: inline-block;
+  width: 7px;
+  height: 7px;
+  margin-right: 5px;
+  border-radius: 50%;
+  vertical-align: baseline;
 }
-.bl-issues button {
+.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;
-  color: #ff6b7d;
   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-issues button:hover { background: rgba(255, 59, 78, 0.08); }
+.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;
@@ -316,6 +358,7 @@ const STYLES = `
 }
 .bl-detail button[data-level="warn"] { color: #ffd36a; }
 .bl-detail button[data-level="error"] { color: #ff6b7d; }
+.bl-detail button[data-level="info"] { color: #8b91a3; }
 .bl-detail button:hover { background: rgba(255, 255, 255, 0.04); }
 .bl-adapter {
   appearance: none;
@@ -396,6 +439,8 @@ export class UIOverlay {
         this.#hotkeySig = '';
         this.#detail = [];
         this.#issues = [];
+        this.#issueNotes = [];
+        this.#openCauses = new Set();
         this.#flashAt = new Map();
         this.#flashTimers = new Map();
     }
@@ -411,6 +456,8 @@ export class UIOverlay {
     #hotkeySig;
     #detail;
     #issues;
+    #issueNotes;
+    #openCauses;
     #flashAt;
     #flashTimers;
 
@@ -447,6 +494,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>
@@ -461,12 +512,32 @@ 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>
+                </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-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>
@@ -494,8 +565,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"]')
@@ -513,11 +586,40 @@ export class UIOverlay {
             else if (act === 'adapter') this.core.toggleAdapter(btn.getAttribute('data-name'));
         });
 
-        this.#root.querySelector('.bl-issues')?.addEventListener('click', (event) => {
+        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 && typeof item.onSelect === 'function') item.onSelect();
+            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) => {
@@ -551,6 +653,8 @@ export class UIOverlay {
         this.#hotkeySig = '';
         this.#detail = [];
         this.#issues = [];
+        this.#issueNotes = [];
+        this.#openCauses.clear();
         this.#clearFlashTimers();
         this.#flashAt.clear();
         return this;
@@ -576,9 +680,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 = '';
@@ -587,30 +693,58 @@ 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;
     }
 
     /**
-     * Red warnings pinned above the scrolling console. Newest first.
-     * @param {Array<{ text: string, level?: string, onSelect?: () => void }>} items
+     * 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) return this;
-        const list = Array.isArray(items) ? items.slice(0, 10) : [];
-        this.#issues = list;
-        const box = this.#els.issues;
-        if (!list.length) {
+        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 = '';
-            box.hidden = true;
+            this.#els.notes.innerHTML = '';
+            section.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>`;
+        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>';
         }
-        box.hidden = false;
         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;
     }
 

package/src/index.d.ts

@@ -185,6 +185,8 @@ export interface DetailItem {
     text: string;
     level?: 'info' | 'warn' | 'error';
     onSelect?: () => void;
+    key?: string;
+    targets?: Array<{ text: string; onSelect?: () => void }>;
 }
 
 export class UIOverlay {