Desktop app: egui/wgpu viewport, model tree, commands and control channel (#9)

* render: display data from the FE model, orbit camera and CPU rasterizer

modelcraft-render (L1, no GPU): DisplayMesh (the unshared faces of solid
elements, shells, element edges, line elements, nodes), the orbit camera
and a CPU rasterizer with PNG output for headless snapshots, adapted from
SolidCraft's render crate. Workspace: egui/eframe/egui-wgpu 0.36 and
SolidCraft's patched egui-wgpu from the pinned rev.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* engine: sample model script (a hex8 block and a tet4 cube)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* Desktop app: egui/wgpu viewport, model tree, commands, status bar, control channel

modelcraft-ui-egui (L5): ModelApp over the engine Session; GPU viewport
(lit faces, element edges, nodes) with a CPU fallback; orbit/pan/zoom,
standard views and fit; model tree; commands panel generated from the
registry with a JSON parameter form; status bar; control request
handling (engine.*, ui.*, ui.screenshot, ui.render). apps/modelcraft:
eframe window, --sample, --control PORT loopback JSON-lines server.
Adapted from SolidCraft's ui-egui and app.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* THIRD-PARTY-LICENSES: the desktop app's dependencies

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* docs: control protocol, desktop app in architecture, roadmap and attribution

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* render: simplify the display mesh (sorted face keys over maps, no unused fields)

Interior faces are found by sorting fixed-size face keys instead of a BTreeMap of Vecs, edges
are deduplicated by sort, and each element's corners are looked up once. Drops the unused
`element` fields on DisplayTri/DisplayLine, the unused Mat4::IDENTITY and corner_count, and
hoists the line colour out of the raster loop.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* viewport: split GPU geometry into batches within the buffer limit; refuse oversized CPU renders

A mesh with a few million boundary triangles made one vertex buffer larger than the device's
max_buffer_size (256 MiB under the limits eframe requests), and wgpu's default error handler
panicked. Geometry is now uploaded in batches of whole primitives, each at most 128 MiB and the
device limit, and all are drawn. A device error handler logs errors and shows them in the status
bar instead of panicking.

The CPU renderer refuses sizes over 8192 per side or 16 MP, and scenes over 20 million
primitives, with an error, and allocates its buffers fallibly. ui.render reports a size out of
range instead of clamping it; the CPU viewport fits a large window into the limit.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

---------

Co-authored-by: jyviko <[email protected]>
Co-authored-by: Claude Opus 5.5 <[email protected]>

apps/modelcraft/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "modelcraft"
+description = "ModelCraft desktop app"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish = false
+
+[lints]
+workspace = true
+
+[dependencies]
+modelcraft-engine = { workspace = true }
+modelcraft-ui-egui = { workspace = true }
+eframe = { workspace = true, features = ["default_fonts", "wgpu", "accesskit", "wayland", "x11"] }
+egui = { workspace = true }
+serde_json = { workspace = true }
+log = { workspace = true }

apps/modelcraft/src/control_server.rs

@@ -0,0 +1,161 @@
+//! Loopback JSON-lines control server: one request per line, one reply per line. Agents and
+//! tests drive the app through it; the UI thread answers each request between frames
+//! (`modelcraft_ui_egui::control`).
+//!
+//! Adapted from SolidCraft's `apps/solidcraft/src/control_server.rs` (MIT OR Apache-2.0), see
+//! ATTRIBUTION.md.
+
+use std::io::{BufRead, BufReader, Write};
+use std::net::{TcpListener, TcpStream};
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::mpsc::{Receiver, Sender, channel};
+use std::time::Duration;
+
+use modelcraft_ui_egui::ControlRequest;
+use serde_json::{Value, json};
+
+/// Longest request line (bytes).
+const MAX_LINE: usize = 16 * 1024 * 1024;
+/// Connections served at once. The channel has no authentication beyond being bound to
+/// loopback, so a flood must not be able to spawn threads without end.
+const MAX_CONNECTIONS: usize = 16;
+/// Lines that are not JSON before the connection is closed, so garbage cannot loop forever.
+const MAX_BAD_LINES: usize = 8;
+/// How long a request waits for the UI thread.
+const REPLY_TIMEOUT: Duration = Duration::from_secs(60);
+
+static OPEN: AtomicUsize = AtomicUsize::new(0);
+
+pub fn start(port: u16, ctx: egui::Context) -> Receiver<ControlRequest> {
+    let (tx, rx) = channel::<ControlRequest>();
+    let listener = match TcpListener::bind(("127.0.0.1", port)) {
+        Ok(l) => l,
+        Err(e) => {
+            eprintln!("modelcraft: control server failed to bind 127.0.0.1:{port}: {e}");
+            return rx;
+        }
+    };
+    eprintln!("modelcraft: control server listening on 127.0.0.1:{port}");
+    std::thread::spawn(move || {
+        for stream in listener.incoming().flatten() {
+            if OPEN.fetch_add(1, Ordering::Relaxed) >= MAX_CONNECTIONS {
+                OPEN.fetch_sub(1, Ordering::Relaxed);
+                let mut refused = stream;
+                let _ = writeln!(refused, "{}", json!({"ok": false, "error": "too many connections"}));
+                continue;
+            }
+            let tx = tx.clone();
+            let ctx = ctx.clone();
+            std::thread::spawn(move || {
+                serve(stream, tx, ctx);
+                OPEN.fetch_sub(1, Ordering::Relaxed);
+            });
+        }
+    });
+    rx
+}
+
+/// One line without its newline, or `None` at the end of the stream. A client that sends
+/// gigabytes with no newline would otherwise make this thread allocate until the process is
+/// killed, so the line is refused as soon as it passes `max`.
+fn read_line(r: &mut impl BufRead, max: usize) -> std::io::Result<Option<Vec<u8>>> {
+    let mut line = Vec::new();
+    loop {
+        let (done, used) = {
+            let available = r.fill_buf()?;
+            if available.is_empty() {
+                return Ok((!line.is_empty()).then_some(line));
+            }
+            match available.iter().position(|b| *b == b'\n') {
+                Some(i) => {
+                    line.extend_from_slice(available.get(..i).unwrap_or(&[]));
+                    (true, i + 1)
+                }
+                None => {
+                    line.extend_from_slice(available);
+                    (false, available.len())
+                }
+            }
+        };
+        r.consume(used);
+        if line.len() > max {
+            return Err(std::io::Error::new(std::io::ErrorKind::InvalidData, "request too large"));
+        }
+        if done {
+            return Ok(Some(line));
+        }
+    }
+}
+
+fn serve(stream: TcpStream, tx: Sender<ControlRequest>, ctx: egui::Context) {
+    let Ok(read) = stream.try_clone() else { return };
+    let mut out = stream;
+    let mut reader = BufReader::new(read);
+    let mut bad = 0usize;
+    loop {
+        let line = match read_line(&mut reader, MAX_LINE) {
+            Ok(Some(l)) => String::from_utf8_lossy(&l).into_owned(),
+            Ok(None) => break,
+            Err(e) => {
+                let _ = writeln!(out, "{}", json!({"ok": false, "error": e.to_string()}));
+                break;
+            }
+        };
+        if line.trim().is_empty() {
+            continue;
+        }
+        let reply = match serde_json::from_str::<Value>(&line) {
+            Ok(msg) => {
+                let id = msg.get("id").cloned().unwrap_or(Value::Null);
+                let method = msg.get("method").and_then(Value::as_str).unwrap_or("").to_string();
+                let params = msg.get("params").cloned().unwrap_or(json!({}));
+                let (req, rrx) = ControlRequest::new(method, params);
+                if tx.send(req).is_err() {
+                    break;
+                }
+                ctx.request_repaint();
+                let mut r = rrx.recv_timeout(REPLY_TIMEOUT).unwrap_or_else(|_| json!({"ok": false, "error": "timeout"}));
+                if let Some(o) = r.as_object_mut() {
+                    o.insert("id".into(), id);
+                }
+                r
+            }
+            Err(e) => {
+                bad += 1;
+                json!({"ok": false, "error": format!("bad JSON: {e}")})
+            }
+        };
+        if writeln!(out, "{reply}").is_err() || bad >= MAX_BAD_LINES {
+            break;
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// A request longer than the cap is refused instead of allocated.
+    #[test]
+    fn lines_past_the_cap_are_refused() {
+        let flood = vec![b'A'; MAX_LINE + 2];
+        let mut r = BufReader::new(flood.as_slice());
+        let e = read_line(&mut r, MAX_LINE).unwrap_err();
+        assert_eq!(e.kind(), std::io::ErrorKind::InvalidData);
+    }
+
+    /// Lines split on newlines, blank lines kept, no trailing newline needed; a line spanning
+    /// several reads arrives whole.
+    #[test]
+    fn lines_split_on_newlines() {
+        let text = b"{\"a\":1}\n\n{\"b\":2}\nlast".to_vec();
+        let mut r = BufReader::with_capacity(3, text.as_slice());
+        let mut got = Vec::new();
+        while let Some(line) = read_line(&mut r, MAX_LINE).unwrap() {
+            got.push(String::from_utf8(line).unwrap());
+        }
+        assert_eq!(got, vec!["{\"a\":1}", "", "{\"b\":2}", "last"]);
+        let mut r = BufReader::with_capacity(4, b"0123456789\n".as_slice());
+        assert!(read_line(&mut r, 5).is_err());
+    }
+}

apps/modelcraft/src/main.rs

@@ -0,0 +1,125 @@
+//! ModelCraft desktop app.
+//!
+//! Usage: `modelcraft [--sample] [--control PORT]`
+//!
+//! `--sample` opens a sample model (`modelcraft_engine::sample`). `--control PORT` (or
+//! `MODELCRAFT_CONTROL_PORT`) starts a localhost JSON-lines control server:
+//! `{"id":1,"method":"engine.execute","params":{"command":"model.info","params":{}}}`. See
+//! `modelcraft_ui_egui::control` and docs/control-protocol.md.
+#![cfg_attr(all(target_os = "windows", not(debug_assertions)), windows_subsystem = "windows")]
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
+#![forbid(unsafe_code)]
+
+mod control_server;
+
+use modelcraft_engine::Session;
+use modelcraft_ui_egui::ModelApp;
+
+const USAGE: &str = "usage: modelcraft [--sample] [--control PORT]";
+const DEPTH_BITS: u8 = 24;
+const MSAA: u16 = 4;
+
+struct App {
+    app: ModelApp,
+}
+
+impl eframe::App for App {
+    fn logic(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) {
+        self.app.logic(ctx);
+    }
+    fn raw_input_hook(&mut self, _ctx: &egui::Context, raw: &mut egui::RawInput) {
+        self.app.raw_input_hook(raw);
+    }
+    fn ui(&mut self, ui: &mut egui::Ui, _frame: &mut eframe::Frame) {
+        self.app.ui(ui);
+    }
+}
+
+/// Command-line options.
+#[derive(Debug, Default, PartialEq)]
+struct Args {
+    sample: bool,
+    control: Option<u16>,
+}
+
+fn parse_args(args: impl IntoIterator<Item = String>, env_port: Option<String>) -> Result<Option<Args>, String> {
+    let mut out = Args { control: env_port.and_then(|p| p.trim().parse().ok()), ..Default::default() };
+    let mut args = args.into_iter();
+    while let Some(a) = args.next() {
+        match a.as_str() {
+            "--sample" => out.sample = true,
+            "--control" => {
+                let port = args.next().ok_or("--control needs a port")?;
+                out.control = Some(port.parse().map_err(|_| format!("--control: `{port}` is not a port number"))?);
+            }
+            "--version" | "-V" => {
+                println!("modelcraft {}", modelcraft_ui_egui::VERSION);
+                return Ok(None);
+            }
+            "--help" | "-h" => {
+                println!("{USAGE}");
+                return Ok(None);
+            }
+            other => return Err(format!("unknown argument `{other}`\n{USAGE}")),
+        }
+    }
+    Ok(Some(out))
+}
+
+fn main() -> eframe::Result {
+    let args = match parse_args(std::env::args().skip(1), std::env::var("MODELCRAFT_CONTROL_PORT").ok()) {
+        Ok(Some(a)) => a,
+        Ok(None) => return Ok(()),
+        Err(e) => {
+            eprintln!("modelcraft: {e}");
+            std::process::exit(2);
+        }
+    };
+    let options = eframe::NativeOptions {
+        viewport: egui::ViewportBuilder::default().with_title("ModelCraft").with_inner_size([1400.0, 900.0]).with_min_inner_size([800.0, 500.0]),
+        depth_buffer: DEPTH_BITS,
+        multisampling: MSAA,
+        ..Default::default()
+    };
+    eframe::run_native(
+        "ModelCraft",
+        options,
+        Box::new(move |cc| {
+            let mut app = ModelApp::new(Session::default());
+            if let Some(rs) = &cc.wgpu_render_state {
+                let info = rs.adapter.get_info();
+                eprintln!("modelcraft: graphics {:?} {}, MSAA {}x (requested {MSAA}x)", info.backend, info.name, rs.msaa_samples);
+                app.set_wgpu(rs, DEPTH_BITS, rs.msaa_samples, &cc.egui_ctx);
+            }
+            if let Some(port) = args.control {
+                app = app.with_control(control_server::start(port, cc.egui_ctx.clone()));
+            }
+            if args.sample {
+                // The status bar reports a failure; the app still opens.
+                let _ = app.run_script(&modelcraft_engine::sample::script());
+            }
+            Ok(Box::new(App { app }))
+        }),
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn parse(a: &[&str], env: Option<&str>) -> Result<Option<Args>, String> {
+        parse_args(a.iter().map(|s| s.to_string()), env.map(str::to_string))
+    }
+
+    #[test]
+    fn arguments() {
+        assert_eq!(parse(&[], None), Ok(Some(Args::default())));
+        assert_eq!(parse(&["--sample", "--control", "7070"], None), Ok(Some(Args { sample: true, control: Some(7070) })));
+        assert_eq!(parse(&[], Some("9000")), Ok(Some(Args { sample: false, control: Some(9000) })));
+        assert_eq!(parse(&[], Some("nope")), Ok(Some(Args::default())));
+        assert!(parse(&["--control"], None).is_err());
+        assert!(parse(&["--control", "99999"], None).is_err());
+        assert!(parse(&["--frobnicate"], None).is_err());
+        assert_eq!(parse(&["--help"], None), Ok(None));
+    }
+}