feat(genui): server-defined components, and buttons that say who they're for

[AimTune]

The client half of mekik PROTOCOL.md §10. Backend counterpart: AimTune/mekik#10.

Server-defined components. The backend announces a catalog on connect and @chativa/genui turns each definition into a custom element, so a { type: "ui", component: "order-card" } chunk mounts a widget nobody compiled into the page. Cached in localStorage under the server URL and validated by a hash riding along on the hello frame the connector already sends — so a returning user's widgets render before the server answers, at no extra round trip.

What its buttons do. <chativa-html> bound exactly one attribute, data-event, and the backend had to guess who the click was for. Now the attribute is the answer:

attribute	scope sent	meaning
component-event="rate_delivery"	"component"	the widget's own conversation with the graph node that mounted it
mekik-event="track_order"	"graph"	the application, which may start a new turn
data-event="…"	none	let the backend decide (the original form)

Most specific wins, an empty value is not a trigger, and forms carry the scope too.

Threading it through

scope and the originating component reach the backend as optional fields on the genui_event frame, carried as one optional GenUIEventOptions argument:

GenUIHtmlElement → sendEvent(type, payload, { scope })
GenUIMessage     → stamps `component` from the chunk
ChatWidget / AgentPanel → ChatEngine.receiveComponentEvent(…, opts)
IConnector       → receiveComponentEvent(streamId, eventType, payload, opts?)
createGenUIEventFrame → { type, streamId, eventType, payload, scope?, component? }

Optional at every hop on purpose. A data-event still makes the two-argument sendEvent call it always made, and a frame with no routing metadata is byte-for-byte the frame backends see today. All five connectors pass opts through; ones whose protocol doesn't model routing simply never receive it.

The component name is stamped by GenUIMessage, not by the component — only the chunk knows which widget an interaction came from, and asking components to report it themselves is asking for it to be wrong.

MekikConnector

An interrupt frame carrying data.event now renders nothing. That pause is waiting for a widget already on screen, so default Approve/Cancel chips would be a dead end: tapping Approve sends a resume the node isn't waiting for.

Verified against the real backend

Not by inspection — I fed chativa's createGenUIEventFrame output straight into a live mekik app:

interrupt data: {"payload":{},"event":"rate_delivery"}
chativa frame:  {"type":"genui_event","streamId":"…","eventType":"rate_delivery",
                 "payload":{"stars":5},"scope":"component","component":"delivery-card"}
  ✓ a component-event frame resolves the node parked on onEvent
  ✓ …and never reaches the graph handler
  ✓ a mekik-event frame reaches the graph handler, carrying the component name
  ✓ a plain data-event produces no scope key, and still reaches the handler
  ✓ an unknown scope is rejected as bad_request

Plus 570 tests passing and 13 packages typechecking.

Reviewer notes

• GenUIComponentAPI.sendEvent gained an optional third parameter — source-compatible for every existing component.
• One existing ChatEngine test was updated: it asserted receiveComponentEvent arity, which changed by one optional argument. A new test covers the forwarding.
• The new attributes need the mekik side to interpret scope; that's feat(genui): the backend defines the widget, and its buttons route mekik#10.

🤖 Generated with Claude Code