yrby 0.5.0 → 0.6.0

data/ext/yrby/src/prosemirror_html.rs

@@ -8,18 +8,38 @@
 //! both spellings in use: Tiptap's camelCase (`bulletList`, `bold`) and the
 //! prosemirror-schema-basic snake_case (`bullet_list`, `strong`).
 //!
-//! Output follows `ueberdosis/tiptap-php` (the maintained PHP renderer for
-//! ProseMirror JSON) and matches Tiptap's own `getHTML()` byte for byte on the
-//! captured fixtures — including mentions — with one deliberate exception: a
-//! table renders as the semantic `<table><tbody>…`, without the
-//! `<colgroup>`/`min-width` styling Tiptap's editor view injects (tiptap-php
-//! drops it too). The details family follows tiptap-php's renderHTML, since
-//! that Tiptap extension is Pro-only.
+//! This renders **core ProseMirror**: the prosemirror-schema-basic node set
+//! plus the prosemirror-tables family — paragraphs, headings, blockquotes,
+//! code blocks, bullet/ordered lists, images, hard breaks, horizontal rules,
+//! and tables (semantic `<table><tbody>…`, without the `<colgroup>`/
+//! `min-width` styling editor views inject). Tiptap's extension nodes — task
+//! lists, mentions, the details family — live in the Ruby layer as the
+//! `Y::Tiptap` renderer's rule set, built on the same extension API apps use
+//! (`Y::ProseMirror` is the core base class). Output follows
+//! `ueberdosis/tiptap-php`, and with `Y::Tiptap`'s rules it matches Tiptap's
+//! own `getHTML()` byte for byte on the captured fixtures — that guarantee
+//! is held at the Ruby layer; the native tests pin core output as goldens
+//! where a fixture contains Tiptap-only nodes.
 //!
-//! Marks nest in a fixed order (outermost first): link, bold, italic, strike,
-//! underline, highlight, then subscript/superscript. `code` excludes every
-//! other mark, so a code run is just `<code>`.
+//! Marks stay native on purpose: mark serialization is text-run machinery
+//! (nesting order, textStyle's CSS, code's exclusivity), which the rule
+//! system can't express. The built-in set covers schema-basic's marks and
+//! Tiptap's — nesting outermost-first: link, a textStyle span, bold, italic,
+//! strike, underline, highlight, then subscript/superscript. `code` excludes
+//! the other formatting marks, so a code run is `<code>` alone — though a
+//! link still wraps it (see `render_run`).
+//!
+//! Custom nodes and marks: apps register rules by node type and mark name
+//! (see `render_rules`). A node rule is consulted before the built-in arms, so
+//! it can extend the schema or override a built-in; a mark rule claims its
+//! mark from the built-in wraps and wraps outside everything, link included.
+//! Declarative rules render here; callback rules emit `Segment::Deferred` for
+//! the caller to fill in after the render.
 
+use crate::render_rules::{
+    any_attr_string, resolve_parts, xml_attrs_json, xml_ref_attr, Content, Emitter, MarkRule,
+    NodeRule, Rules, Segment, TypeMap,
+};
 use yrs::types::text::YChange;
 use yrs::types::Attrs;
 use yrs::{
@@ -27,40 +47,139 @@ use yrs::{
     XmlTextRef,
 };
 
-// The block tree is walked on a heap stack, so depth costs memory, not native
-// stack frames; this caps the work a pathological document can demand.
+// The block tree is walked on a heap stack, so depth can't overflow the
+// native call stack; this caps the work a pathological document can demand.
 const MAX_DEPTH: usize = 1024;
 
-/// A pending block on the traversal stack. `Open` renders a node (pushing its
-/// block children as more work); `Close` emits a container's end tag once its
-/// children are done. Container end tags are all fixed strings.
+/// A unit of block work on the traversal stack. `Open` renders a node (pushing its
+/// block children as more work); `Close` and `CloseOwned` emit a container's
+/// end tag once its children are done (built-in containers close with fixed
+/// strings; rule containers close with their computed tag). `EndDeferred` seals
+/// a callback node: it pops the emitter frame its children rendered into and
+/// emits the deferred segment.
 enum Work {
     Open(XmlElementRef, usize),
     Close(&'static str),
+    CloseOwned(String),
+    EndDeferred {
+        node_type: String,
+        attrs_json: String,
+        child_types: Vec<String>,
+    },
 }
 
-/// Render a ProseMirror/Tiptap-shaped XML root to HTML, or `None` when the root
-/// isn't ProseMirror-shaped. ProseMirror blocks are plain Y.XmlElement tags; a
-/// Lexical root (Y.XmlText children carrying a `__type`) is a different schema
-/// and returns `None` instead of a garbled render.
-pub fn render<T: ReadTxn>(txn: &T, fragment: &XmlFragmentRef) -> Option<String> {
+/// Render a ProseMirror/Tiptap-shaped XML root to segments, or `None` when the
+/// root isn't ProseMirror-shaped. ProseMirror blocks are plain Y.XmlElement
+/// tags; a Lexical root (Y.XmlText children carrying a `__type`) is a
+/// different schema and returns `None` instead of a garbled render.
+pub fn render_segments<T: ReadTxn>(
+    txn: &T,
+    fragment: &XmlFragmentRef,
+    rules: &Rules,
+) -> Option<Vec<Segment>> {
     if !is_prosemirror_shaped(txn, fragment) {
         return None;
     }
-    let mut out = String::new();
+    let mut em = Emitter::new();
     for node in fragment.children(txn) {
         match node {
-            XmlOut::Element(e) => render_block_tree(txn, &e, &mut out),
+            XmlOut::Element(e) => render_block_tree(txn, &e, &mut em, rules),
             // y-prosemirror never writes a bare text run at the root, but a
             // crafted doc can; render it rather than drop it.
-            XmlOut::Text(t) => render_text_runs(txn, &t, &mut out),
+            XmlOut::Text(t) => render_text_runs(txn, &t, &mut em, rules),
             // Fragments can't nest as children in yrs, so this arm shouldn't
             // be reachable; it exists because the match must be exhaustive,
             // and escaping the text is the safe degradation.
-            XmlOut::Fragment(f) => out.push_str(&escape_text(&f.get_string(txn))),
+            XmlOut::Fragment(f) => em.push_str(&escape_text(&f.get_string(txn))),
+        }
+    }
+    Some(em.into_segments())
+}
+
+/// Rule-free rendering to a plain string — the fixture-parity surface most
+/// tests pin. With no callback rules, segments always flatten.
+#[cfg(test)]
+pub fn render<T: ReadTxn>(txn: &T, fragment: &XmlFragmentRef) -> Option<String> {
+    render_segments(txn, fragment, &Rules::empty()).map(|segs| {
+        crate::render_rules::flatten(segs)
+            .into_html()
+            .expect("no callback rules registered")
+    })
+}
+
+/// The node types the built-in arms cover (both Tiptap and schema-basic
+/// spellings). Everything else needs a rule.
+pub fn is_builtin(ty: &str) -> bool {
+    matches!(
+        ty,
+        "paragraph"
+            | "heading"
+            | "codeBlock"
+            | "code_block"
+            | "blockquote"
+            | "bulletList"
+            | "bullet_list"
+            | "orderedList"
+            | "ordered_list"
+            | "listItem"
+            | "list_item"
+            | "table"
+            | "tableRow"
+            | "table_row"
+            | "tableHeader"
+            | "table_header"
+            | "tableCell"
+            | "table_cell"
+            | "horizontalRule"
+            | "horizontal_rule"
+            | "image"
+            | "hardBreak"
+            | "hard_break"
+    )
+}
+
+/// Walk the document and record what each node type actually looks like —
+/// the discovery aid behind `Y::ProseMirror#node_types`. It records facts:
+/// counts, attribute names, child element types, and whether text runs were
+/// seen. The inline-vs-blocks distinction itself is editor-schema knowledge
+/// the storage never serializes, so the rule author reads it off the child
+/// types and text flags.
+pub fn collect_node_types<T: ReadTxn>(txn: &T, fragment: &XmlFragmentRef) -> Option<TypeMap> {
+    if !is_prosemirror_shaped(txn, fragment) {
+        return None;
+    }
+    let mut map = TypeMap::new();
+    for node in fragment.children(txn) {
+        if let XmlOut::Element(e) = node {
+            observe(txn, &e, &mut map, 0);
+        }
+    }
+    Some(map)
+}
+
+fn observe<T: ReadTxn>(txn: &T, e: &XmlElementRef, map: &mut TypeMap, depth: usize) {
+    let ty = e.tag().to_string();
+    let info = map.entry(ty.clone()).or_default();
+    info.count += 1;
+    for (key, _) in e.attributes(txn) {
+        info.attrs.insert(key.to_string());
+    }
+    if depth >= MAX_DEPTH {
+        return;
+    }
+    for child in e.children(txn) {
+        match child {
+            XmlOut::Text(_) => map.get_mut(&ty).expect("just inserted").text = true,
+            XmlOut::Element(el) => {
+                map.get_mut(&ty)
+                    .expect("just inserted")
+                    .children
+                    .insert(el.tag().to_string());
+                observe(txn, &el, map, depth + 1);
+            }
+            XmlOut::Fragment(_) => {}
         }
     }
-    Some(out)
 }
 
 /// A root is ProseMirror-shaped when it's empty or its first child is a block
@@ -75,122 +194,108 @@ fn is_prosemirror_shaped<T: ReadTxn>(txn: &T, fragment: &XmlFragmentRef) -> bool
 }
 
 /// Walk one top-level block and everything under it on a heap stack.
-fn render_block_tree<T: ReadTxn>(txn: &T, root: &XmlElementRef, out: &mut String) {
+fn render_block_tree<T: ReadTxn>(txn: &T, root: &XmlElementRef, em: &mut Emitter, rules: &Rules) {
     let mut stack: Vec<Work> = vec![Work::Open(root.clone(), 0)];
     while let Some(work) = stack.pop() {
         match work {
-            Work::Close(tag) => out.push_str(tag),
-            Work::Open(node, depth) => open_block(txn, &node, depth, out, &mut stack),
+            Work::Close(tag) => em.push_str(tag),
+            Work::CloseOwned(tag) => em.push_str(&tag),
+            Work::EndDeferred {
+                node_type,
+                attrs_json,
+                child_types,
+            } => {
+                let content = em.end_frame();
+                em.emit_deferred(node_type, attrs_json, child_types, content);
+            }
+            Work::Open(node, depth) => open_block(txn, &node, depth, em, &mut stack, rules),
         }
     }
 }
 
-/// Render one block. Text blocks (paragraph, heading, code) render in full on
-/// the spot; container blocks emit their opening tag and defer their children
-/// (and matching `Close`) to the stack.
+/// Render one block. A registered rule wins over the built-in arms (so apps
+/// can extend the schema or override a built-in). Text blocks (paragraph,
+/// heading, code) render in full on the spot; container blocks emit their
+/// opening tag and defer their children (and matching `Close`) to the stack.
 fn open_block<T: ReadTxn>(
     txn: &T,
     e: &XmlElementRef,
     depth: usize,
-    out: &mut String,
+    em: &mut Emitter,
     stack: &mut Vec<Work>,
+    rules: &Rules,
 ) {
+    if let Some(rule) = rules.nodes.get(e.tag().as_ref()) {
+        open_rule_block(txn, e, rule, depth, em, stack, rules);
+        return;
+    }
     match e.tag().as_ref() {
         "paragraph" => {
-            out.push_str("<p>");
-            out.push_str(&render_inline(txn, e, 0));
-            out.push_str("</p>");
+            em.push_str("<p>");
+            render_inline(txn, e, 0, em, rules);
+            em.push_str("</p>");
         }
         "heading" => {
             let level = num_attr(txn, e, "level").unwrap_or(1).clamp(1, 6);
             let tag = ['1', '2', '3', '4', '5', '6'][(level - 1) as usize];
-            out.push_str("<h");
-            out.push(tag);
-            out.push('>');
-            out.push_str(&render_inline(txn, e, 0));
-            out.push_str("</h");
-            out.push(tag);
-            out.push('>');
+            em.push_str("<h");
+            em.push(tag);
+            em.push('>');
+            render_inline(txn, e, 0, em, rules);
+            em.push_str("</h");
+            em.push(tag);
+            em.push('>');
         }
         "codeBlock" | "code_block" => {
-            out.push_str("<pre><code");
+            em.push_str("<pre><code");
             if let Some(lang) = str_attr(txn, e, "language").filter(|l| !l.is_empty()) {
-                out.push_str(" class=\"language-");
-                out.push_str(&escape_attr(&lang));
-                out.push('"');
-            }
-            out.push('>');
-            out.push_str(&escape_text(&code_text(txn, e)));
-            out.push_str("</code></pre>");
-        }
-        "blockquote" => open_container(txn, e, depth, "<blockquote>", "</blockquote>", out, stack),
-        "bulletList" | "bullet_list" => open_container(txn, e, depth, "<ul>", "</ul>", out, stack),
-        "orderedList" | "ordered_list" => {
-            match num_attr(txn, e, "start") {
-                Some(start) if start != 1 => {
-                    out.push_str("<ol start=\"");
-                    out.push_str(&start.to_string());
-                    out.push_str("\">");
-                }
-                _ => out.push_str("<ol>"),
+                em.push_str(" class=\"language-");
+                em.push_str(&escape_attr(&lang));
+                em.push('"');
             }
-            push_block_children(txn, e, depth, "</ol>", out, stack);
+            em.push('>');
+            em.push_str(&escape_text(&code_text(txn, e)));
+            em.push_str("</code></pre>");
         }
-        "listItem" | "list_item" => open_container(txn, e, depth, "<li>", "</li>", out, stack),
-        "taskList" | "task_list" => open_container(
+        "blockquote" => open_container(
             txn,
             e,
             depth,
-            "<ul data-type=\"taskList\">",
-            "</ul>",
-            out,
+            "<blockquote>",
+            "</blockquote>",
+            em,
             stack,
+            rules,
         ),
-        "taskItem" | "task_item" => {
-            let checked = bool_attr(txn, e, "checked");
-            out.push_str("<li data-checked=\"");
-            out.push_str(if checked { "true" } else { "false" });
-            out.push_str("\" data-type=\"taskItem\"><label><input type=\"checkbox\"");
-            if checked {
-                out.push_str(" checked=\"checked\"");
+        "bulletList" | "bullet_list" => {
+            open_container(txn, e, depth, "<ul>", "</ul>", em, stack, rules)
+        }
+        "orderedList" | "ordered_list" => {
+            match num_attr(txn, e, "start") {
+                Some(start) if start != 1 => {
+                    em.push_str("<ol start=\"");
+                    em.push_str(&start.to_string());
+                    em.push_str("\">");
+                }
+                _ => em.push_str("<ol>"),
             }
-            out.push_str("><span></span></label><div>");
-            push_block_children(txn, e, depth, "</div></li>", out, stack);
+            push_block_children(txn, e, depth, "</ol>", em, stack, rules);
+        }
+        "listItem" | "list_item" => {
+            open_container(txn, e, depth, "<li>", "</li>", em, stack, rules)
         }
         "table" => {
-            out.push_str("<table><tbody>");
-            push_block_children(txn, e, depth, "</tbody></table>", out, stack);
-        }
-        "tableRow" | "table_row" => open_container(txn, e, depth, "<tr>", "</tr>", out, stack),
-        "tableHeader" | "table_header" => open_cell(txn, e, depth, "th", "</th>", out, stack),
-        "tableCell" | "table_cell" => open_cell(txn, e, depth, "td", "</td>", out, stack),
-        // The details family follows tiptap-php (the extension is Tiptap Pro,
-        // so there's no free getHTML() to capture against).
-        "details" => {
-            let open = if bool_attr(txn, e, "open") {
-                "<details open=\"open\">"
-            } else {
-                "<details>"
-            };
-            open_container(txn, e, depth, open, "</details>", out, stack);
+            em.push_str("<table><tbody>");
+            push_block_children(txn, e, depth, "</tbody></table>", em, stack, rules);
         }
-        "detailsSummary" | "details_summary" => {
-            out.push_str("<summary>");
-            out.push_str(&render_inline(txn, e, 0));
-            out.push_str("</summary>");
+        "tableRow" | "table_row" => {
+            open_container(txn, e, depth, "<tr>", "</tr>", em, stack, rules)
         }
-        "detailsContent" | "details_content" => open_container(
-            txn,
-            e,
-            depth,
-            "<div data-type=\"detailsContent\">",
-            "</div>",
-            out,
-            stack,
-        ),
-        "horizontalRule" | "horizontal_rule" => out.push_str("<hr>"),
-        "image" => render_image(txn, e, out),
-        "hardBreak" | "hard_break" => out.push_str("<br>"),
+        "tableHeader" | "table_header" => open_cell(txn, e, depth, "th", "</th>", em, stack, rules),
+        "tableCell" | "table_cell" => open_cell(txn, e, depth, "td", "</td>", em, stack, rules),
+        "horizontalRule" | "horizontal_rule" => em.push_str("<hr>"),
+        "image" => render_image(txn, e, em),
+        "hardBreak" | "hard_break" => em.push_str("<br>"),
         // Unknown block: keep its content rather than dropping it. If it holds
         // child blocks, render them with no wrapper; otherwise treat it as a
         // text block.
@@ -198,144 +303,309 @@ fn open_block<T: ReadTxn>(
             if has_element_child(txn, e) {
                 // Renders its direct text runs, then the children, with no
                 // invented wrapper tags.
-                push_block_children(txn, e, depth, "", out, stack);
+                push_block_children(txn, e, depth, "", em, stack, rules);
             } else {
-                let inline = render_inline(txn, e, 0);
+                em.begin_frame();
+                render_inline(txn, e, 0, em, rules);
+                let inline = em.end_frame();
                 if !inline.is_empty() {
-                    out.push_str("<p>");
-                    out.push_str(&inline);
-                    out.push_str("</p>");
+                    em.push_str("<p>");
+                    em.append(inline);
+                    em.push_str("</p>");
+                }
+            }
+        }
+    }
+}
+
+/// Render a block through a registered rule. Declarative rules emit the tag,
+/// resolved attributes, and template text here; callback rules capture their
+/// children into a frame and defer the markup to the caller.
+#[allow(clippy::too_many_arguments)]
+fn open_rule_block<T: ReadTxn>(
+    txn: &T,
+    e: &XmlElementRef,
+    rule: &NodeRule,
+    depth: usize,
+    em: &mut Emitter,
+    stack: &mut Vec<Work>,
+    rules: &Rules,
+) {
+    let ty = e.tag().to_string();
+    let (tag, void, attrs, text, content) = match rule {
+        NodeRule::Callback { content } => {
+            em.begin_frame();
+            // Children render into the frame; EndDeferred seals it. Blocks go
+            // via the stack (pushed above the marker, so they complete
+            // first); inline content renders now.
+            stack.push(Work::EndDeferred {
+                node_type: ty,
+                attrs_json: xml_attrs_json(txn, e),
+                child_types: element_child_types(txn, e),
+            });
+            match content {
+                Content::Inline => render_inline(txn, e, 0, em, rules),
+                Content::Blocks => {
+                    render_stray_text(txn, e, em, rules);
+                    if depth < MAX_DEPTH {
+                        for child in element_children(txn, e).into_iter().rev() {
+                            stack.push(Work::Open(child, depth + 1));
+                        }
+                    }
+                }
+                Content::None => {}
+            }
+            return;
+        }
+        NodeRule::Declarative {
+            tag,
+            void,
+            attrs,
+            text,
+            content,
+        } => (tag, *void, attrs, text, *content),
+    };
+
+    em.push('<');
+    em.push_str(tag);
+    for (name, parts) in attrs {
+        if let Some(value) = resolve_parts(parts, |r| xml_ref_attr(txn, e, r)) {
+            em.push(' ');
+            em.push_str(name);
+            em.push_str("=\"");
+            em.push_str(&escape_attr(&value));
+            em.push('\"');
+        }
+    }
+    em.push('>');
+    if void {
+        return;
+    }
+    if let Some(text) = text {
+        if let Some(value) = resolve_parts(text, |r| xml_ref_attr(txn, e, r)) {
+            em.push_str(&escape_text(&value));
+        }
+    }
+    match content {
+        Content::Inline => {
+            render_inline(txn, e, 0, em, rules);
+            em.push_str("</");
+            em.push_str(tag);
+            em.push('>');
+        }
+        Content::Blocks => {
+            render_stray_text(txn, e, em, rules);
+            stack.push(Work::CloseOwned(format!("</{tag}>")));
+            if depth < MAX_DEPTH {
+                for child in element_children(txn, e).into_iter().rev() {
+                    stack.push(Work::Open(child, depth + 1));
                 }
             }
         }
+        Content::None => {
+            em.push_str("</");
+            em.push_str(tag);
+            em.push('>');
+        }
     }
 }
 
+#[allow(clippy::too_many_arguments)]
 fn open_container<T: ReadTxn>(
     txn: &T,
     e: &XmlElementRef,
     depth: usize,
     open: &str,
     close: &'static str,
-    out: &mut String,
+    em: &mut Emitter,
     stack: &mut Vec<Work>,
+    rules: &Rules,
 ) {
-    out.push_str(open);
-    push_block_children(txn, e, depth, close, out, stack);
+    em.push_str(open);
+    push_block_children(txn, e, depth, close, em, stack, rules);
 }
 
 /// A table cell: `<th>`/`<td>` carrying colspan/rowspan (default 1, always
 /// emitted, matching Tiptap).
+#[allow(clippy::too_many_arguments)]
 fn open_cell<T: ReadTxn>(
     txn: &T,
     e: &XmlElementRef,
     depth: usize,
     tag: &str,
     close: &'static str,
-    out: &mut String,
+    em: &mut Emitter,
     stack: &mut Vec<Work>,
+    rules: &Rules,
 ) {
-    out.push('<');
-    out.push_str(tag);
-    out.push_str(" colspan=\"");
-    out.push_str(&num_attr(txn, e, "colspan").unwrap_or(1).to_string());
-    out.push_str("\" rowspan=\"");
-    out.push_str(&num_attr(txn, e, "rowspan").unwrap_or(1).to_string());
-    out.push_str("\">");
-    push_block_children(txn, e, depth, close, out, stack);
+    em.push('<');
+    em.push_str(tag);
+    em.push_str(" colspan=\"");
+    em.push_str(&num_attr(txn, e, "colspan").unwrap_or(1).to_string());
+    em.push_str("\" rowspan=\"");
+    em.push_str(&num_attr(txn, e, "rowspan").unwrap_or(1).to_string());
+    em.push_str("\">");
+    push_block_children(txn, e, depth, close, em, stack, rules);
 }
 
 /// Defer a node's child *elements* onto the stack, closing tag below them, so
 /// they render in order and the tag closes after. Any direct text runs render
-/// to `out` first: schema-valid documents never put bare text in a container,
-/// but a crafted one can, and dropping it would lose content. Past `MAX_DEPTH`
-/// the children are dropped but the tag still closes, keeping the output well
+/// first: schema-valid documents never put bare text in a container, but a
+/// crafted one can, and dropping it would lose content. Past `MAX_DEPTH` the
+/// children are dropped but the tag still closes, keeping the output well
 /// formed.
+#[allow(clippy::too_many_arguments)]
 fn push_block_children<T: ReadTxn>(
     txn: &T,
     e: &XmlElementRef,
     depth: usize,
     close: &'static str,
-    out: &mut String,
+    em: &mut Emitter,
     stack: &mut Vec<Work>,
+    rules: &Rules,
 ) {
-    for node in e.children(txn) {
-        if let XmlOut::Text(t) = node {
-            render_text_runs(txn, &t, out);
-        }
-    }
+    render_stray_text(txn, e, em, rules);
     stack.push(Work::Close(close));
     if depth >= MAX_DEPTH {
         return;
     }
-    let children: Vec<_> = e
-        .children(txn)
+    for child in element_children(txn, e).into_iter().rev() {
+        stack.push(Work::Open(child, depth + 1));
+    }
+}
+
+/// Direct text runs jammed into a container (schema-valid documents have
+/// none); rendered rather than dropped.
+fn render_stray_text<T: ReadTxn>(txn: &T, e: &XmlElementRef, em: &mut Emitter, rules: &Rules) {
+    for node in e.children(txn) {
+        if let XmlOut::Text(t) = node {
+            render_text_runs(txn, &t, em, rules);
+        }
+    }
+}
+
+fn element_children<T: ReadTxn>(txn: &T, e: &XmlElementRef) -> Vec<XmlElementRef> {
+    e.children(txn)
         .filter_map(|c| match c {
             XmlOut::Element(el) => Some(el),
             _ => None,
         })
-        .collect();
-    for child in children.into_iter().rev() {
-        stack.push(Work::Open(child, depth + 1));
-    }
+        .collect()
+}
+
+/// The node type (tag) of every element child, in document order — handed to
+/// callback rules as `node.child_types` for the structural facts `attrs` and
+/// the rendered content can't answer.
+fn element_child_types<T: ReadTxn>(txn: &T, e: &XmlElementRef) -> Vec<String> {
+    element_children(txn, e)
+        .iter()
+        .map(|el| el.tag().to_string())
+        .collect()
 }
 
 /// Render a text block's inline content: text runs (with their marks) and
-/// inline element nodes (hard breaks, mentions, inline images). An unknown
-/// inline node keeps its text instead of vanishing; `depth` caps that
-/// recursion on a crafted nest of unknowns.
-fn render_inline<T: ReadTxn>(txn: &T, e: &XmlElementRef, depth: usize) -> String {
-    let mut out = String::new();
+/// inline element nodes (hard breaks, inline images). A registered
+/// rule wins over the built-in inline nodes here too. An unknown inline node
+/// keeps its text instead of vanishing; `depth` caps that recursion on a
+/// crafted nest of unknowns.
+fn render_inline<T: ReadTxn>(
+    txn: &T,
+    e: &XmlElementRef,
+    depth: usize,
+    em: &mut Emitter,
+    rules: &Rules,
+) {
     for node in e.children(txn) {
         match node {
-            XmlOut::Text(t) => render_text_runs(txn, &t, &mut out),
-            XmlOut::Element(child) => match child.tag().as_ref() {
-                "hardBreak" | "hard_break" => out.push_str("<br>"),
-                "image" => render_image(txn, &child, &mut out),
-                "mention" => render_mention(txn, &child, &mut out),
-                _ => {
-                    if depth < MAX_DEPTH {
-                        out.push_str(&render_inline(txn, &child, depth + 1));
+            XmlOut::Text(t) => render_text_runs(txn, &t, em, rules),
+            XmlOut::Element(child) => {
+                if let Some(rule) = rules.nodes.get(child.tag().as_ref()) {
+                    render_rule_inline(txn, &child, rule, depth, em, rules);
+                    continue;
+                }
+                match child.tag().as_ref() {
+                    "hardBreak" | "hard_break" => em.push_str("<br>"),
+                    "image" => render_image(txn, &child, em),
+                    _ => {
+                        if depth < MAX_DEPTH {
+                            render_inline(txn, &child, depth + 1, em, rules);
+                        }
                     }
                 }
-            },
+            }
             XmlOut::Fragment(_) => {}
         }
     }
-    out
 }
 
-/// A mention, as Tiptap's Mention extension serializes it (no app-configured
-/// HTMLAttributes): `data-type`, `data-id`, `data-label` when present, the
-/// suggestion char, and `@label` (falling back to `@id`) as the text.
-fn render_mention<T: ReadTxn>(txn: &T, e: &XmlElementRef, out: &mut String) {
-    let id = str_attr(txn, e, "id");
-    let label = str_attr(txn, e, "label");
-    let char = str_attr(txn, e, "mentionSuggestionChar").unwrap_or_else(|| "@".to_string());
-    out.push_str("<span data-type=\"mention\"");
-    if let Some(id) = &id {
-        out.push_str(" data-id=\"");
-        out.push_str(&escape_attr(id));
-        out.push('"');
-    }
-    if let Some(label) = &label {
-        out.push_str(" data-label=\"");
-        out.push_str(&escape_attr(label));
-        out.push('"');
-    }
-    out.push_str(" data-mention-suggestion-char=\"");
-    out.push_str(&escape_attr(&char));
-    out.push_str("\">");
-    out.push_str(&escape_text(&char));
-    out.push_str(&escape_text(&label.or(id).unwrap_or_default()));
-    out.push_str("</span>");
+/// A rule node in inline position (inside a text block). Unlike Lexical's
+/// childless decorators, a ProseMirror inline node can hold real content, so
+/// the content slot renders — as inline content, since there are no blocks
+/// inside a text block (a blocks content slot behaves like inline here).
+fn render_rule_inline<T: ReadTxn>(
+    txn: &T,
+    e: &XmlElementRef,
+    rule: &NodeRule,
+    depth: usize,
+    em: &mut Emitter,
+    rules: &Rules,
+) {
+    let (tag, void, attrs, text, content) = match rule {
+        NodeRule::Callback { content } => {
+            em.begin_frame();
+            if *content != Content::None && depth < MAX_DEPTH {
+                render_inline(txn, e, depth + 1, em, rules);
+            }
+            let captured = em.end_frame();
+            em.emit_deferred(
+                e.tag().to_string(),
+                xml_attrs_json(txn, e),
+                element_child_types(txn, e),
+                captured,
+            );
+            return;
+        }
+        NodeRule::Declarative {
+            tag,
+            void,
+            attrs,
+            text,
+            content,
+        } => (tag, *void, attrs, text, *content),
+    };
+    em.push('<');
+    em.push_str(tag);
+    for (name, parts) in attrs {
+        if let Some(value) = resolve_parts(parts, |r| xml_ref_attr(txn, e, r)) {
+            em.push(' ');
+            em.push_str(name);
+            em.push_str("=\"");
+            em.push_str(&escape_attr(&value));
+            em.push('\"');
+        }
+    }
+    em.push('>');
+    if void {
+        return;
+    }
+    if let Some(text) = text {
+        if let Some(value) = resolve_parts(text, |r| xml_ref_attr(txn, e, r)) {
+            em.push_str(&escape_text(&value));
+        }
+    }
+    if content != Content::None && depth < MAX_DEPTH {
+        render_inline(txn, e, depth + 1, em, rules);
+    }
+    em.push_str("</");
+    em.push_str(tag);
+    em.push('>');
 }
 
 /// Emit each formatted run of a Y.XmlText.
-fn render_text_runs<T: ReadTxn>(txn: &T, t: &XmlTextRef, out: &mut String) {
+fn render_text_runs<T: ReadTxn>(txn: &T, t: &XmlTextRef, em: &mut Emitter, rules: &Rules) {
     for d in t.diff(txn, YChange::identity) {
         if let Out::Any(Any::String(s)) = &d.insert {
-            out.push_str(&render_run(s, d.attributes.as_deref()));
+            em.push_str(&render_run(s, d.attributes.as_deref(), rules));
         }
     }
 }
@@ -346,47 +616,115 @@ fn render_text_runs<T: ReadTxn>(txn: &T, t: &XmlTextRef, out: &mut String) {
 /// formatting marks (Tiptap's Code mark excludes them all), but a link still
 /// wraps it — Tiptap can't produce code+link, prosemirror-schema-basic can,
 /// and dropping the link would lose the href.
-fn render_run(text: &str, marks: Option<&Attrs>) -> String {
+///
+/// A registered mark rule claims its stored name from the built-in wraps
+/// (overriding it) and wraps outside everything; multiple custom marks nest
+/// alphabetically by name, so output is deterministic regardless of
+/// registration order. Overriding replaces only the markup: a claimed
+/// `code` still excludes the other formatting marks, and a claimed
+/// formatting mark stays excluded from a code run.
+fn render_run(text: &str, marks: Option<&Attrs>, rules: &Rules) -> String {
     let mut html = escape_text(text);
     let Some(marks) = marks else {
         return html;
     };
-    if has(marks, &["code"]) {
+    if has(marks, &["code"], rules) {
         html = wrap(html, "code");
-    } else {
-        if has(marks, &["subscript", "sub"]) {
+    } else if !marks.contains_key("code") {
+        // (A claimed `code` lands here too — on the run, but skipped by the
+        // else-if: the rule replaces the wrap, via wrap_custom_marks below,
+        // and code's exclusivity over the other formatting marks holds.)
+        if has(marks, &["subscript", "sub"], rules) {
             html = wrap(html, "sub");
-        } else if has(marks, &["superscript", "sup"]) {
+        } else if has(marks, &["superscript", "sup"], rules) {
             html = wrap(html, "sup");
         }
-        if has(marks, &["highlight"]) {
+        if has(marks, &["highlight"], rules) {
             html = wrap(html, "mark");
         }
-        if has(marks, &["underline", "u"]) {
+        if has(marks, &["underline", "u"], rules) {
             html = wrap(html, "u");
         }
-        if has(marks, &["strike", "s"]) {
+        if has(marks, &["strike", "s"], rules) {
             html = wrap(html, "s");
         }
-        if has(marks, &["italic", "em"]) {
+        if has(marks, &["italic", "em"], rules) {
             html = wrap(html, "em");
         }
-        if has(marks, &["bold", "strong"]) {
+        if has(marks, &["bold", "strong"], rules) {
             html = wrap(html, "strong");
         }
-        if let Some(Any::Map(style)) = marks.get("textStyle") {
-            let css = text_style_css(style);
-            if !css.is_empty() {
-                html = format!("<span style=\"{}\">{html}</span>", escape_attr(&css));
+        if !rules.marks.contains_key("textStyle") {
+            if let Some(Any::Map(style)) = marks.get("textStyle") {
+                let css = text_style_css(style);
+                if !css.is_empty() {
+                    html = format!("<span style=\"{}\">{html}</span>", escape_attr(&css));
+                }
             }
         }
     }
-    if let Some(Any::Map(link)) = marks.get("link") {
-        html = wrap_link(html, link);
+    if !rules.marks.contains_key("link") {
+        if let Some(Any::Map(link)) = marks.get("link") {
+            html = wrap_link(html, link);
+        }
+    }
+    if !rules.marks.is_empty() {
+        html = wrap_custom_marks(html, marks, rules);
     }
     html
 }
 
+/// Apply the run's registered custom marks, outermost of everything. A code
+/// run keeps its exclusivity under overrides too: only the `code` and `link`
+/// claims themselves may wrap it, matching what the built-in wraps allow —
+/// otherwise overriding a formatting mark would change which marks render on
+/// a code run, not just their markup.
+fn wrap_custom_marks(html: String, marks: &Attrs, rules: &Rules) -> String {
+    let code = marks.contains_key("code");
+    let mut names: Vec<&str> = rules
+        .marks
+        .keys()
+        .map(String::as_str)
+        .filter(|name| marks.contains_key(*name))
+        .filter(|name| !code || matches!(*name, "code" | "link"))
+        .collect();
+    names.sort_unstable();
+    let mut html = html;
+    for name in names {
+        html = wrap_custom_mark(html, &rules.marks[name], marks.get(name));
+    }
+    html
+}
+
+fn wrap_custom_mark(inner: String, rule: &MarkRule, value: Option<&Any>) -> String {
+    let mut out = String::from("<");
+    out.push_str(&rule.tag);
+    for (attr, parts) in &rule.attrs {
+        if let Some(v) = resolve_parts(parts, |r| mark_ref_attr(value, r)) {
+            out.push(' ');
+            out.push_str(attr);
+            out.push_str("=\"");
+            out.push_str(&escape_attr(&v));
+            out.push('"');
+        }
+    }
+    out.push('>');
+    out.push_str(&inner);
+    out.push_str("</");
+    out.push_str(&rule.tag);
+    out.push('>');
+    out
+}
+
+/// An attribute reference on a custom mark: y-prosemirror stores mark attrs
+/// as a map under the mark's name (bool `true` when the mark has none).
+fn mark_ref_attr(value: Option<&Any>, name: &str) -> Option<String> {
+    match value {
+        Some(Any::Map(map)) => any_attr_string(map.get(name)?),
+        _ => None,
+    }
+}
+
 /// The `style` string for a textStyle mark (Tiptap's Color/FontFamily/etc.
 /// extensions all store their value as a textStyle attribute). Attributes are
 /// camelCase CSS property names; unset ones sit in the map as explicit nulls.
@@ -466,26 +804,29 @@ fn wrap_link(inner: String, link: &std::collections::HashMap<String, Any>) -> St
 }
 
 /// `<img>` with attribute order src, alt, title, skipping absent/null ones.
-fn render_image<T: ReadTxn>(txn: &T, e: &XmlElementRef, out: &mut String) {
-    out.push_str("<img");
+fn render_image<T: ReadTxn>(txn: &T, e: &XmlElementRef, em: &mut Emitter) {
+    em.push_str("<img");
     for (attr, html) in [("src", "src"), ("alt", "alt"), ("title", "title")] {
         if let Some(v) = str_attr(txn, e, attr) {
-            out.push(' ');
-            out.push_str(html);
-            out.push_str("=\"");
-            out.push_str(&escape_attr(&v));
-            out.push('"');
+            em.push(' ');
+            em.push_str(html);
+            em.push_str("=\"");
+            em.push_str(&escape_attr(&v));
+            em.push('"');
         }
     }
-    out.push('>');
+    em.push('>');
 }
 
 fn wrap(inner: String, tag: &str) -> String {
     format!("<{tag}>{inner}</{tag}>")
 }
 
-fn has(marks: &Attrs, keys: &[&str]) -> bool {
-    keys.iter().any(|k| marks.contains_key(*k))
+/// A mark is present and not claimed by a registered rule for that stored
+/// name (a rule overrides the built-in wrap).
+fn has(marks: &Attrs, keys: &[&str], rules: &Rules) -> bool {
+    keys.iter()
+        .any(|k| marks.contains_key(*k) && !rules.marks.contains_key(*k))
 }
 
 fn has_element_child<T: ReadTxn>(txn: &T, e: &XmlElementRef) -> bool {
@@ -522,10 +863,6 @@ fn num_attr<T: ReadTxn>(txn: &T, e: &XmlElementRef, name: &str) -> Option<i64> {
     }
 }
 
-fn bool_attr<T: ReadTxn>(txn: &T, e: &XmlElementRef, name: &str) -> bool {
-    matches!(e.get_attribute(txn, name), Some(Out::Any(Any::Bool(true))))
-}
-
 /// Text-content escaping, matching the browser serializer: `&`, `<`, `>`.
 fn escape_text(s: &str) -> String {
     s.replace('&', "&amp;")
@@ -562,20 +899,27 @@ mod tests {
         a
     }
 
-    /// The core proof: a document captured from a real Tiptap editor renders to
-    /// exactly the editor's own `getHTML()`. The fixture covers headings,
-    /// every mark and combination, links, escaping, blockquote, nested bullet
-    /// and ordered lists (with a `start`), a task list, code blocks with and
-    /// without a language, a hard break, a horizontal rule, an image, and the
-    /// trailing empty paragraph Tiptap keeps.
+    fn run(text: &str, marks: Option<&Attrs>) -> String {
+        render_run(text, marks, &Rules::empty())
+    }
+
+    /// Core rendering of the captured Tiptap document, pinned as a golden
+    /// (`.core.html`). The task list renders through the unknown-container
+    /// fallback here (unwrapped children); the external truth — byte parity
+    /// with the editor's own `getHTML()` — is held at the Ruby layer, where
+    /// `Y::Tiptap` completes the schema. The fixture covers headings, every
+    /// mark and combination, links, escaping, blockquote, nested bullet and
+    /// ordered lists (with a `start`), a task list, code blocks with and
+    /// without a language, a hard break, a horizontal rule, an image, and
+    /// the trailing empty paragraph Tiptap keeps.
     #[test]
-    fn renders_the_captured_tiptap_document_byte_for_byte() {
+    fn core_rendering_of_the_tiptap_fixture_is_pinned() {
         let doc = doc_from(include_bytes!("fixtures/prosemirror_tiptap.bin"));
         let txn = doc.transact();
         let frag = txn.get_xml_fragment("default").unwrap();
         assert_eq!(
             render(&txn, &frag).unwrap(),
-            include_str!("fixtures/prosemirror_tiptap.html")
+            include_str!("fixtures/prosemirror_tiptap.core.html")
         );
     }
 
@@ -595,25 +939,19 @@ mod tests {
 
     #[test]
     fn marks_nest_in_tiptaps_serializer_order() {
-        assert_eq!(render_run("x", None), "x");
-        assert_eq!(
-            render_run("x", Some(&marks(&["bold"]))),
-            "<strong>x</strong>"
-        );
-        assert_eq!(render_run("x", Some(&marks(&["italic"]))), "<em>x</em>");
+        assert_eq!(run("x", None), "x");
+        assert_eq!(run("x", Some(&marks(&["bold"]))), "<strong>x</strong>");
+        assert_eq!(run("x", Some(&marks(&["italic"]))), "<em>x</em>");
         // bold wraps italic.
         assert_eq!(
-            render_run("x", Some(&marks(&["italic", "bold"]))),
+            run("x", Some(&marks(&["italic", "bold"]))),
             "<strong><em>x</em></strong>"
         );
         // code excludes every other mark.
-        assert_eq!(
-            render_run("x", Some(&marks(&["code", "bold"]))),
-            "<code>x</code>"
-        );
+        assert_eq!(run("x", Some(&marks(&["code", "bold"]))), "<code>x</code>");
         // Full compatible stack, innermost sub to outermost bold.
         assert_eq!(
-            render_run(
+            run(
                 "x",
                 Some(&marks(&[
                     "bold",
@@ -627,7 +965,7 @@ mod tests {
             "<strong><em><s><u><mark><sub>x</sub></mark></u></s></em></strong>"
         );
         // Escaping happens before wrapping.
-        assert_eq!(render_run("<&>", None), "&lt;&amp;&gt;");
+        assert_eq!(run("<&>", None), "&lt;&amp;&gt;");
     }
 
     #[test]
@@ -642,7 +980,7 @@ mod tests {
         let mut a = Attrs::new();
         a.insert("link".into(), Any::Map(Arc::new(link)));
         assert_eq!(
-            render_run("site", Some(&a)),
+            run("site", Some(&a)),
             "<a target=\"_blank\" rel=\"noopener\" href=\"https://e.com?a=1&amp;b=2\">site</a>"
         );
 
@@ -656,22 +994,25 @@ mod tests {
         let mut a = Attrs::new();
         a.insert("link".into(), Any::Map(Arc::new(link)));
         assert_eq!(
-            render_run("the doc", Some(&a)),
+            run("the doc", Some(&a)),
             "<a class=\"doc-link\" href=\"https://d.example\" title=\"A Doc\">the doc</a>"
         );
     }
 
-    /// Mentions (captured from Tiptap's Mention extension): the fixture holds
-    /// one mention with a label, one with only an id, and a link carrying
-    /// class and title.
+    /// Core rendering of the captured mention document, pinned as a golden
+    /// (`.core.html`). Mention is a Tiptap extension node — an atom with no
+    /// children — so core renders it to nothing; parity with the editor's
+    /// `getHTML()` is held at the Ruby layer by `Y::Tiptap`. The fixture
+    /// holds one mention with a label, one with only an id, and a link
+    /// carrying class and title.
     #[test]
-    fn renders_the_captured_mention_document_byte_for_byte() {
+    fn core_rendering_of_the_mention_fixture_is_pinned() {
         let doc = doc_from(include_bytes!("fixtures/prosemirror_mention.bin"));
         let txn = doc.transact();
         let frag = txn.get_xml_fragment("default").unwrap();
         assert_eq!(
             render(&txn, &frag).unwrap(),
-            include_str!("fixtures/prosemirror_mention.html")
+            include_str!("fixtures/prosemirror_mention.core.html")
         );
     }
 
@@ -733,34 +1074,6 @@ mod tests {
         );
     }
 
-    /// The details family follows tiptap-php's renderHTML (the Tiptap
-    /// extension is Pro-only, so tiptap-php is the reference).
-    #[test]
-    fn renders_the_details_family_per_tiptap_php() {
-        let doc = Doc::new();
-        let frag = doc.get_or_insert_xml_fragment("default");
-        {
-            let mut txn = doc.transact_mut();
-            let details = frag.push_back(&mut txn, XmlElementPrelim::empty("details"));
-            details.insert_attribute(&mut txn, "open", true);
-            let summary = details.push_back(&mut txn, XmlElementPrelim::empty("detailsSummary"));
-            summary.push_back(&mut txn, XmlTextPrelim::new("More info"));
-            let content = details.push_back(&mut txn, XmlElementPrelim::empty("detailsContent"));
-            let p = content.push_back(&mut txn, XmlElementPrelim::empty("paragraph"));
-            p.push_back(&mut txn, XmlTextPrelim::new("The body."));
-
-            let closed = frag.push_back(&mut txn, XmlElementPrelim::empty("details"));
-            closed.push_back(&mut txn, XmlElementPrelim::empty("detailsSummary"));
-        }
-        let txn = doc.transact();
-        assert_eq!(
-            render(&txn, &frag).unwrap(),
-            "<details open=\"open\"><summary>More info</summary>\
-             <div data-type=\"detailsContent\"><p>The body.</p></div></details>\
-             <details><summary></summary></details>"
-        );
-    }
-
     /// prosemirror-schema-basic's `code` mark has no excludes, so a code run
     /// can also carry a link; the link must survive. (Tiptap's Code mark
     /// excludes everything, so this shape only comes from schema-basic docs.)
@@ -772,7 +1085,7 @@ mod tests {
         a.insert("code".into(), Any::Map(Arc::new(HashMap::new())));
         a.insert("link".into(), Any::Map(Arc::new(link)));
         assert_eq!(
-            render_run("x", Some(&a)),
+            run("x", Some(&a)),
             "<a href=\"https://e.com\"><code>x</code></a>"
         );
     }
@@ -893,4 +1206,160 @@ mod tests {
             r#"&lt;a &amp; &quot;b&quot;&gt;"#
         );
     }
+
+    /// A declarative node rule renders natively: tag, attribute refs resolved
+    /// from the node's attrs, and a blocks content slot. Rules can also
+    /// override a built-in (paragraph here).
+    #[test]
+    fn a_declarative_rule_renders_and_can_override_a_builtin() {
+        let rules = Rules::parse(
+            r#"{ "nodes": {
+                 "callout": { "tag": "aside",
+                              "attrs": [["class", [{"lit": "callout callout--"}, {"ref": "kind"}]]],
+                              "content": "blocks" },
+                 "paragraph": { "tag": "div", "attrs": [["class", [{"lit": "para"}]]] } } }"#,
+        )
+        .unwrap();
+        let doc = Doc::new();
+        let frag = doc.get_or_insert_xml_fragment("default");
+        {
+            let mut txn = doc.transact_mut();
+            let callout = frag.push_back(&mut txn, XmlElementPrelim::empty("callout"));
+            callout.insert_attribute(&mut txn, "kind", "warning");
+            let p = callout.push_back(&mut txn, XmlElementPrelim::empty("paragraph"));
+            p.push_back(&mut txn, XmlTextPrelim::new("careful"));
+        }
+        let txn = doc.transact();
+        let segs = render_segments(&txn, &frag, &rules).unwrap();
+        assert_eq!(
+            crate::render_rules::flatten(segs).into_html().unwrap(),
+            "<aside class=\"callout callout--warning\"><div class=\"para\">careful</div></aside>"
+        );
+    }
+
+    /// A callback rule defers: the node comes back as a Deferred segment with
+    /// its attrs as JSON and its children already rendered.
+    #[test]
+    fn a_callback_rule_emits_a_deferred_segment_with_rendered_content() {
+        let rules = Rules::parse(
+            r#"{ "nodes": { "videoEmbed": { "callback": true, "content": "blocks" } } }"#,
+        )
+        .unwrap();
+        let doc = Doc::new();
+        let frag = doc.get_or_insert_xml_fragment("default");
+        {
+            let mut txn = doc.transact_mut();
+            let intro = frag.push_back(&mut txn, XmlElementPrelim::empty("paragraph"));
+            intro.push_back(&mut txn, XmlTextPrelim::new("watch:"));
+            let video = frag.push_back(&mut txn, XmlElementPrelim::empty("videoEmbed"));
+            video.insert_attribute(&mut txn, "src", "https://v.example/1");
+            let caption = video.push_back(&mut txn, XmlElementPrelim::empty("paragraph"));
+            caption.push_back(&mut txn, XmlTextPrelim::new("the caption"));
+        }
+        let txn = doc.transact();
+        let segs = render_segments(&txn, &frag, &rules).unwrap();
+        assert_eq!(segs.len(), 2);
+        assert!(matches!(&segs[0], Segment::Html(s) if s == "<p>watch:</p>"));
+        let Segment::Deferred {
+            node_type,
+            attrs_json,
+            child_types,
+            content,
+        } = &segs[1]
+        else {
+            panic!("expected a deferred segment");
+        };
+        assert_eq!(node_type, "videoEmbed");
+        assert_eq!(attrs_json, r#"{"src":"https://v.example/1"}"#);
+        assert_eq!(child_types, &["paragraph"]);
+        assert!(matches!(&content[0], Segment::Html(s) if s == "<p>the caption</p>"));
+    }
+
+    /// Discovery reports facts per type, and an unknown type annotates as
+    /// unhandled (null) — the signal a rule author filters for.
+    #[test]
+    fn node_type_discovery_reports_unknown_types_as_unhandled() {
+        let doc = Doc::new();
+        let frag = doc.get_or_insert_xml_fragment("default");
+        {
+            let mut txn = doc.transact_mut();
+            let callout = frag.push_back(&mut txn, XmlElementPrelim::empty("callout"));
+            callout.insert_attribute(&mut txn, "kind", "warning");
+            let p = callout.push_back(&mut txn, XmlElementPrelim::empty("paragraph"));
+            p.push_back(&mut txn, XmlTextPrelim::new("body"));
+        }
+        let txn = doc.transact();
+        let map = collect_node_types(&txn, &frag).unwrap();
+        let json = crate::render_rules::type_map_json(&map, |ty| {
+            if is_builtin(ty) {
+                Some("builtin")
+            } else {
+                None
+            }
+        });
+        let v: serde_json::Value = serde_json::from_str(&json).unwrap();
+        assert_eq!(v["callout"]["handled"], serde_json::Value::Null);
+        assert_eq!(v["callout"]["attrs"][0], "kind");
+        assert_eq!(v["callout"]["children"][0], "paragraph");
+        assert_eq!(v["paragraph"]["handled"], "builtin");
+        assert_eq!(v["paragraph"]["text"], true);
+    }
+
+    /// A custom mark claims its stored name from the built-ins and wraps
+    /// outside everything, attribute refs resolving against the mark's map.
+    #[test]
+    fn a_custom_mark_overrides_the_builtin_and_wraps_outermost() {
+        let rules = Rules::parse(
+            r#"{ "marks": {
+                 "comment": { "tag": "span", "attrs": [["data-comment-id", [{"ref": "id"}]]] },
+                 "bold": { "tag": "b" } } }"#,
+        )
+        .unwrap();
+        let mut comment = HashMap::new();
+        comment.insert("id".to_string(), Any::String("c1".into()));
+        let mut a = Attrs::new();
+        a.insert("bold".into(), Any::Bool(true));
+        a.insert("italic".into(), Any::Bool(true));
+        a.insert("comment".into(), Any::Map(Arc::new(comment)));
+        assert_eq!(
+            render_run("x", Some(&a), &rules),
+            "<span data-comment-id=\"c1\"><b><em>x</em></b></span>"
+        );
+
+        // Overriding code replaces only its tag: the other
+        // formatting marks stay excluded.
+        let kbd = Rules::parse(r#"{ "marks": { "code": { "tag": "kbd" } } }"#).unwrap();
+        let mut a = Attrs::new();
+        a.insert("code".into(), Any::Bool(true));
+        a.insert("bold".into(), Any::Bool(true));
+        assert_eq!(render_run("x", Some(&a), &kbd), "<kbd>x</kbd>");
+    }
+
+    /// The exclusivity holds from the other direction too: a claimed
+    /// formatting mark must not sneak onto a code run through the custom
+    /// wrap when the built-in wrap would have excluded it.
+    #[test]
+    fn a_claimed_formatting_mark_stays_excluded_on_a_code_run() {
+        let rules = Rules::parse(r#"{ "marks": { "bold": { "tag": "b" } } }"#).unwrap();
+        let mut a = Attrs::new();
+        a.insert("code".into(), Any::Bool(true));
+        a.insert("bold".into(), Any::Bool(true));
+        assert_eq!(render_run("x", Some(&a), &rules), "<code>x</code>");
+
+        // The link claim is the exception, matching the built-in behavior
+        // (schema-basic can produce code+link; the href must survive).
+        let link_rule =
+            Rules::parse(r#"{ "marks": { "link": { "tag": "a", "attrs": [["href", [{"ref": "href"}]]] }, "bold": { "tag": "b" } } }"#)
+                .unwrap();
+        let mut link = HashMap::new();
+        link.insert("href".to_string(), Any::String("https://e.com".into()));
+        let mut a = Attrs::new();
+        a.insert("code".into(), Any::Bool(true));
+        a.insert("bold".into(), Any::Bool(true));
+        a.insert("link".into(), Any::Map(Arc::new(link)));
+        assert_eq!(
+            render_run("x", Some(&a), &link_rule),
+            "<a href=\"https://e.com\"><code>x</code></a>"
+        );
+    }
 }