diff --git a/Cargo.lock b/Cargo.lock index 9b7d41aea..3081e0fab 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4454,6 +4454,7 @@ dependencies = [ "serde_json", "solidcraft-engine", "solidcraft-ui-egui", + "url", "wasm-bindgen", "wasm-bindgen-futures", "web-sys", diff --git a/apps/solidcraft-web/Cargo.toml b/apps/solidcraft-web/Cargo.toml index 2cb8d37f1..d96c49f65 100644 --- a/apps/solidcraft-web/Cargo.toml +++ b/apps/solidcraft-web/Cargo.toml @@ -22,6 +22,7 @@ solidcraft-engine = { workspace = true } solidcraft-ui-egui = { workspace = true } egui = { workspace = true } log = { workspace = true } +url = "2" [target.'cfg(target_arch = "wasm32")'.dependencies] eframe = { workspace = true, features = ["default_fonts", "wgpu", "accesskit"] } @@ -34,5 +35,6 @@ web-sys = { version = "0.3", features = [ "FileSystemHandle", "FileSystemDirectoryHandle", "FileSystemFileHandle", "FileSystemGetFileOptions", "FileSystemWritableFileStream", "WritableStream", "File", "FileList", "Blob", "BlobPropertyBag", "Url", "HtmlAnchorElement", "HtmlInputElement", "Storage", "IdbFactory", "IdbDatabase", "IdbObjectStore", "IdbOpenDbRequest", "IdbRequest", "IdbTransaction", "IdbTransactionMode", + "Headers", "ReadableStream", "ReadableStreamDefaultReader", "BeforeUnloadEvent", "Event", "EventTarget", "KeyboardEvent", "Response", "MediaQueryList", "Gamepad", "Performance", ] } diff --git a/apps/solidcraft-web/src/linked.rs b/apps/solidcraft-web/src/linked.rs new file mode 100644 index 000000000..5a24cc46c --- /dev/null +++ b/apps/solidcraft-web/src/linked.rs @@ -0,0 +1,136 @@ +//! Bounded HTTPS downloads, handed to the normal design-open command as unsaved copies. +use std::{cell::RefCell, rc::Rc}; + +use js_sys::{Reflect, Uint8Array}; +use solidcraft_engine::io::vfs; +use solidcraft_ui_egui::{SolveApp, ui_kit}; +use wasm_bindgen::{JsCast as _, JsValue}; +use wasm_bindgen_futures::{JsFuture, spawn_local}; + +use crate::{check_download_size, design_url}; + +type Reply = Result<(String, Vec), String>; + +#[derive(Default)] +pub struct Download { + reply: Rc>>, + pending: Option<(String, Vec)>, +} + +impl Download { + pub fn start(url: Option<&str>, ctx: &egui::Context) -> Self { + let download = Self::default(); + if let Some(url) = url { + let url = url.to_owned(); + let slot = download.reply.clone(); + let ctx = ctx.clone(); + spawn_local(async move { + *slot.borrow_mut() = Some(fetch(&url).await); + ctx.request_repaint(); + }); + } + download + } + + pub fn tick(&mut self, app: &mut SolveApp, ctx: &egui::Context) { + if let Some(reply) = self.reply.borrow_mut().take() { + match reply { + Ok(file) => self.pending = Some(file), + Err(error) => app.set_status(format!("Could not open design link: {error}"), true), + } + } + if self.pending.is_none() || app.file_picker_busy() { + return; + } + if solidcraft_ui_egui::documents::any_dirty(app) { + let mut answer = None; + let closed = ui_kit::Window::new(egui::Id::new("open_link"), "status_warning", solidcraft_ui_egui::i18n::tr("web.open_link")) + .required() + .show_body(ctx, |ui| { + ui.label(solidcraft_ui_egui::i18n::tr("web.open_link_confirm")); + ui.horizontal(|ui| { + if ui_kit::button(ui, solidcraft_ui_egui::i18n::tr("ui.open"), ui_kit::Button::Normal).clicked() { + answer = Some(true); + } + if ui_kit::button(ui, solidcraft_ui_egui::i18n::tr("ui.cancel"), ui_kit::Button::Normal).clicked() { + answer = Some(false); + } + }); + }); + match answer { + Some(true) => {} + Some(false) => { + self.pending = None; + return; + } + None if closed => { + self.pending = None; + return; + } + None => return, + } + } + let Some((name, bytes)) = self.pending.take() else { return }; + // The extension selects the design loader even when the URL has no extension. + let path = "/linked/design.solidcraft"; + vfs::insert(path, bytes); + app.open_path(path); + if app.session.path.as_deref() == Some(path) { + app.session.path = None; + app.session.doc_mut().name = name; + app.session.mark_unsaved(); + } else { + app.set_status("Could not open design link: the downloaded file is not a valid SolidCraft design", true); + } + let _ = vfs::remove(path); + } +} + +async fn fetch(value: &str) -> Reply { + let url = design_url(value)?; + let name = url.path_segments().and_then(|mut segments| segments.next_back()).filter(|name| !name.is_empty()).unwrap_or("Design.solidcraft"); + let decoded = js_sys::decode_uri_component(name).ok().and_then(|name| name.as_string()).unwrap_or_else(|| name.to_owned()); + let name: String = decoded.strip_suffix(".solidcraft").unwrap_or(&decoded).chars().take(255).collect(); + let window = web_sys::window().ok_or("No browser window")?; + let response = JsFuture::from(window.fetch_with_str(url.as_str())).await.map_err(|_| "Network request failed or the host refused CORS access")?; + let response: web_sys::Response = response.dyn_into().map_err(|_| "Invalid download response")?; + design_url(&response.url()).map_err(|_| "Design redirected to a URL that does not use HTTPS")?; + if !response.ok() { + return Err(format!("HTTP {} {}", response.status(), response.status_text())); + } + let length = response + .headers() + .get("Content-Length") + .map_err(|_| "Cannot read download size")? + .map(|value| value.parse::().map_err(|_| "Invalid Content-Length")) + .transpose()?; + if let Some(length) = length { + check_download_size(0, length)?; + } + let stream = response.body().ok_or("Download has no body")?; + let reader: web_sys::ReadableStreamDefaultReader = stream.get_reader().dyn_into().map_err(|_| "Cannot read download stream")?; + let result = read(&reader).await; + if result.is_err() { + let _ = JsFuture::from(reader.cancel()).await; + } + // Fetch rejects interrupted HTTP bodies and decodes Content-Encoding. Content-Length + // can describe compressed bytes, so the streamed limit also checks the decoded size. + let bytes = result?; + Ok((name, bytes)) +} + +async fn read(reader: &web_sys::ReadableStreamDefaultReader) -> Result, String> { + let mut bytes = Vec::new(); + // Bound even a stream which keeps returning empty chunks. + for _ in 0..1_000_000 { + let chunk = JsFuture::from(reader.read()).await.map_err(|_| "Download interrupted")?; + if Reflect::get(&chunk, &JsValue::from_str("done")).map_err(|_| "Invalid download stream")?.as_bool() == Some(true) { + return Ok(bytes); + } + let value = Reflect::get(&chunk, &JsValue::from_str("value")).map_err(|_| "Invalid download chunk")?; + let chunk: Uint8Array = value.dyn_into().map_err(|_| "Invalid download bytes")?; + check_download_size(bytes.len(), u64::from(chunk.length()))?; + bytes.extend_from_slice(&chunk.to_vec()); + } + Err("Download returned too many chunks".into()) +} diff --git a/apps/solidcraft-web/src/main.rs b/apps/solidcraft-web/src/main.rs index c66b56bd0..8631aa93f 100644 --- a/apps/solidcraft-web/src/main.rs +++ b/apps/solidcraft-web/src/main.rs @@ -14,6 +14,8 @@ mod disk; mod files; #[cfg(target_arch = "wasm32")] mod install; +#[cfg(target_arch = "wasm32")] +mod linked; #[cfg(any(target_arch = "wasm32", test))] mod space_mouse; @@ -25,6 +27,61 @@ fn browser_switches_tabs(key: &str, ctrl: bool) -> bool { ctrl && key == "Tab" } +#[cfg(any(target_arch = "wasm32", test))] +fn query_flag(query: &str, name: &str) -> bool { + url::form_urlencoded::parse(query.trim_start_matches('?').as_bytes()).any(|(key, _)| key == name) +} + +/// Launch options use exact query keys; URL values are decoded only once. +#[cfg(any(target_arch = "wasm32", test))] +#[derive(Default, Debug)] +struct Launch { + open: Option, + embed: bool, +} + +#[cfg(any(target_arch = "wasm32", test))] +impl Launch { + fn parse(query: &str) -> Self { + let mut launch = Self::default(); + let mut embed = false; + 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" => embed = true, + _ => {} + } + } + launch.embed = embed && launch.open.is_some(); + launch + } + + fn persists(&self) -> bool { + !self.embed + } +} + +#[cfg(any(target_arch = "wasm32", test))] +fn design_url(value: &str) -> Result { + if value.len() > 16_384 { + return Err("Design URL is too long".into()); + } + let url = url::Url::parse(value).map_err(|_| "Invalid design URL")?; + if url.scheme() != "https" || url.host_str().is_none() || !url.username().is_empty() || url.password().is_some() { + return Err("Design links must use HTTPS without credentials".into()); + } + Ok(url) +} + +#[cfg(any(target_arch = "wasm32", test))] +fn check_download_size(current: usize, incoming: u64) -> Result<(), String> { + let cap = solidcraft_engine::io::MAX_DESIGN_BYTES as u64; + if current as u64 > cap || incoming > cap.saturating_sub(current as u64) { + return Err(format!("Design exceeds the {} MB size limit", cap / (1024 * 1024))); + } + Ok(()) +} + #[cfg(target_arch = "wasm32")] mod web { use std::rc::Rc; @@ -112,6 +169,9 @@ mod web { struct Shell { app: SolveApp, + launch: crate::Launch, + linked: crate::linked::Download, + full_url: Option, api: Api, files: Rc, /// When the last autosave was (seconds), and the revision it holds (none stored: `None`). @@ -137,6 +197,9 @@ mod web { impl Shell { /// Files from the computer, writes to store, messages and the autosave. fn files_tick(&mut self, ctx: &egui::Context) { + if !self.launch.persists() { + return; + } if self.files.ctx.borrow().is_none() { *self.files.ctx.borrow_mut() = Some(ctx.clone()); } @@ -526,19 +589,42 @@ mod web { if let Some(delay) = self.wheel_gestures.update(raw, now) { ctx.request_repaint_after(delay); } - files::take_drops(&self.files, raw); + if self.launch.persists() { + files::take_drops(&self.files, raw); + } else { + raw.dropped_files.clear(); + } // Before the app's own hook, which adds the control channel's events. self.space_mouse.raw_input_hook(ctx, self.app.preferences.space_mouse_enabled, raw); self.app.raw_input_hook(raw); } fn ui(&mut self, ui: &mut egui::Ui, _frame: &mut eframe::Frame) { + self.linked.tick(&mut self.app, ui.ctx()); + UNSAVED.with(|u| u.set(self.launch.persists() && solidcraft_ui_egui::documents::any_dirty(&self.app))); + if self.launch.embed { + ui_kit::Container::new(ui.ctx(), ui_kit::Surface::Chrome).edge("embed_header", ui_kit::Edge::Top).show(ui, |ui| { + if ui_kit::button(ui, solidcraft_ui_egui::i18n::tr("web.open_full"), ui_kit::Button::Normal).clicked() + && let (Some(window), Some(url)) = (web_sys::window(), &self.full_url) + { + let _ = window.open_with_url_and_target_and_features(url, "_blank", "noopener"); + } + }); + } self.app.ui(ui); let ctx = ui.ctx().clone(); - self.file_panel(&ctx); - self.recovery_prompt(&ctx); + if self.launch.persists() { + self.file_panel(&ctx); + self.recovery_prompt(&ctx); + } self.watch_text_for_font(&ctx); } + fn persist_egui_memory(&self) -> bool { + self.launch.persists() + } fn save(&mut self, storage: &mut dyn eframe::Storage) { + if !self.launch.persists() { + return; + } // Persist the user's own language, not a session-only English fallback. let saved = self.font.persisted_language(&self.app.preferences.language).to_owned(); let live = std::mem::replace(&mut self.app.preferences.language, saved); @@ -557,15 +643,15 @@ mod web { /// Render with WebGL2: asked for now (`?webgl`, remembered) or before (until `?webgpu`). fn webgl() -> bool { - let storage = web_sys::window().and_then(|w| w.local_storage().ok().flatten()); + let storage = crate::Launch::parse(&query()).persists().then(|| web_sys::window().and_then(|w| w.local_storage().ok().flatten())).flatten(); let q = query(); - if q.contains("webgl") { + if crate::query_flag(&q, "webgl") { if let Some(s) = &storage { let _ = s.set_item(WEBGL_KEY, "1"); } return true; } - if q.contains("webgpu") { + if crate::query_flag(&q, "webgpu") { if let Some(s) = &storage { let _ = s.remove_item(WEBGL_KEY); } @@ -591,7 +677,10 @@ mod web { eframe::WebLogger::init(log::LevelFilter::Info).ok(); wasm_bindgen_futures::spawn_local(async { let Some(window) = web_sys::window() else { return }; - ask_before_unload(&window); + let launch = crate::Launch::parse(&query()); + if launch.persists() { + ask_before_unload(&window); + } leave_tab_switching_to_browser(&window); let Some(document) = window.document() else { return }; let Some(canvas) = document.get_element_by_id(CANVAS_ID).and_then(|e| e.dyn_into::().ok()) else { @@ -611,10 +700,12 @@ mod web { Box::new(move |cc| { solidcraft_ui_egui::fonts::setup_fonts(&cc.egui_ctx); let files = Rc::new(Files::default()); - files::start(&files); + if launch.persists() { + files::start(&files); + } let (panel, opener, saver, shown) = (files.clone(), files.clone(), files.clone(), files.clone()); let (restorable, restorer) = (files.clone(), files.clone()); - let services = Services { + let services = if launch.embed { 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); otherwise, // and for inserting STEP or meshes, the browser's files window. @@ -648,26 +739,27 @@ mod web { browser_files: Some(Box::new(move || shown.panel.set(true))), install_app: Some(crate::install::service(&cc.egui_ctx)), ..Default::default() - }; + }}; // Thumbnails of saves and start-page cards. solidcraft_ui_egui::gpu::install_cpu_picture_renderer(); let (sender, receiver) = std::sync::mpsc::channel(); let mut app = SolveApp::new(Session::default(), services).with_control(receiver); - if let Some(p) = cc.storage.and_then(|s| solidcraft_ui_egui::prefs::stored(|k| s.get_string(k))) { + app.embedded = launch.embed; + if launch.persists() && let Some(p) = cc.storage.and_then(|s| solidcraft_ui_egui::prefs::stored(|k| s.get_string(k))) { app.load_prefs(&p); } if let Some(rs) = &cc.wgpu_render_state { // eframe's web painter has no stencil buffer. app.set_wgpu(rs, DEPTH_BITS, 0, 1); } - if query().contains("sample") { + if launch.open.is_none() && crate::query_flag(&query(), "sample") { if let Err(e) = app.session.run_script(&solidcraft_engine::sample::script()) { app.set_status(format!("sample: {e}"), true); } app.session.doc_mut().name = "Sample Plate".into(); app.session.mark_saved(); } - if !query().contains("sample") { + if launch.open.is_none() && !crate::query_flag(&query(), "sample") { // The empty design takes Units of new designs (#1205). The sample // part is built in millimetres and is left that way. solidcraft_ui_egui::prefs::apply_new_design(&mut app); @@ -676,8 +768,20 @@ mod web { } let api = Api::install(sender, cc.egui_ctx.clone()).map_err(|e| format!("SolidCraft browser API: {e:?}"))?; let font_language = app.preferences.language.clone(); + let linked = crate::linked::Download::start(launch.open.as_deref(), &cc.egui_ctx); + let full_url = window.location().href().ok().and_then(|value| url::Url::parse(&value).ok()).map(|mut url| { + url.set_query(None); + url.set_fragment(None); + if let Some(open) = &launch.open { + url.query_pairs_mut().append_pair("open", open); + } + url.to_string() + }); Ok(Box::new(Shell { app, + launch, + linked, + full_url, api, files, autosaved_at: f64::NEG_INFINITY, @@ -721,6 +825,48 @@ fn main() { mod tests { use super::*; + #[test] + fn link_query_decodes_once_and_embed_disables_persistence() { + assert!(!query_flag("?open=https://example.org/webgl?sample", "webgl")); + assert!(!query_flag("?open=https://example.org/webgl?sample", "sample")); + assert!(query_flag("?embed&webgl", "webgl")); + let launch = Launch::parse("?embed&open=https%3A%2F%2Fexample.org%2Farm.solidcraft%3Fx%3Da%2520b%26y%3D1"); + assert_eq!(launch.open.as_deref(), Some("https://example.org/arm.solidcraft?x=a%20b&y=1")); + assert!(launch.embed); + assert!(!launch.persists()); + assert!(!Launch::parse("?embed").embed); + assert!(!Launch::parse("?other=embed&reopen=https://example.org").embed); + assert!(Launch::parse("?open=https://example.org/a").persists()); + assert_eq!(Launch::parse("?open=first&open=second").open.as_deref(), Some("first")); + } + + #[test] + fn design_links_refuse_hostile_schemes_credentials_and_sizes() { + assert!(design_url("https://example.org/arm.solidcraft?download=1").is_ok()); + for value in [ + "http://example.org/a", + "data:application/json,{}", + "blob:https://example.org/a", + "javascript:alert(1)", + "/arm.solidcraft", + "https://user:secret@example.org/a", + "", + ] { + assert!(design_url(value).is_err(), "{value}"); + } + assert!(design_url(&format!("https://example.org/{}", "x".repeat(16_384))).is_err()); + assert!(design_url("http://redirect.example.org/a").is_err()); + + let cap = solidcraft_engine::io::MAX_DESIGN_BYTES; + assert!(check_download_size(0, cap as u64).is_ok()); + assert!(check_download_size(0, cap as u64 + 1).is_err()); + assert!(check_download_size(cap - 2, 2).is_ok()); + assert!(check_download_size(cap - 2, 3).is_err()); + assert!(check_download_size(0, u64::MAX).is_err()); + assert!(check_download_size(cap, 1).is_err()); + assert!(check_download_size(usize::MAX, 0).is_err()); + } + #[test] fn only_ctrl_tab_is_left_to_the_browser() { // Ctrl+Tab and Ctrl+Shift+Tab (the event's key is "Tab" either way) switch browser tabs. diff --git a/assets/locales/en.json b/assets/locales/en.json index 81019ef28..b90ba4694 100644 --- a/assets/locales/en.json +++ b/assets/locales/en.json @@ -3134,6 +3134,9 @@ "update.up_to_date": "SolidCraft is up to date.", "update.update_now": "Update now", "update.you_have": "You have {version}.", + "web.open_full": "Open in SolidCraft", + "web.open_link": "Open linked design?", + "web.open_link_confirm": "There are unsaved changes. Open the linked design in a new tab?", "↑ ↓ choose · Enter / Tab complete · Esc dismiss": "↑ ↓ choose · Enter / Tab complete · Esc dismiss", "↑ ↓ choose · Enter applies what you typed · Esc dismiss": "↑ ↓ choose · Enter applies what you typed · Esc dismiss" } diff --git a/assets/locales/ja.json b/assets/locales/ja.json index 12881aa74..9fae5f6c2 100644 --- a/assets/locales/ja.json +++ b/assets/locales/ja.json @@ -3134,6 +3134,9 @@ "update.up_to_date": "SolidCraft は最新です。", "update.update_now": "今すぐ更新", "update.you_have": "現在のバージョンは {version} です。", + "web.open_full": "SolidCraft で開く", + "web.open_link": "リンク先のデザインを開きますか?", + "web.open_link_confirm": "保存していない変更があります。リンク先のデザインを新しいタブで開きますか?", "↑ ↓ choose · Enter / Tab complete · Esc dismiss": "↑ ↓ 選択 · Enter / Tab 補完 · Esc 閉じる", "↑ ↓ choose · Enter applies what you typed · Esc dismiss": "↑ ↓ 選択 · Enter 入力どおりに適用 · Esc 閉じる" } diff --git a/assets/locales/zh.json b/assets/locales/zh.json index 38a877e57..d5c5d40b0 100644 --- a/assets/locales/zh.json +++ b/assets/locales/zh.json @@ -3134,6 +3134,9 @@ "update.up_to_date": "SolidCraft 已是最新版本。", "update.update_now": "立即更新", "update.you_have": "当前版本为 {version}。", + "web.open_full": "在 SolidCraft 中打开", + "web.open_link": "打开链接的设计?", + "web.open_link_confirm": "有未保存的更改。要在新标签页中打开链接的设计吗?", "↑ ↓ choose · Enter / Tab complete · Esc dismiss": "↑ ↓ 选择 · Enter / Tab 补全 · Esc 关闭", "↑ ↓ choose · Enter applies what you typed · Esc dismiss": "↑ ↓ 选择 · Enter 按原样应用 · Esc 关闭" } diff --git a/crates/ui-egui/src/lib.rs b/crates/ui-egui/src/lib.rs index b5d898a15..546600da1 100644 --- a/crates/ui-egui/src/lib.rs +++ b/crates/ui-egui/src/lib.rs @@ -383,6 +383,8 @@ pub struct Services { } pub struct SolveApp { + /// Compact browser embed: retain model panels and joint controls without application chrome. + pub embedded: bool, pub session: Session, pub ui: UiState, pub(crate) shell: shell::State, @@ -659,6 +661,7 @@ impl SolveApp { fitted: false, pending_fit: None, flat_view: Default::default(), + embedded: false, home: home::HomeState::default(), space_mouse: Default::default(), file_load: file_load::FileLoad::default(), @@ -1698,7 +1701,9 @@ impl SolveApp { if !keymap::capturing(self) { expression_complete::begin_frame(ctx); } - toolbar::shortcuts(self, ctx); + if !self.embedded { + toolbar::shortcuts(self, ctx); + } } recovery_ui::tick(self); open_elsewhere::tick(self, ctx); @@ -1800,11 +1805,19 @@ impl SolveApp { } fn cad_ui(&mut self, ui: &mut egui::Ui, report_input: &mut Option) { + if self.embedded { + self.ui.layout = shell::LayoutMode::Docked; + self.home.open = false; + self.ui.show_browser = true; + self.ui.show_timeline = true; + } self.ui.layout.publish(ui.ctx()); scenario::clear_handles(); self.poll_deferred(ui.ctx()); self.poll_delete_check(ui.ctx()); - toolbar::app_bar(self, ui); + if !self.embedded { + toolbar::app_bar(self, ui); + } issue_report::CadInput::block(self, ui, report_input); file_load::show(self, ui.ctx()); open_meshing::show(self, ui.ctx()); @@ -1831,7 +1844,7 @@ impl SolveApp { let show_timeline = self.ui.show_timeline && !render_workspace::active(self); let left_timeline = show_timeline && self.preferences.timeline_left; timeline_left::animate_folds(self, ui.ctx()); - if !floating { + if !floating && !self.embedded { toolbar::toolbar(self, ui); } theme::TabAccent::publish(self, ui.ctx()); diff --git a/crates/ui-egui/src/shell_tests.rs b/crates/ui-egui/src/shell_tests.rs index 2ea1fd301..0f68765bd 100644 --- a/crates/ui-egui/src/shell_tests.rs +++ b/crates/ui-egui/src/shell_tests.rs @@ -662,3 +662,21 @@ fn ribbon_labels_are_saved_independently_and_icon_only_commands_remain_reachable } assert!(crate::prefs::lenient(&json!({})).ribbon_labels); } + +#[test] +fn embed_keeps_model_panels_without_application_chrome() { + let mut h = Harness::new(); + h.app.embedded = true; + h.app.home.show(h.app.session.revision); + h.app.ui.show_browser = false; + h.app.ui.show_timeline = false; + h.app.run("solid.box", json!({"length":40,"width":30,"height":20})).unwrap(); + h.settle(); + assert!(!h.app.home.open); + assert_eq!(h.app.ui.layout, LayoutMode::Docked); + assert!(h.app.ui.show_browser && h.app.ui.show_timeline); + assert!(rect_of("toolbar").is_none()); + assert!(rect_of("ribbon:workspace").is_none()); + assert!(rect_of("browser:card").is_some()); + assert!(h.app.viewport.rect.is_some()); +} diff --git a/docs/book/src/guide/getting-started.md b/docs/book/src/guide/getting-started.md index ca1c1b382..ab474a60b 100644 --- a/docs/book/src/guide/getting-started.md +++ b/docs/book/src/guide/getting-started.md @@ -116,6 +116,27 @@ cd apps/solidcraft-web && trunk serve --release --no-autoreload Offline use needs `--no-autoreload`: Trunk's live reload changes the page as it serves it, so it no longer matches the build the browser would keep. Debug builds (`trunk serve`) never keep a copy. +### Design links and embeds + +Use `?open=` to open a hosted `.solidcraft` design as an unsaved +copy, including its history, constraints, and joints. Encode the URL with +`encodeURIComponent` when it contains query parameters. The host must allow CORS +requests from the app's origin. Downloads, including redirected URLs, must use HTTPS +and fit within the File > Open design size limit. Failed downloads and invalid designs +show an error and leave the empty design. + +Add `embed` to show the viewport, timeline, browser tree, and joint controls without +the ribbon, file menus, or start page: + +```html + +``` + +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. + ### Self-hosting with Docker The web app is also a container image, `ghcr.io/tangency-labs/solidcraft-web`, for Linux on x86_64