From 2720f105f1dfbd23708dbe43028e03a963c14df0 Mon Sep 17 00:00:00 2001
From: Pierre Le Fevre <hello@pierrelf.com>
Date: Fri, 27 Mar 2026 22:21:12 +0100
Subject: [PATCH] Implement script element loading and execution (defer, async)

Add script execution to the page loading pipeline: after HTML parsing,
walk the DOM for <script> elements and execute them in a shared JS VM
with full DOM access. Scripts can modify the DOM before CSS/image
collection.

Key changes:
- New script_loader module: discovers scripts in document order,
  fetches external scripts, handles defer/async/type attributes
- VM.detach_document(): reclaim Document after script execution
- Top-level var declarations now emit StoreGlobal so variables
  persist across multiple execute() calls (shared global scope)
- Resource::Script variant for JavaScript MIME types
- Exhaustive match updates in css_loader and img_loader

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 crates/browser/src/css_loader.rs    |   1 +
 crates/browser/src/img_loader.rs    |   4 +-
 crates/browser/src/lib.rs           |   1 +
 crates/browser/src/loader.rs        |  19 ++
 crates/browser/src/main.rs          |   9 +-
 crates/browser/src/script_loader.rs | 491 ++++++++++++++++++++++++++++
 crates/js/src/compiler.rs           |  18 +
 crates/js/src/vm.rs                 |  18 +
 8 files changed, 558 insertions(+), 3 deletions(-)
 create mode 100644 crates/browser/src/script_loader.rs

diff --git a/crates/browser/src/css_loader.rs b/crates/browser/src/css_loader.rs
index 301adb9..37c87ba 100644
--- a/crates/browser/src/css_loader.rs
+++ b/crates/browser/src/css_loader.rs
@@ -208,6 +208,7 @@ fn fetch_stylesheet(
                 }
             }
         }
+        Resource::Script { text, url } => (text, url),
         Resource::Image { .. } => {
             return Err(CssLoadError::NotCss {
                 url: href.to_string(),
diff --git a/crates/browser/src/img_loader.rs b/crates/browser/src/img_loader.rs
index 4d0cb0b..4bcc56e 100644
--- a/crates/browser/src/img_loader.rs
+++ b/crates/browser/src/img_loader.rs
@@ -227,7 +227,9 @@ fn fetch_and_decode(
         Resource::Image { data, url, .. } => (data, url.to_string()),
         Resource::Other { data, url, .. } => (data, url.to_string()),
         Resource::Html { text, .. } => (text.into_bytes(), src.to_string()),
-        Resource::Css { text, .. } => (text.into_bytes(), src.to_string()),
+        Resource::Css { text, .. } | Resource::Script { text, .. } => {
+            (text.into_bytes(), src.to_string())
+        }
     };
 
     decode_image_data(&data, &url_str)
diff --git a/crates/browser/src/lib.rs b/crates/browser/src/lib.rs
index b5ba26a..2cbb3d4 100644
--- a/crates/browser/src/lib.rs
+++ b/crates/browser/src/lib.rs
@@ -3,3 +3,4 @@
 pub mod css_loader;
 pub mod img_loader;
 pub mod loader;
+pub mod script_loader;
diff --git a/crates/browser/src/loader.rs b/crates/browser/src/loader.rs
index f4c0097..2d95b10 100644
--- a/crates/browser/src/loader.rs
+++ b/crates/browser/src/loader.rs
@@ -70,6 +70,8 @@ pub enum Resource {
         mime_type: String,
         url: Url,
     },
+    /// A JavaScript script.
+    Script { text: String, url: Url },
     /// Any other resource type (binary).
     Other {
         data: Vec<u8>,
@@ -147,6 +149,14 @@ impl ResourceLoader {
                     url: url.clone(),
                 })
             }
+            MimeClass::Script => {
+                let (text, _encoding) =
+                    decode_text_resource(&response.body, content_type.as_ref(), false);
+                Ok(Resource::Script {
+                    text,
+                    url: url.clone(),
+                })
+            }
             MimeClass::Image => Ok(Resource::Image {
                 data: response.body,
                 mime_type: mime.to_string(),
@@ -212,6 +222,7 @@ impl Default for ResourceLoader {
 enum MimeClass {
     Html,
     Css,
+    Script,
     Image,
     Other,
 }
@@ -220,6 +231,9 @@ fn classify_mime(mime: &str) -> MimeClass {
     match mime {
         "text/html" | "application/xhtml+xml" => MimeClass::Html,
         "text/css" => MimeClass::Css,
+        "text/javascript" | "application/javascript" | "application/x-javascript" => {
+            MimeClass::Script
+        }
         "image/png" | "image/jpeg" | "image/gif" | "image/webp" | "image/svg+xml" => {
             MimeClass::Image
         }
@@ -315,6 +329,11 @@ fn fetch_data_url(url_str: &str) -> Result<Resource, LoadError> {
             let text = we_encoding::decode(&parsed.data, encoding);
             Ok(Resource::Css { text, url })
         }
+        MimeClass::Script => {
+            let encoding = charset_to_encoding(parsed.charset.as_deref());
+            let text = we_encoding::decode(&parsed.data, encoding);
+            Ok(Resource::Script { text, url })
+        }
         MimeClass::Image => Ok(Resource::Image {
             data: parsed.data,
             mime_type: mime.to_string(),
diff --git a/crates/browser/src/main.rs b/crates/browser/src/main.rs
index 114c22a..0c07899 100644
--- a/crates/browser/src/main.rs
+++ b/crates/browser/src/main.rs
@@ -4,6 +4,7 @@ use std::collections::HashMap;
 use we_browser::css_loader::collect_stylesheets;
 use we_browser::img_loader::{collect_images, ImageStore};
 use we_browser::loader::{Resource, ResourceLoader, ABOUT_BLANK_HTML};
+use we_browser::script_loader::execute_page_scripts;
 use we_css::parser::Stylesheet;
 use we_dom::{Document, NodeId};
 use we_html::parse_html;
@@ -276,12 +277,16 @@ fn error_page(message: &str) -> LoadedHtml {
     }
 }
 
-/// Load a page: fetch HTML, parse DOM, collect CSS and images.
+/// Load a page: fetch HTML, parse DOM, execute scripts, collect CSS and images.
 fn load_page(loaded: LoadedHtml) -> PageState {
     let doc = parse_html(&loaded.text);
 
-    // Fetch external stylesheets and merge with inline <style> elements.
+    // Execute <script> elements. Scripts may modify the DOM, so this must
+    // run before collecting CSS and images (which depend on DOM structure).
     let mut loader = ResourceLoader::new();
+    let doc = execute_page_scripts(doc, &mut loader, &loaded.base_url);
+
+    // Fetch external stylesheets and merge with inline <style> elements.
     let stylesheet = collect_stylesheets(&doc, &mut loader, &loaded.base_url);
 
     // Fetch and decode images referenced by <img> elements.
diff --git a/crates/browser/src/script_loader.rs b/crates/browser/src/script_loader.rs
new file mode 100644
index 0000000..a6100cd
--- /dev/null
+++ b/crates/browser/src/script_loader.rs
@@ -0,0 +1,491 @@
+//! Script element loading and execution.
+//!
+//! Walks the DOM for `<script>` elements, fetches external scripts, and
+//! executes them in a shared JS VM with DOM access.
+
+use crate::loader::{Resource, ResourceLoader};
+use we_dom::{Document, NodeId};
+use we_js::compiler;
+use we_js::parser::Parser;
+use we_js::vm::Vm;
+use we_url::Url;
+
+/// Information about a `<script>` element extracted from the DOM.
+struct ScriptInfo {
+    /// Inline script text (from child text nodes).
+    text: Option<String>,
+    /// `src` attribute value (external script URL).
+    src: Option<String>,
+    /// Whether the `defer` attribute is present.
+    defer: bool,
+    /// Whether the `async` attribute is present.
+    async_attr: bool,
+    /// The `type` attribute value, if any.
+    type_attr: Option<String>,
+}
+
+/// Returns true if a script's `type` attribute indicates it should execute.
+///
+/// Per spec, scripts execute if there is no type attribute or if the type
+/// is a JavaScript MIME type. Unknown types are not executed.
+fn should_execute(type_attr: &Option<String>) -> bool {
+    match type_attr {
+        None => true,
+        Some(t) => {
+            let t = t.trim().to_ascii_lowercase();
+            t.is_empty()
+                || t == "text/javascript"
+                || t == "application/javascript"
+                || t == "application/x-javascript"
+                || t == "text/ecmascript"
+                || t == "application/ecmascript"
+        }
+    }
+}
+
+/// Collect text content from child text nodes of an element.
+fn collect_text_content(doc: &Document, node: NodeId) -> String {
+    let mut text = String::new();
+    for child in doc.children(node) {
+        if let Some(data) = doc.text_content(child) {
+            text.push_str(data);
+        }
+    }
+    text
+}
+
+/// Walk the DOM tree in document order, collecting `<script>` elements.
+fn collect_script_nodes(doc: &Document, node: NodeId, result: &mut Vec<NodeId>) {
+    if doc.tag_name(node) == Some("script") {
+        result.push(node);
+    }
+    for child in doc.children(node) {
+        collect_script_nodes(doc, child, result);
+    }
+}
+
+/// Extract script info from a `<script>` element node.
+fn extract_script_info(doc: &Document, node: NodeId) -> ScriptInfo {
+    let src = doc.get_attribute(node, "src").map(|s| s.to_string());
+    let defer = doc.get_attribute(node, "defer").is_some();
+    let async_attr = doc.get_attribute(node, "async").is_some();
+    let type_attr = doc.get_attribute(node, "type").map(|s| s.to_string());
+
+    let text = if src.is_none() {
+        let content = collect_text_content(doc, node);
+        if content.is_empty() {
+            None
+        } else {
+            Some(content)
+        }
+    } else {
+        None
+    };
+
+    ScriptInfo {
+        text,
+        src,
+        defer,
+        async_attr,
+        type_attr,
+    }
+}
+
+/// Fetch the text of an external script.
+fn fetch_script_text(loader: &mut ResourceLoader, src: &str, base_url: &Url) -> Option<String> {
+    match loader.fetch_url(src, Some(base_url)) {
+        Ok(Resource::Script { text, .. }) => Some(text),
+        Ok(Resource::Other { data, .. }) => {
+            // Try decoding as UTF-8 (servers may not set correct MIME type).
+            String::from_utf8(data).ok()
+        }
+        Ok(_) => {
+            eprintln!("[script] unexpected resource type for {src}");
+            None
+        }
+        Err(e) => {
+            eprintln!("[script] failed to fetch {src}: {e}");
+            None
+        }
+    }
+}
+
+/// Compile and execute a script in the VM. Errors are logged, not propagated.
+fn execute_script(vm: &mut Vm, source: &str, label: &str) {
+    let ast = match Parser::parse(source) {
+        Ok(ast) => ast,
+        Err(e) => {
+            eprintln!("[script] parse error in {label}: {e}");
+            return;
+        }
+    };
+
+    let func = match compiler::compile(&ast) {
+        Ok(f) => f,
+        Err(e) => {
+            eprintln!("[script] compile error in {label}: {e}");
+            return;
+        }
+    };
+
+    if let Err(e) = vm.execute(&func) {
+        eprintln!("[script] runtime error in {label}: {e}");
+    }
+}
+
+/// Execute all `<script>` elements on the page.
+///
+/// Takes ownership of the DOM `Document`, creates a JS VM with DOM access,
+/// executes scripts in document order (respecting `defer` and `async`
+/// attributes), then returns the (possibly modified) document.
+///
+/// Script execution order:
+/// 1. Synchronous scripts (no `defer`/`async`): execute in document order,
+///    blocking further script processing.
+/// 2. Deferred scripts (`defer`): execute after all synchronous scripts,
+///    in document order.
+/// 3. Async scripts (`async`): execute as soon as fetched; for synchronous
+///    fetching this is equivalent to document order.
+///
+/// Scripts with an unrecognized `type` attribute are skipped.
+/// Errors in one script do not prevent other scripts from running.
+pub fn execute_page_scripts(
+    doc: Document,
+    loader: &mut ResourceLoader,
+    base_url: &Url,
+) -> Document {
+    // Find all <script> elements in document order.
+    let mut script_nodes = Vec::new();
+    let root = doc.root();
+    collect_script_nodes(&doc, root, &mut script_nodes);
+
+    // Extract script info and classify.
+    let scripts: Vec<(NodeId, ScriptInfo)> = script_nodes
+        .into_iter()
+        .map(|node| (node, extract_script_info(&doc, node)))
+        .filter(|(_, info)| should_execute(&info.type_attr))
+        .collect();
+
+    if scripts.is_empty() {
+        return doc;
+    }
+
+    // Create VM with DOM access.
+    let mut vm = Vm::new();
+    vm.attach_document(doc);
+
+    // Separate into immediate (sync + async) and deferred scripts.
+    let mut deferred_sources: Vec<(String, String)> = Vec::new();
+
+    for (_node, info) in &scripts {
+        // Resolve the script source text.
+        let (source, label) = if let Some(ref src) = info.src {
+            // External script: fetch it.
+            match fetch_script_text(loader, src, base_url) {
+                Some(text) => (text, src.clone()),
+                None => continue,
+            }
+        } else if let Some(ref text) = info.text {
+            (text.clone(), "<inline>".to_string())
+        } else {
+            continue;
+        };
+
+        if info.defer && !info.async_attr && info.src.is_some() {
+            // Deferred external scripts: queue for later execution.
+            // Per spec, defer only applies to external scripts and is
+            // ignored when async is also present.
+            deferred_sources.push((source, label));
+        } else {
+            // Synchronous and async scripts: execute immediately.
+            // Async scripts have no ordering guarantee, but since we
+            // fetch synchronously they execute in document order.
+            execute_script(&mut vm, &source, &label);
+        }
+    }
+
+    // Execute deferred scripts in document order.
+    for (source, label) in &deferred_sources {
+        execute_script(&mut vm, source, label);
+    }
+
+    // Pump the event loop to handle any pending microtasks/timers.
+    let _ = vm.pump_event_loop();
+
+    // Take the document back from the VM.
+    vm.detach_document().unwrap_or_default()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use we_html::parse_html;
+
+    /// Helper: parse HTML, execute scripts, return the document.
+    fn run_scripts(html: &str) -> Document {
+        let doc = parse_html(html);
+        let mut loader = ResourceLoader::new();
+        let base_url = Url::parse("about:blank").unwrap();
+        execute_page_scripts(doc, &mut loader, &base_url)
+    }
+
+    #[test]
+    fn test_no_scripts() {
+        let doc = run_scripts("<html><body><p>Hello</p></body></html>");
+        // Should return the document unchanged.
+        assert!(doc.tag_name(doc.root()).is_none()); // root is Document node
+    }
+
+    #[test]
+    fn test_inline_script_executes() {
+        // Script that modifies a DOM element's text content.
+        let html = r#"<html><body>
+            <div id="target">before</div>
+            <script>
+                var el = document.getElementById("target");
+                el.textContent = "after";
+            </script>
+        </body></html>"#;
+        let doc = run_scripts(html);
+
+        // Find the div and check its text content was modified.
+        let mut found = false;
+        fn find_div(doc: &Document, node: NodeId, found: &mut bool) {
+            if doc.tag_name(node) == Some("div") {
+                if doc.get_attribute(node, "id") == Some("target") {
+                    // Check child text node.
+                    for child in doc.children(node) {
+                        if let Some(text) = doc.text_content(child) {
+                            if text == "after" {
+                                *found = true;
+                            }
+                        }
+                    }
+                }
+            }
+            for child in doc.children(node) {
+                find_div(doc, child, found);
+            }
+        }
+        find_div(&doc, doc.root(), &mut found);
+        assert!(found, "script should have modified div text to 'after'");
+    }
+
+    #[test]
+    fn test_multiple_scripts_share_scope() {
+        let html = r#"<html><body>
+            <script>var x = 42;</script>
+            <script>var y = x + 1;</script>
+            <div id="result">placeholder</div>
+            <script>
+                document.getElementById("result").textContent = String(y);
+            </script>
+        </body></html>"#;
+        let doc = run_scripts(html);
+
+        fn find_result(doc: &Document, node: NodeId) -> Option<String> {
+            if doc.tag_name(node) == Some("div") {
+                if doc.get_attribute(node, "id") == Some("result") {
+                    for child in doc.children(node) {
+                        if let Some(text) = doc.text_content(child) {
+                            return Some(text.to_string());
+                        }
+                    }
+                }
+            }
+            for child in doc.children(node) {
+                if let Some(result) = find_result(doc, child) {
+                    return Some(result);
+                }
+            }
+            None
+        }
+
+        let result = find_result(&doc, doc.root());
+        assert_eq!(result.as_deref(), Some("43"));
+    }
+
+    #[test]
+    fn test_unknown_type_not_executed() {
+        let html = r#"<html><body>
+            <div id="target">original</div>
+            <script type="text/template">
+                document.getElementById("target").textContent = "changed";
+            </script>
+        </body></html>"#;
+        let doc = run_scripts(html);
+
+        fn find_target(doc: &Document, node: NodeId) -> Option<String> {
+            if doc.tag_name(node) == Some("div") {
+                if doc.get_attribute(node, "id") == Some("target") {
+                    for child in doc.children(node) {
+                        if let Some(text) = doc.text_content(child) {
+                            return Some(text.to_string());
+                        }
+                    }
+                }
+            }
+            for child in doc.children(node) {
+                if let Some(result) = find_target(doc, child) {
+                    return Some(result);
+                }
+            }
+            None
+        }
+
+        let result = find_target(&doc, doc.root());
+        assert_eq!(result.as_deref(), Some("original"));
+    }
+
+    #[test]
+    fn test_type_text_javascript_executes() {
+        let html = r#"<html><body>
+            <div id="target">before</div>
+            <script type="text/javascript">
+                document.getElementById("target").textContent = "after";
+            </script>
+        </body></html>"#;
+        let doc = run_scripts(html);
+
+        fn find_target(doc: &Document, node: NodeId) -> Option<String> {
+            if doc.tag_name(node) == Some("div") {
+                if doc.get_attribute(node, "id") == Some("target") {
+                    for child in doc.children(node) {
+                        if let Some(text) = doc.text_content(child) {
+                            return Some(text.to_string());
+                        }
+                    }
+                }
+            }
+            for child in doc.children(node) {
+                if let Some(result) = find_target(doc, child) {
+                    return Some(result);
+                }
+            }
+            None
+        }
+
+        let result = find_target(&doc, doc.root());
+        assert_eq!(result.as_deref(), Some("after"));
+    }
+
+    #[test]
+    fn test_script_error_does_not_crash() {
+        // A script with a runtime error should not prevent subsequent scripts.
+        let html = r#"<html><body>
+            <div id="target">before</div>
+            <script>
+                undefinedFunction();
+            </script>
+            <script>
+                document.getElementById("target").textContent = "after";
+            </script>
+        </body></html>"#;
+        let doc = run_scripts(html);
+
+        fn find_target(doc: &Document, node: NodeId) -> Option<String> {
+            if doc.tag_name(node) == Some("div") {
+                if doc.get_attribute(node, "id") == Some("target") {
+                    for child in doc.children(node) {
+                        if let Some(text) = doc.text_content(child) {
+                            return Some(text.to_string());
+                        }
+                    }
+                }
+            }
+            for child in doc.children(node) {
+                if let Some(result) = find_target(doc, child) {
+                    return Some(result);
+                }
+            }
+            None
+        }
+
+        let result = find_target(&doc, doc.root());
+        assert_eq!(result.as_deref(), Some("after"));
+    }
+
+    #[test]
+    fn test_empty_script_no_crash() {
+        let doc = run_scripts("<html><body><script></script></body></html>");
+        assert!(!doc.is_empty());
+    }
+
+    #[test]
+    fn test_defer_scripts_run_after_sync() {
+        // In our parse-first model, both sync and defer run after parsing.
+        // defer scripts with src are queued; defer inline scripts are treated
+        // as sync. Without external script loading in tests, we verify that
+        // defer inline scripts still execute (treated as sync per spec —
+        // defer only applies to external scripts).
+        let html = r#"<html><body>
+            <div id="result">0</div>
+            <script defer>
+                var counter = 1;
+            </script>
+            <script>
+                document.getElementById("result").textContent = String(counter);
+            </script>
+        </body></html>"#;
+        let doc = run_scripts(html);
+
+        fn find_result(doc: &Document, node: NodeId) -> Option<String> {
+            if doc.tag_name(node) == Some("div") {
+                if doc.get_attribute(node, "id") == Some("result") {
+                    for child in doc.children(node) {
+                        if let Some(text) = doc.text_content(child) {
+                            return Some(text.to_string());
+                        }
+                    }
+                }
+            }
+            for child in doc.children(node) {
+                if let Some(result) = find_result(doc, child) {
+                    return Some(result);
+                }
+            }
+            None
+        }
+
+        let result = find_result(&doc, doc.root());
+        // defer on inline scripts is ignored per spec, so counter=1 runs first
+        assert_eq!(result.as_deref(), Some("1"));
+    }
+
+    #[test]
+    fn test_script_create_element() {
+        let html = r#"<html><body>
+            <div id="container"></div>
+            <script>
+                var div = document.createElement("p");
+                div.textContent = "dynamic";
+                document.getElementById("container").appendChild(div);
+            </script>
+        </body></html>"#;
+        let doc = run_scripts(html);
+
+        // Check that a <p> was added inside #container.
+        fn find_dynamic(doc: &Document, node: NodeId) -> bool {
+            if doc.tag_name(node) == Some("div") {
+                if doc.get_attribute(node, "id") == Some("container") {
+                    for child in doc.children(node) {
+                        if doc.tag_name(child) == Some("p") {
+                            return true;
+                        }
+                    }
+                }
+            }
+            for child in doc.children(node) {
+                if find_dynamic(doc, child) {
+                    return true;
+                }
+            }
+            false
+        }
+
+        assert!(
+            find_dynamic(&doc, doc.root()),
+            "script should have appended a <p> to #container"
+        );
+    }
+}
diff --git a/crates/js/src/compiler.rs b/crates/js/src/compiler.rs
index 5b81bce..23a3a36 100644
--- a/crates/js/src/compiler.rs
+++ b/crates/js/src/compiler.rs
@@ -23,6 +23,9 @@ struct FunctionCompiler {
     /// Set of local variable names that are captured by inner functions.
     /// Pre-populated before compilation by scanning inner function bodies.
     captured_names: HashSet<String>,
+    /// True for the top-level script scope. Top-level `var` declarations
+    /// are also stored as globals so they persist across `execute()` calls.
+    is_top_level: bool,
 }
 
 #[derive(Debug, Clone)]
@@ -63,6 +66,7 @@ impl FunctionCompiler {
             loop_stack: Vec::new(),
             upvalues: Vec::new(),
             captured_names: HashSet::new(),
+            is_top_level: false,
         }
     }
 
@@ -707,6 +711,7 @@ fn collect_inner_captures_expr(expr: &Expr, caps: &mut HashSet<String>) {
 /// Compile a parsed program into a top-level bytecode function.
 pub fn compile(program: &Program) -> Result<Function, JsError> {
     let mut fc = FunctionCompiler::new("<main>".into(), 0);
+    fc.is_top_level = true;
 
     // Pre-scan to find which top-level locals are captured by inner functions.
     fc.captured_names = collect_inner_captures(&program.body);
@@ -1230,6 +1235,11 @@ fn compile_var_declarator(
                     let tmp = fc.alloc_reg();
                     compile_expr(fc, init, tmp)?;
                     fc.builder.emit_reg_reg(Op::CellStore, reg, tmp);
+                    // Top-level var: also store as global for cross-script access.
+                    if fc.is_top_level && kind == VarKind::Var {
+                        let name_idx = fc.builder.add_name(name);
+                        fc.builder.emit_store_global(name_idx, tmp);
+                    }
                     fc.free_reg(tmp);
                 }
                 // No init => cell stays undefined (already the default).
@@ -1238,6 +1248,14 @@ fn compile_var_declarator(
             } else {
                 fc.builder.emit_reg(Op::LoadUndefined, reg);
             }
+
+            // Top-level var/let/const: also store as global so the value
+            // persists across separate `execute()` calls (multiple scripts
+            // sharing the same global scope).
+            if fc.is_top_level && !is_captured {
+                let name_idx = fc.builder.add_name(name);
+                fc.builder.emit_store_global(name_idx, reg);
+            }
         }
         _ => {
             // Destructuring: evaluate init, then bind patterns.
diff --git a/crates/js/src/vm.rs b/crates/js/src/vm.rs
index ef4249a..d503731 100644
--- a/crates/js/src/vm.rs
+++ b/crates/js/src/vm.rs
@@ -846,6 +846,24 @@ impl Vm {
         crate::dom_bridge::init_event_system(self);
     }
 
+    /// Detach the DOM document from the VM, returning it.
+    ///
+    /// This removes the `document` global and disconnects the DOM bridge.
+    /// Returns `None` if no document was attached or if there are outstanding
+    /// references to the bridge.
+    pub fn detach_document(&mut self) -> Option<Document> {
+        let bridge = self.dom_bridge.take()?;
+        self.globals.remove("document");
+        match Rc::try_unwrap(bridge) {
+            Ok(bridge) => Some(bridge.document.into_inner()),
+            Err(rc) => {
+                // Something still holds a reference — reattach.
+                self.dom_bridge = Some(rc);
+                None
+            }
+        }
+    }
+
     /// Set an instruction limit. The VM will return a RuntimeError after
     /// executing this many instructions.
     pub fn set_instruction_limit(&mut self, limit: u64) {
-- 
2.51.2