BeeLadybug 如何把除錯資訊整理成可匯出的報告

BeeLadybug, my open-source debug overlay, has always shown what's happening in real time: FPS, logs, !important, z-index traps, clicks being swallowed by the wrong element.

The problem is the overlay. Make it big and it covers the game or the page you're debugging. Make it small, the way it is now, and you're squinting at a phone-sized box on the left of the screen while the rows scroll past.

One evening I gave up and asked myself a simple question: why can't I just press a key and get everything on one page, to read calmly?

One key, one file

Version 0.6.1 adds exportReport(). Press F8, or the EXPORT button, and you get report-YYYYMMDD-HHMM.html:

• a summary at the top: errors, warnings, ok
• the Core log with sim time and frame
• series: FPS min / avg / max, nodes, mutations
• one section per adapter: Canvas hitboxes and collisions, DOM box model and clipped nodes, CSS (!important, stacking contexts, intercepted clicks, overflow), long tasks, slow resources, Python metrics

It's plain HTML with a dark theme. Ctrl+P turns it into a PDF. You can also get json (for CI or an AI agent) or csv (for a spreadsheet).

import { BeeLadybugCore, exportReport } from 'bee-ladybug';

const bee = new BeeLadybugCore();
// ...attach adapters...
exportReport(bee, { format: 'html' }); // downloads the file

In headless mode (ui: false) nothing is downloaded. The function just returns the data, so it works in Node and in bots too.

How it fits a "blind" Core

The Core still knows nothing about Canvas, the DOM or Python. Each adapter can now register an optional snapshot() hook that returns rows like { severity, selector, rule, value, source }. The exporter asks every registered adapter for its snapshot, and if one throws, it becomes a single warn row while the rest of the report still renders. A new adapter only has to implement snapshot() to show up in the report.

Then I pointed it at real sites

First, my own games portal. It found:

• my .entry-content creating a stacking context that traps the z-index of the game grid
• a container blocking clicks on three elements
• an average of 33 FPS, which explains a lot

Then, for fun, a big professional games portal. 25 errors, 51 warnings 😄 To be fair, most of them are intentional tricks: negative margins so a carousel can bleed to the edges, and content clipped on purpose inside cards. Their site works great. It still averaged ~52 FPS with 3× my DOM nodes, which taught me more than the error count did.

…and it found bugs in itself

The best part of testing on real pages: the report exposed its own weak spots.

• an icon from the WordPress admin bar slipped through the filter
• the same row repeated dozens of times instead of being grouped as ×N
• the summary said "0 errors" while the log had four of them

All three are being fixed. A debugger that finds bugs in itself on its first real run felt like a good sign.

Try it

Install it in your project:

npm i bee-ladybug

Or try it right now without installing: open any page, press F12 and paste this in the console, then press F8 for the report.

import('https://cdn.jsdelivr.net/npm/bee-ladybug@0.6.1/src/index.js')
  .then(({ BeeLadybugCore, WebDOMAdapter, CSSAdapter }) => {
    const bee = new BeeLadybugCore();
    new WebDOMAdapter(bee, { root: document.body }).attach();
    new CSSAdapter(bee).attach();
    window.bee = bee;
  });

Feedback welcome, especially from people debugging Canvas games and DOM-heavy pages.