It started with a message from a client.
"Since your update, the site is slow and the buttons don't work unless you click them twice."
My gut said: this isn't my code.
But gut feelings don't win client arguments. Evidence does.
The Symptom
Buttons on the site required two clicks to fire. The site felt sluggish overall.
To most people, that looks like a broken button. To me, that's a classic sign of a choked JavaScript main thread.
Here's why:
When the main thread is blocked, click events don't get ignored — they get queued. The first click registers, but the handler can't execute because the thread is busy. The moment the thread frees up, the queued event fires — which is why the second click seems to "work."
The button isn't broken. The thread is.
The Diagnosis
Something on their site was blocking the main thread and preventing normal JavaScript execution. Common culprits:
- A heavy third-party script loading synchronously
- A poorly written plugin running expensive operations on the main thread
- A theme or script with a long task blocking the event loop
The key word: their site. Not my plugin.
How I Proved It
Rather than going back and forth in chat, I did this:
- Deployed my plugin in a completely isolated environment — fresh WordPress install, no other plugins, no custom theme, nothing else active
- Recorded videos testing it on three devices — my laptop, an Android phone, and an iPhone
- Sent the standalone URL so the client could test it themselves in real time
Result? Every button worked on the first click. Every time. On every device.
The plugin wasn't the problem.
The Lesson
Isolate before you blame.
When a client reports a bug, resist the urge to defend your code with words. Instead, strip the environment down to one variable — your code, nothing else — and let the result speak.
If it works in isolation, the problem is in the integration, not your implementation.
This is especially true in WordPress, where plugin conflicts and main thread congestion from third-party scripts are incredibly common. A site running 20+ plugins and a bloated theme is a minefield. Your plugin might be the last one loaded, which makes it the easiest to blame — but rarely the actual culprit.
What to Look For
If you're debugging a similar issue, open Chrome DevTools → Performance tab and record a few seconds of interaction. Look for:
- Long Tasks (red bars) blocking the main thread
- Scripts with high Total Blocking Time (TBT)
- Synchronous third-party scripts in the
<head>
Tools like WebPageTest or Lighthouse will also flag main thread congestion clearly.
Once you identify the blocking script, the fix is usually one of:
- Deferring or async-loading the script
- Removing the offending plugin
- Lazy-loading heavy third-party resources
Takeaway
The double-click symptom is almost never about the button. It's about what's happening around it.
When something breaks after your change, don't just defend — demonstrate. Build the isolated environment, record it, share it. Evidence is the only language that ends the argument.
If you've run into something similar or have a different approach to diagnosing main thread issues — drop it in the comments. Always curious how others handle this.
