Calls: end-to-end browser calling and the complete calls UI

CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## Unreleased
+
+- Added `CallsSocket` (the calls WebSocket: pushed `call.*` lifecycle events,
+  ICE both ways, ticket-based auth, capped reconnect) as a drop-in lifecycle
+  source for `createSignalingCallsBackend` and a `candidateTransport` for
+  `WebRtcMediaFactory`; `CallsSignalingClient` gained `renegotiate`,
+  `socketTicket`, and `socketUrl`; `BrowserTransport` exposes `baseUrl`.
+- `CallsController` gained `enableVideo()` (audio→video upgrade by re-offer),
+  a `reconnecting` status with ICE restart and a bounded resumption window,
+  and ends the call as `pod_lost` / `capacity` when the offer is refused
+  with 410 / 503. The React camera button upgrades audio calls to video;
+  `CallStage` and `pmfa-call` show "Reconnecting…".
+- Added `MessagingClient.voip.socketTicket` and `voip.agentToken`; typed
+  `maxSetupsPerMinute` in the client rules; refreshed the contracts and the
+  coverage ledger to polymorfa@83b819dd6 (renegotiate, ws-ticket,
+  agent-token).
+
+- Added `MessagingClient.voip.token` for minting the browser call token, typed
+  the client-rules response the runtime actually returns (including the calls
+  bindings `maxConcurrency` and `allowedNumber`), and typed client actions.
+- Added `createSignalingCallsBackend`, `IncomingCallRelay`, and
+  `incomingCallFromWebhook` so browser calls run end to end on the REST
+  signaling surface; `CallsController` now carries the calling `line` and
+  `capabilities`, device lists and selections, live device switching, and
+  `connectedAt`.
+- Replaced the placeholder `CallSurface` with the complete call UI —
+  `IncomingCallCard`, `CallStage`, `CallControls`, `DialPad`, a pop-out call
+  window, and `useCallDuration` — themed from the shared appearance variables
+  and localized through new `calls.*` messages; `pmfa-call` follows the same
+  controller contract.
+- Refreshed the Messaging and Platform contracts and the coverage ledger for
+  the `/api/voip/*` signaling routes and the `call.ended` / `call.telemetry`
+  webhook events.
+
 ## 0.1.0-dev.0 - 2026-08-19
 
 - Added handwritten Messaging clients for sessions, messages, and webhooks.

README.md

@@ -6,7 +6,7 @@ The development branch contains the TypeScript server SDK, a framework-neutral
 browser runtime, shared UI contracts, Web Components, React bindings, thin
 Next.js server helpers, and a production-gated developer assistant. It follows
 the Messaging and Platform contracts recorded at source revision
-`f156af2dda13e62b6b106a542fdedb39524bdb66`. Graph-compatible APIs are outside
+`d2ddaef836762dc189887f4f21b17c74c9c79ee7`. Graph-compatible APIs are outside
 this SDK's initial scope.
 
 ## Package architecture
@@ -84,6 +84,7 @@ The handwritten Messaging resources in this milestone are:
 - `business`: manage the connected Business App profile, commerce catalog,
   products, collections, orders, compliance, linked accounts, and eligibility
 - `calls`: reject an identified incoming Linked Device call
+- `voip`: mint the browser call token used by `@polymorfa/browser` signaling
 - `campaigns`: list, create, retrieve, inspect analytics, launch, pause, resume,
   stop, and requeue project campaigns through the Messaging control plane
 - `messages`: send every contract-defined message kind through one typed send
@@ -338,15 +339,32 @@ that interoperate with the Custom Elements standard. `@polymorfa/react`
 provides idiomatic hooks and components, including controlled and SDK-owned
 controller lifecycles.
 
-### Calls boundary
-
-Call media and signaling follow the implementation in `voip-v2`: browser WebRTC
-media, offer/answer exchange, trickle ICE candidate submission and polling, and
-the existing `/api/voip/calls/{id}` signaling paths. The application supplies a
-`CallsBackend` for place, answer, reject, hangup, and lifecycle events because
-that control plane is not exposed by the current `voip-v2` REST signaling
-surface. The SDK does not invent group rooms, participants, reactions, hand
-raising, or waiting rooms.
+### Calls
+
+Call media and signaling follow the platform's browser signaling surface:
+WebRTC media, offer/answer exchange, trickle ICE candidate submission and
+polling, and idempotent teardown over the `/api/voip/calls/{id}` paths, all on
+the client token. `createSignalingCallsBackend` is the `CallsBackend` for that
+surface; `IncomingCallRelay` is where the application hands the browser the
+`call.received` webhook it received on its own server
+(`incomingCallFromWebhook` maps the payload). The server mints the browser
+token with `MessagingClient.voip.token` after granting the session's client
+rules the `voip_place`, `voip_answer`, and `voip_signal` actions; those rules
+also bind calls per token (`maxConcurrency`, `allowedNumber`).
+
+Calls carry a `line`: `linkedDevice` (a paired WhatsApp device session, audio
+and video) or `cloudApi` (the WhatsApp Business Calling API, audio only). Every
+component gates on the snapshot's `capabilities`, never on the line name. The
+controller also owns capture/playback device choice (`setPreferredDevices`,
+`switchDevice`, `refreshDevices`) so a microphone or camera swap mid-call is a
+track replacement, not a renegotiation. The SDK does not invent group rooms,
+participants, reactions, hand raising, or waiting rooms.
+
+`@polymorfa/react` ships the complete call UI: `CallSurface` (incoming card,
+stage, control dock, and a pop-out window), plus `IncomingCallCard`,
+`CallStage`, `CallControls`, and `DialPad` for composition. The design mirrors
+the official WhatsApp desktop call windows in a monochrome Material-3 voice;
+colors derive from the shared appearance variables.
 
 ## Next.js and dev mode