yrby 0.6.0-aarch64-linux → 0.6.1-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8ac7194fe7f383fbea760aae137ae6848f6291687eff4a334dc318d1600f467
-  data.tar.gz: 98197e70d3928419eac8a590b50bff1a336ae53c62f2eda17d2b9147e1280cb0
+  metadata.gz: b673ec3d72751c36ecb0b8edc586c15f393e1136d5a1589f52bc3199bc872030
+  data.tar.gz: 1ff196e6cedb72da559c3c61a20cd54254c43ef08203a4d476819caf46af5384
 SHA512:
-  metadata.gz: 9aa048cce5443d92b7192174da78525019535142323033b85ffe6788258097a9ccbca492c567d8b456491a130f067605b521e83b3b3f1e7858785d268b7158af
-  data.tar.gz: fbaa5ffe1493344b10c012d9ec4284f85dc9734a7386a438ae40672733c48f0082d3c9d0d5e1556881597f08e10add4e360ffc40700c6864789320c4c22e5f28
+  metadata.gz: 81949023eb7db2147856515dadb883919a95fac2bb85bd3bc774ba64b37e1065cea942608a554f4a390cbb700a2df2992a378d98a039147329e6f58c1232201c
+  data.tar.gz: 5055fb7f8f94d381cb7ad1a12ed204059064a6dbced1ce1693e574491feb1a66d1a1fc124ca01b890af14f04a01ed04a35c5e0dedb03ab073c2c165da9697d5a

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/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/lib/generators/yrby/install/install_generator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "generators/yrby/tables/tables_generator"
+
+module Yrby
+  module Generators
+    # `bin/rails generate yrby:install` — a DocumentChannel speaking the
+    # y-websocket protocol over the gem's document storage, plus the storage
+    # migration (via yrby:tables). The models ship in the gem; only the
+    # migration lands in the app.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_channel
+        template "document_channel.rb", "app/channels/document_channel.rb"
+      end
+
+      def create_tables
+        invoke "yrby:tables"
+      end
+
+      def show_next_steps
+        say <<~NEXT
+
+          Next steps:
+
+            1. Authorize document access: implement `authorized?` in
+               app/channels/document_channel.rb (it denies everyone until you do).
+            2. bin/rails db:migrate
+            3. Install the yrby-client npm package and connect an editor:
+
+                 import { ActionCableProvider } from "yrby-client"
+                 const provider = new ActionCableProvider(doc, consumer,
+                   "DocumentChannel", { id: documentId })
+                 provider.connect()
+
+          The README's Editors section links working integrations for
+          Tiptap, Lexxy, Rhino Editor, and CodeMirror.
+        NEXT
+      end
+    end
+  end
+end

data/lib/generators/yrby/install/templates/document_channel.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Collaborative documents over Action Cable: one channel speaking the
+# y-websocket protocol (sync plus presence). Storage is Y::Document +
+# Y::DocumentUpdate; a document is created on its first change and its
+# history goes with it when it is destroyed. Point on_load/on_change
+# elsewhere to swap storage.
+class DocumentChannel < ApplicationCable::Channel
+  include Y::ActionCable
+
+  # Rebuild a document from durable storage (nil means a brand-new document).
+  on_load { |key| Y::Document.load_state(key) }
+
+  # Record each CRDT delta durably. Runs before the change is acknowledged
+  # or broadcast; if this raises, the change is neither acked nor relayed,
+  # and yrby-client retries it.
+  on_change { |key, update| Y::Document.append(key, update) }
+
+  def subscribed
+    return reject unless authorized?(params[:id])
+
+    sync_subscribed(params[:id])
+  end
+
+  def receive(data) = sync_receive(data, params[:id])
+
+  private
+
+  # Everyone is denied until you fill this in. Wire it to your app's auth:
+  # identify current_user on the cable connection, then check they may read
+  # and write this document. Don't lean on on_change raising for access
+  # control — that path exists for store failures.
+  def authorized?(_document_key)
+    false
+  end
+end

data/lib/generators/yrby/tables/tables_generator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Yrby
+  module Generators
+    # `bin/rails generate yrby:tables` — the migration for the gem-owned
+    # document models (Y::Document + Y::DocumentUpdate). Invoked by
+    # yrby:install, and by other gems building on the same storage.
+    #
+    # Template notes (kept here, not in the emitted migration): state is
+    # 4.gigabytes - 1 (longblob on MySQL — a compacted snapshot is the whole
+    # document; a 16 MB cap would break compaction) and payload is
+    # 16.megabytes - 1 (one update can carry a big paste or a client's
+    # accumulated offline edits — the 64 KB default blob is too small).
+    # The partial unique index's WHERE only keeps
+    # key-only rows out of the index: uniqueness holds without it, since
+    # unique indexes treat NULLs as distinct on every supported database,
+    # and MySQL drops the predicate harmlessly. y_document_updates indexes
+    # (document_id, pending) instead of bare document_id: the prefix
+    # serves the tail and foreign-key lookups, and the pair serves the
+    # clean-row count every append runs.
+    class TablesGenerator < ::Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def create_migration_file
+        migration_template "create_y_tables.rb",
+                           File.join(db_migrate_path, "create_y_tables.rb")
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/yrby/tables/templates/create_y_tables.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class CreateYTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :y_documents do |t|
+      t.string :key, null: false, index: { unique: true }
+      t.references :record, polymorphic: true, null: true, index: false
+      t.string :name
+      t.binary :state, limit: 4.gigabytes - 1
+      t.timestamps
+      t.index %i[record_type record_id name], unique: true,
+              where: "record_type IS NOT NULL",
+              name: "index_y_documents_on_record_and_name"
+    end
+
+    create_table :y_document_updates do |t|
+      t.references :document, null: false, foreign_key: { to_table: :y_documents }, index: false
+      t.binary :payload, null: false, limit: 16.megabytes - 1
+      t.boolean :pending, null: false, default: false
+      t.datetime :created_at, null: false
+      t.index %i[document_id pending]
+    end
+  end
+end

data/lib/y/lexxy.rb

@@ -52,24 +52,44 @@ module Y
     # and presence mirror Lexxy's exportDOM (nulls omitted, `previewable`
     # only when true, `presentation="gallery"` always).
     def self.upload(node)
-      out = +"<action-text-attachment"
+      tag = attachment_tag(node)
+      out = "<#{tag}"
       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>)
+      %(#{out} presentation="gallery"></#{tag}>)
     end
 
     # A content attachment (mention, embed): `content` carries the escaped
     # inner HTML; `plainText` is not exported.
     def self.mention(node)
-      out = +"<action-text-attachment"
+      tag = attachment_tag(node)
+      out = "<#{tag}"
       out << attachment_attr(node, "sgid", "sgid")
       out << attachment_attr(node, "content", "innerHtml")
       out << attachment_attr(node, "content-type", "contentType")
-      "#{out}></action-text-attachment>"
+      "#{out}></#{tag}>"
+    end
+
+    # Lexxy's attachment tag is configurable (`Lexxy.configure`'s
+    # attachmentTagName, paired with ActionText::Attachment.tag_name on the
+    # Rails side), and each attachment node stores the tag it was created
+    # with. Emit the stored tag. The value is stored document data, not
+    # markup, so anything that doesn't look like a tag name falls back to
+    # ActionText's default.
+    def self.attachment_tag(node)
+      tag = node.attrs["tagName"].to_s
+      tag.match?(/\A[a-zA-Z][a-zA-Z0-9-]*\z/) ? tag : "action-text-attachment"
+    end
+
+    # An in-flight upload placeholder. Only the uploader's browser can
+    # complete it, so it is never finished content -- materialized output
+    # (Action Text bodies, search text) must not carry it.
+    def self.pending_upload(_node)
+      ""
     end
 
     # A stored nil (unset) is skipped; a stored empty string still emits.
@@ -90,6 +110,7 @@ module Y
       "tablecell" => { contains: :blocks, render: method(:table_cell) },
       "listitem" => { contains: :blocks, render: method(:list_item) },
       "action_text_attachment" => method(:upload),
+      "action_text_attachment_upload" => method(:pending_upload),
       "custom_action_text_attachment" => method(:mention)
     }.freeze
 

data/lib/y/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yrby
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: aarch64-linux
 authors:
 - JP Camara
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-12 00:00:00.000000000 Z
+date: 2026-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -55,7 +55,7 @@ dependencies:
 description: 'yrby is a thread-safe Ruby binding over the Rust y-crdt (yrs) library:
   CRDT documents, awareness/presence, and the y-websocket sync protocol primitives,
   with the GVL released during native work so documents sync in parallel. The ActionCable/Rails
-  integration lives in the companion yrby-actioncable gem.'
+  integration lives in the companion yrby-rails gem.'
 email:
 - johnpcamara@gmail.com
 executables: []
@@ -65,6 +65,10 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- lib/generators/yrby/install/install_generator.rb
+- lib/generators/yrby/install/templates/document_channel.rb
+- lib/generators/yrby/tables/tables_generator.rb
+- lib/generators/yrby/tables/templates/create_y_tables.rb
 - lib/y.rb
 - lib/y/3.4/yrby.so
 - lib/y/4.0/yrby.so