yrby 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: addc2f9c08a109299b6c3db7cbf977b9b39194b7d784424b55876e8357897b29
-  data.tar.gz: 586d689d080396b5e3c9cf528f49dfbccd5dca831e6e64bbaf6de35216f74143
+  metadata.gz: bb0de1a9048f2aa942aad3bafed3269a029ed28ea178a72cb0f532e163cbb5f5
+  data.tar.gz: 6949735cd0edca033e78ef060333b91c40af2e3f900a79da46885d6630e6bc32
 SHA512:
-  metadata.gz: 3412853b540745a3a1db1134104c7cda42330d952b9d6eb08d8c20512069eae93f762aa77204cb6ecc3961da0c117df6bb66ef4b2aad5b0b81b05beedf3253b7
-  data.tar.gz: 6d65ed5a61f737cd904800747c40e74d7b57fb0f64f77b12128533a0cfbf4c86058e13d2b2a33d9d005a7bfd015c31683fb25054236dbb3f28639f867d9a3a69
+  metadata.gz: 3f0a9aeea9e3efdd443f7da526eaf692226015a5a6be037527e1600b74cb2529e123fbcf0f03d91282ad4b60e96cfd5d81d51d149ec1f42b06f27664f4cf3ffb
+  data.tar.gz: 5532beea7978401cf18a2970eac4eefdc037c075bc6de2fb56b92978b3dc5e8b3c5759b9b6d9aabfb879ba92517e3792810ab14fabf9ef4461da30bfa2bd4c39

data/CHANGELOG.md

@@ -6,6 +6,23 @@ to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-07
+
+### Added
+
+- **`Y::ProseMirror` — render ProseMirror/Tiptap documents to HTML.**
+  `Y::ProseMirror.new(doc).to_html` turns a Tiptap document into HTML on the
+  server, with no Node process or headless editor. The output matches Tiptap's
+  own `getHTML()`; the tests check it byte-for-byte against a document captured
+  from a real editor. It follows `ueberdosis/tiptap-php` and reads both name
+  styles editors use — Tiptap's `bulletList`/`bold` and prosemirror-schema-basic's
+  `bullet_list`/`strong`. Covers paragraphs, headings, blockquotes,
+  bullet/ordered/task lists, code blocks, links, images, mentions, details,
+  hard breaks, horizontal rules, tables, text styles (color, font family), and
+  every text mark. A table renders as semantic `<table><tbody>` without the
+  editor's column-width styling. A root that isn't ProseMirror (a Lexical
+  document, say) returns `nil`.
+
 ## [0.3.1] - 2026-07-01
 
 Fixes from a full source review.

data/README.md

@@ -175,6 +175,31 @@ guarantees keep serving safe:
   keeps its pending), while `encode_state_as_update` stays lossless so you can
   still preserve the raw pending bytes for recovery.
 
+### Rendering to HTML
+
+`Y::ProseMirror` renders a ProseMirror or Tiptap document to HTML on the
+server, with no Node process or headless editor:
+
+```ruby
+prosemirror = Y::ProseMirror.new(doc)
+prosemirror.to_html            # the "default" fragment (Tiptap's default root)
+prosemirror.to_html("content") # or another XML root
+```
+
+The output matches Tiptap's own `getHTML()`, checked byte-for-byte in the tests
+against a document captured from a real editor. So you can render, search, or
+email a collaborative document without running a browser. It follows
+[`tiptap-php`](https://github.com/ueberdosis/tiptap-php) and reads both name
+styles editors use — Tiptap's `bulletList`/`bold` and prosemirror-schema-basic's
+`bullet_list`/`strong`.
+
+It covers paragraphs, headings, blockquotes, bullet/ordered/task lists, code
+blocks, links, images, mentions, details, hard breaks, horizontal rules,
+tables, text styles (color, font family), and every text mark. A table renders
+as semantic `<table><tbody>`, without the column-width styling Tiptap's editor
+view adds. A root that isn't ProseMirror — a Lexical document, say — returns
+`nil`.
+
 ### Protocol codec (module functions)
 
 Classifying and unwrapping wire frames is stateless, so it's exposed as
@@ -242,21 +267,6 @@ servers:
   causal dependencies are already in the store (checked against `on_load`); a
   causally-incomplete update triggers a resync instead, so the log always
   rebuilds cleanly.
-- **An unhealable gap is dropped, not resynced forever.** A resync heals a gap
-  whose missing dependency is still in flight. But a *permanently*-orphaned update
-  (its dependency is gone for good) stays gappy through every resync, and a client
-  retransmitting it would loop endlessly (server resyncs → client resends →
-  repeat). After `gap_strike_limit` rejections of the same update on one
-  connection (default 3, minimum 2), the channel settles it with
-  `{ "ack" => id, "dropped" => true }` and drops it instead of resyncing again —
-  breaking the loop while never dropping a *healable* gap (those heal within a
-  resync or two, and healing frees the strike). The `dropped` flag lets the
-  client surface the loss (`yrby-client` reports it via `onError`) instead of
-  silently showing synced. Set `gap_strike_limit nil` to disable. Works on both
-  transports: plain ActionCable keeps strikes on the channel instance; under
-  AnyCable (fresh instance per RPC command) they persist through
-  anycable-rails' `state_attr_accessor` (istate), declared automatically when
-  anycable-rails is loaded.
 - **`on_change` is at-least-once, and the durable guarantee is that replaying the
   log reconstructs the document.** Every update triggers `on_change` before it's acked or
   broadcast (record-before-distribute). If exactly-once updates matter for you, **you

data/ext/yrby/src/lib.rs

@@ -6,6 +6,7 @@ use yrs::updates::decoder::Decode;
 use yrs::updates::encoder::Encode;
 use yrs::{Doc, GetString, ReadTxn, Transact};
 
+mod prosemirror_html;
 mod protocol;
 mod read;
 use protocol::{
@@ -30,6 +31,7 @@ struct RbDoc(Doc);
 fn assert_thread_safe() {
     fn is_send_sync<T: Send + Sync>() {}
     is_send_sync::<Doc>();
+    is_send_sync::<RbProseMirror>();
 }
 
 /// Run `f` with the GVL (Global VM Lock) released, so other Ruby threads,
@@ -329,6 +331,55 @@ impl RbDoc {
     }
 }
 
+// ============================================================================
+// Y::ProseMirror — schema-pinned rendering of ProseMirror/Tiptap documents
+// ============================================================================
+
+/// A ProseMirror/Tiptap view over a `Y::Doc`. The schema knowledge (node/mark
+/// names, Tiptap's serializer semantics) lives here rather than on the
+/// schema-agnostic `Doc`. Holds a cheap clone of the doc (yrs `Doc` is an Arc
+/// handle), so it reads live state.
+///
+/// Thread safety matches `Y::Doc`: every method opens its own transaction
+/// inside `nogvl` and holds no lock across the GVL boundary.
+#[magnus::wrap(class = "Y::ProseMirror", free_immediately, size)]
+struct RbProseMirror(Doc);
+
+impl RbProseMirror {
+    /// `Y::ProseMirror.new(doc)`
+    fn new(doc: &RbDoc) -> Self {
+        RbProseMirror(doc.0.clone())
+    }
+
+    /// Render an XML root (default `"default"`, the fragment name Tiptap's
+    /// Collaboration extension uses) to HTML. Output follows tiptap-php and
+    /// matches Tiptap's `getHTML()` on the reference fixture; see
+    /// `prosemirror_html.rs` for coverage and caveats. Returns nil when the
+    /// root is missing or not ProseMirror-shaped (e.g. a Lexical document).
+    fn to_html(&self, args: &[Value]) -> Result<Option<String>, Error> {
+        if args.len() > 1 {
+            let ruby = Ruby::get().unwrap();
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                format!(
+                    "wrong number of arguments (given {}, expected 0..1)",
+                    args.len()
+                ),
+            ));
+        }
+        let name: String = match args.first() {
+            Some(arg) => TryConvert::try_convert(*arg)?,
+            None => "default".to_string(),
+        };
+        let doc = &self.0;
+        Ok(nogvl(move || {
+            let txn = doc.transact();
+            let fragment = txn.get_xml_fragment(name.as_str())?;
+            prosemirror_html::render(&txn, &fragment)
+        }))
+    }
+}
+
 // ============================================================================
 // Protocol codec (stateless), exposed as `Y` module functions
 // ============================================================================
@@ -409,6 +460,11 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         "handle_sync_message",
         method!(RbDoc::handle_sync_message, 1),
     )?;
+    // Y::ProseMirror: schema-pinned ProseMirror/Tiptap rendering over a Doc.
+    let prosemirror_class = module.define_class("ProseMirror", ruby.class_object())?;
+    prosemirror_class.define_singleton_method("new", function!(RbProseMirror::new, 1))?;
+    prosemirror_class.define_method("to_html", method!(RbProseMirror::to_html, -1))?;
+
     // Stateless protocol codec, as Y module functions.
     module.define_module_function("wrap_update", function!(wrap_update, 1))?;
     module.define_module_function("message_kind", function!(message_kind, 1))?;

data/ext/yrby/src/prosemirror_html.rs

@@ -0,0 +1,896 @@
+//! Native HTML rendering of ProseMirror/Tiptap documents from the yrs collab
+//! structure — no Node process, no headless editor.
+//!
+//! The y-prosemirror binding stores a document in a Y.XmlFragment: block nodes
+//! are Y.XmlElement (the tag is the node type, its attributes are the node
+//! attrs), and text is Y.XmlText whose per-run formatting attributes are the
+//! marks. Node and mark names come from the editor's schema, so this accepts
+//! 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.
+//!
+//! 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>`.
+
+use yrs::types::text::YChange;
+use yrs::types::Attrs;
+use yrs::{
+    Any, GetString, Out, ReadTxn, Text, Xml, XmlElementRef, XmlFragment, XmlFragmentRef, XmlOut,
+    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.
+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.
+enum Work {
+    Open(XmlElementRef, usize),
+    Close(&'static str),
+}
+
+/// 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> {
+    if !is_prosemirror_shaped(txn, fragment) {
+        return None;
+    }
+    let mut out = String::new();
+    for node in fragment.children(txn) {
+        match node {
+            XmlOut::Element(e) => render_block_tree(txn, &e, &mut out),
+            // 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),
+            // 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))),
+        }
+    }
+    Some(out)
+}
+
+/// A root is ProseMirror-shaped when it's empty or its first child is a block
+/// element with no `__type` (Lexical stamps `__type` on every node; ProseMirror
+/// uses the node type as the element tag).
+fn is_prosemirror_shaped<T: ReadTxn>(txn: &T, fragment: &XmlFragmentRef) -> bool {
+    match fragment.children(txn).next() {
+        Some(XmlOut::Element(e)) => e.get_attribute(txn, "__type").is_none(),
+        Some(_) => false, // Lexical stores blocks as XmlText
+        None => true,     // empty document
+    }
+}
+
+/// 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) {
+    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),
+        }
+    }
+}
+
+/// 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.
+fn open_block<T: ReadTxn>(
+    txn: &T,
+    e: &XmlElementRef,
+    depth: usize,
+    out: &mut String,
+    stack: &mut Vec<Work>,
+) {
+    match e.tag().as_ref() {
+        "paragraph" => {
+            out.push_str("<p>");
+            out.push_str(&render_inline(txn, e, 0));
+            out.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('>');
+        }
+        "codeBlock" | "code_block" => {
+            out.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>"),
+            }
+            push_block_children(txn, e, depth, "</ol>", out, stack);
+        }
+        "listItem" | "list_item" => open_container(txn, e, depth, "<li>", "</li>", out, stack),
+        "taskList" | "task_list" => open_container(
+            txn,
+            e,
+            depth,
+            "<ul data-type=\"taskList\">",
+            "</ul>",
+            out,
+            stack,
+        ),
+        "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\"");
+            }
+            out.push_str("><span></span></label><div>");
+            push_block_children(txn, e, depth, "</div></li>", out, stack);
+        }
+        "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);
+        }
+        "detailsSummary" | "details_summary" => {
+            out.push_str("<summary>");
+            out.push_str(&render_inline(txn, e, 0));
+            out.push_str("</summary>");
+        }
+        "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>"),
+        // 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.
+        _ => {
+            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);
+            } else {
+                let inline = render_inline(txn, e, 0);
+                if !inline.is_empty() {
+                    out.push_str("<p>");
+                    out.push_str(&inline);
+                    out.push_str("</p>");
+                }
+            }
+        }
+    }
+}
+
+fn open_container<T: ReadTxn>(
+    txn: &T,
+    e: &XmlElementRef,
+    depth: usize,
+    open: &str,
+    close: &'static str,
+    out: &mut String,
+    stack: &mut Vec<Work>,
+) {
+    out.push_str(open);
+    push_block_children(txn, e, depth, close, out, stack);
+}
+
+/// A table cell: `<th>`/`<td>` carrying colspan/rowspan (default 1, always
+/// emitted, matching Tiptap).
+fn open_cell<T: ReadTxn>(
+    txn: &T,
+    e: &XmlElementRef,
+    depth: usize,
+    tag: &str,
+    close: &'static str,
+    out: &mut String,
+    stack: &mut Vec<Work>,
+) {
+    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);
+}
+
+/// 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
+/// formed.
+fn push_block_children<T: ReadTxn>(
+    txn: &T,
+    e: &XmlElementRef,
+    depth: usize,
+    close: &'static str,
+    out: &mut String,
+    stack: &mut Vec<Work>,
+) {
+    for node in e.children(txn) {
+        if let XmlOut::Text(t) = node {
+            render_text_runs(txn, &t, out);
+        }
+    }
+    stack.push(Work::Close(close));
+    if depth >= MAX_DEPTH {
+        return;
+    }
+    let children: Vec<_> = 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));
+    }
+}
+
+/// 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();
+    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::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>");
+}
+
+/// Emit each formatted run of a Y.XmlText.
+fn render_text_runs<T: ReadTxn>(txn: &T, t: &XmlTextRef, out: &mut String) {
+    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()));
+        }
+    }
+}
+
+/// Wrap one text run in its marks, nesting innermost-first:
+/// subscript/superscript, highlight, underline, strike, italic, bold, a
+/// textStyle span, then link on the outside. `code` renders alone among the
+/// 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 {
+    let mut html = escape_text(text);
+    let Some(marks) = marks else {
+        return html;
+    };
+    if has(marks, &["code"]) {
+        html = wrap(html, "code");
+    } else {
+        if has(marks, &["subscript", "sub"]) {
+            html = wrap(html, "sub");
+        } else if has(marks, &["superscript", "sup"]) {
+            html = wrap(html, "sup");
+        }
+        if has(marks, &["highlight"]) {
+            html = wrap(html, "mark");
+        }
+        if has(marks, &["underline", "u"]) {
+            html = wrap(html, "u");
+        }
+        if has(marks, &["strike", "s"]) {
+            html = wrap(html, "s");
+        }
+        if has(marks, &["italic", "em"]) {
+            html = wrap(html, "em");
+        }
+        if has(marks, &["bold", "strong"]) {
+            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 let Some(Any::Map(link)) = marks.get("link") {
+        html = wrap_link(html, link);
+    }
+    html
+}
+
+/// 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.
+/// Keys sort alphabetically, which is the order Tiptap serializes (color
+/// before font-family). Hex colors convert to rgb() because that's how they
+/// come back out of the browser's style attribute; other values pass through.
+fn text_style_css(style: &std::collections::HashMap<String, Any>) -> String {
+    let mut pairs: Vec<_> = style
+        .iter()
+        .filter_map(|(k, v)| match v {
+            Any::String(s) => Some((k, s.as_ref())),
+            _ => None,
+        })
+        .collect();
+    pairs.sort_by(|a, b| a.0.cmp(b.0));
+    let mut css = String::new();
+    for (key, value) in pairs {
+        if !css.is_empty() {
+            css.push(' ');
+        }
+        // camelCase -> kebab-case: fontFamily -> font-family.
+        for ch in key.chars() {
+            if ch.is_ascii_uppercase() {
+                css.push('-');
+                css.push(ch.to_ascii_lowercase());
+            } else {
+                css.push(ch);
+            }
+        }
+        css.push_str(": ");
+        css.push_str(&hex_to_rgb(value).unwrap_or_else(|| value.to_string()));
+        css.push(';');
+    }
+    css
+}
+
+/// `#rgb`/`#rrggbb` -> `rgb(r, g, b)`, matching the browser's style-attribute
+/// serialization. Anything else (named colors, rgb()/hsl(), fonts) is None.
+fn hex_to_rgb(value: &str) -> Option<String> {
+    let hex = value.strip_prefix('#')?;
+    // len() and the slices below are byte-based; non-ASCII input would panic
+    // on a char boundary. Real hex never is, crafted input passes through.
+    if !hex.is_ascii() {
+        return None;
+    }
+    let (r, g, b) = match hex.len() {
+        3 => {
+            let d = |i: usize| u8::from_str_radix(&hex[i..=i].repeat(2), 16);
+            (d(0).ok()?, d(1).ok()?, d(2).ok()?)
+        }
+        6 => {
+            let d = |i: usize| u8::from_str_radix(&hex[i..i + 2], 16);
+            (d(0).ok()?, d(2).ok()?, d(4).ok()?)
+        }
+        _ => return None,
+    };
+    Some(format!("rgb({r}, {g}, {b})"))
+}
+
+/// `<a>` with Tiptap's attribute order (target, rel, class, href, title),
+/// skipping any that are absent or null.
+fn wrap_link(inner: String, link: &std::collections::HashMap<String, Any>) -> String {
+    let mut out = String::from("<a");
+    for key in ["target", "rel", "class", "href", "title"] {
+        if let Some(Any::String(v)) = link.get(key) {
+            out.push(' ');
+            out.push_str(key);
+            out.push_str("=\"");
+            out.push_str(&escape_attr(v));
+            out.push('"');
+        }
+    }
+    out.push('>');
+    out.push_str(&inner);
+    out.push_str("</a>");
+    out
+}
+
+/// `<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");
+    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('"');
+        }
+    }
+    out.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))
+}
+
+fn has_element_child<T: ReadTxn>(txn: &T, e: &XmlElementRef) -> bool {
+    e.children(txn).any(|c| matches!(c, XmlOut::Element(_)))
+}
+
+/// The concatenated text of a code block (no marks — code is plain text).
+fn code_text<T: ReadTxn>(txn: &T, e: &XmlElementRef) -> String {
+    let mut s = String::new();
+    for node in e.children(txn) {
+        if let XmlOut::Text(t) = node {
+            for d in t.diff(txn, YChange::identity) {
+                if let Out::Any(Any::String(run)) = &d.insert {
+                    s.push_str(run);
+                }
+            }
+        }
+    }
+    s
+}
+
+fn str_attr<T: ReadTxn>(txn: &T, e: &XmlElementRef, name: &str) -> Option<String> {
+    match e.get_attribute(txn, name) {
+        Some(Out::Any(Any::String(s))) => Some(s.to_string()),
+        _ => None,
+    }
+}
+
+fn num_attr<T: ReadTxn>(txn: &T, e: &XmlElementRef, name: &str) -> Option<i64> {
+    match e.get_attribute(txn, name) {
+        Some(Out::Any(Any::Number(n))) => Some(n as i64),
+        Some(Out::Any(Any::BigInt(n))) => Some(n),
+        _ => None,
+    }
+}
+
+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;")
+        .replace('<', "&lt;")
+        .replace('>', "&gt;")
+}
+
+/// Attribute-value escaping: text escaping plus `"`.
+fn escape_attr(s: &str) -> String {
+    escape_text(s).replace('"', "&quot;")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::HashMap;
+    use std::sync::Arc;
+    use yrs::updates::decoder::Decode;
+    use yrs::{Doc, Transact, Update, XmlElementPrelim, XmlTextPrelim};
+
+    fn doc_from(bytes: &[u8]) -> Doc {
+        let doc = Doc::new();
+        doc.transact_mut()
+            .apply_update(Update::decode_v1(bytes).unwrap())
+            .unwrap();
+        doc
+    }
+
+    fn marks(keys: &[&str]) -> Attrs {
+        let mut a = Attrs::new();
+        for k in keys {
+            a.insert((*k).into(), Any::Bool(true));
+        }
+        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.
+    #[test]
+    fn renders_the_captured_tiptap_document_byte_for_byte() {
+        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")
+        );
+    }
+
+    /// A table renders as tiptap-php's semantic form — `<table><tbody>` with
+    /// colspan/rowspan cells — dropping the `<colgroup>`/`min-width` styling
+    /// Tiptap's editor view adds (and which isn't in the CRDT).
+    #[test]
+    fn renders_a_table_as_semantic_html() {
+        let doc = doc_from(include_bytes!("fixtures/prosemirror_table.bin"));
+        let txn = doc.transact();
+        let frag = txn.get_xml_fragment("default").unwrap();
+        assert_eq!(
+            render(&txn, &frag).unwrap(),
+            include_str!("fixtures/prosemirror_table.html")
+        );
+    }
+
+    #[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>");
+        // bold wraps italic.
+        assert_eq!(
+            render_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>"
+        );
+        // Full compatible stack, innermost sub to outermost bold.
+        assert_eq!(
+            render_run(
+                "x",
+                Some(&marks(&[
+                    "bold",
+                    "italic",
+                    "strike",
+                    "underline",
+                    "highlight",
+                    "subscript"
+                ]))
+            ),
+            "<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;");
+    }
+
+    #[test]
+    fn renders_a_link_run_with_tiptaps_attribute_order() {
+        let mut link = HashMap::new();
+        link.insert(
+            "href".to_string(),
+            Any::String("https://e.com?a=1&b=2".into()),
+        );
+        link.insert("target".to_string(), Any::String("_blank".into()));
+        link.insert("rel".to_string(), Any::String("noopener".into()));
+        let mut a = Attrs::new();
+        a.insert("link".into(), Any::Map(Arc::new(link)));
+        assert_eq!(
+            render_run("site", Some(&a)),
+            "<a target=\"_blank\" rel=\"noopener\" href=\"https://e.com?a=1&amp;b=2\">site</a>"
+        );
+
+        // class and title (Link's remaining attrs) keep Tiptap's serialized
+        // order: target, rel, class, href, title. Null-valued attrs skip.
+        let mut link = HashMap::new();
+        link.insert("href".to_string(), Any::String("https://d.example".into()));
+        link.insert("class".to_string(), Any::String("doc-link".into()));
+        link.insert("title".to_string(), Any::String("A Doc".into()));
+        link.insert("target".to_string(), Any::Null);
+        let mut a = Attrs::new();
+        a.insert("link".into(), Any::Map(Arc::new(link)));
+        assert_eq!(
+            render_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.
+    #[test]
+    fn renders_the_captured_mention_document_byte_for_byte() {
+        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")
+        );
+    }
+
+    /// textStyle (captured from Tiptap's Color/FontFamily extensions): hex
+    /// colors come back out of the browser as rgb(), rgb() strings pass
+    /// through, font-family joins the same span, and the span wraps outside
+    /// bold.
+    #[test]
+    fn renders_the_captured_textstyle_document_byte_for_byte() {
+        let doc = doc_from(include_bytes!("fixtures/prosemirror_textstyle.bin"));
+        let txn = doc.transact();
+        let frag = txn.get_xml_fragment("default").unwrap();
+        assert_eq!(
+            render(&txn, &frag).unwrap(),
+            include_str!("fixtures/prosemirror_textstyle.html")
+        );
+    }
+
+    #[test]
+    fn text_style_converts_hex_and_kebab_cases_keys() {
+        let mut style = HashMap::new();
+        style.insert("color".to_string(), Any::String("#ff0000".into()));
+        style.insert(
+            "fontFamily".to_string(),
+            Any::String("Georgia, serif".into()),
+        );
+        style.insert("fontSize".to_string(), Any::Null); // unset: skipped
+        assert_eq!(
+            text_style_css(&style),
+            "color: rgb(255, 0, 0); font-family: Georgia, serif;"
+        );
+
+        assert_eq!(hex_to_rgb("#0f8"), Some("rgb(0, 255, 136)".to_string()));
+        assert_eq!(hex_to_rgb("rebeccapurple"), None);
+        assert_eq!(hex_to_rgb("#12345"), None);
+        // Multibyte input must pass through, not panic on a byte-slice
+        // boundary ("日" is one char, three bytes — it enters the 3 arm).
+        assert_eq!(hex_to_rgb("#日"), None);
+        assert_eq!(hex_to_rgb("#日本"), None);
+    }
+
+    /// A known container with bare text jammed directly into it (schema-valid
+    /// documents never do this) keeps the text instead of dropping it.
+    #[test]
+    fn a_known_container_keeps_stray_direct_text() {
+        let doc = Doc::new();
+        let frag = doc.get_or_insert_xml_fragment("default");
+        {
+            let mut txn = doc.transact_mut();
+            let bq = frag.push_back(&mut txn, XmlElementPrelim::empty("blockquote"));
+            bq.push_back(&mut txn, XmlTextPrelim::new("stray"));
+            let p = bq.push_back(&mut txn, XmlElementPrelim::empty("paragraph"));
+            p.push_back(&mut txn, XmlTextPrelim::new("body"));
+        }
+        let txn = doc.transact();
+        assert_eq!(
+            render(&txn, &frag).unwrap(),
+            "<blockquote>stray<p>body</p></blockquote>"
+        );
+    }
+
+    /// 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.)
+    #[test]
+    fn a_code_run_keeps_its_link() {
+        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::Map(Arc::new(HashMap::new())));
+        a.insert("link".into(), Any::Map(Arc::new(link)));
+        assert_eq!(
+            render_run("x", Some(&a)),
+            "<a href=\"https://e.com\"><code>x</code></a>"
+        );
+    }
+
+    /// An unknown block holding both text and child blocks keeps the text.
+    #[test]
+    fn an_unknown_block_with_mixed_content_keeps_its_text() {
+        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.push_back(&mut txn, XmlTextPrelim::new("intro"));
+            let p = callout.push_back(&mut txn, XmlElementPrelim::empty("paragraph"));
+            p.push_back(&mut txn, XmlTextPrelim::new("body"));
+        }
+        let txn = doc.transact();
+        assert_eq!(render(&txn, &frag).unwrap(), "intro<p>body</p>");
+    }
+
+    /// An unknown inline node keeps its text instead of vanishing.
+    #[test]
+    fn an_unknown_inline_node_keeps_its_text() {
+        let doc = Doc::new();
+        let frag = doc.get_or_insert_xml_fragment("default");
+        {
+            let mut txn = doc.transact_mut();
+            let p = frag.push_back(&mut txn, XmlElementPrelim::empty("paragraph"));
+            p.push_back(&mut txn, XmlTextPrelim::new("see "));
+            let custom = p.push_back(&mut txn, XmlElementPrelim::empty("customInline"));
+            custom.push_back(&mut txn, XmlTextPrelim::new("kept"));
+            p.push_back(&mut txn, XmlTextPrelim::new(" here"));
+        }
+        let txn = doc.transact();
+        assert_eq!(render(&txn, &frag).unwrap(), "<p>see kept here</p>");
+    }
+
+    /// The prosemirror-schema-basic spellings (snake_case nodes, `strong`/`em`
+    /// marks) render the same as Tiptap's camelCase.
+    #[test]
+    fn accepts_prosemirror_basic_schema_names() {
+        let doc = Doc::new();
+        let frag = doc.get_or_insert_xml_fragment("default");
+        {
+            let mut txn = doc.transact_mut();
+            let bq = frag.push_back(&mut txn, XmlElementPrelim::empty("blockquote"));
+            let p = bq.push_back(&mut txn, XmlElementPrelim::empty("paragraph"));
+            let t = p.push_back(&mut txn, XmlTextPrelim::new("hi bold it"));
+            t.format(&mut txn, 3, 4, marks(&["strong"]));
+            t.format(&mut txn, 8, 2, marks(&["em"]));
+        }
+        let txn = doc.transact();
+        assert_eq!(
+            render(&txn, &frag).unwrap(),
+            "<blockquote><p>hi <strong>bold</strong> <em>it</em></p></blockquote>"
+        );
+    }
+
+    #[test]
+    fn a_lexical_shaped_root_is_refused() {
+        // A Lexical doc stores blocks as XmlText carrying `__type`. That's a
+        // different schema; render must return None, not a garbled document.
+        let doc = Doc::new();
+        // Create both roots before opening the read transaction:
+        // get_or_insert_* opens its own write transaction, which would deadlock
+        // against a live read guard.
+        let frag = doc.get_or_insert_xml_fragment("root");
+        let empty = doc.get_or_insert_xml_fragment("empty");
+        {
+            let mut txn = doc.transact_mut();
+            let block = frag.push_back(&mut txn, XmlTextPrelim::new("hello"));
+            block.insert_attribute(&mut txn, "__type", "paragraph");
+        }
+        let txn = doc.transact();
+        assert_eq!(render(&txn, &frag), None);
+        // An empty root is fine.
+        assert_eq!(render(&txn, &empty).as_deref(), Some(""));
+    }
+
+    #[test]
+    fn deeply_nested_blocks_do_not_overflow_the_stack() {
+        // The walk is on the heap, so nesting that would blow a small native
+        // stack under recursion renders fine. Built and rendered on a 512 KiB
+        // thread so it can't pass just by having room to spare.
+        std::thread::Builder::new()
+            .stack_size(512 * 1024)
+            .spawn(|| {
+                let doc = Doc::new();
+                let frag = doc.get_or_insert_xml_fragment("default");
+                {
+                    let mut txn = doc.transact_mut();
+                    let mut cursor =
+                        frag.push_back(&mut txn, XmlElementPrelim::empty("blockquote"));
+                    for _ in 0..20_000 {
+                        cursor = cursor.push_back(&mut txn, XmlElementPrelim::empty("blockquote"));
+                    }
+                    let p = cursor.push_back(&mut txn, XmlElementPrelim::empty("paragraph"));
+                    p.push_back(&mut txn, XmlTextPrelim::new("deep"));
+                }
+                let txn = doc.transact();
+                let html = render(&txn, &frag).expect("prosemirror-shaped");
+                assert_eq!(
+                    html.matches("<blockquote>").count(),
+                    html.matches("</blockquote>").count()
+                );
+                assert!(html.contains("<p>deep</p>") || html.contains("<blockquote>"));
+            })
+            .unwrap()
+            .join()
+            .unwrap();
+    }
+
+    #[test]
+    fn escaping_matches_the_browser_serializer() {
+        assert_eq!(escape_text(r#"<a & "b">"#), r#"&lt;a &amp; "b"&gt;"#);
+        assert_eq!(
+            escape_attr(r#"<a & "b">"#),
+            r#"&lt;a &amp; &quot;b&quot;&gt;"#
+        );
+    }
+}

data/lib/y/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Y
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yrby
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - JP Camara
@@ -84,6 +84,7 @@ files:
 - ext/yrby/Cargo.toml
 - ext/yrby/extconf.rb
 - ext/yrby/src/lib.rs
+- ext/yrby/src/prosemirror_html.rs
 - ext/yrby/src/protocol.rs
 - ext/yrby/src/read.rs
 - lib/y.rb