202 upstream commits since 6cb00467a. Resolutions:
- craft-window, craft-platform: ours. Upstream's frame policy v2, restore
store and GNOME light/wait_first are the versions carried on 28 Oct;
ours moved place() to craft-behavior and kept LayoutWatch and the
appearance/portal.rs split.
- craft-timeline: ours. craft-time (crates/time) lands as upstream wrote
it and is not yet used by craft-timeline.
- Old crates/ui modules stay removed. Upstream's frosted backdrops, shape
gallery, dialog tabs and the iconic flyout top-edge rendering are not
carried. The #1094 model half is in craft-behavior's dock:
Group::flyout_offset and Action::MoveFlyoutTop.
- craft-update: #586 Save and Update, the install probe on the check
thread and quiet per-user MSI self-updates, carried into updater.rs,
stack_dialogs.rs, install/windows.rs and self_update/helper.rs.
- craft-jpeg: progressive Huffman decoding, carried into huffman.rs,
parse.rs and scan.rs.
- craft-print: the driver settings dialog's new tests and the bounded
XML parse's tests, as trials.
- Test-only conflicts: upstream tests from before the base that our side
cut stay cut; tests new upstream are kept.
craft-web-api
The page command API for every Craft web build: one window.<app> shape over the app's JSON
control channel.
The JS API
PageApi::install puts this on window.<app> ("vectorcraft" → window.vectorcraft), without
replacing an existing window.<app>: missing functions are added, an app that already has its own
keeps them. Each function returns a Promise that resolves with the method's result or rejects with
an Error carrying error. Every call has a timeout (30 s by default, PageApi::with_timeout);
when the app does not answer in time, the error says so and the app's request future is dropped, so an app that releases a request when its future goes away (the desktop ControlRequest has abandon) never runs a call the page was told had failed.
At most 64 calls may wait for the app at once (PageApi::with_max_in_flight); a call made while that many are waiting rejects at once with a busy error and never reaches the app, so a script that calls in a loop without awaiting cannot grow the app's queue without bound. The size of a call's params is not capped here: opening a file passes the file's bytes in them, and each app already limits the files it opens.
Who can call it
window.<app> is a plain property of the page's own global object: it is not a network port and it has no key. Any script that runs in the page's origin can call every function and so has the same command control as the app's desktop control server; a page from another origin cannot reach it, but a same-origin parent, child or opener that holds a reference to the window can call it directly, and frame or opener separation alone does not stop that (the host messages in craft-web-host check event.origin and event.source, and those checks do not apply to a direct call). Treat it as you treat the page's own scripts.
screenshot() resolves with the reply the app's control method sends, plus data when the reply carries the PNG inline: the base64 PNG, whatever field the app names it (pngBase64, png_base64, png or base64). A reply with no inline PNG, such as one the app wrote to a path, has no data and is unchanged.
Which functions are installed follows the app's Methods table: only the functions whose control
method the table provides are installed; request is always there.
| Function | Call | Table entry | Default method |
|---|---|---|---|
request |
request(method, params) |
— | — (as given) |
execute |
execute(command, params) |
execute |
engine.execute {command, params} |
commands |
commands() |
commands |
engine.commands {} |
docInspect |
docInspect(params) |
doc_inspect |
document.inspect |
uiInspect |
uiInspect(params) |
ui_inspect |
ui.inspect |
screenshot |
screenshot(params) |
screenshot |
ui.screenshot (with data: true); an inline PNG is always also in data |
Methods::default() is the desktop control-server method names; an app whose control channel
names a method differently, or lacks one, says so in its table (Methods::NONE is the empty table).
How an app wires it
The app hands the crate its control channel as a Request; the crate never knows the app's
internals. Using VectorCraft's channel (the same one the desktop control server uses) as the example:
use std::rc::Rc;
use craft_web_api::methods::Methods;
use craft_web_api::page::{PageApi, Request};
// Send a ControlRequest to the app and await its reply object ({ok, result} / {ok: false, error}).
let request: Request = Rc::new(move |method: String, params: serde_json::Value| {
let (req, rx) = ControlRequest::new(method, params);
control_tx.send(req);
Box::pin(poll_reply(rx)) // resolves when the app answers the request
});
let page = Rc::new(PageApi::new("vectorcraft", Methods::default(), request));
page.install()?; // window.vectorcraft
Beside the host messages
Opening a document, handing a saved or exported file to the host, the document name and the dirty
flag stay with the host messages in craft-web-host (<app>:open,
<app>:save, <app>:dirty, …) and the app's own control methods. A page reaches any control
method through request(method, params).
Tests
src/methods.rs carries the native unit tests (the default and empty tables). tests/page.rs runs
under wasm-bindgen-test in Node with a canned control channel: install and keeping an app's own
functions, the table deciding which functions exist, the method and params each function sends,
error replies as rejections, the timeout, and the in-flight limit.