From 929911326873116404a2d85e00d5fa0ac5326989 Mon Sep 17 00:00:00 2001
From: Helen Kwok <107752876+helenkwok@users.noreply.github.com>
Date: Thu, 5 Nov 2026 17:34:20 +0800
Subject: [PATCH] deckcraft-web: speak the host messages through
 craft-web-host, and add page host mode

The transports, the message types and the origin checks come from the shared crate (storytold/craft-libs#420). `data-host="page"` on the canvas now hosts DeckCraft in a page's own document, as in the other apps; the parent bridge keeps its behaviour.
---
 Cargo.lock                     |  10 ++
 apps/deckcraft-web/Cargo.toml  |   2 +
 apps/deckcraft-web/src/host.rs | 163 +++++++++++----------------------
 apps/deckcraft-web/src/web.rs  |  12 ++-
 packaging/web/README.md        |   4 +-
 5 files changed, 74 insertions(+), 117 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 89aaa91aa..b4059e689 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -935,6 +935,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 = "crc32fast"
 version = "1.5.2"
@@ -1322,6 +1331,7 @@ dependencies = [
 name = "deckcraft-web"
 version = "0.15.0"
 dependencies = [
+ "craft-web-host",
  "deckcraft-engine",
  "deckcraft-ui-egui",
  "eframe",
diff --git a/apps/deckcraft-web/Cargo.toml b/apps/deckcraft-web/Cargo.toml
index ca04d5be9..58e8657a4 100644
--- a/apps/deckcraft-web/Cargo.toml
+++ b/apps/deckcraft-web/Cargo.toml
@@ -16,6 +16,8 @@ path = "src/main.rs"
 [dependencies]
 deckcraft-engine = { workspace = true }
 deckcraft-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/deckcraft-web/src/host.rs b/apps/deckcraft-web/src/host.rs
index 85c357a12..5cf4b0399 100644
--- a/apps/deckcraft-web/src/host.rs
+++ b/apps/deckcraft-web/src/host.rs
@@ -1,17 +1,21 @@
-//! The `postMessage` bridge to a same-origin parent page (`?host=parent`), for pages that embed
-//! DeckCraft in an `<iframe>` and keep its files (a Nextcloud app, a personal file server). The
-//! same messages as GridCraft's, WordCraft's and PdfCraft's bridges; each is a plain object with a
-//! `type`:
+//! The host bridge, for pages that embed DeckCraft and keep its files (a Nextcloud app, a personal
+//! file server). 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
+//! `deckcraft:` prefix. This module is DeckCraft's part of it.
 //!
-//! - `deckcraft:ready` (to the parent): `{ version }`, sent once the app is running and
-//!   listening; send a file now.
-//! - `deckcraft:open` (from the parent): `{ name, bytes }`, bytes an `ArrayBuffer` or
+//! - `?host=parent` (an `<iframe>`) 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.
+//! - `deckcraft:ready` (to the host): sent once the app is running and listening; send a file now. DeckCraft
+//!   reads bytes, so it says `file: false` and a host sends `bytes`.
+//! - `deckcraft:open` (from the host): `{ name, bytes }`, bytes an `ArrayBuffer` or
 //!   `Uint8Array`, name a bare file name. It opens like a file picked with File › Open on the
 //!   desktop: a presentation sent with its name (.pptx, .potx, .ppsx, .deckcraft) has that name
 //!   as its file, so Save goes back to it; an outline (.txt, .md, .rtf), a file without a name and
 //!   a damaged file open untitled.
-//! - `deckcraft:save` (to the parent): `{ name, saveAs, bytes }` (a transferred `ArrayBuffer`) for
-//!   every file DeckCraft would otherwise download. The parent stores it and reports failures
+//! - `deckcraft:save` (to the host): `{ name, saveAs, bytes }` (with the bytes as a transferred `ArrayBuffer` over `postMessage`) for
+//!   every file DeckCraft would otherwise download. The host stores it and reports failures
 //!   itself. `saveAs` says whether the file becomes the presentation's file:
 //!   - Save: `false`. It writes the opened file under its own name and format (a .pptx stays a
 //!     .pptx), as the desktop app does. A name the parent never sent (an untitled presentation, an
@@ -22,59 +26,46 @@
 //!     now that file; the next Save sends its name with `false`.
 //!   - Export (PDF, pictures, outline, GIF, handouts, a Save As type that isn't a presentation)
 //!     and Print: `false`. They are copies; the presentation's file stays the same.
-//! - `deckcraft:dirty` (to the parent): `{ dirty }` whenever unsaved changes appear or go away.
-//! - `deckcraft:failed` (to the parent): `{ error }` when the app couldn't start.
+//! - `deckcraft:dirty` whenever unsaved changes appear or go away, `deckcraft:failed` when the
+//!   app couldn't start.
 //!
-//! Only the parent window on the page's own origin is heard or answered. In host mode the app
-//! starts with an empty presentation instead of the sample, which gives way to the first file the
-//! parent sends; the parent guards leaving the page, and `?author=` names the user for comments.
+//! In host mode the app starts with an empty presentation instead of the sample, which gives way to
+//! the first file the host sends; the host guards leaving the page, and `?author=` names the user
+//! for comments.
 
-use std::cell::{Cell, RefCell};
+use std::cell::RefCell;
 use std::rc::Rc;
 
+use craft_web_host::web::{FileData, Host, Message};
 use deckcraft_ui_egui::{Services, SlideApp};
-use wasm_bindgen::JsCast as _;
-use wasm_bindgen::JsValue;
-use wasm_bindgen::closure::Closure;
+
+/// The app id in the host messages (`deckcraft:ready`).
+const APP: &str = "deckcraft";
+
+/// The name `craft-web-host` gives an open request that carries none (it cleans a host's name and
+/// falls back to this): no name is no file, so the presentation opens untitled.
+const NAMELESS: &str = "document";
 
 /// The longest user name taken from `?author=` (the preferences' own limit).
 const MAX_AUTHOR_CHARS: usize = 256;
 
 #[derive(Clone)]
 pub struct Bridge {
-    window: web_sys::Window,
-    parent: web_sys::Window,
-    origin: String,
-    /// Files the parent sent (the name, if it sent one), waiting for the next frame.
+    host: Rc<Host>,
+    /// Files the host sent (the name, if it sent one), waiting for the next frame.
     opened: Rc<RefCell<Vec<(Option<String>, Vec<u8>)>>>,
-    /// The unsaved-changes state last reported to the parent.
-    reported: Rc<Cell<Option<bool>>>,
 }
 
 impl Bridge {
-    /// `None` when the page isn't framed (there is no parent to talk to), or when the parent is
-    /// on another origin: messages only go to this origin, so the browser would drop every save
-    /// without an error while the presentation showed as saved.
-    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()?;
-        // An opaque origin (a `file://` page in some browsers) can't be a `postMessage` target.
-        if origin == "null" {
-            return None;
-        }
-        // Reading another origin's location throws, which is `None` too.
-        if parent.location().origin().ok()? != origin {
-            return None;
-        }
-        Some(Self { window, parent, origin, opened: Rc::default(), reported: Rc::default() })
+    /// The bridge for this page, or `None` when DeckCraft 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)?), opened: Rc::default() })
     }
 
-    /// Hand saved and exported files to the parent instead of downloading them, and hear the
-    /// files it sends.
+    /// Hand saved and exported files to the host instead of downloading them, and hear the files
+    /// it sends.
     pub fn connect(&self, services: &mut Services, ctx: egui::Context) {
         self.listen(ctx);
         let bridge = self.clone();
@@ -97,15 +88,15 @@ impl Bridge {
     }
 
     pub fn post_ready(&self) {
-        self.send(&[("type", "deckcraft:ready".into()), ("version", env!("CARGO_PKG_VERSION").into())]);
+        let _ = self.host.post_ready(env!("CARGO_PKG_VERSION"), false);
     }
 
-    /// The app couldn't start (no WebGPU or WebGL2, for example): let the parent say so.
+    /// The app couldn't start (no WebGPU or WebGL2, for example): let the host say so.
     pub fn post_failed(&self, error: &str) {
-        self.send(&[("type", "deckcraft:failed".into()), ("error", error.into())]);
+        let _ = self.host.post_failed(error, None);
     }
 
-    /// Before each frame: open the files the parent sent.
+    /// Before each frame: open the files the host sent.
     pub fn open_files(&self, app: &mut SlideApp) {
         let opened = std::mem::take(&mut *self.opened.borrow_mut());
         for (name, bytes) in opened {
@@ -113,80 +104,30 @@ impl Bridge {
         }
     }
 
-    /// After each frame: tell the parent when unsaved changes appear or go away.
+    /// After each frame: tell the host when unsaved changes appear or go away (the crate does not
+    /// repeat a state it already reported).
     pub fn report_dirty(&self, app: &SlideApp) {
-        let dirty = app.session.documents().iter().any(|d| d.is_dirty());
-        if self.reported.get() != Some(dirty) && self.send(&[("type", "deckcraft:dirty".into()), ("dirty", dirty.into())]) {
-            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], save_as: bool) -> 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 buffer = js_sys::Uint8Array::from(bytes).buffer();
-        let message = message(&[
-            ("type", "deckcraft:save".into()),
-            ("name", name.as_str().into()),
-            ("saveAs", save_as.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.host.post_save(&name, bytes, None, save_as)
     }
 
-    /// Hear `deckcraft:open` from the parent and queue the file for the next frame.
+    /// Hear `deckcraft:open` and queue the file for the next frame.
     fn listen(&self, ctx: egui::Context) {
-        let parent = self.parent.clone();
-        let origin = self.origin.clone();
         let opened = self.opened.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)) {
+        self.host.listen(move |message| {
+            let Message::Open { name, data } = message else { return };
+            let FileData::Bytes(array) = data else {
+                log::warn!("host file {name} came as a File; DeckCraft reads bytes only; not opened");
                 return;
-            }
-            let data = event.data();
-            if string(&data, "type").as_deref() != Some("deckcraft:open") {
-                return;
-            }
+            };
             // No name is no file: the presentation opens untitled, never under an invented name.
-            let name = string(&data, "name").filter(|n| !n.trim().is_empty());
-            let Some(bytes) = bytes(&data) else { return };
-            opened.borrow_mut().push((name, bytes));
+            let name = (name != NAMELESS).then_some(name);
+            opened.borrow_mut().push((name, array.to_vec()));
             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())
-    }
-}
-
-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()?;
-    if let Some(array) = bytes.dyn_ref::<js_sys::Uint8Array>() {
-        Some(array.to_vec())
-    } else if bytes.is_instance_of::<js_sys::ArrayBuffer>() {
-        Some(js_sys::Uint8Array::new(&bytes).to_vec())
-    } else {
-        None
     }
 }
diff --git a/apps/deckcraft-web/src/web.rs b/apps/deckcraft-web/src/web.rs
index 7720b605c..8930a66f4 100644
--- a/apps/deckcraft-web/src/web.rs
+++ b/apps/deckcraft-web/src/web.rs
@@ -24,11 +24,13 @@ pub fn start() {
             log::error!("missing <canvas id=\"{CANVAS_ID}\">");
             return;
         };
-        // `?host=parent`: a same-origin page framing DeckCraft opens presentations in it and
-        // stores what it saves (`host`). The presenter popup is never the framed page.
-        let host = query_param("host").as_deref() == Some("parent") && crate::presenter::token().is_none();
-        let bridge = if host { crate::host::Bridge::new() } else { None };
-        if host && bridge.is_none() {
+        // Host modes (`craft-web-host`): `?host=parent`, a same-origin page framing DeckCraft,
+        // opens presentations in it and stores what it saves (`host`); `data-host="page"` on the
+        // canvas opts a page in that runs DeckCraft in its own document. The presenter popup is
+        // never the framed page.
+        let hosted = crate::presenter::token().is_none();
+        let bridge = if hosted { crate::host::Bridge::detect(&canvas) } else { None };
+        if hosted && bridge.is_none() && query_param("host").as_deref() == Some("parent") {
             log::warn!("?host=parent needs a framing page on the same origin; saves download instead");
         }
         let app_bridge = bridge.clone();
diff --git a/packaging/web/README.md b/packaging/web/README.md
index 1e96279c0..19cdaedfa 100644
--- a/packaging/web/README.md
+++ b/packaging/web/README.md
@@ -86,7 +86,7 @@ Messages are plain objects with a `type`:
 
 | Message | Direction | Fields |
 |---|---|---|
-| `deckcraft:ready` | to the page | `version`. The app runs and listens: send the file now. |
+| `deckcraft:ready` | to the page | `version`, `appVersion`. The app runs and listens: send the file now. |
 | `deckcraft:open` | from the page | `name` (a bare file name, such as `Talk.pptx`), `bytes` (`ArrayBuffer` or `Uint8Array`). Opens like File › Open: a presentation (.pptx, .potx, .ppsx, .deckcraft) has that name as its file; an outline (.txt, .md, .rtf), a file sent without a name and a damaged file open untitled. |
 | `deckcraft:save` | to the page | `name`, `saveAs`, `bytes` (a transferred `ArrayBuffer`), for every file DeckCraft would otherwise download. The page stores it. |
 | `deckcraft:dirty` | to the page | `dirty`, whenever unsaved changes appear or go away. |
@@ -134,6 +134,8 @@ beside it. The page guards leaving itself (DeckCraft adds no guard of its own),
 </script>
 ```
 
+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 `deckcraft:ready`, `version` is the contract's (`"1"`) and `appVersion` is this app's release. DeckCraft reads bytes, so a host sends `bytes`, not a `File`.
+
 ## Renderer selection and fallback flags
 
 DeckCraft renders with wgpu. It uses **WebGPU** when the browser has it and falls back to