DEV Community: Antonio

bug.ai.dev: writing docs at night made me find 11 real bugs in my own library

Antonio — Wed, 11 Nov 2026 21:38:06 +0000

Hi everyone, I'm Antonio. I'm 53, I work as a factory worker during the day, and in the evening I keep building my own projects: modules, classes, a small 2D game engine and a debugging tool called BeeLadybug.

Last time I told you how I argued with AI for hours over a floating search bar that only needed a few lines of CSS.

This time the story is different. This time the AIs were more bugged than my code. 😂

What BeeLadybug is

BeeLadybug is an open-source inspection overlay that runs inside a Shadow DOM. You send it raw data, and adapters turn the page into something you can read:

import('https://cdn.jsdelivr.net/npm/bee-ladybug/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;
  });

Paste that in the console of any page (Chrome may ask you to type allow pasting first), press F6 to start the CSS hunt, and F8 to export a full HTML report.

The plan: just write the docs

I'm writing the documentation one adapter at a time. Canvas, WebDOM, and then CSSAdapter, about 1,235 lines.

To document it properly I asked an AI to read the module and explain it to me. Instead of an explanation, I got a list of bugs.

Then I asked a second AI to check the same folder. It found a different list. One said "10 functions" and then listed 11. Another said "5 points" and wrote 6.

After a full day of work, reading 1,500 lines of code with two AIs arguing in my head... my brain got bugged too. 😂

How I got out of it: I checked with my own eyes

I stopped trusting the numbers and opened the file myself. One of the claims was that the S key scan didn't filter the same noise as the F8 report.

Line 144, inside scan():

if (!el || isBeeChrome(el) || isSkippedTag(el)) continue;

Line 216, inside snapshot():

if (!el || isBeeChrome(el) || isSkippedTag(el) || isReportNoise(el)) continue;

There it was. The quick scan was missing isReportNoise(el), so on a WordPress site it reported fake problems on #wpadminbar and on hidden elements, while the F8 report skipped them correctly.

The bug was real. The counting was wrong, but the bugs were real.

The 11 bugs (short version)

Merging both reviews, these were the ones worth fixing now:

With the CSS hunt on, Ctrl+S / Ctrl+P / Cmd+S were blocked. #handleKey didn't check modifier keys.
With the overlay hidden (F2), the P and S keys and the hover/pin boxes were still active on the page.
A stylesheet change before the first mouse move inspected the element at (0,0).
scan() didn't filter isReportNoise, as shown above.
Modern colors like oklch(), lab(), color() and color-mix() produced a fake "invisible text" warning.
Stylesheets that were disabled or had a non-matching media (like print) were counted as active.
The snapshot cut to 80 rows before sorting by severity, so a harmless will-change could push out a real error.
touchesSheet checked the whole subtree on every mutation, which invalidated the cache almost every frame.
HUD states (css.target, css.hits, css.pin) stayed stuck after turning the hunt off.
cssPath didn't escape special characters, which breaks with Tailwind classes like sm:w-1/2.
The other adapters didn't recognize CSSAdapter's own boxes (data-bee-ladybug-css), so they could count them as page nodes.

One small fix, as an example. The keyboard shortcut problem was solved like this:

#handleKey(event) {
  if (event.ctrlKey || event.metaKey || event.altKey) return;
  if (this.core && this.core.visible === false) return;
  // ... S scans, P pins
}

The result

npm test: 70 tests, 70 passing
npm run lint: clean
npm run typecheck: clean

The things that are design limits, not bugs (like overflow inside overflow:hidden ancestors, or @import sheets not being visible), will go in the docs as known limitations. I think that's more honest than pretending they don't exist.

What I learned

Writing docs is a code review. When you have to explain a function, you notice when it doesn't do what you think.
Two AIs disagreeing doesn't mean nobody is right. It means you have to open the file and look.
Don't trust counts, trust lines. "Line 144 vs line 216" is a fact; "10 or 11 bugs" is just noise.
You don't need a degree to read code. You need patience, coffee, and the stubbornness to check one line at a time.

BeeLadybug is on npm as bee-ladybug, and the docs (in Italian, for now) are on beeenginejs.com.

If you're also building things at night after work: keep going. Your brain will get bugged, but your code will get better. 🐞

I wanted a floating search bar. My AI assistants wanted a bigger project. 😅 A few CSS changes later: the behavior I wanted and a mobile PageSpeed score of 99. Ever had to convince AI to keep things simple?

Antonio — Sat, 07 Nov 2026 21:51:19 +0000

Antonio

Nov 7

I Wanted a Floating Search Bar. The Fix Was a Few Lines of CSS (After Hours of Arguing With AI)

#css #webdev #ai #performance

4 min read

I Wanted a Floating Search Bar. The Fix Was a Few Lines of CSS (After Hours of Arguing With AI)

Antonio — Sat, 07 Nov 2026 21:46:30 +0000

I already had the solution on the screen. Twice, actually.

Two small floating logo/search buttons on my site stayed visible all the way to the footer. Their .blocco-nav-fluttuante used position: fixed, with top: 45px and left: 20px. No JavaScript moving them around. They simply stayed there.

So why couldn't my central search and categories bar work the same way?

That was my point. Getting my AI assistants to stay focused on it took considerably longer than writing the CSS.

In my previous article, I covered the homepage rebuild of SPC – Super Play Combo, my WordPress games portal. This time, the important part isn't a new engine or a clever architecture. It's the simple solution I kept asking for.

Here is the fix—not three sections later

I wanted a rounded bar, slightly detached from the top and sides, with games scrolling underneath it. Visible right down to the footer. I showed Poki as a visual reference for that behavior, not as a source of code.

These are the two CSS rules that delivered it on the Arcade page:

.barra-fissa-spc {
  position: fixed;
  top: 12px;
  left: 12px;
  right: 12px;
  margin: 0 auto;
  max-width: 540px;
  border-radius: 22px;
}

.contenitore-arcade-spc {
  padding: 150px 10px 10px 10px !important;
}

Fixed positioning from the first paint, plus space already reserved underneath. That was the solution for the bar.

The bar stayed in its existing HTML location. Its controls, IDs, event handlers, URLs, and category logic stayed intact. No separate external file. No engine rewrite. No rebuilding the categories just to make a bar float.

A few CSS declarations. A much longer conversation.

Why the two little buttons had the right idea

sticky and fixed aren't interchangeable. In my layout, a sticky bar was constrained by its containing block. It didn't stay visible through the footer the way I wanted.

The little floating buttons already demonstrated the alternative: anchor to the viewport with fixed.

For the central bar, top: 12px creates the gap above it; the side offsets and maximum width keep it centered; the radius rounds all four corners. The games can scroll behind it, including through that small gap above.

Because fixed elements don't occupy normal-flow space, the container needs room at the top. The final value here was 150px, not the earlier 135px trial. That keeps the title, description, and first games clear of the bar initially. It's a value for my layout, to check at different widths and with the WordPress admin bar—not a magic number for every site.

The JavaScript detour we didn't need

The earlier spostaBarra() function relocated the bar into the body on DOMContentLoaded. Moving a visible element after rendering was an avoidable layout-shift risk. A Puzzle report showing the whole #page displaced made that worth investigating.

The answer wasn't another relocation strategy. It was to stop relocating it:

function avvia() {
  // spostaBarra();
  osservaGioco();
}

osservaGioco() still handles visibility when opening a game. Removing the move didn't mean throwing away useful behavior.

During troubleshooting of the optimized styles, we also added this as the first CSS rule:

.spc-css-guard { --spc: 1; }

That was a debugging precaution, not a diagnosed universal LiteSpeed fix. The layout solution remained fixed plus reserved space, with !important on my container padding to keep it applied.

My AI assistants were helping. Enthusiastically. Elsewhere.

The discussion kept wandering into animation, visual styling, layout shifts, and changes to the game engine. Meanwhile, I kept returning to those two little floating buttons.

I knew the behavior I wanted. I was using AI to implement it, not asking it to replace the goal with something more complicated.

I also did my part to prolong the adventure: undoing and reapplying changes whenever PageSpeed moved. Apparently, my afternoon needed a second source of stubbornness.

Still, this was a satisfying little vindication. I didn't need to name every CSS property to recognize that the working example was already on my own page.

One separate issue, not a reason to rebuild the bar

The game grid had its own loading problem. An intermediate Arcade report showed CLS 0.120: 0.102 attributed to pagination and 0.018 to the grid.

The separate fix reserved responsive space for the first 60 cards while JavaScript populated the grid. Once filled, the waiting class was removed, allowing filtered results and shorter final pages to use their natural height.

That mattered for stability. It wasn't part of making the search bar float, and it didn't require reinventing the bar.

The result—and six categories still waiting

The later Arcade mobile lab report reached 99 Performance, with FCP and LCP at 1.4s, 30ms Total Blocking Time, and CLS 0.017. Accessibility, Best Practices, and SEO were 100.

Not a promise of zero CLS everywhere, and not a claim that the bar's CSS alone produced the whole score. But the intended behavior worked, and the layout was much steadier.

Now I'm saving the stable version before carefully updating the six remaining categories. First, this article. Even debugging deserves an intermission.

Have your AI assistants ever confidently complicated something you already knew could be simple? And have you solved a floating-bar or layout-shift problem this way? Tell me in the comments.

"I don't talk much, so I wrote a dialogue plugin instead. 🐝 Feedback welcome!"

Antonio — Sun, 01 Nov 2026 11:06:41 +0000

Antonio

Nov 1

How nice it is to talk — BeeDialogue lands in BeeEngine 2.11.0

#javascript #gamedev #webdev #opensource

3 min read

How nice it is to talk — BeeDialogue lands in BeeEngine 2.11.0

Antonio — Sun, 01 Nov 2026 11:03:43 +0000

Hi. I'm Antonio. I'm 53. I build things out of pure passion.

I don't talk much. But when I do… BeeDialogue comes out.

From “dialogue” to a dialogue plugin

BeeEngine is a small 2D HTML5 Canvas engine I keep shaping in the open. Physics, scenes, sprites, tiles, audio buses, an inventory plugin, a locale plugin. Useful pieces. Quiet pieces.

What was missing for story-shaped games was obvious: a place for NPCs to say something without me inventing a new if tree every weekend.

So v2.11.0 adds BeeDialogue.

Not a chatbot. Not a voice synthesizer. A dialogue tree: speakers, lines, branching choices, straight-line advances. The kind of thing you wire to a blue rectangle that pretends to be a guide on a bridge.

The engine stays blind (on purpose)

BeeEngine has a plugin contract I take seriously. The core does not import plugins. A plugin attaches itself.

import { BeeEngine } from 'beeengine';
import { BeeDialogue, BeeLocale } from 'beeengine/plugins';

const game = new BeeEngine('c', 800, 480);
const locale = new BeeLocale({ /* strings… */, engine: game });

const dialogue = new BeeDialogue({ engine: game, locale, cancelKey: 'Escape' });
// attach() registers it as 'dialogue' — detach() unregisters

No monkey-patch of loop(). No hijacking of update / render. BeeDialogue has no tick of its own and no DOM listeners. Your scene calls the verbs:

handleInput(input) from scene.update
draw(ctx) from scene.draw (screen space, after the camera)

The motor stays a motor. The plugin stays a plugin. I sleep better.

A tree you can read

You load a tree once. Nodes can be an array (easier to skim) or a map. Literal text / speaker work. Or textKey / speakerKey if you pass an optional BeeLocale (constructor, setLocale, or engine.plugin('locale')).

dialogue.load({
  start: 'intro',
  nodes: [
    {
      id: 'intro',
      speakerKey: 'guide',
      textKey: 'hi',
      choices: [
        { textKey: 'ask_map', next: 'map', data: { topic: 'map' } },
        { textKey: 'bye', next: null, data: { topic: 'bye' } }
      ]
    },
    { id: 'map', speakerKey: 'guide', textKey: 'map', next: 'tip' },
    { id: 'tip', speakerKey: 'guide', textKey: 'tip' }
  ]
});

Rules that saved me from myself:

Node without choices → advance() follows next (or ends).
Node with choices → choose(index).
The wrong verb returns false and warns. Good. I need warnings more than cleverness.
start() while already open does a clean restart (end with reason restart, then start again).

Drawing choices (without becoming a second renderer)

BeeDialogue is not BeeText.drawHUD. It draws a simple panel when you ask.

const scene = {
  update(_dt, input) {
    if (input.wasPressed('KeyE') && !dialogue.isOpen()) dialogue.start();
    dialogue.handleInput(input); // Space / Enter advances or confirms; arrows move the highlight
  },
  draw(ctx) {
    dialogue.draw(ctx, { x: 40, width: ctx.canvas.width - 80 });
  }
};

onChange reports start, node, choice, advance, and end (with a reason: finished, cancel, restart, reload, missing-node…). Enough to feed a future quest plugin without hard-wiring anything today.

And yes — toJSON / fromJSON save the tree and where you stood, so you can tuck the DTO into BeeSave next to inventory slots. Definitions stay yours; restore reopens on the saved node and emits node (not a fake second start).

About that demo label

The demo is examples/dialogue.html. Press E.

The English string does not say “E to talk”.

It says “E to interact”.

Because BeeDialogue does not talk. It does not clear its throat. It does not do regional accents. It advances nodes. The joke writes itself, and I left it in the locale table on purpose (talk: 'E to interact'). Press L if you want Italian. The guide still will not speak aloud. She will, however, mention a village east of a bridge, which is already more social than most of my week.

Why this shape

I like small contracts:

Piece	Job
BeeLocale	`t(key)` — pure read
BeeInventory	stacks, use, equip — no draw loop
BeeDialogue	tree state — you draw and feed input

Together they feel like a tiny RPG toolkit without pretending to be one. Next ideas on the shelf (one at a time): Quest, Post FX, scene Transition, action remapping… Lights, Spine, Net later. Those touch more surface area. Dialogue was the polite guest who hangs its coat on attach and leaves with detach.

Try it

Repo: BeeEngine-V2.5.0 (package beeengine 2.11.0)
Demo: examples/dialogue.html
Tests: node scripts/test-beedialogue.mjs
Import: import { BeeDialogue } from 'beeengine/plugins'

If you break it, tell me how. If you use it in a jam game with three lines of dialogue and a torch tip, tell me that too. Short messages welcome — I don't talk much.

But when I do… you already know what comes out.

— Antonio

How I Rebuilt the Homepage of My HTML5 Games Portal (and What I Learned About Caching)

Antonio — Sat, 31 Oct 2026 19:03:01 +0000

I run a free HTML5 games portal, SPC – Super Play Combo. It's built on WordPress with the GeneratePress theme and has over 3,000 games from the GameMonetize and GamePix feeds. Over the last few weeks I rebuilt the homepage in a Poki-like style, with one horizontal row per category. It looked easy. It wasn't.

Here are the real problems I ran into and how I fixed them.

1. Category rows with no duplicates

Each category (Puzzle, Arcade, Match-3, Mahjong, Quiz, Sports, Racing…) has its own page with its own game list. The homepage shows one row per category, built by a script called motore-playcombo.js.

The feeds use English category names, while my site uses Italian ones, so I made a map:

const CATEGORIE_HOME = [
  'puzzle', 'sparabolle', 'arcade', 'match-3', 'mahjong',
  'trivia', 'gamesforgirls', 'sports', 'racing',
  'card', 'adventure', 'platformer', '2048'
];

Golden rule: each game appears in exactly one row. A Set of already-used ids does the job:

const alreadyShown = new Set();

function removeDuplicates(games) {
  return games.filter(g => {
    const key = g.id || g.url || g.title;
    if (alreadyShown.has(key)) return false;
    alreadyShown.add(key);
    return true;
  });
}

Rows further down only load when they're about to scroll into view:

const observer = new IntersectionObserver((entries) => {
  entries.forEach(e => {
    if (e.isIntersecting) {
      loadRow(e.target.dataset.category);
      observer.unobserve(e.target);
    }
  });
}, { rootMargin: '300px' });

2. "It works when I'm logged in, but not in incognito"

The Quiz and Card rows were full when I was logged in as admin, but empty for visitors. The culprit was LiteSpeed Cache. For visitors who aren't logged in, it optimizes the page and turns the game list inside the HTML into base64. My script was looking for plain text and found nothing.

The fix is to try decoding it:

function readList(text) {
  try { return JSON.parse(text); } catch (e) {}
  try { return JSON.parse(atob(text)); } catch (e) {}
  return [];
}

Lesson: always test in incognito. What you see as an admin is not what your users see.

3. The little `?v=` number that saves your life

The script is loaded like this:

<script src="/js/motore-playcombo.js?v=16"></script>

?v=16 does nothing to the code. It only tells the browser (and the cache, and the PWA service worker) that the file is new. Every time I upload a new version, I:

bump the number on every page that loads the script;
purge the LiteSpeed cache.

Forget this and you'll get 404 errors for files you already deleted, because the browser is still running the old version. Ask me how I know.

4. Thumbnails: from wsrv.nl to i0.wp.com

To make thumbnails lighter, I was running them through an image proxy. Then I found out that the service's robots.txt blocks Googlebot, so Google couldn't see my images. I switched to WordPress's free image CDN:

function optimizeImg(url) {
  if (url.includes('gamepix') || url.includes('?')) return url;
  const u = new URL(url);
  return `https://i0.wp.com/${u.host}${u.pathname}?w=240&quality=75`;
}

I also added a small safety net: if the optimized image fails to load, it falls back to the original.

img.onerror = () => { img.onerror = null; img.src = original; };

The result is a much faster homepage.

5. A bit of (lightweight) style

One last touch: the background has game-themed icons (a joypad, a coin, a star, a heart) made with pure CSS and no shadows, so phones don't struggle. With body.page-id-XXXX I can give each page its own look, like floating yellow stars only on the Girls page.

Takeaways

Always test in incognito and on a phone.
The cache is your friend, until you forget about it.
A wrong (or unchanged) ?v= can cost you hours.
Check the robots.txt of any third-party service you rely on.
PWA errors often go away by themselves after a few minutes, so don't panic right away.

If you want to see the result, the games are on playcombo.it. Free, as always. 🎮

Pressed F8 on a big games portal: 25 errors. On my own site: 4. Then the report found bugs in my debugger itself 😄

Antonio — Mon, 26 Oct 2026 22:10:04 +0000

Antonio

Oct 26

I got tired of reading CSS bugs in a tiny overlay, so I made my debugger print a report

#javascript #webdev #debugging #opensource

3 min read

I got tired of reading CSS bugs in a tiny overlay, so I made my debugger print a report

Antonio — Mon, 26 Oct 2026 22:07:26 +0000

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.

Chrome DevTools tells you z-index is 9999. It doesn't tell you which parent is trapping it. Now my debugger does.

Antonio — Sat, 24 Oct 2026 22:22:46 +0000

Antonio

Oct 22

Why your z-index doesn't work: my debugger now points to the exact line

#css #javascript #webdev #debugging

2 min read

Two docs sites, one WordPress install, zero plugins fighting each other. Here's how I kept BeeEngine and BeeLadybug apart.

Antonio — Sat, 24 Oct 2026 22:17:29 +0000

Antonio

Oct 24

How I kept two docs sites apart in one WordPress install (and almost gave up)

#wordpress #documentation #webdev #javascript

2 min read

How I kept two docs sites apart in one WordPress install (and almost gave up)

Antonio — Sat, 24 Oct 2026 22:07:28 +0000

I already had the BeeEngine docs on beeenginejs.com as static WordPress pages. When BeeLadybug grew big enough to need its own docs, about 33 pages, I hit a wall. Everything I made ended up mixed in with the BeeEngine pages: the same page list, the same hierarchy, the same mess. Using posts wasn't an option either, because docs aren't blog articles.

I'll be honest: I was close to dropping it. I'm not a WordPress plugin expert, and every solution I found was either too complicated or broke something else.

The fix: a custom post type

The answer turned out to be simple. I gave BeeLadybug its own content type:

I installed Custom Post Type UI.
I created a post type with the slug ladybug, set Hierarchical to true and Has archive to false.
I went to Settings → Permalinks and clicked Save. Skip this step and you'll get 404s.

Now every BeeLadybug page lives under /ladybug/... with its own URL, and it's completely separate from the BeeEngine pages in the admin.

Keeping the style separate too

Each page is a Custom HTML block, and all the CSS is scoped under a .bld-docs wrapper, so it never leaks into the theme or the BeeEngine docs. Links to pages I haven't written yet point to # and get dimmed:

.bld-docs a[href="#"] {
  opacity: .4;
  pointer-events: none;
}

What I learned

The problem was never WordPress, it was not knowing which tool to use. If you're stuck on something similar, keep going. The fix might be one plugin and one checkbox away.🫈🫈🫈

👉 BeeLadybug docs

Why your z-index doesn't work: my debugger now points to the exact line

Antonio — Thu, 22 Oct 2026 19:48:29 +0000

The same evening I shipped this, Chrome opened "New in DevTools" and proudly announced DevTools for agents: AI that reads your CSS rules. Thanks Google, I'll take it as a sign I'm on the right track. Their version is for AI agents. Mine is for a 53-year-old guy pressing F6😂😂😂😂😂😂.

We've all done it. A popup stays behind the header, so you write z-index: 999. Then 9999. Then 99999. Nothing changes.

The problem is almost never the element you're fixing. It's one of its ancestors.

The invisible box

When an element has a transform, an opacity below 1, a filter, or a position with a z-index, it creates a stacking context. Think of it as a closed box: its children can only stack inside the box. A child with z-index: 99999 is still only as high as the box itself.

DevTools won't tell you which ancestor is the box. You have to climb the tree by hand.

The idea came from a comment

After my last post about BeeLadybug's CSS hunt, a reader suggested in the comments: scan the ancestors with getComputedStyle, flag whatever creates a stacking context, then group it by cause, like the click-blocker lines. He also warned that will-change is often set on purpose for animations, so it should be a hint, not a verdict.

So that's exactly what 0.5.4 does.

What it looks like

On the demo page:

div.hero creates stacking context (transform) - z-index of 3 children is trapped

Click the line and it lists span.b1, span.b2, span.b3.

will-change stays a grey info line, with the z-index note on the same line:

div.layer-hint will-change: opacity — z-index of 1 child stays in this layer

Then I ran it on my own site

I tested it on my live HTML5 games portal. Logged in, it flagged the WordPress admin bar blocking clicks (only I see that). In incognito, only this was left:

div.entry-content creates stacking context (z-index) - z-index of 1 child is trapped

And the INSPECT section went one step further. It showed the rule responsible, inside my LiteSpeed-minified CSS:

.site-header, .main-navigation, .entry-content, .griglia-giochi-spc {
  position: relative !important;
}

One !important rule from my own custom CSS, creating four boxes at once. It's not a bug today, since each box has a single child. But the day I add a dropdown that must cover the header, I already know where to look.

That's the point: not "something is wrong", but "this line caused it".

Try it (F12, paste in the console)

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

Press F6 for the CSS hunt, S to scan the page. Zero dependencies, no extension.

Next time your z-index "doesn't work", let the ladybug find the box. 🐞

DEV Community: Antonio

bug.ai.dev: writing docs at night made me find 11 real bugs in my own library

What BeeLadybug is

The plan: just write the docs

How I got out of it: I checked with my own eyes

The 11 bugs (short version)

The result

What I learned

I wanted a floating search bar. My AI assistants wanted a bigger project. 😅 A few CSS changes later: the behavior I wanted and a mobile PageSpeed score of 99. Ever had to convince AI to keep things simple?

I Wanted a Floating Search Bar. The Fix Was a Few Lines of CSS (After Hours of Arguing With AI)

I Wanted a Floating Search Bar. The Fix Was a Few Lines of CSS (After Hours of Arguing With AI)

Here is the fix—not three sections later

Why the two little buttons had the right idea

The JavaScript detour we didn't need

My AI assistants were helping. Enthusiastically. Elsewhere.

One separate issue, not a reason to rebuild the bar

The result—and six categories still waiting

"I don't talk much, so I wrote a dialogue plugin instead. 🐝 Feedback welcome!"

How nice it is to talk — BeeDialogue lands in BeeEngine 2.11.0

How nice it is to talk — BeeDialogue lands in BeeEngine 2.11.0

From “dialogue” to a dialogue plugin

The engine stays blind (on purpose)

A tree you can read

Drawing choices (without becoming a second renderer)

About that demo label

Why this shape

Try it

How I Rebuilt the Homepage of My HTML5 Games Portal (and What I Learned About Caching)

1. Category rows with no duplicates

2. "It works when I'm logged in, but not in incognito"

3. The little ?v= number that saves your life

4. Thumbnails: from wsrv.nl to i0.wp.com

5. A bit of (lightweight) style

Takeaways

Pressed F8 on a big games portal: 25 errors. On my own site: 4. Then the report found bugs in my debugger itself 😄

I got tired of reading CSS bugs in a tiny overlay, so I made my debugger print a report

I got tired of reading CSS bugs in a tiny overlay, so I made my debugger print a report

One key, one file

How it fits a "blind" Core

Then I pointed it at real sites

…and it found bugs in itself

Try it

Chrome DevTools tells you z-index is 9999. It doesn't tell you which parent is trapping it. Now my debugger does.

Why your z-index doesn't work: my debugger now points to the exact line

Two docs sites, one WordPress install, zero plugins fighting each other. Here's how I kept BeeEngine and BeeLadybug apart.

How I kept two docs sites apart in one WordPress install (and almost gave up)

How I kept two docs sites apart in one WordPress install (and almost gave up)

The fix: a custom post type

Keeping the style separate too

What I learned

Why your z-index doesn't work: my debugger now points to the exact line

The invisible box

The idea came from a comment

What it looks like

Then I ran it on my own site

Try it (F12, paste in the console)

3. The little `?v=` number that saves your life