From 0690ee5875d5efdf9b5769c9796f28b8896fdf90 Mon Sep 17 00:00:00 2001 From: Arjan Duijs Date: Wed, 4 Nov 2026 21:23:25 +0000 Subject: [PATCH] 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 * 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 * 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 --------- Co-authored-by: aduijs <7501203+aduijs@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 --- apps/solidcraft-web/src/main.rs | 26 +++++++-- crates/engine/src/control_pending.rs | 4 ++ crates/ui-egui/src/agent_chat/gate.rs | 4 ++ crates/ui-egui/src/control.rs | 6 ++ crates/ui-egui/src/control_job.rs | 2 +- crates/ui-egui/src/documents.rs | 43 ++++++++++++++ crates/ui-egui/src/lib.rs | 13 ++++- crates/ui-egui/src/shell_tests.rs | 79 ++++++++++++++++++++++++++ crates/ui-egui/src/toolbar.rs | 4 +- docs/book/src/guide/getting-started.md | 14 +++++ docs/browser-api.md | 19 +++++++ docs/control-protocol.md | 7 +++ xtask/src/web_offline_test.rs | 14 ++++- 13 files changed, 227 insertions(+), 8 deletions(-) diff --git a/apps/solidcraft-web/src/main.rs b/apps/solidcraft-web/src/main.rs index 4509dffa3..d9db4981a 100644 --- a/apps/solidcraft-web/src/main.rs +++ b/apps/solidcraft-web/src/main.rs @@ -3,7 +3,8 @@ //! Runs the same [`solidcraft_ui_egui::SolveApp`] as the desktop app through eframe's web runner //! (wgpu: WebGPU where available, WebGL2 otherwise). Build with `trunk build --release` from this //! directory (output in `dist/web`). URL flags: `?webgl` forces WebGL2 (remembered until -//! `?webgpu`), `?sample` opens the sample part. +//! `?webgpu`), `?sample` opens the sample part, `?embed=editor` runs it as an editing embed in a +//! host page (no application bar or start page; nothing kept in the browser; #8517). #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] #[cfg(target_arch = "wasm32")] @@ -42,6 +43,8 @@ fn query_flag(query: &str, name: &str) -> bool { struct Launch { open: Option, embed: bool, + /// `?embed=editor` (#8517): an editing embed in a host page that keeps the files itself. + editor: bool, } #[cfg(any(target_arch = "wasm32", test))] @@ -52,16 +55,19 @@ impl Launch { for (key, value) in url::form_urlencoded::parse(query.trim_start_matches('?').as_bytes()) { match key.as_ref() { "open" if launch.open.is_none() => launch.open = Some(value.into_owned()), + "embed" if value == "editor" => launch.editor = true, "embed" => embed = true, _ => {} } } - launch.embed = embed && launch.open.is_some(); + launch.embed = embed && launch.open.is_some() && !launch.editor; launch } + /// The browser's own storage (designs, autosave, recovery, preferences) is used: not when + /// embedded, where the host keeps what is kept. fn persists(&self) -> bool { - !self.embed + !self.embed && !self.editor } fn full_app_url(&self, mut url: url::Url) -> String { @@ -928,7 +934,7 @@ mod web { } let (panel, opener, saver, shown) = (files.clone(), files.clone(), files.clone(), files.clone()); let (restorable, restorer) = (files.clone(), files.clone()); - let services = if launch.embed { Services::default() } else { Services { + let services = if !launch.persists() { Services::default() } else { Services { // Open shows the browser's open dialog for a design where it has one // (the file keeps its handle, so Save writes back to it), else the // browser's files window. A command that reads another kind of file @@ -972,6 +978,7 @@ mod web { let (sender, receiver) = std::sync::mpsc::channel(); let mut app = SolveApp::new(Session::default(), services).with_control(receiver); app.embedded = launch.embed; + app.embed_editor = launch.editor; // Listening before reading: settings another tab writes from now on are // newer than those read here. let other_tab_prefs = PrefsInbox::default(); @@ -1082,6 +1089,17 @@ mod tests { assert!(full.fragment().is_none()); } + #[test] + fn embed_editor_needs_no_design_link_and_keeps_nothing_in_the_browser() { + let editor = Launch::parse("?embed=editor"); + assert!(editor.editor && !editor.embed && !editor.persists()); + let linked = Launch::parse("?embed=editor&open=https://example.org/a.sc"); + assert!(linked.editor && !linked.embed, "an editing embed may open a linked design, still editable"); + let viewer = Launch::parse("?embed=viewer&open=https://example.org/a.sc"); + assert!(viewer.embed && !viewer.editor, "any other value is the viewer embed, as before"); + assert!(!Launch::parse("?other=editor").editor); + } + #[test] fn design_links_refuse_hostile_schemes_credentials_and_sizes() { assert!(design_url("https://example.org/arm.solidcraft?download=1", "http://solidcraft.io").is_ok()); diff --git a/crates/engine/src/control_pending.rs b/crates/engine/src/control_pending.rs index 1579fc834..eb3509658 100644 --- a/crates/engine/src/control_pending.rs +++ b/crates/engine/src/control_pending.rs @@ -33,6 +33,7 @@ impl Effect { const READ_METHODS: &[&str] = &[ "control.pending", "control.subscribe", + "document.export", "document.inspect", "document.revision", "engine.commands", @@ -119,6 +120,7 @@ mod tests { 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": {}})), @@ -135,6 +137,8 @@ mod tests { ("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}"); diff --git a/crates/ui-egui/src/agent_chat/gate.rs b/crates/ui-egui/src/agent_chat/gate.rs index 633d190b2..be95d6e05 100644 --- a/crates/ui-egui/src/agent_chat/gate.rs +++ b/crates/ui-egui/src/agent_chat/gate.rs @@ -342,6 +342,10 @@ mod tests { for m in ["app.quit", "ui.click", "ui.prefs", "ui.agent_chat", "engine.script", "ui.key", "ui.file"] { assert!(matches!(request(m, &json!({}), 0), Verdict::Refuse(_)), "{m}"); } + // How a host page keeps the design (#8517) is not the agent's. + for m in ["document.export", "document.import", "document.saved"] { + assert!(matches!(request(m, &json!({}), 0), Verdict::Refuse(_)), "{m}"); + } } #[test] diff --git a/crates/ui-egui/src/control.rs b/crates/ui-egui/src/control.rs index 3b57df38b..9c481a517 100644 --- a/crates/ui-egui/src/control.rs +++ b/crates/ui-egui/src/control.rs @@ -10,6 +10,8 @@ //! of it first //! - `engine.commands`: every command with tab, panel, params and enablement //! - `document.inspect {measure?}`: the design (parameters, timeline, bodies, sketches) +//! - `document.export`, `document.import {text, name?}`, `document.saved {revision}`: the design +//! for a host that keeps the files itself (#8517) //! - `ui.inspect`: UI state, viewport rect, camera, tool and dialog //! - `ui.drag {x0, y0, x1, y1, button?, shift?, ctrl?, steps?, hold?}` (box selection, navigation; //! `hold` keeps the button down that many frames before moving); @@ -821,6 +823,10 @@ fn dispatch(app: &mut SolveApp, ctx: &egui::Context, method: &str, p: &Value) -> "engine.commands" => wrap(execute(app, "engine.commands", json!({}))), "document.inspect" => wrap(app.session.execute("document.inspect", p).map_err(|e| e.to_string())), "document.revision" => wrap(app.session.execute("document.revision", p).map_err(|e| e.to_string())), + // A host that keeps the files itself (an editing embed, #8517). + "document.export" => wrap(crate::documents::export(app)), + "document.import" => wrap(crate::documents::import(app, p)), + "document.saved" => wrap(crate::documents::saved(app, p)), // The connection already counts as subscribed (`DesignWatch::join`), and its events start // from this answer: published first, so no event repeats it and none older follows. "control.subscribe" => { diff --git a/crates/ui-egui/src/control_job.rs b/crates/ui-egui/src/control_job.rs index 931f7ce4b..f6b1565bb 100644 --- a/crates/ui-egui/src/control_job.rs +++ b/crates/ui-egui/src/control_job.rs @@ -132,7 +132,7 @@ fn reading(req: &ControlRequest) -> Option<(&'static str, Value)> { /// Requests that change the design: they wait while one computes. pub(crate) fn changes_the_design(method: &str) -> bool { - matches!(method, "engine.execute" | "command" | "engine.script" | "engine.batch") + matches!(method, "engine.execute" | "command" | "engine.script" | "engine.batch" | "document.import" | "document.saved") } /// Whether `doc` is the design `session` shows, as it is or edited since (an undo step away). diff --git a/crates/ui-egui/src/documents.rs b/crates/ui-egui/src/documents.rs index 82c21ef2b..aee803318 100644 --- a/crates/ui-egui/src/documents.rs +++ b/crates/ui-egui/src/documents.rs @@ -486,6 +486,49 @@ pub fn adopt(app: &mut SolveApp, session: Session) { } } +/// The active design as its file holds it (`document.export`): what a host that keeps the files +/// itself writes (#8517). `text` is the design's JSON, the same a `.json` design file holds, and +/// `revision` is the one `document.revision` names this state by. +pub fn export(app: &mut SolveApp) -> Result { + let revision = app.session.design_revision(); + let design = app.session.design(); + let text = String::from_utf8(solidcraft_engine::io::write_design(&design)).map_err(|e| e.to_string())?; + Ok(json!({"name": design.name, "revision": revision, "dirty": app.session.is_dirty(), "format": "json", "text": text})) +} + +/// Replace the active design with one a host kept (`document.import {text, name?}`): the text of +/// a design file (its JSON, as `document.export` gives it). It opens saved, with nothing to undo, +/// in the active design's place: as a design opened in a tab of its own, with that tab closed +/// without asking. A text that does not read changes nothing. +pub fn import(app: &mut SolveApp, p: &Value) -> Result { + if app.file_picker_busy() || app.file_load.busy() || app.docs.closing.is_some() || app.docs.quitting.is_some() || app.docs.batch.is_some() { + return Err("a file is being opened or saved, or designs are being closed: try again".into()); + } + let text = p.get("text").and_then(Value::as_str).ok_or("missing `text` (the design's JSON)")?; + let mut doc = solidcraft_engine::io::read_design(text.as_bytes()).map_err(|e| e.to_string())?; + if let Some(name) = p.get("name").and_then(Value::as_str).map(str::trim).filter(|n| !n.is_empty()) { + doc.name = name.to_string(); + } + let replaced = app.docs.active; + open_tab(app, Session::opened(doc, None))?; + close(app, replaced, true); + let errors = app.session.model.results.iter().filter(|r| r.error.is_some()).count(); + let revision = app.session.design_revision(); + Ok(json!({"name": app.session.doc.name, "features": app.session.doc.features.len(), "errors": errors, "revision": revision})) +} + +/// The host saved the design at `revision` (`document.saved`): it counts as saved from there. +/// Refused when the design has changed since. +pub fn saved(app: &mut SolveApp, p: &Value) -> Result { + let revision = p.get("revision").and_then(Value::as_u64).ok_or("missing `revision`")?; + let now = app.session.design_revision(); + if revision != now { + return Err(format!("the design changed since revision {revision} (now {now})")); + } + app.session.mark_saved(); + Ok(json!({"revision": revision, "dirty": app.session.is_dirty()})) +} + /// A new, empty design in its own tab. One that is already empty keeps its tab and still /// takes Units of new designs (#1205): a launch starts on that empty design, so returning /// here used to leave it in millimetres. diff --git a/crates/ui-egui/src/lib.rs b/crates/ui-egui/src/lib.rs index 543051435..5f9b277ee 100644 --- a/crates/ui-egui/src/lib.rs +++ b/crates/ui-egui/src/lib.rs @@ -524,6 +524,11 @@ pub struct SolveApp { pub(crate) viewport_status_fixture: viewport_status_fixture::Fixture, /// Compact browser embed: retain model panels and joint controls without application chrome. pub embedded: bool, + /// Editing embed (#8517): the host page owns the files and the window's chrome. No + /// application bar, no start page, no New/Open/Save/Close or Preferences shortcuts; the + /// ribbon, browser, timeline and properties stay, and the host reads and replaces the + /// design through `document.export` / `document.import`. + pub embed_editor: bool, pub session: Session, pub ui: UiState, pub(crate) shell: shell::State, @@ -930,6 +935,7 @@ impl SolveApp { fit_waits: 0, flat_view: Default::default(), embedded: false, + embed_editor: false, home: home::HomeState::default(), space_mouse: Default::default(), file_load: file_load::FileLoad::default(), @@ -3104,6 +3110,11 @@ impl SolveApp { self.ui.show_browser = true; self.ui.show_timeline = true; } + if self.embed_editor { + // The host shows one design and has its own way to start one. + self.ui.layout = shell::LayoutMode::Docked; + self.home.open = false; + } self.ui.layout.publish(ui.ctx()); self.preferences.dialog_buttons.publish(ui.ctx()); self.preferences.toast_place.publish(ui.ctx()); @@ -3112,7 +3123,7 @@ impl SolveApp { self.poll_deferred(ui.ctx()); self.poll_delete_check(ui.ctx()); timeline::tick_playback(self, ui.ctx()); - if !self.embedded { + if !self.embedded && !self.embed_editor { toolbar::app_bar(self, ui); } issue_report::CadInput::block(self, ui, report_input); diff --git a/crates/ui-egui/src/shell_tests.rs b/crates/ui-egui/src/shell_tests.rs index 8efb2e1fa..f5cfd1ad8 100644 --- a/crates/ui-egui/src/shell_tests.rs +++ b/crates/ui-egui/src/shell_tests.rs @@ -741,6 +741,40 @@ fn embed_keeps_model_panels_without_application_chrome() { assert!(h.app.viewport.rect.is_some()); } +#[test] +fn embed_editor_keeps_the_ribbon_and_leaves_files_to_the_host() { + let mut h = Harness::new(); + h.settle(); + assert!(rect_of("appbar:home").is_some(), "the full app has its application bar"); + h.app.embed_editor = true; + h.app.home.show(h.app.session.revision); + h.settle(); + assert!(!h.app.home.open, "the host shows the design, never the start page"); + assert_eq!(h.app.ui.layout, LayoutMode::Docked); + assert!(rect_of("appbar:home").is_none() && rect_of("titlebar:report").is_none(), "no application bar"); + assert!(rect_of("button:sketch.create").is_some() && rect_of("browser:card").is_some(), "the modelling surface stays"); + // With no bar to hold it, command search stays in the ribbon whatever the host's header layout. + h.app.header = crate::toolbar::HeaderLayout::COMPACT; + h.settle(); + assert!(rect_of("ribbon:search").is_some() && rect_of("titlebar:search").is_none()); + h.step(&json!({"click":{"handle":"button:sketch.create"}})).unwrap(); + assert!(h.app.dialog.is_some(), "and its commands work"); + h.step(&json!({"key":"Escape"})).unwrap(); + // New, Open, Save, Close and Preferences belong to the host page. + let (docs, revision) = (h.app.docs.count(), h.app.session.revision); + for key in ["N", "O", "S", "W", "Comma"] { + h.step(&json!({"key":key,"cmd":true})).unwrap(); + } + h.settle(); + assert_eq!((h.app.docs.count(), h.app.session.revision), (docs, revision)); + assert!(!h.app.file_picker_busy() && !h.app.prefs_window.open, "{}", h.call("ui.inspect", json!({}))); + // Undo stays the design's own. + h.app.run("solid.box", json!({"length":40,"width":30,"height":20})).unwrap(); + h.settle(); + h.step(&json!({"key":"Z","cmd":true})).unwrap(); + assert!(h.app.session.doc.features.is_empty(), "Ctrl+Z undoes in the embed too"); +} + /// A design with a finished sketch nothing uses yet, so Extrude opens ready for OK. fn sketched(h: &mut Harness) { h.app.run("sketch.create", json!({"plane":"XY"})).unwrap(); @@ -748,6 +782,51 @@ fn sketched(h: &mut Harness) { h.app.run("sketch.finish", json!({})).unwrap(); } +#[test] +fn a_host_keeps_the_design_and_gives_it_back_with_its_timeline() { + let mut h = Harness::new(); + h.app.embed_editor = true; + sketched(&mut h); + h.app.run("solid.box", json!({"length":40,"width":30,"height":20})).unwrap(); + h.settle(); + let kept = h.call("document.export", json!({})); + assert_eq!(kept["ok"], true, "{kept}"); + let kept = &kept["result"]; + assert_eq!((kept["format"].as_str(), kept["dirty"].as_bool()), (Some("json"), Some(true))); + assert_eq!(kept["revision"], h.call("document.revision", json!({}))["result"]["revision"], "the revision that follows the design"); + let text = kept["text"].as_str().unwrap().to_string(); + let timeline = |h: &Harness| h.app.session.doc.features.iter().map(|f| f.name.clone()).collect::>(); + let before = timeline(&h); + assert!(before.len() >= 2, "{before:?}"); + // The host says it saved: the design is saved from there, until the next change. + let at = kept["revision"].as_u64().unwrap(); + assert_eq!(h.call("document.saved", json!({"revision": at}))["result"]["dirty"], false); + assert!(!h.app.session.is_dirty()); + assert_eq!(h.call("document.saved", json!({"revision": at + 7}))["ok"], false, "another revision is refused"); + // Something else is drawn and left open; the kept design comes back in its place, saved, + // timeline and all, and what was going on in the other leaves with it. + h.app.run("solid.box", json!({"length":10,"width":10,"height":10})).unwrap(); + assert_eq!(h.call("document.saved", json!({"revision": at}))["ok"], false, "the design changed since"); + h.call("ui.start", json!({"command":"sketch.create"})); + h.settle(); + assert!(h.app.dialog.is_some(), "{}", h.call("ui.inspect", json!({}))); + let (docs, id) = (h.app.docs.count(), h.app.session.document_id.clone()); + let back = h.call("document.import", json!({"text": text, "name": "Bracket"})); + assert_eq!(back["ok"], true, "{back}"); + assert_eq!(back["result"]["errors"], 0); + assert_eq!(back["result"]["revision"], h.call("document.revision", json!({}))["result"]["revision"]); + assert_eq!(timeline(&h), before); + assert_eq!((h.app.session.doc.name.as_str(), h.app.session.is_dirty(), h.app.docs.count()), ("Bracket", false, docs)); + assert_ne!(h.app.session.document_id, id, "another design, as one opened is"); + assert!(h.app.session.undo.is_empty(), "the undo history is the opened design's own"); + assert!(h.app.dialog.is_none() && h.app.tool.is_none()); + h.settle(); + for bad in [json!({}), json!({"text": "{"}), json!({"text": "not a design"})] { + assert_eq!(h.call("document.import", bad.clone())["ok"], false, "{bad}"); + assert_eq!(timeline(&h), before, "a refused import leaves the design as it was"); + } +} + /// Dialogs › In the left column (#6707): Extrude takes the place of the browser and the History /// at the left, at the column's width and never narrower than its card, in both layouts and /// every History dock. The view keeps its size, the dialog is covered, the content area starts diff --git a/crates/ui-egui/src/toolbar.rs b/crates/ui-egui/src/toolbar.rs index adb030a1b..7a39fca9a 100644 --- a/crates/ui-egui/src/toolbar.rs +++ b/crates/ui-egui/src/toolbar.rs @@ -393,7 +393,7 @@ pub enum VersionPlace { /// The closed search field goes in the application bar rather than the ribbon. pub(crate) fn search_in_header(app: &SolveApp) -> bool { - app.header.search == SearchPlace::Header && !app.embedded + app.header.search == SearchPlace::Header && !app.embedded && !app.embed_editor } /// Space between the header search field and Settings. @@ -3396,6 +3396,8 @@ pub fn shortcuts(app: &mut SolveApp, ctx: &egui::Context) { } if mods.command { match k { + // An editing embed's host has its own New, Open, Save, Close and settings. + Key::N | Key::O | Key::S | Key::W | Key::Comma if app.embed_editor => {} Key::N => crate::documents::new_design(app), Key::Comma => crate::prefs::open_at(app, 0), Key::O => { diff --git a/docs/book/src/guide/getting-started.md b/docs/book/src/guide/getting-started.md index 592bd363a..ec30248b7 100644 --- a/docs/book/src/guide/getting-started.md +++ b/docs/book/src/guide/getting-started.md @@ -175,6 +175,20 @@ Embedded designs do not save designs, preferences, or recovery copies to browser storage and do not ask before unloading. **Open in SolidCraft** opens the same link in the full app in a new tab. `?embed` without `open` keeps the normal app layout. +Use `embed=editor` instead for a page that keeps the designs itself and has people model in +the frame. It needs no `open`: + +```html + +``` + +The ribbon, browser tree, timeline and properties stay; the application bar and start page +do not. Ctrl+N, Ctrl+O, Ctrl+S, Ctrl+W and Ctrl+, do nothing there, because those belong to +the page; Ctrl+Z and Ctrl+Y still undo and redo. As with `embed`, nothing is kept in browser +storage: the page moves the design in and out with the `document.export` and +`document.import` control methods. + ### Self-hosting with Docker The web app is also a container image, `ghcr.io/tangency-labs/solidcraft-web`, for Linux on x86_64 diff --git a/docs/browser-api.md b/docs/browser-api.md index 0065b3a63..63b37c65d 100644 --- a/docs/browser-api.md +++ b/docs/browser-api.md @@ -37,6 +37,25 @@ the API with the page's browser permissions. File paths refer to the browser's v system, not arbitrary files on the user's computer. Native-only operations remain subject to the browser host's limitations; this API does not grant desktop filesystem or window access. +## A host page that keeps the designs + +`?embed=editor` runs the app as an editing embed: the ribbon, browser, timeline and properties, +without the application bar or start page, and with nothing kept in the browser. A page that +frames it from the same origin reaches this API as `frame.contentWindow.solidcraft`, keeps the +designs itself and moves them with three [control methods](control-protocol.md): + +```js +const app = frame.contentWindow.solidcraft; +const kept = await app.request("document.export"); // {name, revision, dirty, format: "json", text} +// ...the page stores kept.text, and says so: +await app.request("document.saved", {revision: kept.revision}); +// ...and later puts it back, timeline and parameters as saved: +await app.request("document.import", {text: kept.text, name: "Bracket"}); +``` + +The 16 MiB limit on parameters applies to `document.import`'s `text`. A design that links other +design files keeps those links as paths; the files themselves are not in `text`. + ## Verify a browser build Build the app with `trunk build` in `apps/solidcraft-web`, then run from the repository root: diff --git a/docs/control-protocol.md b/docs/control-protocol.md index ec74cb88d..ef81fe597 100644 --- a/docs/control-protocol.md +++ b/docs/control-protocol.md @@ -429,9 +429,16 @@ reply without `param_check` as unchecked. The bridged MCP server asks once per c | `document.revision` | — | `{document_id, revision}`: the active design's id and a number that moves whenever the design changes, for programs that follow it ([Following the design](#following-the-design)) | | `control.subscribe` | — | `{document_id, revision}`, as `document.revision`; the connection is then sent a `design.changed` line whenever they change ([Following the design](#following-the-design)) | | `document.inspect` | `measure?`: bool | parameters, timeline (errors, timings), bodies, sketches, selection (assembly joints: `engine.execute` `joint.inspect {joint?}`, which reads only: each joint's two origins with the occurrence, the snap as saved, the feature, face, edge or sketch curve its names refer to, and whether it resolves or why not; kind, offset, angle, flip, values, limits, expressions and motion links) | +| `document.export` | — | `{name, revision, dirty, format, text}`: the active design as its file holds it, for a host that keeps the files itself ([browser command API](browser-api.md)). `text` is the design's JSON, what a `.json` design file holds; `format` is `"json"`; `revision` is the one `document.revision` answers for this state. Only reads | +| `document.import` | `text`: a design's JSON; `name?`: the name it takes | `{name, features, errors, revision}`: replaces the active design with `text`, timeline and parameters as saved; it opens saved, with a new `document_id` and nothing to undo. It does not ask about unsaved changes in the design it replaces: that is the caller's to decide. A text that does not read changes nothing. Waits behind a file loading or a design change, and evaluates on the window thread in the frame it runs | +| `document.saved` | `revision`: as `document.export` gave it | `{revision, dirty}`: the host saved the design at that revision, so it counts as saved from there. Refused when the design has changed since | Commands never open dialogs when run this way. `solidcraft-cli commands` prints the same registry. +`document.export`, `document.import` and `document.saved` are control methods, not commands: they +act on the app's open design rather than on an engine session, and they are not among the methods +the agent chat may use. + ### Following the design A program that follows the open design (a renderer kept in step, a live link) asks diff --git a/xtask/src/web_offline_test.rs b/xtask/src/web_offline_test.rs index 42bcccf00..ad3f67e9b 100644 --- a/xtask/src/web_offline_test.rs +++ b/xtask/src/web_offline_test.rs @@ -177,6 +177,17 @@ const API_TEST: &str = r#"(async () => { check(settled.filter(r => r.status === 'rejected' && r.reason instanceof Error && r.reason.message.includes('pending')).length === 1, 'queue limit rejects excess work'); check((await app.inspect()).bodies.length === 1, 'API still works after rejected requests'); + // A host page keeps the design itself (#8517): out, changed, and back in its place. + const kept = await app.request('document.export'); + check(kept.format === 'json' && kept.dirty === true && kept.text.includes('Browser API box'), 'export gives the design as its file holds it'); + check((await app.request('document.saved', {revision: kept.revision})).dirty === false, 'the host saved that revision'); + await app.execute('solid.box', {length: 10, width: 10, height: 10, body_name: 'Second box'}); + await rejects(() => app.request('document.saved', {revision: kept.revision}), 'changed since'); + await rejects(() => app.request('document.import', {text: 'not a design'}), ''); + check((await app.inspect()).bodies.length === 2, 'a refused import leaves the design as it was'); + check((await app.request('document.import', {text: kept.text})).errors === 0, 'import evaluates the kept design'); + check((await app.inspect()).bodies.length === 1, 'import puts the kept design back'); + check((await app.request('document.export')).dirty === false, 'an imported design opens saved'); const ui = await app.request('ui.inspect'); check(ui.home === false && ui.viewport[2] > 600, 'model viewport is visible'); // #3431: a native Instant compiles for wasm but panics when exporting in the browser. @@ -224,7 +235,8 @@ const API_TEST: &str = r#"(async () => { await app.request('ui.documents', {action: 'switch', index: 0}); check((await app.execute('component.links')).links[0].component === linked.component, 'assembly remains in its tab'); return {commands: 'discovered', bodies: [0, 1, 0, 1], errors: 'rejected', queue: '256 completed, 1 rejected', - dxf: 'omit and dashed exported; dialog download checked', linked: 'source opened from browser storage'}; + dxf: 'omit and dashed exported; dialog download checked', linked: 'source opened from browser storage', + host: 'exported, saved and imported back'}; })()"#; /// Run the test; `required: false` (from `cargo xtask ci`) skips it when Chrome is missing.