Skip to content

VectorCraft: An open-source, vector art tool written by scratch in pure Rust

web: window.vectorcraft, the control channel for the page

focuer9dbab52168fe
diff --git a/Cargo.lock b/Cargo.lock
index afaecd644..159ea55a8 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -5007,6 +5007,7 @@ dependencies = [
"js-sys",
"log",
"rfd",
+ "serde_json",
"vectorcraft-engine",
"vectorcraft-format",
"vectorcraft-text",
diff --git a/apps/vectorcraft-web/Cargo.toml b/apps/vectorcraft-web/Cargo.toml
index 2e9218dc3..f67a377ef 100644
--- a/apps/vectorcraft-web/Cargo.toml
+++ b/apps/vectorcraft-web/Cargo.toml
@@ -26,6 +26,7 @@ log = { workspace = true }
eframe = { workspace = true, features = ["default_fonts", "wgpu", "accesskit"] }
rfd = { workspace = true }
wasm-bindgen = "0.2"
+serde_json = { workspace = true }
wasm-bindgen-futures = "0.4"
js-sys = "0.3"
web-sys = { version = "0.3", features = ["Window", "Document", "Element", "HtmlElement", "HtmlCanvasElement", "HtmlIFrameElement", "HtmlAnchorElement", "Blob", "BlobPropertyBag", "ClipboardEvent", "DataTransfer", "File", "FileList", "Url", "Location", "CssStyleDeclaration", "Event", "EventTarget", "MouseEvent", "PointerEvent", "TouchEvent", "AddEventListenerOptions", "DomRect", "DragEvent", "Storage", "Navigator", "RequestInit", "Response", "AbortController", "AbortSignal"] }
diff --git a/apps/vectorcraft-web/src/api.rs b/apps/vectorcraft-web/src/api.rs
new file mode 100644
index 000000000..47252756d
--- /dev/null
+++ b/apps/vectorcraft-web/src/api.rs
@@ -0,0 +1,183 @@
+//! `window.vectorcraft`: the control channel for the page, as promises.
+//!
+//! The same JSON methods as the desktop control server (`docs/control-protocol.md`), so an agent
+//! driving VectorCraft in a browser tab (or an `<iframe>` in another app) uses the same commands as
+//! the CLI and the MCP server:
+//!
+//! ```js
+//! await vectorcraft.execute("object.rectangle", {x: 0, y: 0, width: 100, height: 50}) // engine command → its result
+//! await vectorcraft.request("ui.inspect") // control method → its result
+//! await vectorcraft.commands() // command list
+//! const {base64} = await vectorcraft.screenshot() // the canvas as PNG (base64)
+//! await vectorcraft.openFile("logo.svg", bytes) // opened as a dropped file is
+//! vectorcraft.captureDownloads(true) // saves stay in the page…
+//! vectorcraft.files(); await vectorcraft.readFile("logo.png") // …to be read back
+//! ```
+//!
+//! Results resolve with the method's `result`; errors reject with an `Error`.
+
+use std::cell::{Cell, RefCell};
+use std::sync::mpsc::{Receiver, Sender, TryRecvError};
+
+use vectorcraft_ui_egui::ControlRequest;
+use serde_json::{Value, json};
+use wasm_bindgen::prelude::*;
+
+use crate::saved_files::SavedFiles;
+
+use crate::web::Inbox;
+
+type Waiting = (Receiver<Value>, js_sys::Function, js_sys::Function);
+
+thread_local! {
+ static TX: RefCell<Option<Sender<ControlRequest>>> = const { RefCell::new(None) };
+ static WAITING: RefCell<Vec<Waiting>> = const { RefCell::new(Vec::new()) };
+ static CTX: RefCell<Option<egui::Context>> = const { RefCell::new(None) };
+ static INBOX: RefCell<Option<Inbox>> = const { RefCell::new(None) };
+ static CAPTURE: Cell<bool> = const { Cell::new(false) };
+ static SAVED: RefCell<SavedFiles> = RefCell::new(SavedFiles::default());
+}
+
+/// Wire the page's requests to the app: control requests go to `tx`, opened files to `inbox`.
+/// After a graphics restart the app keeps its channel: `tx` is `None` and only the context changes.
+pub fn connect(tx: Option<Sender<ControlRequest>>, inbox: Inbox, ctx: egui::Context) {
+ if let Some(tx) = tx {
+ TX.with(|t| *t.borrow_mut() = Some(tx));
+ }
+ INBOX.with(|i| *i.borrow_mut() = Some(inbox));
+ CTX.with(|c| *c.borrow_mut() = Some(ctx));
+}
+
+fn repaint() {
+ CTX.with(|c| {
+ if let Some(ctx) = c.borrow().as_ref() {
+ ctx.request_repaint();
+ }
+ });
+}
+
+/// Keep a save instead of downloading it, when the page asked for that. True when kept.
+pub fn capture(path: &str, bytes: &[u8]) -> bool {
+ if !CAPTURE.with(Cell::get) {
+ return false;
+ }
+ SAVED.with(|s| s.borrow_mut().keep(path, bytes));
+ true
+}
+
+fn to_js(v: &Value) -> JsValue {
+ js_sys::JSON::parse(&v.to_string()).unwrap_or(JsValue::NULL)
+}
+
+fn from_js(v: &JsValue) -> Value {
+ if v.is_undefined() || v.is_null() {
+ return json!({});
+ }
+ js_sys::JSON::stringify(v).ok().and_then(|s| s.as_string()).and_then(|s| serde_json::from_str(&s).ok()).unwrap_or(json!({}))
+}
+
+/// Settle the promises of answered requests (called every frame).
+pub fn poll_replies() {
+ WAITING.with(|w| {
+ w.borrow_mut().retain(|(rx, resolve, reject)| match rx.try_recv() {
+ Ok(v) => {
+ if v.get("ok").and_then(Value::as_bool) == Some(true) {
+ let _ = resolve.call1(&JsValue::NULL, &to_js(v.get("result").unwrap_or(&Value::Null)));
+ } else {
+ let msg = v.get("error").and_then(Value::as_str).unwrap_or("error").to_string();
+ let _ = reject.call1(&JsValue::NULL, &js_sys::Error::new(&msg));
+ }
+ false
+ }
+ Err(TryRecvError::Empty) => true,
+ Err(TryRecvError::Disconnected) => {
+ let _ = reject.call1(&JsValue::NULL, &js_sys::Error::new("request dropped"));
+ false
+ }
+ });
+ });
+}
+
+fn request(method: &str, params: Value) -> js_sys::Promise {
+ let method = method.to_string();
+ let p = js_sys::Promise::new(&mut |resolve, reject| {
+ let (req, rx) = ControlRequest::new(method.clone(), params.clone());
+ let sent = TX.with(|t| t.borrow().as_ref().is_some_and(|tx| tx.send(req).is_ok()));
+ if sent {
+ WAITING.with(|w| w.borrow_mut().push((rx, resolve, reject)));
+ } else {
+ let _ = reject.call1(&JsValue::NULL, &js_sys::Error::new("VectorCraft is not running yet"));
+ }
+ });
+ repaint();
+ p
+}
+
+fn set_fn(obj: &js_sys::Object, name: &str, f: JsValue) -> Result<(), JsValue> {
+ js_sys::Reflect::set(obj, &name.into(), &f).map(|_| ())
+}
+
+/// Install `window.vectorcraft`.
+pub fn install() -> Result<(), JsValue> {
+ let obj = js_sys::Object::new();
+ set_fn(
+ &obj,
+ "request",
+ Closure::<dyn Fn(String, JsValue) -> js_sys::Promise>::new(|method: String, params: JsValue| request(&method, from_js(&params))).into_js_value(),
+ )?;
+ set_fn(
+ &obj,
+ "execute",
+ Closure::<dyn Fn(String, JsValue) -> js_sys::Promise>::new(|command: String, params: JsValue| {
+ request("engine.execute", json!({"command": command, "params": from_js(&params)}))
+ })
+ .into_js_value(),
+ )?;
+ set_fn(&obj, "commands", Closure::<dyn Fn() -> js_sys::Promise>::new(|| request("engine.commands", json!({}))).into_js_value())?;
+ set_fn(&obj, "inspect", Closure::<dyn Fn() -> js_sys::Promise>::new(|| request("ui.inspect", json!({}))).into_js_value())?;
+ set_fn(
+ &obj,
+ "screenshot",
+ Closure::<dyn Fn(JsValue) -> js_sys::Promise>::new(|params: JsValue| request("ui.screenshot", from_js(&params))).into_js_value(),
+ )?;
+ set_fn(
+ &obj,
+ "openFile",
+ Closure::<dyn Fn(String, js_sys::Uint8Array) -> JsValue>::new(|name: String, bytes: js_sys::Uint8Array| {
+ let queued = INBOX.with(|i| {
+ i.borrow().as_ref().is_some_and(|inbox| {
+ inbox.lock().unwrap_or_else(|e| e.into_inner()).push((name, bytes.to_vec()));
+ true
+ })
+ });
+ repaint();
+ JsValue::from_bool(queued)
+ })
+ .into_js_value(),
+ )?;
+ set_fn(&obj, "captureDownloads", Closure::<dyn Fn(bool)>::new(|on: bool| CAPTURE.with(|c| c.set(on))).into_js_value())?;
+ set_fn(
+ &obj,
+ "files",
+ Closure::<dyn Fn() -> JsValue>::new(|| {
+ SAVED.with(|s| to_js(&Value::Array(s.borrow().list().map(|(n, size)| json!({"path": n, "size": size})).collect())))
+ })
+ .into_js_value(),
+ )?;
+ set_fn(
+ &obj,
+ "readFile",
+ Closure::<dyn Fn(String) -> Result<JsValue, JsValue>>::new(|name: String| {
+ SAVED.with(|s| {
+ s.borrow()
+ .get(&name)
+ .map(|b| js_sys::Uint8Array::from(b).into())
+ .ok_or_else(|| js_sys::Error::new(&format!("{name}: not found")).into())
+ })
+ })
+ .into_js_value(),
+ )?;
+ let w = web_sys::window().ok_or("no window")?;
+ js_sys::Reflect::set(&w, &"vectorcraft".into(), &obj)?;
+ Ok(())
+}
diff --git a/apps/vectorcraft-web/src/main.rs b/apps/vectorcraft-web/src/main.rs
index 32cd10784..e2e31da97 100644
--- a/apps/vectorcraft-web/src/main.rs
+++ b/apps/vectorcraft-web/src/main.rs
@@ -23,6 +23,10 @@ mod locks;
#[cfg(any(target_arch = "wasm32", test))]
mod pencil;
#[cfg(target_arch = "wasm32")]
+mod api;
+#[cfg(any(target_arch = "wasm32", test))]
+mod saved_files;
+#[cfg(target_arch = "wasm32")]
mod web;
#[cfg(target_arch = "wasm32")]
diff --git a/apps/vectorcraft-web/src/saved_files.rs b/apps/vectorcraft-web/src/saved_files.rs
new file mode 100644
index 000000000..7cd88637d
--- /dev/null
+++ b/apps/vectorcraft-web/src/saved_files.rs
@@ -0,0 +1,70 @@
+//! What the page keeps of the app's saves (`api.rs`): `readFile` reads them back.
+
+/// Saved files kept (the oldest go first).
+pub const MAX_SAVED: usize = 16;
+
+/// The last component of a `/` or `\` path.
+fn file_name(path: &str) -> &str {
+ path.rsplit(['/', '\\']).next().filter(|n| !n.is_empty()).unwrap_or(path)
+}
+
+/// Files by name, newest last: saving a name again replaces it.
+#[derive(Default)]
+pub struct SavedFiles(Vec<(String, Vec<u8>)>);
+
+impl SavedFiles {
+ /// Keep `bytes` under the last component of `path`.
+ pub fn keep(&mut self, path: &str, bytes: &[u8]) {
+ let name = file_name(path).to_string();
+ self.0.retain(|(n, _)| *n != name);
+ self.0.push((name, bytes.to_vec()));
+ let extra = self.0.len().saturating_sub(MAX_SAVED);
+ self.0.drain(..extra);
+ }
+
+ /// A kept file by its name, or by a path ending in it.
+ pub fn get(&self, name: &str) -> Option<&[u8]> {
+ let wanted = file_name(name);
+ self.0.iter().find(|(n, _)| n == wanted).map(|(_, b)| b.as_slice())
+ }
+
+ /// `(name, size)` of each kept file, oldest first.
+ pub fn list(&self) -> impl Iterator<Item = (&str, usize)> {
+ self.0.iter().map(|(n, b)| (n.as_str(), b.len()))
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn keeps_by_name_replaces_and_reads_back_by_path() {
+ let mut s = SavedFiles::default();
+ s.keep("exports/poster.png", b"one");
+ s.keep(r"C:\out\poster.png", b"two");
+ s.keep("notes.txt", b"three");
+ assert_eq!(s.list().collect::<Vec<_>>(), vec![("poster.png", 3), ("notes.txt", 5)]);
+ assert_eq!(s.get("poster.png"), Some(&b"two"[..]));
+ assert_eq!(s.get("/exports/poster.png"), Some(&b"two"[..]));
+ assert_eq!(s.get("missing.png"), None);
+ }
+
+ #[test]
+ fn drops_the_oldest_past_the_cap() {
+ let mut s = SavedFiles::default();
+ for i in 0..MAX_SAVED + 3 {
+ s.keep(&format!("f{i}.png"), &[0]);
+ }
+ assert_eq!(s.list().count(), MAX_SAVED);
+ assert_eq!(s.get("f0.png"), None);
+ assert!(s.get(&format!("f{}.png", MAX_SAVED + 2)).is_some());
+ }
+
+ #[test]
+ fn a_trailing_separator_keeps_the_whole_name() {
+ let mut s = SavedFiles::default();
+ s.keep("odd/", b"x");
+ assert_eq!(s.get("odd/"), Some(&b"x"[..]));
+ }
+}
diff --git a/apps/vectorcraft-web/src/web.rs b/apps/vectorcraft-web/src/web.rs
index cfe8458b4..c30799475 100644
--- a/apps/vectorcraft-web/src/web.rs
+++ b/apps/vectorcraft-web/src/web.rs
@@ -19,7 +19,7 @@ use wasm_bindgen::JsCast as _;
use crate::locks::WebLocks;
use crate::pencil::SharedPointers;
-type Inbox = Arc<Mutex<Vec<(String, Vec<u8>)>>>;
+pub(crate) type Inbox = Arc<Mutex<Vec<(String, Vec<u8>)>>>;
/// Where the pointer was over the canvas during the last file drag (CSS px from its top-left) and
/// whether Shift was held: where dropped files land.
@@ -122,9 +122,18 @@ async fn run(host: Host, canvas: web_sys::HtmlCanvasElement, moving: Option<Movi
// The old services asked the old context for frames.
app.services = services;
app.status("The graphics were lost and have been restarted");
+ crate::api::connect(None, host.inbox.clone(), ctx.clone());
app
}
- None => VectorcraftApp::new(Session::new(), services),
+ None => {
+ // `window.vectorcraft`: the page's control channel (crate::api).
+ let (control_tx, control_rx) = std::sync::mpsc::channel();
+ crate::api::connect(Some(control_tx), host.inbox.clone(), ctx.clone());
+ if let Err(e) = crate::api::install() {
+ log::error!("vectorcraft-web: couldn't install window.vectorcraft: {}", js_err(e));
+ }
+ VectorcraftApp::new(Session::new(), services).with_control(control_rx)
+ }
};
Ok(Box::new(WebShell { app: Some(app), host, canvas: page, loss }))
}),
@@ -386,6 +395,7 @@ impl eframe::App for WebShell {
}
}
app.logic(ctx);
+ crate::api::poll_replies();
}
fn raw_input_hook(&mut self, _ctx: &egui::Context, raw: &mut egui::RawInput) {
@@ -399,6 +409,7 @@ impl eframe::App for WebShell {
if let Some(app) = &mut self.app {
app.ui(ui);
}
+ crate::api::poll_replies();
}
}
@@ -544,6 +555,9 @@ impl RecoveryStore for BrowserStore {
/// Trigger a browser download of `bytes` named after the last component of `path`.
fn download(path: &str, bytes: &[u8]) -> Result<(), String> {
+ if crate::api::capture(path, bytes) {
+ return Ok(());
+ }
let js = |e: wasm_bindgen::JsValue| format!("{e:?}");
let name = std::path::Path::new(path).file_name().map(|n| n.to_string_lossy().to_string()).unwrap_or_else(|| "vectorcraft".into());
let window = web_sys::window().ok_or("no window")?;
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index 62ac716b7..1fbb9b1aa 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -880,9 +880,30 @@ split paths return an error without changing the workspace.
- [x] Release connection slots on worker exit, including timeout and failed worker creation.
- [x] Preserve correlated replies and persistent connections within the transport budgets.
+## In the browser: `window.vectorcraft`
+
+The web build has no TCP server (a page can't listen on a socket), so it offers the same methods to the
+page itself, as promises on `window.vectorcraft` (`apps/vectorcraft-web/src/api.rs`). An agent driving VectorCraft in a
+browser tab, or a host app showing it in an `<iframe>`, uses the commands it would send to the desktop
+app:
+
+| Call | |
+|---|---|
+| `vectorcraft.request(method, params)` | any control method of this document → its `result` |
+| `vectorcraft.execute(command, params)` | `engine.execute` |
+| `vectorcraft.commands()` / `vectorcraft.inspect()` | `engine.commands` / the inspect method |
+| `vectorcraft.screenshot(params)` | `ui.screenshot` (no `path`: the PNG comes back inline) |
+| `vectorcraft.openFile(name, bytes)` | opens the bytes the way a dropped file opens (returns `true` once queued) |
+| `vectorcraft.captureDownloads(on)` | while on, a save or export is kept in the page instead of downloaded |
+| `vectorcraft.files()` / `vectorcraft.readFile(name)` | the kept files (`{path, size}`) / one of them as a `Uint8Array` |
+
+Errors reject with an `Error` carrying the method's message. Requests run on the UI's next frame, so a
+hidden tab (whose frames the browser pauses) answers when it is shown again.
+
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-10-13 | minor | Documented count, pending-event and per-frame request budgets (#1709). |
| 2026-10-13 | minor | Documented transport deadlines and connection-slot recovery (#1726). |
+| 2026-10-18 | minor | Documented `window.vectorcraft`, the web build's control channel. |