DOM event system: addEventListener, dispatch, bubbling #109

Implement the W3C DOM event model connecting JavaScript event handlers to the DOM tree.

Scope#

Event Interface#

• Event constructor: new Event(type, options)
  • event.type — event type string (e.g., "click")
  • event.target — element that triggered the event
  • event.currentTarget — element currently handling the event
  • event.bubbles — boolean, whether event bubbles
  • event.cancelable — boolean, whether event is cancelable
  • event.defaultPrevented — boolean
  • event.eventPhase — 0 (NONE), 1 (CAPTURING), 2 (AT_TARGET), 3 (BUBBLING)
  • event.timeStamp — timestamp of event creation

Event Methods#

• event.preventDefault() — cancel the default action
• event.stopPropagation() — stop event from propagating further
• event.stopImmediatePropagation() — stop even other handlers on same element

EventTarget Methods (on all DOM node wrappers)#

• element.addEventListener(type, callback, options) — register handler
  • Support capture option (boolean or options object with capture field)
  • Support once option (auto-remove after first invocation)
• element.removeEventListener(type, callback, options) — unregister handler
• element.dispatchEvent(event) — dispatch event, return false if preventDefault was called

Event Propagation#

• Capture phase: traverse from document root to target, invoke capture listeners
• Target phase: invoke listeners on the target element
• Bubble phase: traverse from target back to root, invoke bubble listeners
• Respect stopPropagation() and stopImmediatePropagation()

Event Storage#

• Store event listeners per-node (in the DOM or in a side table keyed by NodeId)
• Each listener entry: { type, callback (GcRef), capture (bool), once (bool) }
• Listeners must be GC roots while attached

Common Event Types#

• Support dispatching any string event type
• No built-in UI event dispatch yet (mouse, keyboard) — that comes with browser integration
• Focus on the infrastructure: registration, dispatch, propagation

Acceptance Criteria#

• element.addEventListener("click", handler) registers a handler
• element.dispatchEvent(new Event("click")) invokes registered handlers
• Event bubbles from target to document root
• Capture phase listeners fire before bubble phase
• event.stopPropagation() halts propagation
• event.preventDefault() sets defaultPrevented
• removeEventListener correctly unregisters handlers
• once: true option auto-removes handler after first call
• event.target and event.currentTarget are set correctly during dispatch

Phase 11 — DOM-JS Bindings (issue 4 of 8). Depends on: issue 2 (DOM-JS bridge).