From dab5ff77792af566da7c50b3535c9436f4b44270 Mon Sep 17 00:00:00 2001
From: Karl Seguin <k@openmymind.io>
Date: Thu, 23 Jul 2026 13:37:42 +0800
Subject: [PATCH 1/2] webapi: XHR uses XML parser for XML content-type
 responses

Expand mime type to be aware of more XML types. DOMParser and XHR now use the
existing Parser.parseXML (via a Frame helper), rather than the HTML parser. Both
these APIs predate the addition of parseXML.
---
 src/browser/Frame.zig                     | 36 ++++++++++++
 src/browser/Mime.zig                      | 37 +++++++++++++
 src/browser/tests/net/xhr.html            | 67 +++++++++++++++++++++--
 src/browser/webapi/DOMParser.zig          | 60 ++++++--------------
 src/browser/webapi/net/XMLHttpRequest.zig | 24 ++++----
 src/testing.zig                           | 18 ++++++
 6 files changed, 183 insertions(+), 59 deletions(-)

diff --git a/src/browser/Frame.zig b/src/browser/Frame.zig
index 7e13f3db37..764e075e0f 100644
--- a/src/browser/Frame.zig
+++ b/src/browser/Frame.zig
@@ -2938,6 +2938,42 @@ fn parseHtmlAsChildrenInner(self: *Frame, node: *Node, html: []const u8, opts: F
     }
 }
 
+// Build a detached XMLDocument from `xml` (DOMParser.parseFromString and
+// XMLHttpRequest.responseXML). Returns null when the input isn't well-formed
+// XML. The parse borrows the fragment parse-mode so frame-side hooks triggered
+// from `Build.created` / `nodeIsReady` (external stylesheet fetches, script
+// execution, mutation-observer fan-out, default-script injection) treat the
+// parsed nodes as detached and skip side effects on the live document.
+pub fn parseXmlDocument(self: *Frame, xml: []const u8) !?*Document.XMLDocument {
+    const arena = try self.getArena(.medium, "Frame.parseXmlDocument");
+    defer self.releaseArena(arena);
+
+    const previous_parse_mode = self._parse_mode;
+    self._parse_mode = .fragment;
+    defer self._parse_mode = previous_parse_mode;
+
+    const doc = try self._factory.document(Document.XMLDocument{ ._proto = undefined });
+    const doc_node = doc.asNode();
+    var parser = Parser.init(arena, doc_node, self, .{});
+    parser.parseXML(xml);
+    if (parser.terminated) {
+        return error.ExecutionTerminated;
+    }
+
+    if (parser.err != null or doc_node.firstChild() == null) {
+        return null;
+    }
+
+    // If first node is a `ProcessingInstruction` (e.g. the <?xml?>
+    // declaration), skip it.
+    const first_child = doc_node.firstChild().?;
+    if (first_child.getNodeType() == 7) {
+        _ = try doc_node.removeChild(first_child, self);
+    }
+
+    return doc;
+}
+
 // Runs the "ready" work for an inserted node and, when it's an element with
 // children, for its descendants in tree order: appending a subtree
 // containing scripts must execute them all, after the whole insertion.
diff --git a/src/browser/Mime.zig b/src/browser/Mime.zig
index 8145f49798..72268c7fb6 100644
--- a/src/browser/Mime.zig
+++ b/src/browser/Mime.zig
@@ -49,6 +49,7 @@ pub const ContentTypeEnum = enum {
     application_json,
     unknown,
     other,
+    other_xml,
 };
 
 pub const ContentType = union(ContentTypeEnum) {
@@ -68,6 +69,7 @@ pub const ContentType = union(ContentTypeEnum) {
     // A valid but unrecognized type/subtype. Keeping it would require some
     // memory management of the input. Nothing needs it right now, so why bother.
     other: void,
+    other_xml: void, // i.e. application/xml or */*+xml
 };
 
 pub fn contentTypeString(mime: *const Mime) []const u8 {
@@ -346,6 +348,13 @@ pub fn isHTML(self: *const Mime) bool {
     return self.content_type == .text_html;
 }
 
+pub fn isXML(self: *const Mime) bool {
+    return switch (self.content_type) {
+        .text_xml, .other_xml => true,
+        else => false,
+    };
+}
+
 pub fn isText(mime: *const Mime) bool {
     return switch (mime.content_type) {
         .text_xml, .text_html, .text_javascript, .text_plain, .text_css, .text_markdown => true,
@@ -378,9 +387,11 @@ fn parseContentType(value: []const u8) !struct { ContentType, usize } {
         @"image/webp",
 
         @"application/json",
+        @"application/xml",
     }, type_name)) |known_type| {
         const ct: ContentType = switch (known_type) {
             .@"text/xml" => .{ .text_xml = {} },
+            .@"application/xml" => .{ .other_xml = {} },
             .@"text/html" => .{ .text_html = {} },
             .@"text/javascript", .@"application/javascript", .@"application/x-javascript" => .{ .text_javascript = {} },
             .@"text/plain" => .{ .text_plain = {} },
@@ -408,6 +419,10 @@ fn parseContentType(value: []const u8) !struct { ContentType, usize } {
         return error.Invalid;
     }
 
+    if (std.mem.endsWith(u8, type_name, "+xml")) {
+        return .{ .{ .other_xml = {} }, attribute_start };
+    }
+
     return .{ .{ .other = {} }, attribute_start };
 }
 
@@ -897,6 +912,28 @@ test "Mime: isHTML" {
     try assert(false, "over/9000");
 }
 
+test "Mime: isXML" {
+    defer testing.reset();
+
+    const assert = struct {
+        fn assert(expected: bool, input: []const u8) !void {
+            const mutable_input = try testing.arena_allocator.dupe(u8, input);
+            var mime = try Mime.parse(mutable_input);
+            try testing.expectEqual(expected, mime.isXML());
+        }
+    }.assert;
+    try assert(true, "text/xml");
+    try assert(true, "TEXT/XML; charset=utf-8");
+    try assert(true, "application/xml");
+    try assert(true, "image/svg+xml");
+    try assert(true, "application/xhtml+xml");
+    try assert(true, "application/rss+xml;charset=utf-8");
+    try assert(false, "text/html");
+    try assert(false, "application/json");
+    try assert(false, "application/xmlfoo");
+    try assert(false, "text/xm");
+}
+
 test "Mime: sniff" {
     try testing.expectEqual(null, Mime.sniff(""));
     try testing.expectEqual(null, Mime.sniff("<htm"));
diff --git a/src/browser/tests/net/xhr.html b/src/browser/tests/net/xhr.html
index 3f45b37150..0025e8966f 100644
--- a/src/browser/tests/net/xhr.html
+++ b/src/browser/tests/net/xhr.html
@@ -372,25 +372,80 @@
 
 <script id=xhr_override_mime_responsexml type=module>
   {
-    // End-to-end: server returns text/html, but overrideMimeType("text/xml")
-    // makes responseXML lazily parse the body as a Document, while
-    // responseText is unaffected (responseType is still the default "").
+    // End-to-end: server returns text/plain, but overrideMimeType("text/xml")
+    // makes responseXML lazily parse the body as XML, while responseText is
+    // unaffected (responseType is still the default "").
     const state = await testing.async();
     const req = new XMLHttpRequest();
     req.overrideMimeType('text/xml');
-    req.open('GET', 'http://127.0.0.1:9582/xhr');
+    req.open('GET', 'http://127.0.0.1:9582/xhr/xml_as_text');
     req.onload = () => state.resolve();
     req.send();
     await state.done(() => {
       testing.expectEqual(200, req.status);
-      testing.expectEqual(100, req.responseText.length);
-      testing.expectEqual(true, req.responseXML instanceof Document);
+      testing.expectEqual(true, req.responseText.startsWith('<?xml'));
+      testing.expectEqual(true, req.responseXML instanceof XMLDocument);
+      testing.expectEqual('catalog', req.responseXML.documentElement.tagName);
       // Cached across calls.
       testing.expectEqual(req.responseXML, req.responseXML);
     });
   }
 </script>
 
+<script id=xhr_override_mime_malformed_xml type=module>
+  {
+    // The overridden type selects the XML parser; a body that isn't
+    // well-formed XML yields responseXML === null.
+    const state = await testing.async();
+    const req = new XMLHttpRequest();
+    req.overrideMimeType('text/xml');
+    req.open('GET', 'http://127.0.0.1:9582/xhr');
+    req.onload = () => state.resolve();
+    req.send();
+    await state.done(() => {
+      testing.expectEqual(100, req.responseText.length);
+      testing.expectEqual(null, req.responseXML);
+    });
+  }
+</script>
+
+<script id=xhr_responsexml_xml_mime type=module>
+  {
+    // An application/xml response parses with the XML parser: XMLDocument,
+    // tag case preserved, self-closing tags don't swallow their siblings.
+    const state = await testing.async();
+    const req = new XMLHttpRequest();
+    req.open('GET', 'http://127.0.0.1:9582/xhr/xml');
+    req.onload = () => state.resolve();
+    req.send();
+    await state.done(() => {
+      const doc = req.responseXML;
+      testing.expectEqual(true, doc instanceof XMLDocument);
+      testing.expectEqual('catalog', doc.documentElement.tagName);
+      testing.expectEqual(3, doc.documentElement.children.length);
+      testing.expectEqual(2, doc.getElementsByTagName('item').length);
+      testing.expectEqual(1, doc.getElementsByTagName('pubDate').length);
+    });
+  }
+</script>
+
+<script id=xhr_document_xml type=module>
+  {
+    // responseType=document with an XML MIME type also uses the XML parser.
+    const state = await testing.async();
+    const req = new XMLHttpRequest();
+    req.open('GET', 'http://127.0.0.1:9582/xhr/xml');
+    req.responseType = 'document';
+    req.onload = () => state.resolve();
+    req.send();
+    await state.done(() => {
+      testing.expectEqual(true, req.response instanceof XMLDocument);
+      testing.expectEqual('catalog', req.response.documentElement.tagName);
+      testing.expectEqual(req.response, req.responseXML);
+    });
+  }
+</script>
+
 <script id=xhr_override_mime_no_override type=module>
   {
     // Without overrideMimeType, a text/html response still yields
diff --git a/src/browser/webapi/DOMParser.zig b/src/browser/webapi/DOMParser.zig
index 57c0f4080b..f304676086 100644
--- a/src/browser/webapi/DOMParser.zig
+++ b/src/browser/webapi/DOMParser.zig
@@ -24,7 +24,6 @@ const Frame = @import("../Frame.zig");
 const Parser = @import("../parser/Parser.zig");
 
 const HTMLDocument = @import("HTMLDocument.zig");
-const XMLDocument = @import("XMLDocument.zig");
 const Document = @import("Document.zig");
 
 const DOMParser = @This();
@@ -50,22 +49,22 @@ pub fn parseFromString(
         @"image/svg+xml",
     }, mime_type) orelse return error.NotSupported;
 
-    const arena = try frame.getArena(.medium, "DOMParser.parseFromString");
-    defer frame.releaseArena(arena);
-
-    // DOMParser builds a detached Document. Borrow the same fragment
-    // parse-mode that `parseHtmlAsChildren` uses so frame-side hooks
-    // triggered from `Build.created` / `nodeIsReady` (external stylesheet
-    // fetches, script execution, mutation-observer fan-out, default-script
-    // injection) treat the parsed nodes as detached and skip
-    // side effects on the live document. The frame's `_parse_mode` is
-    // restored on exit.
-    const previous_parse_mode = frame._parse_mode;
-    frame._parse_mode = .fragment;
-    defer frame._parse_mode = previous_parse_mode;
-
     return switch (target_mime) {
         .@"text/html" => {
+            const arena = try frame.getArena(.medium, "DOMParser.parseFromString");
+            defer frame.releaseArena(arena);
+
+            // DOMParser builds a detached Document. Borrow the same fragment
+            // parse-mode that `parseHtmlAsChildren` uses so frame-side hooks
+            // triggered from `Build.created` / `nodeIsReady` (external
+            // stylesheet fetches, script execution, mutation-observer fan-out,
+            // default-script injection) treat the parsed nodes as detached and
+            // skip side effects on the live document. The frame's
+            // `_parse_mode` is restored on exit.
+            const previous_parse_mode = frame._parse_mode;
+            frame._parse_mode = .fragment;
+            defer frame._parse_mode = previous_parse_mode;
+
             // Create a new HTMLDocument
             const doc = try frame._factory.document(HTMLDocument{
                 ._proto = undefined,
@@ -90,35 +89,10 @@ pub fn parseFromString(
             return doc.asDocument();
         },
         else => {
-            // Create a new XMLDocument.
-            const doc = try frame._factory.document(XMLDocument{
-                ._proto = undefined,
-            });
-
-            // Parse XML into XMLDocument.
-            const doc_node = doc.asNode();
-            var parser = Parser.init(arena, doc_node, frame, .{});
-            parser.parseXML(html);
-            if (parser.terminated) {
-                return error.ExecutionTerminated;
-            }
-
-            if (parser.err != null or doc_node.firstChild() == null) {
+            const doc = (try frame.parseXmlDocument(html)) orelse blk: {
                 // Return a document with a <parsererror> element per spec.
-                const err_doc = try frame._factory.document(XMLDocument{ ._proto = undefined });
-                var err_parser = Parser.init(arena, err_doc.asNode(), frame, .{});
-                err_parser.parseXML("<parsererror xmlns=\"http://www.mozilla.org/newlayout/xml/parsererror.xml\">error</parsererror>");
-                return err_doc.asDocument();
-            }
-
-            const first_child = doc_node.firstChild().?;
-
-            // If first node is a `ProcessingInstruction`, skip it.
-            if (first_child.getNodeType() == 7) {
-                // We're sure that firstChild exist, this cannot fail.
-                _ = try doc_node.removeChild(first_child, frame);
-            }
-
+                break :blk (try frame.parseXmlDocument("<parsererror xmlns=\"http://www.mozilla.org/newlayout/xml/parsererror.xml\">error</parsererror>")).?;
+            };
             return doc.asDocument();
         },
     };
diff --git a/src/browser/webapi/net/XMLHttpRequest.zig b/src/browser/webapi/net/XMLHttpRequest.zig
index db3627b505..d59c6cc261 100644
--- a/src/browser/webapi/net/XMLHttpRequest.zig
+++ b/src/browser/webapi/net/XMLHttpRequest.zig
@@ -434,14 +434,16 @@ pub fn getResponse(self: *XMLHttpRequest, exec: *const Execution) !?Response {
         .document => blk: {
             // responseType=document is only meaningful in a Frame; workers
             // have no DOM. Drastically different impls -> switch on global.
-            //
-            // TODO: per WHATWG XHR "set a document response", the final MIME
-            // type (_override_mime ?? _response_mime) should select an XML
-            // parser when it is an XML MIME type, and the HTML parser
-            // otherwise. We only have an HTML parser today, so the body is
-            // always parsed as HTML regardless of the override.
             switch (exec.js.global) {
                 .frame => |frame| {
+                    const final: Mime = self._override_mime orelse self._response_mime orelse .{ .content_type = .text_xml };
+                    if (final.isXML()) {
+                        const document = (try frame.parseXmlDocument(data)) orelse return null;
+                        break :blk .{ .document = document.asDocument() };
+                    }
+                    if (!final.isHTML()) {
+                        return null;
+                    }
                     const document = try exec._factory.node(Node.Document{ ._proto = undefined, ._type = .generic });
                     try frame.parseHtmlAsChildren(document.asNode(), data);
                     break :blk .{ .document = document };
@@ -478,13 +480,15 @@ pub fn getResponseXML(self: *XMLHttpRequest, exec: *const Execution) !?*Node.Doc
         return document;
     }
 
-    const final = self._override_mime orelse self._response_mime orelse return null;
-    if (final.content_type != .text_xml) return null;
+    // With responseType "", only an XML final MIME type is parsed (an HTML
+    // one yields null); absent a Content-Type it defaults to text/xml.
+    const final: Mime = self._override_mime orelse self._response_mime orelse .{ .content_type = .text_xml };
+    if (!final.isXML()) return null;
 
     switch (exec.js.global) {
         .frame => |frame| {
-            const document = try exec._factory.node(Node.Document{ ._proto = undefined, ._type = .generic });
-            try frame.parseHtmlAsChildren(document.asNode(), self._response_data.items);
+            const xml_document = (try frame.parseXmlDocument(self._response_data.items)) orelse return null;
+            const document = xml_document.asDocument();
             self._response_xml = document;
             return document;
         },
diff --git a/src/testing.zig b/src/testing.zig
index 7cf26c4a7f..3c335d0e85 100644
--- a/src/testing.zig
+++ b/src/testing.zig
@@ -637,6 +637,24 @@ fn testHTTPHandler(req: *std.http.Server.Request) !void {
         });
     }
 
+    const xhr_xml_body = "<?xml version=\"1.0\"?><catalog><item id=\"a\"/><item id=\"b\"/><pubDate>2026</pubDate></catalog>";
+
+    if (std.mem.eql(u8, path, "/xhr/xml")) {
+        return req.respond(xhr_xml_body, .{
+            .extra_headers = &.{
+                .{ .name = "Content-Type", .value = "application/xml" },
+            },
+        });
+    }
+
+    if (std.mem.eql(u8, path, "/xhr/xml_as_text")) {
+        return req.respond(xhr_xml_body, .{
+            .extra_headers = &.{
+                .{ .name = "Content-Type", .value = "text/plain" },
+            },
+        });
+    }
+
     if (std.mem.eql(u8, path, "/xhr/json")) {
         return req.respond("{\"over\":\"9000!!!\",\"updated_at\":1765867200000}", .{
             .extra_headers = &.{

From 705bc78b7276858c6516ffa6787b0bdc0fb6727d Mon Sep 17 00:00:00 2001
From: Karl Seguin <k@openmymind.io>
Date: Thu, 23 Jul 2026 13:51:34 +0800
Subject: [PATCH 2/2] cleanup: Mechanical move various frame.parse* method

Follows the observer, user_input, etc.. pattern and relocates various
`Frame.parse*` methods into Frame.parse.* functions.

Goal is just to keep Frame neat.
---
 src/browser/Frame.zig                         | 108 +--------------
 src/browser/forms.zig                         |   2 +-
 src/browser/frame/parse.zig                   | 129 ++++++++++++++++++
 src/browser/interactive.zig                   |   2 +-
 src/browser/links.zig                         |   2 +-
 src/browser/markdown.zig                      |  12 +-
 src/browser/structured_data.zig               |   4 +-
 .../parser_wrapper_removed.html               |   2 +-
 src/browser/webapi/DOMParser.zig              |   6 +-
 src/browser/webapi/Element.zig                |   2 +-
 src/browser/webapi/HTMLDocument.zig           |   2 +-
 src/browser/webapi/Node.zig                   |   4 +-
 src/browser/webapi/Range.zig                  |   2 +-
 src/browser/webapi/element/Html.zig           |   2 +-
 src/browser/webapi/net/XMLHttpRequest.zig     |   7 +-
 15 files changed, 155 insertions(+), 131 deletions(-)
 create mode 100644 src/browser/frame/parse.zig

diff --git a/src/browser/Frame.zig b/src/browser/Frame.zig
index 764e075e0f..ce78f7588b 100644
--- a/src/browser/Frame.zig
+++ b/src/browser/Frame.zig
@@ -73,6 +73,7 @@ const milliTimestamp = @import("../datetime.zig").milliTimestamp;
 
 const GlobalEventHandlersLookup = @import("webapi/global_event_handlers.zig").Lookup;
 
+pub const parse = @import("frame/parse.zig");
 pub const preload = @import("frame/preload.zig");
 pub const observers = @import("frame/observers.zig");
 pub const user_input = @import("frame/user_input.zig");
@@ -2867,113 +2868,6 @@ pub fn updateRangesForNodeRemoval(self: *Frame, parent: *Node, child: *Node, chi
     }
 }
 
-// TODO: optimize and cleanup, this is called a lot (e.g., innerHTML = '')
-pub fn parseHtmlAsChildren(self: *Frame, node: *Node, html: []const u8) !void {
-    return self.parseHtmlAsChildrenInner(node, html, .{});
-}
-
-// setHTMLUnsafe variant: parse a fragment that may contain declarative shadow node
-pub fn parseHtmlUnsafeAsChildren(self: *Frame, node: *Node, html: []const u8) !void {
-    return self.parseHtmlAsChildrenInner(node, html, .{ .allow_declarative_shadow = true });
-}
-
-// Range.createContextualFragment variant: unlike innerHTML et al., its scripts
-// are run when the fragment is inserted into a document.
-pub fn parseContextualFragment(self: *Frame, node: *Node, html: []const u8) !void {
-    return self.parseHtmlAsChildrenInner(node, html, .{ .scripts_runnable = true });
-}
-
-const FragmentParseOpts = struct {
-    scripts_runnable: bool = false,
-    allow_declarative_shadow: bool = false,
-};
-
-fn parseHtmlAsChildrenInner(self: *Frame, node: *Node, html: []const u8, opts: FragmentParseOpts) !void {
-    const previous_parse_mode = self._parse_mode;
-    self._parse_mode = .fragment;
-    defer self._parse_mode = previous_parse_mode;
-
-    // The html5ever wrapper-unwrap below rebinds children without going
-    // through the insertion path, so recompute slot assignments for any
-    // shadow tree this fragment landed in (idempotent; signals only on diff).
-    defer if (self._element_shadow_roots.count() != 0) {
-        const root = node.getRootNode(.{});
-        if (root.is(ShadowRoot) != null) {
-            slotting.assignSlottablesForTree(root, self);
-        }
-        if (node.is(Element)) |el| {
-            if (self._element_shadow_roots.get(el)) |shadow_root| {
-                slotting.assignSlottablesForTree(shadow_root.asNode(), self);
-            }
-        }
-    };
-
-    const previous_scripts_runnable = self._fragment_scripts_runnable;
-    self._fragment_scripts_runnable = opts.scripts_runnable;
-    defer self._fragment_scripts_runnable = previous_scripts_runnable;
-
-    var parser = Parser.init(self.call_arena, node, self, .{ .allow_declarative_shadow = opts.allow_declarative_shadow });
-    parser.parseFragment(html);
-    if (parser.terminated) {
-        return error.ExecutionTerminated;
-    }
-
-    // html5ever wraps fragment output in an <html> element; unwrap so its
-    // children land directly on `node`. See https://github.com/servo/html5ever/issues/583.
-    // Because of custom element callbacks, the structure might not be what
-    // we expect, and nodes might be altogether removed. We deal with this in a
-    // few different places, but always the same way: leave it as-is.
-    const children = node._children orelse return;
-    const first = Node.linkToNode(children.first.?);
-    if (first.is(Element.Html.Html) == null) {
-        return;
-    }
-    node._children = first._children;
-
-    // No mutation records for the unwrapped children either; see the comment
-    // about fragment parses in _insertNodeRelative.
-    var it = node.childrenIterator();
-    while (it.next()) |child| {
-        child._parent = node;
-    }
-}
-
-// Build a detached XMLDocument from `xml` (DOMParser.parseFromString and
-// XMLHttpRequest.responseXML). Returns null when the input isn't well-formed
-// XML. The parse borrows the fragment parse-mode so frame-side hooks triggered
-// from `Build.created` / `nodeIsReady` (external stylesheet fetches, script
-// execution, mutation-observer fan-out, default-script injection) treat the
-// parsed nodes as detached and skip side effects on the live document.
-pub fn parseXmlDocument(self: *Frame, xml: []const u8) !?*Document.XMLDocument {
-    const arena = try self.getArena(.medium, "Frame.parseXmlDocument");
-    defer self.releaseArena(arena);
-
-    const previous_parse_mode = self._parse_mode;
-    self._parse_mode = .fragment;
-    defer self._parse_mode = previous_parse_mode;
-
-    const doc = try self._factory.document(Document.XMLDocument{ ._proto = undefined });
-    const doc_node = doc.asNode();
-    var parser = Parser.init(arena, doc_node, self, .{});
-    parser.parseXML(xml);
-    if (parser.terminated) {
-        return error.ExecutionTerminated;
-    }
-
-    if (parser.err != null or doc_node.firstChild() == null) {
-        return null;
-    }
-
-    // If first node is a `ProcessingInstruction` (e.g. the <?xml?>
-    // declaration), skip it.
-    const first_child = doc_node.firstChild().?;
-    if (first_child.getNodeType() == 7) {
-        _ = try doc_node.removeChild(first_child, self);
-    }
-
-    return doc;
-}
-
 // Runs the "ready" work for an inserted node and, when it's an element with
 // children, for its descendants in tree order: appending a subtree
 // containing scripts must execute them all, after the whole insertion.
diff --git a/src/browser/forms.zig b/src/browser/forms.zig
index 18d068734f..ce6de36b1d 100644
--- a/src/browser/forms.zig
+++ b/src/browser/forms.zig
@@ -282,7 +282,7 @@ fn testForms(html: []const u8) ![]FormInfo {
 
     const doc = frame.window._document;
     const div = try doc.createElement("div", null, frame);
-    try frame.parseHtmlAsChildren(div.asNode(), html);
+    try Frame.parse.htmlAsChildren(frame, div.asNode(), html);
 
     return collectForms(frame.call_arena, div.asNode(), frame);
 }
diff --git a/src/browser/frame/parse.zig b/src/browser/frame/parse.zig
new file mode 100644
index 0000000000..526fc872d5
--- /dev/null
+++ b/src/browser/frame/parse.zig
@@ -0,0 +1,129 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const Frame = @import("../Frame.zig");
+const Parser = @import("../parser/Parser.zig");
+
+const Node = @import("../webapi/Node.zig");
+const Element = @import("../webapi/Element.zig");
+const Document = @import("../webapi/Document.zig");
+const ShadowRoot = @import("../webapi/ShadowRoot.zig");
+const slotting = @import("../webapi/element/slotting.zig");
+
+pub fn htmlAsChildren(frame: *Frame, node: *Node, html: []const u8) !void {
+    return htmlAsChildrenInner(frame, node, html, .{});
+}
+
+// setHTMLUnsafe variant: parse a fragment that may contain declarative shadow node
+pub fn htmlUnsafeAsChildren(frame: *Frame, node: *Node, html: []const u8) !void {
+    return htmlAsChildrenInner(frame, node, html, .{ .allow_declarative_shadow = true });
+}
+
+// Range.createContextualFragment variant: unlike innerHTML et al., its scripts
+// are run when the fragment is inserted into a document.
+pub fn contextualFragment(frame: *Frame, node: *Node, html: []const u8) !void {
+    return htmlAsChildrenInner(frame, node, html, .{ .scripts_runnable = true });
+}
+
+const FragmentParseOpts = struct {
+    scripts_runnable: bool = false,
+    allow_declarative_shadow: bool = false,
+};
+
+fn htmlAsChildrenInner(frame: *Frame, node: *Node, html: []const u8, opts: FragmentParseOpts) !void {
+    const previous_parse_mode = frame._parse_mode;
+    frame._parse_mode = .fragment;
+    defer frame._parse_mode = previous_parse_mode;
+
+    // The html5ever wrapper-unwrap below rebinds children without going
+    // through the insertion path, so recompute slot assignments for any
+    // shadow tree this fragment landed in (idempotent; signals only on diff).
+    defer if (frame._element_shadow_roots.count() != 0) {
+        const root = node.getRootNode(.{});
+        if (root.is(ShadowRoot) != null) {
+            slotting.assignSlottablesForTree(root, frame);
+        }
+        if (node.is(Element)) |el| {
+            if (frame._element_shadow_roots.get(el)) |shadow_root| {
+                slotting.assignSlottablesForTree(shadow_root.asNode(), frame);
+            }
+        }
+    };
+
+    const previous_scripts_runnable = frame._fragment_scripts_runnable;
+    frame._fragment_scripts_runnable = opts.scripts_runnable;
+    defer frame._fragment_scripts_runnable = previous_scripts_runnable;
+
+    var parser = Parser.init(frame.call_arena, node, frame, .{ .allow_declarative_shadow = opts.allow_declarative_shadow });
+    parser.parseFragment(html);
+    if (parser.terminated) {
+        return error.ExecutionTerminated;
+    }
+
+    // html5ever wraps fragment output in an <html> element; unwrap so its
+    // children land directly on `node`. See https://github.com/servo/html5ever/issues/583.
+    // Because of custom element callbacks, the structure might not be what
+    // we expect, and nodes might be altogether removed. We deal with this in a
+    // few different places, but always the same way: leave it as-is.
+    const children = node._children orelse return;
+    const first = Node.linkToNode(children.first.?);
+    if (first.is(Element.Html.Html) == null) {
+        return;
+    }
+    node._children = first._children;
+
+    // No mutation records for the unwrapped children either; see the comment
+    // about fragment parses in _insertNodeRelative.
+    var it = node.childrenIterator();
+    while (it.next()) |child| {
+        child._parent = node;
+    }
+}
+
+// Build a detached XMLDocument from `xml` (DOMParser.parseFromString and
+// XMLHttpRequest.responseXML). Returns null when the input isn't well-formed
+// XML.
+pub fn xmlDocument(frame: *Frame, xml: []const u8) !?*Document.XMLDocument {
+    const arena = try frame.getArena(.medium, "parse.xmlDocument");
+    defer frame.releaseArena(arena);
+
+    const previous_parse_mode = frame._parse_mode;
+    frame._parse_mode = .fragment;
+    defer frame._parse_mode = previous_parse_mode;
+
+    const doc = try frame._factory.document(Document.XMLDocument{ ._proto = undefined });
+    const doc_node = doc.asNode();
+    var parser = Parser.init(arena, doc_node, frame, .{});
+    parser.parseXML(xml);
+    if (parser.terminated) {
+        return error.ExecutionTerminated;
+    }
+
+    if (parser.err != null or doc_node.firstChild() == null) {
+        return null;
+    }
+
+    // If first node is a `ProcessingInstruction` (e.g. the <?xml?>
+    // declaration), skip it.
+    const first_child = doc_node.firstChild().?;
+    if (first_child.getNodeType() == 7) {
+        _ = try doc_node.removeChild(first_child, frame);
+    }
+
+    return doc;
+}
diff --git a/src/browser/interactive.zig b/src/browser/interactive.zig
index 8c9c51e313..d6f0928427 100644
--- a/src/browser/interactive.zig
+++ b/src/browser/interactive.zig
@@ -501,7 +501,7 @@ fn testInteractive(html: []const u8) ![]InteractiveElement {
 
     const doc = frame.window._document;
     const div = try doc.createElement("div", null, frame);
-    try frame.parseHtmlAsChildren(div.asNode(), html);
+    try Frame.parse.htmlAsChildren(frame, div.asNode(), html);
 
     return collectInteractiveElements(div.asNode(), frame.call_arena, frame);
 }
diff --git a/src/browser/links.zig b/src/browser/links.zig
index 45695923a6..95624ce0f5 100644
--- a/src/browser/links.zig
+++ b/src/browser/links.zig
@@ -94,7 +94,7 @@ fn testLinks(html: []const u8) ![]Link {
 
     const doc = frame.window._document;
     const div = try doc.createElement("div", null, frame);
-    try frame.parseHtmlAsChildren(div.asNode(), html);
+    try Frame.parse.htmlAsChildren(frame, div.asNode(), html);
 
     return collectLinks(frame.call_arena, div.asNode(), frame);
 }
diff --git a/src/browser/markdown.zig b/src/browser/markdown.zig
index ae702e2d4d..86cdd45f4c 100644
--- a/src/browser/markdown.zig
+++ b/src/browser/markdown.zig
@@ -599,7 +599,7 @@ fn testMarkdownHTML(html: []const u8, expected: []const u8) !void {
     const doc = frame.window._document;
 
     const div = try doc.createElement("div", null, frame);
-    try frame.parseHtmlAsChildren(div.asNode(), html);
+    try Frame.parse.htmlAsChildren(frame, div.asNode(), html);
 
     var aw: std.Io.Writer.Allocating = .init(testing.allocator);
     defer aw.deinit();
@@ -800,7 +800,7 @@ test "browser.markdown: resolve links" {
 
     const doc = frame.window._document;
     const div = try doc.createElement("div", null, frame);
-    try frame.parseHtmlAsChildren(div.asNode(),
+    try Frame.parse.htmlAsChildren(frame, div.asNode(),
         \\<a href="b">Link</a>
         \\<img src="../c.png" alt="Img">
         \\<a href="/my page">Space</a>
@@ -839,7 +839,7 @@ test "browser.markdown: max_bytes leaves output untouched when under cap" {
 
     const doc = frame.window._document;
     const div = try doc.createElement("div", null, frame);
-    try frame.parseHtmlAsChildren(div.asNode(), "<p>Short</p>");
+    try Frame.parse.htmlAsChildren(frame, div.asNode(), "<p>Short</p>");
 
     var aw: std.Io.Writer.Allocating = .init(testing.allocator);
     defer aw.deinit();
@@ -855,7 +855,7 @@ test "browser.markdown: max_bytes truncates with marker" {
 
     const doc = frame.window._document;
     const div = try doc.createElement("div", null, frame);
-    try frame.parseHtmlAsChildren(div.asNode(), "<p>" ++ ("AAAA " ** 100) ++ "</p>");
+    try Frame.parse.htmlAsChildren(frame, div.asNode(), "<p>" ++ ("AAAA " ** 100) ++ "</p>");
 
     var aw: std.Io.Writer.Allocating = .init(testing.allocator);
     defer aw.deinit();
@@ -878,11 +878,11 @@ fn testMarkdownShadow(light: []const u8, shadow: []const u8, expected: []const u
 
     const host = try doc.createElement("div", null, frame);
     if (light.len > 0) {
-        try frame.parseHtmlAsChildren(host.asNode(), light);
+        try Frame.parse.htmlAsChildren(frame, host.asNode(), light);
     }
 
     const sr = try host.attachShadow(.{ .mode = .open }, frame);
-    try frame.parseHtmlAsChildren(sr.asNode(), shadow);
+    try Frame.parse.htmlAsChildren(frame, sr.asNode(), shadow);
 
     var aw: std.Io.Writer.Allocating = .init(testing.allocator);
     defer aw.deinit();
diff --git a/src/browser/structured_data.zig b/src/browser/structured_data.zig
index 8e5aac6141..0090f81ebd 100644
--- a/src/browser/structured_data.zig
+++ b/src/browser/structured_data.zig
@@ -494,7 +494,7 @@ fn testStructuredData(html: []const u8) !StructuredData {
 
     const doc = frame.window._document;
     const div = try doc.createElement("div", null, frame);
-    try frame.parseHtmlAsChildren(div.asNode(), html);
+    try Frame.parse.htmlAsChildren(frame, div.asNode(), html);
 
     return collectStructuredData(div.asNode(), frame.call_arena, frame);
 }
@@ -714,7 +714,7 @@ test "structured_data: link headers from response" {
 
     const doc = frame.window._document;
     const div = try doc.createElement("div", null, frame);
-    try frame.parseHtmlAsChildren(div.asNode(), "<title>Example</title>");
+    try Frame.parse.htmlAsChildren(frame, div.asNode(), "<title>Example</title>");
 
     const data = try collectStructuredData(div.asNode(), frame.call_arena, frame);
 
diff --git a/src/browser/tests/custom_elements/parser_wrapper_removed.html b/src/browser/tests/custom_elements/parser_wrapper_removed.html
index 77c637eb56..c2ca9f62bd 100644
--- a/src/browser/tests/custom_elements/parser_wrapper_removed.html
+++ b/src/browser/tests/custom_elements/parser_wrapper_removed.html
@@ -2,7 +2,7 @@
 <body>
 <script src="../testing.js"></script>
 
-<!-- Frame.parseHtmlAsChildren extracts children from the temporary
+<!-- Frame.parse.htmlAsChildren extracts children from the temporary
      <html> element the fragment parser leaves at the top of the parse
      result. A custom element's connectedCallback fires synchronously
      during that parse, so it can reach two levels up (this.parentNode is
diff --git a/src/browser/webapi/DOMParser.zig b/src/browser/webapi/DOMParser.zig
index f304676086..3a8088bd16 100644
--- a/src/browser/webapi/DOMParser.zig
+++ b/src/browser/webapi/DOMParser.zig
@@ -55,7 +55,7 @@ pub fn parseFromString(
             defer frame.releaseArena(arena);
 
             // DOMParser builds a detached Document. Borrow the same fragment
-            // parse-mode that `parseHtmlAsChildren` uses so frame-side hooks
+            // parse-mode that `Frame.parse` uses so frame-side hooks
             // triggered from `Build.created` / `nodeIsReady` (external
             // stylesheet fetches, script execution, mutation-observer fan-out,
             // default-script injection) treat the parsed nodes as detached and
@@ -89,9 +89,9 @@ pub fn parseFromString(
             return doc.asDocument();
         },
         else => {
-            const doc = (try frame.parseXmlDocument(html)) orelse blk: {
+            const doc = (try Frame.parse.xmlDocument(frame, html)) orelse blk: {
                 // Return a document with a <parsererror> element per spec.
-                break :blk (try frame.parseXmlDocument("<parsererror xmlns=\"http://www.mozilla.org/newlayout/xml/parsererror.xml\">error</parsererror>")).?;
+                break :blk (try Frame.parse.xmlDocument(frame, "<parsererror xmlns=\"http://www.mozilla.org/newlayout/xml/parsererror.xml\">error</parsererror>")).?;
             };
             return doc.asDocument();
         },
diff --git a/src/browser/webapi/Element.zig b/src/browser/webapi/Element.zig
index e44c1f0664..a81b82b665 100644
--- a/src/browser/webapi/Element.zig
+++ b/src/browser/webapi/Element.zig
@@ -484,7 +484,7 @@ pub fn setOuterHTML(self: *Element, html: []const u8, frame: *Frame) !void {
     var fragment: ?*Node = null;
     if (html.len > 0) {
         const frag = (try Node.DocumentFragment.init(frame)).asNode();
-        try frame.parseHtmlAsChildren(frag, html);
+        try Frame.parse.htmlAsChildren(frame, frag, html);
         fragment = frag;
     }
 
diff --git a/src/browser/webapi/HTMLDocument.zig b/src/browser/webapi/HTMLDocument.zig
index be47ff9827..08befb559f 100644
--- a/src/browser/webapi/HTMLDocument.zig
+++ b/src/browser/webapi/HTMLDocument.zig
@@ -71,7 +71,7 @@ pub fn setBody(self: *HTMLDocument, html: []const u8, frame: *Frame) !void {
     // parsing strips any <html>/<body>/<head> wrappers the author included.
     const new_body_node = try Frame.node_factory.createElementNS(frame, .html, "body", null);
     if (html.len > 0) {
-        try frame.parseHtmlAsChildren(new_body_node, html);
+        try Frame.parse.htmlAsChildren(frame, new_body_node, html);
     }
 
     const document_node = document_element.asNode();
diff --git a/src/browser/webapi/Node.zig b/src/browser/webapi/Node.zig
index 898e28f579..0bd37dbccb 100644
--- a/src/browser/webapi/Node.zig
+++ b/src/browser/webapi/Node.zig
@@ -1557,9 +1557,9 @@ pub fn setHTML(self: *Node, html: []const u8, allow_declarative_shadow: bool, fr
 
     if (html.len > 0) {
         if (allow_declarative_shadow) {
-            try frame.parseHtmlUnsafeAsChildren(self, html);
+            try Frame.parse.htmlUnsafeAsChildren(frame, self, html);
         } else {
-            try frame.parseHtmlAsChildren(self, html);
+            try Frame.parse.htmlAsChildren(frame, self, html);
         }
     }
 
diff --git a/src/browser/webapi/Range.zig b/src/browser/webapi/Range.zig
index cc443566be..9339fde76b 100644
--- a/src/browser/webapi/Range.zig
+++ b/src/browser/webapi/Range.zig
@@ -703,7 +703,7 @@ pub fn createContextualFragment(self: *const Range, html: []const u8, frame: *Fr
     else
         try Frame.node_factory.createElementNS(frame, .html, "div", null);
 
-    try frame.parseContextualFragment(temp_node, html);
+    try Frame.parse.contextualFragment(frame, temp_node, html);
 
     // Move all parsed children to the fragment
     // Keep removing first child until temp element is empty
diff --git a/src/browser/webapi/element/Html.zig b/src/browser/webapi/element/Html.zig
index c2776a1f01..699e98e134 100644
--- a/src/browser/webapi/element/Html.zig
+++ b/src/browser/webapi/element/Html.zig
@@ -290,7 +290,7 @@ pub fn insertAdjacentHTML(
 ) !void {
     const DocumentFragment = @import("../DocumentFragment.zig");
     const fragment = (try DocumentFragment.init(frame)).asNode();
-    try frame.parseHtmlAsChildren(fragment, html);
+    try Frame.parse.htmlAsChildren(frame, fragment, html);
 
     const target_node, const prev_node = try self.asNode().findAdjacentNodes(position, .html);
 
diff --git a/src/browser/webapi/net/XMLHttpRequest.zig b/src/browser/webapi/net/XMLHttpRequest.zig
index d59c6cc261..52b8539b1a 100644
--- a/src/browser/webapi/net/XMLHttpRequest.zig
+++ b/src/browser/webapi/net/XMLHttpRequest.zig
@@ -26,6 +26,7 @@ const Transfer = @import("../../../network/HttpClient.zig").Transfer;
 const URL = @import("../../URL.zig");
 const Mime = @import("../../Mime.zig");
 const Page = @import("../../Page.zig");
+const Frame = @import("../../Frame.zig");
 
 const Node = @import("../Node.zig");
 const Event = @import("../Event.zig");
@@ -438,14 +439,14 @@ pub fn getResponse(self: *XMLHttpRequest, exec: *const Execution) !?Response {
                 .frame => |frame| {
                     const final: Mime = self._override_mime orelse self._response_mime orelse .{ .content_type = .text_xml };
                     if (final.isXML()) {
-                        const document = (try frame.parseXmlDocument(data)) orelse return null;
+                        const document = (try Frame.parse.xmlDocument(frame, data)) orelse return null;
                         break :blk .{ .document = document.asDocument() };
                     }
                     if (!final.isHTML()) {
                         return null;
                     }
                     const document = try exec._factory.node(Node.Document{ ._proto = undefined, ._type = .generic });
-                    try frame.parseHtmlAsChildren(document.asNode(), data);
+                    try Frame.parse.htmlAsChildren(frame, document.asNode(), data);
                     break :blk .{ .document = document };
                 },
                 .worker => return error.NotSupportedInWorker,
@@ -487,7 +488,7 @@ pub fn getResponseXML(self: *XMLHttpRequest, exec: *const Execution) !?*Node.Doc
 
     switch (exec.js.global) {
         .frame => |frame| {
-            const xml_document = (try frame.parseXmlDocument(self._response_data.items)) orelse return null;
+            const xml_document = (try Frame.parse.xmlDocument(frame, self._response_data.items)) orelse return null;
             const document = xml_document.asDocument();
             self._response_xml = document;
             return document;