yrby 0.5.0-x86_64-linux → 0.6.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 231867b33dd1e931ddd90b1b8c6dc2ba1b57d2959038bf4bc5e3cf0c18e1974f
-  data.tar.gz: 28a227ff609a340c2ec9e52eac3ff5fa0a8853969fbf2aa0b1d3a93d9274f4ef
+  metadata.gz: 79698fd2fb1bd27630f886cb29bb5f0bf6a5bacdcfaf0104cfa93e2b82ac0cce
+  data.tar.gz: 9b527fc536ca22c48b1800529d98d5887d4414d4d45c58fb82c6c4c8a1c5d3bc
 SHA512:
-  metadata.gz: f1410e692049f9c97a34cda63c174bbd9cf3a72061c1a43db121e1e15b72b9120663129e1bea81c188d65d9255df161b7b19c4c9b3f055960d93faf0baf68ee5
-  data.tar.gz: b1057a860265ce47641c11560a5c2eee9ce10acb676c161847484fb8247621288be44899cc95f86c2ccd49bbd8d5699858935e19a62791feff83c8e21eed91f6
+  metadata.gz: 580f47b1edb62176cec4d081a063a642fc6ebde8dee413c22dde243cdb430c430a118dc3d72123aba015661c58f3924c9cd56514fb6e8f57643ef38dc28295da
+  data.tar.gz: 3c64aeee5940a2183198362c04a2cdb508263fc24143bae33310f84a91a0a822c9fced780047da543288f4a3e25c8524edcc2d73828068136eebf4a02d12faff

data/CHANGELOG.md

@@ -4,7 +4,68 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project aims
 to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.6.0] - 2026-07-11
+
+### Added
+
+- **Custom render rules for `Y::Lexical` and `Y::ProseMirror`.** Both
+  renderers now take a block registering rules per node type —
+  `rules.node "callout", tag: "aside"` for markup-as-data, a Ruby block for
+  logic — plus `nodes:`/`marks:` keywords as the equivalent data form, to
+  render node types the pinned schemas don't know or to override how a
+  built-in renders.
+  Declarative rules (`tag`/`attrs`/`text`/`contains`, with templates mixing
+  literals and attribute references) render natively at full speed. Callback
+  rules run a Ruby block per node, receiving its type, attributes,
+  already-rendered children, and `child_types` (its element/block children by
+  type — the structural facts behind gallery counts and nested-list classes).
+  The block runs after the document read has finished, never while the doc is
+  locked, so it can safely read or write the same doc. Blocks are proven
+  sufficient for whole schemas: the gem's own editor schemas (`Y::Lexxy`,
+  `Y::Tiptap`) ship through this API, and the fixture tests hold their
+  output byte-identical to a live editor's. With no callback rules the
+  render path is unchanged, byte for byte. See "Custom nodes and marks" in
+  the README.
+- **`Y::Lexical#node_types` / `Y::ProseMirror#node_types` — schema
+  discovery.** Ask a real document which node types it holds and what they
+  look like: counts, attribute names as stored, child types, whether text
+  runs appear, and whether a builtin or one of your rules already handles
+  each ("handled" nil marks what still needs a rule). Editors store names
+  you'd never guess; this is how you find them.
+- `Y::RenderRules.escape_text` / `escape_attr` — the exact escaping the
+  native renderers use, for blocks that build markup from stored values
+  (ERB's `html_escape` also rewrites apostrophes, which breaks byte parity
+  with editor output).
+
+### Changed
+
+- **Lexical rendering is now two classes: `Y::Lexical` (core Lexical) and
+  `Y::Lexxy` (core plus the Lexxy schema as render rules).** Stock Lexical
+  has no canonical serializer, so the editor-specific class carries the
+  editor's name — `Y::Lexxy.new(doc).to_html` is the byte-parity call for
+  Lexxy/Rails apps, and `Y::Lexical` is the base any other Lexical editor
+  extends with its own rules. The
+  native side renders core structure — paragraphs, headings, quotes, code,
+  lists, tables, links, the full text-format model. Lexxy's own node types
+  (attachments, galleries, `early_escape_code`, `horizontal_divider`) and its
+  decorations of core nodes (the table figure wrapper, header-cell styling,
+  the nested-list-item class) are rules applied beneath the app's, on the
+  same extension API — the gem's Lexxy support is the API's first consumer.
+  Output is unchanged: the fixture tests still hold `to_html` byte-identical
+  to a live editor's serialized value, now through the extension path. An
+  unknown Lexical container also degrades better: its block children render
+  without an invented wrapper instead of being dropped.
+- **ProseMirror rendering gets the same split: `Y::ProseMirror` (core
+  ProseMirror) and `Y::Tiptap` (core plus Tiptap's extension nodes as render
+  rules).** `Y::Tiptap.new(doc).to_html` is the byte-parity call for Tiptap
+  apps. The native side renders prosemirror-schema-basic plus the
+  prosemirror-tables family; Tiptap's extension nodes — task lists, mentions,
+  the details family — are `Y::Tiptap::NODES` rules. Marks stay native in the
+  base class: mark rendering (nesting order, `textStyle` CSS, `code`
+  exclusivity) runs through text-run machinery node rules don't reach, so
+  `Y::ProseMirror` still renders Tiptap's full mark set and `rules.mark`
+  overrides individual marks. Output through `Y::Tiptap` is unchanged, held
+  byte-identical to a live editor's `getHTML()` by the fixture tests.
 
 ## [0.5.0] - 2026-07-08
 

data/README.md

@@ -129,6 +129,27 @@ The rest of the dev setup, plus the demo, is in [CONTRIBUTING.md](CONTRIBUTING.m
   and the test/load suites.
 - [CHANGELOG.md](CHANGELOG.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
 
+## Editors
+
+yrby syncs opaque Yjs updates, so it works with any editor that has a Yjs
+binding. The demo app runs four, and CI drives each one in real Chrome:
+concurrent typing with every keystroke accounted for, remote cursors,
+local-only undo, and byte parity between the server-side renderers and the
+editor's own serializer. Each page is a working integration to copy from:
+
+| Editor | Yjs binding | Demo code |
+|---|---|---|
+| [Tiptap](https://tiptap.dev) (v2) | `@tiptap/extension-collaboration` | [`app.js`](examples/actioncable-demo/frontend/src/app.js) |
+| [Lexxy](https://github.com/basecamp/lexxy) (Lexical) | [`lexxy-realtime`](https://www.npmjs.com/package/lexxy-realtime) | [`lexxy.js`](examples/actioncable-demo/frontend/src/lexxy.js) |
+| [Rhino Editor](https://github.com/KonnorRogers/rhino-editor) (Tiptap 3) | `@tiptap/extension-collaboration` + `-caret` | [`rhino.js`](examples/actioncable-demo/frontend/src/rhino.js) |
+| [CodeMirror 6](https://codemirror.net) | `y-codemirror.next` | [`codemirror.js`](examples/actioncable-demo/frontend/src/codemirror.js) |
+
+The demo also syncs plain Yjs shapes with no editor at all — a whiteboard
+on a `Y.Map`, a kanban board on a `Y.Array`, a co-filled form — over the
+same channel. The demo README's "Using this in your own app" section has
+the integration recipe, and its `NoteMaterializer` shows how to render a
+document to ActionText server-side with `Y::Tiptap` or `Y::Lexxy`.
+
 ## Usage
 
 ### Doc (Low-Level Document Sync)
@@ -188,18 +209,20 @@ guarantees keep serving safe:
 
 ### Rendering to HTML
 
-Two schema-pinned renderers turn a collaborative document into HTML on the
-server, with no Node process or headless editor: `Y::ProseMirror` for
-ProseMirror/Tiptap documents and `Y::Lexical` for
-[Lexxy](https://github.com/basecamp/lexxy) (Lexical) documents. Each returns
-`nil` for a root that belongs to the other schema.
+Schema-pinned renderers turn a collaborative document into HTML on the
+server, with no Node process or headless editor. Each is an editor-specific
+class (byte-for-byte with that editor's own serializer) built on a core base
+any other editor extends with rules: `Y::Tiptap` on `Y::ProseMirror` for
+ProseMirror documents, and `Y::Lexxy` (the
+[Lexxy](https://github.com/basecamp/lexxy) editor) on `Y::Lexical`. Each
+returns `nil` for a root that belongs to the other schema.
 
-#### `Y::ProseMirror`
+#### `Y::Tiptap` (and `Y::ProseMirror`, its base)
 
 ```ruby
-prosemirror = Y::ProseMirror.new(doc)
-prosemirror.to_html            # the "default" fragment (Tiptap's default root)
-prosemirror.to_html("content") # or another XML root
+tiptap = Y::Tiptap.new(doc)
+tiptap.to_html            # the "default" fragment (Tiptap's default root)
+tiptap.to_html("content") # or another XML root
 ```
 
 The output matches Tiptap's own `getHTML()`, checked byte-for-byte in the tests
@@ -214,17 +237,30 @@ 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.
 
-#### `Y::Lexical`
+The support is layered like the Lexical side: `Y::ProseMirror` covers core
+ProseMirror natively — prosemirror-schema-basic plus the prosemirror-tables
+family — and Tiptap's extension nodes (task lists, mentions, the details
+family) are `Y::Tiptap`'s rule set (`Y::Tiptap::NODES`), built on the
+extension API below. Marks stay in the base: mark rendering (nesting order,
+`textStyle` CSS, `code` exclusivity) runs through native text-run machinery
+that node rules don't reach, so `Y::ProseMirror` renders Tiptap's mark set
+as-is and `rules.mark` overrides individual marks.
+
+#### `Y::Lexxy` (and `Y::Lexical`, its base)
 
 ```ruby
-lexical = Y::Lexical.new(doc)
-lexical.to_html            # the "root" fragment (Lexical's default root name)
-lexical.to_html("notepad") # or another XML root
+lexxy = Y::Lexxy.new(doc)
+lexxy.to_html            # the "root" fragment (Lexical's default root name)
+lexxy.to_html("notepad") # or another XML root
 ```
 
 The HTML is identical to what a `lexxy-editor` submits to Rails (its `value`).
 The tests check this byte-for-byte against a document captured from a real
-editor.
+editor. Stock Lexical has no canonical serializer — every editor configures
+its own — so the editor-specific class carries the editor's name, and
+`Y::Lexical` is the core-Lexical base: paragraphs, headings, quotes, code,
+lists, tables, links, and the full text-format model, for any other Lexical
+editor to extend with rules.
 
 It handles the whole Lexxy 0.9.x node set: paragraphs, headings, every text
 format and their combinations, links, the four list types and nesting,
@@ -233,8 +269,178 @@ header cells, image galleries, and ActionText attachments (uploads and
 mentions both emit `<action-text-attachment>` elements that ActionText can
 re-render).
 
-In both renderers an unknown node keeps its content — text falls back to a
-plain paragraph rather than disappearing.
+Internally that support is layered: `Y::Lexical` covers core Lexical
+structure natively, and everything Lexxy adds — its node types (attachments,
+galleries) and its decorations of core nodes (the table wrapper, header-cell
+styling, nested-list classes) — is `Y::Lexxy`'s rule set
+(`Y::Lexxy::NODES`), built on the extension API below. The gem's own Lexxy
+support is the API's first consumer: an app rule for one of those types
+simply replaces it.
+
+In both renderers an unknown node keeps its content — text and nested blocks
+fall back to readable markup rather than disappearing.
+
+#### Custom nodes and marks
+
+The built-in schemas are pinned to what Tiptap and Lexxy ship, but apps add
+their own node types. Both renderers take rules for them. A rule is checked
+before the built-in schema, so it can add a node type or replace how a
+built-in renders.
+
+Rules register in a block — one `rules.node` call per type. A declarative
+rule is markup as data, rendered natively:
+
+```ruby
+tiptap = Y::Tiptap.new(doc) do |rules|
+  rules.node "callout", tag: "aside",
+                        attrs: { "class" => ["callout callout--", :kind] },
+                        contains: :blocks
+end
+```
+
+`tag` names the element. `attrs` values are templates: a string is a literal,
+a symbol reads that attribute off the node, an array concatenates both kinds;
+an attribute that resolves empty is left out. `text` (same template form)
+emits literal text content. `contains` declares what lives inside the node — `:inline` (formatted text,
+the default), `:blocks` (child block nodes — a container), or `:none` (a
+leaf). `void: true` skips the closing tag.
+
+You don't have to guess any of those names or shapes. Editors store types
+and attributes under names you'd never predict (Rhino's strike mark is
+`rhino-strike`; Lexical prefixes its own props `__`), so ask a real
+document instead — make one in your editor using your custom node, then:
+
+```ruby
+Y::Tiptap.new(doc).node_types
+# => { "callout"   => { "count" => 2, "attrs" => ["kind"],
+#                       "children" => ["paragraph"], "text" => false,
+#                       "handled" => nil },
+#      "paragraph" => { ..., "handled" => "builtin" } }
+```
+
+`handled` nil marks the types that still need a rule; `attrs` are the stored
+names your templates and blocks will read; `children` plus `text` is how you
+pick `contains:` (child block types → `:blocks`; text → `:inline`).
+
+When markup-as-data isn't enough, give the node a block:
+
+```ruby
+lexical = Y::Lexical.new(doc) do |rules|
+  rules.node "video_embed" do |node|
+    src = ERB::Util.html_escape(node.attrs["__src"])
+    %(<video controls src="#{src}"></video>)
+  end
+end
+```
+
+The block gets the node's type, its stored attributes, `node.content` — the
+children, already rendered to HTML — and `node.child_types`, the node's
+element/block children by type, in document order. `child_types` answers the
+structural questions attributes can't: how many images a gallery holds, or
+whether a list item carries a nested list. Whatever the block returns is
+spliced into the output as-is: it's trusted HTML, so escape any values you
+interpolate. To set the content mode for a callback, give the node both —
+`rules.node "embed", contains: :blocks do |node| ... end`.
+
+Callbacks never run while the document is locked. The render finishes first
+(inside one read transaction, GVL released), then the blocks run and their
+output is spliced in — so a callback can safely read or even write the same
+doc. With no callback rules, `to_html` skips the splicing entirely.
+
+Blocks are the escape hatch for everything the declarative form can't say,
+and they're proven sufficient: `Y::Lexxy` and `Y::Tiptap` are themselves
+built on this API (`lib/y/lexxy.rb`, `lib/y/tiptap.rb`) — simple nodes as
+declarative hashes, everything with logic as plain methods mapped by node
+type (a `Method` responds to `call` like any lambda) — and the fixture tests
+hold their output byte-identical to a live editor's.
+
+The ProseMirror side also takes custom marks:
+
+```ruby
+tiptap = Y::Tiptap.new(doc) do |rules|
+  rules.mark "comment", tag: "span", attrs: { "data-comment-id" => :id }
+end
+```
+
+Symbol refs resolve against the mark's own attributes. A custom mark wraps
+outside every built-in mark; several on one run nest alphabetically. A rule
+for a built-in mark name (`"bold"`) replaces its built-in tag.
+
+##### Worked examples
+
+A video-embed node from an app's Tiptap extension — a type the pinned schema
+has never heard of:
+
+```ruby
+tiptap = Y::Tiptap.new(doc) do |rules|
+  rules.node "videoEmbed" do |node|
+    src   = ERB::Util.html_escape(node.attrs["src"])
+    title = ERB::Util.html_escape(node.attrs["title"] || "Video")
+    %(<figure class="video"><iframe src="#{src}" title="#{title}" allowfullscreen></iframe></figure>)
+  end
+end
+```
+
+Resolving mentions against the database. Blocks run after the document read
+has finished, so hitting ActiveRecord (or the doc itself) inside one is safe:
+
+```ruby
+tiptap = Y::Tiptap.new(doc) do |rules|
+  rules.node "mention" do |node|
+    user = User.find_by(id: node.attrs["id"])
+    next "<span>@unknown</span>" unless user
+
+    %(<a class="mention" href="/users/#{user.id}">@#{ERB::Util.html_escape(user.handle)}</a>)
+  end
+end
+```
+
+Overriding a shipped rule — rendering Lexxy uploads as real image markup
+instead of the `<action-text-attachment>` elements ActionText re-renders:
+
+```ruby
+lexxy = Y::Lexxy.new(doc) do |rules|
+  rules.node "action_text_attachment" do |node|
+    src     = ERB::Util.html_escape(node.attrs["src"])
+    alt     = ERB::Util.html_escape(node.attrs["altText"].to_s)
+    caption = node.attrs["caption"].to_s
+    html = %(<img src="#{src}" alt="#{alt}" loading="lazy">)
+    html += "<figcaption>#{ERB::Util.html_escape(caption)}</figcaption>" unless caption.empty?
+    "<figure>#{html}</figure>"
+  end
+end
+```
+
+Markup that depends on structure — `node.child_types` lists the node's
+element/block children in document order, so a layout container can size
+itself by its column count while the columns themselves stay declarative:
+
+```ruby
+tiptap = Y::Tiptap.new(doc) do |rules|
+  rules.node "columns", contains: :blocks do |node|
+    %(<div class="columns columns--#{node.child_types.length}">#{node.content}</div>)
+  end
+  rules.node "column", tag: "div", attrs: { "class" => "column" }, contains: :blocks
+end
+```
+
+Content-aware overrides — dropping the empty paragraphs an editor keeps
+around the cursor, since `node.content` arrives already rendered:
+
+```ruby
+lexical = Y::Lexical.new(doc) do |rules|
+  rules.node "paragraph" do |node|
+    node.content.empty? ? "" : "<p>#{node.content}</p>"
+  end
+end
+```
+
+For a larger reference, the gem's own editor schemas ship this way — see
+`Y::Lexxy::NODES` in `lib/y/lexxy.rb` (declarative hashes for the simple
+nodes, a plain method per node that needs logic — galleries, list items,
+header cells, both attachment types — mapped with `method(:name)`) and
+`Y::Tiptap::NODES` in `lib/y/tiptap.rb` (task lists, mentions, the details
+family).
 
 ### Protocol codec (module functions)
 

data/lib/y/lexxy.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Y
+  # The Lexxy renderer: Y::Lexical (core Lexical) plus the Lexxy-specific
+  # schema, applied beneath the app's rules — an app rule for one of these
+  # types simply replaces it. This is the byte-parity class: the fixture
+  # tests hold `Y::Lexxy.new(doc).to_html` identical to a live editor's own
+  # serialized value.
+  #
+  # The schema doubles as the reference for augmenting a renderer: simple
+  # nodes are declarative hashes, nodes with logic are plain methods mapped
+  # in NODES.
+  class Lexxy < Lexical
+    # A cursor-placement placeholder; empty ones export to nothing.
+    def self.provisional_paragraph(node)
+      node.content.empty? ? "" : "<p>#{node.content}</p>"
+    end
+
+    # Adjacent previewable images; the class carries the image count
+    # (ActionText's convention).
+    def self.gallery(node)
+      %(<div class="attachment-gallery attachment-gallery--#{node.child_types.length}">#{node.content}</div>)
+    end
+
+    # Lexxy wraps tables in a styled figure.
+    def self.table(node)
+      %(<figure class="lexxy-content__table-wrapper"><table><tbody>#{node.content}</tbody></table></figure>)
+    end
+
+    # Class + background match Lexxy's own header-cell export.
+    def self.table_cell(node)
+      header = node.attrs["__headerState"].is_a?(Numeric) && node.attrs["__headerState"].positive?
+      return "<td>#{node.content}</td>" unless header
+
+      style = %(style="background-color: rgb(242, 243, 245);")
+      %(<th class="lexxy-content__table-cell--header" #{style}>#{node.content}</th>)
+    end
+
+    # Attribute order follows Lexxy's export — checked items put aria-checked
+    # before value; items holding a nested list append the
+    # lexxy-nested-listitem class after value.
+    def self.list_item(node)
+      out = +"<li"
+      checked = node.attrs["__checked"]
+      out << %( aria-checked="#{checked}") unless checked.nil?
+      out << %( value="#{node.attrs["__value"] || 1}")
+      out << %( class="lexxy-nested-listitem") if node.child_types.include?("list")
+      "#{out}>#{node.content}</li>"
+    end
+
+    # An upload, in the exact shape ActionText round-trips: attribute order
+    # and presence mirror Lexxy's exportDOM (nulls omitted, `previewable`
+    # only when true, `presentation="gallery"` always).
+    def self.upload(node)
+      out = +"<action-text-attachment"
+      out << attachment_attr(node, "sgid", "sgid")
+      out << %( previewable="true") if node.attrs["previewable"] == true
+      [%w[url src], %w[alt altText], %w[caption caption],
+       %w[content-type contentType], %w[filename fileName],
+       %w[filesize fileSize], %w[width width], %w[height height]]
+        .each { |html_name, stored| out << attachment_attr(node, html_name, stored) }
+      %(#{out} presentation="gallery"></action-text-attachment>)
+    end
+
+    # A content attachment (mention, embed): `content` carries the escaped
+    # inner HTML; `plainText` is not exported.
+    def self.mention(node)
+      out = +"<action-text-attachment"
+      out << attachment_attr(node, "sgid", "sgid")
+      out << attachment_attr(node, "content", "innerHtml")
+      out << attachment_attr(node, "content-type", "contentType")
+      "#{out}></action-text-attachment>"
+    end
+
+    # A stored nil (unset) is skipped; a stored empty string still emits.
+    def self.attachment_attr(node, html_name, stored)
+      return "" if node.attrs[stored].nil?
+
+      %( #{html_name}="#{RenderRules.escape_attr(node.attrs[stored])}")
+    end
+
+    NODES = {
+      # Lexxy's replacement for Lexical's CodeNode.
+      "early_escape_code" => { tag: "pre", attrs: { "data-language" => :language } },
+      "horizontal_divider" => { tag: "hr", void: true },
+      "provisonal_paragraph" => method(:provisional_paragraph), # (sic: Lexxy's spelling)
+      "image_gallery" => method(:gallery),
+      "table" => { contains: :blocks, render: method(:table) },
+      "wrapped_table_node" => { contains: :blocks, render: method(:table) },
+      "tablecell" => { contains: :blocks, render: method(:table_cell) },
+      "listitem" => { contains: :blocks, render: method(:list_item) },
+      "action_text_attachment" => method(:upload),
+      "custom_action_text_attachment" => method(:mention)
+    }.freeze
+
+    def initialize(doc, nodes: {}, &)
+      super(doc, nodes: NODES.merge(nodes.transform_keys(&:to_s)), &)
+    end
+  end
+end

data/lib/y/rendering.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Y
+  # Custom render rules for Y::Lexical and Y::ProseMirror.
+  #
+  # Both renderers accept a `nodes:` hash mapping a node type (Lexical's
+  # `__type`, ProseMirror's node name) to a rule; Y::ProseMirror also accepts
+  # `marks:`. A rule is consulted before the built-in schema, so it can add a
+  # custom node or override a built-in one.
+  #
+  # The usual way in is the block form — one `rules.node` call per type,
+  # keyword options for markup-as-data, a Ruby block for logic (see Builder
+  # below). `contains:` says what's inside the node: :inline (formatted
+  # text, the default), :blocks (child block nodes), or :none (a leaf). The
+  # nodes:/marks: keywords take the same rules as plain hashes, for shipping
+  # rule sets as data.
+  #
+  # Two kinds of rule:
+  #
+  # - Declarative (keyword options / a Hash): markup as data, rendered
+  #   natively at full speed.
+  #     Y::ProseMirror.new(doc) do |rules|
+  #       rules.node "callout", tag: "aside",
+  #                             attrs: { "class" => ["callout callout--", :kind] },
+  #                             contains: :blocks
+  #     end
+  #   `tag` is the element; `attrs` values are templates — a String literal,
+  #   a Symbol referencing one of the node's stored attributes, or an Array
+  #   mixing both (an attribute that resolves empty is omitted); `text` is a
+  #   template for literal text content; `void: true` emits no closing tag;
+  #   `contains` declares what lives inside the node and renders there:
+  #   :inline (default) for formatted text, :blocks for child block nodes
+  #   (a container), :none for a leaf.
+  #
+  # - Callback (a block; in the hash form, a callable or `render:` plus
+  #   `contains`):
+  #     Y::Lexical.new(doc) do |rules|
+  #       rules.node "video_embed" do |node|
+  #         %(<video src="#{ERB::Util.html_escape(node.attrs["src"])}"></video>)
+  #       end
+  #     end
+  #   The block runs after the document read has finished (never while the
+  #   document is locked) and receives a RenderRules::Node with the node's
+  #   type, stored attributes, children already rendered to HTML, and
+  #   child_types (its element/block children by type). Its return value is
+  #   spliced in verbatim — it is trusted HTML, so escape any attribute
+  #   values you interpolate.
+  #
+  # Mark rules (ProseMirror only) are declarative: `tag` plus `attrs`
+  # templates whose Symbol refs resolve against the mark's own attributes. A
+  # custom mark wraps outside every built-in mark; several custom marks nest
+  # alphabetically. A rule for a built-in mark's stored name replaces its
+  # wrap (the markup changes, the semantics don't — an overridden code mark
+  # still excludes the other formatting).
+  module RenderRules
+    # What a callback receives. `attrs` keys are as stored (Lexical's own
+    # props keep their "__" prefix); `content` is the node's children,
+    # already rendered to an HTML string; `child_types` lists the node's
+    # element/block children by type, in document order — the structural
+    # facts attrs and content can't answer (a gallery's image count, whether
+    # a list item holds a nested list).
+    Node = Data.define(:type, :attrs, :content, :child_types)
+
+    module_function
+
+    # Compile the user-facing config into [rules_json, callbacks]. Structural
+    # validation happens in the native parser, which raises ArgumentError.
+    def compile(nodes, marks)
+      callbacks = {}
+      spec = {}
+      unless nodes.empty?
+        spec["nodes"] = nodes.to_h do |type, rule|
+          [type.to_s, compile_node(type.to_s, rule, callbacks)]
+        end
+      end
+      unless marks.empty?
+        spec["marks"] = marks.to_h do |name, rule|
+          [name.to_s, compile_mark(name.to_s, rule)]
+        end
+      end
+      [JSON.generate(spec), callbacks]
+    end
+
+    def compile_node(type, rule, callbacks)
+      if rule.respond_to?(:call)
+        callbacks[type] = rule
+        return { "callback" => true }
+      end
+      raise ArgumentError, "rule for #{type.inspect} must be a Hash or a callable" unless rule.is_a?(Hash)
+
+      if rule[:render]
+        callbacks[type] = rule[:render]
+        compiled = { "callback" => true }
+        compiled["content"] = rule[:contains].to_s if rule[:contains]
+        return compiled
+      end
+      compile_declarative_node(rule)
+    end
+
+    def compile_declarative_node(rule)
+      compiled = {}
+      compiled["tag"] = rule[:tag].to_s if rule[:tag]
+      compiled["void"] = true if rule[:void]
+      compiled["attrs"] = compile_attrs(rule[:attrs]) if rule[:attrs]
+      compiled["text"] = compile_parts(rule[:text]) if rule[:text]
+      compiled["content"] = rule[:contains].to_s if rule[:contains]
+      compiled
+    end
+
+    def compile_mark(name, rule)
+      raise ArgumentError, "mark rule for #{name.inspect} must be a Hash" unless rule.is_a?(Hash)
+
+      compiled = {}
+      compiled["tag"] = rule[:tag].to_s if rule[:tag]
+      compiled["attrs"] = compile_attrs(rule[:attrs]) if rule[:attrs]
+      compiled
+    end
+
+    def compile_attrs(attrs)
+      attrs.map { |name, template| [name.to_s, compile_parts(template)] }
+    end
+
+    # A template: String literal, Symbol attribute reference, or an Array of
+    # both.
+    def compile_parts(template)
+      Array(template).map do |part|
+        case part
+        when Symbol then { "ref" => part.to_s }
+        else { "lit" => part.to_s }
+        end
+      end
+    end
+
+    # The escaping the native renderers use, for blocks that build markup
+    # from stored values. Text content escapes `&`, `<`, `>` (quotes stay
+    # literal, matching the browser serializer); attribute values also
+    # escape `"`. Prefer these over ERB::Util.html_escape when byte parity
+    # with editor output matters — html_escape also rewrites apostrophes.
+    def escape_text(value)
+      value.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+    end
+
+    def escape_attr(value)
+      escape_text(value).gsub('"', "&quot;")
+    end
+
+    # Yielded by Y::Lexical.new / Y::ProseMirror.new: register rules one
+    # call per node type. Keyword options are the markup-as-data; a block is
+    # the logic; both together say what a callback node contains and how to
+    # render it:
+    #
+    #   Y::ProseMirror.new(doc) do |rules|
+    #     rules.node "callout", tag: "aside", contains: :blocks
+    #     rules.node "video" do |node|
+    #       %(<video src="#{RenderRules.escape_attr(node.attrs["src"])}"></video>)
+    #     end
+    #     rules.node "columns", contains: :blocks do |node|
+    #       %(<div class="cols--#{node.child_types.length}">#{node.content}</div>)
+    #     end
+    #     rules.mark "comment", tag: "span", attrs: { "data-comment-id" => :id }
+    #   end
+    #
+    # It compiles to the same rule hashes the nodes:/marks: keywords take, so
+    # both forms mean the same thing; the keywords remain the data form for
+    # shipping rule sets (Y::Lexxy::NODES is one).
+    class Builder
+      attr_reader :nodes, :marks
+
+      def initialize(marks_allowed:)
+        @nodes = {}
+        @marks = {}
+        @marks_allowed = marks_allowed
+      end
+
+      def node(type, **options, &block)
+        @nodes[type.to_s] =
+          if block && options.empty?
+            block
+          elsif block
+            options.merge(render: block)
+          else
+            options
+          end
+      end
+
+      def mark(name, **options)
+        raise ArgumentError, "marks are ProseMirror-only" unless @marks_allowed
+
+        @marks[name.to_s] = options
+      end
+    end
+
+    # Resolve callback segments depth-first, so a callback's `node.content`
+    # is finished HTML even when callback nodes nest.
+    def splice(segments, callbacks)
+      segments.map do |segment|
+        next segment if segment.is_a?(String)
+
+        type, attrs_json, content, child_types = segment
+        node = Node.new(type: type, attrs: JSON.parse(attrs_json),
+                        content: splice(content, callbacks),
+                        child_types: child_types)
+        callbacks.fetch(type).call(node).to_s
+      end.join
+    end
+  end
+
+  # Y::Lexical and Y::ProseMirror are plain Ruby facades over the native
+  # renderers (Y::NativeLexical / Y::NativeProseMirror, private constants):
+  # they compile the rules config, hold the callbacks, and splice deferred
+  # segments after a render. The native handle does everything else.
+  class Lexical
+    # `Y::Lexical.new(doc, nodes: { "type" => rule })` — see Y::RenderRules
+    # for the rule forms. This is core Lexical only: paragraphs, headings,
+    # quotes, code, lists, tables, links, text formatting. Editor-specific
+    # nodes arrive as rules — Y::Lexxy subclasses this with the Lexxy schema;
+    # a different Lexical editor brings its own rule set the same way.
+    def initialize(doc, nodes: {})
+      builder = RenderRules::Builder.new(marks_allowed: false)
+      yield builder if block_given?
+      nodes = nodes.transform_keys(&:to_s).merge(builder.nodes)
+      rules_json, @render_callbacks = RenderRules.compile(nodes, {})
+      @native = NativeLexical.new(doc, rules_json)
+    end
+
+    def to_html(root = nil)
+      result = root.nil? ? @native.to_html : @native.to_html(root)
+      return result unless result.is_a?(Array)
+
+      RenderRules.splice(result, @render_callbacks)
+    end
+
+    # What node types this document actually contains — the discovery aid
+    # for writing rules. Facts per type: "count", "attrs" (names as stored),
+    # "children" (child node types), "text" (whether it holds text runs),
+    # and "handled" ("builtin", "rule", or nil — nil marks the types you
+    # still need a rule for). Children plus text is how you pick contains:.
+    def node_types(root = nil)
+      json = root.nil? ? @native.node_types : @native.node_types(root)
+      json && JSON.parse(json)
+    end
+  end
+
+  class ProseMirror
+    # `Y::ProseMirror.new(doc, nodes: {...}, marks: {...})` — see
+    # Y::RenderRules for the rule forms. This is core ProseMirror only:
+    # prosemirror-schema-basic plus the prosemirror-tables family, and the
+    # full mark set (marks are native — see `rules.mark` for overrides).
+    # Editor-specific nodes arrive as rules — Y::Tiptap subclasses this with
+    # Tiptap's extension nodes; a different ProseMirror editor brings its
+    # own rule set the same way.
+    def initialize(doc, nodes: {}, marks: {})
+      builder = RenderRules::Builder.new(marks_allowed: true)
+      yield builder if block_given?
+      nodes = nodes.transform_keys(&:to_s).merge(builder.nodes)
+      marks = marks.transform_keys(&:to_s).merge(builder.marks)
+      rules_json, @render_callbacks = RenderRules.compile(nodes, marks)
+      @native = NativeProseMirror.new(doc, rules_json)
+    end
+
+    def to_html(root = nil)
+      result = root.nil? ? @native.to_html : @native.to_html(root)
+      return result unless result.is_a?(Array)
+
+      RenderRules.splice(result, @render_callbacks)
+    end
+
+    # What node types this document actually contains — the discovery aid
+    # for writing rules. Facts per type: "count", "attrs" (names as stored),
+    # "children" (child node types), "text" (whether it holds text runs),
+    # and "handled" ("builtin", "rule", or nil — nil marks the types you
+    # still need a rule for). Children plus text is how you pick contains:.
+    def node_types(root = nil)
+      json = root.nil? ? @native.node_types : @native.node_types(root)
+      json && JSON.parse(json)
+    end
+  end
+
+  private_constant :NativeLexical, :NativeProseMirror
+end

data/lib/y/tiptap.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Y
+  # The Tiptap renderer: Y::ProseMirror (core ProseMirror — schema-basic plus
+  # tables) plus Tiptap's extension nodes, applied beneath the app's rules —
+  # an app rule for one of these types simply replaces it. This is the
+  # byte-parity class: the fixture tests hold `Y::Tiptap.new(doc).to_html`
+  # identical to a live editor's own `getHTML()`.
+  #
+  # Tiptap's marks (underline, highlight, sub/superscript, textStyle) render
+  # natively in the base class — mark serialization is text-run machinery
+  # the rule system can't express.
+  class Tiptap < ProseMirror
+    # Tiptap's TaskItem markup: the data-checked flag (false when unset), a
+    # label wrapping the checkbox, and the item body in a div.
+    def self.task_item(node)
+      checked = node.attrs["checked"] == true
+      out = %(<li data-checked="#{checked}" data-type="taskItem">)
+      out << %(<label><input type="checkbox")
+      out << %( checked="checked") if checked
+      out << "><span></span></label><div>"
+      "#{out}#{node.content}</div></li>"
+    end
+
+    # Tiptap's Mention extension (no app-configured HTMLAttributes): data
+    # attributes when present, the suggestion char, and @label (falling back
+    # to @id) as the text.
+    def self.mention(node)
+      char = node.attrs["mentionSuggestionChar"] || "@"
+      out = +%(<span data-type="mention")
+      %w[id label].each do |key|
+        next if node.attrs[key].nil?
+
+        out << %( data-#{key}="#{RenderRules.escape_attr(node.attrs[key])}")
+      end
+      out << %( data-mention-suggestion-char="#{RenderRules.escape_attr(char)}">)
+      out << RenderRules.escape_text(char)
+      out << RenderRules.escape_text(node.attrs["label"] || node.attrs["id"] || "")
+      "#{out}</span>"
+    end
+
+    # The details family follows tiptap-php's renderHTML (the Tiptap
+    # extension is Pro-only, so there's no free getHTML() to capture
+    # against).
+    def self.details(node)
+      open = node.attrs["open"] == true ? %( open="open") : ""
+      "<details#{open}>#{node.content}</details>"
+    end
+
+    NODES = {
+      "taskList" => { tag: "ul", attrs: { "data-type" => "taskList" }, contains: :blocks },
+      "taskItem" => { contains: :blocks, render: method(:task_item) },
+      "mention" => method(:mention),
+      "details" => { contains: :blocks, render: method(:details) },
+      "detailsSummary" => { tag: "summary" },
+      "detailsContent" => { tag: "div", attrs: { "data-type" => "detailsContent" }, contains: :blocks }
+    }.freeze
+
+    def initialize(doc, nodes: {}, marks: {}, &)
+      super(doc, nodes: NODES.merge(nodes.transform_keys(&:to_s)), marks: marks, &)
+    end
+  end
+end

data/lib/y/version.rb

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

data/lib/y.rb

@@ -12,6 +12,10 @@ rescue LoadError
   require_relative "y/yrby"
 end
 
+require_relative "y/rendering"
+require_relative "y/lexxy"
+require_relative "y/tiptap"
+
 module Y
   # Doc, Error, and the protocol module functions are defined in the Rust
   # extension. The ActionCable integration (Y::ActionCable::Sync) lives in the

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yrby
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: x86_64-linux
 authors:
 - JP Camara
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-09 00:00:00.000000000 Z
+date: 2026-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -68,6 +68,9 @@ files:
 - lib/y.rb
 - lib/y/3.4/yrby.so
 - lib/y/4.0/yrby.so
+- lib/y/lexxy.rb
+- lib/y/rendering.rb
+- lib/y/tiptap.rb
 - lib/y/version.rb
 - lib/yrby.rb
 homepage: https://github.com/jpcamara/yrby