add all crates: domain, protocol, application, client, adapters, ESP32 firmware

Server: domain (entities, value objects, ports), protocol (postcard wire types),
application (config service, data projection), adapters (config-memory, tcp-server),
bootstrap (composition root with fake data).

Client: client-domain (layout engine, render tree, HAL ports),
client-application (message handling, repaint commands),
adapters (tcp-client, display-terminal), client-desktop (end-to-end working).

ESP32: client-esp32 firmware with ILI9341 display over SPI, WiFi networking.
Display test verified on hardware — landscape orientation, text rendering works.

60 workspace tests, all passing.

crates/protocol/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "protocol"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+domain.workspace = true
+serde.workspace = true
+postcard.workspace = true
+
+[dev-dependencies]

crates/protocol/src/frame.rs

@@ -0,0 +1,54 @@
+use serde::{Serialize, Deserialize};
+use super::wire::{WireLayoutNode, WireWidgetState, WireDisplayHint};
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct WidgetDescriptor {
+    pub id: u16,
+    pub display_hint: WireDisplayHint,
+    pub state: WireWidgetState,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum ServerMessage {
+    ScreenUpdate {
+        layout: WireLayoutNode,
+        widgets: Vec<WidgetDescriptor>,
+    },
+    DataUpdate {
+        widgets: Vec<WidgetDescriptor>,
+    },
+    Heartbeat,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum ClientMessage {
+    Heartbeat,
+}
+
+pub const MAX_FRAME_SIZE: usize = 32 * 1024;
+
+pub fn encode(msg: &ServerMessage) -> Result<Vec<u8>, postcard::Error> {
+    let payload = postcard::to_allocvec(msg)?;
+    let len = (payload.len() as u32).to_be_bytes();
+    let mut frame = Vec::with_capacity(4 + payload.len());
+    frame.extend_from_slice(&len);
+    frame.extend_from_slice(&payload);
+    Ok(frame)
+}
+
+pub fn decode_server_message(payload: &[u8]) -> Result<ServerMessage, postcard::Error> {
+    postcard::from_bytes(payload)
+}
+
+pub fn encode_client(msg: &ClientMessage) -> Result<Vec<u8>, postcard::Error> {
+    let payload = postcard::to_allocvec(msg)?;
+    let len = (payload.len() as u32).to_be_bytes();
+    let mut frame = Vec::with_capacity(4 + payload.len());
+    frame.extend_from_slice(&len);
+    frame.extend_from_slice(&payload);
+    Ok(frame)
+}
+
+pub fn decode_client_message(payload: &[u8]) -> Result<ClientMessage, postcard::Error> {
+    postcard::from_bytes(payload)
+}

crates/protocol/src/lib.rs

@@ -0,0 +1,13 @@
+mod wire;
+mod frame;
+
+pub use wire::{
+    WireValue, WireWidgetState, WireWidgetError, WireDisplayHint,
+    WireLayoutNode, WireContainerNode, WireLayoutChild, WireDirection, WireSizing,
+    WireKeyValue,
+};
+pub use frame::{
+    ServerMessage, ClientMessage, WidgetDescriptor,
+    encode, decode_server_message, encode_client, decode_client_message,
+    MAX_FRAME_SIZE,
+};

crates/protocol/src/wire.rs

@@ -0,0 +1,232 @@
+use std::collections::BTreeMap;
+use serde::{Serialize, Deserialize};
+use domain::value_objects::{
+    ContainerNode, Direction, DisplayHint, LayoutChild, LayoutNode, Sizing, Value,
+    WidgetError, WidgetState,
+};
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum WireValue {
+    Null,
+    Bool(bool),
+    Number(f64),
+    String(String),
+    Array(Vec<WireValue>),
+    Object(BTreeMap<String, WireValue>),
+}
+
+impl From<&Value> for WireValue {
+    fn from(v: &Value) -> Self {
+        match v {
+            Value::Null => WireValue::Null,
+            Value::Bool(b) => WireValue::Bool(*b),
+            Value::Number(n) => WireValue::Number(*n),
+            Value::String(s) => WireValue::String(s.clone()),
+            Value::Array(arr) => WireValue::Array(arr.iter().map(Into::into).collect()),
+            Value::Object(map) => {
+                WireValue::Object(map.iter().map(|(k, v)| (k.clone(), v.into())).collect())
+            }
+        }
+    }
+}
+
+impl From<WireValue> for Value {
+    fn from(w: WireValue) -> Self {
+        match w {
+            WireValue::Null => Value::Null,
+            WireValue::Bool(b) => Value::Bool(b),
+            WireValue::Number(n) => Value::Number(n),
+            WireValue::String(s) => Value::String(s),
+            WireValue::Array(arr) => Value::Array(arr.into_iter().map(Into::into).collect()),
+            WireValue::Object(map) => {
+                Value::Object(map.into_iter().map(|(k, v)| (k, v.into())).collect())
+            }
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum WireWidgetError {
+    SourceUnavailable,
+    ExtractionFailed,
+}
+
+impl From<&WidgetError> for WireWidgetError {
+    fn from(e: &WidgetError) -> Self {
+        match e {
+            WidgetError::SourceUnavailable => WireWidgetError::SourceUnavailable,
+            WidgetError::ExtractionFailed => WireWidgetError::ExtractionFailed,
+        }
+    }
+}
+
+impl From<WireWidgetError> for WidgetError {
+    fn from(w: WireWidgetError) -> Self {
+        match w {
+            WireWidgetError::SourceUnavailable => WidgetError::SourceUnavailable,
+            WireWidgetError::ExtractionFailed => WidgetError::ExtractionFailed,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct WireKeyValue {
+    pub key: String,
+    pub value: WireValue,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct WireWidgetState {
+    pub data: Vec<WireKeyValue>,
+    pub error: Option<WireWidgetError>,
+}
+
+impl From<&WidgetState> for WireWidgetState {
+    fn from(s: &WidgetState) -> Self {
+        WireWidgetState {
+            data: s.data.iter().map(|(k, v)| WireKeyValue {
+                key: k.clone(),
+                value: v.into(),
+            }).collect(),
+            error: s.error.as_ref().map(Into::into),
+        }
+    }
+}
+
+impl From<WireWidgetState> for WidgetState {
+    fn from(w: WireWidgetState) -> Self {
+        WidgetState {
+            data: w.data.into_iter().map(|kv| (kv.key, kv.value.into())).collect(),
+            error: w.error.map(Into::into),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum WireDisplayHint {
+    IconValue,
+    TextBlock,
+    KeyValue,
+}
+
+impl From<&DisplayHint> for WireDisplayHint {
+    fn from(h: &DisplayHint) -> Self {
+        match h {
+            DisplayHint::IconValue => WireDisplayHint::IconValue,
+            DisplayHint::TextBlock => WireDisplayHint::TextBlock,
+            DisplayHint::KeyValue => WireDisplayHint::KeyValue,
+        }
+    }
+}
+
+impl From<WireDisplayHint> for DisplayHint {
+    fn from(w: WireDisplayHint) -> Self {
+        match w {
+            WireDisplayHint::IconValue => DisplayHint::IconValue,
+            WireDisplayHint::TextBlock => DisplayHint::TextBlock,
+            WireDisplayHint::KeyValue => DisplayHint::KeyValue,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum WireSizing {
+    Fixed(u16),
+    Flex(u8),
+}
+
+impl From<&Sizing> for WireSizing {
+    fn from(s: &Sizing) -> Self {
+        match s {
+            Sizing::Fixed(px) => WireSizing::Fixed(*px),
+            Sizing::Flex(w) => WireSizing::Flex(*w),
+        }
+    }
+}
+
+impl From<WireSizing> for Sizing {
+    fn from(w: WireSizing) -> Self {
+        match w {
+            WireSizing::Fixed(px) => Sizing::Fixed(px),
+            WireSizing::Flex(weight) => Sizing::Flex(weight),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum WireDirection {
+    Row,
+    Column,
+}
+
+impl From<&Direction> for WireDirection {
+    fn from(d: &Direction) -> Self {
+        match d {
+            Direction::Row => WireDirection::Row,
+            Direction::Column => WireDirection::Column,
+        }
+    }
+}
+
+impl From<WireDirection> for Direction {
+    fn from(w: WireDirection) -> Self {
+        match w {
+            WireDirection::Row => Direction::Row,
+            WireDirection::Column => Direction::Column,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct WireContainerNode {
+    pub direction: WireDirection,
+    pub gap: u8,
+    pub padding: u8,
+    pub children: Vec<WireLayoutChild>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct WireLayoutChild {
+    pub sizing: WireSizing,
+    pub node: WireLayoutNode,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub enum WireLayoutNode {
+    Container(WireContainerNode),
+    Leaf(u16),
+}
+
+impl From<&LayoutNode> for WireLayoutNode {
+    fn from(n: &LayoutNode) -> Self {
+        match n {
+            LayoutNode::Leaf(id) => WireLayoutNode::Leaf(*id),
+            LayoutNode::Container(c) => WireLayoutNode::Container(WireContainerNode {
+                direction: (&c.direction).into(),
+                gap: c.gap,
+                padding: c.padding,
+                children: c.children.iter().map(|ch| WireLayoutChild {
+                    sizing: (&ch.sizing).into(),
+                    node: (&ch.node).into(),
+                }).collect(),
+            }),
+        }
+    }
+}
+
+impl From<WireLayoutNode> for LayoutNode {
+    fn from(w: WireLayoutNode) -> Self {
+        match w {
+            WireLayoutNode::Leaf(id) => LayoutNode::Leaf(id),
+            WireLayoutNode::Container(c) => LayoutNode::Container(ContainerNode {
+                direction: c.direction.into(),
+                gap: c.gap,
+                padding: c.padding,
+                children: c.children.into_iter().map(|ch| LayoutChild {
+                    sizing: ch.sizing.into(),
+                    node: ch.node.into(),
+                }).collect(),
+            }),
+        }
+    }
+}

crates/protocol/tests/conversion_tests.rs

@@ -0,0 +1,82 @@
+use std::collections::BTreeMap;
+use domain::{
+    Value, WidgetState, WidgetError, DisplayHint,
+    LayoutNode, ContainerNode, LayoutChild, Direction, Sizing,
+};
+use protocol::{
+    WireValue, WireWidgetState, WireWidgetError, WireDisplayHint,
+    WireLayoutNode, WireContainerNode, WireLayoutChild, WireDirection, WireSizing,
+    WireKeyValue,
+};
+
+#[test]
+fn value_converts_to_wire_and_back() {
+    let original = Value::Object(BTreeMap::from([
+        ("items".into(), Value::Array(vec![
+            Value::String("hello".into()),
+            Value::Number(42.0),
+            Value::Bool(true),
+            Value::Null,
+        ])),
+    ]));
+
+    let wire: WireValue = (&original).into();
+    let roundtripped: Value = wire.into();
+    assert_eq!(original, roundtripped);
+}
+
+#[test]
+fn widget_state_with_error_converts_to_wire_and_back() {
+    let original = WidgetState {
+        data: BTreeMap::from([
+            ("temp".into(), Value::Number(5.4)),
+        ]),
+        error: Some(WidgetError::SourceUnavailable),
+    };
+
+    let wire: WireWidgetState = (&original).into();
+    let roundtripped: WidgetState = wire.into();
+    assert_eq!(original, roundtripped);
+}
+
+#[test]
+fn layout_tree_converts_to_wire_and_back() {
+    let original = LayoutNode::Container(ContainerNode {
+        direction: Direction::Row,
+        gap: 4,
+        padding: 2,
+        children: vec![
+            LayoutChild {
+                sizing: Sizing::Flex(1),
+                node: LayoutNode::Leaf(1),
+            },
+            LayoutChild {
+                sizing: Sizing::Fixed(100),
+                node: LayoutNode::Container(ContainerNode {
+                    direction: Direction::Column,
+                    gap: 2,
+                    padding: 0,
+                    children: vec![
+                        LayoutChild {
+                            sizing: Sizing::Flex(1),
+                            node: LayoutNode::Leaf(2),
+                        },
+                    ],
+                }),
+            },
+        ],
+    });
+
+    let wire: WireLayoutNode = (&original).into();
+    let roundtripped: LayoutNode = wire.into();
+    assert_eq!(original, roundtripped);
+}
+
+#[test]
+fn display_hint_converts_to_wire_and_back() {
+    for hint in [DisplayHint::IconValue, DisplayHint::TextBlock, DisplayHint::KeyValue] {
+        let wire: WireDisplayHint = (&hint).into();
+        let roundtripped: DisplayHint = wire.into();
+        assert_eq!(hint, roundtripped);
+    }
+}

crates/protocol/tests/round_trip_tests.rs

@@ -0,0 +1,94 @@
+use protocol::{
+    ServerMessage, ClientMessage, WidgetDescriptor,
+    WireDisplayHint, WireLayoutNode, WireContainerNode, WireLayoutChild,
+    WireDirection, WireSizing, WireWidgetState, WireKeyValue, WireValue,
+    encode, decode_server_message, encode_client, decode_client_message,
+};
+
+#[test]
+fn screen_update_round_trips() {
+    let msg = ServerMessage::ScreenUpdate {
+        layout: WireLayoutNode::Container(WireContainerNode {
+            direction: WireDirection::Row,
+            gap: 4,
+            padding: 2,
+            children: vec![
+                WireLayoutChild {
+                    sizing: WireSizing::Flex(1),
+                    node: WireLayoutNode::Leaf(1),
+                },
+                WireLayoutChild {
+                    sizing: WireSizing::Fixed(80),
+                    node: WireLayoutNode::Leaf(2),
+                },
+            ],
+        }),
+        widgets: vec![
+            WidgetDescriptor {
+                id: 1,
+                display_hint: WireDisplayHint::IconValue,
+                state: WireWidgetState {
+                    data: vec![
+                        WireKeyValue { key: "temperature".into(), value: WireValue::String("5.4°C".into()) },
+                        WireKeyValue { key: "icon".into(), value: WireValue::String("cloud_rain".into()) },
+                    ],
+                    error: None,
+                },
+            },
+        ],
+    };
+
+    let frame = encode(&msg).unwrap();
+    let payload = &frame[4..];
+    let decoded = decode_server_message(payload).unwrap();
+    assert_eq!(msg, decoded);
+}
+
+#[test]
+fn data_update_round_trips() {
+    let msg = ServerMessage::DataUpdate {
+        widgets: vec![
+            WidgetDescriptor {
+                id: 3,
+                display_hint: WireDisplayHint::TextBlock,
+                state: WireWidgetState {
+                    data: vec![
+                        WireKeyValue { key: "body".into(), value: WireValue::String("Breaking news...".into()) },
+                    ],
+                    error: None,
+                },
+            },
+        ],
+    };
+
+    let frame = encode(&msg).unwrap();
+    let payload = &frame[4..];
+    let decoded = decode_server_message(payload).unwrap();
+    assert_eq!(msg, decoded);
+}
+
+#[test]
+fn server_heartbeat_round_trips() {
+    let msg = ServerMessage::Heartbeat;
+    let frame = encode(&msg).unwrap();
+    let payload = &frame[4..];
+    let decoded = decode_server_message(payload).unwrap();
+    assert_eq!(msg, decoded);
+}
+
+#[test]
+fn client_heartbeat_round_trips() {
+    let msg = ClientMessage::Heartbeat;
+    let frame = encode_client(&msg).unwrap();
+    let payload = &frame[4..];
+    let decoded = decode_client_message(payload).unwrap();
+    assert_eq!(msg, decoded);
+}
+
+#[test]
+fn frame_has_correct_length_prefix() {
+    let msg = ServerMessage::Heartbeat;
+    let frame = encode(&msg).unwrap();
+    let len = u32::from_be_bytes([frame[0], frame[1], frame[2], frame[3]]) as usize;
+    assert_eq!(len, frame.len() - 4);
+}