net: add heartbeat reconnect and server restart/version announcements

docs/protocol-notes.md

@@ -38,6 +38,9 @@ This is a behavior guide for packet semantics beyond raw schemas.
 ## Welcome Metadata
 
 - `welcome.worldConfig.gridSize`: server-authoritative grid size used by clients for bounds/drawing.
+- `welcome.serverInfo`: server process identity/version metadata:
+  - `instanceId`: unique id generated at server startup
+  - `version`: server package version (or `unknown` fallback)
 - `welcome.uiDefinitions`: server-provided item UI definitions:
   - `itemTypeOrder`: add-item menu order
   - `itemTypes[].tooltip`: item-level tooltip/help text
@@ -53,3 +56,11 @@ This is a behavior guide for packet semantics beyond raw schemas.
 - Server is authoritative for all action validation and normalization.
 - Client validates incoming packet shapes and applies runtime behavior.
 - Client-side item edit validation is convenience only; server remains source of truth.
+
+## Heartbeat/Stale Recovery
+
+- Client sends automatic heartbeat `ping` packets every 10 seconds while connected.
+- Heartbeat pings use negative `clientSentAt` ids and are internal (not user-visible ping status).
+- If no heartbeat `pong` arrives within 25 seconds, client force-disconnects and reconnects.
+- After reconnect, if `welcome.serverInfo.instanceId` changed, client announces:
+  `Server restarted, version <version>.`

docs/runtime-flow.md

@@ -8,12 +8,14 @@
 4. Server sends `welcome` with users/items snapshot.
 5. Client:
    - applies `welcome.worldConfig.gridSize` for authoritative grid bounds/rendering
+   - records `welcome.serverInfo` (`instanceId`, `version`) for restart detection
    - applies `welcome.uiDefinitions` for item menus/properties/options
    - sends initial `update_position`
    - sends initial `update_nickname`
    - creates peer runtimes for known users
    - syncs item runtimes (`radio`, `emit`)
    - applies audio layer state
+   - starts signaling heartbeat monitor
    - starts game loop
 
 ## Main Loop
@@ -38,12 +40,22 @@ Core incoming message effects:
 - `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).
+- `pong`:
+  - positive `clientSentAt`: user ping response (`P` command)
+  - negative `clientSentAt`: internal heartbeat response
+
+## Stale Connection Recovery
+
+- While running, client sends heartbeat `ping` every 10 seconds.
+- If no heartbeat `pong` is observed for 25 seconds, client auto-reconnects.
+- If reconnect lands on a different `welcome.serverInfo.instanceId`, client announces server restart/version.
 
 ## Disconnect/Cleanup
 
 On disconnect:
 
 - Close signaling.
+- Stop heartbeat monitor.
 - Stop local media tracks.
 - Cleanup peers and all audio runtimes.
 - Reset UI/mode state and lists.