yrby 0.7.1-aarch64-linux → 0.8.1-aarch64-linux

data/lib/generators/yrby/install/install_generator.rb

@@ -5,15 +5,16 @@ 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.
+    # `bin/rails generate yrby:install` runs yrby:tables to create the storage
+    # migration. The models and Y::DocumentChannel ship in the gem, so that is
+    # the only file it generates by default. Pass --channel to also generate
+    # an application channel for custom authorization or room-keyed documents.
     class InstallGenerator < ::Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
+      class_option :channel, type: :boolean, default: false, desc: "Generate a custom DocumentChannel"
 
       def create_channel
-        template "document_channel.rb", "app/channels/document_channel.rb"
+        template "document_channel.rb", "app/channels/document_channel.rb" if options[:channel]
       end
 
       def create_tables
@@ -25,15 +26,25 @@ module Yrby
 
           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:
+            1. bin/rails db:migrate
+            2. Render a collaborative document on a page where the user may
+               edit the record:
 
-                 import { ActionCableProvider } from "yrby-client"
-                 const provider = new ActionCableProvider(doc, consumer,
-                   "DocumentChannel", { id: documentId })
-                 provider.connect()
+                 <%= collaborative_document_tag @post, :body %>
+
+            3. Install the yrby-client npm package. The tag renders an
+               element that connects automatically. Once it syncs, your code
+               gets the document and can bind it to any Yjs editor:
+
+                 import "yrby-client/element"
+
+                 document.addEventListener("yrby:synced", ({ target, detail }) => {
+                   const editor = bindYourEditor(target, detail.doc, detail.provider)
+                   detail.signal.addEventListener("abort", () => editor.destroy(), { once: true })
+                 })
+
+          Run with --channel to also generate app/channels/document_channel.rb,
+          and implement its authorized? method before you use it.
 
           The README's Editors section links working integrations for
           Tiptap, Lexxy, Rhino Editor, and CodeMirror.

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

@@ -16,11 +16,7 @@ class DocumentChannel < ApplicationCable::Channel
   # 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 subscribed = sync_subscribed(params[:id])
 
   def receive(data) = sync_receive(data, params[:id])
 
@@ -28,8 +24,9 @@ class DocumentChannel < ApplicationCable::Channel
 
   # 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.
+  # and write this document. This runs once when the client subscribes, and
+  # the subscription stays authorized until it ends. Raising in on_change is
+  # for store failures, so don't use it for access control.
   def authorized?(_document_key)
     false
   end

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

@@ -10,10 +10,13 @@ module Yrby
     # 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).
+    # 1.gigabyte - 1: the largest limit every adapter accepts. MySQL maps
+    # anything over 16 MB to longblob (a compacted snapshot is the whole
+    # document; a 16 MB cap would break compaction); Postgres raises above
+    # 1 GB - 1 and ignores the limit on bytea otherwise; SQLite ignores
+    # limits. 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,

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

@@ -6,7 +6,7 @@ class CreateYTables < ActiveRecord::Migration<%= migration_version %>
       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.binary :state, limit: 1.gigabyte - 1
       t.timestamps
       t.index %i[record_type record_id name], unique: true,
               where: "record_type IS NOT NULL",

data/lib/y/collaborative/attribute.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Y
+  module Collaborative
+    # The collaborative document for one attribute of one record, such as a
+    # post's body. Ruby code and the shipped channel both use it, so they read
+    # and write the same rows.
+    class Attribute
+      attr_reader :record, :name
+
+      def initialize(record, name)
+        raise ArgumentError, "collaboration requires a persisted record" unless record.persisted?
+
+        @record = record
+        @name = name.to_s.dup.freeze
+      end
+
+      # The document as update bytes, or nil before the first write.
+      def load_state = existing_row&.load_state
+
+      # Records one change and returns once it's saved. The channel waits for
+      # this to return before it acknowledges or broadcasts the change.
+      def append(update) = document_row.append(update)
+
+      # Builds a new Y::Doc from storage on every call.
+      def y_doc
+        Y::Doc.new.tap do |doc|
+          state = load_state
+          doc.apply_update(state) if state
+        end
+      end
+
+      # The key clients sync the document under, such as "post/1/body". If a
+      # key-only channel created the document before it was linked to a
+      # record, this returns that original key.
+      def key = existing_row&.key || Y::Document.key_for(record, name)
+
+      # Finds or creates the Y::Document or Y::EncryptedDocument row. Writes
+      # and maintenance work such as compaction go through it.
+      def document_row = document_class.for(record, name)
+
+      private
+
+      # Returns the row if it exists without creating one, so reading a
+      # document never adds a row. It selects only id and key because the
+      # row's load_state reads the snapshot itself, and loading the snapshot
+      # here too would fetch it twice.
+      def existing_row = document_class.select(:id, :key).find_by(record:, name:)
+
+      def document_class = record.class.collaborative_document_class(name)
+    end
+  end
+end

data/lib/y/collaborative/helper.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Y
+  module Collaborative
+    # The view side of a collaborative document. The engine includes it into
+    # Action View.
+    #
+    #   <%= collaborative_document_tag @post, :body %>
+    #
+    # renders the auto-connecting element:
+    #
+    #   <yrby-document grant="<signed sgid>" name="body"></yrby-document>
+    #
+    # Importing "yrby-client/element" registers the element. It subscribes to
+    # Y::DocumentChannel by itself and exposes the synced Y.Doc through its
+    # `doc` property and `yrby:synced` event, much like the element behind
+    # turbo_stream_from.
+    #
+    # The grant is a signed GlobalID scoped to this record and attribute
+    # (record.collaborative_sgid(name)). Only render the tag on pages where
+    # the user may edit the record, because by default anyone holding the
+    # grant can open the document. To also check the user's current
+    # permissions when they subscribe, use Y::DocumentChannel.authorize_document.
+    #
+    # Extra options pass through to the element and a block becomes its
+    # content, so the element can wrap the mount point an editor binds to:
+    #
+    #   <%= collaborative_document_tag @post, :body, id: "editor" %>
+    #
+    # expires_in: limits how long the grant lasts. refresh: is a URL the
+    # element fetches a new grant from when a subscription is rejected, so it
+    # can resubscribe without a page load. The app's action there re-runs its
+    # own authorization and renders { grant: record.collaborative_sgid(name) }:
+    #
+    #   <%= collaborative_document_tag @post, :body, expires_in: 10.minutes,
+    #                                  refresh: grant_post_path(@post) %>
+    module Helper
+      def collaborative_document_tag(record, name, expires_in: nil, refresh: nil, **, &)
+        grant = record.collaborative_sgid(name, **{ expires_in: expires_in }.compact)
+        attributes = { grant: grant, name: name }
+        attributes[:refresh] = refresh if refresh
+        # The helper's attributes go last because a later key wins in a keyword
+        # splat, so a template can't override the grant or the name.
+        tag.yrby_document(**, **attributes, &)
+      end
+    end
+  end
+end

data/lib/y/collaborative.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "global_id"
+
+module Y
+  # The signed token that connects a page to a channel for record-backed
+  # collaborative documents.
+  #
+  # The client never picks its own document. The server signs a token for the
+  # record and attribute, the page renders it, and the channel looks the
+  # record up from it. The token is a signed GlobalID scoped to one attribute.
+  #
+  #   # the view
+  #   tag.div data: { grant: post.collaborative_sgid(:body) }
+  #
+  #   # the channel
+  #   def authorized?(_key)
+  #     record.present? && record.editable_by?(current_user)
+  #   end
+  #
+  #   # Not memoized, because AnyCable gives each command a fresh channel
+  #   # instance and a cached record would go stale. Y::DocumentChannel
+  #   # does the same.
+  #   def record
+  #     Y::Collaborative.locate(params[:grant], :body)
+  #   end
+  #
+  # The engine includes this into ActiveRecord::Base so any channel's
+  # authorized? can use it. lexxy-realtime uses the same token flow.
+  module Collaborative
+    extend ActiveSupport::Concern
+
+    class << self
+      # The signed-GlobalID purpose for one collaborative attribute. A token
+      # signed for one attribute verifies only against that attribute's
+      # purpose, so it can't locate the record through any other attribute.
+      # The purpose leaves out the channel name, so a custom channel and the
+      # shipped one can both resolve the same tokens for an attribute.
+      def sgid_purpose(name) = "yrby/#{name}"
+
+      # Looks up the record for a token from `collaborative_sgid(name)`.
+      # Returns nil for an invalid, tampered, expired, or wrong-attribute
+      # token, and for a record that no longer exists.
+      def locate(sgid, name)
+        GlobalID::Locator.locate_signed(sgid, for: sgid_purpose(name))
+      rescue ActiveRecord::RecordNotFound
+        nil
+      end
+    end
+
+    included do
+      class_attribute :collaborative_document_options,
+                      instance_accessor: false, default: {}.freeze
+    end
+
+    class_methods do
+      # Declares how one attribute's document is stored. The shipped channel
+      # and Ruby reads both follow it, and undeclared attributes use plain
+      # Y::Document.
+      def has_collaborative_document(name, encrypted: false) # rubocop:disable Naming/PredicatePrefix
+        self.collaborative_document_options = collaborative_document_options.merge(
+          name.to_s => { encrypted: encrypted }.freeze
+        ).freeze
+      end
+
+      # Returns the model that stores this attribute's document,
+      # Y::EncryptedDocument for an attribute declared encrypted and
+      # Y::Document for the rest. It resolves the constant on every call so
+      # that declaring an attribute doesn't load the engine's models while the
+      # app's models are still loading.
+      def collaborative_document_class(name)
+        encrypted = collaborative_document_options.dig(name.to_s, :encrypted)
+        encrypted ? Y::EncryptedDocument : Y::Document
+      end
+    end
+
+    # Returns the document for one attribute, stored the way the model
+    # declared. It responds to load_state, append, y_doc, and key.
+    def collaborative_document(name)
+      Attribute.new(self, name)
+    end
+
+    # A signed token that a channel can pass to Y::Collaborative.locate to get
+    # this record back, for this attribute only. Pass expires_in: to limit how
+    # long the grant lasts. Without it GlobalID's own default applies, which is
+    # one month under Rails. We pass the option through only when it's given,
+    # because an explicit nil would mean "never expire".
+    def collaborative_sgid(name, expires_in: nil)
+      options = { for: Y::Collaborative.sgid_purpose(name) }
+      options[:expires_in] = expires_in if expires_in
+      to_sgid(**options).to_s
+    end
+  end
+end
+
+require "y/collaborative/attribute"
+require "y/collaborative/helper"

data/lib/y/lexxy.rb

@@ -2,7 +2,7 @@
 
 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
+  # 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.
@@ -36,14 +36,14 @@ module Y
       %(<th class="lexxy-content__table-cell--header" #{style}>#{node.content}</th>)
     end
 
-    # Attribute order follows Lexxy's export — checked items put aria-checked
+    # 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 << %( aria-checked="#{RenderRules.escape_attr(checked)}") unless checked.nil?
+      out << %( value="#{RenderRules.escape_attr(node.attrs["__value"] || 1)}")
       out << %( class="lexxy-nested-listitem") if node.child_types.include?("list")
       "#{out}>#{node.content}</li>"
     end

data/lib/y/rendering.rb

@@ -10,7 +10,7 @@ module Y
   # `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,
+  # 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
@@ -26,7 +26,7 @@ module Y
   #                             attrs: { "class" => ["callout callout--", :kind] },
   #                             contains: :blocks
   #     end
-  #   `tag` is the element; `attrs` values are templates — a String literal,
+  #   `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;
@@ -45,20 +45,20 @@ module Y
   #   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
+  #   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
+  # 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
+    # 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)
@@ -137,7 +137,7 @@ module Y
     # 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.
+    # with editor output matters: html_escape also rewrites apostrophes.
     def escape_text(value)
       value.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
     end
@@ -212,10 +212,10 @@ module Y
   # 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
+    # `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;
+    # 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)
@@ -232,23 +232,35 @@ module Y
       RenderRules.splice(result, @render_callbacks)
     end
 
-    # What node types this document actually contains — the discovery aid
+    # 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
+    # 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
+
+    # The node types to_html can't fully render: types in the document that
+    # neither the built-in schema nor a registered rule handles. An unknown
+    # container or inline wrapper renders its children without its own
+    # markup, so its text stays. An unknown decorator renders nothing, so
+    # content kept only in its attributes is missing from the HTML. Returns
+    # [] when every type is handled, and when the root is missing or isn't
+    # Lexical-shaped, because to_html returns nil there.
+    def unknown_types(root = nil)
+      types = node_types(root)
+      types ? types.filter_map { |type, info| type if info["handled"].nil? } : []
+    end
   end
 
   class ProseMirror
-    # `Y::ProseMirror.new(doc, nodes: {...}, marks: {...})` — see
+    # `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
+    # 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: {})
@@ -267,15 +279,27 @@ module Y
       RenderRules.splice(result, @render_callbacks)
     end
 
-    # What node types this document actually contains — the discovery aid
+    # 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
+    # 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
+
+    # The node types to_html can't fully render: types in the document that
+    # neither the built-in schema nor a registered rule handles. An unknown
+    # node renders its text and children without its own markup. A node that
+    # keeps its content only in its attributes renders nothing. Marks aren't
+    # listed, and an unknown mark renders its text unformatted. Returns []
+    # when every type is handled, and when the root is missing or isn't
+    # ProseMirror-shaped, because to_html returns nil there.
+    def unknown_types(root = nil)
+      types = node_types(root)
+      types ? types.filter_map { |type, info| type if info["handled"].nil? } : []
+    end
   end
 
   private_constant :NativeLexical, :NativeProseMirror

data/lib/y/tiptap.rb

@@ -1,14 +1,14 @@
 # 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 —
+  # 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
+  # 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

data/lib/y/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yrby
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.1
 platform: aarch64-linux
 authors:
 - JP Camara
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-20 00:00:00.000000000 Z
+date: 2026-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -72,6 +72,9 @@ files:
 - lib/y.rb
 - lib/y/3.4/yrby.so
 - lib/y/4.0/yrby.so
+- lib/y/collaborative.rb
+- lib/y/collaborative/attribute.rb
+- lib/y/collaborative/helper.rb
 - lib/y/decoder.rb
 - lib/y/lexxy.rb
 - lib/y/rendering.rb