per-source polling, initial client state, webhook, preview, client tracking

- per-source poll intervals: spawn task per source with own interval,
  manager re-checks sources every 30s for add/remove
- initial screen update on TCP connect: send layout + widget states
- client tracking: ClientRegistry port, GET /api/clients, dashboard list
- webhook adapter: POST /api/webhook/{source_id} feeds data into projection
- widget preview: GET /api/widgets/{id}/preview returns current state
- serve SPA from Axum: ServeDir + index.html fallback via KFRAME_SPA_DIR
- layout builder delete confirmation with AlertDialog
- form validation: required fields disable save button
- guide page at /guide
- fix architecture: ClientDto to api-types, ClientRegistry + WidgetStateReader
  ports in domain, DataProjection has internal Mutex, no adapter cross-deps
- ESP32: full screen clear on layout change (stale pixel fix)

crates/adapters/http-api/Cargo.toml

@@ -19,3 +19,4 @@ tower.workspace = true
 serde_json.workspace = true
 config-memory.workspace = true
 tcp-server.workspace = true
+application.workspace = true

crates/adapters/http-api/src/lib.rs

@@ -1,43 +1,72 @@
 mod routes;
 
 use axum::Router;
-use domain::{ConfigRepository, EventPublisher};
+use domain::{BroadcastPort, ClientRegistry, ConfigRepository, EventPublisher, WidgetStateReader};
 use std::sync::Arc;
 use tower_http::cors::CorsLayer;
+use tower_http::services::{ServeDir, ServeFile};
 
-pub struct AppState<C, E> {
+pub struct AppState<C, E, W, B, R> {
     pub config: Arc<C>,
     pub events: Arc<E>,
+    pub widget_states: Arc<W>,
+    pub broadcaster: Arc<B>,
+    pub clients: Arc<R>,
+    pub spa_dir: Option<String>,
 }
 
-impl<C, E> Clone for AppState<C, E> {
+impl<C, E, W, B, R> Clone for AppState<C, E, W, B, R> {
     fn clone(&self) -> Self {
         Self {
             config: self.config.clone(),
             events: self.events.clone(),
+            widget_states: self.widget_states.clone(),
+            broadcaster: self.broadcaster.clone(),
+            clients: self.clients.clone(),
+            spa_dir: self.spa_dir.clone(),
         }
     }
 }
 
-pub fn router<C, E>(state: AppState<C, E>) -> Router
+pub fn router<C, E, W, B, R>(state: AppState<C, E, W, B, R>) -> Router
 where
     C: ConfigRepository + Send + Sync + 'static,
     C::Error: std::fmt::Debug + Send,
     E: EventPublisher + Send + Sync + 'static,
     E::Error: std::fmt::Debug + Send,
+    W: WidgetStateReader + Send + Sync + 'static,
+    B: BroadcastPort + Send + Sync + 'static,
+    B::Error: std::fmt::Debug + Send,
+    R: ClientRegistry + Send + Sync + 'static,
 {
-    Router::new()
+    let spa_dir = state.spa_dir.clone();
+
+    let app = Router::new()
         .nest("/api", routes::api_routes())
         .layer(CorsLayer::permissive())
-        .with_state(state)
+        .with_state(state);
+
+    if let Some(dir) = spa_dir {
+        let index = format!("{dir}/index.html");
+        app.fallback_service(ServeDir::new(&dir).fallback(ServeFile::new(index)))
+    } else {
+        app
+    }
 }
 
-pub async fn serve<C, E>(addr: &str, state: AppState<C, E>) -> Result<(), std::io::Error>
+pub async fn serve<C, E, W, B, R>(
+    addr: &str,
+    state: AppState<C, E, W, B, R>,
+) -> Result<(), std::io::Error>
 where
     C: ConfigRepository + Send + Sync + 'static,
     C::Error: std::fmt::Debug + Send,
     E: EventPublisher + Send + Sync + 'static,
     E::Error: std::fmt::Debug + Send,
+    W: WidgetStateReader + Send + Sync + 'static,
+    B: BroadcastPort + Send + Sync + 'static,
+    B::Error: std::fmt::Debug + Send,
+    R: ClientRegistry + Send + Sync + 'static,
 {
     let app = router(state);
     let listener = tokio::net::TcpListener::bind(addr).await?;

crates/adapters/http-api/src/routes/clients.rs

@@ -0,0 +1,25 @@
+use crate::AppState;
+use api_types::ClientDto;
+use axum::extract::State;
+use axum::response::Json;
+use domain::{ClientRegistry, ConfigRepository, EventPublisher};
+
+type S<C, E, W, B, R> = State<AppState<C, E, W, B, R>>;
+
+pub async fn list_clients<C, E, W, B, R>(State(state): S<C, E, W, B, R>) -> Json<Vec<ClientDto>>
+where
+    C: ConfigRepository,
+    C::Error: std::fmt::Debug,
+    E: EventPublisher,
+    E::Error: std::fmt::Debug,
+    R: ClientRegistry,
+{
+    Json(
+        state
+            .clients
+            .list_clients()
+            .iter()
+            .map(ClientDto::from)
+            .collect(),
+    )
+}

crates/adapters/http-api/src/routes/data_sources.rs

@@ -8,10 +8,10 @@ use axum::{
 };
 use domain::{ConfigRepository, EventPublisher};
 
-type S<C, E> = State<AppState<C, E>>;
+type S<C, E, W, B, R> = State<AppState<C, E, W, B, R>>;
 
-pub async fn list_data_sources<C, E>(
-    State(state): S<C, E>,
+pub async fn list_data_sources<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
 ) -> Result<Json<Vec<DataSourceDto>>, StatusCode>
 where
     C: ConfigRepository,
@@ -27,8 +27,8 @@ where
     Ok(Json(sources.iter().map(DataSourceDto::from).collect()))
 }
 
-pub async fn get_data_source<C, E>(
-    State(state): S<C, E>,
+pub async fn get_data_source<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
     Path(id): Path<u16>,
 ) -> Result<Json<DataSourceDto>, StatusCode>
 where
@@ -48,8 +48,8 @@ where
     }
 }
 
-pub async fn create_data_source<C, E>(
-    State(state): S<C, E>,
+pub async fn create_data_source<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
     Json(body): Json<DataSourceDto>,
 ) -> Result<StatusCode, (StatusCode, String)>
 where
@@ -68,8 +68,8 @@ where
     Ok(StatusCode::CREATED)
 }
 
-pub async fn update_data_source<C, E>(
-    State(state): S<C, E>,
+pub async fn update_data_source<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
     Path(_id): Path<u16>,
     Json(body): Json<DataSourceDto>,
 ) -> Result<StatusCode, (StatusCode, String)>
@@ -89,8 +89,8 @@ where
     Ok(StatusCode::OK)
 }
 
-pub async fn delete_data_source<C, E>(
-    State(state): S<C, E>,
+pub async fn delete_data_source<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
     Path(id): Path<u16>,
 ) -> Result<StatusCode, StatusCode>
 where

crates/adapters/http-api/src/routes/layout.rs

@@ -4,9 +4,11 @@ use application::ConfigService;
 use axum::{extract::State, http::StatusCode, response::Json};
 use domain::{ConfigRepository, EventPublisher};
 
-type S<C, E> = State<AppState<C, E>>;
+type S<C, E, W, B, R> = State<AppState<C, E, W, B, R>>;
 
-pub async fn get_layout<C, E>(State(state): S<C, E>) -> Result<Json<Option<LayoutDto>>, StatusCode>
+pub async fn get_layout<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
+) -> Result<Json<Option<LayoutDto>>, StatusCode>
 where
     C: ConfigRepository,
     C::Error: std::fmt::Debug,
@@ -21,8 +23,8 @@ where
     Ok(Json(layout.as_ref().map(LayoutDto::from)))
 }
 
-pub async fn update_layout<C, E>(
-    State(state): S<C, E>,
+pub async fn update_layout<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
     Json(body): Json<LayoutDto>,
 ) -> Result<StatusCode, (StatusCode, String)>
 where

crates/adapters/http-api/src/routes/mod.rs

@@ -1,53 +1,74 @@
+mod clients;
 mod data_sources;
 mod layout;
 mod presets;
+mod webhook;
 mod widgets;
 
 use crate::AppState;
 use axum::Router;
 use axum::routing::{get, post};
-use domain::{ConfigRepository, EventPublisher};
+use domain::{BroadcastPort, ClientRegistry, ConfigRepository, EventPublisher, WidgetStateReader};
 
-pub fn api_routes<C, E>() -> Router<AppState<C, E>>
+pub fn api_routes<C, E, W, B, R>() -> Router<AppState<C, E, W, B, R>>
 where
     C: ConfigRepository + Send + Sync + 'static,
     C::Error: std::fmt::Debug + Send,
     E: EventPublisher + Send + Sync + 'static,
     E::Error: std::fmt::Debug + Send,
+    W: WidgetStateReader + Send + Sync + 'static,
+    B: BroadcastPort + Send + Sync + 'static,
+    B::Error: std::fmt::Debug + Send,
+    R: ClientRegistry + Send + Sync + 'static,
 {
     Router::new()
         .route(
             "/widgets",
-            get(widgets::list_widgets::<C, E>).post(widgets::create_widget::<C, E>),
+            get(widgets::list_widgets::<C, E, W, B, R>)
+                .post(widgets::create_widget::<C, E, W, B, R>),
         )
         .route(
             "/widgets/{id}",
-            get(widgets::get_widget::<C, E>)
-                .put(widgets::update_widget::<C, E>)
-                .delete(widgets::delete_widget::<C, E>),
+            get(widgets::get_widget::<C, E, W, B, R>)
+                .put(widgets::update_widget::<C, E, W, B, R>)
+                .delete(widgets::delete_widget::<C, E, W, B, R>),
+        )
+        .route(
+            "/widgets/{id}/preview",
+            get(widgets::preview_widget::<C, E, W, B, R>),
         )
         .route(
             "/data-sources",
-            get(data_sources::list_data_sources::<C, E>)
-                .post(data_sources::create_data_source::<C, E>),
+            get(data_sources::list_data_sources::<C, E, W, B, R>)
+                .post(data_sources::create_data_source::<C, E, W, B, R>),
         )
         .route(
             "/data-sources/{id}",
-            get(data_sources::get_data_source::<C, E>)
-                .put(data_sources::update_data_source::<C, E>)
-                .delete(data_sources::delete_data_source::<C, E>),
+            get(data_sources::get_data_source::<C, E, W, B, R>)
+                .put(data_sources::update_data_source::<C, E, W, B, R>)
+                .delete(data_sources::delete_data_source::<C, E, W, B, R>),
         )
         .route(
             "/layout",
-            get(layout::get_layout::<C, E>).put(layout::update_layout::<C, E>),
+            get(layout::get_layout::<C, E, W, B, R>).put(layout::update_layout::<C, E, W, B, R>),
         )
         .route(
             "/presets",
-            get(presets::list_presets::<C, E>).post(presets::create_preset::<C, E>),
+            get(presets::list_presets::<C, E, W, B, R>)
+                .post(presets::create_preset::<C, E, W, B, R>),
         )
         .route(
             "/presets/{id}",
-            get(presets::get_preset::<C, E>).delete(presets::delete_preset::<C, E>),
+            get(presets::get_preset::<C, E, W, B, R>)
+                .delete(presets::delete_preset::<C, E, W, B, R>),
+        )
+        .route(
+            "/presets/{id}/load",
+            post(presets::load_preset::<C, E, W, B, R>),
+        )
+        .route("/clients", get(clients::list_clients::<C, E, W, B, R>))
+        .route(
+            "/webhook/{source_id}",
+            post(webhook::receive_webhook::<C, E, W, B, R>),
         )
-        .route("/presets/{id}/load", post(presets::load_preset::<C, E>))
 }

crates/adapters/http-api/src/routes/presets.rs

@@ -8,9 +8,11 @@ use axum::{
 };
 use domain::{ConfigRepository, EventPublisher};
 
-type S<C, E> = State<AppState<C, E>>;
+type S<C, E, W, B, R> = State<AppState<C, E, W, B, R>>;
 
-pub async fn list_presets<C, E>(State(state): S<C, E>) -> Result<Json<Vec<PresetDto>>, StatusCode>
+pub async fn list_presets<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
+) -> Result<Json<Vec<PresetDto>>, StatusCode>
 where
     C: ConfigRepository,
     C::Error: std::fmt::Debug,
@@ -25,8 +27,8 @@ where
     Ok(Json(presets.iter().map(PresetDto::from).collect()))
 }
 
-pub async fn get_preset<C, E>(
-    State(state): S<C, E>,
+pub async fn get_preset<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
     Path(id): Path<u16>,
 ) -> Result<Json<PresetDto>, StatusCode>
 where
@@ -46,8 +48,8 @@ where
     }
 }
 
-pub async fn create_preset<C, E>(
-    State(state): S<C, E>,
+pub async fn create_preset<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
     Json(body): Json<CreatePresetDto>,
 ) -> Result<StatusCode, (StatusCode, String)>
 where
@@ -66,8 +68,8 @@ where
     Ok(StatusCode::CREATED)
 }
 
-pub async fn delete_preset<C, E>(
-    State(state): S<C, E>,
+pub async fn delete_preset<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
     Path(id): Path<u16>,
 ) -> Result<StatusCode, StatusCode>
 where
@@ -83,8 +85,8 @@ where
     Ok(StatusCode::NO_CONTENT)
 }
 
-pub async fn load_preset<C, E>(
-    State(state): S<C, E>,
+pub async fn load_preset<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
     Path(id): Path<u16>,
 ) -> Result<StatusCode, (StatusCode, String)>
 where

crates/adapters/http-api/src/routes/webhook.rs

@@ -0,0 +1,81 @@
+use crate::AppState;
+use axum::extract::{Path, State};
+use axum::http::StatusCode;
+use axum::response::Json;
+use domain::{BroadcastPort, ConfigRepository, EventPublisher, WidgetStateReader};
+
+type S<C, E, W, B, R> = State<AppState<C, E, W, B, R>>;
+
+pub async fn receive_webhook<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
+    Path(source_id): Path<u16>,
+    Json(body): Json<serde_json::Value>,
+) -> Result<StatusCode, (StatusCode, String)>
+where
+    C: ConfigRepository,
+    C::Error: std::fmt::Debug,
+    E: EventPublisher,
+    E::Error: std::fmt::Debug,
+    W: WidgetStateReader,
+    B: BroadcastPort,
+    B::Error: std::fmt::Debug,
+{
+    let source = state
+        .config
+        .get_data_source(source_id)
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, format!("{e:?}")))?
+        .ok_or((StatusCode::NOT_FOUND, "data source not found".into()))?;
+
+    if source.source_type != domain::DataSourceType::Webhook {
+        return Err((
+            StatusCode::BAD_REQUEST,
+            "data source is not a webhook type".into(),
+        ));
+    }
+
+    let raw = json_to_domain_value(body);
+    let widgets = state
+        .config
+        .list_widgets()
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, format!("{e:?}")))?;
+
+    let layout = state
+        .config
+        .get_layout()
+        .await
+        .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, format!("{e:?}")))?;
+
+    let changed = state
+        .widget_states
+        .apply_raw_data(source_id, &raw, &widgets)
+        .await;
+
+    if !changed.is_empty()
+        && let Some(l) = &layout
+    {
+        let _ = state.broadcaster.push_screen_update(l, &changed).await;
+    }
+
+    Ok(StatusCode::OK)
+}
+
+fn json_to_domain_value(json: serde_json::Value) -> domain::Value {
+    match json {
+        serde_json::Value::Null => domain::Value::Null,
+        serde_json::Value::Bool(b) => domain::Value::Bool(b),
+        serde_json::Value::Number(n) => domain::Value::Number(n.as_f64().unwrap_or(0.0)),
+        serde_json::Value::String(s) => domain::Value::String(s),
+        serde_json::Value::Array(arr) => {
+            domain::Value::Array(arr.into_iter().map(json_to_domain_value).collect())
+        }
+        serde_json::Value::Object(obj) => {
+            let map = obj
+                .into_iter()
+                .map(|(k, v)| (k, json_to_domain_value(v)))
+                .collect();
+            domain::Value::Object(map)
+        }
+    }
+}

crates/adapters/http-api/src/routes/widgets.rs

@@ -6,11 +6,13 @@ use axum::{
     http::StatusCode,
     response::Json,
 };
-use domain::{ConfigRepository, EventPublisher};
+use domain::{ConfigRepository, EventPublisher, WidgetStateReader};
 
-type S<C, E> = State<AppState<C, E>>;
+type S<C, E, W, B, R> = State<AppState<C, E, W, B, R>>;
 
-pub async fn list_widgets<C, E>(State(state): S<C, E>) -> Result<Json<Vec<WidgetDto>>, StatusCode>
+pub async fn list_widgets<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
+) -> Result<Json<Vec<WidgetDto>>, StatusCode>
 where
     C: ConfigRepository,
     C::Error: std::fmt::Debug,
@@ -25,8 +27,8 @@ where
     Ok(Json(widgets.iter().map(WidgetDto::from).collect()))
 }
 
-pub async fn get_widget<C, E>(
-    State(state): S<C, E>,
+pub async fn get_widget<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
     Path(id): Path<u16>,
 ) -> Result<Json<WidgetDto>, StatusCode>
 where
@@ -46,8 +48,8 @@ where
     }
 }
 
-pub async fn create_widget<C, E>(
-    State(state): S<C, E>,
+pub async fn create_widget<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
     Json(body): Json<CreateWidgetDto>,
 ) -> Result<StatusCode, (StatusCode, String)>
 where
@@ -66,8 +68,8 @@ where
     Ok(StatusCode::CREATED)
 }
 
-pub async fn update_widget<C, E>(
-    State(state): S<C, E>,
+pub async fn update_widget<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
     Path(_id): Path<u16>,
     Json(body): Json<CreateWidgetDto>,
 ) -> Result<StatusCode, (StatusCode, String)>
@@ -87,8 +89,8 @@ where
     Ok(StatusCode::OK)
 }
 
-pub async fn delete_widget<C, E>(
-    State(state): S<C, E>,
+pub async fn delete_widget<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
     Path(id): Path<u16>,
 ) -> Result<StatusCode, StatusCode>
 where
@@ -103,3 +105,46 @@ where
         .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;
     Ok(StatusCode::NO_CONTENT)
 }
+
+pub async fn preview_widget<C, E, W, B, R>(
+    State(state): S<C, E, W, B, R>,
+    Path(id): Path<u16>,
+) -> Result<Json<serde_json::Value>, StatusCode>
+where
+    C: ConfigRepository,
+    C::Error: std::fmt::Debug,
+    E: EventPublisher,
+    E::Error: std::fmt::Debug,
+    W: WidgetStateReader,
+{
+    match state.widget_states.get_widget_state(id).await {
+        Some(ws) => {
+            let map: serde_json::Map<String, serde_json::Value> = ws
+                .data
+                .iter()
+                .map(|(k, v)| (k.clone(), domain_value_to_json(v)))
+                .collect();
+            Ok(Json(serde_json::Value::Object(map)))
+        }
+        None => Err(StatusCode::NOT_FOUND),
+    }
+}
+
+fn domain_value_to_json(v: &domain::Value) -> serde_json::Value {
+    match v {
+        domain::Value::Null => serde_json::Value::Null,
+        domain::Value::Bool(b) => serde_json::Value::Bool(*b),
+        domain::Value::Number(n) => serde_json::json!(n),
+        domain::Value::String(s) => serde_json::Value::String(s.clone()),
+        domain::Value::Array(arr) => {
+            serde_json::Value::Array(arr.iter().map(domain_value_to_json).collect())
+        }
+        domain::Value::Object(obj) => {
+            let map = obj
+                .iter()
+                .map(|(k, v)| (k.clone(), domain_value_to_json(v)))
+                .collect();
+            serde_json::Value::Object(map)
+        }
+    }
+}

crates/adapters/http-api/tests/api_tests.rs

@@ -1,15 +1,21 @@
+use application::DataProjection;
 use axum::body::Body;
 use axum::http::{Request, StatusCode};
 use config_memory::MemoryConfigStore;
 use http_api::{AppState, router};
 use std::sync::Arc;
-use tcp_server::TcpEventBus;
+use tcp_server::{ClientTracker, TcpBroadcaster, TcpEventBus};
 use tower::ServiceExt;
 
 fn test_app() -> axum::Router {
-    let config = Arc::new(MemoryConfigStore::new());
-    let events = Arc::new(TcpEventBus::new(16));
-    let state = AppState { config, events };
+    let state = AppState {
+        config: Arc::new(MemoryConfigStore::new()),
+        events: Arc::new(TcpEventBus::new(16)),
+        widget_states: Arc::new(DataProjection::new()),
+        broadcaster: Arc::new(TcpBroadcaster::new(16)),
+        clients: Arc::new(ClientTracker::new()),
+        spa_dir: None,
+    };
     router(state)
 }
 

crates/adapters/tcp-server/src/client_tracker.rs

@@ -0,0 +1,48 @@
+use domain::{ClientRegistry, ConnectedClient};
+use std::net::SocketAddr;
+use std::sync::Mutex;
+use std::time::SystemTime;
+
+#[derive(Default)]
+pub struct ClientTracker {
+    clients: Mutex<Vec<ConnectedClient>>,
+}
+
+impl ClientTracker {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn add(&self, addr: SocketAddr) {
+        let info = ConnectedClient {
+            addr: addr.to_string(),
+            connected_at: SystemTime::now()
+                .duration_since(SystemTime::UNIX_EPOCH)
+                .unwrap_or_default()
+                .as_secs(),
+        };
+        self.clients.lock().unwrap().push(info);
+    }
+
+    pub fn remove(&self, addr: SocketAddr) {
+        let addr_str = addr.to_string();
+        self.clients.lock().unwrap().retain(|c| c.addr != addr_str);
+    }
+}
+
+impl ClientRegistry for ClientTracker {
+    fn add_client(&self, addr: &str, connected_at: u64) {
+        self.clients.lock().unwrap().push(ConnectedClient {
+            addr: addr.to_string(),
+            connected_at,
+        });
+    }
+
+    fn remove_client(&self, addr: &str) {
+        self.clients.lock().unwrap().retain(|c| c.addr != addr);
+    }
+
+    fn list_clients(&self) -> Vec<ConnectedClient> {
+        self.clients.lock().unwrap().clone()
+    }
+}

crates/adapters/tcp-server/src/lib.rs

@@ -1,9 +1,11 @@
 mod broadcaster;
+mod client_tracker;
 mod error;
 mod event_bus;
 mod server;
 
 pub use broadcaster::TcpBroadcaster;
+pub use client_tracker::ClientTracker;
 pub use error::TcpServerError;
 pub use event_bus::TcpEventBus;
 pub use server::run_tcp_server;

crates/adapters/tcp-server/src/server.rs

@@ -1,15 +1,27 @@
-use crate::broadcaster::TcpBroadcaster;
+use crate::client_tracker::ClientTracker;
 use crate::error::TcpServerError;
+use domain::{ConfigRepository, WidgetStateReader};
+use protocol::{ServerMessage, WidgetDescriptor, WireDisplayHint, WireLayoutNode, encode};
 use std::sync::Arc;
 use tokio::io::AsyncWriteExt;
 use tokio::net::TcpListener;
 use tokio::sync::broadcast;
-use tracing::{info, warn};
+use tracing::{error, info, warn};
 
-pub async fn run_tcp_server(
+use crate::broadcaster::TcpBroadcaster;
+
+pub async fn run_tcp_server<C, W>(
     addr: &str,
     broadcaster: Arc<TcpBroadcaster>,
-) -> Result<(), TcpServerError> {
+    tracker: Arc<ClientTracker>,
+    config: Arc<C>,
+    widget_states: Arc<W>,
+) -> Result<(), TcpServerError>
+where
+    C: ConfigRepository + Send + Sync + 'static,
+    C::Error: std::fmt::Debug + Send,
+    W: WidgetStateReader + Send + Sync + 'static,
+{
     let listener = TcpListener::bind(addr).await.map_err(TcpServerError::Io)?;
     info!(addr, "TCP server listening");
 
@@ -17,9 +29,21 @@ pub async fn run_tcp_server(
         let (mut socket, peer) = listener.accept().await.map_err(TcpServerError::Io)?;
         info!(%peer, "client connected");
 
+        tracker.add(peer);
+        let tracker = tracker.clone();
         let mut rx = broadcaster.subscribe();
 
+        let initial_frame = build_initial_frame(&*config, &*widget_states).await;
+
         tokio::spawn(async move {
+            if let Some(frame) = initial_frame
+                && socket.write_all(&frame).await.is_err()
+            {
+                info!(%peer, "client disconnected during initial send");
+                tracker.remove(peer);
+                return;
+            }
+
             loop {
                 match rx.recv().await {
                     Ok(frame) => {
@@ -34,6 +58,56 @@ pub async fn run_tcp_server(
                     }
                 }
             }
+            tracker.remove(peer);
         });
     }
 }
+
+async fn build_initial_frame<C, W>(config: &C, widget_states: &W) -> Option<Vec<u8>>
+where
+    C: ConfigRepository,
+    C::Error: std::fmt::Debug,
+    W: WidgetStateReader,
+{
+    let layout = match config.get_layout().await {
+        Ok(Some(l)) => l,
+        Ok(None) => return None,
+        Err(e) => {
+            error!(error = ?e, "failed to fetch layout for initial send");
+            return None;
+        }
+    };
+
+    let widgets = match config.list_widgets().await {
+        Ok(w) => w,
+        Err(e) => {
+            error!(error = ?e, "failed to fetch widgets for initial send");
+            return None;
+        }
+    };
+
+    let wire_layout: WireLayoutNode = (&layout.root).into();
+    let mut wire_widgets = Vec::new();
+    for w in &widgets {
+        if let Some(s) = widget_states.get_widget_state(w.id).await {
+            wire_widgets.push(WidgetDescriptor {
+                id: w.id,
+                display_hint: WireDisplayHint::IconValue,
+                state: (&s).into(),
+            });
+        }
+    }
+
+    let msg = ServerMessage::ScreenUpdate {
+        layout: wire_layout,
+        widgets: wire_widgets,
+    };
+
+    match encode(&msg) {
+        Ok(frame) => Some(frame),
+        Err(e) => {
+            error!(error = %e, "failed to encode initial screen update");
+            None
+        }
+    }
+}