Wire VNode event delivery + wikilink intercept (post-v1.2 followup)

[thetechjon]

Summary

Plugin API v1.2 (PRs A–F + integration #141) shipped the VNode event ENVELOPE shape and the VNode shapes (button / input / radio / clickable svg) that emit events, but the dispatch + routing pipeline was never wired. Four feature plugins (#70 / #71 / #72 / #73) hit the same wall trying to use the API today. This PR closes two distinct gaps in a single piece of plumbing.

Gap 1 — VNode events did not reach the plugin

• PluginFullscreenView.handleEvent was a documented no-op.
• PluginsPanel's <PluginNode> mount had no onEvent prop.
• PluginHost had no sendVNodeEvent method.
• workerEntry.ts had no inbound handler for host:vnodeEvent.
• PluginCtx had no onVNodeEvent registration API.

The wire envelope (HostVNodeEvent in src/plugins/protocol.ts) was already correct with the source.kind: 'panel' | 'codeBlock' | 'fullscreen' discriminator — PR A pre-shipped the shape. This PR wires both ends.

Gap 2 — wikilink:// clicks on plugin-rendered note links did nothing

A plugin emits { tag: 'link', href: { kind: 'note', noteId } }; the renderer produces <a href="wikilink://<encodedId>">. Browser navigation to an unrecognised scheme is a no-op, so the click was inert.

What landed

Dispatch + routing

• PluginHost.sendVNodeEvent(pluginId, source, event, payload) constructs the envelope and posts to the worker.
• workerEntry.ts handles host:vnodeEvent by fanning out to every handler registered via ctx.onVNodeEvent. Handlers live in a worker-local Set; unload() calls worker.terminate(), which drops the entire module and every handler with it.
• PluginsPanel, PluginFullscreenView, and PluginCodeBlock now pass an onEvent callback to <PluginNode> with the right source descriptor ({ kind: 'panel', panelId } / { kind: 'fullscreen', viewId } / { kind: 'codeBlock', blockId }).

SDK addition

ctx.onVNodeEvent(handler): Unsubscribe ships in BOTH src/plugins/sdk.ts and packages/noteser-plugin-sdk/src/sdk.ts.

Handler signature:

(args: {
  event: string
  payload: unknown
  source:
    | { kind: 'panel'; panelId: string }
    | { kind: 'codeBlock'; blockId: string }
    | { kind: 'fullscreen'; viewId: string }
}) => void

ONE handler shape with the source discriminator rather than the plan-section-6 (event, cb) pair so plugins that reuse an event name across surfaces can disambiguate without renaming.

Wikilink intercept

The renderer's renderLink now attaches an onClick:

• If href starts with wikilink:// AND the click is unmodified (no meta / ctrl / shift / alt, primary button), call e.preventDefault() and useWorkspaceStore.getState().openNote(noteId). The noteId comes from the typed VNodeLink.href.kind === 'note' branch — NOT URL parsing — so the parsing surface stays at one chokepoint.
• Modifier-clicks pass through (native semantics, no-op for an unknown scheme).
• Anchor (#fragment) links are untouched (native fragment-scroll owns that case).

Rate-limit choice

MAX_VNODE_EVENTS_PER_SECOND = 16 events / sec / plugin, sliding 1-second window. Tighter than the general MAX_MESSAGES_PER_SECOND ceiling of 60.

• 16 events/sec is one event per repaint at 60Hz with three frames of headroom — plenty for interactive controls.
• Tight enough to bottom out a runaway loop fast (a render that emits one onClick is typically one event per repaint; a real workload never approaches the cap).
• A drop within a window emits a single vnodeEventRateLimited PluginHostEvent (one per window) so a runaway loop surfaces in the dev console without spamming the toast layer.

The event family has no acknowledged use case for high-rate streaming — the high-rate paths are setPanelContent + vault.events, both already capped elsewhere.

Backwards compatibility

Plugins that never call ctx.onVNodeEvent see no behaviour change. Their rendered controls fire events into an empty handler set in the worker, which silently drops them — exactly the pre-PR behaviour.

The PluginVNode.tsx renderer adds an onClick to every <a> it emits, but the handler is a pass-through for any non-wikilink:// href, so existing tests of the link shape still pass.

Reference plugin

public/plugins/noteser-vnode-demo bumps to 0.3.0:

• Subscribes via ctx.onVNodeEvent from onActivate — toasts every event with the source kind, and console.logs every event for the manual smoke check.
• Tracks the active note via onActiveNoteChange and renders a link VNode to it, so the wikilink intercept can be smoke-tested by clicking the link in the panel.
• No new permissions.

Test plan

• npm run lint is clean.
• npx tsc --noEmit reports zero errors.
• npm test -- --ci is green (207 suites pass, 2564 tests).
• Install the updated noteser-vnode-demo plugin, open the demo panel, click the button — devtools shows the [noteser-vnode-demo] vnodeEvent log line with source.kind: 'panel'.
• In the demo panel, click the "Open the current note" link — the host opens that note (wikilink intercept fires).
• Run the "VNode demo: show fullscreen" command, click the button inside the modal — devtools logs the event with source.kind: 'fullscreen'.

🤖 Generated with Claude Code