mnml_bridge/
lib.rs

1//! # mnml-bridge — Mount protocol for mnml sibling tools
2//!
3//! Bridge / Mount is the integration layer that lets sibling tools
4//! (`mnml-tattle-tests`, `mnml-db-postgres`, …) render their UI as a
5//! first-class pane inside mnml — owning the activity-bar icon, the
6//! rail content, and the editor body — instead of running as a
7//! plain `Pty` pane.
8//!
9//! ## The four tiers
10//!
11//! 1. **Env vars** — every Pty mnml spawns sees `MNML_WORKSPACE`,
12//!    `MNML_THEME`, and `MNML_IPC_DIR`. Zero protocol; just read on
13//!    startup. (Available today for any sibling.)
14//! 2. **JSONL sibling → host** — sibling writes JSONL commands to
15//!    `$MNML_IPC_DIR/command`; mnml ingests them. `toast`,
16//!    `open-pty`, `open` (file), more coming. One-way.
17//! 3. **mnml-bridge SDK** — this crate. Typed Rust API around tiers
18//!    1 + 2, plus the Mount protocol below.
19//! 4. **Mount** — sibling connects to a Unix-socket-per-mount,
20//!    streams cell+style frames back, receives input events. Owns
21//!    rail + body areas of an activity-bar section.
22//!
23//! ## Wire shape
24//!
25//! Length-prefixed JSON. Every message is a `Frame` or `Input`. The
26//! 4-byte little-endian length precedes the JSON body so framing is
27//! trivial (no streaming JSON parser needed).
28//!
29//! Host → Sibling:
30//!   - `MountHello { cols, rows }` first
31//!   - `Resize { cols, rows }` on terminal resize
32//!   - `Input { event }` on every routed key / mouse event
33//!
34//! Sibling → Host:
35//!   - `Frame { cells: Vec<Vec<Cell>> }` whenever the sibling has a
36//!     new screen state. Cell-perfect; the host stamps these into
37//!     its own ratatui frame.
38//!
39//! V1 keeps it simple: full frames, no diffing. A ~24x80 panel is
40//! ~2 KB of JSON; serialization cost is negligible vs ratatui's
41//! own draw cycle.
42
43use serde::{Deserialize, Serialize};
44
45#[cfg(feature = "client")]
46pub mod client;
47
48#[cfg(feature = "client")]
49pub use client::Mount;
50
51/// A single terminal cell — one grapheme + style. Mirrors
52/// ratatui's `buffer::Cell` shape but with serde derived.
53#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
54pub struct Cell {
55    /// The grapheme cluster painted in this cell. Multi-codepoint
56    /// (e.g. flag emoji) is fine; mnml stamps the whole thing into
57    /// a single buffer cell.
58    pub symbol: String,
59    #[serde(default, skip_serializing_if = "Option::is_none")]
60    pub fg: Option<RgbOrIndex>,
61    #[serde(default, skip_serializing_if = "Option::is_none")]
62    pub bg: Option<RgbOrIndex>,
63    /// Bitfield of [`Modifier`] flags. Stored as u16 for compact wire shape.
64    #[serde(default, skip_serializing_if = "is_zero_u16")]
65    pub modifiers: u16,
66}
67
68fn is_zero_u16(v: &u16) -> bool {
69    *v == 0
70}
71
72/// Either a true-color RGB triple or a 256-color palette index.
73#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
74#[serde(untagged)]
75pub enum RgbOrIndex {
76    /// `[r, g, b]` 24-bit color.
77    Rgb([u8; 3]),
78    /// 0-255 palette index (terminal default semantics: 0-7 ANSI,
79    /// 8-15 bright, 16-231 6×6×6 cube, 232-255 grayscale).
80    Index(u8),
81}
82
83/// Bitflags for [`Cell::modifiers`]. Mirrors ratatui's `Modifier`
84/// constants so a sibling can reuse its existing styling.
85pub mod modifier {
86    pub const BOLD: u16 = 1 << 0;
87    pub const DIM: u16 = 1 << 1;
88    pub const ITALIC: u16 = 1 << 2;
89    pub const UNDERLINED: u16 = 1 << 3;
90    pub const SLOW_BLINK: u16 = 1 << 4;
91    pub const RAPID_BLINK: u16 = 1 << 5;
92    pub const REVERSED: u16 = 1 << 6;
93    pub const HIDDEN: u16 = 1 << 7;
94    pub const CROSSED_OUT: u16 = 1 << 8;
95}
96
97/// Sent by the host once on connection, then on every terminal resize.
98#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
99pub struct Geometry {
100    pub cols: u16,
101    pub rows: u16,
102}
103
104/// Routed input event from the host. Key / mouse events that
105/// happened inside the mount's area are forwarded as-is.
106#[derive(Debug, Clone, Serialize, Deserialize)]
107#[serde(tag = "kind", rename_all = "snake_case")]
108pub enum InputEvent {
109    /// A single keypress (key spec, e.g. `"down"`, `"ctrl+c"`).
110    Key { spec: String },
111    /// Mouse click. `button` is `"left" | "middle" | "right"`.
112    Click { col: u16, row: u16, button: String },
113    /// Mouse wheel. Positive `dy` ⇒ scroll up.
114    Scroll { col: u16, row: u16, dy: i16 },
115    /// Mouse hover (cursor moved over the mount).
116    Hover { col: u16, row: u16 },
117}
118
119/// Host → sibling messages.
120#[derive(Debug, Clone, Serialize, Deserialize)]
121#[serde(tag = "kind", rename_all = "snake_case")]
122pub enum HostMessage {
123    /// First message after connect — tells the sibling the initial
124    /// area size.
125    Hello { geometry: Geometry, theme: String },
126    /// Sent on terminal / pane resize.
127    Resize { geometry: Geometry },
128    /// Forwarded user input.
129    Input { event: InputEvent },
130    /// Host is going away (mnml quitting, mount being unmounted).
131    Goodbye,
132}
133
134/// Sibling → host messages.
135#[derive(Debug, Clone, Serialize, Deserialize)]
136#[serde(tag = "kind", rename_all = "snake_case")]
137pub enum SiblingMessage {
138    /// A full screen of cells. `cells.len()` rows × `cells[i].len()`
139    /// cols — must match the most recent `Hello`/`Resize` geometry.
140    /// Rows shorter than the advertised `cols` are right-padded
141    /// with default cells by the host.
142    Frame { cells: Vec<Vec<Cell>> },
143    /// Sibling is voluntarily exiting (clean shutdown).
144    Bye,
145}
146
147/// Read a length-prefixed JSON message from a stream.
148///
149/// Wire format: `[u8; 4]` little-endian length, then `length` bytes
150/// of UTF-8 JSON. Returns `Ok(None)` on clean EOF, `Err` on truncated
151/// reads or malformed JSON.
152pub fn read_message<R, T>(r: &mut R) -> std::io::Result<Option<T>>
153where
154    R: std::io::Read,
155    T: serde::de::DeserializeOwned,
156{
157    let mut len_buf = [0u8; 4];
158    match r.read_exact(&mut len_buf) {
159        Ok(()) => {}
160        Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => return Ok(None),
161        Err(e) => return Err(e),
162    }
163    let len = u32::from_le_bytes(len_buf) as usize;
164    if len > 16 * 1024 * 1024 {
165        return Err(std::io::Error::new(
166            std::io::ErrorKind::InvalidData,
167            format!("bridge message too large: {len} bytes"),
168        ));
169    }
170    let mut body = vec![0u8; len];
171    r.read_exact(&mut body)?;
172    let parsed: T = serde_json::from_slice(&body).map_err(|e| {
173        std::io::Error::new(
174            std::io::ErrorKind::InvalidData,
175            format!("bridge JSON parse: {e}"),
176        )
177    })?;
178    Ok(Some(parsed))
179}
180
181/// Write a length-prefixed JSON message to a stream.
182pub fn write_message<W, T>(w: &mut W, msg: &T) -> std::io::Result<()>
183where
184    W: std::io::Write,
185    T: Serialize,
186{
187    let body = serde_json::to_vec(msg).map_err(|e| {
188        std::io::Error::new(
189            std::io::ErrorKind::InvalidData,
190            format!("bridge JSON serialize: {e}"),
191        )
192    })?;
193    let len = body.len() as u32;
194    w.write_all(&len.to_le_bytes())?;
195    w.write_all(&body)?;
196    Ok(())
197}
198
199#[cfg(test)]
200mod tests {
201    use super::*;
202
203    #[test]
204    fn frame_roundtrip() {
205        let frame = SiblingMessage::Frame {
206            cells: vec![vec![Cell {
207                symbol: "x".to_string(),
208                fg: Some(RgbOrIndex::Rgb([255, 0, 0])),
209                bg: None,
210                modifiers: modifier::BOLD,
211            }]],
212        };
213        let mut buf = Vec::new();
214        write_message(&mut buf, &frame).unwrap();
215        let mut cursor = std::io::Cursor::new(&buf);
216        let back: SiblingMessage = read_message(&mut cursor).unwrap().unwrap();
217        match back {
218            SiblingMessage::Frame { cells } => {
219                assert_eq!(cells.len(), 1);
220                assert_eq!(cells[0][0].symbol, "x");
221                assert_eq!(cells[0][0].fg, Some(RgbOrIndex::Rgb([255, 0, 0])));
222                assert_eq!(cells[0][0].modifiers, modifier::BOLD);
223            }
224            _ => panic!("wrong variant"),
225        }
226    }
227
228    #[test]
229    fn host_hello_roundtrip() {
230        let hello = HostMessage::Hello {
231            geometry: Geometry { cols: 80, rows: 24 },
232            theme: "cyberdream".to_string(),
233        };
234        let mut buf = Vec::new();
235        write_message(&mut buf, &hello).unwrap();
236        let mut cursor = std::io::Cursor::new(&buf);
237        let back: HostMessage = read_message(&mut cursor).unwrap().unwrap();
238        match back {
239            HostMessage::Hello { geometry, theme } => {
240                assert_eq!(geometry.cols, 80);
241                assert_eq!(geometry.rows, 24);
242                assert_eq!(theme, "cyberdream");
243            }
244            _ => panic!("wrong variant"),
245        }
246    }
247
248    #[test]
249    fn eof_returns_none() {
250        let mut empty = std::io::Cursor::new(Vec::<u8>::new());
251        let res: Option<HostMessage> = read_message(&mut empty).unwrap();
252        assert!(res.is_none());
253    }
254
255    #[test]
256    fn rejects_oversize_length() {
257        // 4-byte length = 100 MB; should be rejected before allocation.
258        let mut buf = (100u32 * 1024 * 1024).to_le_bytes().to_vec();
259        buf.extend_from_slice(b"junk");
260        let mut cursor = std::io::Cursor::new(&buf);
261        let res: std::io::Result<Option<HostMessage>> = read_message(&mut cursor);
262        assert!(res.is_err());
263    }
264}
mnml_bridge/lib.rs

mnml_bridge/
lib.rs
