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

CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## Unreleased
+
+- `createSignalingCallsBackend` no longer invents a call id for outbound
+  calls. Nothing on the client-token surface dials a destination, so an
+  invented id reached no pod and its offer was refused as not-ready forever.
+  Outbound calling now goes through a `place` hook that hands the destination
+  to the application's server and takes back the platform's call id; the
+  removed `createCallId` option had no working use.
+- `CallsSocket` heartbeats. A half-open connection still reports OPEN, so
+  candidates were dropped while the media factory kept REST polling disabled;
+  an unanswered `ping` now closes it and reconnects. `heartbeatMs` tunes the
+  period, 0 disables it.
+- `CallsSocket` takes a `line`, carried onto the calls it delivers. It always
+  reported `linkedDevice`, so a Business Calling API session showed video
+  controls on an audio-only line.
+- `CallsSignalingClient.socketTicket` no longer names a session. The client
+  token is bound to one, and the API answers 403 when a request names another.
+- `CallsSocket` reports a signaling client that cannot mint tickets as an
+  `unsupported` error and stops, instead of backing off forever against a
+  failure that can never succeed; ordinary ticket failures still retry, now
+  reported as `ticket_failed`.
+- `CallsSocket` gained `onError`, so a server `error` frame reaches the
+  application instead of being parsed and dropped while the socket keeps
+  reconnecting against a permanent failure.
+- Timer defaults are bound to `globalThis`. `CallsController`, `CallsSocket`,
+  `WebRtcMediaFactory`, and the QuickLink controller called the unbound
+  `setTimeout`/`setInterval` with the instance as receiver, which browsers
+  reject with `TypeError: Illegal invocation`.
+- Calls hardening: a recovered ICE flap leaves `reconnecting` instead of
+  waiting for a connection-state change that may never come; mute pressed
+  while the microphone was still being acquired now reaches the tracks;
+  pushed ICE candidates are held until the answer is applied rather than
+  discarded; setup failures release the candidate subscription; an audio-only
+  call no longer keeps an unnegotiated camera track (which had made the video
+  upgrade unretryable); a failed upgrade rolls the camera back; the calls
+  WebSocket survives a throwing constructor and validates every frame shape; a
+  camera button in `pmfa-call` upgrades an audio call over a video-capable
+  line, as the React dock's already did; a
+  failed re-offer rolls the peer out of `have-local-offer` so later upgrades
+  and ICE restarts are not blocked by the stale offer; the audio→video upgrade
+  acquires the camera chosen during the call rather than the one selected when
+  it opened; a failed device swap
+  releases the stream it acquired; and `pmfa-call` localizes the connected
+  heading rather than rendering a raw status identifier.
+
+- 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@b413f2c6a (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
+`b413f2c6a701c86ec593241a70145ee89cc2bcd2`. 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,34 @@ 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; outbound calls go through its `place` hook, because starting a call
+is a server-key operation and the browser can only attach media to a call the
+platform already owns. `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