From 915535cd59456581115b89634654d749bafda840 Mon Sep 17 00:00:00 2001
From: Lachlan Kermode <lachie@ohrg.org>
Date: Fri, 18 Sep 2026 11:01:45 +0200
Subject: [PATCH 1/2] Asks a package whether its scripts survive a DOM morph
 before patching a page

A morph does not re-execute the page's scripts, and refetched page bytes are
the pre-hydration build output, so a package whose script does work at boot
had that work reverted with nothing re-running to redo it. The widget was
left drawn as though it had never started, and nothing threw.

A package now declares `js_rehydrate = true` in its `[tool.rheo.<format>]`
block and pushes a callback onto `window.__rheoRehydrate`. Declaring scripts
render with `data-rheo-rehydrate`; the live client surveys every script on
the page before morphing and reloads instead if any one of them is
undeclared, then runs the callbacks after a morph it did perform.
---
 changelog.md                         | 30 ++++++++++++
 crates/core/src/assets/mod.rs        | 50 ++++++++++++++++---
 crates/core/src/html_dom.rs          | 73 ++++++++++++++++++++++++++--
 crates/core/src/packages/manifest.rs | 13 ++++-
 crates/core/src/plugins/mod.rs       |  6 +++
 crates/html/src/lib.rs               |  2 +
 crates/html/src/live/live-reload.js  | 46 ++++++++++++++++++
 crates/html/src/server.rs            |  7 ++-
 docs/contract.md                     | 62 +++++++++++++++++++++++
 9 files changed, 276 insertions(+), 13 deletions(-)

diff --git a/changelog.md b/changelog.md
index ff002537..2eb112f5 100644
--- a/changelog.md
+++ b/changelog.md
@@ -1,5 +1,35 @@
 # 0.6.4 — user-visible changes
 
+## `rheo watch` patches the page on a content edit, and a package must opt in
+
+A rebuild that touched only `.typ` sources no longer reloads the page. The
+dev-server client refetches it and morphs the new HTML into the live DOM
+instead, so scroll position, focus, text selection, open `<details>` and
+playing media survive an edit. A rebuild that touched assets still reloads.
+
+**A package shipping JavaScript has to declare that it can cope, or its page
+falls back to a reload.** A morph does not re-execute the page's scripts, and
+refetched page bytes are the pre-hydration build output — so for a package
+whose script does work at boot (pressing the buttons the URL names, hiding
+filtered rows, setting the attribute its stylesheet keys off), a morph would
+revert all of it and re-run nothing, leaving the widget drawn as though it had
+never started. Nothing would throw.
+
+So rheo asks. A package sets `js_rehydrate = true` in its
+`[tool.rheo.<format>]` block and pushes a callback onto
+`window.__rheoRehydrate`; rheo renders its scripts with `data-rheo-rehydrate`
+and calls the callbacks after each morph. Before morphing, the client checks
+every script on the page and reloads instead if any one of them is
+undeclared — a page is a single DOM, and patching it for the widgets that cope
+would break the ones that do not.
+
+The upshot for an existing project is that nothing changes yet: a page
+carrying package JavaScript keeps reloading exactly as it did, and pages with
+no scripts get the morph immediately. `docs/contract.md` has the protocol,
+including what idempotence on a morphed DOM actually requires of a hook —
+Idiomorph mutates elements in place, so listeners survive and a naive re-wire
+double-fires.
+
 ## A configured releases namespace caches by its host, not in the shared Typst cache
 
 A namespace configured with `releases = ...` now caches its downloaded
diff --git a/crates/core/src/assets/mod.rs b/crates/core/src/assets/mod.rs
index 0eeb1935..5f073cca 100644
--- a/crates/core/src/assets/mod.rs
+++ b/crates/core/src/assets/mod.rs
@@ -26,7 +26,11 @@ enum AssetSource<'b> {
     User,
     /// Contributed by an `[packages.<ns>]` block, resolved against the
     /// package's own directory.
-    Package { source_root: &'b Path, module: bool },
+    Package {
+        source_root: &'b Path,
+        module: bool,
+        rehydrate: bool,
+    },
     /// The project-root filename convention, pushed by [`gather_entries`]
     /// only when the project declared no `User` entry of its own.
     ProjectDefault,
@@ -44,6 +48,16 @@ impl<'b> AssetSource<'b> {
         matches!(self, AssetSource::Package { module: true, .. })
     }
 
+    fn rehydrate(&self) -> bool {
+        matches!(
+            self,
+            AssetSource::Package {
+                rehydrate: true,
+                ..
+            }
+        )
+    }
+
     /// Only a path the project wrote down in a `[[<plugin>.assets]]` block
     /// warns when it's missing. A package file and the root convention are
     /// paths rheo proposed itself, so their absence is routine rather than
@@ -53,6 +67,13 @@ impl<'b> AssetSource<'b> {
     }
 }
 
+/// An on-disk source's module/rehydrate flags, collected in [`AssetResolver::copy_group`]
+/// alongside its path and zipped back onto the copied output there.
+struct ScriptFlags {
+    module: bool,
+    rehydrate: bool,
+}
+
 /// One candidate source for a declared asset, gathered from user overrides,
 /// package blocks, or the project-root convention.
 struct AssetEntry<'b> {
@@ -103,6 +124,7 @@ fn gather_entries<'b>(
             source: AssetSource::Package {
                 source_root: &pkg.source_root,
                 module: pkg.js_module,
+                rehydrate: pkg.js_rehydrate,
             },
         }));
     }
@@ -246,12 +268,19 @@ impl<'a> AssetResolver<'a> {
         };
 
         let mut sources: Vec<PathBuf> = Vec::new();
-        let mut modules: Vec<bool> = Vec::new();
+        // `module` and `rehydrate` travel together as one struct rather than a
+        // second parallel `Vec<bool>` (or an unlabelled `Vec<(bool, bool)>`), so
+        // the zip below reads as `flags.module` / `flags.rehydrate` instead of a
+        // positional `.0`/`.1`.
+        let mut flags: Vec<ScriptFlags> = Vec::new();
         for entry in &group.entries {
             let abs = group.root.join(entry.path);
             if abs.is_file() {
                 sources.push(abs);
-                modules.push(entry.source.module());
+                flags.push(ScriptFlags {
+                    module: entry.source.module(),
+                    rehydrate: entry.source.rehydrate(),
+                });
             } else if entry.source.warns_on_missing() {
                 warn!(
                     plugin = plugin.name(),
@@ -269,8 +298,8 @@ impl<'a> AssetResolver<'a> {
         outputs
             .into_iter()
             .zip(sources.iter())
-            .zip(modules.iter())
-            .map(|((abs, src), module)| {
+            .zip(flags.iter())
+            .map(|((abs, src), flags)| {
                 let rel = abs
                     .strip_prefix(self.plugin_output_dir)
                     .expect("copy_each output is always under plugin_output_dir")
@@ -287,7 +316,8 @@ impl<'a> AssetResolver<'a> {
                 seen_relative_paths.insert(rel.clone(), src.clone());
                 Ok(Asset {
                     config: asset_config.clone(),
-                    module: *module,
+                    module: flags.module,
+                    rehydrate: flags.rehydrate,
                     source_path: src.clone(),
                     resolved_path: abs,
                     built_relative_path: rel,
@@ -333,6 +363,7 @@ impl<'a> AssetResolver<'a> {
         Ok(Some(Asset {
             config: asset_config.clone(),
             module: false,
+            rehydrate: false,
             source_path: dest.clone(),
             resolved_path: dest,
             built_relative_path: rel,
@@ -684,6 +715,7 @@ mod tests {
             !AssetSource::Package {
                 source_root: Path::new("/tmp"),
                 module: false,
+                rehydrate: false,
             }
             .warns_on_missing()
         );
@@ -1149,6 +1181,7 @@ mod tests {
                 extra,
             },
             js_module: false,
+            js_rehydrate: false,
             source_root: pkg_dir.clone(),
         }];
 
@@ -1193,6 +1226,7 @@ mod tests {
                 extra,
             },
             js_module: false,
+            js_rehydrate: false,
             source_root: pkg_dir,
         }];
 
@@ -1246,6 +1280,7 @@ mod tests {
                 extra: pkg_extra,
             },
             js_module: false,
+            js_rehydrate: false,
             source_root: pkg_dir,
         }];
 
@@ -1307,6 +1342,7 @@ mod tests {
                 extra: pkg_extra,
             },
             js_module: false,
+            js_rehydrate: false,
             source_root: pkg_dir,
         }];
 
@@ -1370,6 +1406,7 @@ mod tests {
                 extra: pkg_extra,
             },
             js_module: false,
+            js_rehydrate: false,
             source_root: pkg_dir,
         }];
 
@@ -1439,6 +1476,7 @@ mod tests {
                 extra: pkg_extra,
             },
             js_module: false,
+            js_rehydrate: false,
             source_root: pkg_dir,
         }];
 
diff --git a/crates/core/src/html_dom.rs b/crates/core/src/html_dom.rs
index ca86f0df..310c0e80 100644
--- a/crates/core/src/html_dom.rs
+++ b/crates/core/src/html_dom.rs
@@ -396,13 +396,21 @@ impl Element {
     ///
     /// A module gets `type="module"` and NO `defer`: modules are deferred by
     /// default and `defer` is ignored on them, so emitting both would only
-    /// mislead a reader of the output.
+    /// mislead a reader of the output. A script whose package declared
+    /// `js_rehydrate = true` ALSO carries a bare `data-rheo-rehydrate`
+    /// attribute, regardless of which of those two forms it takes — the flag
+    /// is orthogonal to module vs. classic loading.
     pub fn create_script(script: &ScriptRef) -> Self {
+        let mut attrs: Vec<(&str, &str)> = vec![("src", &script.src)];
         if script.module {
-            Self::create_element("script", &[("src", &script.src), ("type", "module")])
+            attrs.push(("type", "module"));
         } else {
-            Self::create_element("script", &[("src", &script.src), ("defer", "")])
+            attrs.push(("defer", ""));
         }
+        if script.rehydrate {
+            attrs.push(("data-rheo-rehydrate", ""));
+        }
+        Self::create_element("script", &attrs)
     }
 
     /// Prepend a child element to this element.
@@ -727,9 +735,12 @@ pub fn depth_relative_refs(paths: &[String], output_rel_path: &str) -> Vec<Strin
 pub struct ScriptRef {
     pub src: String,
     pub module: bool,
+    /// Whether to stamp `data-rheo-rehydrate` on the emitted `<script>` tag.
+    pub rehydrate: bool,
 }
 
-/// [`depth_relative_refs`] for scripts, carrying each one's module flag through.
+/// [`depth_relative_refs`] for scripts, carrying each one's module and
+/// rehydrate flags through.
 pub fn depth_relative_scripts(scripts: &[ScriptRef], output_rel_path: &str) -> Vec<ScriptRef> {
     let prefix = depth_prefix(output_rel_path);
     scripts
@@ -737,6 +748,7 @@ pub fn depth_relative_scripts(scripts: &[ScriptRef], output_rel_path: &str) -> V
         .map(|s| ScriptRef {
             src: format!("{prefix}{}", s.src),
             module: s.module,
+            rehydrate: s.rehydrate,
         })
         .collect()
 }
@@ -970,6 +982,7 @@ mod tests {
         ScriptRef {
             src: src.to_string(),
             module: false,
+            rehydrate: false,
         }
     }
 
@@ -985,6 +998,7 @@ mod tests {
             &[ScriptRef {
                 src: "src/lib.js".to_string(),
                 module: true,
+                rehydrate: false,
             }],
         )
         .unwrap();
@@ -998,12 +1012,48 @@ mod tests {
         );
     }
 
+    /// A script flagged `js_rehydrate = true` carries a bare
+    /// `data-rheo-rehydrate` attribute — orthogonal to, and independent of,
+    /// whichever of the two forms above it also takes.
+    #[test]
+    fn test_inject_head_links_rehydrate_script() {
+        let html = "<!DOCTYPE html><html><head><title>Test</title></head><body></body></html>";
+        let mut dom = HtmlDom::parse(html).unwrap();
+        dom.inject_head_links(
+            &[],
+            &[],
+            &[ScriptRef {
+                src: "src/lib.js".to_string(),
+                module: false,
+                rehydrate: true,
+            }],
+        )
+        .unwrap();
+        let result = dom.serialize().unwrap();
+
+        assert!(result.contains(r#"src="src/lib.js""#));
+        assert!(result.contains("data-rheo-rehydrate"));
+    }
+
+    /// Without the flag, no `data-rheo-rehydrate` attribute is emitted at all.
+    #[test]
+    fn test_inject_head_links_without_rehydrate_omits_the_attribute() {
+        let html = "<!DOCTYPE html><html><head><title>Test</title></head><body></body></html>";
+        let mut dom = HtmlDom::parse(html).unwrap();
+        dom.inject_head_links(&[], &[], &[classic("index.js")])
+            .unwrap();
+        let result = dom.serialize().unwrap();
+
+        assert!(!result.contains("data-rheo-rehydrate"));
+    }
+
     #[test]
     fn test_depth_relative_scripts_keeps_the_module_flag() {
         let scripts = vec![
             ScriptRef {
                 src: "a.js".to_string(),
                 module: true,
+                rehydrate: false,
             },
             classic("b.js"),
         ];
@@ -1014,6 +1064,21 @@ mod tests {
         assert!(!out[1].module);
     }
 
+    #[test]
+    fn test_depth_relative_scripts_keeps_the_rehydrate_flag() {
+        let scripts = vec![
+            ScriptRef {
+                src: "a.js".to_string(),
+                module: false,
+                rehydrate: true,
+            },
+            classic("b.js"),
+        ];
+        let out = depth_relative_scripts(&scripts, "deep/page.html");
+        assert!(out[0].rehydrate);
+        assert!(!out[1].rehydrate);
+    }
+
     #[test]
     fn test_inject_head_links_scripts_with_stylesheets() {
         let html = "<!DOCTYPE html><html><head><title>Test</title></head><body></body></html>";
diff --git a/crates/core/src/packages/manifest.rs b/crates/core/src/packages/manifest.rs
index 1288627b..aea0f39a 100644
--- a/crates/core/src/packages/manifest.rs
+++ b/crates/core/src/packages/manifest.rs
@@ -182,6 +182,7 @@ impl PackageManifest {
             merged.assets.copy = source.assets.copy.clone();
         }
         merged.js_module = source.js_module;
+        merged.js_rehydrate = source.js_rehydrate;
         Some(merged)
     }
 
@@ -242,6 +243,10 @@ impl PackageManifest {
             .get("js_module")
             .and_then(|v| v.as_bool())
             .unwrap_or(false);
+        let js_rehydrate = section
+            .get("js_rehydrate")
+            .and_then(|v| v.as_bool())
+            .unwrap_or(false);
         let copy = section
             .get("copy")
             .and_then(|v| v.as_array())
@@ -266,6 +271,7 @@ impl PackageManifest {
             },
             source_root: self.pkg.source_root.clone(),
             js_module,
+            js_rehydrate,
         })
     }
 
@@ -819,7 +825,7 @@ css_stylesheet = "style.css"
             pkg_dir.join("typst.toml"),
             "[tool.rheo]\nmin_version = \"0.5.0\"\n\n[tool.rheo.html]\ncss_stylesheet = \"a.css\"\n\
              js_scripts = \"dist/lib.js\"\n\n[tool.rheo.source.html]\n\
-             js_scripts = [\"src/a.js\", \"src/b.js\"]\njs_module = true\n",
+             js_scripts = [\"src/a.js\", \"src/b.js\"]\njs_module = true\njs_rehydrate = true\n",
         )
         .unwrap();
         let pkg = make_resolved(&pkg_dir, "ns", "pkg", "1.0");
@@ -834,14 +840,17 @@ css_stylesheet = "style.css"
         // Release mode keeps the bundle and its classic tag.
         let release = manifest.assets_for("html", false).unwrap();
         assert!(!release.js_module);
+        assert!(!release.js_rehydrate);
         assert_eq!(
             release.assets.extra.get("js_scripts").unwrap().as_str(),
             Some("dist/lib.js"),
         );
 
-        // Source mode takes the unbundled list and asks for modules.
+        // Source mode takes the unbundled list, asks for modules, and flags
+        // them for client-side rehydration.
         let source = manifest.assets_for("html", true).unwrap();
         assert!(source.js_module);
+        assert!(source.js_rehydrate);
         assert_eq!(
             source
                 .assets
diff --git a/crates/core/src/plugins/mod.rs b/crates/core/src/plugins/mod.rs
index 7dec6ef3..0060fb56 100644
--- a/crates/core/src/plugins/mod.rs
+++ b/crates/core/src/plugins/mod.rs
@@ -77,6 +77,9 @@ pub struct Asset {
     /// Whether this script must be loaded as an ES module. Only ever true for a
     /// package's source-mode block, whose unbundled files use `import`.
     pub module: bool,
+    /// Whether this script carries `data-rheo-rehydrate` on its emitted `<script>`
+    /// tag. Set only by a package declaring `js_rehydrate = true`.
+    pub rehydrate: bool,
     /// Absolute path of the source file this asset was copied from.
     ///
     /// For user-declared assets this is under the project root; for
@@ -315,6 +318,9 @@ pub struct PackageAssets {
     pub source_root: PathBuf,
     /// Whether this block's scripts are ES modules (`js_module = true`).
     pub js_module: bool,
+    /// Whether this block's scripts should be rehydrated client-side
+    /// (`js_rehydrate = true`).
+    pub js_rehydrate: bool,
 }
 
 /// A resolved package specifier ready for asset block synthesis.
diff --git a/crates/html/src/lib.rs b/crates/html/src/lib.rs
index 47544f35..a94658af 100644
--- a/crates/html/src/lib.rs
+++ b/crates/html/src/lib.rs
@@ -229,6 +229,7 @@ impl LiveReload for HtmlPlugin {
             .map(|a| rheo_core::html_dom::ScriptRef {
                 src: a.built_relative_path.clone(),
                 module: a.module,
+                rehydrate: a.rehydrate,
             })
             .collect();
 
@@ -341,6 +342,7 @@ mod tests {
                 default_content: None,
             },
             module: false,
+            rehydrate: false,
             source_path: Path::new("/project").join(name),
             resolved_path: Path::new("/build/html").join(name),
             built_relative_path: name.to_string(),
diff --git a/crates/html/src/live/live-reload.js b/crates/html/src/live/live-reload.js
index ca80720a..d4b3d8a3 100644
--- a/crates/html/src/live/live-reload.js
+++ b/crates/html/src/live/live-reload.js
@@ -20,10 +20,41 @@ if (!window.__rheoLive) {
 
   source.addEventListener('reload', () => location.reload());
 
+  // IS THIS PAGE SAFE TO MORPH? Reusing a script tag is exactly what keeps one
+  // EventSource open above, and it is also what makes a morph WRONG for any
+  // page whose scripts built state the compiled HTML does not carry. Refetched
+  // page bytes are always the PRE-HYDRATION build output: a widget's input is
+  // empty, its buttons are unpressed, its rows are in build order, and the
+  // attribute its stylesheet keys off says "not ready". Morphing that over a
+  // live island reverts every one of those AND does not re-run the script that
+  // would set them again — the island is left drawn as though it had never
+  // booted, which is worse than the reload it replaced.
+  //
+  // So a script must DECLARE that it can rebuild its own state, by shipping
+  // under a package that sets `js_rehydrate = true` and pushing a callback
+  // onto `window.__rheoRehydrate` (see `docs/contract.md`). rheo renders a
+  // declaring script with `data-rheo-rehydrate`, and one undeclared script is
+  // enough to disqualify the page: a page is a single DOM, and morphing it for
+  // the sake of the widgets that cope would break the ones that do not.
+  //
+  // PER SCRIPT rather than per page, and read off the DOM rather than counted
+  // out of `__rheoRehydrate`, because the failure being avoided is the MIXED
+  // page — one migrated package and one not. A non-empty hook list says
+  // somebody can rehydrate, never that everybody can.
+  const morphable = () => {
+    for (const script of document.querySelectorAll('script[src]')) {
+      // This file, injected into every served page by `inject_live_reload_script`.
+      if (script.hasAttribute('data-rheo-live')) continue;
+      if (!script.hasAttribute('data-rheo-rehydrate')) return false;
+    }
+    return true;
+  };
+
   // A rebuild that touched only .typ sources: the page bytes are the whole
   // delta, so morphing them in preserves scroll, focus, selection, open
   // <details>, and media playback that a navigation would discard.
   source.addEventListener('morph', async () => {
+    if (!morphable()) return location.reload();
     try {
       const response = await fetch(location.href, { cache: 'no-store' });
       if (!response.ok) return location.reload();
@@ -37,7 +68,22 @@ if (!window.__rheoLive) {
         // writing.
         ignoreActiveValue: true,
       });
+      // CHECKED AGAIN, because the survey above ran against the OLD DOM. An
+      // edit that puts a new widget on the page brings its scripts in with it,
+      // and a <script> the morph INSERTS does execute — so a newly arrived
+      // island boots by itself. One that arrives undeclared, though, was never
+      // covered by the decision to morph, and the page is now the mixed case
+      // that decision existed to avoid.
+      if (!morphable()) return location.reload();
+      // THE HOOKS RUN AFTER THE MORPH, never before: they read the DOM they are
+      // rebuilding state onto, and the DOM they need is the one that just
+      // landed. Registered with `??=` at the far end, so this list exists
+      // whether or not this file loaded first.
+      for (const rehydrate of window.__rheoRehydrate ?? []) rehydrate();
     } catch (e) {
+      // COVERS THE HOOKS TOO. A hook that throws has left its island in an
+      // unknown state — half re-wired, or not at all — and a reload is the one
+      // recovery that does not depend on knowing which.
       console.warn('rheo: morph failed, reloading', e);
       location.reload();
     }
diff --git a/crates/html/src/server.rs b/crates/html/src/server.rs
index d1ee655d..5c46e17f 100644
--- a/crates/html/src/server.rs
+++ b/crates/html/src/server.rs
@@ -332,7 +332,12 @@ fn inject_live_reload_script(html: &[u8]) -> std::io::Result<Vec<u8>> {
 
     // Absolute path: the dev server serves the output dir as root, so this
     // resolves correctly from a page at any depth.
-    const SCRIPT: &str = r#"<script src="/.rheo/live.js"></script>"#;
+    //
+    // `data-rheo-live` MARKS THIS TAG AS RHEO'S OWN, because the client has to
+    // survey the page's other scripts to decide whether a morph is safe (see
+    // `live/live-reload.js`) and must not count itself among them. Matching on
+    // the `src` instead would tie that decision to this route's spelling.
+    const SCRIPT: &str = r#"<script src="/.rheo/live.js" data-rheo-live></script>"#;
 
     // Try to inject before </body>, fall back to end of document
     let modified = if let Some(pos) = html_str.rfind("</body>") {
diff --git a/docs/contract.md b/docs/contract.md
index 280190e7..cce9139a 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -196,6 +196,7 @@ never break the build):
 | --- | --- | --- | --- |
 | `[tool.rheo.<format>]` | `css_stylesheet` | `str` (path, relative to the package's own root) | Consulted only by plugins that declare an `AssetConfig` under that name — today only `html` (`crates/html/src/lib.rs:48`). |
 | `[tool.rheo.<format>]` | `js_scripts` | `str` (path) | Same as above (`crates/html/src/lib.rs:49`). |
+| `[tool.rheo.<format>]` | `js_rehydrate` | `bool`, default `false` | Declares that every script this block ships can rebuild its own state on demand, and registers itself to be asked. Renders the script tag with `data-rheo-rehydrate`, which is what admits the page to the dev server's morph path — see **Dev-server rehydrate protocol** below. Absent or `false` is the safe reading, not a defect. |
 | `[tool.rheo.<format>]` | `copy` | `array` of glob strings | Copied into that format's output dir for every format `manifest_blocks_for` is called with (html/pdf/epub alike), independent of whether that format defines named asset keys. |
 | `[tool.rheo]` | `min_version` | `str`, semver | A floor: if this build's own version is below it, `check_package_min_versions` fails the build, naming every offending import in one error (`crates/core/src/plugins/typst_manifest.rs:199-219`). Runs for every scanned `@`-import **unconditionally** — unlike asset/marrow auto-detection, it is *not* gated by the package auto-detect opt-out (`crates/core/src/build.rs:920-927`, called from both the full-build and dev-server-preview paths). Absent or unparseable → no floor, not an error. |
 
@@ -268,6 +269,67 @@ prefix is a hard build error naming the offending file and label
 canonical-label collision rule above (which silently skips injection instead
 of erroring).
 
+## Dev-server rehydrate protocol (`window.__rheoRehydrate`)
+
+`rheo watch` patches the live DOM on a content edit rather than navigating:
+a rebuild that touched only `.typ` sources broadcasts `morph`, and the client
+(`crates/html/src/live/live-reload.js`) refetches the page and morphs it in
+with Idiomorph, preserving scroll, focus, selection, open `<details>` and
+media playback. A rebuild that touched assets still broadcasts `reload`
+(`ReloadKind::for_change`, `crates/core/src/plugins/mod.rs`).
+
+**A morph does not re-execute the page's scripts.** Idiomorph reuses a
+byte-identical `<script src>` tag rather than re-adding it, and refetched page
+bytes are always the *pre-hydration* build output. So for any package whose
+script mutates the DOM at boot — pressing buttons the URL names, hiding
+filtered rows, setting the `data-…-ready` attribute a stylesheet keys off — a
+morph reverts all of that and re-runs nothing. Nothing throws; the island is
+simply left drawn as though it had never booted.
+
+The protocol that closes this has two halves, and a package needs both:
+
+1. **Declare it** — `js_rehydrate = true` in the package's
+   `[tool.rheo.<format>]` block. rheo renders the block's scripts with
+   `data-rheo-rehydrate`.
+2. **Register a callback** — `(window.__rheoRehydrate ??= []).push(fn)`. The
+   `??=` spelling is required rather than stylistic: load order between the
+   live client and a package's own module is not something either can assume.
+
+The client then surveys **every** `script[src]` on the page (bar its own,
+marked `data-rheo-live`) before morphing, and reloads instead if any one of
+them is undeclared. One undeclared script disqualifies the page: a page is a
+single DOM, and morphing it for the widgets that cope would break the ones
+that do not. A non-empty `__rheoRehydrate` says somebody can rehydrate, never
+that everybody can, which is why the gate reads the DOM and not the hook list.
+The survey runs again after the morph, because an edit that puts a new widget
+on a page brings its scripts in with it.
+
+Hooks run **after** the morph, in registration order, and a hook that throws
+triggers a reload — it has left its island half-wired, and a reload is the one
+recovery that does not depend on knowing how far it got.
+
+**No hook may depend on another hook having run first.** Registration order is
+script order, which is the order a *consuming project* imported the packages
+in — nothing a package can see or control. So a package that keeps a
+page-global registry must not have one hook clear it for the others: state
+shared across packages has to be reclaimable by each holder on its own
+evidence. `@rookery/search` does this by refusing a URL-key claim only when
+the element holding it is still in the document, which needs no agreement
+about order.
+
+What this asks of a hook is **idempotence on a morphed DOM**, which is a
+stronger requirement than "run again": Idiomorph mutates elements *in place*,
+so listeners bound to surviving nodes survive the morph and a naive re-wire
+double-fires. The shape that works is to scope each wiring to an
+`AbortController` kept on the container and abort the previous one first, and
+to make any module-level registry releasable rather than write-once. A package
+that has not done this work should leave `js_rehydrate` unset and take the
+reload.
+
+Stability: Experimental — the attribute name, the global's name and the
+one-undeclared-script-disqualifies rule are all new with the morph path, and
+no first-party package has migrated yet.
+
 ## Not part of this contract, on purpose
 
 - `@rheo/feeds`'s and `@rheo/rookery`'s own package-level API — see their own

From 1ebf974e1d1ef6788361040157a31a1a716fbd3e Mon Sep 17 00:00:00 2001
From: Lachlan Kermode <lachie@ohrg.org>
Date: Fri, 18 Sep 2026 12:04:35 +0200
Subject: [PATCH 2/2] Resolves a package's own package imports when collecting
 assets

A package that #imports another package now contributes that package's
declared css_stylesheet and js_scripts too, so a shared helper package works
by being depended on rather than by every consuming project repeating the
import. The asset scan walks the imported packages breadth-first from the
project's own imports until no new ones appear.

Specs a project imports directly keep their position ahead of anything reached
only through a package, because injection order is script execution order on
the page. An import cycle terminates, and a spec that resolves to no package
is skipped rather than failing a build that would otherwise have succeeded.
---
 crates/core/src/build.rs             |  14 ++-
 crates/core/src/packages/manifest.rs | 153 +++++++++++++++++++++++++++
 crates/core/src/packages/mod.rs      |   2 +-
 docs/contract.md                     |  23 ++++
 4 files changed, 186 insertions(+), 6 deletions(-)

diff --git a/crates/core/src/build.rs b/crates/core/src/build.rs
index 5c348028..467b9e53 100644
--- a/crates/core/src/build.rs
+++ b/crates/core/src/build.rs
@@ -292,7 +292,7 @@ impl Build {
         let default_section = PluginSection::default();
         let resolver = self.package_resolver();
         let packages = PackageIndex::resolved(
-            &crate::packages::scan_project_package_imports(&self.project.typ_files),
+            &crate::packages::scan_transitive_package_imports(&self.project.typ_files, &resolver),
             &resolver,
         );
 
@@ -922,9 +922,11 @@ impl Build {
             .get(serving_plugin.name())
             .unwrap_or(&default_section);
         let (packages, package_resolver) = self.timed(phase::PACKAGES, None, || {
-            let package_imports =
-                crate::packages::scan_project_package_imports(&self.project.typ_files);
             let resolver = self.package_resolver();
+            let package_imports = crate::packages::scan_transitive_package_imports(
+                &self.project.typ_files,
+                &resolver,
+            );
             let packages = prewarm_and_resolve(
                 &package_imports,
                 plugin_section.auto_detect_packages.get(),
@@ -1161,9 +1163,11 @@ impl Build {
         // package (a directory probe plus a `typst.toml` parse) once — both
         // shared across every plugin in this build.
         let packages = self.timed(phase::PACKAGES, None, || {
-            let package_imports =
-                crate::packages::scan_project_package_imports(&self.project.typ_files);
             let resolver = self.package_resolver();
+            let package_imports = crate::packages::scan_transitive_package_imports(
+                &self.project.typ_files,
+                &resolver,
+            );
             let packages =
                 prewarm_and_resolve(&package_imports, self.auto_detects_packages(), &resolver)?;
             Ok::<_, RheoError>((packages, resolver))
diff --git a/crates/core/src/packages/manifest.rs b/crates/core/src/packages/manifest.rs
index aea0f39a..c4678979 100644
--- a/crates/core/src/packages/manifest.rs
+++ b/crates/core/src/packages/manifest.rs
@@ -2,6 +2,7 @@ use crate::config::PluginAssets;
 use crate::packages::PackageResolver;
 use crate::parser::ImportInfo;
 use crate::plugins::{PackageAssets, ResolvedPackage, parse_package_spec};
+use crate::reticulate::SpineScan;
 use crate::{Result, RheoError};
 use std::collections::HashSet;
 use std::path::{Path, PathBuf};
@@ -51,6 +52,58 @@ pub fn scan_project_package_imports(typ_files: &[PathBuf]) -> Vec<String> {
     result
 }
 
+/// Scans `typ_files` for package imports, then follows each imported package's
+/// own package imports to a fixed point, so a package's dependency contributes
+/// its assets without the consuming project repeating the import.
+///
+/// The project's own specs come first and encounter order is otherwise
+/// preserved: asset injection order is script execution order on the page, so
+/// reaching a package only transitively must never reorder the scripts a
+/// project already had. A spec that resolves to no directory is skipped, as an
+/// unreadable `.typ` is — a transitive dependency rheo cannot locate must not
+/// fail a build that would otherwise have succeeded.
+pub fn scan_transitive_package_imports(
+    typ_files: &[PathBuf],
+    resolver: &PackageResolver,
+) -> Vec<String> {
+    scan_transitive_in(typ_files, resolver, &typst_package_search_dirs(None))
+}
+
+/// [`scan_transitive_package_imports`] against explicit search directories.
+fn scan_transitive_in(
+    typ_files: &[PathBuf],
+    resolver: &PackageResolver,
+    search_dirs: &[PathBuf],
+) -> Vec<String> {
+    let mut specs = scan_project_package_imports(typ_files);
+    // `specs` doubles as the breadth-first queue. A spec enters it only by
+    // passing the `seen` guard, so it is descended into at most once and two
+    // packages importing each other terminate.
+    let mut seen: HashSet<String> = specs.iter().cloned().collect();
+    let mut next = 0;
+    while next < specs.len() {
+        let spec = specs[next].clone();
+        next += 1;
+        let Some(pkg) = resolve_package(&spec, resolver, search_dirs) else {
+            debug!(spec = %spec, "package did not resolve; its own imports contribute nothing");
+            continue;
+        };
+        let package_files = match SpineScan::typ_files(&pkg.source_root) {
+            Ok(files) => files,
+            Err(e) => {
+                warn!(spec = %spec, error = %e, "could not walk a package for its own imports");
+                continue;
+            }
+        };
+        for path in scan_project_package_imports(&package_files) {
+            if seen.insert(path.clone()) {
+                specs.push(path);
+            }
+        }
+    }
+    specs
+}
+
 /// Probe `search_dirs` (in order) for `{namespace}/{name}/{version}/`.
 /// Returns the resolved package directory the first time it's found.
 pub fn find_package_in_dirs(spec: &str, search_dirs: &[PathBuf]) -> Option<ResolvedPackage> {
@@ -613,6 +666,106 @@ mod tests {
         assert_eq!(result, vec!["@preview/tablex:0.0.6"]);
     }
 
+    /// A resolver with no `[packages]` table, so every namespace resolves by
+    /// probing the search directories.
+    fn unconfigured_resolver() -> PackageResolver {
+        PackageResolver::new(&std::collections::HashMap::new())
+    }
+
+    /// Lays down `{ns}/{name}/{version}/lib.typ` under `base` containing `body`.
+    fn make_pkg_source(
+        base: &std::path::Path,
+        ns: &str,
+        name: &str,
+        version: &str,
+        body: &str,
+    ) -> PathBuf {
+        let dir = make_pkg_dir(base, ns, name, version);
+        std::fs::write(dir.join("lib.typ"), body).unwrap();
+        dir
+    }
+
+    #[test]
+    fn package_own_import_contributes_its_spec() {
+        let dir = tempfile::tempdir().unwrap();
+        let project = dir.path().join("project.typ");
+        std::fs::write(&project, r#"#import "@ns/outer:1.0.0": *"#).unwrap();
+        let pkgs = dir.path().join("pkgs");
+        make_pkg_source(
+            &pkgs,
+            "ns",
+            "outer",
+            "1.0.0",
+            r#"#import "@ns/inner:2.0.0": *"#,
+        );
+        make_pkg_source(&pkgs, "ns", "inner", "2.0.0", "#let x = 1");
+        let result = scan_transitive_in(&[project], &unconfigured_resolver(), &[pkgs]);
+        assert_eq!(result, vec!["@ns/outer:1.0.0", "@ns/inner:2.0.0"]);
+    }
+
+    #[test]
+    fn project_specs_precede_transitive_ones() {
+        let dir = tempfile::tempdir().unwrap();
+        let project = dir.path().join("project.typ");
+        std::fs::write(
+            &project,
+            "#import \"@ns/outer:1.0.0\": *\n#import \"@ns/last:1.0.0\": *",
+        )
+        .unwrap();
+        let pkgs = dir.path().join("pkgs");
+        make_pkg_source(
+            &pkgs,
+            "ns",
+            "outer",
+            "1.0.0",
+            r#"#import "@ns/inner:2.0.0": *"#,
+        );
+        make_pkg_source(&pkgs, "ns", "inner", "2.0.0", "#let x = 1");
+        make_pkg_source(&pkgs, "ns", "last", "1.0.0", "#let y = 2");
+        let result = scan_transitive_in(&[project], &unconfigured_resolver(), &[pkgs]);
+        assert_eq!(
+            result,
+            vec!["@ns/outer:1.0.0", "@ns/last:1.0.0", "@ns/inner:2.0.0"]
+        );
+    }
+
+    #[test]
+    fn import_cycle_terminates() {
+        let dir = tempfile::tempdir().unwrap();
+        let project = dir.path().join("project.typ");
+        std::fs::write(&project, r#"#import "@ns/a:1.0.0": *"#).unwrap();
+        let pkgs = dir.path().join("pkgs");
+        make_pkg_source(&pkgs, "ns", "a", "1.0.0", r#"#import "@ns/b:1.0.0": *"#);
+        make_pkg_source(&pkgs, "ns", "b", "1.0.0", r#"#import "@ns/a:1.0.0": *"#);
+        let result = scan_transitive_in(&[project], &unconfigured_resolver(), &[pkgs]);
+        assert_eq!(result, vec!["@ns/a:1.0.0", "@ns/b:1.0.0"]);
+    }
+
+    #[test]
+    fn unresolvable_spec_skipped_without_error() {
+        let dir = tempfile::tempdir().unwrap();
+        let project = dir.path().join("project.typ");
+        std::fs::write(
+            &project,
+            "#import \"@ns/missing:1.0.0\": *\n#import \"@ns/present:1.0.0\": *",
+        )
+        .unwrap();
+        let pkgs = dir.path().join("pkgs");
+        make_pkg_source(
+            &pkgs,
+            "ns",
+            "present",
+            "1.0.0",
+            r#"#import "@ns/deep:1.0.0": *"#,
+        );
+        make_pkg_source(&pkgs, "ns", "deep", "1.0.0", "#let x = 1");
+        let result = scan_transitive_in(&[project], &unconfigured_resolver(), &[pkgs]);
+        assert_eq!(
+            result,
+            vec!["@ns/missing:1.0.0", "@ns/present:1.0.0", "@ns/deep:1.0.0"]
+        );
+    }
+
     #[test]
     fn parse_package_spec_valid() {
         assert_eq!(
diff --git a/crates/core/src/packages/mod.rs b/crates/core/src/packages/mod.rs
index f10e4aba..bbf992ba 100644
--- a/crates/core/src/packages/mod.rs
+++ b/crates/core/src/packages/mod.rs
@@ -21,7 +21,7 @@ mod path;
 pub use git::GitPackages;
 pub use manifest::{
     PackageIndex, find_package_in_dirs, manifest_package_assets, prewarm_packages,
-    scan_project_package_imports, typst_package_search_dirs,
+    scan_project_package_imports, scan_transitive_package_imports, typst_package_search_dirs,
 };
 pub use path::PathPackages;
 
diff --git a/docs/contract.md b/docs/contract.md
index cce9139a..5e75b2e8 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -346,3 +346,26 @@ package does. `AssetResolver::resolve`
 user-declared pairs alone, so a package dependency — an additive third scope,
 outside the CLI > `rheo.toml` > defaults chain — cannot answer the question of
 whether the project overrode its own default.
+
+### Transitive package imports
+
+The scan that finds package assets is **transitive**: a package's own
+`@`-imports contribute their declared assets too. A project importing
+`@rheo/notebox` gets the assets of whatever `@rheo/notebox` itself imports,
+without repeating that import in its own content. This is what makes a shared
+helper package possible — a package can depend on one without every consuming
+project having to know it exists.
+
+The order is **project-first, then transitive**: every spec a project imports
+directly keeps its position ahead of anything reached only through a package,
+and within each level first sight wins. Asset injection order is script
+execution order on the page, so adding a dependency to a package can never
+reorder the scripts a project already had.
+
+A transitive spec that resolves to no package is **skipped silently**. A
+dependency rheo cannot locate costs that package's assets and nothing else; it
+never fails a build that would otherwise have succeeded. Discovering a
+package's own imports means reading its `.typ` files, so a package must be on
+disk to be descended into — a namespace served from a releases host therefore
+contributes its transitive dependencies from the build after the one that first
+cached it.