feat: surface cards — data-only UI specs rendered as native cards (#2480)

[ahmetbir]

Closes #2480.

Follows up on my RFC comment — same design, now implemented end to end and exercised against a live relay (the e2e suite publishes, edits, and reads real signed events; screenshots below are captured through the desktop E2E harness).

What this adds

A surface card: a channel-scoped event (KIND_SURFACE) whose content is a small, versioned, data-only JSON document that clients render as a native card. The author controls content, never layout — no markup, links, or scripts. Live updates reuse the existing edit kind (40003) with full-spec replacement, so a card can go healthy → incident → recovered inside one message row.

{
  "version": 1,
  "fallbackText": "Deploy v2.4.1: 2/2 pods running, rollout 100%",
  "title": "Deployment — api-gateway",
  "nodes": [
    { "type": "badge", "text": "HEALTHY", "tone": "success" },
    { "type": "statGrid", "stats": [{ "label": "Pods", "value": 2, "tone": "success" }] },
    { "type": "table", "columns": ["Pod", "Status"], "rows": [["web-7d9f", "Running"]] },
    { "type": "progress", "label": "Rollout", "value": 100 }
  ]
}

Because it is an ordinary signed event, it renders identically whether the author is a frontier model, a tiny local model, or a person with the CLI — and it inherits NIP-29 scoping, membership auth, and the audit trail for free.

Full protocol spec: docs/nips/NIP-SC.md (start there — it carries the design rationale).

What it looks like

An agent posts a deployment status. Badge, stat grid, table, and progress bar — all from the spec above, all rendered natively by the desktop client.

The deploy degrades. The agent sends a 40003 edit carrying a full replacement spec, and the same message row becomes the incident view — new tone, new stats, a rollback bar, plus a text node explaining what happened. No second message, no scrollback archaeology.

By layer

• buzz-core — surface.rs: payload types, strict validation with field-specific errors, canonical serialization, producer-side alias normalization, 32 KiB cap. KIND_SURFACE in the registry.
• buzz-relay — messages-write scope + h scope, spec validation at ingest, and revalidation of any 40003 edit whose target is a surface (edits are author-gated and must themselves be a valid spec).
• buzz-sdk / buzz-cli — build_surface / build_surface_edit; messages send-surface / edit-surface with --spec <file|-|inline>, repeatable --mention, and field-specific errors so an agent repairs a payload without a relay round-trip. Agent docs updated (CLI README, ACP base prompt, nest skill).
• Desktop — tolerant zod parser implementing the fallback matrix (invalid nodes drop, unknown version → fallbackText, unparseable → escaped plain text; never the markdown pipeline), native SurfaceCard, and surfaces counted for unread/home/mentions exactly like a stream message.

Non-goals in this PR

Interactivity (an actions node that only prefills a composer is sketched in the NIP as a follow-up), streaming/partial patches, an MCP tool, a visual editor, and search indexing (surfaces stay out of FTS — the positive allowlist in migration 0008 already excludes the kind). Mobile is deliberately untouched: the kind is simply absent there rather than half-rendered — happy to add the Flutter renderer here if you'd prefer.

Why the wire format is not OpenUI Lang

The issue title says OpenUI, so this is the one design call worth spelling out. I evaluated OpenUI Lang properly and deliberately did not put it on the wire — inspired by, not embedded — for three reasons:

1. A Buzz event is permanent; a young DSL is not. Every surface ever published is a signed, immutable event sitting in the relay's event store forever. Whatever grammar goes on the wire has to be readable by a client written three years from now. OpenUI Lang is moving fast, which is exactly the property you want in a generation format and exactly the property you do not want in an archival one. A 6-field JSON object with a version integer is boring on purpose.
2. The token argument is real, but it's about generation, not transport. Lang's savings measure what a model emits. That's separable from what gets signed: an agent can emit Lang and have the CLI transpile it before signing, and nothing in this PR forecloses that — messages send-surface already takes --spec from a file, stdin, or inline, so a Lang front-end is an additive change to one command, not a protocol change.
3. The streaming advantage doesn't apply here. Lang's incremental-parse design pays off when tokens arrive one at a time into a live-rendering view. Buzz events arrive whole and verified; there is nothing to progressively parse. Live updates are already handled better by the existing edit kind — a full replacement spec that swaps the card in place — which also gets author-gating and audit for free.

The result of the choice is the constraint that matters most: the payload is data, not markup. There is no expression language, no layout primitive, no URL, no script — an author picks from seven node types and fills in values. A malicious or confused agent cannot inject anything, because there is no channel to inject into. Renderers own layout entirely, which is also what lets mobile and desktop diverge visually without a protocol negotiation.

Questions for maintainers

1. Kind number. I used 40110 as a placeholder (free, adjacent to canvas at 40100). Assign whatever you want and I'll change it — it's a single constant plus its mirrors.
2. Actions in v1? Currently read-only. I can add the constrained actions node here instead if you'd rather ship it whole.
3. Mobile parity — same PR, or follow-up?

Compatibility

A new kind, so clients that don't implement it simply don't match it in their timeline filters — zero breaking changes. That's the same "new feature = new kind" shape the project already uses.

Known limitations

• A burst of edits inside one second has no defined "last": every reader converges on the same one (ties break on the smallest event id, which matches the relay's created_at DESC, id ASC ordering and makes a one-row lookup per target exact), but which one is arbitrary. Documented in the NIP.
• Background push (NIP-PL) does not carry surfaces; PUSH_KINDS omits them (it omits 40002 too). Home feed, unread state, and open-app desktop notifications do work.
• A surface used as a forum thread root is listed and rendered, but forum-specific affordances beyond that weren't in scope.

A note on scope

Wiring a new content kind through every read path surfaced a few gaps that were not surface-specific and are fixed here because the feature is unusable without them: neither the forum thread view nor the ACP agent context applied kind:40003 edits for any kind (so edited normal messages were stale there too), buzz-cli was not a current-state reader, and the Projects inline agent chat filtered out everything except kinds 9/40002. Each fix is in its own commit with the reasoning. Happy to split any of them out if you'd prefer them separate.

To keep future content kinds from needing the same sweep, the kind lists are now centralized (buzz_core::kind::CONVERSATIONAL_KINDS, desktop/src-tauri/src/commands/query_kinds.rs) with parity tests across the Rust/TS boundary.

Testing

just ci green. New coverage: buzz-core validation/canonicalization boundaries, SDK builders, desktop parser fallback matrix + timeline edit ordering, Rust↔TS kind parity, edit-overlay targeting/tie-break, and relay e2e in crates/buzz-test-client/tests/e2e_relay.rs (member accept / non-member reject, invalid payloads, edit authorization, cross-channel edit rejection, edit replacement observable, mention delivery to the recipient's own connection, FTS exclusion). The e2e are #[ignore] as usual and pass against a live local relay.