yrby 0.8.1-aarch64-linux → 0.9.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2a8adb2628da0f03d1f51aaaa8e9d4fff8b312ec2721e553a5948644bc2c316
-  data.tar.gz: b3f8faa69b75d3d4ec8bc005f968e221da4039d7193401337c14a9e0582d87c4
+  metadata.gz: 8c1d9b86b8778b8120f728232c70de38d9a0dfc09ff99973f7ac7ad772c6bcd8
+  data.tar.gz: 32e33a4f2cab0777d3e15953aca69085fcedd4189de11a57756fadda5d760553
 SHA512:
-  metadata.gz: a4a916bd3d7534bf7c39c6fcfb9fc3ca1b90931bb3887cb4e38faab64d7e8264dd0bbc7902f3c479da32037e64dea3fbfbb4ccdbd5b4d287dd04c05fc0859f3d
-  data.tar.gz: 9725fd1c74ddaa31b4248f3b318eff62c754970468700e4e5a59db3179923be516628ccd1d2a24219abaff0aca15be26aac701efcfff76bf1fcaa9302b7f7cb2
+  metadata.gz: 6bb73b454506e9e766fc7ff22074363a517ac5624075185b79f2c19d0c0cd754997c1b48d6a1341c4a7a0ccfa442f8f6d501d23d38a94100183083417da94107
+  data.tar.gz: 45fcbb30ba7e37a59803b6f7ba2d4ac051bf3c59d342eb1dbdef8724e4461661ca3ce64c0fd5a9218d5d44173dc10b0e78baa7b430355976c8ee2e0a084c1c79

data/CHANGELOG.md

@@ -6,6 +6,96 @@ to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## yrby-client 0.7.1 - 2026-11-03
+
+### Fixed
+
+- yrby-client: `connect()` restores the presence that `disconnect()` removed,
+  unless the app set or cleared presence in between. Before this, a `renew()`
+  (which document sessions call with a renewed grant) or a manual reconnect
+  left the local awareness state `null`, and y-protocols ignores
+  `setLocalStateField` while it is `null`, so the user stayed invisible to
+  peers until reload.
+
+## [0.9.0] - 2026-11-03
+
+### Experimental
+
+These are new, and they may change in a minor release. See
+[docs/experimental.md](docs/experimental.md).
+
+- Live handles that write to a document from Ruby: `Doc#get_map`,
+  `get_array`, `get_text`, and `get_xml_text` return `Y::Map`, `Y::Array`,
+  `Y::Text`, and `Y::XmlText`. A write is a CRDT edit, so a person editing the
+  same document keeps their change. A handle stays on the shared type it was
+  made for while others edit around it, and releases the GVL like `Doc`.
+  Indexes are Ruby characters, and negative indexes count from the end as in
+  Ruby. `push`, `<<`, and `insert` return the receiver, and `each`
+  without a block an Enumerator, as Ruby's own do.
+- `Doc#edit { }` runs a block that writes to the document and returns the
+  update its writes produced, or nil when it wrote nothing. It is the unit a
+  process saves and sends as it writes.
+- `Y::Lexical` and `Y::Lexxy` write Lexical's node shape: `append_paragraph`,
+  `append_heading`, `append_list`, `append_quote`, `append_code`,
+  `append_markdown`, `insert_paragraph`, `append_text`, `replace_runs`, and
+  `delete_block`.
+  Text takes formatted runs (`bold:`, `italic:`, `code:`, `link:`, and so on).
+  What Ruby writes renders the same as what a person typed. Each helper
+  writes its block in one transaction. `XmlText#push_xml_text` and
+  `insert_xml_text` take the new block's content, and `append` and
+  `replace` write content into a block.
+- `append_markdown` writes a link to a script as plain text.
+- `Y::Anchor`, from `XmlText#anchor`, is a block's identity as a value to
+  store or send. `Doc#block_at` and `Doc#find` resolve it.
+  `relative_position(index)` builds the Yjs caret shape editors put in
+  awareness, and `Text#index_at(position)` resolves one.
+- `Doc#apply_update_changes(update, root)` applies an update and returns the
+  ordinals of the top-level blocks it touched. It reads the blocks and
+  applies the update in one transaction, so another thread's write doesn't
+  show up in the result.
+- `Y::Awareness` builds and reads presence frames, and `Doc#client_id` returns
+  the id a document writes under.
+
+### Changed
+
+- yrby and the renderer crates are on yrs 0.28. yrs 0.28 replaced the number
+  variants of `Any` with `Any::Number(Number::Int | Number::Float)`. Because
+  the crates take yrs types, this is a breaking release for them:
+  `lexical-yjs-html` 0.2.0, `prosemirror-yjs-html` 0.2.0, and
+  `yjs-html-core` 0.2.0 need yrs 0.28.
+
+### Fixed
+
+- The Lexical and ProseMirror renderers (and the `lexical-yjs-html` and
+  `prosemirror-yjs-html` 0.2.1 crates) refuse a link to a script: Lexical
+  sends it to `about:blank` and ProseMirror empties its `href`, as each
+  editor does.
+- A `Timeout`, `Thread#raise`, or `Thread#kill` that arrives during a
+  native call raises once the call returns. Before, Ruby could jump over
+  the extension's Rust frames without running their cleanup.
+
+## yrby-client 0.7.0 - 2026-10-08
+
+This release updates yrby-client only. The gems are unchanged.
+
+### Added
+
+- yrby-client: `<yrby-document>` has a read-only `current` property that
+  returns the `yrby:synced` detail of the bound session, or undefined when
+  nothing is bound. A binding that loads after the event fired can bind from
+  it.
+- yrby-client: `<yrby-document>` has a `retry()` method that acquires the
+  document again after its session blocked or was discarded, without changing
+  whether the page is live. It works from a lease abort handler or right after
+  `session.discard()`, so a binding can replace a broken document with a fresh
+  session. It replaces calling `activate()`, which is internal to the Turbo
+  adapter.
+- yrby-client: `YrbyDocumentElement.consumer` accepts a function that returns
+  a consumer or a promise of one. The element calls it when it first needs a
+  consumer and reuses the result. A function that throws or rejects is called
+  again on the next attempt, and assigning a different value replaces the
+  result.
+
 ## [0.8.1] - 2026-10-03
 
 ### Added

data/README.md

@@ -101,6 +101,7 @@ bin/rails generate yrby:install && bin/rails db:migrate
   - [Rendering to HTML](#rendering-to-html)
   - [Protocol codec (module functions)](#protocol-codec-module-functions)
   - [ActionCable Integration](#actioncable-integration)
+- [Experimental: writing from Ruby](#experimental-writing-from-ruby)
 - [Thread Safety](#thread-safety)
   - [Parallelism (GVL release)](#parallelism-gvl-release)
 - [Message Type Constants](#message-type-constants)
@@ -117,7 +118,9 @@ primitives. By default the Ruby side treats a document as opaque CRDT state. It
 applies updates, answers sync handshakes, and records deltas without reading
 the contents, and the browser editor decides what shape the document has. When
 you do need to look inside, `Doc#read_text` and `Doc#read_map` rebuild it in
-Ruby.
+Ruby, and live handles (`Doc#get_map`, `get_array`, `get_text`,
+`get_xml_text`) write to it. The handles are
+[experimental](docs/experimental.md).
 
 ## Durability and delivery
 
@@ -680,7 +683,7 @@ gets blocked at the next reconnect. To avoid that, pair `expires_in:` with
 # app/controllers/posts_controller.rb
 def grant
   @post = current_user.posts.find(params[:id])   # your own authorization, again
-  render json: { grant: @post.collaborative_sgid(:body, expires_in: 10.minutes) }
+  render json: { grant: @post.collaborative_document(:body).grant(expires_in: 10.minutes) }
 end
 ```
 
@@ -744,7 +747,7 @@ up the record from it, so the page decides which document the client gets.
 
 ```erb
 <%# the view picks the document and signs it %>
-<%= tag.div data: { grant: post.collaborative_sgid(:body) } %>
+<%= tag.div data: { grant: post.collaborative_document(:body).grant } %>
 ```
 
 ```ruby
@@ -1074,6 +1077,18 @@ The browser clients manage presence (cursors, selections). The server doesn't
 set or hold presence state, and it relays awareness frames without reading
 them. See `yrby-client` for the client-side awareness API.
 
+## Experimental: writing from Ruby
+
+These APIs are new. They may change in any minor release, and they aren't
+covered by yrby's usual compatibility promise.
+[docs/experimental.md](docs/experimental.md) documents them:
+
+- Live `Y::Map`, `Y::Array`, and `Y::Text` handles that write to a document
+- Writing Lexical rich text from Ruby, with `Y::Lexical` and `Y::Lexxy`
+- Anchors: a block's identity as a value
+- Streaming into a document with `Doc#edit`
+- Editing a record's document from Ruby
+
 ## Thread Safety
 
 You can share a `Doc` across Ruby threads. Puma workers, ActionCable connection

data/lib/y/anchor.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Y
+  # A block's identity as a plain value. A live handle already stays on its
+  # block while people edit, but it lives in one process; an anchor can be
+  # stored and sent, then turned back into the block's ordinal with
+  # `Doc#block_at(anchor)` or into a handle with `Doc#find(anchor)`. It is a
+  # Yjs relative position that names the block itself, plus the root's name.
+  #
+  #   anchor = block.anchor
+  #   doc.block_at(anchor)   # => 3 (the block's ordinal now), or nil once it is gone
+  #   doc.find(anchor)       # => the live handle, or nil
+  #   Y::Anchor.from_json(anchor.to_json) == anchor
+  Anchor = Data.define(:position, :root) do
+    def self.from_h(hash)
+      hash = hash.transform_keys(&:to_s)
+      new(position: hash.fetch("position").transform_keys(&:to_s), root: hash.fetch("root"))
+    end
+
+    def self.from_json(json)
+      from_h(JSON.parse(json))
+    end
+
+    def to_h
+      { "position" => position, "root" => root }
+    end
+
+    def to_json(*)
+      to_h.to_json(*)
+    end
+  end
+end

data/lib/y/collaborative/attribute.rb

@@ -22,6 +22,42 @@ module Y
       # this to return before it acknowledges or broadcasts the change.
       def append(update) = document_row.append(update)
 
+      # A signed grant for this document, what a page or a Ruby client
+      # subscribes with. It's a signed GlobalID scoped to this attribute, and
+      # Y::Collaborative.locate turns it back into the record. Pass
+      # expires_in: to limit how long it lasts. Without it GlobalID's own
+      # default applies, which is one month under Rails. The option goes
+      # through only when it's given, because an explicit nil would mean
+      # "never expire".
+      def grant(expires_in: nil)
+        options = { for: Y::Collaborative.sgid_purpose(name) }
+        options[:expires_in] = expires_in if expires_in
+        record.to_sgid(**options).to_s
+      end
+
+      # The channel that accepts this document's grant. A gem with its own
+      # grants and channel, such as lexxy-realtime, returns its own document
+      # with both.
+      def channel = "Y::DocumentChannel"
+
+      # Edits the document from Ruby the way a browser does: yields the
+      # current document, records what the block changed, and broadcasts it so
+      # open editors apply it. Returns the update, or nil when the block
+      # changed nothing.
+      #
+      #   post.collaborative_document(:body).edit do |doc|
+      #     Y::Lexxy.append_paragraph(doc, "Reviewed by ops.")
+      #   end
+      def edit
+        doc = y_doc
+        update = doc.edit { yield doc }
+        return unless update
+
+        append(update)
+        Y::ActionCable.broadcast(key, update)
+        update
+      end
+
       # Builds a new Y::Doc from storage on every call.
       def y_doc
         Y::Doc.new.tap do |doc|

data/lib/y/collaborative/helper.rb

@@ -9,15 +9,18 @@ module Y
     #
     # renders the auto-connecting element:
     #
-    #   <yrby-document grant="<signed sgid>" name="body"></yrby-document>
+    #   <yrby-document channel="Y::DocumentChannel" grant="<signed grant>" 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
+    # the document's channel 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 grant and channel come from record.collaborative_document(name), so
+    # the tag works for any gem that returns its own document, such as
+    # lexxy-realtime. Pass channel: for an app's own Y::DocumentChannel
+    # subclass. The grant is scoped to this record and attribute. 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.
@@ -30,18 +33,18 @@ module Y
     # 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) }:
+    # own authorization and renders { grant: record.collaborative_document(name).grant }:
     #
     #   <%= 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 }
+        document = record.collaborative_document(name)
+        attributes = { grant: document.grant(expires_in:), 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, &)
+        # A later key wins in a keyword splat. A template can pass its own
+        # channel, but it can't override the grant or the name.
+        tag.yrby_document(channel: document.channel, **, **attributes, &)
       end
     end
   end

data/lib/y/collaborative.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require "active_support/concern"
+require "active_support/deprecation"
 require "global_id"
+require "y/action_cable"
 
 module Y
   # The signed token that connects a page to a channel for record-backed
@@ -12,7 +14,7 @@ module Y
   # record up from it. The token is a signed GlobalID scoped to one attribute.
   #
   #   # the view
-  #   tag.div data: { grant: post.collaborative_sgid(:body) }
+  #   tag.div data: { grant: post.collaborative_document(:body).grant }
   #
   #   # the channel
   #   def authorized?(_key)
@@ -28,6 +30,10 @@ module Y
   #
   # The engine includes this into ActiveRecord::Base so any channel's
   # authorized? can use it. lexxy-realtime uses the same token flow.
+  # Warns about yrby-rails methods that are going away. The engine adds it to
+  # Rails.application.deprecators, so the app's deprecation settings apply.
+  def self.deprecator = @deprecator ||= ActiveSupport::Deprecation.new("0.9", "yrby-rails")
+
   module Collaborative
     extend ActiveSupport::Concern
 
@@ -39,7 +45,7 @@ module Y
       # 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)`.
+      # Looks up the record for a grant from `collaborative_document(name).grant`.
       # Returns nil for an invalid, tampered, expired, or wrong-attribute
       # token, and for a record that no longer exists.
       def locate(sgid, name)
@@ -76,20 +82,17 @@ module Y
     end
 
     # Returns the document for one attribute, stored the way the model
-    # declared. It responds to load_state, append, y_doc, and key.
+    # declared. It responds to load_state, append, edit, y_doc, key, grant,
+    # and channel.
     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".
+    # Deprecated. Use collaborative_document(name).grant. This one always
+    # signs yrby's own grant, as it did before.
     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
+      Y.deprecator.warn("collaborative_sgid(name) is deprecated. Use collaborative_document(name).grant instead.")
+      Attribute.new(self, name).grant(expires_in:)
     end
   end
 end

data/lib/y/doc.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Y
+  # Ruby-side conveniences over the native document.
+  class Doc
+    # Runs the block, which edits this document through handles, and returns
+    # the update its writes produced, or nil when the document didn't change.
+    # The document has the edit either way. The update is what a process
+    # saves and broadcasts, one call per chunk as it streams into a document.
+    #
+    # The update holds everything the document gained while the block ran,
+    # so a write another thread or peer made meanwhile is in it too. Applying
+    # an update twice changes nothing, so that only adds bytes.
+    def edit
+      before = native_snapshot
+      yield self
+      native_update_since(before)
+    end
+
+    # The ordinal of the top-level block a position falls in, or nil at the
+    # root or once the block is gone. Takes an `Anchor`, or a raw relative
+    # position hash (`{type, tname, item, assoc}`, the shape editors put in
+    # awareness as `anchorPos`/`focusPos`) plus the root's name.
+    def block_at(position, root = nil)
+      return native_block_at(position.position, position.root) if position.is_a?(Anchor)
+      raise ArgumentError, "block_at needs the root name with a raw position" unless root
+
+      native_block_at(position, root)
+    end
+
+    # The block an anchor names, as a live handle, or nil once it is gone.
+    def find(anchor)
+      native_find(anchor.position, anchor.root)
+    end
+  end
+end

data/lib/y/lexical_markdown.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Y
+  class Lexical
+    # The subset of Markdown a model writes: headings, paragraphs, bulleted
+    # and numbered lists, quotes, fenced code, and inline bold, italic, code,
+    # and links. Appended as Lexical blocks, so model output arrives looking
+    # like what a person would have typed.
+    module Markdown
+      HEADING = /\A(\#{1,6})\s+(.*)\z/
+      BULLET = /\A[-*]\s+(.*)\z/
+      NUMBERED = /\A\d+[.)]\s+(.*)\z/
+      QUOTE = /\A>\s?(.*)\z/
+      FENCE = /\A```\s*([^\s`]*)[^`]*\z/ # the language, then any other info
+      INLINE = /
+        ( \*\*(.+?)\*\*                                # bold
+        | `([^`]+)`                                    # code
+        | \[([^\]]+)\]\(((?:[^()\s]|\([^()\s]*\))+)\)  # link: its URL may hold balanced parentheses
+        | (?<![*\w])\*([^*]+)\*(?!\w)                  # italic
+        | (?<!\w)_([^_]+)_(?!\w)                       # italic
+        )
+      /x
+
+      module_function
+
+      # Append `markdown` to `doc` through `flavor` (Y::Lexical or Y::Lexxy).
+      def append(flavor, doc, markdown, root: "root")
+        blocks(markdown.to_s).each do |kind, payload, extra|
+          case kind
+          when :heading then flavor.append_heading(doc, runs(payload), tag: "h#{extra}", root: root)
+          when :paragraph then flavor.append_paragraph(doc, runs(payload), root: root)
+          when :quote then flavor.append_quote(doc, runs(payload), root: root)
+          when :code then flavor.append_code(doc, payload, language: extra, root: root)
+          when :list then flavor.append_list(doc, payload.map { |line| runs(line) }, ordered: extra, root: root)
+          end
+        end
+      end
+
+      # Lines into [kind, payload, extra] blocks.
+      def blocks(text)
+        parser = Blocks.new
+        text.each_line(chomp: true) { |line| parser.feed(line) }
+        parser.finish
+      end
+
+      # A line-by-line parser. Prose lines gather into a paragraph, quote
+      # lines into a quote, and list lines into a list until something else
+      # ends them; a fence gathers lines verbatim until it closes.
+      class Blocks
+        def initialize
+          @out = []
+          @para = []
+          @quote = nil
+          @list = nil
+          @fence = nil
+        end
+
+        def feed(line)
+          return fenced(line) if @fence
+
+          if (m = FENCE.match(line)) then open_fence(m[1])
+          elsif (m = HEADING.match(line)) then block(:heading, m[2], m[1].length)
+          elsif (m = BULLET.match(line)) then item(m[1], ordered: false)
+          elsif (m = NUMBERED.match(line)) then item(m[1], ordered: true)
+          elsif (m = QUOTE.match(line)) then quote(m[1])
+          elsif line.strip.empty? then close_all
+          else
+            close_list
+            close_quote
+            @para << line.strip
+          end
+        end
+
+        def finish
+          close_fence if @fence
+          close_all
+          @out
+        end
+
+        private
+
+        def fenced(line)
+          return close_fence if line.start_with?("```")
+
+          @fence[:lines] << line
+        end
+
+        def open_fence(lang)
+          close_all
+          @fence = { lang: lang.empty? ? "plain" : lang, lines: [] }
+        end
+
+        def close_fence
+          @out << [:code, @fence[:lines].join("\n"), @fence[:lang]]
+          @fence = nil
+        end
+
+        def block(kind, payload, extra = nil)
+          close_all
+          @out << [kind, payload, extra]
+        end
+
+        def item(payload, ordered:)
+          close_para
+          close_quote
+          close_list if @list && @list[:ordered] != ordered
+          (@list ||= { ordered: ordered, items: [] })[:items] << payload
+        end
+
+        def quote(line)
+          close_para
+          close_list
+          @quote ||= []
+          @quote << line.strip unless line.strip.empty?
+        end
+
+        def close_quote
+          @out << [:quote, @quote.join(" ")] if @quote&.any?
+          @quote = nil
+        end
+
+        def close_para
+          @out << [:paragraph, @para.join(" ")] unless @para.empty?
+          @para = []
+        end
+
+        def close_list
+          @out << [:list, @list[:items], @list[:ordered]] if @list
+          @list = nil
+        end
+
+        def close_all
+          close_para
+          close_quote
+          close_list
+        end
+      end
+
+      # Inline markdown into runs: strings and { text:, bold:/italic:/code:/link: }.
+      def runs(line)
+        out = []
+        rest = line
+        while (m = INLINE.match(rest))
+          out << m.pre_match unless m.pre_match.empty?
+          out << if m[2] then { text: m[2], bold: true }
+                 elsif m[3] then { text: m[3], code: true }
+                 elsif m[4] then safe_url?(m[5]) ? { text: m[4], link: m[5] } : m[4]
+                 else { text: m[6] || m[7], italic: true }
+                 end
+          rest = m.post_match
+        end
+        out << rest unless rest.empty?
+        out
+      end
+
+      # The URL schemes a Markdown link may use, as Lexical's own link node
+      # allows them. A URL without a scheme is a path and stays.
+      SAFE_SCHEMES = %w[http https mailto sms tel].freeze
+
+      # Whether a model's link is safe to write: a `javascript:` URL becomes
+      # plain text. Browsers ignore whitespace and control characters inside
+      # a scheme, so those don't hide one.
+      def safe_url?(url)
+        scheme = url.gsub(/[\x00-\x20\x7f]/, "")[/\A([a-z][a-z0-9+.-]*):/i, 1]
+        scheme.nil? || SAFE_SCHEMES.include?(scheme.downcase)
+      end
+    end
+
+    # Append a subset of Markdown as Lexical blocks. Call it on the flavor that
+    # matches the editor (`Y::Lexxy.append_markdown` for a Lexxy editor).
+    def self.append_markdown(doc, markdown, root: "root")
+      Markdown.append(self, doc, markdown, root: root)
+    end
+  end
+end

data/lib/y/lexical_writer.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Y
+  # Writing to a Lexical document from Ruby.
+  #
+  # Lexical keeps its document in a root `XmlText`. Each block is an `XmlText`
+  # embedded in it, carrying the node's properties as attributes. Inside a
+  # block, a text node is an embedded marker (a map of its properties)
+  # followed by the characters; a run of formatted text is its own marker and
+  # characters. These helpers build exactly that shape, so what Ruby writes
+  # renders the same as what a person typed, and an open editor applies it as
+  # an ordinary remote edit. Each helper writes its block in one transaction,
+  # so another thread or a peer never sees a block without its text, or text
+  # under the wrong marker.
+  class Lexical
+    ELEMENT_ATTRIBUTES = {
+      "__format" => 0, "__style" => "", "__indent" => 0, "__dir" => nil,
+      "__textFormat" => 0, "__textStyle" => ""
+    }.freeze
+
+    PARAGRAPH_ATTRIBUTES = { "__type" => "paragraph", **ELEMENT_ATTRIBUTES }.freeze
+
+    TEXT_ATTRIBUTES = {
+      "__type" => "text", "__format" => 0, "__style" => "", "__mode" => 0, "__detail" => 0
+    }.freeze
+
+    # Lexical's text format bits.
+    FORMAT = { bold: 1, italic: 2, strikethrough: 4, underline: 8, code: 16 }.freeze
+
+    # A heading block: `tag` is "h1".."h6".
+    def self.heading_attributes(tag)
+      { "__type" => "heading", "__tag" => tag.to_s, **ELEMENT_ATTRIBUTES }
+    end
+
+    def self.quote_attributes = { "__type" => "quote", **ELEMENT_ATTRIBUTES }
+
+    # A code block. Its text nodes are `code-highlight` nodes.
+    def self.code_attributes(language: "plain")
+      { "__type" => "code", "__language" => language.to_s, **ELEMENT_ATTRIBUTES }
+    end
+
+    CODE_TEXT_ATTRIBUTES = { **TEXT_ATTRIBUTES, "__type" => "code-highlight" }.freeze
+
+    # A text node's marker with a format from FORMAT keys, e.g. bold: true.
+    def self.text_attributes(**format)
+      bits = format.sum { |name, on| on ? FORMAT.fetch(name) : 0 }
+      { **TEXT_ATTRIBUTES, "__format" => bits }
+    end
+
+    # A list block: `ordered:` false is a bulleted list ("ul"), true a numbered
+    # one ("ol").
+    def self.list_attributes(ordered: false)
+      { "__type" => "list", "__tag" => ordered ? "ol" : "ul",
+        "__listType" => ordered ? "number" : "bullet", "__start" => 1, **ELEMENT_ATTRIBUTES }
+    end
+
+    # A list item; `value` is its 1-based position. The item node's type is
+    # `list_item_type`, which an editor flavor can override (Lexxy uses its own).
+    def self.list_item_attributes(value)
+      { "__type" => list_item_type, "__value" => value, **ELEMENT_ATTRIBUTES }
+    end
+
+    def self.list_item_type = "listitem"
+
+    # A link inside a block: an element holding its own text nodes.
+    def self.link_attributes(url, title: nil)
+      { "__type" => "link", "__url" => url.to_s, "__target" => nil, "__rel" => nil,
+        "__title" => title, **ELEMENT_ATTRIBUTES }
+    end
+
+    # --- appending blocks ---
+
+    # Append a paragraph and return the live block. `runs` is a string, or an
+    # array of strings and hashes like `{ text: "bold", bold: true }` or
+    # `{ text: "docs", link: "https://…" }`.
+    def self.append_paragraph(doc, runs, root: "root")
+      append_block(doc, PARAGRAPH_ATTRIBUTES, runs, root: root)
+    end
+
+    # Append a heading (`tag:` "h1".."h6") and return the live block.
+    def self.append_heading(doc, runs, tag: "h2", root: "root")
+      append_block(doc, heading_attributes(tag), runs, root: root)
+    end
+
+    def self.append_quote(doc, runs, root: "root")
+      append_block(doc, quote_attributes, runs, root: root)
+    end
+
+    # Append a code block. Lines stay as they are; `language:` names the syntax.
+    def self.append_code(doc, code, language: "plain", root: "root")
+      doc.get_xml_text(root).push_xml_text(code_attributes(language: language),
+                                           [CODE_TEXT_ATTRIBUTES, code.to_s])
+    end
+
+    # Append a list of `items` (each a string or runs) and return the live list.
+    def self.append_list(doc, items, ordered: false, root: "root")
+      entries = items.each_with_index.map { |runs, i| [list_item_attributes(i + 1), content(runs)] }
+      doc.get_xml_text(root).push_xml_text(list_attributes(ordered: ordered), entries)
+    end
+
+    # Append a block with `attributes` holding `runs`.
+    def self.append_block(doc, attributes, runs, root: "root")
+      doc.get_xml_text(root).push_xml_text(attributes, content(runs))
+    end
+
+    # --- editing in place ---
+
+    # Insert a paragraph before the `at`-th block (at the end when past the
+    # last) and return it.
+    def self.insert_paragraph(doc, at, runs, root: "root")
+      doc.get_xml_text(root).insert_xml_text(at, PARAGRAPH_ATTRIBUTES, content(runs))
+    end
+
+    # Replace everything in a block with `runs`.
+    def self.replace_runs(block, runs) = block.replace(content(runs))
+
+    # Remove the `at`-th block. Returns whether there was one.
+    def self.delete_block(doc, at, root: "root") = doc.get_xml_text(root).delete_xml_text(at)
+
+    # Append plain `text` to the end of `block` and return the block. This is
+    # the call for streaming into a block. Text must follow a text node's
+    # marker or Lexical drops it, so after a link, or in an empty block, it
+    # starts a text node of its own; otherwise it joins the last one.
+    def self.append_text(block, text) = block.append_text(text.to_s, TEXT_ATTRIBUTES)
+
+    # Write `runs` at the end of `block`.
+    def self.write_runs(block, runs) = block.append(content(runs))
+
+    # `runs` as block content (see `XmlText#insert_xml_text`): a text node,
+    # its marker then its text, per run, and a link element holding one for a
+    # run with `link:`. Runs may use string keys, as parsed JSON does.
+    def self.content(runs)
+      Array(runs).flat_map do |run|
+        run = run.is_a?(String) ? { text: run } : run.transform_keys(&:to_sym)
+        raise ArgumentError, "a run needs text: #{run.inspect}" unless run.key?(:text)
+
+        text = [text_attributes(**run.slice(*FORMAT.keys)), run[:text].to_s]
+        run[:link] ? [[link_attributes(run[:link], title: run[:title]), text]] : text
+      end
+    end
+  end
+end

data/lib/y/lexxy.rb

@@ -11,6 +11,27 @@ module Y
   # nodes are declarative hashes, nodes with logic are plain methods mapped
   # in NODES.
   class Lexxy < Lexical
+    # Lexxy's list items are its own node type (it leaves a list when you press
+    # Enter on an empty item), so lists written for a Lexxy editor use it.
+    def self.list_item_type
+      "early_escape_listitem"
+    end
+
+    # Lexxy's code block is its own node type, with a syntax-highlight flag.
+    def self.code_attributes(language: "plain")
+      { **super, "__type" => "early_escape_code", "__isSyntaxHighlightSupported" => true }
+    end
+
+    # Lexxy links carry rel="noreferrer".
+    def self.link_attributes(url, title: nil)
+      { **super, "__rel" => "noreferrer" }
+    end
+
+    # Lexxy puts a quote's text inside a paragraph within the quote block.
+    def self.append_quote(doc, runs, root: "root")
+      doc.get_xml_text(root).push_xml_text(quote_attributes, [[PARAGRAPH_ATTRIBUTES, content(runs)]])
+    end
+
     # A cursor-placement placeholder; empty ones export to nothing.
     def self.provisional_paragraph(node)
       node.content.empty? ? "" : "<p>#{node.content}</p>"
@@ -101,6 +122,8 @@ module Y
 
     NODES = {
       # Lexxy's replacement for Lexical's CodeNode.
+      # Lexxy wraps a quote's content in a paragraph.
+      "quote" => { tag: "blockquote", contains: :blocks },
       "early_escape_code" => { tag: "pre", attrs: { "data-language" => :language } },
       "horizontal_divider" => { tag: "hr", void: true },
       "provisonal_paragraph" => method(:provisional_paragraph), # (sic: Lexxy's spelling)
@@ -109,6 +132,8 @@ module Y
       "wrapped_table_node" => { contains: :blocks, render: method(:table) },
       "tablecell" => { contains: :blocks, render: method(:table_cell) },
       "listitem" => { contains: :blocks, render: method(:list_item) },
+      # Lexxy's own list item (it leaves the list on Enter in an empty item).
+      "early_escape_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)

data/lib/y/rendering.rb

@@ -125,7 +125,7 @@ module Y
     # A template: String literal, Symbol attribute reference, or an Array of
     # both.
     def compile_parts(template)
-      Array(template).map do |part|
+      Kernel.Array(template).map do |part|
         case part
         when Symbol then { "ref" => part.to_s }
         else { "lit" => part.to_s }
@@ -227,7 +227,7 @@ module Y
 
     def to_html(root = nil)
       result = root.nil? ? @native.to_html : @native.to_html(root)
-      return result unless result.is_a?(Array)
+      return result unless result.is_a?(::Array)
 
       RenderRules.splice(result, @render_callbacks)
     end
@@ -274,7 +274,7 @@ module Y
 
     def to_html(root = nil)
       result = root.nil? ? @native.to_html : @native.to_html(root)
-      return result unless result.is_a?(Array)
+      return result unless result.is_a?(::Array)
 
       RenderRules.splice(result, @render_callbacks)
     end

data/lib/y/text.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Y
+  class Text
+    # The Yjs relative position of character `index`, the shape editors put
+    # in awareness as a caret. It keeps pointing at the same character as
+    # people edit around it; `index_at` says where that is now. `assoc:` is
+    # :after (default) or :before.
+    def relative_position(index, assoc: :after)
+      native_relative_position(index, assoc.to_s)
+    end
+  end
+end

data/lib/y/version.rb

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

data/lib/y/xml_text.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Y
+  # Ruby-side conveniences over the native live handle.
+  class XmlText
+    # Insert a block with `attributes` before the `ordinal`-th embedded
+    # block and return a live handle to it. A negative `ordinal` counts from
+    # the end, so -1 adds it after the last. `content` is written into the
+    # block in the same transaction, so no one sees the block before what it
+    # holds. It is an Array of Strings (text), Hashes (embeds, such as the
+    # marker Lexical puts before a text node's characters), and
+    # `[attributes, content]` pairs (blocks of their own).
+    def insert_xml_text(ordinal, attributes, content = [])
+      native_insert_xml_text(ordinal, attributes, content)
+    end
+
+    # Append a block with `attributes` holding `content` (see
+    # `insert_xml_text`) and return a live handle to it.
+    def push_xml_text(attributes, content = [])
+      insert_xml_text(-1, attributes, content)
+    end
+
+    # The Yjs relative position of character `index`: the `{type, tname,
+    # item, assoc}` hash editors carry in awareness as `anchorPos`/`focusPos`.
+    # `assoc:` is `:after` (the default) or `:before`.
+    def relative_position(index, assoc: :after)
+      native_relative_position(index, assoc.to_s)
+    end
+
+    # This block's `Anchor`: a value that names the block itself, with the
+    # root's name, so the document can say where the block is later.
+    def anchor
+      Anchor.new(position: native_block_position, root: root_name)
+    end
+  end
+end

data/lib/y.rb

@@ -14,6 +14,12 @@ end
 
 require_relative "y/rendering"
 require_relative "y/lexxy"
+require_relative "y/lexical_writer"
+require_relative "y/lexical_markdown"
+require_relative "y/anchor"
+require_relative "y/xml_text"
+require_relative "y/text"
+require_relative "y/doc"
 require_relative "y/tiptap"
 require_relative "y/decoder"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yrby
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.9.0
 platform: aarch64-linux
 authors:
 - JP Camara
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-10-04 00:00:00.000000000 Z
+date: 2026-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -72,14 +72,20 @@ files:
 - lib/y.rb
 - lib/y/3.4/yrby.so
 - lib/y/4.0/yrby.so
+- lib/y/anchor.rb
 - lib/y/collaborative.rb
 - lib/y/collaborative/attribute.rb
 - lib/y/collaborative/helper.rb
 - lib/y/decoder.rb
+- lib/y/doc.rb
+- lib/y/lexical_markdown.rb
+- lib/y/lexical_writer.rb
 - lib/y/lexxy.rb
 - lib/y/rendering.rb
+- lib/y/text.rb
 - lib/y/tiptap.rb
 - lib/y/version.rb
+- lib/y/xml_text.rb
 - lib/yrby.rb
 homepage: https://github.com/jpcamara/yrby
 licenses: