Happy DOM Event Handling
Description
Documents verified Happy DOM shadow DOM event behavior and guides agents away from unnecessary re-entrancy guards. Happy DOM correctly enforces shadow DOM event boundaries — events dispatched on a host element do not re-enter its shadow tree. When duplicate handler calls occur in tests, the cause is application-level bugs (typically listener accumulation), not Happy DOM defects.
Trigger
- Adding or reviewing re-entrancy guards in web component event handlers
- Debugging duplicate event handling in Happy DOM unit tests
- Investigating whether Happy DOM leaks events across shadow boundaries
- Proxy/facade pattern: re-dispatching an event from shadowRoot listener onto the host
Response Pattern
- Assume Happy DOM is correct — Happy DOM (v20.6.1+) correctly enforces shadow DOM event boundaries. Events dispatched on the host element (
this) do not propagate back intothis.shadowRootlisteners. This was verified in the AdminPanel investigation (see issue-endless-loop-employee-acknowledge.md). - Look for listener accumulation — The most common cause of duplicate handler calls is listeners being registered multiple times. Check whether
setupEventDelegation()overrides guard against re-registration across re-renders. - Check for feedback loops — If the handler dispatches an event of the same type, verify the listener target (
thisvsthis.shadowRoot) prevents self-triggering. - Never add a re-entrancy guard to paper over duplicates — A
_handlingEventflag silently drops duplicate calls, masking the real bug (e.g., N listeners where only 1 should exist). Fix the root cause instead.
Examples
- "My handler is called twice — is Happy DOM broken?" → No. Check for duplicate listener registration.
- "Should I add a
_handlingEventguard?" → No. Find and fix the source of re-entrancy. - "Does
composed: truecause events to loop back into the shadow tree?" → No. Happy DOM correctly scopes dispatch. - "setupEventDelegation is called on every render — is that safe?" → Only if custom listeners are guarded against re-registration.
Additional Context
Verified Happy DOM Behavior (v20.6.1)
These behaviors were verified by test in this project, not assumed from documentation:
shadowRoot.addEventListener("x", handler)— handler fires when event dispatched inside the shadow treethis.dispatchEvent(new CustomEvent("x", { bubbles: true }))on the host — does NOT triggershadowRootlisteners for "x"composed: trueallows events to cross shadow boundaries outward (child → host → parent), not inward (host → its own shadow tree)stopPropagation()on the original event plus re-dispatch on host is a safe proxy pattern — no cycle occurs
The Listener Accumulation Pattern (Confirmed Root Cause)
The AdminPanel "infinite loop" was caused by listener accumulation, not Happy DOM:
BaseComponent.connectedCallback()callssetupEventDelegation()→ adds custom listeners onshadowRoot- Then calls
update()→renderTemplate()→setupEventDelegation()again → adds duplicate listeners - Each
requestUpdate()→renderTemplate()→ anothersetupEventDelegation()→ more duplicates shadowRootlisteners surviveinnerHTMLreplacement (they're on the root, not on child elements)- Result: N listeners fire for 1 event → handler called N times → looks like re-entrancy
Fix: Add a _customEventsSetup boolean guard in setupEventDelegation() overrides, same pattern BaseComponent uses with isEventDelegationSetup.
protected setupEventDelegation() {
super.setupEventDelegation();
if (this._customEventsSetup) return; // Prevent duplicate listeners
this._customEventsSetup = true;
this.shadowRoot.addEventListener("my-event", (e) => {
e.stopPropagation();
this.handleCustomEvent(e as CustomEvent);
});
}Why Re-entrancy Guards Are Wrong Here
// BAD: Masks the real bug (duplicate listeners)
private _handlingEvent = false;
handleCustomEvent(e: Event): void {
if (this._handlingEvent) return; // Silently drops calls 2..N
this._handlingEvent = true;
try { /* … */ } finally { this._handlingEvent = false; }
}This "works" but:
- Silently drops legitimate duplicate calls that indicate a bug
- Tests can only assert
callCount ≤ 2instead ofcallCount === 1 - The guard remains forever, obscuring whether the underlying bug is fixed
Rules for Agents
- Happy DOM shadow DOM event boundaries are correct — do not claim otherwise without a minimal repro
- Never add
_handlingEventguards — find and fix the source of duplicate calls - Check
setupEventDelegationoverrides for missing re-registration guards whenever duplicate handler calls are observed - Assert exact call counts in tests (
toBe(1), nottoBeLessThanOrEqual(2)) to catch listener accumulation regressions