SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Expose a JavaScript command API for the browser app (#1713)
Olup4193ea26acf0
diff --git a/README.md b/README.mdindex 094dc3f3f4..6452da9f02 100644--- a/README.md+++ b/README.md@@ -259,6 +259,9 @@ Each axis is scaled from the range the descriptor declares.In the browser: `cd apps/solidcraft-web && trunk build --release --public-url ./` (WebGPU, orWebGL2 with `?webgl`; `?sample` opens the sample part).+Agents can control the document open in a browser tab through `window.solidcraft.execute(...)`+and `window.solidcraft.request(...)`; see the [browser command API](docs/browser-api.md).+## ScriptsA script is a JSON list of commands, the same ones the UI runs:diff --git a/apps/solidcraft-web/src/api.rs b/apps/solidcraft-web/src/api.rsnew file mode 100644index 0000000000..121fbc8d11--- /dev/null+++ b/apps/solidcraft-web/src/api.rs@@ -0,0 +1,131 @@+//! Promise-based access to the running app's existing control channel.++use std::cell::RefCell;+use std::rc::Rc;+use std::sync::mpsc::{Receiver, Sender, TryRecvError};+use std::time::Duration;++use serde_json::{Value, json};+use solidcraft_ui_egui::ControlRequest;+use wasm_bindgen::{JsValue, closure::Closure};++const MAX_PENDING: usize = 256;+const MAX_JSON_BYTES: usize = 16 * 1024 * 1024;++struct Pending {+ reply: Receiver<Value>,+ resolve: js_sys::Function,+ reject: js_sys::Function,+}++#[derive(Clone)]+pub struct Api {+ sender: Sender<ControlRequest>,+ pending: Rc<RefCell<Vec<Pending>>>,+ ctx: egui::Context,+}++fn params(value: &JsValue) -> Result<Value, String> {+ if value.is_undefined() || value.is_null() {+ return Ok(json!({}));+ }+ let text = js_sys::JSON::stringify(value).ok().and_then(|v| v.as_string()).ok_or("params must be JSON serializable")?;+ if text.len() > MAX_JSON_BYTES {+ return Err("params exceed 16 MiB".into());+ }+ serde_json::from_str(&text).map_err(|e| format!("invalid params: {e}"))+}++fn error(message: &str) -> JsValue {+ js_sys::Error::new(message).into()+}++impl Api {+ pub fn install(sender: Sender<ControlRequest>, ctx: egui::Context) -> Result<Self, JsValue> {+ let api = Self { sender, pending: Rc::default(), ctx };+ let object = js_sys::Object::new();+ let request = api.clone();+ let execute = api.clone();+ let commands = api.clone();+ let inspect = api.clone();+ for (name, function) in [+ (+ "request",+ Closure::<dyn Fn(String, JsValue) -> js_sys::Promise>::new(move |method: String, value: JsValue| {+ request.request(&method, params(&value))+ })+ .into_js_value(),+ ),+ (+ "execute",+ Closure::<dyn Fn(String, JsValue) -> js_sys::Promise>::new(move |command: String, value: JsValue| {+ execute.request("engine.execute", params(&value).map(|p| json!({"command": command, "params": p})))+ })+ .into_js_value(),+ ),+ ("commands", Closure::<dyn Fn() -> js_sys::Promise>::new(move || commands.request("engine.commands", Ok(json!({})))).into_js_value()),+ (+ "inspect",+ Closure::<dyn Fn(JsValue) -> js_sys::Promise>::new(move |value: JsValue| inspect.request("document.inspect", params(&value)))+ .into_js_value(),+ ),+ ] {+ js_sys::Reflect::set(&object, &name.into(), &function)?;+ }+ let window = web_sys::window().ok_or_else(|| error("no window"))?;+ js_sys::Reflect::set(&window, &"solidcraft".into(), &object)?;+ Ok(api)+ }++ fn request(&self, method: &str, params: Result<Value, String>) -> js_sys::Promise {+ let params = match params {+ Ok(params) => params,+ Err(message) => return js_sys::Promise::reject(&error(&message)),+ };+ if self.pending.borrow().len() >= MAX_PENDING {+ return js_sys::Promise::reject(&error("too many pending SolidCraft requests (maximum 256)"));+ }+ js_sys::Promise::new(&mut |resolve, reject| {+ let (request, reply) = ControlRequest::new(method, params.clone());+ if self.sender.send(request).is_err() {+ let _ = reject.call1(&JsValue::UNDEFINED, &error("SolidCraft is not running"));+ return;+ }+ self.pending.borrow_mut().push(Pending { reply, resolve, reject });+ self.ctx.request_repaint();+ })+ }++ pub fn poll(&self) {+ let mut completed = Vec::new();+ self.pending.borrow_mut().retain_mut(|pending| {+ let result = match pending.reply.try_recv() {+ Ok(reply) => {+ if reply.get("ok").and_then(Value::as_bool) == Some(true) {+ js_sys::JSON::parse(&reply.get("result").unwrap_or(&Value::Null).to_string())+ } else {+ Err(error(reply.get("error").and_then(Value::as_str).unwrap_or("SolidCraft request failed")))+ }+ }+ Err(TryRecvError::Empty) => return true,+ Err(TryRecvError::Disconnected) => Err(error("SolidCraft request dropped")),+ };+ completed.push((pending.resolve.clone(), pending.reject.clone(), result));+ false+ });+ // Release the queue before calling JavaScript, which can submit another request.+ for (resolve, reject, result) in completed {+ match result {+ Ok(value) => {+ let _ = resolve.call1(&JsValue::UNDEFINED, &value);+ }+ Err(error) => {+ let _ = reject.call1(&JsValue::UNDEFINED, &error);+ }+ }+ }+ if !self.pending.borrow().is_empty() {+ self.ctx.request_repaint_after(Duration::from_millis(16));+ }+ }+}diff --git a/apps/solidcraft-web/src/main.rs b/apps/solidcraft-web/src/main.rsindex 5d760c6627..b134903b75 100644--- a/apps/solidcraft-web/src/main.rs+++ b/apps/solidcraft-web/src/main.rs@@ -6,6 +6,8 @@//! `?webgpu`), `?sample` opens the sample part.#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]+#[cfg(target_arch = "wasm32")]+mod api;#[cfg(target_arch = "wasm32")]mod files;#[cfg(target_arch = "wasm32")]@@ -22,6 +24,7 @@ mod web {use solidcraft_ui_egui::{Services, SolveApp};use wasm_bindgen::JsCast as _;+ use crate::api::Api;use crate::files::{self, Files, Intent};use crate::space_mouse::SpaceMouse;@@ -84,6 +87,7 @@ mod web {struct Shell {app: SolveApp,+ api: Api,files: Rc<Files>,/// When the last autosave was (seconds), and the revision it holds (none stored: `None`).autosaved_at: f64,@@ -413,6 +417,7 @@ mod web {fn logic(&mut self, ctx: &egui::Context, _frame: &mut eframe::Frame) {self.tick_font(ctx);self.app.logic(ctx);+ self.api.poll();self.space_mouse.logic(&mut self.app, ctx);self.files_tick(ctx);UNSAVED.with(|u| u.set(solidcraft_ui_egui::documents::any_dirty(&self.app)));@@ -520,7 +525,8 @@ mod web {};// Thumbnails of saves and start-page cards.solidcraft_ui_egui::gpu::install_cpu_picture_renderer();- let mut app = SolveApp::new(Session::default(), services);+ let (sender, receiver) = std::sync::mpsc::channel();+ let mut app = SolveApp::new(Session::default(), services).with_control(receiver);if let Some(p) = cc.storage.and_then(|s| solidcraft_ui_egui::prefs::stored(|k| s.get_string(k))) {app.load_prefs(&p);}@@ -542,8 +548,10 @@ mod web {let rev = app.session.revision;app.home.show(rev);}+ let api = Api::install(sender, cc.egui_ctx.clone()).map_err(|e| format!("SolidCraft browser API: {e:?}"))?;Ok(Box::new(Shell {app,+ api,files,autosaved_at: f64::NEG_INFINITY,autosaved: None,diff --git a/docs/browser-api.md b/docs/browser-api.mdnew file mode 100644index 0000000000..33ded3683f--- /dev/null+++ b/docs/browser-api.md@@ -0,0 +1,50 @@+# Browser command API++After the browser app starts, `window.solidcraft` controls the design open in that tab.+Calls use the same command ids, parameters, control handlers and undo history as the desktop+control channel. No separate engine or server is started.++| Call | Result |+|---|---|+| `solidcraft.request(method, params?)` | Any [control method](control-protocol.md), such as `ui.inspect`, `document.inspect` or `engine.batch` |+| `solidcraft.execute(command, params?)` | Run an engine command without opening its interactive dialog |+| `solidcraft.commands()` | Discover commands, their parameters and current enablement |+| `solidcraft.inspect(params?)` | Inspect the active document, optionally with `{measure: true}` |++Every call returns a promise. It resolves to the control reply's `result`, or rejects with an+`Error`. Omitted or `null` parameters become `{}`. Parameters must be JSON serializable and+at most 16 MiB of JSON. At most 256 requests may be pending; excess requests reject without+running. Requests run on the UI thread between frames. A hidden or suspended tab can delay+completion; keep it active while driving the app. A reload ends the session and its pending work.++In the browser's developer console, on an empty design:++```js+await solidcraft.commands();+await solidcraft.request("ui.home", {open: false});+await solidcraft.execute("solid.box", {+ length: 30, width: 20, height: 10, body_name: "Browser API box"+});+await solidcraft.inspect({measure: true});+await solidcraft.execute("edit.undo");+await solidcraft.execute("edit.redo");+await solidcraft.request("ui.inspect");+```++An agent with JavaScript evaluation access to this tab can make the same calls. The API does+not register WebMCP tools or expose a network listener. Scripts executing in the page can use+the API with the page's browser permissions. File paths refer to the browser's virtual file+system, not arbitrary files on the user's computer. Native-only operations remain subject to+the browser host's limitations; this API does not grant desktop filesystem or window access.++## Verify a browser build++Build the app with `trunk build` in `apps/solidcraft-web`, then run from the repository root:++```sh+cargo xtask web-api-test --site dist/web+```++The test starts a local server and headless Chrome, discovers commands, creates a box in the+live document, checks undo and redo, and verifies error handling and the pending-request limit.+Set `CHROME` to a Chrome or Chromium executable if it is not installed in a usual location.diff --git a/xtask/src/main.rs b/xtask/src/main.rsindex ae7ded72af..96faebd550 100644--- a/xtask/src/main.rs+++ b/xtask/src/main.rs@@ -60,6 +60,7 @@ commands:web-offline [DIR]write the web build's service worker (sw.js: offline use, updates); run byTrunk after release builds of apps/solidcraft-web, or on a built site in DIR+ web-api-test [--site DIR] Test the command API in a real browser build (default: dist/web)web-offline-test [--site DIR]check in headless Chrome that the web app works offline and updates to a newbuild (a stand-in app, or the web build in DIR such as dist/web)@@ -97,6 +98,10 @@ fn main() -> ExitCode {let site = rest.iter().position(|a| *a == "--site").and_then(|i| rest.get(i + 1)).copied();web_offline_test::run(&root(), site, true)}+ Some("web-api-test") => {+ let site = rest.iter().position(|a| *a == "--site").and_then(|i| rest.get(i + 1)).copied().unwrap_or("dist/web");+ web_offline_test::run_api(site)+ }Some("-h" | "--help" | "help") | None => {print!("{USAGE}");Ok(())diff --git a/xtask/src/web_offline_test.rs b/xtask/src/web_offline_test.rsindex 817d97531e..e006b22943 100644--- a/xtask/src/web_offline_test.rs+++ b/xtask/src/web_offline_test.rs@@ -66,6 +66,67 @@ const SLOW_NETWORK_WAIT: Duration = Duration::from_secs(3);/// How long a file takes in Mode::SlowFiles.const SLOW_FILE: Duration = Duration::from_secs(6);+/// Exercise the real browser build's command bridge, using the same Chrome harness as the offline test.+pub fn run_api(site: &str) -> Result<(), String> {+ let site = std::fs::canonicalize(site).map_err(|e| format!("{site}: {e}; build apps/solidcraft-web with trunk first"))?;+ if !site.join("index.html").is_file() {+ return Err(format!("{}: index.html missing; build apps/solidcraft-web with trunk first", site.display()));+ }+ let chrome = find_chrome().ok_or("web-api-test: Chrome not found (set CHROME to its executable)")?;+ let work = TempDir::new()?;+ let server = Server::start(site.clone())?;+ server.set(Mode::Serve(site));+ let browser = Chrome::launch(&chrome, &work.0.join("profile"))?;+ let mut cdp = browser.connect()?;+ cdp.call("Emulation.setDeviceMetricsOverride", json!({"width": 1280, "height": 900, "deviceScaleFactor": 1, "mobile": false}))?;+ cdp.call("Page.navigate", json!({"url": format!("http://127.0.0.1:{}{PREFIX}?webgl", server.port)}))?;+ wait_for(&mut cdp, "!!window.solidcraft && !document.getElementById('solidcraft_loading')", "the browser API is ready", |v| v == true)?;+ let result = cdp.eval(API_TEST)?;+ println!("web-api-test: {result}");+ Ok(())+}++const API_TEST: &str = r#"(async () => {+ const app = window.solidcraft;+ const check = (condition, message) => { if (!condition) throw new Error(message); };+ const rejects = async (call, message) => {+ try { await call(); } catch (error) {+ check(error instanceof Error, 'rejections must be Error objects');+ check(error.message.includes(message), error.message);+ return;+ }+ throw new Error('expected rejection: ' + message);+ };+ const commands = await app.commands();+ check(JSON.stringify(commands).includes('solid.box'), 'command discovery');+ await app.request('ui.home', {open: false});+ const before = await app.inspect();+ check(before.bodies.length === 0, 'test starts with an empty design');+ await app.execute('solid.box', {length: 30, width: 20, height: 10, body_name: 'Browser API box'});+ const after = await app.inspect({measure: true});+ check(after.bodies.length === 1, 'box appears in the active document');+ check(Math.abs(after.bodies[0].volume_mm3 - 6000) < 0.001, 'box volume is 6000 mm³');+ await app.execute('edit.undo');+ check((await app.inspect()).bodies.length === 0, 'undo removes the box');+ await app.execute('edit.redo', null);+ check((await app.inspect()).bodies.length === 1, 'redo restores the box');+ await rejects(() => app.request('missing.browser.method'), 'unknown');+ await rejects(() => app.execute('missing.browser.command'), 'unknown');+ const circular = {}; circular.self = circular;+ await rejects(() => app.request('ui.inspect', circular), 'JSON serializable');+ await rejects(() => app.request('ui.inspect', {value: 1n}), 'JSON serializable');+ await rejects(() => app.request('ui.inspect', {text: 'x'.repeat(16 * 1024 * 1024)}), '16 MiB');+ const queued = Array.from({length: 257}, () => app.request('ui.inspect'));+ const settled = await Promise.allSettled(queued);+ check(settled.filter(r => r.status === 'fulfilled').length === 256, 'queued requests drain across frames');+ check(settled.filter(r => r.status === 'rejected' && r.reason instanceof Error && r.reason.message.includes('pending')).length === 1,+ 'queue limit rejects excess work');+ check((await app.inspect()).bodies.length === 1, 'API still works after rejected requests');+ const ui = await app.request('ui.inspect');+ check(ui.home === false && ui.viewport[2] > 600, 'model viewport is visible');+ return {commands: 'discovered', bodies: [0, 1, 0, 1], errors: 'rejected', queue: '256 completed, 1 rejected'};+})()"#;+/// Run the test; `required: false` (from `cargo xtask ci`) skips it when Chrome is missing.pub fn run(root: &Path, site: Option<&str>, required: bool) -> Result<(), String> {let Some(chrome) = find_chrome() else {@@ -555,6 +616,7 @@ fn answer(mut stream: TcpStream, shared: &Mutex<Mode>, slow: &AtomicUsize, elsewlet kind = match file.and_then(|f| f.rsplit('.').next()) {Some("html") => "text/html; charset=utf-8",Some("js") => "text/javascript",+ Some("css") => "text/css",Some("json") => "application/json",Some("wasm") => "application/wasm",_ => "application/octet-stream",