rusteerio 1.0.0 → 1.1.0

package/native/src/lib.rs

@@ -14,18 +14,27 @@ use napi_derive::napi;
 use scraper::{Html, Node, Selector};
 use serde_json::{Map, Value};
 
+#[cfg(target_os = "linux")]
+#[global_allocator]
+static ALLOCATOR: mimalloc::MiMalloc = mimalloc::MiMalloc;
+
 mod arena;
 mod attributes;
 mod codec;
 mod diagnostics;
+mod document_order;
 mod extraction;
 mod gc;
 mod hook_sink;
 mod hook_stream;
+mod id_hash;
+mod immutable;
 mod location;
+mod markup_tokenizer;
 mod runtime;
 mod selector;
 mod sink;
+mod snapshot;
 mod stream;
 mod tokenizer;
 mod tracker;
@@ -68,19 +77,81 @@ pub(crate) fn push_attribute_name(
     output.push_str(local);
 }
 
+/// Orders attributes the way a JavaScript object enumerates its keys: integer
+/// keys first, ascending, then insertion order. Cheerio serializes attributes
+/// from such an object.
+pub(crate) fn js_property_order<'a, T, I>(entries: I) -> JsPropertyOrder<I>
+where
+    I: Iterator<Item = (&'a str, T)> + Clone,
+{
+    if !entries.clone().any(|(name, _)| array_index(name).is_some()) {
+        return JsPropertyOrder::Unchanged(entries);
+    }
+    let mut keyed: Vec<_> = entries
+        .map(|entry| {
+            (
+                array_index(entry.0).map_or((1, 0), |index| (0, index)),
+                entry,
+            )
+        })
+        .collect();
+    keyed.sort_by_key(|(key, _)| *key);
+    let sorted: Vec<_> = keyed.into_iter().map(|(_, entry)| entry).collect();
+    JsPropertyOrder::Sorted(sorted.into_iter())
+}
+
+pub(crate) enum JsPropertyOrder<I: Iterator> {
+    Unchanged(I),
+    Sorted(std::vec::IntoIter<I::Item>),
+}
+
+impl<I: Iterator> Iterator for JsPropertyOrder<I> {
+    type Item = I::Item;
+    fn next(&mut self) -> Option<Self::Item> {
+        match self {
+            Self::Unchanged(entries) => entries.next(),
+            Self::Sorted(entries) => entries.next(),
+        }
+    }
+}
+
+fn array_index(name: &str) -> Option<u32> {
+    let is_canonical = !name.is_empty()
+        && name.len() <= 10
+        && name.bytes().all(|byte| byte.is_ascii_digit())
+        && (name == "0" || !name.starts_with('0'));
+    is_canonical
+        .then(|| name.parse::<u64>().ok())
+        .flatten()
+        .filter(|value| *value < u64::from(u32::MAX))
+        .map(|value| value as u32)
+}
+
 #[napi(custom_finalize)]
 pub struct NativeDocument {
     html: RefCell<Option<Html>>,
     // Stable public IDs are preorder positions, rather than parser allocation
     // positions: HTML5 foster parenting can change the latter's ordering.
     ids: RefCell<Vec<NodeId>>,
-    reverse: RefCell<HashMap<NodeId, u32>>,
+    reverse: RefCell<id_hash::IdMap<NodeId, u32>>,
+    /// Parent/child links of the parse tree, built on the first query that needs them.
+    tree_index: RefCell<Option<immutable::TreeIndex>>,
     pub(crate) arena: RefCell<Option<arena::DomArena>>,
     options: Value,
     source: RefCell<Option<String>>,
     retained: RefCell<HashMap<u32, usize>>,
     needs_collect: Cell<bool>,
     managed: Cell<bool>,
+    /// Slots managed collections keep regardless of pins.
+    kept_slots: Cell<u32>,
+    /// The document index JavaScript routes this document's node ids by.
+    routing_index: Cell<Option<u32>>,
+    /// Nodes were removed from the parse tree, so traversal order no longer
+    /// matches local ids and parsed nodes may be orphans.
+    tree_detached: Cell<bool>,
+    /// Parents whose children a parse-tree removal changed since JavaScript last asked.
+    tree_touched: RefCell<Vec<u32>>,
+    _live: LiveDocument,
     diagnostics: RefCell<Vec<Value>>,
     locations: RefCell<HashMap<u32, Value>>,
     // V8 cannot see native allocations. Reporting them lets its GC collect
@@ -89,12 +160,71 @@ pub struct NativeDocument {
     reported_heap_bytes: Cell<i64>,
 }
 
+/// Node-API calls the finalizers of a module that declares the experimental
+/// version directly from garbage collection, rather than on a later turn of
+/// the event loop, so a synchronous loop over documents frees each native tree
+/// as soon as V8 collects its document. Finalizers must therefore not call
+/// into V8: see `NativeDocument::finalize`.
+#[no_mangle]
+pub extern "C" fn node_api_module_get_api_version_v1() -> i32 {
+    NAPI_VERSION_EXPERIMENTAL
+}
+
+const NAPI_VERSION_EXPERIMENTAL: i32 = i32::MAX;
+
+thread_local! {
+    /// External memory of finalized documents not yet returned to V8.
+    static RELEASED_HEAP_BYTES: Cell<i64> = const { Cell::new(0) };
+    /// Routing indexes of finalized documents, free for new documents.
+    static FREE_ROUTING_INDEXES: RefCell<Vec<u32>> = const { RefCell::new(Vec::new()) };
+    static NEXT_ROUTING_INDEX: Cell<u32> = const { Cell::new(0) };
+}
+
+static LIVE_DOCUMENTS: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);
+
+/// Counts documents whose native storage has not been dropped yet.
+struct LiveDocument;
+
+impl LiveDocument {
+    fn new() -> Self {
+        LIVE_DOCUMENTS.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+        Self
+    }
+}
+
+impl Drop for LiveDocument {
+    fn drop(&mut self) {
+        LIVE_DOCUMENTS.fetch_sub(1, std::sync::atomic::Ordering::Relaxed);
+    }
+}
+
+/// Trees with more nodes than this are freed on the shared pool, so a
+/// collection pause does not wait for them.
+const POOL_RELEASE_NODES: usize = 4096;
+
 impl ObjectFinalize for NativeDocument {
-    fn finalize(self, mut env: Env) -> Result<()> {
+    fn finalize(self, _env: Env) -> Result<()> {
+        // Adjusting external memory during garbage collection is not allowed;
+        // the next report on this thread returns it.
         let reported = self.reported_heap_bytes.get();
-        if reported != 0 {
-            // Accounting is advisory; a failure must not throw from a finalizer.
-            let _ = env.adjust_external_memory(-reported);
+        RELEASED_HEAP_BYTES.with(|released| released.set(released.get() + reported));
+        if let Some(index) = self.routing_index.get() {
+            FREE_ROUTING_INDEXES.with(|free| free.borrow_mut().push(index));
+        }
+        let nodes = self.ids.borrow().len()
+            + self
+                .arena
+                .borrow()
+                .as_ref()
+                .map_or(0, |arena| arena.nodes.len());
+        if nodes > POOL_RELEASE_NODES {
+            runtime::release_later((
+                self.html.into_inner(),
+                self.arena.into_inner(),
+                self.ids.into_inner(),
+                self.reverse.into_inner(),
+                self.tree_index.into_inner(),
+            ));
         }
         Ok(())
     }
@@ -120,16 +250,31 @@ const HEAP_REPORT_STEP: i64 = 64 * 1024;
 impl NativeDocument {
     pub(crate) fn from_arena(arena: arena::DomArena, options: Value) -> Self {
         let content_bytes = arena.nodes.iter().map(arena::DomNode::content_bytes).sum();
+        Self::from_arena_sized(arena, options, content_bytes)
+    }
+
+    /// A document over `arena` whose text and attribute content takes about
+    /// `content_bytes`, such as the length of the source it was parsed from.
+    fn from_arena_sized(arena: arena::DomArena, options: Value, content_bytes: usize) -> Self {
+        if arena.nodes.len() > POOL_RELEASE_NODES {
+            runtime::start_release_thread();
+        }
         Self {
             html: RefCell::new(None),
             ids: RefCell::new(Vec::new()),
-            reverse: RefCell::new(HashMap::new()),
+            reverse: RefCell::new(id_hash::IdMap::default()),
+            tree_index: RefCell::new(None),
             arena: RefCell::new(Some(arena)),
             options,
             source: RefCell::new(None),
             retained: RefCell::new(HashMap::new()),
             needs_collect: Cell::new(false),
             managed: Cell::new(false),
+            kept_slots: Cell::new(0),
+            routing_index: Cell::new(None),
+            tree_detached: Cell::new(false),
+            tree_touched: RefCell::new(Vec::new()),
+            _live: LiveDocument::new(),
             diagnostics: RefCell::new(Vec::new()),
             locations: RefCell::new(HashMap::new()),
             content_bytes: Cell::new(content_bytes),
@@ -168,6 +313,10 @@ impl NativeDocument {
     }
 
     fn report_heap_bytes(&self, mut env: Env) {
+        let released = RELEASED_HEAP_BYTES.with(|released| released.replace(0));
+        if released != 0 && env.adjust_external_memory(-released).is_err() {
+            RELEASED_HEAP_BYTES.with(|pending| pending.set(pending.get() + released));
+        }
         let reported = self.reported_heap_bytes.get();
         let estimated = self.estimated_heap_bytes();
         let change = estimated - reported;
@@ -196,20 +345,40 @@ impl NativeDocument {
             .as_object_mut()
             .and_then(|options| options.remove("__tokenEvents"))
         {
-            return Self::from_arena(
+            return Self::from_arena_sized(
                 tokenizer::parse(source, &events, parser_options.clone()),
                 parser_options,
+                source.len(),
             );
         }
         if arena::xml_mode(&parser_options)
             || parser_options.get("_useHtmlParser2") == Some(&Value::Bool(true))
         {
-            return Self::from_arena(
+            return Self::from_arena_sized(
                 arena::parse_xml(source, parser_options.clone()),
                 parser_options,
+                source.len(),
             );
         }
 
+        let capture = parser_options
+            .get("sourceCodeLocationInfo")
+            .is_some_and(|value| !matches!(value, Value::Null | Value::Bool(false)))
+            || parser_options.get("__collectParseErrors") == Some(&Value::Bool(true));
+        // HTML5 input preprocessing turns CRLF and CR into LF; html5ever does
+        // it one character at a time, which dominates pages with CRLF endings.
+        // Captured source locations must index the original input instead.
+        let normalized;
+        let source = if !capture && source.contains('\r') {
+            normalized = normalize_newlines(source);
+            normalized.as_str()
+        } else {
+            source
+        };
+        if !is_document && context_name.is_none() && !capture && is_plain_text(source) {
+            return Self::from_html(plain_text_fragment(source), false, parser_options, None);
+        }
+
         let options = html5ever::driver::ParseOpts {
             tokenizer: html5ever::tokenizer::TokenizerOpts {
                 discard_bom: false,
@@ -224,7 +393,7 @@ impl NativeDocument {
         };
         let html = if is_document {
             html5ever::driver::parse_document(
-                sink::CompatibleSink::new(Html::new_document()),
+                sink::CompatibleSink::new(sized_html(source, true)),
                 options,
             )
             .one(source)
@@ -232,7 +401,7 @@ impl NativeDocument {
             // parse5's default fragment context is a template. A body context
             // discards valid standalone table fragments such as <td> and <tr>.
             html5ever::driver::parse_fragment(
-                sink::CompatibleSink::new(Html::new_fragment()),
+                sink::CompatibleSink::new(sized_html(source, false)),
                 options,
                 html5ever::QualName::new(
                     None,
@@ -250,10 +419,6 @@ impl NativeDocument {
             .one(source)
         };
 
-        let capture = parser_options
-            .get("sourceCodeLocationInfo")
-            .is_some_and(|value| !matches!(value, Value::Null | Value::Bool(false)))
-            || parser_options.get("__collectParseErrors") == Some(&Value::Bool(true));
         Self::from_html(
             html,
             is_document,
@@ -269,18 +434,7 @@ impl NativeDocument {
         source: Option<String>,
     ) -> Self {
         if !is_document {
-            // html5ever's fragment sink creates a synthetic html element.
-            // Cheerio exposes the fragment's actual children at its root.
-            let wrapper = html.tree.root().children().find_map(|node| {
-                node.value()
-                    .as_element()
-                    .filter(|element| element.name() == "html")
-                    .map(|_| node.id())
-            });
-            if let Some(wrapper) = wrapper {
-                html.tree.root_mut().reparent_from_id_append(wrapper);
-                html.tree.get_mut(wrapper).unwrap().detach();
-            }
+            unwrap_fragment_root(&mut html);
         }
 
         let mut locations = HashMap::new();
@@ -304,20 +458,7 @@ impl NativeDocument {
                     |_, _| {},
                 );
                 if !is_document {
-                    let wrapper = tracked
-                        .tree
-                        .root()
-                        .children()
-                        .find(|node| {
-                            node.value()
-                                .as_element()
-                                .is_some_and(|element| element.name() == "html")
-                        })
-                        .map(|node| node.id());
-                    if let Some(wrapper) = wrapper {
-                        tracked.tree.root_mut().reparent_from_id_append(wrapper);
-                        tracked.tree.get_mut(wrapper).unwrap().detach();
-                    }
+                    unwrap_fragment_root(&mut tracked);
                 }
                 let order: HashMap<_, _> = tracked
                     .tree
@@ -363,16 +504,25 @@ impl NativeDocument {
             })
             .and(source);
         let content_bytes = html.tree.values().map(html_node_content_bytes).sum();
+        if ids.len() > POOL_RELEASE_NODES {
+            runtime::start_release_thread();
+        }
         Self {
             html: RefCell::new(Some(html)),
             ids: RefCell::new(ids),
             reverse: RefCell::new(reverse),
+            tree_index: RefCell::new(None),
             arena: RefCell::new(None),
             options: parser_options,
             source: RefCell::new(source),
             retained: RefCell::new(HashMap::new()),
             needs_collect: Cell::new(false),
             managed: Cell::new(false),
+            kept_slots: Cell::new(0),
+            routing_index: Cell::new(None),
+            tree_detached: Cell::new(false),
+            tree_touched: RefCell::new(Vec::new()),
+            _live: LiveDocument::new(),
             diagnostics: RefCell::new(diagnostics),
             locations: RefCell::new(locations),
             content_bytes: Cell::new(content_bytes),
@@ -380,13 +530,33 @@ impl NativeDocument {
         }
     }
 
+    /// The arena borrowed for writing. It drops the name index first: a write
+    /// may add, remove or reorder elements.
+    pub(crate) fn arena_for_write(&self) -> std::cell::RefMut<'_, Option<arena::DomArena>> {
+        let mut arena = self.arena.borrow_mut();
+        if let Some(arena) = arena.as_mut() {
+            arena.name_index = None;
+        }
+        arena
+    }
+
     pub(crate) fn ensure_arena(&self) -> Result<()> {
         let missing = self.arena.borrow().is_none();
         if missing {
-            let records: Vec<arena::DomNode> = (0..self.ids.borrow().len())
-                .filter_map(|id| self.immutable_dom_node(id as u32))
-                .collect();
-            let mut arena = arena::DomArena::from_records(records, self.options.clone());
+            let records = {
+                let html = self.html.borrow();
+                let ids = self.ids.borrow();
+                let reverse = self.reverse.borrow();
+                let tree = SharedTree {
+                    html: html
+                        .as_ref()
+                        .ok_or_else(|| Error::new(Status::GenericFailure, "Missing parse tree"))?,
+                    ids: &ids,
+                    reverse: &reverse,
+                };
+                runtime::chunked_map(ids.len(), CONVERSION_CHUNK, |range| tree.convert(range))
+            };
+            let mut arena = arena::DomArena::from_linked_records(records, self.options.clone());
             if let Some(source) = self.source.borrow().as_ref() {
                 location::annotate(
                     source,
@@ -412,10 +582,17 @@ impl NativeDocument {
                 }
             }
             *self.arena.borrow_mut() = Some(arena);
-            self.html.borrow_mut().take();
+            let html = self.html.borrow_mut().take();
+            let reverse = std::mem::take(&mut *self.reverse.borrow_mut());
+            let ids = std::mem::take(&mut *self.ids.borrow_mut());
+            // Freeing a large parse tree takes as long as copying it; the
+            // JavaScript thread need not wait for it. Waking a worker costs
+            // more than freeing a small one.
+            if ids.len() > POOL_RELEASE_NODES {
+                runtime::release_later((html, reverse, ids));
+            }
             self.source.borrow_mut().take();
-            *self.ids.borrow_mut() = Vec::new();
-            *self.reverse.borrow_mut() = HashMap::new();
+            *self.tree_index.borrow_mut() = None;
         }
         Ok(())
     }
@@ -431,127 +608,246 @@ impl NativeDocument {
         Some(operation(node, html))
     }
 
-    fn immutable_dom_node(&self, id: u32) -> Option<arena::DomNode> {
-        self.with_node(id, |node, html| {
-            let pointer = |node: Option<NodeRef<'_, Node>>| {
-                node.and_then(|node| self.reverse.borrow().get(&node.id()).copied())
+    /// Runs `operation` over the parse tree, or returns `None` once the
+    /// document has moved to the mutable arena.
+    fn with_tree_dom<T>(
+        &self,
+        options: &Value,
+        operation: impl FnOnce(&immutable::TreeDom<'_>) -> T,
+    ) -> Option<T> {
+        if self.arena.borrow().is_some() {
+            return None;
+        }
+        let html = self.html.borrow();
+        let html = html.as_ref()?;
+        let ids = self.ids.borrow();
+        if self.tree_index.borrow().is_none() {
+            let index = if self.tree_detached.get() {
+                immutable::TreeIndex::build_mapped(html, &ids, &self.reverse.borrow())
+            } else {
+                immutable::TreeIndex::build(html, ids.len())
             };
-            let mut record = arena::DomNode::new("root");
-            record.id = id;
-            record.children = node
-                .children()
-                .filter_map(|child| self.reverse.borrow().get(&child.id()).copied())
-                .collect();
-            record.parent = pointer(node.parent());
-            record.prev = pointer(node.prev_sibling());
-            record.next = pointer(node.next_sibling());
-            record.extras.insert("startIndex".into(), Value::Null);
-            record.extras.insert("endIndex".into(), Value::Null);
-            match node.value() {
-                Node::Document => {
-                    record.extras.insert(
-                        "x-mode".into(),
-                        Value::String(
-                            match html.quirks_mode {
-                                html5ever::tree_builder::QuirksMode::Quirks => "quirks",
-                                html5ever::tree_builder::QuirksMode::LimitedQuirks => {
-                                    "limited-quirks"
-                                }
-                                html5ever::tree_builder::QuirksMode::NoQuirks => "no-quirks",
-                            }
-                            .into(),
-                        ),
-                    );
-                }
-                Node::Fragment => {}
-                Node::Text(data) => {
-                    record.kind = "text".into();
-                    record.data = Some(data.to_string());
-                }
-                Node::Comment(data) => {
-                    record.kind = "comment".into();
-                    record.data = Some(data.to_string());
+            *self.tree_index.borrow_mut() = Some(index);
+        }
+        let index = self.tree_index.borrow();
+        let dom = immutable::TreeDom {
+            html,
+            ids: &ids,
+            index: index.as_ref()?,
+            options,
+        };
+        Some(operation(&dom))
+    }
+
+    fn immutable_dom_node(&self, id: u32) -> Option<arena::DomNode> {
+        let html = self.html.borrow();
+        let ids = self.ids.borrow();
+        let reverse = self.reverse.borrow();
+        convert_node(html.as_ref()?, &ids, &reverse, id)
+    }
+
+    fn immutable_record(&self, id: u32) -> Option<Value> {
+        serde_json::to_value(self.immutable_dom_node(id)?).ok()
+    }
+
+    /// Read commands answered from the parse tree; `None` when the command
+    /// needs the mutable arena.
+    fn tree_read(
+        &self,
+        command: &str,
+        args: &Value,
+        ids: &[u32],
+        options: &Value,
+    ) -> Option<Result<Value>> {
+        match command {
+            "select" | "matches" => {
+                let mut options = options.clone();
+                if let Some(matches) = args.get("pseudoMatches") {
+                    options["__pseudoMatches"] = matches.clone();
                 }
-                Node::Doctype(data) => {
-                    record.kind = "directive".into();
-                    record.name = Some("!doctype".into());
-                    record
-                        .extras
-                        .insert("x-name".into(), Value::String(data.name().into()));
-                    record
-                        .extras
-                        .insert("x-publicId".into(), Value::String(data.public_id().into()));
-                    record
-                        .extras
-                        .insert("x-systemId".into(), Value::String(data.system_id().into()));
-                    let mut content = format!("!DOCTYPE {}", data.name());
-                    if !data.public_id().is_empty() {
-                        content.push_str(" PUBLIC ");
-                        content.push_str(&quote_doctype(data.public_id()));
-                    } else if !data.system_id().is_empty() {
-                        content.push_str(" SYSTEM");
-                    }
-                    if !data.system_id().is_empty() {
-                        content.push(' ');
-                        content.push_str(&quote_doctype(data.system_id()));
+                let selector = args["selector"].as_str().unwrap_or("");
+                let contexts = args.get("contexts").map(arena::value_ids);
+                self.with_tree_dom(&options, |dom| {
+                    if command == "select" {
+                        selector::select(dom, selector, contexts.as_deref())
+                    } else {
+                        selector::filter(dom, selector, ids)
                     }
-                    record.data = Some(content);
-                }
-                Node::ProcessingInstruction(data) => {
-                    record.kind = "directive".into();
-                    record.name = Some(data.target.to_string());
-                    record.data = Some(data.data.to_string());
+                    .map(|ids| serde_json::json!(ids))
+                })
+            }
+            "uniqueSort" => {
+                // Removed nodes have no place in the parse tree's order, so
+                // the arena orders them.
+                if self.tree_detached.get() {
+                    return None;
                 }
-                Node::Element(element) => {
-                    record.kind = match element.name() {
-                        "script" => "script",
-                        "style" => "style",
-                        _ => "tag",
+                self.with_tree_dom(options, |dom| {
+                    if !document_order::is_document_ordered(dom, ids) {
+                        return Ok(serde_json::json!(document_order::unique_sort(dom, ids)));
                     }
-                    .into();
-                    record.name = Some(element.name().into());
-                    record.extras.insert(
-                        "namespace".into(),
-                        Value::String(element.name.ns.to_string()),
-                    );
-                    if let Some(prefix) = &element.name.prefix {
-                        record
-                            .extras
-                            .insert("prefix".into(), Value::String(prefix.to_string()));
-                    }
-                    let (mut namespaces, mut prefixes) = (Map::new(), Map::new());
-                    for (name, value) in &element.attrs {
-                        let key = name.local.to_string();
-                        record
-                            .attribs
-                            .insert(key.clone(), Value::String(value.to_string()));
-                        if !name.ns.is_empty() {
-                            namespaces.insert(key.clone(), Value::String(name.ns.to_string()));
-                        }
-                        if let Some(prefix) = &name.prefix {
-                            prefixes.insert(key, Value::String(prefix.to_string()));
-                        }
-                    }
-                    record
-                        .extras
-                        .insert("attribsNamespace".into(), Value::Object(namespaces));
+                    // Local ids of a parse tree are preorder positions: document order.
+                    let mut unique = ids.to_vec();
+                    unique.sort_unstable();
+                    unique.dedup();
+                    Ok(serde_json::json!(unique))
+                })
+            }
+            "hasClass" => {
+                let needle = args["name"].as_str().unwrap_or("");
+                self.with_tree_dom(options, |dom| {
+                    Ok(Value::Bool(ids.iter().any(|id| {
+                        dom.is_element(*id)
+                            && dom
+                                .element_attr(*id, "class")
+                                .is_some_and(|classes| immutable::has_class_token(classes, needle))
+                    })))
+                })
+            }
+            "contains" => {
+                let container = args
+                    .get("container")
+                    .or_else(|| args.get("parent"))
+                    .and_then(Value::as_u64)
+                    .unwrap_or(0) as u32;
+                let contained = args
+                    .get("contained")
+                    .or_else(|| args.get("child"))
+                    .and_then(Value::as_u64)? as u32;
+                self.with_tree_dom(options, |dom| {
+                    Ok(Value::Bool(dom.index.contains(container, contained)))
+                })
+            }
+            "extractPlan" => Some(extraction::execute_in(self, &args["plan"], ids)),
+            _ => None,
+        }
+    }
+
+    /// A node with only the kind, name and attributes the attribute commands read.
+    fn attribute_node(&self, id: u32) -> Option<arena::DomNode> {
+        self.with_node(id, |node, _| {
+            let mut record = arena::DomNode::new("text");
+            if let Node::Element(element) = node.value() {
+                record.kind = match element.name() {
+                    "script" => "script",
+                    "style" => "style",
+                    _ => "tag",
+                }
+                .into();
+                record.name = Some(element.name().into());
+                record.attribs = Map::with_capacity(element.attrs.len());
+                for (name, value) in &element.attrs {
                     record
-                        .extras
-                        .insert("attribsPrefix".into(), Value::Object(prefixes));
+                        .attribs
+                        .insert(name.local.to_string(), Value::String(value.to_string()));
                 }
             }
             record
         })
     }
 
-    fn immutable_record(&self, id: u32) -> Option<Value> {
-        serde_json::to_value(self.immutable_dom_node(id)?).ok()
+    /// Applies a write that only changes attributes to the parse tree, so the
+    /// document is not copied into the mutable arena. The arena's own attribute
+    /// logic runs on a temporary arena holding just the target elements.
+    fn tree_attribute_write(
+        &self,
+        command: &str,
+        args: &Value,
+        ids: &[u32],
+        options: &Value,
+    ) -> Option<Result<Value>> {
+        let is_write = match command {
+            "attr" | "css" => args.get("value").is_some(),
+            "removeAttr" | "addClass" | "removeClass" | "toggleClass" => true,
+            _ => false,
+        };
+        if !is_write || self.source.borrow().is_some() {
+            return None;
+        }
+        let mut targets: Vec<u32> = Vec::new();
+        for id in ids {
+            if !targets.contains(id) {
+                targets.push(*id);
+            }
+        }
+        let nodes: Vec<arena::DomNode> = targets
+            .iter()
+            .map(|id| self.attribute_node(*id))
+            .collect::<Option<_>>()?;
+        let before: Vec<Map<String, Value>> =
+            nodes.iter().map(|node| node.attribs.clone()).collect();
+        let mut scratch = arena::DomArena::from_records(nodes, options.clone());
+        if self.options.get("__utf16Codec") == Some(&Value::Bool(true)) {
+            scratch.options["__utf16Codec"] = Value::Bool(true);
+        }
+        let mut local_args = args.clone();
+        local_args["ids"] = serde_json::json!(ids
+            .iter()
+            .map(|id| targets.iter().position(|target| target == id).unwrap_or(0))
+            .collect::<Vec<_>>());
+        let result = match attributes::execute(&mut scratch, command, &local_args) {
+            Ok(Some(result)) => result,
+            Ok(None) => return None,
+            Err(error) => return Some(Err(error)),
+        };
+        let mut html = self.html.borrow_mut();
+        let html = html.as_mut()?;
+        let node_ids = self.ids.borrow();
+        for (index, id) in targets.iter().enumerate() {
+            let after = &scratch.nodes[index].attribs;
+            if *after == before[index] {
+                continue;
+            }
+            let mut node = html.tree.get_mut(*node_ids.get(*id as usize)?)?;
+            let Node::Element(element) = node.value() else {
+                continue;
+            };
+            let attributes = after
+                .iter()
+                .map(|(name, value)| {
+                    let qualified = element
+                        .attrs
+                        .keys()
+                        .rev()
+                        .find(|key| key.local.as_ref() == name)
+                        .cloned()
+                        .unwrap_or_else(|| {
+                            html5ever::QualName::new(
+                                None,
+                                html5ever::ns!(),
+                                html5ever::LocalName::from(name.as_str()),
+                            )
+                        });
+                    let value = value
+                        .as_str()
+                        .map_or_else(|| value.to_string(), str::to_owned);
+                    html5ever::Attribute {
+                        name: qualified,
+                        value: value.into(),
+                    }
+                })
+                .collect();
+            *element = scraper::node::Element::new(element.name.clone(), attributes);
+        }
+        Some(Ok(result))
+    }
+
+    /// Cheerio-compatible selection without copying an unchanged document.
+    fn select_native(&self, source: &str, contexts: Option<&[u32]>) -> Result<Vec<u32>> {
+        if let Some(result) =
+            self.with_tree_dom(&self.options, |dom| selector::select(dom, source, contexts))
+        {
+            return result;
+        }
+        self.ensure_arena()?;
+        selector::select(self.arena.borrow().as_ref().unwrap(), source, contexts)
     }
 
     fn select_ids(&self, source: &str, contexts: Option<&[u32]>) -> Result<Vec<u32>> {
         self.maybe_collect();
         let contexts = contexts.filter(|contexts| *contexts != [0]);
         if self.arena.borrow().is_some()
+            || self.tree_detached.get()
             || contexts.is_some()
             || self.options.get("__losslessUnicode") == Some(&Value::Bool(true))
             || codec::has_encoding(source)
@@ -564,17 +860,12 @@ impl NativeDocument {
                 .next()
                 .is_some_and(|ch| matches!(ch, '>' | '+' | '~'))
             || source.contains("!=")
+            || compares_case_insensitive_attribute(source)
         {
-            self.ensure_arena()?;
-            return selector::select(self.arena.borrow().as_ref().unwrap(), source, contexts);
-        }
-        let normalized = normalize_attribute_namespaces(source);
-        let selector = match Selector::parse(&normalized) {
-            Ok(selector) => selector,
-            Err(_) => {
-                self.ensure_arena()?;
-                return selector::select(self.arena.borrow().as_ref().unwrap(), source, contexts);
-            }
+            return self.select_native(source, contexts);
+        }
+        let Some(selector) = parsed_selector(source) else {
+            return self.select_native(source, contexts);
         };
         let mut matched = Vec::new();
 
@@ -686,6 +977,207 @@ impl NativeDocument {
             }
         }
     }
+    /// Every live node that `root` does not reach; a parse tree has none.
+    #[napi(js_name = "detachedSlots")]
+    pub fn detached_slots(&self, root: u32) -> Uint32Array {
+        if let Some(arena) = self.arena.borrow().as_ref() {
+            return Uint32Array::from(arena.detached_slots(root));
+        }
+        Uint32Array::from(self.tree_detached_slots(root))
+    }
+
+    /// Nodes removed from the parse tree itself, which keeps them in place
+    /// but unreachable from `root`.
+    fn tree_detached_slots(&self, root: u32) -> Vec<u32> {
+        if !self.tree_detached.get() {
+            return Vec::new();
+        }
+        let html = self.html.borrow();
+        let ids = self.ids.borrow();
+        let reverse = self.reverse.borrow();
+        let Some(root) = html
+            .as_ref()
+            .zip(ids.get(root as usize))
+            .and_then(|(html, id)| html.tree.get(*id))
+        else {
+            return Vec::new();
+        };
+        let mut attached = vec![false; ids.len()];
+        for node in root.descendants() {
+            if let Some(local) = reverse.get(&node.id()) {
+                attached[*local as usize] = true;
+            }
+        }
+        (0..ids.len() as u32)
+            .filter(|local| !attached[*local as usize])
+            .collect()
+    }
+
+    /// Sets an attribute on elements, or removes it when `value` is `null`,
+    /// exactly as the `attr` command does, without copying an unchanged
+    /// document into the mutable arena.
+    #[napi(js_name = "setAttribute")]
+    pub fn set_attribute(&self, ids: Vec<u32>, name: String, value: Option<String>) -> Result<()> {
+        if self.arena.borrow().is_none() && self.source.borrow().is_none() {
+            if let Some(html) = self.html.borrow_mut().as_mut() {
+                let node_ids = self.ids.borrow();
+                for id in &ids {
+                    let Some(mut node) = node_ids
+                        .get(*id as usize)
+                        .and_then(|node_id| html.tree.get_mut(*node_id))
+                    else {
+                        continue;
+                    };
+                    if let Node::Element(element) = node.value() {
+                        let attributes = with_attribute(element, &name, value.as_deref());
+                        *element = scraper::node::Element::new(element.name.clone(), attributes);
+                    }
+                }
+                return Ok(());
+            }
+        }
+        self.ensure_arena()?;
+        if let Some(arena) = self.arena_for_write().as_mut() {
+            arena.set_attr(&ids, &name, value.as_deref());
+        }
+        Ok(())
+    }
+
+    /// This document's routing index, assigned on first call. An index is
+    /// reused only once its document has been finalized, when nothing in
+    /// JavaScript can hold the document's node ids any more.
+    #[napi(js_name = "routingIndex")]
+    pub fn routing_index(&self) -> u32 {
+        if let Some(index) = self.routing_index.get() {
+            return index;
+        }
+        let index = FREE_ROUTING_INDEXES
+            .with(|free| free.borrow_mut().pop())
+            .unwrap_or_else(|| {
+                NEXT_ROUTING_INDEX.with(|next| {
+                    let index = next.get();
+                    next.set(index.saturating_add(1));
+                    index
+                })
+            });
+        self.routing_index.set(Some(index));
+        index
+    }
+
+    /// Documents in this process whose native storage has not been dropped,
+    /// for tests of memory release; resident memory is a noisy signal.
+    #[napi(js_name = "liveDocumentCount")]
+    pub fn live_document_count(&self) -> u32 {
+        LIVE_DOCUMENTS.load(std::sync::atomic::Ordering::Relaxed) as u32
+    }
+
+    /// Whether removed created nodes and arena growth make a collection worthwhile.
+    #[napi(js_name = "isCollectionDue")]
+    pub fn is_collection_due(&self) -> bool {
+        self.arena
+            .borrow()
+            .as_ref()
+            .is_some_and(arena::DomArena::is_collection_due)
+    }
+
+    /// The number of node slots, including released ones.
+    #[napi(js_name = "slotCount")]
+    pub fn slot_count(&self) -> u32 {
+        match self.arena.borrow().as_ref() {
+            Some(arena) => arena.nodes.len() as u32,
+            None => self.ids.borrow().len() as u32,
+        }
+    }
+
+    /// Parents whose child lists changed since the last call; `null` when
+    /// too many changed to list and every parent must be treated as changed.
+    #[napi(js_name = "takeTouched")]
+    pub fn take_touched(&self) -> Option<Uint32Array> {
+        let removed = std::mem::take(&mut *self.tree_touched.borrow_mut());
+        match self.arena_for_write().as_mut() {
+            Some(arena) => arena.take_touched().map(|mut touched| {
+                touched.extend(removed);
+                Uint32Array::from(touched)
+            }),
+            None => Some(Uint32Array::from(removed)),
+        }
+    }
+
+    /// Removes nodes from the parse tree itself: the common clean-up before
+    /// reading text or markup then needs no copy into the mutable arena.
+    fn remove_from_tree(&self, ids: &[u32]) {
+        let mut html = self.html.borrow_mut();
+        let Some(html) = html.as_mut() else {
+            return;
+        };
+        let node_ids = self.ids.borrow();
+        let reverse = self.reverse.borrow();
+        let mut touched = self.tree_touched.borrow_mut();
+        for id in ids {
+            let Some(node_id) = node_ids.get(*id as usize) else {
+                continue;
+            };
+            let Some(mut node) = html.tree.get_mut(*node_id) else {
+                continue;
+            };
+            let Some(parent) = node.parent().map(|parent| parent.id()) else {
+                continue;
+            };
+            node.detach();
+            touched.extend(reverse.get(&parent).copied());
+        }
+        self.tree_detached.set(true);
+        *self.tree_index.borrow_mut() = None;
+    }
+
+    /// Replaces every pin with `pins`, the nodes JavaScript still references,
+    /// then reclaims detached nodes that are neither pinned, below
+    /// `keep_below`, nor connected to such a node. Computing pins at
+    /// collection time lets JavaScript track references without a native call
+    /// per node.
+    #[napi(js_name = "collectPinned")]
+    pub fn collect_pinned(
+        &self,
+        env: Env,
+        pins: Uint32Array,
+        keep_below: Option<u32>,
+    ) -> PinnedCollection {
+        self.kept_slots.set(keep_below.unwrap_or(0));
+        let mut retained = HashMap::new();
+        {
+            let arena = self.arena.borrow();
+            let immutable_count = self.ids.borrow().len();
+            for id in pins.iter() {
+                let exists = arena
+                    .as_ref()
+                    .map_or((*id as usize) < immutable_count, |arena| {
+                        arena.node(*id).is_some()
+                    });
+                if exists {
+                    *retained.entry(*id).or_insert(0) += 1;
+                }
+            }
+        }
+        *self.retained.borrow_mut() = retained;
+        self.managed.set(true);
+        let stats = self.collect_garbage_and_report(env);
+        let free = self
+            .arena
+            .borrow()
+            .as_ref()
+            .map(|arena| arena.free.clone())
+            .unwrap_or_default();
+        PinnedCollection {
+            live: stats.live,
+            slots: stats.slots,
+            retained: stats.retained,
+            reclaimed: stats.reclaimed,
+            immutable_nodes: stats.immutable_nodes,
+            external_bytes: stats.external_bytes,
+            free: free.into(),
+        }
+    }
+
     #[napi(js_name = "collectGarbage")]
     pub fn collect_garbage_and_report(&self, env: Env) -> MemoryStats {
         let stats = self.collect_garbage();
@@ -698,13 +1190,17 @@ impl NativeDocument {
 
     pub fn collect_garbage(&self) -> MemoryStats {
         self.needs_collect.set(false);
-        if self.arena.borrow().is_none() && self.managed.get() && self.retained.borrow().is_empty()
+        if self.arena.borrow().is_none()
+            && self.managed.get()
+            && self.kept_slots.get() == 0
+            && self.retained.borrow().is_empty()
         {
             self.html.borrow_mut().take();
             self.source.borrow_mut().take();
             let reclaimed = self.ids.borrow().len() as u32;
             *self.ids.borrow_mut() = Vec::new();
-            *self.reverse.borrow_mut() = HashMap::new();
+            *self.reverse.borrow_mut() = id_hash::IdMap::default();
+            *self.tree_index.borrow_mut() = None;
             return MemoryStats {
                 live: 0,
                 slots: 0,
@@ -714,8 +1210,13 @@ impl NativeDocument {
                 external_bytes: self.reported_heap_bytes.get(),
             };
         }
-        if let Some(arena) = self.arena.borrow_mut().as_mut() {
-            let stats = gc::collect_managed(arena, &self.retained.borrow(), !self.managed.get());
+        if let Some(arena) = self.arena_for_write().as_mut() {
+            let stats = gc::collect_managed(
+                arena,
+                &self.retained.borrow(),
+                !self.managed.get(),
+                self.kept_slots.get(),
+            );
             arena.free = stats.free;
             MemoryStats {
                 live: stats.live,
@@ -806,7 +1307,7 @@ impl NativeDocument {
         if (self.tag_name(id).as_deref() == Some("template") || self.arena.borrow().is_some())
             && self.ensure_arena().is_ok()
         {
-            return self.arena.borrow_mut().as_mut().unwrap().inner_html_mut(id);
+            return self.arena_for_write().as_mut().unwrap().inner_html_mut(id);
         }
         self.serialize_nodes(&[id], true)
     }
@@ -816,6 +1317,53 @@ impl NativeDocument {
         self.serialize_nodes(&ids, false)
     }
 
+    /// Serializes nodes as the `render` command does, returning the markup
+    /// itself rather than markup encoded as JSON.
+    #[napi(js_name = "render")]
+    pub fn render_and_report(
+        &self,
+        env: Env,
+        ids: Vec<u32>,
+        options_json: Option<String>,
+    ) -> Result<String> {
+        self.maybe_collect();
+        let overrides = match options_json {
+            Some(json) => Some(serde_json::from_str::<Value>(&json).map_err(json_error)?),
+            None => None,
+        }
+        .filter(Value::is_object);
+        let rendered = self.render_nodes(&ids, overrides)?;
+        Ok(self.reported(env, rendered))
+    }
+
+    fn render_nodes(&self, ids: &[u32], overrides: Option<Value>) -> Result<String> {
+        if self.arena.borrow().is_none() {
+            let mut options = self.options.clone();
+            if let Some(Value::Object(overrides)) = &overrides {
+                for (key, value) in overrides {
+                    options[key] = value.clone();
+                }
+            }
+            let options = arena::normalized_options(options);
+            if !arena::xml_mode(&options)
+                && options.get("_useHtmlParser2") != Some(&Value::Bool(true))
+            {
+                return Ok(self.serialize_nodes(ids, false));
+            }
+        }
+        self.ensure_arena()?;
+        let arena = self.arena.borrow();
+        let arena = arena.as_ref().unwrap();
+        let mut options = match overrides {
+            Some(overrides) => arena::normalized_options(overrides),
+            None => arena.options.clone(),
+        };
+        if self.options.get("__utf16Codec") == Some(&Value::Bool(true)) {
+            options["__utf16Codec"] = Value::Bool(true);
+        }
+        Ok(arena.serialize(ids, &arena::normalized_options(options)))
+    }
+
     #[napi]
     pub fn attr(&self, id: u32, name: String) -> Option<String> {
         self.attribute(id, &name)
@@ -852,6 +1400,18 @@ impl NativeDocument {
         serde_json::to_string(&records).map_err(json_error)
     }
 
+    /// Every node record at once, in the compact form `snapshot.rs` describes.
+    #[napi]
+    pub fn snapshot(&self, env: Env) -> Result<Object> {
+        self.maybe_collect();
+        if self.source.borrow().is_some() {
+            self.ensure_arena()?;
+        }
+        let built = snapshot::build(self);
+        self.report_heap_bytes(env);
+        built.into_js(&env)
+    }
+
     #[napi(js_name = "node")]
     pub fn node_and_report(&self, env: Env, id: u32) -> Result<String> {
         self.reported(env, self.node(id))
@@ -921,7 +1481,7 @@ impl NativeDocument {
         }
         self.ensure_arena()?;
         source.ensure_arena()?;
-        let mut source_arena = source.arena.borrow_mut();
+        let mut source_arena = source.arena_for_write();
         let source_arena = source_arena.as_mut().unwrap();
         // Detach all requested roots first: overlapping roots become siblings
         // and each requested descendant is imported exactly once.
@@ -940,7 +1500,7 @@ impl NativeDocument {
                 stack.extend(node.children.iter().rev().copied());
             }
         }
-        let mut target_arena = self.arena.borrow_mut();
+        let mut target_arena = self.arena_for_write();
         let target_arena = target_arena.as_mut().unwrap();
         target_arena.nodes.reserve(moved.len());
         let (roots, mapping) = if detach.unwrap_or(true) {
@@ -1014,6 +1574,14 @@ impl NativeDocument {
         if command == "node" {
             return self.node(args["id"].as_u64().unwrap_or(0) as u32);
         }
+        if command == "remove"
+            && args["keepChildren"].as_bool() != Some(true)
+            && self.arena.borrow().is_none()
+            && self.source.borrow().is_none()
+        {
+            self.remove_from_tree(&arena::value_ids(&args["ids"]));
+            return Ok("null".into());
+        }
         if self.arena.borrow().is_none() {
             let ids = arena::value_ids(&args["ids"]);
             let effective_options = arena::normalized_options(
@@ -1078,6 +1646,14 @@ impl NativeDocument {
                     .unwrap_or(Value::Null);
                 return serde_json::to_string(&result).map_err(json_error);
             }
+            if let Some(result) = self.tree_read(&command, &args, &ids, &effective_options) {
+                return serde_json::to_string(&result?).map_err(json_error);
+            }
+            if let Some(result) =
+                self.tree_attribute_write(&command, &args, &ids, &effective_options)
+            {
+                return serde_json::to_string(&result?).map_err(json_error);
+            }
             if command == "render" || command == "outerHtml" {
                 let mut options = self.options.clone();
                 if let Some(overrides) = args.get("options").and_then(Value::as_object) {
@@ -1095,7 +1671,7 @@ impl NativeDocument {
             }
         }
         self.ensure_arena()?;
-        let mut arena = self.arena.borrow_mut();
+        let mut arena = self.arena_for_write();
         let arena = arena.as_mut().unwrap();
         let previous_options = arena.options.clone();
         if let Some(options) = args.get("options").filter(|options| options.is_object()) {
@@ -1124,6 +1700,18 @@ impl NativeDocument {
     }
 }
 
+#[napi(object)]
+pub struct PinnedCollection {
+    pub live: u32,
+    pub slots: u32,
+    pub retained: u32,
+    pub reclaimed: u32,
+    pub immutable_nodes: u32,
+    pub external_bytes: i64,
+    /// Slots that hold no node after collection.
+    pub free: Uint32Array,
+}
+
 #[napi(object)]
 pub struct MemoryStats {
     pub live: u32,
@@ -1203,6 +1791,309 @@ fn normalize_attribute_namespaces(source: &str) -> Cow<'_, str> {
     Cow::Owned(normalized)
 }
 
+/// An element's attributes after setting or removing `name`. Attributes are
+/// keyed by local name as in the arena: a repeated local name keeps its first
+/// position, with the name and value of its last occurrence.
+fn with_attribute(
+    element: &scraper::node::Element,
+    name: &str,
+    value: Option<&str>,
+) -> Vec<html5ever::Attribute> {
+    let mut attributes: Vec<html5ever::Attribute> = Vec::with_capacity(element.attrs.len() + 1);
+    for (key, current) in &element.attrs {
+        let attribute = html5ever::Attribute {
+            name: key.clone(),
+            value: current.as_ref().into(),
+        };
+        match attributes
+            .iter_mut()
+            .find(|existing| existing.name.local == key.local)
+        {
+            Some(existing) => *existing = attribute,
+            None => attributes.push(attribute),
+        }
+    }
+    match value {
+        Some(value) => match attributes
+            .iter_mut()
+            .find(|attribute| attribute.name.local.as_ref() == name)
+        {
+            Some(attribute) => attribute.value = value.into(),
+            None => attributes.push(html5ever::Attribute {
+                name: html5ever::QualName::new(
+                    None,
+                    html5ever::ns!(),
+                    html5ever::LocalName::from(name),
+                ),
+                value: value.into(),
+            }),
+        },
+        None => attributes.retain(|attribute| attribute.name.local.as_ref() != name),
+    }
+    attributes
+}
+
+thread_local! {
+    /// Parse-tree selectors by source, or `None` for sources they cannot express.
+    static SELECTORS: RefCell<HashMap<String, Option<std::rc::Rc<Selector>>>> = RefCell::new(HashMap::new());
+}
+
+/// A selector for the parse tree, parsed once per source per thread.
+fn parsed_selector(source: &str) -> Option<std::rc::Rc<Selector>> {
+    if let Some(parsed) = SELECTORS.with(|cache| cache.borrow().get(source).cloned()) {
+        return parsed;
+    }
+    let parsed = Selector::parse(&normalize_attribute_namespaces(source))
+        .ok()
+        .map(std::rc::Rc::new);
+    SELECTORS.with(|cache| {
+        let mut cache = cache.borrow_mut();
+        if cache.len() >= 512 {
+            cache.clear();
+        }
+        cache.insert(source.to_owned(), parsed.clone());
+    });
+    parsed
+}
+
+/// Whether a selector compares the value of an attribute whose values HTML
+/// matches without regard to case, which the parse-tree selector engine does not.
+fn compares_case_insensitive_attribute(source: &str) -> bool {
+    source.contains('=')
+        && source.match_indices('[').any(|(index, _)| {
+            let name: String = source[index + 1..]
+                .trim_start()
+                .chars()
+                .take_while(|character| character.is_ascii_alphanumeric() || *character == '-')
+                .collect();
+            selector::CASE_INSENSITIVE_ATTRIBUTES
+                .iter()
+                .any(|candidate| name.eq_ignore_ascii_case(candidate))
+        })
+}
+
+/// `source` with CRLF and CR replaced by LF, as HTML5 input preprocessing does.
+fn normalize_newlines(source: &str) -> String {
+    let mut output = String::with_capacity(source.len());
+    let mut rest = source;
+    while let Some(index) = rest.find('\r') {
+        output.push_str(&rest[..index]);
+        output.push('\n');
+        rest = &rest[index + 1..];
+        if let Some(stripped) = rest.strip_prefix('\n') {
+            rest = stripped;
+        }
+    }
+    output.push_str(rest);
+    output
+}
+
+/// Whether HTML5 parses `source` as a fragment to a single text node holding
+/// it unchanged: no markup, character references, carriage returns to
+/// normalize or NUL characters to replace.
+fn is_plain_text(source: &str) -> bool {
+    !source
+        .bytes()
+        .any(|byte| matches!(byte, b'<' | b'&' | b'\r' | b'\0'))
+}
+
+/// The fragment HTML5 builds from plain text, without running the parser,
+/// whose fixed setup costs more than parsing a short string.
+fn plain_text_fragment(source: &str) -> Html {
+    let mut html = Html::new_fragment();
+    if !source.is_empty() {
+        html.tree.root_mut().append(Node::Text(scraper::node::Text {
+            text: source.into(),
+        }));
+    }
+    html
+}
+
+/// A parse target with node storage sized for `source`: grown one
+/// reallocation at a time, it copies every node again, which dominates the
+/// parse of small inputs. Large documents grow from the cap.
+fn sized_html(source: &str, is_document: bool) -> Html {
+    const MAXIMUM_INITIAL_NODES: usize = 4096;
+    let capacity = (source.len() / 16 + 8).min(MAXIMUM_INITIAL_NODES);
+    let mut html = if is_document {
+        Html::new_document()
+    } else {
+        Html::new_fragment()
+    };
+    let root = if is_document {
+        Node::Document
+    } else {
+        Node::Fragment
+    };
+    html.tree = ego_tree::Tree::with_capacity(root, capacity);
+    html
+}
+
+/// html5ever's fragment sink creates a synthetic html element; Cheerio
+/// exposes the fragment's actual children at its root. Children move one at a
+/// time because `reparent_from_id_append` only re-points the first and last
+/// moved child at their new parent.
+fn unwrap_fragment_root(html: &mut Html) {
+    let wrapper = html.tree.root().children().find_map(|node| {
+        node.value()
+            .as_element()
+            .filter(|element| element.name() == "html")
+            .map(|_| node.id())
+    });
+    let Some(wrapper) = wrapper else { return };
+    let children: Vec<NodeId> = html
+        .tree
+        .get(wrapper)
+        .map(|node| node.children().map(|child| child.id()).collect())
+        .unwrap_or_default();
+    let mut root = html.tree.root_mut();
+    for child in children {
+        root.append_id(child);
+    }
+    html.tree.get_mut(wrapper).unwrap().detach();
+}
+
+/// Nodes converted per worker task when copying a parse tree into the arena.
+const CONVERSION_CHUNK: usize = 2048;
+
+/// A parse tree read by several workers at once while copying it into the
+/// mutable arena.
+struct SharedTree<'a> {
+    html: &'a Html,
+    ids: &'a [NodeId],
+    reverse: &'a id_hash::IdMap<NodeId, u32>,
+}
+
+// SAFETY: `Html` is not `Sync` only because elements cache their id and
+// classes in `OnceCell`s and tendrils keep their header in `Cell`s. Conversion
+// reads names, attribute lists and text through shared references and never
+// touches those caches, and the owning thread waits for the workers, so no
+// write can race these reads.
+unsafe impl Sync for SharedTree<'_> {}
+
+impl SharedTree<'_> {
+    fn convert(&self, range: std::ops::Range<usize>) -> Vec<arena::DomNode> {
+        let mut nodes = Vec::with_capacity(range.len());
+        nodes.extend(
+            range.filter_map(|id| convert_node(self.html, self.ids, self.reverse, id as u32)),
+        );
+        nodes
+    }
+}
+
+/// A parse-tree node as a mutable-arena record. It reads only names,
+/// attributes and text, never the tree's lazily filled caches.
+fn convert_node(
+    html: &Html,
+    ids: &[NodeId],
+    reverse: &id_hash::IdMap<NodeId, u32>,
+    id: u32,
+) -> Option<arena::DomNode> {
+    let node = html.tree.get(*ids.get(id as usize)?)?;
+    let pointer =
+        |node: Option<NodeRef<'_, Node>>| node.and_then(|node| reverse.get(&node.id()).copied());
+    let mut record = arena::DomNode::new("root");
+    record.id = id;
+    record.children = node
+        .children()
+        .filter_map(|child| reverse.get(&child.id()).copied())
+        .collect();
+    record.parent = pointer(node.parent());
+    record.prev = pointer(node.prev_sibling());
+    record.next = pointer(node.next_sibling());
+    match node.value() {
+        Node::Document => {
+            record.extras.insert(
+                "x-mode".into(),
+                Value::String(
+                    match html.quirks_mode {
+                        html5ever::tree_builder::QuirksMode::Quirks => "quirks",
+                        html5ever::tree_builder::QuirksMode::LimitedQuirks => "limited-quirks",
+                        html5ever::tree_builder::QuirksMode::NoQuirks => "no-quirks",
+                    }
+                    .into(),
+                ),
+            );
+        }
+        Node::Fragment => {}
+        Node::Text(data) => {
+            record.kind = "text".into();
+            record.data = Some(String::from(&**data));
+        }
+        Node::Comment(data) => {
+            record.kind = "comment".into();
+            record.data = Some(String::from(&**data));
+        }
+        Node::Doctype(data) => {
+            record.kind = "directive".into();
+            record.name = Some("!doctype".into());
+            record
+                .extras
+                .insert("x-name".into(), Value::String(data.name().into()));
+            record
+                .extras
+                .insert("x-publicId".into(), Value::String(data.public_id().into()));
+            record
+                .extras
+                .insert("x-systemId".into(), Value::String(data.system_id().into()));
+            record.data = Some(doctype_content(data));
+        }
+        Node::ProcessingInstruction(data) => {
+            record.kind = "directive".into();
+            record.name = Some(String::from(&*data.target));
+            record.data = Some(String::from(&*data.data));
+        }
+        Node::Element(element) => {
+            record.kind = match element.name() {
+                "script" => "script",
+                "style" => "style",
+                _ => "tag",
+            }
+            .into();
+            record.name = Some(element.name().into());
+            record.namespace = Some(arena::namespace_name(&element.name.ns));
+            if let Some(prefix) = &element.name.prefix {
+                record
+                    .extras
+                    .insert("prefix".into(), Value::String(String::from(&**prefix)));
+            }
+            let (mut namespaces, mut prefixes) = (Map::new(), Map::new());
+            record.attribs = Map::with_capacity(element.attrs.len());
+            for (name, value) in &element.attrs {
+                let key = String::from(&*name.local);
+                if !name.ns.is_empty() {
+                    namespaces.insert(key.clone(), Value::String(String::from(&*name.ns)));
+                }
+                if let Some(prefix) = &name.prefix {
+                    prefixes.insert(key.clone(), Value::String(String::from(&**prefix)));
+                }
+                record
+                    .attribs
+                    .insert(key, Value::String(String::from(&**value)));
+            }
+            record.attribs_namespace = Some(Box::new(namespaces));
+            record.attribs_prefix = Some(Box::new(prefixes));
+        }
+    }
+    Some(record)
+}
+
+/// A doctype's `data`, as htmlparser2 reports the declaration.
+pub(crate) fn doctype_content(data: &scraper::node::Doctype) -> String {
+    let mut content = format!("!DOCTYPE {}", data.name());
+    if !data.public_id().is_empty() {
+        content.push_str(" PUBLIC ");
+        content.push_str(&quote_doctype(data.public_id()));
+    } else if !data.system_id().is_empty() {
+        content.push_str(" SYSTEM");
+    }
+    if !data.system_id().is_empty() {
+        content.push(' ');
+        content.push_str(&quote_doctype(data.system_id()));
+    }
+    content
+}
+
 fn quote_doctype(value: &str) -> String {
     let quote = if value.contains('"') { '\'' } else { '"' };
     format!("{quote}{value}{quote}")
@@ -1323,7 +2214,13 @@ fn serialize_node(node: NodeRef<'_, Node>, output: &mut String) {
             Node::Element(element) => {
                 output.push('<');
                 output.push_str(element.name());
-                for (name, value) in &element.attrs {
+                let attributes = js_property_order(
+                    element
+                        .attrs
+                        .iter()
+                        .map(|(name, value)| (name.local.as_ref(), (name, value))),
+                );
+                for (_, (name, value)) in attributes {
                     output.push(' ');
                     push_attribute_name(
                         output,
@@ -1589,6 +2486,32 @@ pub fn extract_plan_many_async(
 mod tests {
     use super::*;
 
+    #[test]
+    fn attribute_writes_keep_the_parse_tree() {
+        let document = NativeDocument::parse(
+            "<main><p id='a' class='x'>one</p><svg><use href='#h' xlink:href='#x'/></svg></main>",
+            false,
+        );
+        let ids = document.select_ids("p, use", None).unwrap();
+        for (command, args) in [
+            (
+                "attr",
+                serde_json::json!({"ids":ids,"name":"data-k","value":"v"}),
+            ),
+            ("addClass", serde_json::json!({"ids":ids,"name":"y z"})),
+            ("removeClass", serde_json::json!({"ids":ids,"name":"x"})),
+            ("removeAttr", serde_json::json!({"ids":ids,"name":"id"})),
+        ] {
+            document.op(command.into(), args.to_string()).unwrap();
+        }
+        assert!(document.arena.borrow().is_none());
+        assert_eq!(
+            document.serialize_nodes(&ids, false),
+            "<p class=\"y z\" data-k=\"v\">one</p><use xlink:href=\"#x\" data-k=\"v\" class=\"y z\"></use>"
+        );
+        assert_eq!(document.select_ids(".z", None).unwrap(), ids);
+    }
+
     #[test]
     fn managed_detached_payloads_are_reclaimed_and_slots_are_reused() {
         let document = NativeDocument::parse("<main></main>", false);
@@ -1596,8 +2519,8 @@ mod tests {
         let main = document.select_ids("main", None).unwrap()[0];
         document
             .op(
-                "attr".into(),
-                serde_json::json!({"ids":[main],"name":"a","value":"b"}).to_string(),
+                "clone".into(),
+                serde_json::json!({"ids":[main],"deep":false}).to_string(),
             )
             .unwrap();
         assert_eq!(document.collect_garbage().immutable_nodes, 0);
@@ -2009,9 +2932,11 @@ mod tests {
                 serde_json::json!({"ids":[detached,ul,detached]}).to_string(),
             )
             .unwrap();
+        // As domutils does: the last of repeated ids is kept, and nodes of
+        // separate trees keep their order.
         assert_eq!(
             serde_json::from_str::<Vec<u32>>(&sorted).unwrap(),
-            vec![detached, ul]
+            vec![ul, detached]
         );
     }