rdom_core/

tree.rs

//! Tree mutation: `append_child`, `remove_child`, `insert_before`, etc.
//!
//! ## Observer record ordering
//!
//! Every detach path (`remove_child`, `replace_child`, `replace_with`,
//! `clear_children`, `drop_subtree`) routes through
//! `detach_from_parent`, which clears any interaction state
//! (`focused` / `hovered` / `pointer_capture` / `selection`) that
//! pointed into the subtree being removed. The
//! `InteractionChanged` / `SelectionChanged` records for those
//! cleanups fire *during* the detach, before the caller's
//! `ChildListChanged` record. Observers therefore see "effect"
//! records before the "cause" record. The alternative —
//! post-detach purge in every caller — would centralize the
//! ordering at the cost of forgetting it on a future tree-mutation
//! API. Document, don't decentralize.
//!
//! Every mutation maintains the doubly-linked sibling chain + first_child/
//! last_child + parent invariants. Fragment insertion unwraps the fragment's
//! children. Cycle detection via `is_ancestor`.
//!
//! These are the primitives every user-facing mutation builds on.

use crate::dom::Dom;
use crate::error::{DomError, Result};
use crate::node::NodeData;
use crate::node_id::NodeId;
use crate::observer::Mutation;

/// Position relative to a reference node, for `insert_adjacent*`.
///
/// Mirrors HTML `insertAdjacentElement`:
///   - `BeforeBegin` — as previous sibling of reference
///   - `AfterBegin`  — as first child of reference
///   - `BeforeEnd`   — as last child of reference
///   - `AfterEnd`    — as next sibling of reference
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AdjacentPosition {
    BeforeBegin,
    AfterBegin,
    BeforeEnd,
    AfterEnd,
}

impl<Ext: 'static> Dom<Ext> {
    /// Append `child` as the last child of `parent`. If `child` is a
    /// Fragment, its children are appended and the fragment is emptied.
    ///
    /// Returns `Err(HierarchyRequest)` if `child` is an ancestor of
    /// `parent` (would create a cycle), `Err(InvalidNode)` for unknown ids.
    pub fn append_child(&mut self, parent: NodeId, child: NodeId) -> Result<()> {
        self.validate_insert(parent, child)?;

        // Fragment: splice its children in, leave the fragment empty.
        if matches!(
            self.get_node(child).map(|n| &n.data),
            Some(NodeData::Fragment)
        ) {
            let mut current = self.get_node(child).and_then(|n| n.first_child);
            // Clear fragment's child pointers up front; we re-link below.
            if let Some(n) = self.get_node_mut(child) {
                n.first_child = None;
                n.last_child = None;
            }
            while let Some(c) = current {
                // Capture next sibling before detaching.
                let next = self.get_node(c).and_then(|n| n.next_sibling);
                if let Some(n) = self.get_node_mut(c) {
                    n.prev_sibling = None;
                    n.next_sibling = None;
                    n.parent = None;
                }
                self.append_child(parent, c)?;
                current = next;
            }
            return Ok(());
        }

        // Detach child from current parent if any.
        self.detach_from_parent(child)?;

        // Link child under parent at the end.
        let last = self.get_node(parent).and_then(|n| n.last_child);
        self.get_node_mut(child)
            .ok_or(DomError::InvalidNode(child))?
            .parent = Some(parent);
        self.get_node_mut(child).unwrap().prev_sibling = last;
        self.get_node_mut(child).unwrap().next_sibling = None;

        match last {
            Some(prev) => {
                self.get_node_mut(prev).unwrap().next_sibling = Some(child);
            }
            None => {
                // Empty parent — also becomes first_child.
                self.get_node_mut(parent).unwrap().first_child = Some(child);
            }
        }
        self.get_node_mut(parent).unwrap().last_child = Some(child);
        self.fire_mutation(Mutation::ChildListChanged {
            parent,
            added: vec![child],
            removed: vec![],
        });
        Ok(())
    }

    /// Prepend `child` as the first child of `parent`.
    pub fn prepend_child(&mut self, parent: NodeId, child: NodeId) -> Result<()> {
        let first = self.get_node(parent).and_then(|n| n.first_child);
        self.insert_before(parent, child, first)
    }

    /// Insert `new_child` before `reference_child` within `parent`.
    /// If `reference_child` is `None`, appends at the end (matches spec
    /// behavior).
    pub fn insert_before(
        &mut self,
        parent: NodeId,
        new_child: NodeId,
        reference_child: Option<NodeId>,
    ) -> Result<()> {
        // Null reference → append.
        let Some(reference) = reference_child else {
            return self.append_child(parent, new_child);
        };

        // Reference must be an actual child of parent.
        if self.get_node(reference).and_then(|n| n.parent) != Some(parent) {
            return Err(DomError::NotFound);
        }

        self.validate_insert(parent, new_child)?;

        // Fragment unwrap — iterate children and insert each before reference.
        if matches!(
            self.get_node(new_child).map(|n| &n.data),
            Some(NodeData::Fragment)
        ) {
            let mut current = self.get_node(new_child).and_then(|n| n.first_child);
            if let Some(n) = self.get_node_mut(new_child) {
                n.first_child = None;
                n.last_child = None;
            }
            while let Some(c) = current {
                let next = self.get_node(c).and_then(|n| n.next_sibling);
                if let Some(n) = self.get_node_mut(c) {
                    n.prev_sibling = None;
                    n.next_sibling = None;
                    n.parent = None;
                }
                self.insert_before(parent, c, Some(reference))?;
                current = next;
            }
            return Ok(());
        }

        self.detach_from_parent(new_child)?;

        // Link: prev_of_reference <-> new_child <-> reference
        let before = self.get_node(reference).and_then(|n| n.prev_sibling);
        let new_node = self.get_node_mut(new_child).unwrap();
        new_node.parent = Some(parent);
        new_node.prev_sibling = before;
        new_node.next_sibling = Some(reference);

        match before {
            Some(prev) => {
                self.get_node_mut(prev).unwrap().next_sibling = Some(new_child);
            }
            None => {
                self.get_node_mut(parent).unwrap().first_child = Some(new_child);
            }
        }
        self.get_node_mut(reference).unwrap().prev_sibling = Some(new_child);
        self.fire_mutation(Mutation::ChildListChanged {
            parent,
            added: vec![new_child],
            removed: vec![],
        });
        Ok(())
    }

    /// Remove `child` from `parent`. Child is detached (parent + sibling
    /// pointers cleared) but **remains in the arena as an orphan** — it
    /// can be reattached elsewhere, or explicitly freed via
    /// [`drop_subtree`](Self::drop_subtree).
    ///
    /// The arena has no GC: a detached node is never reclaimed on its
    /// own. Code that removes nodes it will **not** reattach — especially
    /// high-churn UIs (a virtualized list/table re-materializing rows on
    /// every scroll) — must free them, or arena slots leak. Use
    /// [`remove_child_dropping`](Self::remove_child_dropping) to remove
    /// and free in one call.
    pub fn remove_child(&mut self, parent: NodeId, child: NodeId) -> Result<()> {
        if self.get_node(child).and_then(|n| n.parent) != Some(parent) {
            return Err(DomError::NotFound);
        }
        self.detach_from_parent(child)?;
        self.fire_mutation(Mutation::ChildListChanged {
            parent,
            added: vec![],
            removed: vec![child],
        });
        Ok(())
    }

    /// Replace `old_child` with `new_child` under `parent`. `old_child`
    /// is detached and becomes an orphan.
    pub fn replace_child(
        &mut self,
        parent: NodeId,
        old_child: NodeId,
        new_child: NodeId,
    ) -> Result<()> {
        if self.get_node(old_child).and_then(|n| n.parent) != Some(parent) {
            return Err(DomError::NotFound);
        }
        self.validate_insert(parent, new_child)?;

        let next = self.get_node(old_child).and_then(|n| n.next_sibling);
        self.detach_from_parent(old_child)?;
        self.insert_before(parent, new_child, next)
    }

    /// `insertAdjacentElement(position, new_child)`. `reference` is the
    /// node relative to which we insert.
    pub fn insert_adjacent(
        &mut self,
        reference: NodeId,
        position: AdjacentPosition,
        new_child: NodeId,
    ) -> Result<()> {
        match position {
            AdjacentPosition::BeforeBegin => {
                let parent = self
                    .get_node(reference)
                    .and_then(|n| n.parent)
                    .ok_or(DomError::HierarchyRequest)?;
                self.insert_before(parent, new_child, Some(reference))
            }
            AdjacentPosition::AfterBegin => self.prepend_child(reference, new_child),
            AdjacentPosition::BeforeEnd => self.append_child(reference, new_child),
            AdjacentPosition::AfterEnd => {
                let parent = self
                    .get_node(reference)
                    .and_then(|n| n.parent)
                    .ok_or(DomError::HierarchyRequest)?;
                let after = self.get_node(reference).and_then(|n| n.next_sibling);
                self.insert_before(parent, new_child, after)
            }
        }
    }

    /// Remove all children from `parent`. They become **orphans in the
    /// arena** (not freed — see [`remove_child`](Self::remove_child) on
    /// the no-GC contract). Fires a single `ChildListChanged` record with
    /// every removed child. To remove and free in one call, use
    /// [`clear_children_dropping`](Self::clear_children_dropping).
    pub fn clear_children(&mut self, parent: NodeId) -> Result<()> {
        self.node_or_err(parent)?;
        let mut removed: Vec<NodeId> = Vec::new();
        while let Some(first) = self.get_node(parent).and_then(|n| n.first_child) {
            removed.push(first);
            self.detach_from_parent(first)?;
        }
        if !removed.is_empty() {
            self.fire_mutation(Mutation::ChildListChanged {
                parent,
                added: vec![],
                removed,
            });
        }
        Ok(())
    }

    /// Drop `id` and its entire subtree from the arena — frees every slot.
    /// Useful when you know you'll never reattach the nodes.
    ///
    /// The root cannot be dropped (`HierarchyRequest`): `Dom::root` must
    /// stay live for the lifetime of the arena. Use
    /// [`clear_children_dropping`](Self::clear_children_dropping) to
    /// empty it.
    pub fn drop_subtree(&mut self, id: NodeId) -> Result<()> {
        self.node_or_err(id)?;
        if id == self.root {
            return Err(DomError::HierarchyRequest);
        }
        let parent = self.get_node(id).and_then(|n| n.parent);
        // Snapshot the subtree to free WHILE it's still alive and before
        // anything can panic.
        let mut to_free = Vec::new();
        self.collect_descendants(id, &mut to_free);
        // Detach, then fire the mutation BEFORE freeing, so observers (the
        // dirty tracker, implicit blur/focusout-on-detach) can still read
        // the removed nodes in their callback — same contract as
        // `remove_child`, and what the MutationObserver spec requires
        // (`removedNodes` are inspectable). Both steps fire records
        // (detach purges focus / hover / selection inside the subtree); a
        // panicking observer is re-raised by `fire_mutation`, so the whole
        // window runs under one guard and the slots are reclaimed on the
        // way out (`CORE-DROP-PANIC-LEAK-1`).
        let outcome = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            let _ = self.detach_from_parent(id);
            if let Some(parent) = parent {
                self.fire_mutation(Mutation::ChildListChanged {
                    parent,
                    added: vec![],
                    removed: vec![id],
                });
            }
        }));
        self.free_if_detached(id, to_free);
        if let Err(payload) = outcome {
            std::panic::resume_unwind(payload);
        }
        Ok(())
    }

    /// Reclaim `to_free` (a subtree rooted at `root`) — unless `root` is
    /// still attached, which happens when an observer panicked in the
    /// `PreDetach` window, before the unlink: then the tree is intact and
    /// freeing it would leave the parent pointing at dead slots.
    fn free_if_detached(&mut self, root: NodeId, to_free: Vec<NodeId>) {
        if self.get_node(root).is_some_and(|n| n.parent.is_some()) {
            return;
        }
        for n in to_free {
            self.free(n);
        }
    }

    /// Remove `child` from `parent` **and free** its subtree from the
    /// arena (the non-leaking [`remove_child`](Self::remove_child)).
    /// Use when you won't reattach the removed node. Fires the same
    /// single `ChildListChanged` record `remove_child` does (the
    /// follow-up free runs on the already-detached orphan, so it adds no
    /// extra record). Observers still see the removed node alive in their
    /// synchronous callback — it's freed only after dispatch returns.
    pub fn remove_child_dropping(&mut self, parent: NodeId, child: NodeId) -> Result<()> {
        if self.get_node(child).and_then(|n| n.parent) != Some(parent) {
            return Err(DomError::NotFound);
        }
        let mut to_free = Vec::new();
        self.collect_descendants(child, &mut to_free);
        // Same guard as `drop_subtree`: the record fires inside
        // `remove_child`; a panicking observer must not leak the orphan.
        let outcome = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            self.remove_child(parent, child)
        }));
        self.free_if_detached(child, to_free);
        match outcome {
            Ok(result) => result,
            Err(payload) => std::panic::resume_unwind(payload),
        }
    }

    /// Remove all children from `parent` **and free** their subtrees
    /// from the arena (the non-leaking [`clear_children`](Self::clear_children)).
    /// Fires the same single `ChildListChanged` record `clear_children`
    /// does; the frees run on the already-detached orphans.
    pub fn clear_children_dropping(&mut self, parent: NodeId) -> Result<()> {
        self.node_or_err(parent)?;
        // Snapshot each child's subtree before detaching anything.
        let mut subtrees: Vec<(NodeId, Vec<NodeId>)> = Vec::new();
        let mut cur = self.get_node(parent).and_then(|n| n.first_child);
        while let Some(id) = cur {
            let mut to_free = Vec::new();
            self.collect_descendants(id, &mut to_free);
            subtrees.push((id, to_free));
            cur = self.get_node(id).and_then(|n| n.next_sibling);
        }
        // Detaches all, one batch record; guarded like `drop_subtree`.
        let outcome =
            std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| self.clear_children(parent)));
        for (child, to_free) in subtrees {
            self.free_if_detached(child, to_free);
        }
        match outcome {
            Ok(result) => result,
            Err(payload) => std::panic::resume_unwind(payload),
        }
    }

    // ── Internal helpers ─────────────────────────────────────────────

    /// Validate that inserting `child` under `parent` is legal.
    /// Cycle check + id existence.
    fn validate_insert(&self, parent: NodeId, child: NodeId) -> Result<()> {
        self.node_or_err(parent)?;
        self.node_or_err(child)?;
        if self.is_ancestor(child, parent) {
            return Err(DomError::HierarchyRequest);
        }
        Ok(())
    }

    /// Detach `id` from its parent. Fixes sibling chain + first/last_child
    /// on parent. Safe no-op if the node has no parent.
    ///
    /// Also clears any interaction state (`focused`, `hovered`,
    /// `active`, `pointer_capture`, `selection`) that pointed into the
    /// detached subtree. Without this, a `set_focused`/etc. pointing
    /// at a now-orphaned node leaves the Dom in an internally
    /// inconsistent state — `dom.focused()` returns a NodeId that's
    /// no longer in the tree, and `:focus` keeps matching it.
    ///
    /// Record-emission order is: `PreDetach`, then
    /// `InteractionChanged`/`SelectionChanged` for any cleared
    /// state — both while the subtree is still connected, so an
    /// observer can walk the cleared node's ancestors (whose
    /// `:hover` / `:active` / `:focus-within` flip) — then the
    /// structural pointer update. The `ChildListChanged` record that motivates the
    /// detach is fired by the caller (`remove_child`,
    /// `replace_with`, `clear_children`, ...) AFTER this returns,
    /// so observers see the interaction-state changes before the
    /// tree change that caused them. The simpler causal order
    /// would require each caller to remember a post-detach purge
    /// step — centralizing in this function trades that
    /// observability nuance for a structurally-guaranteed cleanup.
    pub(crate) fn detach_from_parent(&mut self, id: NodeId) -> Result<()> {
        self.node_or_err(id)?;
        // **Pre-detach event window** — fire `Mutation::PreDetach`
        // BEFORE structural unlink, while focused/hovered's
        // ancestor chains are still intact. Observers (notably
        // `rdom-tui`'s App-level observer) use this to dispatch
        // implicit `blur` / `focusout` / `mouseleave` / `mouseout`
        // events with normal bubbling semantics. Only emitted
        // when at least one of focused/hovered is actually inside
        // the subtree being detached — empty PreDetach records
        // would be noise. Membership is an O(depth) ancestor walk
        // from the state's node, not a walk of the subtree.
        let focused_in = self.focused.filter(|&f| self.is_ancestor(id, f));
        let hovered_in = self.hovered.filter(|&h| self.is_ancestor(id, h));
        if focused_in.is_some() || hovered_in.is_some() {
            self.fire_mutation(Mutation::PreDetach {
                detached_root: id,
                focused: focused_in,
                hovered: hovered_in,
            });
        }

        // Clear the interaction state inside the subtree while it is
        // still connected: `:hover`, `:active` and `:focus-within` also
        // match the ancestors, so an observer of the `InteractionChanged`
        // record must be able to walk from `prev` to them. A panicking
        // observer does not stop the unlink (the caller frees a dropped
        // subtree on the way out); whatever the purge had not reached
        // yet is cleared silently before the panic resumes.
        let purged = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            self.purge_interaction_state_for_subtree(id, true);
        }));

        let node = self.node_or_err(id)?;
        let parent = node.parent;
        let prev = node.prev_sibling;
        let next = node.next_sibling;

        if let Some(prev) = prev {
            self.get_node_mut(prev).unwrap().next_sibling = next;
        }
        if let Some(next) = next {
            self.get_node_mut(next).unwrap().prev_sibling = prev;
        }
        if let Some(parent) = parent {
            if self.get_node(parent).and_then(|n| n.first_child) == Some(id) {
                self.get_node_mut(parent).unwrap().first_child = next;
            }
            if self.get_node(parent).and_then(|n| n.last_child) == Some(id) {
                self.get_node_mut(parent).unwrap().last_child = prev;
            }
        }

        let n = self.get_node_mut(id).unwrap();
        n.parent = None;
        n.prev_sibling = None;
        n.next_sibling = None;

        if let Err(payload) = purged {
            self.purge_interaction_state_for_subtree(id, false);
            std::panic::resume_unwind(payload);
        }
        Ok(())
    }

    /// Clear any document-level interaction state
    /// (`focused`, `hovered`, `active`, `pointer_capture`, `selection`)
    /// whose referenced node lives inside the subtree rooted at `root`
    /// (inclusive). Called by `detach_from_parent` so detachment
    /// can never leave dangling interaction pointers.
    ///
    /// With `notify`, each cleared field that has a mutation type
    /// (`focused`, `hovered`, `active`, `selection`) goes through its
    /// public setter so the appropriate `InteractionChanged` /
    /// `SelectionChanged` record fires; without it (the cleanup after a
    /// panicking observer) the fields are cleared directly.
    /// `pointer_capture` always clears silently because it has no
    /// associated record type (it's a runtime-routing flag, not a
    /// cascade-affecting state).
    ///
    /// Membership is `is_ancestor(root, node)`: O(depth) per field, no
    /// subtree walk, correct before and after `root` is unlinked (the
    /// links inside the subtree stay).
    fn purge_interaction_state_for_subtree(&mut self, root: NodeId, notify: bool) {
        let inside =
            |dom: &Self, node: Option<NodeId>| node.is_some_and(|n| dom.is_ancestor(root, n));
        if inside(self, self.focused) {
            if notify {
                self.set_focused(None);
            } else {
                self.focused = None;
            }
        }
        if inside(self, self.hovered) {
            if notify {
                self.set_hovered(None);
            } else {
                self.hovered = None;
            }
        }
        if inside(self, self.active) {
            if notify {
                self.set_active(None);
            } else {
                self.active = None;
            }
        }
        if inside(self, self.pointer_capture) {
            self.pointer_capture = None;
        }
        let selected = self
            .selection
            .as_ref()
            .map(|sel| (sel.anchor.node, sel.focus.node));
        if let Some((anchor, focus)) = selected
            && (inside(self, Some(anchor)) || inside(self, Some(focus)))
        {
            if notify {
                self.set_selection(None);
            } else {
                self.selection = None;
                self.selection_serial = self.selection_serial.next();
            }
        }
    }

    /// Depth-first descendants including `root` (iterative). Used by
    /// `drop_subtree`.
    fn collect_descendants(&self, root: NodeId, out: &mut Vec<NodeId>) {
        self.walk_subtree(root, &mut |id, _| out.push(id));
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn sample() -> (Dom, NodeId, NodeId, NodeId) {
        let mut dom: Dom = Dom::new();
        let a = dom.create_element("a");
        let b = dom.create_element("b");
        let c = dom.create_element("c");
        (dom, a, b, c)
    }

    // ── append_child ─────────────────────────────────────────────────

    #[test]
    fn append_to_empty_parent() {
        let (mut dom, a, _, _) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        assert_eq!(dom.get_node(root).unwrap().first_child, Some(a));
        assert_eq!(dom.get_node(root).unwrap().last_child, Some(a));
        assert_eq!(dom.get_node(a).unwrap().parent, Some(root));
        assert!(dom.get_node(a).unwrap().prev_sibling.is_none());
        assert!(dom.get_node(a).unwrap().next_sibling.is_none());
    }

    #[test]
    fn append_multiple_maintains_sibling_chain() {
        let (mut dom, a, b, c) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        dom.append_child(root, b).unwrap();
        dom.append_child(root, c).unwrap();

        assert_eq!(dom.get_node(root).unwrap().first_child, Some(a));
        assert_eq!(dom.get_node(root).unwrap().last_child, Some(c));
        assert_eq!(dom.get_node(a).unwrap().next_sibling, Some(b));
        assert_eq!(dom.get_node(b).unwrap().prev_sibling, Some(a));
        assert_eq!(dom.get_node(b).unwrap().next_sibling, Some(c));
        assert_eq!(dom.get_node(c).unwrap().prev_sibling, Some(b));
    }

    #[test]
    fn append_moves_node_from_old_parent() {
        let (mut dom, a, b, _) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        dom.append_child(a, b).unwrap();
        dom.append_child(root, b).unwrap(); // re-parent b
        assert_eq!(dom.get_node(b).unwrap().parent, Some(root));
        assert!(dom.get_node(a).unwrap().first_child.is_none());
        assert!(dom.get_node(a).unwrap().last_child.is_none());
    }

    #[test]
    fn append_rejects_cycle() {
        let (mut dom, a, b, _) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        dom.append_child(a, b).unwrap();
        // Try to append a under b — cycle.
        assert!(matches!(
            dom.append_child(b, a).unwrap_err(),
            DomError::HierarchyRequest
        ));
    }

    /// `CORE-DROP-PANIC-LEAK-1`: the `ChildListChanged` record fires
    /// before the slots are freed (observers may inspect the removed
    /// subtree). A panicking observer must not turn that ordering into
    /// a leak — the subtree is freed on the way out, then the panic
    /// continues.
    #[test]
    fn drop_subtree_frees_even_when_an_observer_panics() {
        struct Bomb;
        impl crate::MutationObserver<()> for Bomb {
            fn observe(&mut self, _dom: &mut Dom, _record: &crate::Mutation) {
                panic!("observer bomb");
            }
        }
        let mut dom: Dom = Dom::new();
        let root = dom.root();
        let div = dom.create_element("div");
        let span = dom.create_element("span");
        dom.append_child(root, div).unwrap();
        dom.append_child(div, span).unwrap();
        dom.add_mutation_observer(Box::new(Bomb));

        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            dom.drop_subtree(div).unwrap();
        }));
        assert!(result.is_err(), "the bomb must actually fire");
        assert!(!dom.contains(div), "subtree root was freed");
        assert!(!dom.contains(span), "subtree descendant was freed");
        assert_eq!(dom.len(), 1, "only the root remains");
        assert!(dom.validate().is_empty());
    }

    /// A panicking observer on the *purge* records that `detach_from_parent`
    /// fires (`InteractionChanged` for a focused descendant, `SelectionChanged`
    /// for a selection anchored inside) must not leak either: those fire while
    /// the subtree is still connected, but the unlink still happens (the rest
    /// of the purge runs silently), so the subtree is freed on the way out.
    #[test]
    fn drop_subtree_frees_when_the_focus_purge_observer_panics() {
        struct Bomb;
        impl crate::MutationObserver<()> for Bomb {
            fn observe(&mut self, _dom: &mut Dom, record: &crate::Mutation) {
                if matches!(record, crate::Mutation::InteractionChanged { .. }) {
                    panic!("observer bomb");
                }
            }
        }
        let mut dom: Dom = Dom::new();
        let root = dom.root();
        let div = dom.create_element("div");
        let span = dom.create_element("span");
        dom.append_child(root, div).unwrap();
        dom.append_child(div, span).unwrap();
        dom.set_focused(Some(span));
        dom.add_mutation_observer(Box::new(Bomb));

        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            dom.drop_subtree(div).unwrap();
        }));
        assert!(result.is_err(), "the bomb must actually fire");
        assert!(
            !dom.contains(div) && !dom.contains(span),
            "subtree was freed"
        );
        assert_eq!(dom.len(), 1);
        assert_eq!(dom.focused(), None);
        assert!(dom.validate().is_empty());
    }

    #[test]
    fn drop_subtree_frees_when_the_selection_purge_observer_panics() {
        struct Bomb;
        impl crate::MutationObserver<()> for Bomb {
            fn observe(&mut self, _dom: &mut Dom, record: &crate::Mutation) {
                if matches!(record, crate::Mutation::SelectionChanged { .. }) {
                    panic!("observer bomb");
                }
            }
        }
        let mut dom: Dom = Dom::new();
        let root = dom.root();
        let div = dom.create_element("div");
        let text = dom.create_text_node("hello");
        dom.append_child(root, div).unwrap();
        dom.append_child(div, text).unwrap();
        let at = crate::Position {
            node: text,
            offset: 1,
        };
        dom.set_selection(Some(crate::Selection {
            anchor: at,
            focus: at,
        }));
        dom.add_mutation_observer(Box::new(Bomb));

        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            dom.drop_subtree(div).unwrap();
        }));
        assert!(result.is_err(), "the bomb must actually fire");
        assert!(
            !dom.contains(div) && !dom.contains(text),
            "subtree was freed"
        );
        assert_eq!(dom.len(), 1);
        assert!(dom.validate().is_empty());
    }

    /// `remove_child_dropping` / `clear_children_dropping` fire their
    /// `ChildListChanged` before the orphan reaches `drop_subtree`; the
    /// same guarantee holds there.
    #[test]
    fn dropping_wrappers_free_when_an_observer_panics() {
        struct Bomb;
        impl crate::MutationObserver<()> for Bomb {
            fn observe(&mut self, _dom: &mut Dom, record: &crate::Mutation) {
                if matches!(record, crate::Mutation::ChildListChanged { .. }) {
                    panic!("observer bomb");
                }
            }
        }
        let mut dom: Dom = Dom::new();
        let root = dom.root();
        let a = dom.create_element("a");
        let a_kid = dom.create_element("kid");
        let b = dom.create_element("b");
        let c = dom.create_element("c");
        dom.append_child(root, a).unwrap();
        dom.append_child(a, a_kid).unwrap();
        dom.append_child(root, b).unwrap();
        dom.append_child(root, c).unwrap();
        dom.add_mutation_observer(Box::new(Bomb));

        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            dom.remove_child_dropping(root, a).unwrap();
        }));
        assert!(result.is_err());
        assert!(
            !dom.contains(a) && !dom.contains(a_kid),
            "removed subtree was freed"
        );
        assert_eq!(dom.len(), 3, "root, b, c");

        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            dom.clear_children_dropping(root).unwrap();
        }));
        assert!(result.is_err());
        assert!(
            !dom.contains(b) && !dom.contains(c),
            "cleared children were freed"
        );
        assert_eq!(dom.len(), 1);
        assert!(dom.validate().is_empty());
    }

    /// The other side of the rule: a panic in the `PreDetach` window
    /// happens *before* the unlink, so the subtree is still attached and
    /// must not be freed out from under its parent.
    #[test]
    fn drop_subtree_keeps_an_attached_subtree_when_pre_detach_panics() {
        struct Bomb;
        impl crate::MutationObserver<()> for Bomb {
            fn observe(&mut self, _dom: &mut Dom, record: &crate::Mutation) {
                if matches!(record, crate::Mutation::PreDetach { .. }) {
                    panic!("observer bomb");
                }
            }
        }
        let mut dom: Dom = Dom::new();
        let root = dom.root();
        let div = dom.create_element("div");
        let span = dom.create_element("span");
        dom.append_child(root, div).unwrap();
        dom.append_child(div, span).unwrap();
        dom.set_focused(Some(span));
        dom.add_mutation_observer(Box::new(Bomb));

        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            dom.drop_subtree(div).unwrap();
        }));
        assert!(result.is_err());
        assert!(
            dom.contains(div) && dom.contains(span),
            "still attached, not freed"
        );
        assert_eq!(dom.node(root).first_child().map(|n| n.id()), Some(div));
        assert!(dom.validate().is_empty());
    }

    /// The root is the arena's anchor; dropping it would leave `Dom::root`
    /// pointing at a dead slot and break every later call.
    #[test]
    fn drop_subtree_rejects_the_root() {
        let mut dom: Dom = Dom::new();
        let root = dom.root();
        let child = dom.create_element("div");
        dom.append_child(root, child).unwrap();
        assert!(matches!(
            dom.drop_subtree(root).unwrap_err(),
            DomError::HierarchyRequest
        ));
        assert!(dom.contains(root));
        assert!(dom.contains(child), "nothing was freed");
        assert!(dom.validate().is_empty());
    }

    #[test]
    fn append_rejects_invalid_parent() {
        let mut dom: Dom = Dom::new();
        // A NodeId that was never allocated — guaranteed invalid.
        let ghost = NodeId::from_parts(999, std::num::NonZeroU32::MIN);
        let child = dom.create_element("child");
        assert!(matches!(
            dom.append_child(ghost, child).unwrap_err(),
            DomError::InvalidNode(_)
        ));
    }

    // ── insert_before ─────────────────────────────────────────────────

    #[test]
    fn insert_before_first_becomes_new_first() {
        let (mut dom, a, b, _) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        dom.insert_before(root, b, Some(a)).unwrap();
        assert_eq!(dom.get_node(root).unwrap().first_child, Some(b));
        assert_eq!(dom.get_node(root).unwrap().last_child, Some(a));
        assert_eq!(dom.get_node(b).unwrap().next_sibling, Some(a));
        assert_eq!(dom.get_node(a).unwrap().prev_sibling, Some(b));
    }

    #[test]
    fn insert_before_middle_updates_chain() {
        let (mut dom, a, b, c) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        dom.append_child(root, c).unwrap();
        dom.insert_before(root, b, Some(c)).unwrap();
        // Order should be a, b, c.
        let names: Vec<_> = iter_children(&dom, root)
            .map(|id| dom.get_node(id).unwrap().tag_name().unwrap().to_string())
            .collect();
        assert_eq!(names, vec!["a", "b", "c"]);
    }

    #[test]
    fn insert_before_null_appends() {
        let (mut dom, a, b, _) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        dom.insert_before(root, b, None).unwrap();
        assert_eq!(dom.get_node(root).unwrap().last_child, Some(b));
    }

    #[test]
    fn insert_before_rejects_non_child_reference() {
        let (mut dom, a, b, _) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        // b is not a child of root.
        assert!(matches!(
            dom.insert_before(root, a, Some(b)).unwrap_err(),
            DomError::NotFound
        ));
    }

    // ── remove_child ─────────────────────────────────────────────────

    #[test]
    fn remove_child_detaches_but_keeps_in_arena() {
        let (mut dom, a, _, _) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        dom.remove_child(root, a).unwrap();
        assert!(dom.get_node(root).unwrap().first_child.is_none());
        assert!(dom.get_node(a).unwrap().parent.is_none());
        assert!(dom.contains(a)); // still in arena as orphan
    }

    #[test]
    fn remove_middle_child_fixes_siblings() {
        let (mut dom, a, b, c) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        dom.append_child(root, b).unwrap();
        dom.append_child(root, c).unwrap();
        dom.remove_child(root, b).unwrap();
        assert_eq!(dom.get_node(a).unwrap().next_sibling, Some(c));
        assert_eq!(dom.get_node(c).unwrap().prev_sibling, Some(a));
    }

    #[test]
    fn remove_nonchild_errors() {
        let (mut dom, a, _, _) = sample();
        let root = dom.root();
        assert!(matches!(
            dom.remove_child(root, a).unwrap_err(),
            DomError::NotFound
        ));
    }

    // ── replace_child ────────────────────────────────────────────────

    #[test]
    fn replace_child_preserves_position() {
        let (mut dom, a, b, c) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        dom.append_child(root, b).unwrap();
        dom.append_child(root, c).unwrap();

        let d = dom.create_element("d");
        dom.replace_child(root, b, d).unwrap();
        let names: Vec<_> = iter_children(&dom, root)
            .map(|id| dom.get_node(id).unwrap().tag_name().unwrap().to_string())
            .collect();
        assert_eq!(names, vec!["a", "d", "c"]);
    }

    // ── Fragment unwrap ──────────────────────────────────────────────

    #[test]
    fn fragment_unwraps_on_append() {
        let mut dom: Dom = Dom::new();
        let root = dom.root();
        let frag = dom.create_document_fragment();
        let a = dom.create_element("a");
        let b = dom.create_element("b");
        dom.append_child(frag, a).unwrap();
        dom.append_child(frag, b).unwrap();

        dom.append_child(root, frag).unwrap();

        // a and b are now direct children of root; frag is empty.
        assert_eq!(dom.get_node(root).unwrap().first_child, Some(a));
        assert_eq!(dom.get_node(root).unwrap().last_child, Some(b));
        assert!(dom.get_node(frag).unwrap().first_child.is_none());
    }

    #[test]
    fn fragment_unwraps_on_insert_before() {
        let mut dom: Dom = Dom::new();
        let root = dom.root();
        let existing = dom.create_element("existing");
        dom.append_child(root, existing).unwrap();

        let frag = dom.create_document_fragment();
        let x = dom.create_element("x");
        let y = dom.create_element("y");
        dom.append_child(frag, x).unwrap();
        dom.append_child(frag, y).unwrap();

        dom.insert_before(root, frag, Some(existing)).unwrap();

        let names: Vec<_> = iter_children(&dom, root)
            .map(|id| dom.get_node(id).unwrap().tag_name().unwrap().to_string())
            .collect();
        assert_eq!(names, vec!["x", "y", "existing"]);
    }

    // ── insert_adjacent ──────────────────────────────────────────────

    #[test]
    fn insert_adjacent_before_begin() {
        let (mut dom, a, b, _) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        dom.insert_adjacent(a, AdjacentPosition::BeforeBegin, b)
            .unwrap();
        assert_eq!(dom.get_node(root).unwrap().first_child, Some(b));
        assert_eq!(dom.get_node(b).unwrap().next_sibling, Some(a));
    }

    #[test]
    fn insert_adjacent_after_end() {
        let (mut dom, a, b, _) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        dom.insert_adjacent(a, AdjacentPosition::AfterEnd, b)
            .unwrap();
        assert_eq!(dom.get_node(a).unwrap().next_sibling, Some(b));
        assert_eq!(dom.get_node(root).unwrap().last_child, Some(b));
    }

    #[test]
    fn insert_adjacent_after_begin_prepends() {
        let (mut dom, a, b, c) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        dom.append_child(root, b).unwrap();
        // c becomes new first child of root.
        dom.insert_adjacent(root, AdjacentPosition::AfterBegin, c)
            .unwrap();
        assert_eq!(dom.get_node(root).unwrap().first_child, Some(c));
    }

    // ── clear + drop ─────────────────────────────────────────────────

    #[test]
    fn clear_children_detaches_all() {
        let (mut dom, a, b, c) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        dom.append_child(root, b).unwrap();
        dom.append_child(root, c).unwrap();

        dom.clear_children(root).unwrap();
        assert!(dom.get_node(root).unwrap().first_child.is_none());
        // Children are orphans but still in arena.
        assert!(dom.contains(a));
        assert!(dom.contains(b));
        assert!(dom.contains(c));
        assert!(dom.get_node(a).unwrap().parent.is_none());
    }

    #[test]
    fn remove_child_dropping_frees_the_node() {
        let (mut dom, a, b, _c) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        dom.append_child(a, b).unwrap();

        dom.remove_child_dropping(root, a).unwrap();
        // Detached AND freed — the whole subtree is gone from the arena.
        assert!(!dom.contains(a));
        assert!(!dom.contains(b));
        assert!(dom.get_node(root).unwrap().first_child.is_none());
    }

    #[test]
    fn clear_children_dropping_frees_all() {
        let (mut dom, a, b, c) = sample();
        let root = dom.root();
        dom.append_child(root, a).unwrap();
        dom.append_child(root, b).unwrap();
        dom.append_child(root, c).unwrap();

        dom.clear_children_dropping(root).unwrap();
        assert!(dom.get_node(root).unwrap().first_child.is_none());
        // Unlike clear_children, every child is freed, not orphaned.
        assert!(!dom.contains(a));
        assert!(!dom.contains(b));
        assert!(!dom.contains(c));
    }

    #[test]
    fn drop_subtree_frees_everything() {
        let mut dom: Dom = Dom::new();
        let root = dom.root();
        let a = dom.create_element("a");
        let b = dom.create_element("b");
        let c = dom.create_element("c");
        dom.append_child(root, a).unwrap();
        dom.append_child(a, b).unwrap();
        dom.append_child(b, c).unwrap();

        dom.drop_subtree(a).unwrap();
        assert!(!dom.contains(a));
        assert!(!dom.contains(b));
        assert!(!dom.contains(c));
        assert!(dom.get_node(root).unwrap().first_child.is_none());
    }

    // ── helpers ──────────────────────────────────────────────────────

    fn iter_children(dom: &Dom, parent: NodeId) -> impl Iterator<Item = NodeId> + '_ {
        let mut cur = dom.get_node(parent).and_then(|n| n.first_child);
        std::iter::from_fn(move || {
            let c = cur?;
            cur = dom.get_node(c).and_then(|n| n.next_sibling);
            Some(c)
        })
    }
}