yrby 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93704595e7dd617d4eccd0645a3dbc99bc798e11ec2591c86f47f0da08381d2c
-  data.tar.gz: 3f4fb67f5fc0368fe31a74cdae2104b9cea8bc44e349b398efc20f84fca7061a
+  metadata.gz: ba28bef094ec97908a5ce4b01a61aedbbbcd49585c88a47acfbcfe0dab02c5be
+  data.tar.gz: dae39a894e92836681c0aa73dc54201aecf1d3fa68eaac38496e420579d760b3
 SHA512:
-  metadata.gz: fbe8957a8298efdb2991fa2de86a184e3395cb4315f7e467c2ee1dc1c37e750404468e9a2e71bf55967a44ca281424e4310fc4d985503171ca50a10bb3341e90
-  data.tar.gz: a29fd67645ef0b5312e34213eaf13c42e0eb8628a4e1da1d6af08ff6a68b77673f0f6e32c74f52da5797a3b802573ca78559e4a94a0c36da5b22331102a0ade6
+  metadata.gz: de4dedd7b4eb4e14e343b83b20007587cd129cbc0f42ff03f21118043ebced3853b9a2e2c51e77688ba1b8665e058422e24d1cc18d7acfd85fd6c99e435b43b9
+  data.tar.gz: 93291be948f34edc50c98266e554bd41a2beb7f8e74b1aeab87b19dc41efed425603f0634cefd117f24077b7d4fecf967b3ff4e40614b2276f2ccb40e85b5dc6

data/CHANGELOG.md

@@ -4,6 +4,18 @@ 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).
 
+## [0.6.1] - 2026-08-04
+
+### Fixed
+
+- `Y::Lexxy` emits the attachment tag the node was created with instead of
+  a hardcoded `<action-text-attachment>`. Lexxy makes the tag configurable
+  (`Lexxy.configure`'s `attachmentTagName`, paired with
+  `ActionText::Attachment.tag_name` in Rails), and each attachment node
+  stores its tag, so a custom-tag app's rendered HTML now matches its
+  editor. A stored value that doesn't look like a tag name falls back to
+  the default; documents from before the tag was stored render unchanged.
+
 ## [0.6.0] - 2026-07-11
 
 ### Added

data/Cargo.lock

@@ -617,6 +617,9 @@ dependencies = [
  "rb-sys-env 0.1.2",
  "serde_json",
  "yrs",
+ "yrs-html-core",
+ "yrs-lexical-html",
+ "yrs-prosemirror-html",
 ]
 
 [[package]]
@@ -637,6 +640,32 @@ dependencies = [
  "thiserror",
 ]
 
+[[package]]
+name = "yrs-html-core"
+version = "0.1.0"
+dependencies = [
+ "serde_json",
+ "yrs",
+]
+
+[[package]]
+name = "yrs-lexical-html"
+version = "0.1.0"
+dependencies = [
+ "serde_json",
+ "yrs",
+ "yrs-html-core",
+]
+
+[[package]]
+name = "yrs-prosemirror-html"
+version = "0.1.0"
+dependencies = [
+ "serde_json",
+ "yrs",
+ "yrs-html-core",
+]
+
 [[package]]
 name = "zmij"
 version = "1.0.14"

data/README.md

@@ -5,14 +5,16 @@
 Collaborative editing for Rails, backed by [y-crdt](https://github.com/y-crdt/y-crdt)
 (the Rust library behind Y.js). Your Rails server speaks the y-websocket sync
 protocol directly, so there's no separate Node process hosting the Y.js
-documents.
+documents. Pronounced "yer-bee".
+
+![Two people typing on separate lines of the same document, each keystroke synced through a Rails server, seen from a third browser with labeled carets](docs/images/collab.gif)
 
 ```ruby
 class DocumentChannel < ApplicationCable::Channel
-  include Y::ActionCable::Sync
+  include Y::ActionCable
 
-  on_load   { |key|         MyStore.load(key) }
-  on_change { |key, update| MyStore.append(key, update) }
+  on_load   { |key|         Y::Document.load_state(key) }
+  on_change { |key, update| Y::Document.append(key, update) }
 
   def subscribed    = sync_subscribed(params[:id])
   def receive(data) = sync_receive(data, params[:id])
@@ -59,7 +61,7 @@ and `Doc#read_map` reconstruct it server-side, in Ruby.
 The surface is intentionally small, but the focus is durability, resiliency, delivery
 guarantees, correctness, and thread safety.
 
-Towards that goal, `yrby` adds capabilities that stand out even in the Yjs ecosystem:
+Towards that goal, `yrby` adds opinionated defaults on top of normal Yjs syncing:
 
 - Built-in update acknowledgement: the `ActionCableProvider` in `yrby-client` will continue to
   send updates until an ack is received from the server. [`yrby-actioncable`](https://rubygems.org/gems/yrby-actioncable)
@@ -101,8 +103,9 @@ Issues and PRs are welcome.
 # Core CRDT + protocol primitives:
 gem "yrby"
 
-# For the Rails/ActionCable server concern (Y::ActionCable::Sync):
-gem "yrby-actioncable"
+# For the Rails side (the sync channel, document models, the generator).
+# Formerly yrby-actioncable; that name stops at 0.3.1.
+gem "yrby-rails"
 ```
 
 Requires Ruby 3.4 or newer. The release workflow builds precompiled gems for
@@ -457,25 +460,72 @@ Y.wrap_update(update_bytes)   # => wrap a raw doc update as a sync Update frame
 
 ### ActionCable Integration
 
-`Y::ActionCable::Sync` (from the `yrby-actioncable` gem) is a channel
-concern that implements the full y-websocket protocol (document sync +
-awareness/presence) over ActionCable:
+In a Rails app, one generator creates the channel and the migration:
+
+```bash
+bin/rails generate yrby:install
+bin/rails db:migrate
+```
+
+The models ship in the gem, the way Action Text owns
+`ActionText::RichText`:
+
+- **`Y::Document`** — one row per document, addressed two ways: by `key`
+  (what a channel addresses — one opaque, unique string, sometimes
+  app-supplied, never parsed) and, optionally, by polymorphic `record` +
+  `name` (which model attribute it backs; `name` is the attribute name,
+  `"body"` — one document per attribute per record, the
+  ActionText::RichText scheme). Key-only documents leave the binding nil.
+  Either side can arrive first: `Y::Document.for(record, name)` finds or
+  creates the binding, derives a readable key (`post/1/body`), and adopts
+  a key-only row already holding that key, so a channel writing first and
+  a binding created later converge on one document. The row also holds
+  the merged `state` snapshot — CRDT state only; derived data (rendered
+  HTML, search text) is the application's job, typically in the channel's
+  on_change. `.load_state(key)` / `.append(key, update)` are the store
+  calls the generated channel uses.
+- **`Y::DocumentUpdate`** — the uncompacted tail: one delta per row,
+  compacted into `state` and deleted once the tail reaches `compact_every`
+  (default 64). Loading reads the snapshot plus the current tail; an
+  empty tail returns `state` directly. Compaction serializes on a
+  per-document row lock and skips causally-gapped rows — they're
+  quarantined until they heal rather than compacted into state or
+  deleted. Destroying a document deletes its updates with it.
+
+The migration creates `y_documents` and `y_document_updates`. To rename
+them, edit the generated migration and point `Y::Document.table_name` /
+`Y::DocumentUpdate.table_name` at the new names in an initializer.
+
+Storage is swappable: the channel only needs `on_load` and `on_change`
+answered, and they can point at anything.
+
+`include Y::ActionCable` (from the `yrby-rails` gem) is the channel
+integration: the y-websocket protocol (document sync +
+awareness/presence) over ActionCable. (`include Y::ActionCable::Sync`
+keeps working and has the same effect.)
 
 ```ruby
 # app/channels/document_channel.rb
 class DocumentChannel < ApplicationCable::Channel
-  include Y::ActionCable::Sync
+  include Y::ActionCable
 
-  on_load { |key| MyStore.load(key) }                 # source of truth
-  on_change { |key, update| MyStore.append(key, update) } # durable record
+  on_load { |key| Y::Document.load_state(key) }          # rebuild from storage
+  on_change { |key, update| Y::Document.append(key, update) } # record, then broadcast
 
   def subscribed
+    return reject unless authorized?(params[:id])
+
     sync_subscribed params[:id]
   end
 
   def receive(data)
     sync_receive(data, params[:id])
   end
+
+  private
+
+  # Everyone is denied until you wire this to your app's auth.
+  def authorized?(_document_key) = false
 end
 ```
 
@@ -571,7 +621,7 @@ It is up to you to durably record it:
 
 ```ruby
 class DocumentChannel < ApplicationCable::Channel
-  include Y::ActionCable::Sync
+  include Y::ActionCable
 
   # ...
 

data/ext/yrby/Cargo.toml

@@ -14,6 +14,9 @@ magnus = "0.8"
 rb-sys = "0.9"
 yrs = { version = "0.27", features = ["sync"] }
 serde_json = "1.0"
+yrs-html-core = { path = "crates/html-core" }
+yrs-lexical-html = { path = "crates/lexical-html" }
+yrs-prosemirror-html = { path = "crates/prosemirror-html" }
 
 [dev-dependencies]
 rb-sys-env = "0.1"

data/ext/yrby/crates/html-core/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "yrs-html-core"
+description = "Internal core for the yrs-*-html renderer crates; depend on those instead"
+repository = "https://github.com/jpcamara/yrby"
+readme = "README.md"
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.85"
+authors = ["JP Camara <johnpcamara@gmail.com>"]
+license = "MIT"
+publish = false
+
+[dependencies]
+yrs = { version = "0.27", features = ["sync"] }
+serde_json = "1.0"

data/ext/yrby/{src/render_rules.rs → crates/html-core/src/lib.rs}

@@ -45,6 +45,12 @@ pub struct Emitter {
     frames: Vec<Vec<Segment>>,
 }
 
+impl Default for Emitter {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
 impl Emitter {
     pub fn new() -> Self {
         Emitter {

data/ext/yrby/crates/lexical-html/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "yrs-lexical-html"
+description = "Render Lexical-shaped yrs documents to HTML, no browser or Node required"
+repository = "https://github.com/jpcamara/yrby"
+readme = "README.md"
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.85"
+authors = ["JP Camara <johnpcamara@gmail.com>"]
+license = "MIT"
+publish = false
+
+[dependencies]
+yrs = { version = "0.27", features = ["sync"] }
+serde_json = "1.0"
+yrs-html-core = { path = "../html-core" }

data/ext/yrby/{src/lexical_html.rs → crates/lexical-html/src/lib.rs}

@@ -39,15 +39,19 @@
 //! with the unwrapped span. Case-transform format bits are never rendered
 //! (their text-transform style is outside the sanitize whitelist).
 //!
-//! Custom nodes: rules are registered by `__type` (see `render_rules`) and
+//! Custom nodes: rules are registered by `__type` (see `yrs-html-core`) and
 //! consulted before the built-in arms, so they extend the schema or override
 //! a built-in. Declarative rules render here; callback rules emit
 //! `Segment::Deferred` for the caller to fill in after the render.
 
-use crate::render_rules::{
-    resolve_parts, xml_attrs_json, xml_ref_attr, Content, Emitter, NodeRule, Rules, Segment,
-    TypeMap,
-};
+// README examples are living code: compile-checked on every cargo test.
+#[cfg(doctest)]
+#[doc = include_str!("../README.md")]
+mod readme_examples {}
+
+// The full rules surface, re-exported: depend on this crate alone;
+// yrs-html-core is an internal implementation crate.
+pub use yrs_html_core::*;
 use yrs::types::text::YChange;
 use yrs::{
     Any, GetString, Map, Out, ReadTxn, Text, Xml, XmlElementRef, XmlFragment, XmlFragmentRef,
@@ -121,12 +125,12 @@ pub fn render_segments<T: ReadTxn>(
     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)]
+/// Rule-free rendering to a plain string — the simplest way to use this
+/// crate standalone, and the fixture-parity surface the tests pin. With no
+/// callback rules, segments always flatten.
 pub fn render<T: ReadTxn>(txn: &T, fragment: &XmlFragmentRef) -> Option<String> {
     render_segments(txn, fragment, &Rules::empty()).map(|segs| {
-        crate::render_rules::flatten(segs)
+        yrs_html_core::flatten(segs)
             .into_html()
             .expect("no callback rules registered")
     })
@@ -1297,7 +1301,7 @@ mod tests {
         let txn = doc.transact();
         let frag = txn.get_xml_fragment("root").unwrap();
         let segs = render_segments(&txn, &frag, &rules).unwrap();
-        let html = crate::render_rules::flatten(segs).into_html().unwrap();
+        let html = yrs_html_core::flatten(segs).into_html().unwrap();
         assert_eq!(
             html,
             "<p><a class=\"app-link\" href=\"https://x.example\">site</a>\

data/ext/yrby/crates/prosemirror-html/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "yrs-prosemirror-html"
+description = "Render ProseMirror-shaped yrs documents to HTML, no browser or Node required"
+repository = "https://github.com/jpcamara/yrby"
+readme = "README.md"
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.85"
+authors = ["JP Camara <johnpcamara@gmail.com>"]
+license = "MIT"
+publish = false
+
+[dependencies]
+yrs = { version = "0.27", features = ["sync"] }
+serde_json = "1.0"
+yrs-html-core = { path = "../html-core" }

data/ext/yrby/{src/prosemirror_html.rs → crates/prosemirror-html/src/lib.rs}

@@ -36,10 +36,14 @@
 //! 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,
-};
+// README examples are living code: compile-checked on every cargo test.
+#[cfg(doctest)]
+#[doc = include_str!("../README.md")]
+mod readme_examples {}
+
+// The full rules surface, re-exported: depend on this crate alone;
+// yrs-html-core is an internal implementation crate.
+pub use yrs_html_core::*;
 use yrs::types::text::YChange;
 use yrs::types::Attrs;
 use yrs::{
@@ -96,12 +100,12 @@ pub fn render_segments<T: ReadTxn>(
     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)]
+/// Rule-free rendering to a plain string — the simplest way to use this
+/// crate standalone, and the fixture-parity surface the tests pin. With no
+/// callback rules, segments always flatten.
 pub fn render<T: ReadTxn>(txn: &T, fragment: &XmlFragmentRef) -> Option<String> {
     render_segments(txn, fragment, &Rules::empty()).map(|segs| {
-        crate::render_rules::flatten(segs)
+        yrs_html_core::flatten(segs)
             .into_html()
             .expect("no callback rules registered")
     })
@@ -1232,7 +1236,7 @@ mod tests {
         let txn = doc.transact();
         let segs = render_segments(&txn, &frag, &rules).unwrap();
         assert_eq!(
-            crate::render_rules::flatten(segs).into_html().unwrap(),
+            yrs_html_core::flatten(segs).into_html().unwrap(),
             "<aside class=\"callout callout--warning\"><div class=\"para\">careful</div></aside>"
         );
     }
@@ -1290,7 +1294,7 @@ mod tests {
         }
         let txn = doc.transact();
         let map = collect_node_types(&txn, &frag).unwrap();
-        let json = crate::render_rules::type_map_json(&map, |ty| {
+        let json = yrs_html_core::type_map_json(&map, |ty| {
             if is_builtin(ty) {
                 Some("builtin")
             } else {

data/ext/yrby/src/lib.rs

@@ -7,16 +7,16 @@ use yrs::updates::decoder::Decode;
 use yrs::updates::encoder::Encode;
 use yrs::{Doc, GetString, ReadTxn, Transact};
 
-mod lexical_html;
-mod prosemirror_html;
 mod protocol;
 mod read;
-mod render_rules;
 use protocol::{
     classify_message, has_pending, integrated_update, merged_doc_update, update_advances_doc,
     update_is_ready,
 };
 use render_rules::{Rules, Segment};
+pub(crate) use yrs_html_core as render_rules;
+use yrs_lexical_html as lexical_html;
+use yrs_prosemirror_html as prosemirror_html;
 
 /// Wrapper around yrs Doc.
 ///

data/ext/yrby/src/read.rs

@@ -352,7 +352,7 @@ mod tests {
         // lexxy-realtime's test server and saving GET /content/:room.
         use yrs::updates::decoder::Decode;
         use yrs::Update;
-        let bytes = include_bytes!("fixtures/lexical_linebreak.bin");
+        let bytes = include_bytes!("../crates/lexical-html/src/fixtures/lexical_linebreak.bin");
         let doc = Doc::new();
         doc.transact_mut()
             .apply_update(Update::decode_v1(bytes).unwrap())
@@ -369,7 +369,7 @@ mod tests {
         // upload's caption as its own line — while the divider stays silent.
         use yrs::updates::decoder::Decode;
         use yrs::{Transact, Update};
-        let bytes = include_bytes!("fixtures/lexxy_full.bin");
+        let bytes = include_bytes!("../crates/lexical-html/src/fixtures/lexxy_full.bin");
         let doc = Doc::new();
         doc.transact_mut()
             .apply_update(Update::decode_v1(bytes).unwrap())
@@ -408,7 +408,7 @@ mod tests {
         // must come through (get_string alone dropped all the nested ones).
         use yrs::updates::decoder::Decode;
         use yrs::{Transact, Update};
-        let bytes = include_bytes!("fixtures/lexical_rich.bin");
+        let bytes = include_bytes!("../crates/lexical-html/src/fixtures/lexical_rich.bin");
         let doc = Doc::new();
         {
             let mut txn = doc.transact_mut();