@origonai/web-sdk 0.1.0

package/docs/backend-integration.md

@@ -0,0 +1,485 @@
+# MoQ-Switch — WebTransport Client Integration Guide
+
+For frontend engineers building a **browser** (or any WebTransport-capable
+runtime) client that joins a media-server call.
+
+> **Read [`client-integration.md`](client-integration.md) first** for the
+> wire-level reference (control messages, audio framing, error taxonomy,
+> reconnect tiers). This doc only covers what is **WebTransport-specific**.
+> The protocol on top of WT is byte-for-byte identical to the native QUIC
+> path.
+
+---
+
+## 1. What WebTransport buys you
+
+WebTransport is the browser's standardized API for QUIC-shaped streams +
+datagrams over HTTP/3. The browser can't open a raw QUIC connection; it
+*can* open a WebTransport session, which gives you:
+
+- Bidirectional sub-streams (≈ QUIC bidi streams)
+- Unidirectional sub-streams (≈ QUIC uni streams)
+- Datagrams (≈ QUIC datagrams)
+- Connection lifetime + close events
+
+The media-server treats a WebTransport session as a 1:1 substitute for
+a raw QUIC connection from the native client. **Same Connect handshake,
+same ControlMessages, same audio datagrams.**
+
+---
+
+## 2. Transport setup
+
+| Item | Value |
+|---|---|
+| URL | `https://<media-server-host>:<port>/web` |
+| ALPN | `h3` (negotiated automatically by the browser) |
+| Protocol header (sent automatically) | `:protocol = webtransport` |
+| TLS | 1.3 mandatory; WebPKI-trusted cert in prod, see §10 for dev |
+| Datagrams | required (server requires; browser supports natively) |
+| Path | `/web` (default; configurable on the server via `[server] wt_path`) |
+
+### 2.1 Opening the session
+
+```js
+const wt = new WebTransport('https://media.example.com/web', {
+  // Production: omit. Browser uses the WebPKI trust store.
+  // Development with a self-signed cert, see §10:
+  // serverCertificateHashes: [{ algorithm: 'sha-256', value: <ArrayBuffer> }],
+})
+
+await wt.ready                        // throws if the handshake failed
+console.log('connected; closed=', wt.closed)
+```
+
+`wt.closed` is a Promise that resolves (or rejects) when the session
+ends. Treat it as your "session lost" signal.
+
+There is **no explicit ALPN knob** in the WebTransport API. The browser
+negotiates `h3` for you; the server's dual-ALPN listener accepts it.
+
+### 2.2 Setting up the audio path
+
+The browser cannot use the OS WebRTC pipeline through WebTransport
+directly; you control the encoder yourself.
+
+| Concern | Recommended primitive |
+|---|---|
+| Mic capture | `getUserMedia({ audio: true })` → `MediaStreamTrackProcessor` |
+| Opus encode | `AudioEncoder` from WebCodecs API (`codec: 'opus'`) |
+| Opus decode (per peer) | `AudioDecoder` (`codec: 'opus'`) per `PeerAttached.alias` |
+| Playback | Each decoder's PCM into an `AudioWorkletNode` mixer → `AudioContext.destination` |
+| Frame sizing | Encoder configured for 20 ms (960 samples @ 48 kHz mono) |
+
+WebCodecs is Chromium-first today (Safari TP, Firefox behind flag).
+Document a min-supported-browser policy with the product team.
+
+---
+
+## 3. The wire on top of WT — what maps to what
+
+| Native client (QUIC) | Browser client (WT) | Carries |
+|---|---|---|
+| Bidi QUIC stream | `wt.createBidirectionalStream()` (client-opened) | ControlMessages — Connect, NegotiateMedia, Hold, Mute, SendDtmf, Resume + their `*Ok` + server-push |
+| QUIC datagrams | `wt.datagrams` (readable + writable streams) | Audio frames (one frame per datagram), uplink + downlink |
+| QUIC uni stream (server→client) | `wt.incomingUnidirectionalStreams` | DTMF events when the peer pressed a digit |
+| QUIC graceful close | `wt.close({ closeCode, reason })` | Hangup |
+
+Everything in [`client-integration.md`](client-integration.md) §4–§12 applies
+unchanged. Substitute "QUIC bidi stream" with "WT bidi sub-stream" and
+"QUIC datagram" with "WT datagram." That's it.
+
+---
+
+## 4. The control stream (bidi sub-stream)
+
+```js
+// Open the control stream — must be the first thing you do.
+const ctrl = await wt.createBidirectionalStream()
+const writer = ctrl.writable.getWriter()
+const reader = ctrl.readable.getReader()
+```
+
+### 4.1 Framing
+
+Every ControlMessage on the bidi stream is:
+
+```
++------------------+------------------+-----------------+
+| msg_type   (vi)  | payload_len (vi) | payload (bytes) |
++------------------+------------------+-----------------+
+```
+
+`(vi)` = QUIC varint (1/2/4/8 bytes, big-endian, RFC 9000 §16).
+
+Cap: **64 KiB per framed message.** Server closes with `ProtocolViolation`
+if you exceed.
+
+> **Ground truth.** Use [`moq-core/codec/src/wire/control.rs`](../../moq-core/codec/src/wire/control.rs)
+> as the authoritative encoder/decoder source. Field ordering, varint
+> widths, and KVP layout are precise; do not roll your own.
+
+### 4.2 Connect — first frame, always
+
+```js
+// Pseudo-typescript; encoder is your moq-codec port.
+const connect = encodeControlMessage('Connect', {
+  request_id:  1n,
+  call_token:  jwtBytes,
+  sdk_name:    'web-sdk',
+  sdk_version: '1.0.0',
+  offers: [{
+    class:    'Audio',
+    purpose:  'Primary',
+    codecs:   ['Opus', 'PCMU', 'PCMA'],   // server picks Opus
+  }],
+  frame_size_ms: 20,
+})
+await writer.write(connect)
+
+const connectOk = await readNextControlMessage(reader)
+// → { type: 'ConnectOk', request_id: 1n, server_epoch_unix, bindings: [{ alias, codec, … }], rejected: [] }
+
+const audioAlias = connectOk.bindings[0].alias
+const serverEpochUnix = connectOk.server_epoch_unix
+```
+
+Server-side gates that will close the session if violated:
+- First frame on this bidi must be `Connect`. Anything else → close.
+- A datagram or uni stream that arrives before `ConnectOk` is rejected.
+
+### 4.3 Mid-call verbs + server-push
+
+After `ConnectOk` the bidi multiplexes:
+- Your verbs out (`Hold`, `Mute`, `SendDtmf`, `Resume`, `NegotiateMedia`).
+- Server `*Ok` responses (correlate by `request_id`).
+- Server-push events (`PeerAttached`, `PeerDetached`, `EndpointHeld`,
+  `EndpointMuted`, `PeerStateChanged`, `DtmfReceived`, `EndpointHangup`,
+  `MoqError`) — these carry `request_id = 0`.
+
+A single read loop on `ctrl.readable.getReader()` is sufficient. Dispatch
+by `msg_type`.
+
+### 4.4 Bytes may arrive split
+
+WT streams give you `Uint8Array` chunks at arbitrary boundaries. Buffer
+until you can decode at least the `msg_type | payload_len` prefix, then
+the full payload, then dispatch. Treat the reader as a byte stream, not
+a message stream.
+
+---
+
+## 5. Audio datagrams
+
+### 5.1 Uplink (you → server)
+
+```js
+const dgWriter = wt.datagrams.writable.getWriter()
+
+// Per encoded Opus frame from your AudioEncoder:
+async function sendFrame(encodedBytes, objectIdInGroup) {
+  const groupId = BigInt(Math.floor(Date.now() / 1000)) - BigInt(serverEpochUnix)
+  const datagram = encodeObjectDatagram({
+    track_alias:        BigInt(audioAlias),
+    group_id:           groupId,
+    object_id:          BigInt(objectIdInGroup),       // 0..49 within the wall-second
+    publisher_priority: 0,
+    payload:            encodedBytes,
+    end_of_group:       objectIdInGroup === 49,
+  })
+  await dgWriter.write(datagram)
+}
+```
+
+`group_id` is `(now_seconds - server_epoch_unix)`. `object_id` is the
+position within the wall-second (0..49 at 20 ms cadence). Receivers use
+the pair `(group_id, object_id)` for jitter buffering and gap detection.
+
+`wt.datagrams.maxDatagramSize` gives the usable payload budget. Opus
+40 B and PCMU/PCMA 160 B at 20 ms both fit any realistic MTU.
+
+> See [`moq-core/codec/src/wire/data_stream.rs`](../../moq-core/codec/src/wire/data_stream.rs)
+> for `ObjectDatagram` byte layout.
+
+### 5.2 Downlink (server → you)
+
+```js
+const dgReader = wt.datagrams.readable.getReader()
+const decoders = new Map()    // alias → AudioDecoder
+
+while (true) {
+  const { value, done } = await dgReader.read()
+  if (done) break
+  const obj = decodeObjectDatagram(value)
+  const dec = decoders.get(obj.track_alias)
+  if (!dec) continue                  // alias not yet PeerAttached
+  dec.decode(new EncodedAudioChunk({
+    type:      'key',
+    timestamp: derivedFromGroupAndObject(obj.group_id, obj.object_id),
+    data:      obj.payload,
+  }))
+}
+```
+
+One decoder per `PeerAttached.alias`. On `PeerDetached`, close the
+decoder and drop the entry.
+
+### 5.3 Loss handling
+
+Datagrams are unreliable — gaps happen. Detect via `object_id` gap,
+ask `AudioDecoder` for a concealment frame (`AudioDecoder.flush()` or
+manual PLC). Server never retransmits.
+
+---
+
+## 6. DTMF inbound (unidirectional sub-stream)
+
+DTMF *from a peer* arrives on a fresh server-initiated uni stream, one
+per digit:
+
+```js
+const uniReader = wt.incomingUnidirectionalStreams.getReader()
+while (true) {
+  const { value: stream, done } = await uniReader.read()
+  if (done) break
+  // stream is a ReadableStream<Uint8Array>
+  handleDtmfUniStream(stream)        // decodes SubgroupHeader + DtmfEvent + EndOfGroup
+}
+```
+
+The framing on this stream is documented in
+[`docs/wire-protocol.md`](wire-protocol.md) §"Stream paths (non-audio)".
+The payload is a single `DtmfEvent { digit, duration_ms }` protobuf
+message.
+
+DTMF *to the server* (you pressing a digit) is the `SendDtmf` verb on
+the bidi control stream — not a uni stream. The browser cannot open
+WT uni sub-streams at all in some specs/browsers, so we never required
+it for the outbound direction.
+
+---
+
+## 7. Session control verbs
+
+Same shape as native. See [`client-integration.md`](client-integration.md)
+§7 for full details. Quick reminder:
+
+| Verb | Direction | Cap claim required |
+|---|---|---|
+| `Hold { held: bool }` | Client → Server | `session.hold` |
+| `Mute { scope: Uplink \| Downlink \| Both \| None }` | Client → Server | `session.mute_self` |
+| `SendDtmf { digit, duration_ms }` | Client → Server | `dtmf_send` |
+| `Resume { call_token, last_event_seq }` | Client → Server | (token only) |
+| `NegotiateMedia { offers, frame_size_ms }` | Client → Server | (token only; additive) |
+
+The corresponding `*Ok` responses carry the echoed `request_id`. Server
+pushes the matching state-change event (`EndpointHeld`, `EndpointMuted`,
+`PeerStateChanged`, `DtmfReceived`) for other peers' UI consistency.
+
+---
+
+## 8. Hangup
+
+```js
+wt.close({ closeCode: 0, reason: '' })
+```
+
+Same semantics as the native client's QUIC `APPLICATION_CLOSE`:
+
+| Reason | closeCode |
+|---|---|
+| Normal | `0x00` |
+| User cancel | `0x01` |
+| App error | `0x02` |
+
+The server treats the WT close as a graceful hangup (ADR-0015), tears
+down the bridge, and emits `EndpointHangup{origin: Client}` to remaining
+peers.
+
+`wt.closed` Promise resolves with the close info when the server (or
+the network) closes from its side.
+
+---
+
+## 9. Reconnect — what's different from the native path
+
+| Native (QUIC) | Browser (WT) |
+|---|---|
+| Tier 1 — connection migration | **Not available.** Browser does not expose QUIC migration. |
+| Tier 2 — 0-RTT resumption | **Not available.** WebTransport API does not expose 0-RTT. |
+| Tier 3 — `Resume` verb | **Required path.** Open a fresh WT session, present same JWT (still within `exp`), send `Resume { call_token, last_event_seq }` on the new bidi. |
+
+So in the browser, *all* reconnects go through Tier 3. The server holds
+the endpoint suspended for `reconnect_window` (default 30 s) after the
+session drops. Reconnect within that window with the same `eid` (in the
+token) and the bridge state is preserved — `ResumeOk` returns the
+`EndpointSnapshot` (mute, held, peer subscriptions) and you resume
+audio pumps against the same aliases.
+
+```js
+wt.closed.catch(async () => {
+  // optional: visual "reconnecting…" state
+  for (const delay of [100, 250, 500, 1000]) {
+    try {
+      const wt2 = new WebTransport(url, opts)
+      await wt2.ready
+      await sendResume(wt2, { last_event_seq: lastSeenSeq })
+      // ResumeOk arrived → swap wt → wt2, rebind pumps
+      return
+    } catch (e) {
+      await new Promise(r => setTimeout(r, delay))
+    }
+  }
+  // give up; surface terminal error
+})
+```
+
+After `reconnect_window` lapses, server returns `EndpointNotProvisioned`
+and the controller has to call `StartModule` again — the app's "start a
+new call" flow.
+
+---
+
+## 10. Certificates
+
+### 10.1 Production
+
+Standard WebPKI cert chain. The browser uses the OS / WebPKI trust
+store. Nothing special on the client side — omit
+`serverCertificateHashes`.
+
+### 10.2 Development (self-signed)
+
+WebTransport supports `serverCertificateHashes` to trust a specific
+cert without a CA chain, **but** there are hard constraints:
+
+- Cert must use ECDSA-P256 (RSA not allowed).
+- Cert validity ≤ 14 days.
+- Both Subject and Issuer must be present.
+- Hash algorithm must be `sha-256`.
+
+```js
+async function sha256Bytes(pem) {
+  const b64 = pem.replace(/-----[^-]+-----/g, '').replace(/\s+/g, '')
+  const der = Uint8Array.from(atob(b64), c => c.charCodeAt(0))
+  return new Uint8Array(await crypto.subtle.digest('SHA-256', der))
+}
+
+const certHash = await sha256Bytes(serverCertPem)
+const wt = new WebTransport(url, {
+  serverCertificateHashes: [{ algorithm: 'sha-256', value: certHash.buffer }],
+})
+```
+
+Hand the dev cert (or just its sha-256) to the JS bundle out-of-band.
+The dev deploy script (`scripts/deploy-dev.sh`) is the right place to
+emit it.
+
+---
+
+## 11. Errors and error codes
+
+All app-level errors arrive as a typed `MoqError` ControlMessage on the
+bidi stream **before** the session is closed. Same enum as native — see
+[`client-integration.md` §10](client-integration.md):
+
+| Code | Meaning |
+|---|---|
+| `0x1001 EndpointNotProvisioned` | Token's `eid` does not match a live endpoint. |
+| `0x1002 EndpointAlreadyConnected` | Another session holds this endpoint. |
+| `0x1010 TokenInvalid` | Sig / iss / aud / schema check failed. |
+| `0x1011 TokenExpired` | `exp` past. |
+| `0x1012 TokenReplayed` | `jti` already seen in the cache. |
+| `0x1020 ProtocolViolation` | Bad frame ordering, oversize, etc. |
+| `0x1021 CapabilityMissing` | Verb requires a `cap` you don't have. |
+| `0x1022 IllegalState` | Verb invalid in current state. |
+| `0x1030 ResourceExhausted` | Server capacity hit. |
+| `0x1031 ReplayLost` | Resume gap too wide. |
+| `0x1040 SessionEnded` | Server closed the session cleanly. |
+
+Transport-level failures (cert rejected, server unreachable, network
+loss) surface as a rejection on `wt.ready` or `wt.closed` — no
+`MoqError` because the session never opened or already dropped.
+
+---
+
+## 12. Browser limitations to design around
+
+| Limitation | Workaround |
+|---|---|
+| No `Origin` enforcement in WT API | Server doesn't gate on Origin — auth is JWT in the framed Connect, not cookies. |
+| No custom request headers on the WT CONNECT | Auth rides the Connect ControlMessage, not headers. |
+| WebCodecs Opus support varies by browser | Detect via `AudioEncoder.isConfigSupported`; fall back to a wasm Opus encoder if you need broader reach. |
+| Datagram backpressure is implicit | Watch `wt.datagrams.writable.getWriter().ready` if you have a bursty sender; for 20 ms audio it's never the bottleneck. |
+| Tab visibility / `requestAnimationFrame` throttling | Audio pumps must use timers (`setInterval` / `AudioWorklet` clock), not rAF. |
+| Same-origin policy for fetch-based token retrieval | The token-mint endpoint must be CORS-enabled or same-origin as the JS bundle. |
+
+---
+
+## 13. Minimal happy-path skeleton
+
+```js
+async function startCall({ url, jwt, certHash /* optional */ }) {
+  // 1. Open session
+  const wt = new WebTransport(url, certHash
+    ? { serverCertificateHashes: [{ algorithm: 'sha-256', value: certHash }] }
+    : undefined)
+  await wt.ready
+
+  // 2. Open control bidi sub-stream
+  const ctrl = await wt.createBidirectionalStream()
+  const writer = ctrl.writable.getWriter()
+  const reader = ctrl.readable.getReader()
+
+  // 3. Send Connect, await ConnectOk
+  await writer.write(encodeConnect({
+    request_id: 1n,
+    call_token: jwt,
+    sdk_name: 'web-sdk', sdk_version: '1.0.0',
+    offers: [{ class: 'Audio', purpose: 'Primary', codecs: ['Opus'] }],
+    frame_size_ms: 20,
+  }))
+  const connectOk = await readControlMessage(reader)
+  const { audioAlias, serverEpochUnix } = parseConnectOk(connectOk)
+
+  // 4. Spin up the four pumps
+  startBidiReadLoop(reader, dispatchEvent)              // server-push + verb Oks
+  startDatagramSender(wt, audioAlias, serverEpochUnix)  // mic → Opus → datagram
+  startDatagramReceiver(wt)                              // datagrams → decoders
+  startUniReceiver(wt)                                   // DTMF uni streams
+
+  // 5. Wait for session end
+  wt.closed.then(info => onClosed(info), err => onError(err))
+
+  return {
+    hangup: () => wt.close({ closeCode: 0, reason: '' }),
+    sendDtmf: (digit) => sendDtmfVerb(writer, digit),
+    hold: (held) => sendHoldVerb(writer, held),
+    mute: (scope) => sendMuteVerb(writer, scope),
+  }
+}
+```
+
+---
+
+## 14. Quick reference
+
+| Constant | Value |
+|---|---|
+| URL path | `/web` |
+| Control stream | one bidi sub-stream, opened by the client right after `wt.ready` |
+| First frame on the control stream | `Connect` (must) |
+| Audio codec | Opus 48 kHz mono, 20 ms |
+| Datagram frame | one `ObjectDatagram` per audio frame |
+| Max framed control message | 64 KiB |
+| `reconnect_window` | 30 s (server-side; Tier-3 Resume budget) |
+| Token TTL | 4 h (server-issued) |
+
+---
+
+## 15. Where to go next
+
+- Wire-level reference: [`client-integration.md`](client-integration.md)
+- Control message byte layout: [`moq-core/codec/src/wire/control.rs`](../../moq-core/codec/src/wire/control.rs)
+- ObjectDatagram byte layout: [`moq-core/codec/src/wire/data_stream.rs`](../../moq-core/codec/src/wire/data_stream.rs)
+- Proto schemas: [`ms-proto/proto/v1/`](../ms-proto/proto/v1/)

package/docs/contract.md

@@ -0,0 +1,71 @@
+# Web SDK contract
+
+This public SDK consumes the browser chat and session REST surfaces produced by
+`/home/yl/workspace/platform/cx`. Public examples explain usage; this file is the
+reciprocal cross-repository contract ledger.
+
+## Interactive chat prompts
+
+- Incoming ORPC messages decode `buttons: [{label,value,type}]` and
+  `gallery: [{title,description,image?,buttons}]`; a gallery image is
+  legitimately absent. The canonical producer and consumer registry is
+  `/home/yl/workspace/platform/cx/CONTRACT.md` (consumers of `buttons` /
+  `gallery`), reciprocated by the active `/home/yl/workspace/web/chat` consumer.
+- The public `SendMessagePayload.buttonReply {value,label?}` is a local typed
+  adapter. It never rides the wire as a nested object: `ChatSession` maps
+  `value` to top-level ORPC `MessageRequest.value` and optional `label` (the
+  gallery card title) to `MessageRequest.galleryLabel`; the button caption
+  remains `text`. cx's reciprocal consumer registration is its Button / Gallery
+  reply-shape entry. This adapter supersedes the original Sprint BG proposal to
+  delete `buttonReply` while preserving the canonical wire exactly.
+
+## Session directory continuity hardcut
+
+- `GET /sessions` is parsed as `SessionSummary[]` and every row must contain
+  `active: boolean`. Missing or non-boolean `active` is a decode failure; there is
+  no compatibility default. The producer is `platform/cx` (`CONTRACT.md`,
+  "Session directory + history + resume") and the native mirror is
+  `workspace/apps/sdk/session/src/types.rs`.
+- `active` is live-owner state, not stored session status. It is meaningful only
+  while list/bootstrap and chat ORPC Attach resolve to the same live cx owner.
+- Browser auto-restore and browser push are intentionally absent. The in-workspace
+  `web/chat` consumer may display/list the decoded rows but must not turn `active`
+  into automatic background attachment.
+
+## Release gate
+
+Run typecheck, unit tests, and the production build, then rebuild the linked
+`workspace/web/chat` consumer before publication. Publishing to npm remains an
+owner action and is never part of an implementation spin.
+
+## Provisioned receive-only voice join
+
+The active in-workspace consumer is `workspace/web/cx` Insights Live. Its
+page-owned supervision controller passes platform/cx's one-time media offer
+directly to this seam, keeps the token in memory only, and uses
+`enableCapture`/`releaseCapture` for Coach/Listen. Deployed gw route, policy,
+certificate, and live-probe evidence remains the workspace LS-4 gate.
+
+`joinSession({channel:'voice', sessionId, url, token,
+voice:{receiveOnly:true}})` is the additive listen-only seam for a media offer
+provisioned by another control plane. It still requires `initialize()` but does
+not require `authenticate()` or `/config`.
+
+The SDK starts the audio worklet and WebTransport receive path, awaits
+`ConnectOk`, then sends `Mute(uplink)` and awaits the matching `MuteOk` before
+firing `onConnected`. It never calls `getUserMedia` or enables capture on this
+path. Server mute acknowledgement, not browser state, is the uplink-safety
+boundary. Omitting the option preserves the existing capture-on-connect
+behavior. A failed voice start removes its SessionManager entry and attempts to
+dispose partial resources so the same provisioned id can be retried; a teardown
+failure is reported explicitly without masking the original start failure.
+
+`enableCapture(sessionId)` is the serialized Listen→Coach transition. It
+acquires and enables the worklet pipeline while the endpoint is uplink-muted,
+waits for a generation-correlated worklet acknowledgement, awaits
+`Mute(none)`/`MuteOk`, and only then opens the local outbound datagram gate.
+`releaseCapture(sessionId)` closes that gate immediately, awaits
+`Mute(uplink)`/`MuteOk`, disables capture, disconnects capture/diagnostic nodes,
+stops every microphone track, and nulls the stream. Permission, worklet, mute,
+transport, terminal-event, and teardown races fail closed: late generations and
+stale transport acknowledgements cannot reopen capture or resolve new requests.

package/docs/new-chat-protocol.md

@@ -0,0 +1,91 @@
+# Chat protocol: wire shape + extension rule
+
+The chat wire is the **`chat.v1` protobuf schema** spoken over
+oRPC-over-WebTransport (since 0.5.0; the SSE lane is deleted — there is
+no fallback transport). The schema's canonical source is
+`platform/cx/protos/chat.proto` in the Origon workspace, vendored into
+this repo as `src/orpc-gen/chat_pb.ts`; the SDK decodes exactly the
+arms that descriptor carries.
+
+## The wire, in one table
+
+| Direction | RPC (`chat.v1.Session/…`) | Payload |
+|-----------|-------------------------------|---------|
+| attach    | `Attach` (server-streaming)   | initial `AttachResponse {participantId, role}`, then one `ChatEvent` per frame |
+| send      | `Message` (unary)             | `MessageRequest {clientMessageId, text?, html?, attachments, value?, galleryLabel?}` → the canonical `Message` echo |
+| typing    | `Typing` (unary)              | `TypingRequest {state: "on"\|"off"}` |
+| leave     | `Leave` (unary)               | empty; immediate server-side finalize |
+
+`ChatEvent` is a oneof: `message`, `typing`, `participant_joined`,
+`participant_left`, `session_ended`, `heartbeat`. The SDK surfaces
+`message`, `typing` and `session_ended`; everything else — and any arm
+it does not know — is consumed and dropped. That tolerance is the
+forward-compat contract.
+
+## The extension rule: proto arms first
+
+**A chat feature does not exist until it has a proto arm.** The path for
+any new server→client event or client→server field is:
+
+1. **Proto** — the arm lands in cx's `chat.proto` (a new `ChatEvent`
+   oneof arm, or a new `MessageRequest` field) and cx emits/reads it.
+2. **Re-vendor** — the monorepo's `web/kit/scripts/ship-orpc.sh`
+   regenerates `src/orpc-gen/` here (never hand-edited).
+3. **SDK surface** — a decode arm in `src/chat/orpc.ts` and, if the
+   consumer needs it, a callback/payload field.
+
+The SSE era did this backwards: the SDK shipped designed-ahead callbacks
+(`onControlUpdated`, `onToolCalls`, `onAssistantModeChanged`) and
+`sendMessage` fields for events no backend ever emitted. Those inert
+surfaces were **deleted with the transport** (owner decision,
+2026-08-06). If control-handoff, tool-calls or mode-switch semantics
+return, they re-enter through the three steps above.
+
+## Streaming AI replies (live behavior)
+
+For AI responses the backend streams the reply as multiple `message`
+events carrying the **same `id`** with `state: "streaming"`, terminated
+by one final event with `state: "completed"`.
+
+- First chunk with a new `id` → `onMessageAdded(message)` — the
+  consumer renders a new row.
+- Subsequent chunks with the same `id` → `onMessageUpdated({id, message})`.
+- `text`/`html` is the complete cumulative content so far, **not a
+  delta** — consumers replace, not append.
+- One-shot messages are a single event with `state: "completed"`; an
+  unknown/absent `state` degrades to `"completed"`.
+
+## Prompt buttons + gallery (live behavior)
+
+A `message` may carry `buttons` (`MessageButton {label, value, type}`)
+and/or `gallery` (`MessageCard {title, description, image?, buttons}`).
+The reply leg is `SendMessagePayload.buttonReply {value, label?}`, which
+the SDK maps onto the wire's top-level `value` / `galleryLabel`.
+
+## Role mapping
+
+The SDK's `MessageRole` is `'ai' | 'external' | 'user' | 'system'`;
+unknown wire roles degrade to `'external'` (the visitor side is the safe
+default). Mapping vs. the legacy chat-sdk:
+
+| Legacy role  | New role     | Who it represents                                           |
+|--------------|--------------|-------------------------------------------------------------|
+| `assistant`  | `ai`         | AI bot                                                      |
+| `user`       | `external`   | End-user / customer (the visitor in the chat widget)        |
+| `supervisor` | `user`       | Staff / internal operator (the human agent on the dashboard)|
+| `system`     | `system`     | System-injected messages                                    |
+
+## Outbound payload: what actually rides the wire
+
+`sendMessage`'s wire carrier is `MessageRequest`:
+`clientMessageId` (SDK-minted idempotency key), `text`, `html`,
+`attachments` (ids/names only — URLs are server-assigned on the echo),
+`value`, `galleryLabel`. The public payload surface also accepts the local
+typed `buttonReply {value,label?}` adapter and maps it to those two top-level
+wire fields; the nested adapter never rides ORPC. Two other local-only fields
+are stripped before send: `role` (the provisional-row hint) and
+`attachments[].localUrl` (preview blob). The
+SSE-era fields with no wire carrier (`type`/`results`/`meta`/`context`/
+`createSystem`/`mode`) were deleted with 0.5.0 (owner decision,
+2026-08-07) — a new outbound field starts with a proto arm, per the
+extension rule above.