From 78502eea6a1452b2fd1c70ac35730f4f7720f733 Mon Sep 17 00:00:00 2001
From: Helen Kwok <107752876+helenkwok@users.noreply.github.com>
Date: Fri, 6 Nov 2026 09:09:24 +0800
Subject: [PATCH] figcraft-web: window.figcraft takes its request functions
 from craft-web-api

request, execute, commands and screenshot move onto the shared crate (storytold/craft-libs#413): a timeout on every call, one data field for the screenshot's PNG, and docInspect and uiInspect beside them. A call the page gave up on cancels its request if the app has not started it, so the app skips it. openFile, captureDownloads, files, readFile and inspect stay FigCraft's own, on the same object.
---
 Cargo.lock                   |  14 ++-
 apps/figcraft-web/Cargo.toml |   4 +-
 apps/figcraft-web/src/api.rs | 166 ++++++++++++++++++++++-------------
 apps/figcraft-web/src/web.rs |   1 -
 docs/control-protocol.md     |   8 +-
 5 files changed, 125 insertions(+), 68 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 36bd121b6..5fdb9e27b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1157,10 +1157,21 @@ dependencies = [
  "zip 9.1.1",
 ]
 
+[[package]]
+name = "craft-web-api"
+version = "0.1.0"
+source = "git+https://github.com/storytold/craft-libs?rev=fd5e2feff6ea25bed371a99cc732b3968d621505#fd5e2feff6ea25bed371a99cc732b3968d621505"
+dependencies = [
+ "js-sys",
+ "serde_json",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+]
+
 [[package]]
 name = "craft-web-host"
 version = "0.1.0"
-source = "git+https://github.com/storytold/craft-libs?rev=2e2312ddaf21bc3d85cd3395d0955c7d239306f6#2e2312ddaf21bc3d85cd3395d0955c7d239306f6"
+source = "git+https://github.com/storytold/craft-libs?rev=fd5e2feff6ea25bed371a99cc732b3968d621505#fd5e2feff6ea25bed371a99cc732b3968d621505"
 dependencies = [
  "wasm-bindgen",
  "web-sys",
@@ -2130,6 +2141,7 @@ name = "figcraft-web"
 version = "0.15.0"
 dependencies = [
  "base64 0.22.1",
+ "craft-web-api",
  "craft-web-host",
  "eframe",
  "egui",
diff --git a/apps/figcraft-web/Cargo.toml b/apps/figcraft-web/Cargo.toml
index 7f0b4ded5..c37663258 100644
--- a/apps/figcraft-web/Cargo.toml
+++ b/apps/figcraft-web/Cargo.toml
@@ -20,7 +20,9 @@ figcraft-ui-egui = { workspace = true }
 figcraft-collab-net = { workspace = true }
 figcraft-text = { workspace = true }
 # The host messages (storytold/craft-libs): one contract and one bridge for the web builds.
-craft-web-host = { git = "https://github.com/storytold/craft-libs", rev = "2e2312ddaf21bc3d85cd3395d0955c7d239306f6", version = "0.1.0" }
+# The page command API (storytold/craft-libs#413): the request plumbing behind window.figcraft.
+craft-web-api = { git = "https://github.com/storytold/craft-libs", rev = "fd5e2feff6ea25bed371a99cc732b3968d621505", version = "0.1.0" }
+craft-web-host = { git = "https://github.com/storytold/craft-libs", rev = "fd5e2feff6ea25bed371a99cc732b3968d621505", version = "0.1.0" }
 base64 = { workspace = true }
 egui = { workspace = true }
 log = { workspace = true }
diff --git a/apps/figcraft-web/src/api.rs b/apps/figcraft-web/src/api.rs
index 7f6a0ec4d..167ea7687 100644
--- a/apps/figcraft-web/src/api.rs
+++ b/apps/figcraft-web/src/api.rs
@@ -1,36 +1,54 @@
-//! `window.figcraft`: the control channel for the page, as promises.
+//! `window.figcraft`: the page command API (`craft-web-api`, storytold/craft-libs#413) plus FigCraft's
+//! own file functions.
 //!
-//! 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:
+//! The crate installs `request`, `execute`, `commands`, `docInspect`, `uiInspect` and `screenshot`
+//! over the same JSON methods as the desktop control server (`docs/control-protocol.md`), as
+//! promises with a timeout, 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.execute("node.create", {type: "frame", name: "Home"})  // engine command → its result
 //! await figcraft.request("document.inspect")                            // control method → its result
 //! await figcraft.commands()                                             // command list
 //! const {data} = await figcraft.screenshot()                            // the canvas as PNG (base64)
+//! ```
+//!
+//! FigCraft adds, on the same object:
+//!
+//! ```js
 //! 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
+//! await figcraft.inspect()                                              // `document.inspect`
 //! ```
 //!
 //! Results resolve with the method's `result`; errors reject with an `Error`.
 
 use std::cell::{Cell, RefCell};
+use std::future::Future;
+use std::pin::Pin;
+use std::rc::Rc;
 use std::sync::mpsc::{Receiver, TryRecvError};
 
 use base64::Engine as _;
-use figcraft_ui_egui::{ControlReply, ControlRequest};
+use craft_web_api::methods::Methods;
+use craft_web_api::page::{PageApi, Request};
+use figcraft_ui_egui::{ControlReply, ControlRequest, RequestGate};
 use serde_json::{Value, json};
+use wasm_bindgen::JsCast;
 use wasm_bindgen::prelude::*;
+use wasm_bindgen_futures::{JsFuture, future_to_promise};
 
 use crate::saved_files::SavedFiles;
 
-type Waiting = (Receiver<ControlReply>, js_sys::Function, js_sys::Function);
+/// The app id in `window.<app>`.
+const APP: &str = "figcraft";
+
+/// How often a waiting call looks for the app's reply, in milliseconds (about a frame).
+const POLL_MS: i32 = 16;
 
 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) };
@@ -59,88 +77,112 @@ 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!({}))
+/// A queued control request whose reply has not arrived. Dropping it before the reply (the page's
+/// timeout fired) cancels the request if the app has not started it: the page was told it failed,
+/// so the app must not run it late.
+struct Waiting {
+    reply: Receiver<ControlReply>,
+    gate: RequestGate,
+    answered: bool,
 }
 
-/// 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
+impl Waiting {
+    /// The reply as the protocol's object once the app has answered or gone away; `None` while the
+    /// request is still waiting.
+    fn poll(&mut self) -> Option<Value> {
+        match self.reply.try_recv() {
+            Ok(ControlReply { result, .. }) => {
+                self.answered = true;
+                Some(match result {
+                    Ok(value) => json!({"ok": true, "result": value}),
+                    Err(error) => json!({"ok": false, "error": error}),
+                })
             }
-            Ok(ControlReply { result: Err(e), .. }) => {
-                let _ = reject.call1(&JsValue::NULL, &js_sys::Error::new(&e));
-                false
-            }
-            Err(TryRecvError::Empty) => true,
+            Err(TryRecvError::Empty) => None,
             Err(TryRecvError::Disconnected) => {
-                let _ = reject.call1(&JsValue::NULL, &js_sys::Error::new("request dropped"));
-                false
+                self.answered = true;
+                Some(json!({"ok": false, "error": "request dropped"}))
             }
-        });
-    });
+        }
+    }
 }
 
-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)));
+impl Drop for Waiting {
+    fn drop(&mut self) {
+        if !self.answered {
+            self.gate.cancel_if_open();
+        }
+    }
+}
+
+/// Queue a control request for the next frame and wait for the app's reply, as the protocol's
+/// `{ok, result}` / `{ok: false, error}` object.
+fn send(method: &str, params: Value) -> Pin<Box<dyn Future<Output = Value>>> {
+    let (reply, rx) = std::sync::mpsc::channel();
+    let id = NEXT_ID.with(|n| {
+        n.set(n.get() + 1);
+        n.get()
     });
+    let gate = RequestGate::new();
+    QUEUE.with(|q| q.borrow_mut().push(ControlRequest { id: json!(id), method: method.to_string(), params, reply, state: gate.clone() }));
     CTX.with(|c| {
         if let Some(ctx) = c.borrow().as_ref() {
             ctx.request_repaint();
         }
     });
-    p
+    let mut waiting = Waiting { reply: rx, gate, answered: false };
+    Box::pin(async move {
+        loop {
+            if let Some(reply) = waiting.poll() {
+                return reply;
+            }
+            sleep(POLL_MS).await;
+        }
+    })
+}
+
+async fn sleep(ms: i32) {
+    let promise = js_sys::Promise::new(&mut |resolve, _| {
+        if let Some(window) = web_sys::window() {
+            let _ = window.set_timeout_with_callback_and_timeout_and_arguments_0(&resolve, ms);
+        }
+    });
+    let _ = JsFuture::from(promise).await;
+}
+
+/// A reply as a promise outcome: the `result`, or an `Error` carrying the `error`.
+fn outcome(reply: &Value) -> Result<JsValue, JsValue> {
+    if reply.get("ok").and_then(Value::as_bool) == Some(true) {
+        Ok(to_js(reply.get("result").unwrap_or(&Value::Null)))
+    } else {
+        Err(js_sys::Error::new(reply.get("error").and_then(Value::as_str).unwrap_or("error")).into())
+    }
 }
 
 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`.
+/// Install `window.figcraft`: the crate's functions, then FigCraft's own.
 pub fn install() -> Result<(), JsValue> {
-    let obj = js_sys::Object::new();
+    let request: Request = Rc::new(|method, params| send(&method, params));
+    Rc::new(PageApi::new(APP, Methods::default(), request)).install()?;
+    let window = web_sys::window().ok_or("no window")?;
+    let obj: js_sys::Object = js_sys::Reflect::get(&window, &APP.into())?.unchecked_into();
     set_fn(
         &obj,
-        "request",
-        Closure::<dyn Fn(String, JsValue) -> js_sys::Promise>::new(|method: String, params: JsValue| request(&method, from_js(&params)))
+        "inspect",
+        Closure::<dyn Fn() -> js_sys::Promise>::new(|| future_to_promise(async { outcome(&send("document.inspect", json!({})).await) }))
             .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}}))
+            future_to_promise(async move {
+                outcome(&send("engine.execute", json!({"command": "file.open", "params": {"name": name, "data": data}})).await)
+            })
         })
         .into_js_value(),
     )?;
@@ -166,7 +208,5 @@ pub fn install() -> Result<(), JsValue> {
         })
         .into_js_value(),
     )?;
-    let w = web_sys::window().ok_or("no window")?;
-    js_sys::Reflect::set(&w, &"figcraft".into(), &obj)?;
     Ok(())
 }
diff --git a/apps/figcraft-web/src/web.rs b/apps/figcraft-web/src/web.rs
index 7da9f8c93..81bd91d64 100644
--- a/apps/figcraft-web/src/web.rs
+++ b/apps/figcraft-web/src/web.rs
@@ -225,7 +225,6 @@ 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();
         // The fonts on this computer that text asked for this frame are read; once one is in,
         // auto-sizing text measured in a fallback fits it.
         crate::local_fonts::load_wanted(ui.ctx());
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index 82ba08bd1..24be85cd9 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -463,11 +463,15 @@ app. It is opt-in: the page installs `window.figcraft` only when its URL has a `
 |---|---|
 | `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.commands()` | `engine.commands` |
+| `figcraft.docInspect(params)` / `figcraft.uiInspect(params)` | `document.inspect` / `ui.inspect` |
+| `figcraft.inspect()` | `document.inspect` (the name before `docInspect`) |
+| `figcraft.screenshot(params)` | `ui.screenshot` (no `path`: the PNG comes back inline, also as `data`) |
 | `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.
+
+`request`, `execute`, `commands`, `docInspect`, `uiInspect` and `screenshot` come from [`craft-web-api`](https://github.com/storytold/craft-libs/tree/main/crates/web-api) (storytold/craft-libs#413), the same shape in every Craft app. A call the app does not answer within 30 seconds rejects, and the app drops it unrun if it had not started it. `openFile`, `captureDownloads`, `files`, `readFile` and `inspect` are FigCraft's own.