From d628abb7b019cbb9e2230b93d4f2c8be4774b98f Mon Sep 17 00:00:00 2001
From: Helen Kwok <107752876+helenkwok@users.noreply.github.com>
Date: Mon, 26 Oct 2026 08:53:11 +1030
Subject: [PATCH 1/3] Web: page host mode, so a page can host GridCraft in its
 own document (#2592)

data-host="page" on the canvas opts a page that loads the module into its own document into the host bridge. The ?host=parent messages travel as non-bubbling CustomEvents on the canvas; Bridge holds a Transport (Parent or Page) and shares the save, dirty and ready logic. Unframed ?host=parent still gets no bridge. Hosting guide documents both modes.
---
 apps/gridcraft-web/Cargo.toml      |   2 +-
 apps/gridcraft-web/src/host.rs     | 184 ++++++++++++++++++++++-------
 apps/gridcraft-web/src/hostmode.rs |  45 +++++++
 apps/gridcraft-web/src/main.rs     |  12 +-
 apps/gridcraft-web/src/web.rs      |  15 ++-
 packaging/web/README.md            |  72 +++++++++++
 6 files changed, 279 insertions(+), 51 deletions(-)
 create mode 100644 apps/gridcraft-web/src/hostmode.rs

diff --git a/apps/gridcraft-web/Cargo.toml b/apps/gridcraft-web/Cargo.toml
index 41059d379..e384ffe09 100644
--- a/apps/gridcraft-web/Cargo.toml
+++ b/apps/gridcraft-web/Cargo.toml
@@ -26,4 +26,4 @@ rfd = { workspace = true }
 wasm-bindgen = "0.2"
 wasm-bindgen-futures = "0.4"
 js-sys = "0.3"
-web-sys = { version = "0.3", features = ["Window", "Document", "Element", "HtmlElement", "HtmlCanvasElement", "HtmlAnchorElement", "HtmlIFrameElement", "Blob", "BlobPropertyBag", "Url", "Location", "CssStyleDeclaration", "Clipboard", "ClipboardItem", "Navigator", "MessageEvent", "UrlSearchParams", "AddEventListenerOptions", "Storage"] }
+web-sys = { version = "0.3", features = ["Window", "Document", "Element", "Event", "EventTarget", "HtmlElement", "HtmlCanvasElement", "HtmlAnchorElement", "HtmlIFrameElement", "Blob", "BlobPropertyBag", "Url", "Location", "CssStyleDeclaration", "Clipboard", "ClipboardItem", "Navigator", "MessageEvent", "UrlSearchParams", "AddEventListenerOptions", "Storage", "CustomEvent", "CustomEventInit"] }
diff --git a/apps/gridcraft-web/src/host.rs b/apps/gridcraft-web/src/host.rs
index 2286023e5..8130d2682 100644
--- a/apps/gridcraft-web/src/host.rs
+++ b/apps/gridcraft-web/src/host.rs
@@ -1,5 +1,10 @@
-//! The `postMessage` bridge to a same-origin parent page (`?host=parent`), for pages that embed
-//! GridCraft in an `<iframe>` (such as a Nextcloud app). Messages are plain objects with a `type`:
+//! Host modes: a page that runs GridCraft (as an iframe, or in its own document) opens workbooks
+//! in it and stores what it saves instead of the browser downloading.
+//!
+//! ## `?host=parent` — an `<iframe>` (such as a Nextcloud app)
+//!
+//! The framing page and GridCraft talk over `postMessage` between same-origin windows. Messages
+//! are plain objects with a `type`:
 //!
 //! - `gridcraft:ready` (to the parent): `{ version }`, the app is listening; send a file now.
 //! - `gridcraft:open` (from the parent): `{ name, bytes }`, bytes an `ArrayBuffer` or
@@ -10,8 +15,21 @@
 //! - `gridcraft:dirty` (to the parent): `{ dirty }` whenever unsaved changes appear or go away.
 //! - `gridcraft:failed` (to the parent): `{ error }` when the app couldn't start.
 //!
-//! Only the parent window on the page's own origin is heard or answered. In host mode the page
-//! starts with an empty workbook instead of a sample, and the parent guards leaving the page.
+//! Only the parent window on the page's own origin is heard or answered.
+//!
+//! ## `data-host="page"` — the page's own document
+//!
+//! A page that loads the module into its own document (its own `<canvas id="gridcraft_canvas">`
+//! with `data-host="page"`, no iframe) gets the same behaviour over DOM `CustomEvent`s on the
+//! canvas instead of `postMessage`: the same four events outward (`ready`, `save`, `dirty`,
+//! `failed`, with the message fields as the event's `detail`), and the page dispatches
+//! `gridcraft:open` on the canvas with `detail: { name, bytes }` to open a workbook. Events don't
+//! bubble, so two editors on one page can't hear each other, and the canvas is the only target
+//! GridCraft listens on.
+//!
+//! In both host modes the page starts with an empty workbook instead of a sample, saves and PDF
+//! exports are handed to the page rather than downloaded, and `?author=` names the user for new
+//! notes and comments.
 
 use std::cell::{Cell, RefCell};
 use std::rc::Rc;
@@ -21,26 +39,69 @@ use wasm_bindgen::JsCast as _;
 use wasm_bindgen::JsValue;
 use wasm_bindgen::closure::Closure;
 
-/// Saving one of these hands the whole workbook to the parent, which stores it: the workbook
+use crate::hostmode::open_name;
+
+/// Saving one of these hands the whole workbook to the host, which stores it: the workbook
 /// counts as saved under that name, as it would after Save on the desktop.
 const WORKBOOK_EXTS: &[&str] = &["xlsx"];
 
 /// The longest user name taken from `?author=`.
 const MAX_AUTHOR_CHARS: usize = 200;
 
+/// How a host page is reached. The modes behave the same; they differ only in how an event goes
+/// out ([`Transport::send`]) and how an open request comes in ([`Bridge::listen`]).
+#[derive(Clone)]
+enum Transport {
+    /// `?host=parent`: `postMessage` between same-origin windows.
+    Parent { window: web_sys::Window, parent: web_sys::Window, origin: String },
+    /// `data-host="page"`: DOM `CustomEvent`s on the editor's own canvas.
+    Page { canvas: web_sys::HtmlCanvasElement },
+}
+
+impl Transport {
+    /// Hand an event to the host. In parent mode this is a `postMessage` with a `type` field; in
+    /// page mode a `CustomEvent` of that name on the canvas, whose `detail` holds the fields and
+    /// which never bubbles (two editors on one page must not hear each other).
+    fn send(&self, event: &str, fields: &[(&str, JsValue)], transfer: Option<&js_sys::ArrayBuffer>) -> Result<(), String> {
+        match self {
+            Transport::Parent { parent, origin, .. } => {
+                let mut message_fields = Vec::with_capacity(fields.len() + 1);
+                message_fields.push(("type", JsValue::from_str(event)));
+                message_fields.extend_from_slice(fields);
+                let message = message(&message_fields).ok_or_else(|| "couldn't build the message".to_string())?;
+                let sent = match transfer {
+                    Some(buffer) => parent.post_message_with_transfer(&message, origin, &js_sys::Array::of1(buffer)),
+                    // `None` is only ever passed for the parent mode's small events; the page mode
+                    // can't transfer anyway (below).
+                    None => parent.post_message(&message, origin),
+                };
+                sent.map_err(|e| js_error(&e, "couldn't post the message"))
+            }
+            Transport::Page { canvas } => {
+                let detail = message(fields).ok_or_else(|| "couldn't build the event detail".to_string())?;
+                let init = web_sys::CustomEventInit::new();
+                init.set_bubbles(false);
+                init.set_detail(&detail);
+                let custom = web_sys::CustomEvent::new_with_event_init_dict(event, &init).map_err(|e| js_error(&e, "couldn't create the event"))?;
+                canvas.dispatch_event(&custom).map_err(|e| js_error(&e, "couldn't dispatch the event"))?;
+                Ok(())
+            }
+        }
+    }
+}
+
 #[derive(Clone)]
 pub struct Bridge {
-    window: web_sys::Window,
-    parent: web_sys::Window,
-    origin: String,
-    /// Names of the files handed to the parent since the last frame.
+    transport: Transport,
+    /// Names of the files handed to the host since the last frame.
     saved: Rc<RefCell<Vec<String>>>,
-    /// The unsaved-changes state last reported to the parent.
+    /// The unsaved-changes state last reported to the host.
     reported: Rc<Cell<Option<bool>>>,
 }
 
 impl Bridge {
-    /// `None` when the page isn't framed (there is no parent to talk to).
+    /// The parent bridge for `?host=parent`; `None` when the page isn't framed (there is no
+    /// parent to talk to), so opening that URL directly stays the normal app with downloads.
     pub fn new() -> Option<Self> {
         let window = web_sys::window()?;
         let parent = window.parent().ok().flatten()?;
@@ -48,10 +109,16 @@ impl Bridge {
             return None;
         }
         let origin = window.location().origin().ok()?;
-        Some(Self { window, parent, origin, saved: Rc::default(), reported: Rc::default() })
+        Some(Self { transport: Transport::Parent { window, parent, origin }, saved: Rc::default(), reported: Rc::default() })
     }
 
-    /// Send saved and exported files to the parent instead of downloading them, and hear files
+    /// The page bridge for `data-host="page"`: the host page runs GridCraft in its own document
+    /// and hears the editor's DOM `CustomEvent`s on this canvas.
+    pub fn for_page(canvas: &web_sys::HtmlCanvasElement) -> Self {
+        Self { transport: Transport::Page { canvas: canvas.clone() }, saved: Rc::default(), reported: Rc::default() }
+    }
+
+    /// Send saved and exported files to the host instead of downloading them, and hear files
     /// from it.
     pub fn connect(&self, services: &mut Services, inbox: Inbox, ctx: egui::Context) {
         self.listen(inbox, ctx);
@@ -72,15 +139,15 @@ impl Bridge {
     }
 
     pub fn post_ready(&self) {
-        self.send(&[("type", "gridcraft:ready".into()), ("version", env!("CARGO_PKG_VERSION").into())]);
+        let _ = self.transport.send("gridcraft:ready", &[("version", env!("CARGO_PKG_VERSION").into())], None);
     }
 
     pub fn post_failed(&self, error: &str) {
-        self.send(&[("type", "gridcraft:failed".into()), ("error", error.into())]);
+        let _ = self.transport.send("gridcraft:failed", &[("error", error.into())], None);
     }
 
-    /// After each frame: a workbook handed to the parent this frame counts as saved under the
-    /// name it was saved as, and the parent hears when unsaved changes appear or go away.
+    /// After each frame: a workbook handed to the host this frame counts as saved under the
+    /// name it was saved as, and the host hears when unsaved changes appear or go away.
     pub fn sync(&self, app: &mut SheetApp) {
         let saved = std::mem::take(&mut *self.saved.borrow_mut());
         if let Some(name) = saved.iter().rev().find(|name| is_workbook(name))
@@ -92,55 +159,81 @@ impl Bridge {
             }
         }
         let dirty = app.session.documents().iter().any(|d| d.is_dirty());
-        if self.reported.get() != Some(dirty) && self.send(&[("type", "gridcraft:dirty".into()), ("dirty", dirty.into())]) {
+        if self.reported.get() != Some(dirty) && self.transport.send("gridcraft:dirty", &[("dirty", dirty.into())], None).is_ok() {
             self.reported.set(Some(dirty));
         }
     }
 
     fn post_save(&self, path: &str, bytes: &[u8]) -> Result<(), String> {
-        let name = std::path::Path::new(path).file_name().map(|n| n.to_string_lossy().to_string()).unwrap_or_else(|| path.to_string());
+        let name = file_name(path);
+        // `gridcraft:save` carries the bytes as an `ArrayBuffer`; the parent bridge transfers it.
         let buffer = js_sys::Uint8Array::from(bytes).buffer();
-        let message = message(&[("type", "gridcraft:save".into()), ("name", name.as_str().into()), ("bytes", buffer.clone().into())])
-            .ok_or_else(|| "couldn't build the message".to_string())?;
-        self.parent
-            .post_message_with_transfer(&message, &self.origin, &js_sys::Array::of1(&buffer))
-            .map_err(|e| e.as_string().unwrap_or_else(|| format!("{e:?}")))?;
+        self.transport.send("gridcraft:save", &[("name", name.as_str().into()), ("bytes", buffer.clone().into())], Some(&buffer))?;
         self.saved.borrow_mut().push(name);
         Ok(())
     }
 
     fn listen(&self, inbox: Inbox, ctx: egui::Context) {
-        let parent = self.parent.clone();
-        let origin = self.origin.clone();
-        let on_message = Closure::<dyn FnMut(web_sys::MessageEvent)>::new(move |event: web_sys::MessageEvent| {
-            if event.origin() != origin || !event.source().is_some_and(|s| js_sys::Object::is(&s, &parent)) {
-                return;
+        match &self.transport {
+            Transport::Parent { window, parent, origin } => {
+                let parent = parent.clone();
+                let origin = origin.clone();
+                let on_message = Closure::<dyn FnMut(web_sys::MessageEvent)>::new(move |event: web_sys::MessageEvent| {
+                    if event.origin() != origin || !event.source().is_some_and(|s| js_sys::Object::is(&s, &parent)) {
+                        return;
+                    }
+                    let data = event.data();
+                    if string(&data, "type").as_deref() != Some("gridcraft:open") {
+                        return;
+                    }
+                    deliver_open(&inbox, &ctx, &data);
+                });
+                if window.add_event_listener_with_callback("message", on_message.as_ref().unchecked_ref()).is_ok() {
+                    // The listener lives as long as the page.
+                    on_message.forget();
+                }
             }
-            let data = event.data();
-            if string(&data, "type").as_deref() != Some("gridcraft:open") {
-                return;
+            Transport::Page { canvas } => {
+                let on_open = Closure::<dyn FnMut(web_sys::Event)>::new(move |event: web_sys::Event| {
+                    let Some(open) = event.dyn_ref::<web_sys::CustomEvent>() else { return };
+                    let detail = open.detail();
+                    deliver_open(&inbox, &ctx, &detail);
+                });
+                if canvas.add_event_listener_with_callback("gridcraft:open", on_open.as_ref().unchecked_ref()).is_ok() {
+                    // The listener lives as long as the page.
+                    on_open.forget();
+                }
             }
-            let name = string(&data, "name").filter(|n| !n.trim().is_empty()).unwrap_or_else(|| "Book.xlsx".to_string());
-            let Some(bytes) = bytes(&data) else { return };
-            inbox.lock().unwrap_or_else(|e| e.into_inner()).push((name, bytes));
-            ctx.request_repaint();
-        });
-        if self.window.add_event_listener_with_callback("message", on_message.as_ref().unchecked_ref()).is_ok() {
-            // The listener lives as long as the page.
-            on_message.forget();
         }
     }
+}
 
-    /// Post a message to the parent; false if it couldn't be sent.
-    fn send(&self, fields: &[(&str, JsValue)]) -> bool {
-        message(fields).is_some_and(|m| self.parent.post_message(&m, &self.origin).is_ok())
+/// The file an open message or event carries, pushed onto the inbox for the next frame, like a
+/// dropped file.
+fn deliver_open(inbox: &Inbox, ctx: &egui::Context, data: &JsValue) {
+    if let Some((name, bytes)) = open_payload(data) {
+        inbox.lock().unwrap_or_else(|e| e.into_inner()).push((name, bytes));
+        ctx.request_repaint();
     }
 }
 
+/// The file an open message or event carries: a usable name and the bytes.
+fn open_payload(data: &JsValue) -> Option<(String, Vec<u8>)> {
+    let name = open_name(string(data, "name").as_deref());
+    let bytes = bytes(data)?;
+    Some((name, bytes))
+}
+
 fn is_workbook(name: &str) -> bool {
     name.rsplit_once('.').is_some_and(|(_, ext)| WORKBOOK_EXTS.iter().any(|e| ext.eq_ignore_ascii_case(e)))
 }
 
+fn file_name(path: &str) -> String {
+    std::path::Path::new(path).file_name().map(|n| n.to_string_lossy().to_string()).unwrap_or_else(|| path.to_string())
+}
+
+/// A message object or `CustomEvent` detail with the given fields, or `None` if one couldn't be
+/// set.
 fn message(fields: &[(&str, JsValue)]) -> Option<js_sys::Object> {
     let m = js_sys::Object::new();
     for (key, value) in fields {
@@ -164,3 +257,8 @@ fn bytes(data: &JsValue) -> Option<Vec<u8>> {
         None
     }
 }
+
+/// A `JsValue` error as a string, after `what` went wrong.
+fn js_error(e: &JsValue, what: &str) -> String {
+    format!("{what}: {}", e.as_string().unwrap_or_else(|| format!("{e:?}")))
+}
diff --git a/apps/gridcraft-web/src/hostmode.rs b/apps/gridcraft-web/src/hostmode.rs
new file mode 100644
index 000000000..aaf4c12aa
--- /dev/null
+++ b/apps/gridcraft-web/src/hostmode.rs
@@ -0,0 +1,45 @@
+//! Pure host-mode rules, shared by the bridge ([`crate::host`]) and testable without a browser
+//! (like [`crate::prefs`]): what opts a page into hosting GridCraft in its own document, and the
+//! name the bridge fills in when a host's open request has none.
+
+/// The one `data-host` value that opts a page in: the exact string `"page"`.
+pub const PAGE_HOST: &str = "page";
+
+/// The file name used when an open request carries no usable one.
+pub const DEFAULT_OPEN_NAME: &str = "Book.xlsx";
+
+/// Does this `data-host` value ask for page host mode? Only the exact value [`PAGE_HOST`] counts;
+/// anything else is ignored, so the page host mode stays opt-in.
+pub fn page_host_requested(data_host: Option<&str>) -> bool {
+    data_host == Some(PAGE_HOST)
+}
+
+/// A usable file name for an open request: the host's name when it isn't blank, else the
+/// [`DEFAULT_OPEN_NAME`].
+pub fn open_name(name: Option<&str>) -> String {
+    name.filter(|n| !n.trim().is_empty()).unwrap_or(DEFAULT_OPEN_NAME).to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn only_the_exact_page_value_opts_in() {
+        assert!(page_host_requested(Some("page")));
+        assert!(!page_host_requested(Some("Page")));
+        assert!(!page_host_requested(Some(" page")));
+        assert!(!page_host_requested(Some("parent")));
+        assert!(!page_host_requested(Some("")));
+        assert!(!page_host_requested(None));
+    }
+
+    #[test]
+    fn open_names_fall_back_to_the_default_when_blank() {
+        assert_eq!(open_name(Some("Budget.xlsx")), "Budget.xlsx");
+        assert_eq!(open_name(Some(" Sheet2!Book.xlsx ")), " Sheet2!Book.xlsx ");
+        assert_eq!(open_name(Some("")), DEFAULT_OPEN_NAME);
+        assert_eq!(open_name(Some("   ")), DEFAULT_OPEN_NAME);
+        assert_eq!(open_name(None), DEFAULT_OPEN_NAME);
+    }
+}
diff --git a/apps/gridcraft-web/src/main.rs b/apps/gridcraft-web/src/main.rs
index 68bee92e6..2c701feb4 100644
--- a/apps/gridcraft-web/src/main.rs
+++ b/apps/gridcraft-web/src/main.rs
@@ -10,15 +10,19 @@
 //!
 //! URL query flags: `?webgl` forces WebGL2; `?sample=sales|budget|grades` opens a sample;
 //! `?host=parent` (inside an `<iframe>`) talks to a same-origin parent page instead: it sends the
-//! workbook to open and stores what GridCraft saves (`host`), and `&author=` names the user for
-//! notes and comments. `?chrome=none|notitlebar|nofiletab` leaves the title bar and/or the File tab
-//! undrawn for a host that embeds the sheet in its own window (see `Chrome`). Preferences (theme,
-//! interface size, editing options…) are kept in `localStorage` (`prefs`).
+//! workbook to open and stores what GridCraft saves (`host`). A page can host GridCraft in its
+//! own document (no iframe) with `data-host="page"` on the canvas, talking over DOM `CustomEvent`s
+//! on the canvas. `&author=` names the user for notes and comments in either host mode.
+//! `?chrome=none|notitlebar|nofiletab` leaves the title bar and/or the File tab undrawn for a host
+//! that embeds the sheet in its own window (see `Chrome`). Preferences (theme, interface size,
+//! editing options…) are kept in `localStorage` (`prefs`).
 #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
 
 #[cfg(target_arch = "wasm32")]
 mod host;
 #[cfg(any(target_arch = "wasm32", test))]
+mod hostmode;
+#[cfg(any(target_arch = "wasm32", test))]
 mod prefs;
 #[cfg(target_arch = "wasm32")]
 mod web;
diff --git a/apps/gridcraft-web/src/web.rs b/apps/gridcraft-web/src/web.rs
index 33dc84936..868b7e641 100644
--- a/apps/gridcraft-web/src/web.rs
+++ b/apps/gridcraft-web/src/web.rs
@@ -38,8 +38,17 @@ pub fn start() {
             create.instance_descriptor.backends = eframe::wgpu::Backends::GL;
         }
         // `?host=parent`: a same-origin page framing GridCraft (such as a Nextcloud app) opens
-        // workbooks in it and stores what it saves (`host`).
-        let bridge = if query_param("host").as_deref() == Some("parent") { crate::host::Bridge::new() } else { None };
+        // workbooks in it and stores what it saves (`host`). Unframed there is no parent, so that
+        // URL on its own stays the normal app with downloads. `data-host="page"` on the canvas
+        // opts a page in instead: it runs GridCraft in its own document and talks over DOM
+        // `CustomEvent`s on the canvas (`host`).
+        let bridge = if query_param("host").as_deref() == Some("parent") {
+            crate::host::Bridge::new()
+        } else if crate::hostmode::page_host_requested(canvas.get_attribute("data-host").as_deref()) {
+            Some(crate::host::Bridge::for_page(&canvas))
+        } else {
+            None
+        };
         let app_bridge = bridge.clone();
         let result = eframe::WebRunner::new()
             .start(
@@ -48,7 +57,7 @@ pub fn start() {
                 Box::new(move |cc| {
                     let inbox: Inbox = Inbox::default();
                     let mut session = Session::new();
-                    // In host mode the parent sends the workbook to edit; no sample meanwhile.
+                    // In host mode the host sends the workbook to edit; no sample meanwhile.
                     let q = if app_bridge.is_some() { String::new() } else { query() };
                     if let Some(name) = q.split(['?', '&']).find_map(|kv| kv.strip_prefix("sample=")) {
                         let _ = session.execute("file.new", serde_json::json!({"sample": name}));
diff --git a/packaging/web/README.md b/packaging/web/README.md
index 21c7a731b..46a54842d 100644
--- a/packaging/web/README.md
+++ b/packaging/web/README.md
@@ -1,5 +1,6 @@
 # Hosting GridCraft for the web
 
+
 `gridcraft-web-<version>.zip` (from the GitHub release, or `packaging/web/package.sh`) holds a
 static site in `gridcraft-web-<version>/`:
 
@@ -77,6 +78,77 @@ Local test: `python3 -m http.server 8765` inside the folder, then open http://lo
   one. Use them when the host window already shows the file name and owns the files, so the sheet's
   own Open or Save As cannot replace what the host thinks is open. Everything stays on by default.
 
+### The parent bridge (`?host=parent`)
+
+A page framing GridCraft in a **same-origin** iframe can add `?host=parent` to the iframe's URL
+(`https://example.com/gridcraft/?host=parent`) and have GridCraft hand its files over instead of
+downloading them. The two sides talk `postMessage` with plain window messages that carry a
+`type`:
+
+| Message | Direction | Fields |
+|---|---|---|
+| `gridcraft:ready` | app → page | `version`: the app is listening; send a file now |
+| `gridcraft:open` | page → app | `name`, `bytes` (an `ArrayBuffer` or `Uint8Array`): open like File › Open |
+| `gridcraft:save` | app → page | `name`, `bytes` (a transferred `ArrayBuffer`): every file the app would otherwise download (Save, Save As, Export as PDF). The page stores it and reports failures itself. |
+| `gridcraft:dirty` | app → page | `dirty`: unsaved changes appeared or went away |
+| `gridcraft:failed` | app → page | `error`: the app couldn't start |
+
+In host mode the app starts with an empty workbook instead of a sample, so the framing page
+should guard leaving the page while changes are unsaved. `&author=` names the user for the
+notes and comments the app creates. Opening `?host=parent` outside an iframe gives the normal
+app with downloads.
+
+### Embedding without an iframe (page host mode)
+
+A page that loads the GridCraft module into its own document — its own `<canvas
+id="gridcraft_canvas">` inside a component, sized to a box beside the page's own header and
+controls — opts in with `data-host="page"` on that canvas. The behaviour is the same as the
+parent bridge, except the transport is DOM `CustomEvent`s on the canvas instead of
+`postMessage`: the app dispatches `gridcraft:ready`, `gridcraft:save`, `gridcraft:dirty` and
+`gridcraft:failed` on the canvas with the message fields above as the event's `detail`, and the
+page dispatches `gridcraft:open` on the canvas with `detail: { name, bytes }` to open a
+workbook. Events don't bubble, so two editors on one page can't hear each other; listen on the
+canvas itself.
+
+```html
+<canvas id="gridcraft_canvas" data-host="page" style="width: 100%; height: 600px; border: 0;"></canvas>
+```
+
+```js
+import init from "./gridcraft-web-<hash>.js"; // the wasm-bindgen glue shipped with the app
+
+// Listen first: the app announces itself while `init` runs.
+const canvas = document.getElementById("gridcraft_canvas");
+
+canvas.addEventListener("gridcraft:ready", async () => {
+  // Open a workbook of the page's own, as with File › Open.
+  const bytes = await workbookBytes(); // an ArrayBuffer or Uint8Array
+  canvas.dispatchEvent(new CustomEvent("gridcraft:open", {
+    detail: { name: "Budget.xlsx", bytes },
+  }));
+});
+
+// Every file GridCraft would otherwise download (Save, Save As, Export as PDF) arrives here.
+canvas.addEventListener("gridcraft:save", (event) => {
+  const { name, bytes } = event.detail; // bytes is an ArrayBuffer
+  storeFile(name, bytes);
+});
+
+canvas.addEventListener("gridcraft:dirty", (event) => {
+  warnBeforeLeaving(event.detail.dirty);
+});
+canvas.addEventListener("gridcraft:failed", (event) => {
+  showError(event.detail.error);
+});
+
+await init({ module_or_path: "./gridcraft-web-<hash>_bg.wasm" });
+```
+
+As with the parent bridge, the app starts with an empty workbook instead of a sample, and
+`?author=` on the page's URL names the user for new notes and comments. The `data-host` value
+must be exactly `page`; anything else is ignored, and the app runs as a standalone page with
+downloads.
+
 ## Renderer selection
 
 GridCraft's web build is the same egui app as the desktop one, compiled to wasm

From bf6bee500af7d133c6a8c8b3304358c43e305fa2 Mon Sep 17 00:00:00 2001
From: Helen Kwok <107752876+helenkwok@users.noreply.github.com>
Date: Sun, 1 Nov 2026 17:30:54 +0800
Subject: [PATCH 2/3] web host mode: refuse an oversized host file before
 copying it, cap the name, and document trust and limits

---
 apps/gridcraft-web/src/host.rs | 22 +++++++++++++++++-----
 packaging/web/README.md        |  6 ++++++
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/apps/gridcraft-web/src/host.rs b/apps/gridcraft-web/src/host.rs
index 8130d2682..0ab4fefbb 100644
--- a/apps/gridcraft-web/src/host.rs
+++ b/apps/gridcraft-web/src/host.rs
@@ -45,6 +45,12 @@ use crate::hostmode::open_name;
 /// counts as saved under that name, as it would after Save on the desktop.
 const WORKBOOK_EXTS: &[&str] = &["xlsx"];
 
+/// The largest file the host may hand over to open, checked before it is copied (the app's own readers have their own limits).
+const MAX_OPEN_BYTES: u64 = 512 << 20;
+
+/// The longest file name taken from the host.
+const MAX_NAME_CHARS: usize = 255;
+
 /// The longest user name taken from `?author=`.
 const MAX_AUTHOR_CHARS: usize = 200;
 
@@ -219,7 +225,7 @@ fn deliver_open(inbox: &Inbox, ctx: &egui::Context, data: &JsValue) {
 
 /// The file an open message or event carries: a usable name and the bytes.
 fn open_payload(data: &JsValue) -> Option<(String, Vec<u8>)> {
-    let name = open_name(string(data, "name").as_deref());
+    let name: String = open_name(string(data, "name").as_deref()).chars().take(MAX_NAME_CHARS).collect();
     let bytes = bytes(data)?;
     Some((name, bytes))
 }
@@ -249,13 +255,19 @@ fn string(data: &JsValue, key: &str) -> Option<String> {
 /// `bytes` as an `ArrayBuffer` or `Uint8Array`.
 fn bytes(data: &JsValue) -> Option<Vec<u8>> {
     let bytes = js_sys::Reflect::get(data, &JsValue::from_str("bytes")).ok()?;
-    if let Some(array) = bytes.dyn_ref::<js_sys::Uint8Array>() {
-        Some(array.to_vec())
+    let view = if let Some(array) = bytes.dyn_ref::<js_sys::Uint8Array>() {
+        array.clone()
     } else if bytes.is_instance_of::<js_sys::ArrayBuffer>() {
-        Some(js_sys::Uint8Array::new(&bytes).to_vec())
+        js_sys::Uint8Array::new(&bytes)
     } else {
-        None
+        return None;
+    };
+    // A file from the host is untrusted input: refuse an oversized one before copying it into the app's memory.
+    if u64::from(view.length()) > MAX_OPEN_BYTES {
+        log::warn!("host file is {} bytes, over the {} MiB host open limit; not opened", view.length(), MAX_OPEN_BYTES >> 20);
+        return None;
     }
+    Some(view.to_vec())
 }
 
 /// A `JsValue` error as a string, after `what` went wrong.
diff --git a/packaging/web/README.md b/packaging/web/README.md
index 46a54842d..d4e85a765 100644
--- a/packaging/web/README.md
+++ b/packaging/web/README.md
@@ -149,6 +149,12 @@ As with the parent bridge, the app starts with an empty workbook instead of a sa
 must be exactly `page`; anything else is ignored, and the app runs as a standalone page with
 downloads.
 
+### Trust and limits
+
+- **Who is trusted.** In page host mode the page and GridCraft share one document, so any script on the page can drive the app: open files in it and receive what it saves. Use this mode only for a page you control. The iframe mode (`?host=parent`) answers only the parent window, on the page's own origin.
+- **Files from the host are untrusted input.** An opened file goes through the same reading as one picked with File ▸ Open or dropped on the window, with the same format limits; before it is copied into the app's memory, its size is checked against the host open limit (512 MiB) and a larger file is refused, and a name is cut to 255 characters.
+- **The event and message names are the interface.** `gridcraft:ready`, `gridcraft:open`, `gridcraft:save`, `gridcraft:dirty` and `gridcraft:failed`, and the fields they carry (the same as the `?host=parent` messages), stay stable; changing one is a breaking change.
+
 ## Renderer selection
 
 GridCraft's web build is the same egui app as the desktop one, compiled to wasm

From e06b2a7ead198debf4e0a36ebf9ac234e5bc5227 Mon Sep 17 00:00:00 2001
From: Helen Kwok <107752876+helenkwok@users.noreply.github.com>
Date: Thu, 5 Nov 2026 17:08:01 +0800
Subject: [PATCH 3/3] gridcraft-web: speak the host messages through
 craft-web-host

The transports, the message types and the origin checks come from the shared crate (storytold/craft-libs#420); GridCraft keeps the download hook, the open size limit, the workbook-saved rule and the author.
---
 Cargo.lock                         |  10 ++
 apps/gridcraft-web/Cargo.toml      |   2 +
 apps/gridcraft-web/src/host.rs     | 241 +++++++----------------------
 apps/gridcraft-web/src/hostmode.rs |  43 ++---
 apps/gridcraft-web/src/web.rs      |  18 +--
 packaging/web/README.md            |   4 +-
 6 files changed, 88 insertions(+), 230 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 785493348..dfdde30e7 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -995,6 +995,15 @@ dependencies = [
  "zip 9.1.0",
 ]
 
+[[package]]
+name = "craft-web-host"
+version = "0.1.0"
+source = "git+https://github.com/storytold/craft-libs?rev=2e2312ddaf21bc3d85cd3395d0955c7d239306f6#2e2312ddaf21bc3d85cd3395d0955c7d239306f6"
+dependencies = [
+ "wasm-bindgen",
+ "web-sys",
+]
+
 [[package]]
 name = "craft-window"
 version = "0.1.0"
@@ -2186,6 +2195,7 @@ dependencies = [
 name = "gridcraft-web"
 version = "0.16.0"
 dependencies = [
+ "craft-web-host",
  "eframe",
  "egui",
  "gridcraft-engine",
diff --git a/apps/gridcraft-web/Cargo.toml b/apps/gridcraft-web/Cargo.toml
index e384ffe09..e5c599bd8 100644
--- a/apps/gridcraft-web/Cargo.toml
+++ b/apps/gridcraft-web/Cargo.toml
@@ -16,6 +16,8 @@ path = "src/main.rs"
 [dependencies]
 gridcraft-engine = { workspace = true }
 gridcraft-ui-egui = { workspace = true }
+# The host messages (storytold/craft-libs): one contract and one bridge for the web builds.
+craft-web-host = { git = "https://github.com/storytold/craft-libs", rev = "2e2312ddaf21bc3d85cd3395d0955c7d239306f6", version = "0.1.0" }
 egui = { workspace = true }
 log = { workspace = true }
 serde_json = { workspace = true }
diff --git a/apps/gridcraft-web/src/host.rs b/apps/gridcraft-web/src/host.rs
index 0ab4fefbb..4a7193b73 100644
--- a/apps/gridcraft-web/src/host.rs
+++ b/apps/gridcraft-web/src/host.rs
@@ -1,127 +1,61 @@
 //! Host modes: a page that runs GridCraft (as an iframe, or in its own document) opens workbooks
-//! in it and stores what it saves instead of the browser downloading.
+//! in it and stores what it saves instead of the browser downloading. The messages and the two
+//! transports are `craft-web-host`'s (storytold/craft-libs), the same contract as the other Craft
+//! apps' bridges, with the `gridcraft:` prefix. This module is GridCraft's part of it.
 //!
-//! ## `?host=parent` — an `<iframe>` (such as a Nextcloud app)
-//!
-//! The framing page and GridCraft talk over `postMessage` between same-origin windows. Messages
-//! are plain objects with a `type`:
-//!
-//! - `gridcraft:ready` (to the parent): `{ version }`, the app is listening; send a file now.
-//! - `gridcraft:open` (from the parent): `{ name, bytes }`, bytes an `ArrayBuffer` or
-//!   `Uint8Array`. It opens like a workbook picked with File › Open or dropped on the window.
-//! - `gridcraft:save` (to the parent): `{ name, bytes }` (a transferred `ArrayBuffer`) for every
-//!   file GridCraft would otherwise download: Save and Save As (an .xlsx workbook) and Export
-//!   as PDF. The parent stores it and reports failures itself.
-//! - `gridcraft:dirty` (to the parent): `{ dirty }` whenever unsaved changes appear or go away.
-//! - `gridcraft:failed` (to the parent): `{ error }` when the app couldn't start.
-//!
-//! Only the parent window on the page's own origin is heard or answered.
-//!
-//! ## `data-host="page"` — the page's own document
-//!
-//! A page that loads the module into its own document (its own `<canvas id="gridcraft_canvas">`
-//! with `data-host="page"`, no iframe) gets the same behaviour over DOM `CustomEvent`s on the
-//! canvas instead of `postMessage`: the same four events outward (`ready`, `save`, `dirty`,
-//! `failed`, with the message fields as the event's `detail`), and the page dispatches
-//! `gridcraft:open` on the canvas with `detail: { name, bytes }` to open a workbook. Events don't
-//! bubble, so two editors on one page can't hear each other, and the canvas is the only target
-//! GridCraft listens on.
+//! - `?host=parent` (an `<iframe>`, such as a Nextcloud app) talks to the same-origin parent over
+//!   `postMessage`; `data-host="page"` on the canvas (the page's own document, no iframe) uses
+//!   DOM `CustomEvent`s on the canvas instead. `?host=parent` wins when both are present. With no
+//!   parent, or a parent on another origin, there is no bridge: the normal app with downloads.
+//! - `gridcraft:ready` once the app is listening; send a file now. GridCraft reads bytes, so it
+//!   says `file: false` and a host sends `bytes`.
+//! - `gridcraft:open` (from the host): `{ name, bytes }`. It opens like a workbook picked with
+//!   File › Open or dropped on the window; a file over [`MAX_OPEN_BYTES`] is refused before it is
+//!   copied.
+//! - `gridcraft:save` (to the host): `{ name, saveAs, bytes }` for every file GridCraft would
+//!   otherwise download: Save and Save As (an .xlsx workbook) and Export as PDF. The host stores
+//!   it and reports failures itself. GridCraft doesn't tell the host which saves make a file the
+//!   document, so `saveAs` is always `false`.
+//! - `gridcraft:dirty` whenever unsaved changes appear or go away, `gridcraft:failed` when the
+//!   app couldn't start.
 //!
 //! In both host modes the page starts with an empty workbook instead of a sample, saves and PDF
 //! exports are handed to the page rather than downloaded, and `?author=` names the user for new
 //! notes and comments.
 
-use std::cell::{Cell, RefCell};
+use std::cell::RefCell;
 use std::rc::Rc;
 
+use craft_web_host::web::{FileData, Host, Message};
 use gridcraft_ui_egui::{Inbox, Services, SheetApp};
-use wasm_bindgen::JsCast as _;
-use wasm_bindgen::JsValue;
-use wasm_bindgen::closure::Closure;
 
 use crate::hostmode::open_name;
 
-/// Saving one of these hands the whole workbook to the host, which stores it: the workbook
-/// counts as saved under that name, as it would after Save on the desktop.
+/// The app id in the host messages (`gridcraft:ready`).
+const APP: &str = "gridcraft";
+
+/// Saved files that count as a workbook: the document is then clean under the name it was saved as.
 const WORKBOOK_EXTS: &[&str] = &["xlsx"];
 
-/// The largest file the host may hand over to open, checked before it is copied (the app's own readers have their own limits).
+/// The largest workbook taken from the host page, refused before it is copied.
 const MAX_OPEN_BYTES: u64 = 512 << 20;
 
-/// The longest file name taken from the host.
-const MAX_NAME_CHARS: usize = 255;
-
 /// The longest user name taken from `?author=`.
 const MAX_AUTHOR_CHARS: usize = 200;
 
-/// How a host page is reached. The modes behave the same; they differ only in how an event goes
-/// out ([`Transport::send`]) and how an open request comes in ([`Bridge::listen`]).
-#[derive(Clone)]
-enum Transport {
-    /// `?host=parent`: `postMessage` between same-origin windows.
-    Parent { window: web_sys::Window, parent: web_sys::Window, origin: String },
-    /// `data-host="page"`: DOM `CustomEvent`s on the editor's own canvas.
-    Page { canvas: web_sys::HtmlCanvasElement },
-}
-
-impl Transport {
-    /// Hand an event to the host. In parent mode this is a `postMessage` with a `type` field; in
-    /// page mode a `CustomEvent` of that name on the canvas, whose `detail` holds the fields and
-    /// which never bubbles (two editors on one page must not hear each other).
-    fn send(&self, event: &str, fields: &[(&str, JsValue)], transfer: Option<&js_sys::ArrayBuffer>) -> Result<(), String> {
-        match self {
-            Transport::Parent { parent, origin, .. } => {
-                let mut message_fields = Vec::with_capacity(fields.len() + 1);
-                message_fields.push(("type", JsValue::from_str(event)));
-                message_fields.extend_from_slice(fields);
-                let message = message(&message_fields).ok_or_else(|| "couldn't build the message".to_string())?;
-                let sent = match transfer {
-                    Some(buffer) => parent.post_message_with_transfer(&message, origin, &js_sys::Array::of1(buffer)),
-                    // `None` is only ever passed for the parent mode's small events; the page mode
-                    // can't transfer anyway (below).
-                    None => parent.post_message(&message, origin),
-                };
-                sent.map_err(|e| js_error(&e, "couldn't post the message"))
-            }
-            Transport::Page { canvas } => {
-                let detail = message(fields).ok_or_else(|| "couldn't build the event detail".to_string())?;
-                let init = web_sys::CustomEventInit::new();
-                init.set_bubbles(false);
-                init.set_detail(&detail);
-                let custom = web_sys::CustomEvent::new_with_event_init_dict(event, &init).map_err(|e| js_error(&e, "couldn't create the event"))?;
-                canvas.dispatch_event(&custom).map_err(|e| js_error(&e, "couldn't dispatch the event"))?;
-                Ok(())
-            }
-        }
-    }
-}
-
 #[derive(Clone)]
 pub struct Bridge {
-    transport: Transport,
+    host: Rc<Host>,
     /// Names of the files handed to the host since the last frame.
     saved: Rc<RefCell<Vec<String>>>,
-    /// The unsaved-changes state last reported to the host.
-    reported: Rc<Cell<Option<bool>>>,
 }
 
 impl Bridge {
-    /// The parent bridge for `?host=parent`; `None` when the page isn't framed (there is no
-    /// parent to talk to), so opening that URL directly stays the normal app with downloads.
-    pub fn new() -> Option<Self> {
-        let window = web_sys::window()?;
-        let parent = window.parent().ok().flatten()?;
-        if js_sys::Object::is(&parent, &window) {
-            return None;
-        }
-        let origin = window.location().origin().ok()?;
-        Some(Self { transport: Transport::Parent { window, parent, origin }, saved: Rc::default(), reported: Rc::default() })
-    }
-
-    /// The page bridge for `data-host="page"`: the host page runs GridCraft in its own document
-    /// and hears the editor's DOM `CustomEvent`s on this canvas.
-    pub fn for_page(canvas: &web_sys::HtmlCanvasElement) -> Self {
-        Self { transport: Transport::Page { canvas: canvas.clone() }, saved: Rc::default(), reported: Rc::default() }
+    /// The bridge for this page, or `None` when GridCraft isn't hosted: no `?host=parent` and no
+    /// `data-host="page"` on the canvas, an unframed `?host=parent` page (it stays the normal app
+    /// with downloads), or a parent on another origin.
+    pub fn detect(canvas: &web_sys::HtmlCanvasElement) -> Option<Self> {
+        Some(Self { host: Rc::new(Host::connect(APP, canvas)?), saved: Rc::default() })
     }
 
     /// Send saved and exported files to the host instead of downloading them, and hear files
@@ -145,15 +79,16 @@ impl Bridge {
     }
 
     pub fn post_ready(&self) {
-        let _ = self.transport.send("gridcraft:ready", &[("version", env!("CARGO_PKG_VERSION").into())], None);
+        let _ = self.host.post_ready(env!("CARGO_PKG_VERSION"), false);
     }
 
     pub fn post_failed(&self, error: &str) {
-        let _ = self.transport.send("gridcraft:failed", &[("error", error.into())], None);
+        let _ = self.host.post_failed(error, None);
     }
 
     /// After each frame: a workbook handed to the host this frame counts as saved under the
-    /// name it was saved as, and the host hears when unsaved changes appear or go away.
+    /// name it was saved as, and the host hears when unsaved changes appear or go away (the
+    /// crate does not repeat a state it already reported).
     pub fn sync(&self, app: &mut SheetApp) {
         let saved = std::mem::take(&mut *self.saved.borrow_mut());
         if let Some(name) = saved.iter().rev().find(|name| is_workbook(name))
@@ -164,70 +99,39 @@ impl Bridge {
                 doc.title = name.clone();
             }
         }
-        let dirty = app.session.documents().iter().any(|d| d.is_dirty());
-        if self.reported.get() != Some(dirty) && self.transport.send("gridcraft:dirty", &[("dirty", dirty.into())], None).is_ok() {
-            self.reported.set(Some(dirty));
-        }
+        self.host.post_dirty(app.session.documents().iter().any(|d| d.is_dirty()));
     }
 
     fn post_save(&self, path: &str, bytes: &[u8]) -> Result<(), String> {
         let name = file_name(path);
-        // `gridcraft:save` carries the bytes as an `ArrayBuffer`; the parent bridge transfers it.
-        let buffer = js_sys::Uint8Array::from(bytes).buffer();
-        self.transport.send("gridcraft:save", &[("name", name.as_str().into()), ("bytes", buffer.clone().into())], Some(&buffer))?;
+        self.host.post_save(&name, bytes, None, false)?;
         self.saved.borrow_mut().push(name);
         Ok(())
     }
 
     fn listen(&self, inbox: Inbox, ctx: egui::Context) {
-        match &self.transport {
-            Transport::Parent { window, parent, origin } => {
-                let parent = parent.clone();
-                let origin = origin.clone();
-                let on_message = Closure::<dyn FnMut(web_sys::MessageEvent)>::new(move |event: web_sys::MessageEvent| {
-                    if event.origin() != origin || !event.source().is_some_and(|s| js_sys::Object::is(&s, &parent)) {
-                        return;
-                    }
-                    let data = event.data();
-                    if string(&data, "type").as_deref() != Some("gridcraft:open") {
-                        return;
-                    }
-                    deliver_open(&inbox, &ctx, &data);
-                });
-                if window.add_event_listener_with_callback("message", on_message.as_ref().unchecked_ref()).is_ok() {
-                    // The listener lives as long as the page.
-                    on_message.forget();
-                }
+        self.host.listen(move |message| {
+            if let Message::Open { name, data } = message {
+                deliver_open(&inbox, &ctx, &name, &data);
             }
-            Transport::Page { canvas } => {
-                let on_open = Closure::<dyn FnMut(web_sys::Event)>::new(move |event: web_sys::Event| {
-                    let Some(open) = event.dyn_ref::<web_sys::CustomEvent>() else { return };
-                    let detail = open.detail();
-                    deliver_open(&inbox, &ctx, &detail);
-                });
-                if canvas.add_event_listener_with_callback("gridcraft:open", on_open.as_ref().unchecked_ref()).is_ok() {
-                    // The listener lives as long as the page.
-                    on_open.forget();
-                }
-            }
-        }
+        });
     }
 }
 
-/// The file an open message or event carries, pushed onto the inbox for the next frame, like a
-/// dropped file.
-fn deliver_open(inbox: &Inbox, ctx: &egui::Context, data: &JsValue) {
-    if let Some((name, bytes)) = open_payload(data) {
-        inbox.lock().unwrap_or_else(|e| e.into_inner()).push((name, bytes));
-        ctx.request_repaint();
+/// The file an open message carries, pushed onto the inbox for the next frame, like a dropped
+/// file. A host's file is untrusted input: an oversized one is refused before it is copied into
+/// the app's memory (the data's own length, not the host's claim).
+fn deliver_open(inbox: &Inbox, ctx: &egui::Context, name: &str, data: &FileData) {
+    let FileData::Bytes(array) = data else {
+        log::warn!("host file {name} came as a File; GridCraft reads bytes only; not opened");
+        return;
+    };
+    if data.size() > MAX_OPEN_BYTES as f64 {
+        log::warn!("host file is {} bytes, over the {} MiB host open limit; not opened", data.size(), MAX_OPEN_BYTES >> 20);
+        return;
     }
-}
-
-/// The file an open message or event carries: a usable name and the bytes.
-fn open_payload(data: &JsValue) -> Option<(String, Vec<u8>)> {
-    let name: String = open_name(string(data, "name").as_deref()).chars().take(MAX_NAME_CHARS).collect();
-    let bytes = bytes(data)?;
-    Some((name, bytes))
+    inbox.lock().unwrap_or_else(|e| e.into_inner()).push((open_name(name), array.to_vec()));
+    ctx.request_repaint();
 }
 
 fn is_workbook(name: &str) -> bool {
@@ -237,40 +141,3 @@ fn is_workbook(name: &str) -> bool {
 fn file_name(path: &str) -> String {
     std::path::Path::new(path).file_name().map(|n| n.to_string_lossy().to_string()).unwrap_or_else(|| path.to_string())
 }
-
-/// A message object or `CustomEvent` detail with the given fields, or `None` if one couldn't be
-/// set.
-fn message(fields: &[(&str, JsValue)]) -> Option<js_sys::Object> {
-    let m = js_sys::Object::new();
-    for (key, value) in fields {
-        js_sys::Reflect::set(&m, &JsValue::from_str(key), value).ok()?;
-    }
-    Some(m)
-}
-
-fn string(data: &JsValue, key: &str) -> Option<String> {
-    js_sys::Reflect::get(data, &JsValue::from_str(key)).ok()?.as_string()
-}
-
-/// `bytes` as an `ArrayBuffer` or `Uint8Array`.
-fn bytes(data: &JsValue) -> Option<Vec<u8>> {
-    let bytes = js_sys::Reflect::get(data, &JsValue::from_str("bytes")).ok()?;
-    let view = if let Some(array) = bytes.dyn_ref::<js_sys::Uint8Array>() {
-        array.clone()
-    } else if bytes.is_instance_of::<js_sys::ArrayBuffer>() {
-        js_sys::Uint8Array::new(&bytes)
-    } else {
-        return None;
-    };
-    // A file from the host is untrusted input: refuse an oversized one before copying it into the app's memory.
-    if u64::from(view.length()) > MAX_OPEN_BYTES {
-        log::warn!("host file is {} bytes, over the {} MiB host open limit; not opened", view.length(), MAX_OPEN_BYTES >> 20);
-        return None;
-    }
-    Some(view.to_vec())
-}
-
-/// A `JsValue` error as a string, after `what` went wrong.
-fn js_error(e: &JsValue, what: &str) -> String {
-    format!("{what}: {}", e.as_string().unwrap_or_else(|| format!("{e:?}")))
-}
diff --git a/apps/gridcraft-web/src/hostmode.rs b/apps/gridcraft-web/src/hostmode.rs
index aaf4c12aa..3ac4bd723 100644
--- a/apps/gridcraft-web/src/hostmode.rs
+++ b/apps/gridcraft-web/src/hostmode.rs
@@ -1,23 +1,18 @@
 //! Pure host-mode rules, shared by the bridge ([`crate::host`]) and testable without a browser
-//! (like [`crate::prefs`]): what opts a page into hosting GridCraft in its own document, and the
-//! name the bridge fills in when a host's open request has none.
-
-/// The one `data-host` value that opts a page in: the exact string `"page"`.
-pub const PAGE_HOST: &str = "page";
+//! (like [`crate::prefs`]): the name the bridge fills in when a host's open request has none.
+//! Which pages host the app is `craft-web-host`'s.
 
 /// The file name used when an open request carries no usable one.
 pub const DEFAULT_OPEN_NAME: &str = "Book.xlsx";
 
-/// Does this `data-host` value ask for page host mode? Only the exact value [`PAGE_HOST`] counts;
-/// anything else is ignored, so the page host mode stays opt-in.
-pub fn page_host_requested(data_host: Option<&str>) -> bool {
-    data_host == Some(PAGE_HOST)
-}
+/// The name `craft-web-host` gives an open request that carries no usable one (it cleans a host's
+/// name and falls back to this).
+const NAMELESS: &str = "document";
 
-/// A usable file name for an open request: the host's name when it isn't blank, else the
-/// [`DEFAULT_OPEN_NAME`].
-pub fn open_name(name: Option<&str>) -> String {
-    name.filter(|n| !n.trim().is_empty()).unwrap_or(DEFAULT_OPEN_NAME).to_string()
+/// A usable file name for an open request: the cleaned name the crate hands over, or
+/// [`DEFAULT_OPEN_NAME`] when the host sent none.
+pub fn open_name(name: &str) -> String {
+    if name == NAMELESS { DEFAULT_OPEN_NAME.to_string() } else { name.to_string() }
 }
 
 #[cfg(test)]
@@ -25,21 +20,9 @@ mod tests {
     use super::*;
 
     #[test]
-    fn only_the_exact_page_value_opts_in() {
-        assert!(page_host_requested(Some("page")));
-        assert!(!page_host_requested(Some("Page")));
-        assert!(!page_host_requested(Some(" page")));
-        assert!(!page_host_requested(Some("parent")));
-        assert!(!page_host_requested(Some("")));
-        assert!(!page_host_requested(None));
-    }
-
-    #[test]
-    fn open_names_fall_back_to_the_default_when_blank() {
-        assert_eq!(open_name(Some("Budget.xlsx")), "Budget.xlsx");
-        assert_eq!(open_name(Some(" Sheet2!Book.xlsx ")), " Sheet2!Book.xlsx ");
-        assert_eq!(open_name(Some("")), DEFAULT_OPEN_NAME);
-        assert_eq!(open_name(Some("   ")), DEFAULT_OPEN_NAME);
-        assert_eq!(open_name(None), DEFAULT_OPEN_NAME);
+    fn open_names_fall_back_to_the_default_when_the_host_sent_none() {
+        assert_eq!(open_name("Budget.xlsx"), "Budget.xlsx");
+        assert_eq!(open_name("Sheet2!Book.xlsx"), "Sheet2!Book.xlsx");
+        assert_eq!(open_name("document"), DEFAULT_OPEN_NAME, "what the crate says for a missing or blank name");
     }
 }
diff --git a/apps/gridcraft-web/src/web.rs b/apps/gridcraft-web/src/web.rs
index 868b7e641..268560520 100644
--- a/apps/gridcraft-web/src/web.rs
+++ b/apps/gridcraft-web/src/web.rs
@@ -37,18 +37,12 @@ pub fn start() {
         {
             create.instance_descriptor.backends = eframe::wgpu::Backends::GL;
         }
-        // `?host=parent`: a same-origin page framing GridCraft (such as a Nextcloud app) opens
-        // workbooks in it and stores what it saves (`host`). Unframed there is no parent, so that
-        // URL on its own stays the normal app with downloads. `data-host="page"` on the canvas
-        // opts a page in instead: it runs GridCraft in its own document and talks over DOM
-        // `CustomEvent`s on the canvas (`host`).
-        let bridge = if query_param("host").as_deref() == Some("parent") {
-            crate::host::Bridge::new()
-        } else if crate::hostmode::page_host_requested(canvas.get_attribute("data-host").as_deref()) {
-            Some(crate::host::Bridge::for_page(&canvas))
-        } else {
-            None
-        };
+        // Host modes (`craft-web-host`): `?host=parent`, a same-origin page framing GridCraft (such
+        // as a Nextcloud app), opens workbooks in it and stores what it saves (`host`). Unframed
+        // there is no parent, so that URL on its own stays the normal app with downloads.
+        // `data-host="page"` on the canvas opts a page in instead: it runs GridCraft in its own
+        // document and talks over DOM `CustomEvent`s on the canvas.
+        let bridge = crate::host::Bridge::detect(&canvas);
         let app_bridge = bridge.clone();
         let result = eframe::WebRunner::new()
             .start(
diff --git a/packaging/web/README.md b/packaging/web/README.md
index d4e85a765..1f346cde0 100644
--- a/packaging/web/README.md
+++ b/packaging/web/README.md
@@ -87,7 +87,7 @@ downloading them. The two sides talk `postMessage` with plain window messages th
 
 | Message | Direction | Fields |
 |---|---|---|
-| `gridcraft:ready` | app → page | `version`: the app is listening; send a file now |
+| `gridcraft:ready` | app → page | `version`, `appVersion`: the app is listening; send a file now |
 | `gridcraft:open` | page → app | `name`, `bytes` (an `ArrayBuffer` or `Uint8Array`): open like File › Open |
 | `gridcraft:save` | app → page | `name`, `bytes` (a transferred `ArrayBuffer`): every file the app would otherwise download (Save, Save As, Export as PDF). The page stores it and reports failures itself. |
 | `gridcraft:dirty` | app → page | `dirty`: unsaved changes appeared or went away |
@@ -149,6 +149,8 @@ As with the parent bridge, the app starts with an empty workbook instead of a sa
 must be exactly `page`; anything else is ignored, and the app runs as a standalone page with
 downloads.
 
+The messages and both transports are the shared contract of [`craft-web-host`](https://github.com/storytold/craft-libs/tree/main/crates/web-host) (storytold/craft-libs#420), the same for every Craft app: its README lists every message, including `saved`, with the compatibility notes. In `gridcraft:ready`, `version` is the contract's (`"1"`) and `appVersion` is this app's release. GridCraft reads bytes, so a host sends `bytes`, not a `File`.
+
 ### Trust and limits
 
 - **Who is trusted.** In page host mode the page and GridCraft share one document, so any script on the page can drive the app: open files in it and receive what it saves. Use this mode only for a page you control. The iframe mode (`?host=parent`) answers only the parent window, on the page's own origin.