Add websocket push for the crosspoint UI, update docs to match

- GET /ws pushes crosspoint state on connect and on every change
  (~200ms detection), so the grid updates live with no client
  polling once connected. REST GET /api/state kept for first paint
  and as a fallback. Verified live in a real browser: a route change
  made via curl (i.e. from outside the page) appeared in the grid
  with zero interaction.
- README/architecture/roadmap updated to reflect tonight's actual
  verified status: real end-to-end SRT relay integration tests, CI,
  route persistence, and websocket push are all done; the one
  remaining honest gap is testing against real third-party SRT
  hardware / a non-loopback network path.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: allan sargeant

Cargo.lock

@@ -2,11 +2,12 @@
 
 > **AI-assisted project.** This codebase was created with [Claude](https://claude.com/claude-code)
 > (Anthropic), directed and reviewed by a human author. The relay/crosspoint
-> engine and web UI have been exercised locally (unit tests, real SRT
-> listener sockets, a live crosspoint switch via the web UI — see
-> [Status](#status)) but **not yet run against real-world SRT
-> encoders/decoders or over an actual network path**. Review before relying
-> on it for anything live.
+> engine and web UI have been exercised locally — including integration
+> tests that relay real SRT protocol traffic end-to-end and a live
+> crosspoint switch via the web UI, see [Status](#status) — but **not yet
+> run against real-world third-party SRT encoders/decoders or over an
+> actual (non-loopback) network path**. Review before relying on it for
+> anything live.
 
 A crosspoint-based [SRT](https://www.srtalliance.org/) router: any number of
 SRT inputs, any number of SRT outputs, and a router-style crosspoint (each
@@ -44,19 +45,29 @@ hardware router's control port.
 - The crosspoint engine (`crates/core`) — output-follows-route-change
   behavior is unit tested.
 - A local web UI (`crates/web`) — grid of outputs x sources, click to route,
-  polls `/api/state` once a second.
-- Verified locally: `cargo test` passes; running the binary against
-  `config/example.toml` actually binds real UDP/SRT listener sockets
-  (confirmed via `lsof`), the REST API drives real crosspoint state changes,
-  and clicking a cell in the web UI (in a real browser) correctly re-routes
-  an output.
-
-**Not yet done:** no test against a real SRT encoder/decoder or over a real
-network (only loopback-adjacent local testing so far), no persistence of
-routing across a restart, no special-purpose sources (stills/media
-player/scaler), no auth on the web UI/API, no external control
-API/Companion integration. See [docs/roadmap.md](docs/roadmap.md) for the
-full phased plan.
+  updated live over a websocket (`GET /ws`) with a REST poll (`GET
+  /api/state`) as first paint / fallback.
+- Routing changes optionally persist to disk (`[state]` in the config) and
+  reload on restart, overriding each output's `default_source`.
+- CI (GitHub Actions) runs `fmt --check`, `clippy -D warnings`, and the full
+  test suite on every push/PR.
+- Verified locally, not just compiled: `cargo test` passes, including
+  integration tests (`crates/srt-io/tests/relay.rs`) that relay real SRT
+  protocol traffic end-to-end through the crosspoint using `srt-tokio`
+  clients as the encoder/decoder — one test also exercises a **live
+  re-route mid-stream over an already-established SRT connection**.
+  Separately confirmed by hand: running the binary against
+  `config/example.toml` binds real UDP/SRT listener sockets (via `lsof`),
+  the REST API and a real browser click both drive live crosspoint changes,
+  the websocket push updates the grid with no client-side polling, and a
+  persisted route survives a real process restart.
+
+**Not yet done:** no test against a real third-party SRT
+encoder/decoder or over a real (non-loopback) network path — only local
+testing so far, still the main open gap. Also missing: special-purpose
+sources (stills/media player/scaler), auth on the web UI/API, external
+control API/Companion integration. See [docs/roadmap.md](docs/roadmap.md)
+for the full phased plan.
 
 ## Quick start
 

README.md

@@ -6,7 +6,7 @@ license.workspace = true
 
 [dependencies]
 crosspoint-core = { path = "../core" }
-axum = "0.7"
+axum = { version = "0.7", features = ["ws"] }
 tokio = { version = "1", features = ["full"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

crates/web/Cargo.toml

@@ -5,16 +5,24 @@
 
 use std::net::SocketAddr;
 use std::sync::Arc;
+use std::time::Duration;
 
+use axum::extract::ws::{Message, WebSocket, WebSocketUpgrade};
 use axum::extract::State;
-use axum::response::Html;
+use axum::response::{Html, IntoResponse};
 use axum::routing::{get, post};
 use axum::{Json, Router};
 use crosspoint_core::Crosspoint;
 use serde::{Deserialize, Serialize};
 
 const INDEX_HTML: &str = include_str!("../static/index.html");
 
+/// How often the websocket handler checks for a routing change to push.
+/// Polling (rather than a change-hook on `crosspoint-core`) keeps the core
+/// engine free of any web-specific API — same tradeoff the REST endpoint
+/// and the router binary's own state-persistence task already make.
+const PUSH_POLL_INTERVAL: Duration = Duration::from_millis(200);
+
 #[derive(Serialize)]
 struct StateResponse {
     sources: Vec<String>,
@@ -33,16 +41,20 @@ struct RouteResponse {
     ok: bool,
 }
 
+fn snapshot(crosspoint: &Crosspoint) -> StateResponse {
+    StateResponse {
+        sources: crosspoint.source_ids(),
+        outputs: crosspoint.output_ids(),
+        routes: crosspoint.routes(),
+    }
+}
+
 async fn index() -> Html<&'static str> {
     Html(INDEX_HTML)
 }
 
 async fn get_state(State(crosspoint): State<Arc<Crosspoint>>) -> Json<StateResponse> {
-    Json(StateResponse {
-        sources: crosspoint.source_ids(),
-        outputs: crosspoint.output_ids(),
-        routes: crosspoint.routes(),
-    })
+    Json(snapshot(&crosspoint))
 }
 
 async fn post_route(
@@ -53,11 +65,46 @@ async fn post_route(
     Json(RouteResponse { ok })
 }
 
+async fn ws_handler(
+    ws: WebSocketUpgrade,
+    State(crosspoint): State<Arc<Crosspoint>>,
+) -> impl IntoResponse {
+    ws.on_upgrade(move |socket| push_state(socket, crosspoint))
+}
+
+/// Push the crosspoint state to the client on connect and again every time
+/// it changes, so the grid updates live without waiting on its own poll.
+async fn push_state(mut socket: WebSocket, crosspoint: Arc<Crosspoint>) {
+    let mut last: Option<String> = None;
+    loop {
+        let Ok(body) = serde_json::to_string(&snapshot(&crosspoint)) else {
+            return;
+        };
+        if last.as_deref() != Some(body.as_str()) {
+            if socket.send(Message::Text(body.clone())).await.is_err() {
+                return;
+            }
+            last = Some(body);
+        }
+        tokio::select! {
+            _ = tokio::time::sleep(PUSH_POLL_INTERVAL) => {}
+            msg = socket.recv() => {
+                // The client doesn't send anything meaningful; only its
+                // disconnect (None) or an error needs to stop this task.
+                if !matches!(msg, Some(Ok(_))) {
+                    return;
+                }
+            }
+        }
+    }
+}
+
 fn app(crosspoint: Arc<Crosspoint>) -> Router {
     Router::new()
         .route("/", get(index))
         .route("/api/state", get(get_state))
         .route("/api/route", post(post_route))
+        .route("/ws", get(ws_handler))
         .with_state(crosspoint)
 }
 

crates/web/src/lib.rs

@@ -95,8 +95,23 @@ <h1>SRT Router — Crosspoint</h1>
   }
 }
 
-tick();
-setInterval(tick, 1000);
+const RECONNECT_DELAY_MS = 2000;
+
+function connectLive() {
+  const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+  const ws = new WebSocket(`${proto}//${location.host}/ws`);
+  ws.addEventListener('open', () => setStatus(''));
+  ws.addEventListener('message', (ev) => render(JSON.parse(ev.data)));
+  ws.addEventListener('close', () => {
+    setStatus('Disconnected, retrying…');
+    setTimeout(connectLive, RECONNECT_DELAY_MS);
+  });
+  ws.addEventListener('error', () => ws.close());
+}
+
+// First paint over plain REST (fast, works even if the websocket upgrade is
+// ever blocked by something in between), then switch to live push.
+tick().finally(connectLive);
 </script>
 </body>
 </html>

crates/web/static/index.html

@@ -76,9 +76,11 @@ at the cost of actually running a media pipeline for that one path — see
   `spawn_input`/`spawn_output`, each owning one socket and one reconnect
   loop (`listener`: re-`listen_on`; `caller`: re-`call`).
 - `crates/web` (`crosspoint-web`) — an `axum` server: `GET /api/state`,
-  `POST /api/route`, and a single embedded HTML/JS page
-  (`crates/web/static/index.html`) that polls `/api/state` once a second and
-  renders the routing grid. No websocket push yet — see roadmap.
+  `POST /api/route`, `GET /ws` (websocket push — sends the current state on
+  connect and again whenever it changes), and a single embedded HTML/JS
+  page (`crates/web/static/index.html`) that does one REST fetch for first
+  paint, then switches to the websocket for live updates (falling back to a
+  2s reconnect loop if the connection drops).
 - `crates/router` (bin `srtrouter`) — loads a TOML config
   ([config/example.toml](../config/example.toml)), registers every
   configured input/output with a shared `Crosspoint`, and starts the web
@@ -101,5 +103,13 @@ connect = "203.0.113.10:5000"
 ```
 
 Outputs are the same shape plus `default_source` (what they're routed from
-at startup — routing changes made afterward via the web UI/API are
-in-memory only and don't persist across a restart yet, see roadmap).
+at startup if nothing better is known — see below).
+
+Optionally, a top-level `[state]` section with a `path` enables persisting
+routing changes to disk: every time a route changes, the full output ->
+source table is written to that JSON file (write-then-rename, so a crash
+mid-write can't leave a corrupt file behind); on startup, any persisted
+route for a configured output overrides that output's `default_source`.
+Omit `[state]` to keep routing in-memory only, as before — every restart
+then resets to each output's `default_source`. See
+`crates/router/src/state.rs`.