Add core architecture and workflow documentation

docs/runtime-flow.md

@@ -0,0 +1,54 @@
+# Runtime Flow
+
+## Connect Flow
+
+1. User clicks connect.
+2. Client validates nickname and sets up local media.
+3. Client connects signaling websocket.
+4. Server sends `welcome` with users/items snapshot.
+5. Client:
+   - sends initial `update_position`
+   - sends initial `update_nickname`
+   - creates peer runtimes for known users
+   - syncs item runtimes (`radio`, `emit`)
+   - applies audio layer state
+   - starts game loop
+
+## Main Loop
+
+Each frame:
+
+- Handle local movement input.
+- Update spatial voice audio.
+- Update spatial radio audio.
+- Update spatial item emit audio.
+- Draw canvas scene.
+
+## Message Handling
+
+Core incoming message effects:
+
+- `signal`: WebRTC negotiation and ICE exchange.
+- `update_position`: update peer position; may play movement/teleport world sound.
+- `update_nickname`: update peer display name.
+- `chat_message`: append/readable status; optional system sound class.
+- `item_upsert`: replace item snapshot and resync item runtimes.
+- `item_remove`: remove item and cleanup runtimes.
+- `item_action_result`: success/error status for actions.
+- `item_use_sound`: play one-shot spatial sample (world layer gated).
+
+## Disconnect/Cleanup
+
+On disconnect:
+
+- Close signaling.
+- Stop local media tracks.
+- Cleanup peers and all audio runtimes.
+- Reset UI/mode state and lists.
+
+## Runtime Components
+
+- `PeerManager`: peer connection lifecycle and remote track attach.
+- `RadioStationRuntime`: shared stream sources + per-item output/effects/spatialization.
+- `ItemEmitRuntime`: per-item looping emit source + spatialization.
+- `AudioEngine`: shared audio context, samples, effects, voice graph.