Merge pull request #824 from youngeuibae/page-api

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

Cargo.lock

@@ -1860,6 +1860,7 @@ dependencies = [
 name = "figcraft-web"
 version = "0.11.2"
 dependencies = [
+ "base64 0.22.1",
  "eframe",
  "egui",
  "figcraft-collab-net",
@@ -1867,6 +1868,7 @@ dependencies = [
  "figcraft-ui-egui",
  "js-sys",
  "log",
+ "serde_json",
  "wasm-bindgen",
  "wasm-bindgen-futures",
  "web-sys",

apps/figcraft-web/Cargo.toml

@@ -24,6 +24,8 @@ log = { workspace = true }
 # `wgpu` pulls egui-wgpu's defaults: WebGPU plus the WebGL2 fallback.
 eframe = { workspace = true, features = ["default_fonts", "wgpu", "accesskit"] }
 wasm-bindgen = "0.2"
+base64 = { workspace = true }
+serde_json = { workspace = true }
 js-sys = "0.3"
 wasm-bindgen-futures = "0.4"
 web-sys = { version = "0.3", features = ["Window", "Document", "Element", "HtmlCanvasElement", "HtmlElement", "HtmlAnchorElement", "Node", "Blob", "BlobPropertyBag", "File", "FileList", "HtmlInputElement", "EventTarget", "Url", "Location", "MediaQueryList", "Navigator", "Gamepad", "GamepadButton", "GamepadMappingType"] }

apps/figcraft-web/src/api.rs

@@ -0,0 +1,172 @@
+//! `window.figcraft`: 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 FigCraft in a browser tab (or an `<iframe>` in another app) uses the same commands as
+//! the CLI and the MCP server:
+//!
+//! ```js
+//! await figcraft.execute("node.create", {kind: "frame", name: "Home"})  // engine command → its result
+//! await figcraft.request("document.inspect")                            // control method → its result
+//! await figcraft.commands()                                             // command list
+//! const {base64} = await figcraft.screenshot()                          // the canvas as PNG (base64)
+//! await figcraft.openFile("home.fig", bytes)                            // `file.open` with the bytes
+//! figcraft.captureDownloads(true)                                       // saves stay in the page…
+//! figcraft.files(); await figcraft.readFile("home.figcraft")            // …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, TryRecvError};
+
+use base64::Engine as _;
+use figcraft_ui_egui::{ControlReply, ControlRequest};
+use serde_json::{Value, json};
+use wasm_bindgen::prelude::*;
+
+use crate::saved_files::SavedFiles;
+
+type Waiting = (Receiver<ControlReply>, js_sys::Function, js_sys::Function);
+
+thread_local! {
+    static QUEUE: RefCell<Vec<ControlRequest>> = const { RefCell::new(Vec::new()) };
+    static WAITING: RefCell<Vec<Waiting>> = const { RefCell::new(Vec::new()) };
+    static NEXT_ID: Cell<u64> = const { Cell::new(0) };
+    static CTX: RefCell<Option<egui::Context>> = const { RefCell::new(None) };
+    static CAPTURE: Cell<bool> = const { Cell::new(false) };
+    static SAVED: RefCell<SavedFiles> = RefCell::new(SavedFiles::default());
+}
+
+pub fn connect(ctx: egui::Context) {
+    CTX.with(|c| *c.borrow_mut() = Some(ctx));
+}
+
+/// The page's requests since the last frame, for the app's control queue.
+pub fn take_requests() -> Vec<ControlRequest> {
+    QUEUE.with(|q| std::mem::take(&mut *q.borrow_mut()))
+}
+
+/// Keep a save instead of downloading it, when the page asked for that. True when kept.
+pub fn capture(name: &str, bytes: &[u8]) -> bool {
+    if !CAPTURE.with(Cell::get) {
+        return false;
+    }
+    SAVED.with(|s| s.borrow_mut().keep(name, 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(ControlReply { result: Ok(v), .. }) => {
+                let _ = resolve.call1(&JsValue::NULL, &to_js(&v));
+                false
+            }
+            Ok(ControlReply { result: Err(e), .. }) => {
+                let _ = reject.call1(&JsValue::NULL, &js_sys::Error::new(&e));
+                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 (reply, rx) = std::sync::mpsc::channel();
+        let id = NEXT_ID.with(|n| {
+            n.set(n.get() + 1);
+            n.get()
+        });
+        let req = ControlRequest { id: json!(id), method: method.clone(), params: params.clone(), reply, state: Default::default() };
+        QUEUE.with(|q| q.borrow_mut().push(req));
+        WAITING.with(|w| w.borrow_mut().push((rx, resolve, reject)));
+    });
+    CTX.with(|c| {
+        if let Some(ctx) = c.borrow().as_ref() {
+            ctx.request_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.figcraft`.
+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("document.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) -> js_sys::Promise>::new(|name: String, bytes: js_sys::Uint8Array| {
+            let data = base64::engine::general_purpose::STANDARD.encode(bytes.to_vec());
+            request("engine.execute", json!({"command": "file.open", "params": {"name": name, "data": data}}))
+        })
+        .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, &"figcraft".into(), &obj)?;
+    Ok(())
+}

apps/figcraft-web/src/main.rs

@@ -13,17 +13,22 @@
 //!   (browsers block `ws://` from secure pages); serve it over `http://` on a trusted network to
 //!   join from other machines.
 //!
-//! URL query flag: `?webgl` forces the WebGL2 backend instead of WebGPU.
+//! URL query flags: `?webgl` forces the WebGL2 backend instead of WebGPU; `?control` installs
+//! `window.figcraft`, the page's control channel (`api.rs`), which is off without it.
 //!
 //! URL fragment: `#join=<invite link or join code>` joins that live session once the page has
 //! loaded, so a bookmark opens a shared file. `join` takes the rest of the fragment: put it last.
 //! The link carries the session's secret; a fragment is never sent to the web host, but the address
 //! bar and the browser history keep it, so the URL is as private as the link itself.
 
+#[cfg(target_arch = "wasm32")]
+mod api;
 #[cfg(any(target_arch = "wasm32", test))]
 mod query;
 #[cfg(test)]
 mod query_tests;
+#[cfg(any(target_arch = "wasm32", test))]
+mod saved_files;
 #[cfg(target_arch = "wasm32")]
 mod web;
 

apps/figcraft-web/src/query.rs

@@ -1,4 +1,4 @@
-//! The page's URL: the invite link its fragment names.
+//! The page's URL: the invite link its fragment names, and the flags its query sets.
 
 /// The invite link in `#join=<link>` (`fragment` is `location.hash`, with or without its `#`), still
 /// escaped. The fragment, unlike the query, never leaves the browser, so the link's secret stays out
@@ -13,3 +13,10 @@ pub fn join_link(fragment: &str) -> Option<&str> {
     let start = if fragment.starts_with("join=") { 0 } else { fragment.find("&join=")? + 1 };
     fragment.get(start + "join=".len()..).filter(|link| !link.is_empty() && link.len() <= MAX)
 }
+
+/// Whether `search` (`location.search`, with or without its `?`) has a `control` entry (`?control`,
+/// or `?control=…` with any value): the page's control channel, `window.figcraft`, is installed only
+/// when it is asked for.
+pub fn control(search: &str) -> bool {
+    search.strip_prefix('?').unwrap_or(search).split('&').any(|entry| entry.split('=').next() == Some("control"))
+}

apps/figcraft-web/src/query_tests.rs

@@ -1,6 +1,6 @@
-//! `#join=` in the page's URL.
+//! `#join=` and `?control` in the page's URL.
 
-use crate::query::join_link;
+use crate::query::{control, join_link};
 
 #[test]
 fn join_takes_the_rest_of_the_fragment() {
@@ -27,3 +27,14 @@ fn an_overlong_link_is_ignored() {
     assert_eq!(join_link(&long), None);
     assert_eq!(join_link(&format!("#join={}", "é".repeat(4000))), None, "length counts bytes");
 }
+
+#[test]
+fn control_is_opt_in() {
+    assert!(control("?control"));
+    assert!(control("?webgl&control=1"), "after other entries, with a value");
+    assert!(control("control"), "no leading ?");
+    assert!(!control(""));
+    assert!(!control("?"));
+    assert!(!control("?webgl"));
+    assert!(!control("?nocontrol&controls"), "only the whole entry name");
+}

apps/figcraft-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"[..]));
+    }
+}

apps/figcraft-web/src/web.rs

@@ -47,6 +47,13 @@ pub fn start() {
                         let link = js_sys::decode_uri_component(link).ok().and_then(|s| s.as_string()).unwrap_or_else(|| link.to_string());
                         figcraft_ui_egui::live::open_invite(&mut fig, &link);
                     }
+                    // `?control`: `window.figcraft`, the page's control channel (crate::api), opt-in.
+                    if crate::query::control(&query()) {
+                        crate::api::connect(cc.egui_ctx.clone());
+                        if let Err(e) = crate::api::install() {
+                            log::error!("couldn't install window.figcraft: {e:?}");
+                        }
+                    }
                     Ok(Box::new(WebShell { fig }))
                 }),
             )
@@ -79,7 +86,9 @@ impl eframe::App for WebShell {
     }
 
     fn ui(&mut self, ui: &mut egui::Ui, _frame: &mut eframe::Frame) {
+        self.fig.control_queue.extend(crate::api::take_requests());
         self.fig.ui(ui);
+        crate::api::poll_replies();
     }
 }
 
@@ -109,6 +118,9 @@ impl Services for WebServices {
     }
     /// A Blob behind a temporary `<a download>` link, clicked and removed.
     fn download(&mut self, name: &str, bytes: &[u8]) -> bool {
+        if crate::api::capture(name, bytes) {
+            return true;
+        }
         match download(name, bytes) {
             Ok(()) => true,
             Err(e) => {

docs/control-protocol.md

@@ -377,3 +377,24 @@ read -r reply <&3; echo "$reply"
 
 For agents, prefer the MCP server (`figcraft-cli mcp --attach 7979`, see `docs/mcp.md`): it wraps
 these methods in documented tools and returns images inline.
+
+## In the browser: `window.figcraft`
+
+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.figcraft` (`apps/figcraft-web/src/api.rs`). An agent driving FigCraft in a
+browser tab, or a host app showing it in an `<iframe>`, uses the commands it would send to the desktop
+app. It is opt-in: the page installs `window.figcraft` only when its URL has a `control` query entry
+(`index.html?control`, which can be combined with other flags: `?webgl&control`).
+
+| Call | |
+|---|---|
+| `figcraft.request(method, params)` | any control method of this document → its `result` |
+| `figcraft.execute(command, params)` | `engine.execute` |
+| `figcraft.commands()` / `figcraft.inspect()` | `engine.commands` / the inspect method |
+| `figcraft.screenshot(params)` | `ui.screenshot` (no `path`: the PNG comes back inline) |
+| `figcraft.openFile(name, bytes)` | runs `file.open` with the bytes as `data` and resolves with its result |
+| `figcraft.captureDownloads(on)` | while on, a save or export is kept in the page instead of downloaded |
+| `figcraft.files()` / `figcraft.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.