first commit

docs/ui/react/react-audio-stream/src/transports/transport.md

@@ -0,0 +1,81 @@
+# Stream transport adapters — shared types
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `transport.types.ts` module declares the structural contract that
+`StreamSession` (authored in chunk A of the `@suaveplan/react-audio-stream`
+split) accepts via constructor injection. By co-locating the contract with
+the three concrete adapters (WebRTC, WebSocket, Trystero) in chunk B we
+guarantee every adapter conforms to the same surface and the session can
+hot-swap them without re-implementation. The shapes mirror the canonical
+specification
+so chunk-A and chunk-B merges remain structurally compatible.
+
+## Features
+
+- `StreamTransportAdapter` — DI contract for any peer-to-peer audio transport.
+- `TransportEvent` — discriminated union covering connect, disconnect,
+  inbound track, and RTT-probe ticks.
+- `SignallingChannel` / `SignallingMessage` — transport-neutral signalling
+  envelope used by the WebRTC adapter (callers MUST plug their own channel).
+- `IceConfig` — STUN/TURN configuration with no embedded defaults.
+- `InterruptionClass` / `InterruptionCause` — disconnect-cause classification
+  fed into chunk A's telemetry histogram.
+- `ReactAudioStreamErrorLike` — local mirror of chunk A's error shape so
+  chunk-B tests can assert on `.code` without a circular merge dependency.
+
+## Usage: Basic
+
+```ts
+import type { StreamTransportAdapter } from "@suaveplan/react-audio-stream/transports";
+
+function logId(adapter: StreamTransportAdapter): void {
+    console.log(adapter.id);
+}
+```
+
+## Usage: Advanced
+
+```ts
+import type {
+    StreamTransportAdapter,
+    TransportEvent,
+} from "@suaveplan/react-audio-stream/transports";
+
+function watch(adapter: StreamTransportAdapter): () => void {
+    return adapter.subscribe((event: TransportEvent) => {
+        switch (event.type) {
+            case "connected":
+                console.log("peer joined", event.peerId);
+                break;
+            case "disconnected":
+                console.warn("peer dropped", event.class, event.cause);
+                break;
+            case "rtt":
+                console.debug("rtt", event.peerId, event.ms, "ms");
+                break;
+        }
+    });
+}
+```
+
+## API Reference
+
+- `StreamTransportAdapter.connect(roomId)` — join a named room.
+- `StreamTransportAdapter.disconnect()` — leave + tear down peer state.
+- `StreamTransportAdapter.send(peerId, payload)` — unicast bytes.
+- `StreamTransportAdapter.broadcast(payload)` — fan-out bytes.
+- `StreamTransportAdapter.getRtt(peerId?)` — sample round-trip in ms.
+- `StreamTransportAdapter.subscribe(handler)` — wire `TransportEvent` flow.
+
+## Implementation Notes
+
+The contract is intentionally minimal: it omits opinionated state-machine
+hooks because `StreamSession` owns its own FSM (chunk A). Adapters MUST
+report disconnects with a fully populated `InterruptionCause` so chunk A's
+`InterruptionClassifier` can map ICE state, close code, or media-permission
+error names without probabilistic heuristics.