Files
makeCAD/crates/engine/src/control_pending.rs
T
Arjan Duijs 0690ee5875 Web app: run as a modelling editor inside another page that keeps the design files (#8517) (#11273)
* claim: #8517

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* web: editing embed for host pages (?embed=editor, #8517)

A host page that keeps the files itself and frames SolidCraft for modelling needs
the modelling UI without the application chrome. `?embed=editor` runs the web app
as such an embed:

- no application bar (logo, File menu, document tabs, update, help, report a bug)
  and no start page; the layout is docked;
- the ribbon, browser, timeline and properties stay; Ctrl+Z and Ctrl+Y still undo
  and redo;
- Ctrl+N, Ctrl+O, Ctrl+S, Ctrl+W and Ctrl+, are left to the host;
- nothing is kept in the browser (no stored designs, autosave, recovery prompt,
  preferences or leave-page prompt), as with the existing viewer embed.

The existing `?embed&open=` viewer embed is unchanged. SolveApp gets one flag,
`embed_editor`, for desktop and test hosts too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* control: document.export / document.import / document.saved for a host (#8517)

An editing embed's host keeps the design itself. Three control methods
(window.solidcraft.request in the browser; the desktop control channel too; not
the agent chat's, whose method list is unchanged):

- `document.export` -> {name, revision, dirty, format: "json", text}: the active
  design as a `.json` design file holds it. `revision` is the one
  `document.revision` answers, so a host that follows the design compares one number.
- `document.import {text, name?}`: replaces the active design with that text,
  timeline and parameters as saved, opened saved with a new `document_id`. It runs
  as a design opened in a tab of its own, with the old tab closed without asking,
  so whatever was open in the old design leaves with it. A text that does not read
  leaves the design as it was. Waits behind a file loading or a design change, as
  commands do, and evaluates on the window thread.
- `document.saved {revision}`: the host saved that revision; refused when the
  design has changed since.

They are control methods, not commands: they act on the app's open design. The
browser API test gets a round trip through all three.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: aduijs <7501203+aduijs@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 21:23:25 +00:00

171 lines
7.5 KiB
Rust

//! What a client is told about a control request that outlasts its wait (docs/control-protocol.md,
//! #1618): the app's control server and the bridged MCP server both say what the request still
//! does when it finishes: nothing (it only reads), write a file (an export or a save), or change
//! the design.
use serde_json::Value;
/// What a request still running does when it finishes.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Effect {
/// It only reads (the design, the window or the command list): nothing changes.
ReadsOnly,
/// It writes a file (an export, a save, a render to a path); the design stays as it is.
WritesFile,
/// It changes the design (or may: anything not known to read or only write a file).
Changes,
}
impl Effect {
/// What happens when the request finishes, for a message: "it only reads: nothing changes",
/// "it was not cancelled and will still write the file when it finishes", …
pub fn when_done(self) -> &'static str {
match self {
Effect::ReadsOnly => "it only reads: nothing changes",
Effect::WritesFile => "it was not cancelled and will still write the file when it finishes; the design does not change",
Effect::Changes => "it was not cancelled and will still apply when it finishes",
}
}
}
/// Control methods that only read: a timed-out one changes nothing when it finishes.
/// (`ui.screenshot` with a `path`, and `ui.render`, write a file: see [`effect`].)
const READ_METHODS: &[&str] = &[
"control.pending",
"control.subscribe",
"document.export",
"document.inspect",
"document.revision",
"engine.commands",
"ui.at",
"ui.handles",
"ui.inspect",
"ui.selection",
"ui.sketchToScreen",
"ui.triad",
"ui.worldToScreen",
];
/// Commands that write a file and leave the design as it is. `file.save` and `file.save_as`
/// count: they mark the design saved, but change nothing in it.
const FILE_COMMANDS: &[&str] = &["file.export", "file.save", "file.save_as", "file.save_mesh"];
/// Commands that only read the design (inspection, lists, measurements).
pub fn command_reads_only(id: &str) -> bool {
let id = crate::find_command(id).map_or(id, |c| c.id);
id.starts_with("inspect.")
|| id.starts_with("model.")
|| id.ends_with(".inspect")
|| id.ends_with(".list")
|| id == "document.revision"
|| id == "view.status_items"
|| matches!(id, "document.inspect" | "engine.commands" | "render.status" | "render.backends" | "render.settings.get" | "file.slicers")
}
/// What the command `id` with `params` does: an export that is given a `path` (`*.export*`, as
/// `sketch.export_dxf` or `parameters.export`) or a save writes a file; without a path an export
/// only answers with its contents.
pub fn command_effect(id: &str, params: &Value) -> Effect {
let id = crate::find_command(id).map_or(id, |c| c.id);
let exports = id.split('.').skip(1).any(|part| part.starts_with("export"));
if FILE_COMMANDS.contains(&id) || (exports && params.get("path").is_some_and(|p| !p.is_null())) {
Effect::WritesFile
} else if command_reads_only(id) || exports {
Effect::ReadsOnly
} else {
Effect::Changes
}
}
/// What the request `method` with `params` does when it finishes. Renders and screenshots
/// change nothing in the design; given a `path` they write it.
pub fn effect(method: &str, params: &Value) -> Effect {
match method {
"engine.execute" | "command" => match params.get("command").or_else(|| params.get("id")).and_then(Value::as_str) {
Some(id) => command_effect(id, params.get("params").unwrap_or(&Value::Null)),
None => Effect::Changes,
},
"ui.render" => Effect::WritesFile,
"ui.screenshot" if params.get("path").is_some_and(|p| !p.is_null()) => Effect::WritesFile,
"ui.screenshot" => Effect::ReadsOnly,
m if READ_METHODS.contains(&m) => Effect::ReadsOnly,
_ => Effect::Changes,
}
}
/// Whether the request `method` with `params` only reads.
pub fn reads_only(method: &str, params: &Value) -> bool {
effect(method, params) == Effect::ReadsOnly
}
/// The request in a message: "`engine.execute` (solid.fillet)", or just "`ui.inspect`".
pub fn describe(method: &str, params: &Value) -> String {
let command = matches!(method, "engine.execute" | "command")
.then(|| params.get("command").or_else(|| params.get("id")).and_then(Value::as_str))
.flatten()
.filter(|c| c.len() <= 128);
match command {
Some(c) => format!("`{method}` ({c})"),
None => format!("`{}`", method.chars().take(128).collect::<String>()),
}
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
#[test]
fn reads_are_told_from_changes() {
for (m, p) in [
("ui.inspect", json!({})),
("ui.screenshot", json!({})),
("document.export", json!({})),
("document.inspect", json!({"measure": true})),
("engine.execute", json!({"command": "sketch.inspect"})),
("engine.execute", json!({"command": "view.status_items", "params": {}})),
("engine.execute", json!({"command": "inspect.measure"})),
("engine.execute", json!({"command": "model.edges", "params": {"body": "Body1"}})),
("engine.execute", json!({"command": "parameters.export", "params": {"format": "csv"}})),
] {
assert!(reads_only(m, &p), "{m} {p}");
assert_eq!(effect(m, &p), Effect::ReadsOnly, "{m} {p}");
}
for (m, p) in [
("engine.execute", json!({"command": "solid.fillet"})),
("engine.execute", json!({})),
("engine.batch", json!({"commands": []})),
("ui.click", json!({"x": 1, "y": 2})),
("app.quit", json!({})),
("document.import", json!({"text": "{}"})),
("document.saved", json!({"revision": 1})),
] {
assert!(!reads_only(m, &p), "{m} {p}");
assert_eq!(effect(m, &p), Effect::Changes, "{m} {p}");
}
assert_eq!(describe("engine.execute", &json!({"command": "solid.fillet"})), "`engine.execute` (solid.fillet)");
assert_eq!(describe("ui.inspect", &json!({})), "`ui.inspect`");
}
/// An export or a save writes a file and leaves the design as it is (#1989: a STEP export
/// is not said to "still apply").
#[test]
fn file_writers_are_told_apart() {
for (m, p) in [
("engine.execute", json!({"command": "file.export", "params": {"path": "/tmp/a.step"}})),
("engine.execute", json!({"command": "file.save", "params": {}})),
("engine.execute", json!({"command": "file.save_as", "params": {"path": "/tmp/a.solidcraft"}})),
("engine.execute", json!({"command": "file.save_mesh", "params": {"path": "/tmp/a.stl"}})),
("engine.execute", json!({"command": "sketch.export_dxf", "params": {"path": "/tmp/a.dxf"}})),
("ui.render", json!({"path": "/tmp/a.png"})),
("ui.screenshot", json!({"path": "/tmp/a.png"})),
] {
assert_eq!(effect(m, &p), Effect::WritesFile, "{m} {p}");
assert!(!reads_only(m, &p), "{m} {p}");
}
assert!(Effect::WritesFile.when_done().contains("will still write the file") && !Effect::WritesFile.when_done().contains("apply"));
assert!(Effect::Changes.when_done().contains("will still apply"));
assert!(Effect::ReadsOnly.when_done().contains("nothing changes"));
}
}