yrby 0.8.1 → 0.9.0

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