Add addEventListener/removeEventListener with DOM-model on* semantics

[ochafik]

Bugs fixed

useHostStyles() is broken — fonts clobber theme/CSS variables (#551)

useHostStyles calls two sub-hooks sequentially:

export function useHostStyles(...) {
  useHostStyleVariables(app, ctx);  // sets app.onhostcontextchanged → theme + CSS vars
  useHostFonts(app, ctx);           // sets app.onhostcontextchanged → fonts ONLY (overwrites above)
}

On main, the second setNotificationHandler call silently replaces the first. Result: when the host changes theme, CSS variables and color-scheme are never updated. Only fonts are applied. Any React app using useHostStyles has broken theme support.

User onhostcontextchanged + SDK hooks are mutually exclusive (#225)

If a user writes app.onhostcontextchanged = myHandler and also uses useHostStyles, whichever runs last wins — the other's handler is silently destroyed. The threejs example has an explicit workaround:

// Note: we handle styles here instead of using useHostStyles,
// because useHostStyles overwrites onhostcontextchanged.
app.onhostcontextchanged = (params) => { /* manually reimplement style logic */ };

getHostContext() correctness is fragile

On main, the context merge (_hostContext = { ..._hostContext, ...params }) is baked into the onhostcontextchanged setter's wrapper closure. If anything bypasses the setter (e.g., calls setNotificationHandler directly), getHostContext() returns stale data.

hookInitializedCallback save/restore pattern is broken

basic-host's hookInitializedCallback reads bridge.oninitialized (always undefined — no getter existed), wraps it, then "restores" it. On main this silently overwrites. The pattern was always broken but happened to appear to work.

---

The fix: DOM event model

This PR follows exactly how the browser DOM handles el.onclick vs el.addEventListener("click", …):

Feature	on* setter	addEventListener
Semantics	Replace (single slot)	Append (listener array)
Clear	app.ontoolinput = undefined	removeEventListener(event, fn)
Getter	app.ontoolinput returns current handler	N/A
Coexistence	Both fire on dispatch	Both fire on dispatch

Dispatch order when a notification arrives:

1. onEventDispatch() — subclass side-effects (e.g., App unconditionally merges hostcontextchanged into cached context)
2. The singular on* handler (if set)
3. All addEventListener listeners in insertion order

What this enables

• useHostStyles works: Both useHostStyleVariables and useHostFonts use addEventListener — they coexist without conflict
• Hooks + user code compose: A user's app.onhostcontextchanged = ... and the SDK's addEventListener("hostcontextchanged", ...) both fire
• getHostContext() is always correct: Context merge happens in onEventDispatch, before any handler, unconditionally
• Save/restore patterns work: Getters exist on all on* properties, so const prev = bridge.oninitialized returns the actual handler

ProtocolWithEvents base class

New intermediate class between Protocol and App/AppBridge:

                  Protocol (MCP SDK)
                      │
              ProtocolWithEvents          ← NEW: DOM-model events
                  /         \
               App          AppBridge

Each notification event gets a single slot with two independent channels:

interface EventSlot<T> {
  onHandler?: (params: T) => void;   // singular on* handler (replace)
  listeners: ((params: T) => void)[]; // addEventListener array (append)
}

One dispatcher is lazily registered with the base Protocol per event. It fans out to both channels.

API surface:

abstract class ProtocolWithEvents<..., EventMap> extends Protocol<...> {
  // Subclass populates: event name → notification schema
  protected abstract readonly eventSchemas: { [K in keyof EventMap]: MethodSchema };

  // DOM-model event API (for subclass on* get/set pairs)
  protected setEventHandler(event, handler | undefined): void;
  protected getEventHandler(event): handler | undefined;

  // Public multi-listener API
  addEventListener(event, handler): void;
  removeEventListener(event, handler): void;

  // Double-set protection for direct calls
  override setRequestHandler(...): void;    // throws on double-set
  override setNotificationHandler(...): void; // throws on double-set
  protected replaceRequestHandler(...): void; // for on* request setters
}

Other changes

• Getters for all on* properties on both App and AppBridge (notification events and request handlers)
• replaceRequestHandler — request handler on* setters (e.g., oncalltool, onteardown) use replace semantics without triggering double-set protection
• Reentrancy safety — listener array is snapshot-copied during dispatch so a listener can safely call removeEventListener on itself
• registerTool bug fixes — output schema validation no longer returns wrong type, title included in tools/list, outputSchema only emitted when defined

Test plan

• Build passes (npm run build)
• All 271 unit tests pass (npm test)
• All examples build (npm run build:all via pre-commit hook)
• on* setters replace (not append)
• on* setters coexist with addEventListener
• on* getters return current handler
• Clearing with undefined works
• Direct setRequestHandler double-set throws
• setNotificationHandler throws for event-mapped methods
• React hooks (useHostStyles) use addEventListener/removeEventListener correctly
• hookInitializedCallback save/restore pattern works with getters
• E2E tests

🤖 Generated with Claude Code

[github-actions]

📖 Docs Preview Deployed

Preview (stable)	https://pr-571.mcp-ext-apps-docs-preview.pages.dev
This commit	https://1512529a.mcp-ext-apps-docs-preview.pages.dev
Commit	ca3f216

Includes drafts and future-dated posts. All pages served with noindex, nofollow — search engines will not crawl this preview.

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/ext-apps

npm i https://pkg.pr.new/@modelcontextprotocol/ext-apps@571

@modelcontextprotocol/server-basic-preact

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-preact@571

@modelcontextprotocol/server-basic-react

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-react@571

@modelcontextprotocol/server-basic-solid

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-solid@571

@modelcontextprotocol/server-basic-svelte

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-svelte@571

@modelcontextprotocol/server-basic-vanillajs

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-vanillajs@571

@modelcontextprotocol/server-basic-vue

npm i https://pkg.pr.new/@modelcontextprotocol/server-basic-vue@571

@modelcontextprotocol/server-budget-allocator

npm i https://pkg.pr.new/@modelcontextprotocol/server-budget-allocator@571

@modelcontextprotocol/server-cohort-heatmap

npm i https://pkg.pr.new/@modelcontextprotocol/server-cohort-heatmap@571

@modelcontextprotocol/server-customer-segmentation

npm i https://pkg.pr.new/@modelcontextprotocol/server-customer-segmentation@571

@modelcontextprotocol/server-debug

npm i https://pkg.pr.new/@modelcontextprotocol/server-debug@571

@modelcontextprotocol/server-map

npm i https://pkg.pr.new/@modelcontextprotocol/server-map@571

@modelcontextprotocol/server-pdf

npm i https://pkg.pr.new/@modelcontextprotocol/server-pdf@571

@modelcontextprotocol/server-scenario-modeler

npm i https://pkg.pr.new/@modelcontextprotocol/server-scenario-modeler@571

@modelcontextprotocol/server-shadertoy

npm i https://pkg.pr.new/@modelcontextprotocol/server-shadertoy@571

@modelcontextprotocol/server-sheet-music

npm i https://pkg.pr.new/@modelcontextprotocol/server-sheet-music@571

@modelcontextprotocol/server-system-monitor

npm i https://pkg.pr.new/@modelcontextprotocol/server-system-monitor@571

@modelcontextprotocol/server-threejs

npm i https://pkg.pr.new/@modelcontextprotocol/server-threejs@571

@modelcontextprotocol/server-transcript

npm i https://pkg.pr.new/@modelcontextprotocol/server-transcript@571

@modelcontextprotocol/server-video-resource

npm i https://pkg.pr.new/@modelcontextprotocol/server-video-resource@571

@modelcontextprotocol/server-wiki-explorer

npm i https://pkg.pr.new/@modelcontextprotocol/server-wiki-explorer@571

commit: 571c215