From f9bf685cbdf55d01aa2f00a167127724cf2c4959 Mon Sep 17 00:00:00 2001
From: Helen Kwok <107752876+helenkwok@users.noreply.github.com>
Date: Fri, 6 Nov 2026 22:25:08 +0800
Subject: [PATCH] vectorcraft-web: window.vectorcraft 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, the screenshot's PNG also in data, and docInspect and uiInspect beside them. A call the page gave up on gives up its request if the app has not started it, so the app skips it. openFile, captureDownloads, files, readFile and inspect stay VectorCraft's own, on the same object.
---
 Cargo.lock                      |  12 +++
 apps/vectorcraft-web/Cargo.toml |   2 +
 apps/vectorcraft-web/src/api.rs | 144 +++++++++++++++++++-------------
 apps/vectorcraft-web/src/web.rs |   2 -
 docs/control-protocol.md        |   8 +-
 5 files changed, 104 insertions(+), 64 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 32cffe9fd..6f92cb310 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1093,6 +1093,17 @@ dependencies = [
  "thiserror 2.0.21",
 ]
 
+[[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-window"
 version = "0.1.0"
@@ -6594,6 +6605,7 @@ dependencies = [
 name = "vectorcraft-web"
 version = "0.21.0"
 dependencies = [
+ "craft-web-api",
  "eframe",
  "egui",
  "js-sys",
diff --git a/apps/vectorcraft-web/Cargo.toml b/apps/vectorcraft-web/Cargo.toml
index 8decb13d8..ff4bcef86 100644
--- a/apps/vectorcraft-web/Cargo.toml
+++ b/apps/vectorcraft-web/Cargo.toml
@@ -16,6 +16,8 @@ path = "src/main.rs"
 [dependencies]
 vectorcraft-engine = { workspace = true, features = ["bundled-fonts"] }
 vectorcraft-ui-egui = { workspace = true }
+# The page command API (storytold/craft-libs#413): the request plumbing behind window.vectorcraft.
+craft-web-api = { git = "https://github.com/storytold/craft-libs", rev = "fd5e2feff6ea25bed371a99cc732b3968d621505", version = "0.1.0" }
 vectorcraft-format = { workspace = true }
 vectorcraft-text = { workspace = true }
 egui = { workspace = true }
diff --git a/apps/vectorcraft-web/src/api.rs b/apps/vectorcraft-web/src/api.rs
index 526e56be1..eddd04f1b 100644
--- a/apps/vectorcraft-web/src/api.rs
+++ b/apps/vectorcraft-web/src/api.rs
@@ -1,14 +1,18 @@
 //! `window.vectorcraft`: the control channel for the page, as promises.
 //!
+//! `request`, `execute`, `commands`, `docInspect`, `uiInspect` and `screenshot` come from
+//! `craft-web-api` (storytold/craft-libs#413), the same in every Craft app; VectorCraft adds its own
+//! functions on the same object.
+//!
 //! 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.execute("shape.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)
+//! const {data} = 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
@@ -17,21 +21,24 @@
 //! 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, Sender, TryRecvError};
 
+use craft_web_api::methods::Methods;
+use craft_web_api::page::{PageApi, Request};
 use serde_json::{Value, json};
-use vectorcraft_ui_egui::ControlRequest;
+use vectorcraft_ui_egui::{ControlRequest, ControlTicket as Ticket};
 use wasm_bindgen::prelude::*;
+use wasm_bindgen_futures::{JsFuture, future_to_promise};
 
 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) };
@@ -69,77 +76,96 @@ 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!({});
+/// 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())
     }
-    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
+/// How often a waiting call looks for the app's reply, in milliseconds (about a frame).
+const POLL_MS: i32 = 16;
+
+/// A queued control request whose reply has not arrived. Dropping it before the reply (the page's
+/// timeout fired) gives the request up if the app has not started it, so the app never runs it late.
+struct Waiting {
+    reply: Receiver<Value>,
+    ticket: Ticket,
+    answered: bool,
+}
+
+impl Waiting {
+    /// The app's reply once it has answered or gone away; `None` while the request is waiting.
+    fn poll(&mut self) -> Option<Value> {
+        match self.reply.try_recv() {
+            Ok(reply) => {
+                self.answered = true;
+                Some(reply)
             }
-            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 (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"));
+impl Drop for Waiting {
+    fn drop(&mut self) {
+        if !self.answered {
+            self.ticket.give_up();
+        }
+    }
+}
+
+/// Queue a control request for the app and wait for its reply, as the protocol's `{ok, result}` /
+/// `{ok: false, error}` object.
+fn send(method: &str, params: Value) -> Pin<Box<dyn Future<Output = Value>>> {
+    let (req, rx) = ControlRequest::new(method, params);
+    let ticket = req.ticket();
+    let sent = TX.with(|t| t.borrow().as_ref().is_some_and(|tx| tx.send(req).is_ok()));
+    if !sent {
+        return Box::pin(async { json!({"ok": false, "error": "VectorCraft is not running yet"}) });
+    }
+    repaint();
+    let mut waiting = Waiting { reply: rx, ticket, 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);
         }
     });
-    repaint();
-    p
+    let _ = JsFuture::from(promise).await;
 }
 
 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`.
+/// Install `window.vectorcraft`: the crate's functions, then VectorCraft's own (`inspect` is its
+/// `ui.inspect`).
 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("vectorcraft", Methods::default(), request)).install()?;
+    let window = web_sys::window().ok_or("no window")?;
+    let obj: js_sys::Object = js_sys::Reflect::get(&window, &"vectorcraft".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)))
-            .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(),
+        "inspect",
+        Closure::<dyn Fn() -> js_sys::Promise>::new(|| future_to_promise(async { outcome(&send("ui.inspect", json!({})).await) })).into_js_value(),
     )?;
     set_fn(
         &obj,
@@ -178,7 +204,5 @@ pub fn install() -> Result<(), JsValue> {
         })
         .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/web.rs b/apps/vectorcraft-web/src/web.rs
index 75eb7b308..60682d698 100644
--- a/apps/vectorcraft-web/src/web.rs
+++ b/apps/vectorcraft-web/src/web.rs
@@ -370,7 +370,6 @@ impl eframe::App for WebShell {
         }
         let Some(app) = &mut self.app else { return };
         app.tick(ctx);
-        crate::api::poll_replies();
         app.finish_ime_logic(ctx);
     }
 
@@ -423,7 +422,6 @@ impl eframe::App for WebShell {
             }
             app.ui(ui);
         }
-        crate::api::poll_replies();
     }
 }
 
diff --git a/docs/control-protocol.md b/docs/control-protocol.md
index a25f189b0..0a9bfd9f0 100644
--- a/docs/control-protocol.md
+++ b/docs/control-protocol.md
@@ -1000,8 +1000,10 @@ app:
 |---|---|
 | `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.commands()` | `engine.commands` |
+| `vectorcraft.docInspect(params)` / `vectorcraft.uiInspect(params)` | `document.inspect` / `ui.inspect` |
+| `vectorcraft.inspect()` | `ui.inspect` (the name before `uiInspect`) |
+| `vectorcraft.screenshot(params)` | `ui.screenshot` (no `path`: the PNG comes back inline, as `data` and as `pngBase64`) |
 | `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` |
@@ -1009,6 +1011,8 @@ app:
 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 VectorCraft's own.
+
 ## Revision history
 
 | Date | Change | Summary |