yrby 0.2.1

data/ext/yrby/src/protocol.rs

@@ -0,0 +1,331 @@
+// Pure Rust protocol helpers (no Ruby interop).
+//
+// Client ids are not validated here, on purpose: every legitimate peer (browser
+// Yjs, and yrs's own `ClientID::random`) already emits 53-bit ids, so it's the
+// client's responsibility not to send a bad one, and we don't want to own that
+// logic.
+use yrs::encoding::read::{Cursor, Read};
+use yrs::sync::protocol::MessageReader;
+use yrs::sync::{Message, SyncMessage};
+use yrs::updates::decoder::{Decode, DecoderV1};
+use yrs::{Doc, ReadTxn, Transact};
+
+/// Classify a frame: a non-zero code only for exactly one well-formed message
+/// that consumes the whole buffer (the codes are the match arms below).
+pub(crate) fn classify_message(bytes: &[u8]) -> u8 {
+    let mut decoder = DecoderV1::new(Cursor::new(bytes));
+    let msg = match Message::decode(&mut decoder) {
+        Ok(msg) => msg,
+        Err(_) => return 0, // empty or malformed
+    };
+    // Any remaining byte means a second message or trailing garbage.
+    if decoder.read_u8().is_ok() {
+        return 0;
+    }
+    match msg {
+        Message::Sync(SyncMessage::SyncStep1(_)) => 1,
+        Message::Sync(SyncMessage::SyncStep2(_)) | Message::Sync(SyncMessage::Update(_)) => 2,
+        Message::Awareness(_) => 3,
+        Message::AwarenessQuery => 4,
+        _ => 0, // Auth / Custom: not part of our model
+    }
+}
+
+/// Merge the document-update deltas (Update / SyncStep2 payloads) carried by a
+/// frame into one update, or `None` if the frame carries no document change
+/// (a request, an awareness update, or a no-op handshake SyncStep2).
+pub(crate) fn merged_doc_update(bytes: &[u8]) -> Result<Option<Vec<u8>>, String> {
+    let mut decoder = DecoderV1::new(Cursor::new(bytes));
+    let mut updates: Vec<Vec<u8>> = Vec::new();
+    for msg in MessageReader::new(&mut decoder) {
+        match msg.map_err(|e| e.to_string())? {
+            Message::Sync(SyncMessage::Update(u)) | Message::Sync(SyncMessage::SyncStep2(u)) => {
+                updates.push(u)
+            }
+            _ => {}
+        }
+    }
+    let merged = match updates.len() {
+        0 => return Ok(None),
+        1 => updates.pop().unwrap(),
+        _ => yrs::merge_updates_v1(&updates).map_err(|e| e.to_string())?,
+    };
+    let update = yrs::Update::decode_v1(&merged).map_err(|e| e.to_string())?;
+    // A genuine no-op (e.g. the empty SyncStep2 in an opening handshake) carries
+    // no structs, no deletes, and no dependencies. We must NOT treat a causally-
+    // pending update as a no-op: such an update reports an empty
+    // state_vector (its structs can't integrate yet), but it still carries
+    // content and a non-empty lower bound (the deps it's waiting on). Dropping it
+    // here would silently swallow a gappy update instead of rejecting + resyncing.
+    if update.state_vector().is_empty()
+        && update.delete_set().is_empty()
+        && update.state_vector_lower().is_empty()
+    {
+        return Ok(None);
+    }
+    Ok(Some(merged))
+}
+
+/// True if applying `update_bytes` to `doc` would integrate cleanly: every
+/// dependency the update references is already present (the doc's state vector
+/// covers the update's lower bound). A pure read; does not mutate the doc.
+/// When false, applying it would park a pending struct, the signal that an
+/// earlier, causally-prior update is missing.
+pub(crate) fn update_is_ready(doc: &Doc, update_bytes: &[u8]) -> Result<bool, String> {
+    let update = yrs::Update::decode_v1(update_bytes).map_err(|e| e.to_string())?;
+    Ok(doc.transact().state_vector() >= update.state_vector_lower())
+}
+
+/// True if applying `update_bytes` would actually change `doc`, i.e. it carries
+/// content the doc doesn't already have. This lets the server make durable side
+/// effects exactly-once: a lost-ack retry re-sends an update the server already
+/// applied; that retry is causally ready (so `update_is_ready` is true) but must
+/// not re-run `on_change`.
+///
+/// We can't read the update's own state vector to decide this: yrs reports an
+/// empty state_vector() for a causally-pending diff (e.g. a resync delta whose
+/// structs depend on updates the doc has but the standalone update doesn't),
+/// which would look identical to a no-op. So measure the real effect: seed an
+/// independent probe with the doc's current state, apply the update there, and
+/// see whether the state vector grew. Deletes don't move the state vector, so we
+/// can't cheaply prove a delete-bearing update is a duplicate; we conservatively
+/// report it as advancing (record it). That can still double-record a pure-delete
+/// retry, but it never drops a real deletion, which is the safe direction.
+/// Assumes the update is already causally ready.
+pub(crate) fn update_advances_doc(doc: &Doc, update_bytes: &[u8]) -> Result<bool, String> {
+    let update = yrs::Update::decode_v1(update_bytes).map_err(|e| e.to_string())?;
+    if !update.delete_set().is_empty() {
+        return Ok(true); // can't cheaply prove a delete is a duplicate; record it
+    }
+    let probe = Doc::new();
+    let current = doc
+        .transact()
+        .encode_state_as_update_v1(&yrs::StateVector::default());
+    probe
+        .transact_mut()
+        .apply_update(yrs::Update::decode_v1(&current).map_err(|e| e.to_string())?)
+        .map_err(|e| e.to_string())?;
+    let before = probe.transact().state_vector();
+    probe
+        .transact_mut()
+        .apply_update(update)
+        .map_err(|e| e.to_string())?;
+    let after = probe.transact().state_vector();
+    Ok(after != before)
+}
+
+/// True if the doc holds pending structs or a pending delete set: blocks that
+/// couldn't integrate because a dependency is missing. Test-only: asserts the
+/// causal-chain parking behavior in the unit tests below.
+#[cfg(test)]
+pub(crate) fn doc_has_pending(doc: &Doc) -> bool {
+    let txn = doc.transact();
+    txn.store().pending_update().is_some() || txn.store().pending_ds().is_some()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use yrs::sync::Awareness;
+    use yrs::updates::encoder::Encode;
+    use yrs::Text;
+
+    fn text_update(content: &str) -> Vec<u8> {
+        let doc = Doc::new();
+        let text = doc.get_or_insert_text("content");
+        text.insert(&mut doc.transact_mut(), 0, content);
+        let update = doc
+            .transact()
+            .encode_state_as_update_v1(&yrs::StateVector::default());
+        update
+    }
+
+    fn update_frame(content: &str) -> Vec<u8> {
+        Message::Sync(SyncMessage::Update(text_update(content))).encode_v1()
+    }
+
+    fn step1_frame() -> Vec<u8> {
+        Message::Sync(SyncMessage::SyncStep1(yrs::StateVector::default())).encode_v1()
+    }
+
+    fn awareness_frame(client_id: u64) -> Vec<u8> {
+        let mut awareness = Awareness::new(Doc::with_client_id(client_id));
+        awareness
+            .set_local_state(serde_json::json!({ "user": "alice" }))
+            .unwrap();
+        Message::Awareness(awareness.update().unwrap()).encode_v1()
+    }
+
+    #[test]
+    fn classify_accepts_clean_single_messages() {
+        assert_eq!(classify_message(&step1_frame()), 1);
+        assert_eq!(classify_message(&update_frame("hi")), 2);
+        assert_eq!(classify_message(&awareness_frame(7)), 3);
+        assert_eq!(classify_message(&Message::AwarenessQuery.encode_v1()), 4);
+    }
+
+    #[test]
+    fn classify_rejects_unsafe_frames() {
+        assert_eq!(classify_message(b""), 0, "empty");
+        assert_eq!(classify_message(&[0xff, 0xff, 0xff]), 0, "garbage");
+        assert_eq!(classify_message(&[0x63, 0x63, 0x63]), 0, "unknown type");
+
+        let mut two = update_frame("a");
+        two.extend(awareness_frame(1)); // two messages packed together
+        assert_eq!(classify_message(&two), 0, "multi-message");
+
+        let mut trailing = update_frame("a");
+        trailing.extend_from_slice(&[0xde, 0xad]);
+        assert_eq!(classify_message(&trailing), 0, "trailing garbage");
+
+        let frame = update_frame("hello");
+        assert_eq!(classify_message(&frame[..frame.len() / 2]), 0, "truncated");
+    }
+
+    #[test]
+    fn update_advances_is_false_for_an_already_applied_retry() {
+        let doc = Doc::new();
+        let upd = text_update("hello");
+
+        // Against a doc that doesn't have it yet, the update advances.
+        assert!(
+            update_advances_doc(&doc, &upd).unwrap(),
+            "new content advances"
+        );
+
+        // Apply it, then the byte-identical retry no longer advances.
+        doc.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&upd).unwrap())
+            .unwrap();
+        assert!(
+            !update_advances_doc(&doc, &upd).unwrap(),
+            "an already-applied retry does not advance"
+        );
+
+        // A genuinely new insert (from a different client) still advances.
+        let more = text_update("world");
+        assert!(
+            update_advances_doc(&doc, &more).unwrap(),
+            "different new content advances"
+        );
+    }
+
+    #[test]
+    fn update_advances_handles_a_dependent_diff_update() {
+        // A causally-pending diff (its structs depend on content the doc already
+        // has) reports an empty state_vector() in isolation, which a naive check
+        // would misread as a no-op. Verify the trial-apply gets it right.
+        let doc = Doc::new();
+        let text = doc.get_or_insert_text("content");
+        text.insert(&mut doc.transact_mut(), 0, "a");
+        let a_update = doc
+            .transact()
+            .encode_state_as_update_v1(&yrs::StateVector::default());
+        let sv_a = doc.transact().state_vector();
+        text.insert(&mut doc.transact_mut(), 1, "b");
+        let diff = doc.transact().encode_state_as_update_v1(&sv_a); // depends on "a"
+
+        // A server that has only "a".
+        let server = Doc::new();
+        server
+            .transact_mut()
+            .apply_update(yrs::Update::decode_v1(&a_update).unwrap())
+            .unwrap();
+
+        assert!(
+            update_advances_doc(&server, &diff).unwrap(),
+            "a dependent diff carrying new content advances"
+        );
+        server
+            .transact_mut()
+            .apply_update(yrs::Update::decode_v1(&diff).unwrap())
+            .unwrap();
+        assert!(
+            !update_advances_doc(&server, &diff).unwrap(),
+            "the byte-identical retry of that diff does not advance"
+        );
+    }
+
+    #[test]
+    fn merged_doc_update_extracts_and_skips_no_ops() {
+        // A document update yields a delta that reconstructs the content.
+        let delta = merged_doc_update(&update_frame("hello"))
+            .unwrap()
+            .expect("a document update");
+        let doc = Doc::new();
+        doc.transact_mut()
+            .apply_update(yrs::Update::decode_v1(&delta).unwrap())
+            .unwrap();
+        // The delta carried real content, so applying it advances the doc.
+        assert!(!doc.transact().state_vector().is_empty());
+
+        // A SyncStep1 request carries no document change.
+        assert!(merged_doc_update(&step1_frame()).unwrap().is_none());
+
+        // An empty SyncStep2 (no new structs) is a no-op.
+        let empty = Message::Sync(SyncMessage::SyncStep2(
+            Doc::new()
+                .transact()
+                .encode_state_as_update_v1(&yrs::StateVector::default()),
+        ))
+        .encode_v1();
+        assert!(merged_doc_update(&empty).unwrap().is_none());
+    }
+
+    #[test]
+    fn merged_doc_update_merges_multiple_updates() {
+        // Two updates from different clients packed in one frame merge into one.
+        let mut frame = update_frame("a");
+        frame.extend(update_frame("b"));
+        let merged = merged_doc_update(&frame).unwrap().expect("merged update");
+
+        // The merged update must decode cleanly as a single update.
+        assert!(yrs::Update::decode_v1(&merged).is_ok());
+    }
+
+    #[test]
+    fn update_readiness_and_pending_detect_a_causal_gap() {
+        // Three sequential single-char inserts from one client: A, then B, then
+        // C. Each delta depends on the previous, so C can't integrate without B.
+        let src = Doc::new();
+        let txt = src.get_or_insert_text("t");
+        let mut deltas: Vec<Vec<u8>> = Vec::new();
+        let mut prev = yrs::StateVector::default();
+        for (i, ch) in ["A", "B", "C"].into_iter().enumerate() {
+            txt.insert(&mut src.transact_mut(), i as u32, ch);
+            deltas.push(src.transact().encode_state_as_update_v1(&prev));
+            prev = src.transact().state_vector();
+        }
+        let (u1, u2, u3) = (&deltas[0], &deltas[1], &deltas[2]);
+
+        // A doc holding only u1 (u2 was lost in transit / its record failed):
+        let doc = Doc::new();
+        doc.transact_mut()
+            .apply_update(yrs::Update::decode_v1(u1).unwrap())
+            .unwrap();
+        assert!(update_is_ready(&doc, u1).unwrap(), "u1 has no missing deps");
+        assert!(
+            !update_is_ready(&doc, u3).unwrap(),
+            "u3 depends on the missing u2"
+        );
+        assert!(
+            !doc_has_pending(&doc),
+            "nothing pending until u3 is applied"
+        );
+
+        // Applying u3 anyway parks it as a pending struct.
+        doc.transact_mut()
+            .apply_update(yrs::Update::decode_v1(u3).unwrap())
+            .unwrap();
+        assert!(
+            doc_has_pending(&doc),
+            "u3 is pending: its parent u2 is missing"
+        );
+
+        // Once u2 arrives (via resync), u3 integrates and pending clears.
+        doc.transact_mut()
+            .apply_update(yrs::Update::decode_v1(u2).unwrap())
+            .unwrap();
+        assert!(!doc_has_pending(&doc), "u2 arrived; u3 integrated");
+    }
+}

data/ext/yrby/src/read.rs

@@ -0,0 +1,188 @@
+//! Pure content-reading helpers over yrs shared types — no magnus/Ruby, so they
+//! can be unit-tested directly in Rust (like `protocol.rs`). The binding layer in
+//! `lib.rs` is a thin wrapper that opens a transaction and calls these.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+use yrs::{Any, Array, GetString, Map, MapRef, Out, ReadTxn, XmlFragment, XmlFragmentRef, XmlOut};
+
+/// Read an XML-shaped root as text, one top-level block per line.
+///
+/// ProseMirror stores blocks as `Y.XmlElement` children (`<paragraph>…`);
+/// Lexical stores each block as a sibling `Y.XmlText` (its node metadata is an
+/// embed, which yrs omits from the string). We serialize each top-level child and
+/// join with "\n", so adjacent blocks don't merge into one run of words. Without
+/// the separator, Lexical — whose blocks carry no element tags — would glue
+/// paragraphs together (e.g. "first paragraphsecond paragraph"), breaking word
+/// boundaries for search/preview. Element tags are kept (the caller strips them);
+/// deeper nesting is flattened, but its inner tags still separate words after
+/// stripping.
+pub fn xml_blocks_text<T: ReadTxn>(txn: &T, fragment: &XmlFragmentRef) -> String {
+    fragment
+        .children(txn)
+        .map(|node| match node {
+            XmlOut::Element(e) => e.get_string(txn),
+            XmlOut::Text(t) => t.get_string(txn),
+            XmlOut::Fragment(f) => f.get_string(txn),
+        })
+        .collect::<Vec<_>>()
+        .join("\n")
+}
+
+/// Read a `Y.Map` root as a JSON object string (keys sorted for stable output).
+///
+/// The complement to `read_text`/`read_xml` for structured state — e.g. a shared
+/// "view state" map. Values are converted recursively: primitives pass through;
+/// nested `Y.Map`/`Y.Array` recurse; `Y.Text`/XML values stringify. The caller
+/// parses the JSON (yrs's own `Out::to_json` is crate-private, so we walk the
+/// `Out` variants ourselves here).
+pub fn map_json<T: ReadTxn>(txn: &T, map: &MapRef) -> String {
+    let mut pairs: Vec<(String, Any)> = map
+        .iter(txn)
+        .map(|(k, v)| (k.to_string(), out_to_any(txn, &v)))
+        .collect();
+    pairs.sort_by(|a, b| a.0.cmp(&b.0)); // deterministic key order
+    let mut out = String::from("{");
+    for (i, (k, v)) in pairs.iter().enumerate() {
+        if i > 0 {
+            out.push(',');
+        }
+        // Any::to_json serializes from the start of the buffer (it doesn't
+        // append), so each piece goes into its own String, then concatenated.
+        out.push_str(&any_to_json(&Any::String(Arc::from(k.as_str())))); // JSON-escaped key
+        out.push(':');
+        out.push_str(&any_to_json(v));
+    }
+    out.push('}');
+    out
+}
+
+fn any_to_json(a: &Any) -> String {
+    let mut s = String::new();
+    a.to_json(&mut s);
+    s
+}
+
+/// Convert a yrs output value to an `Any` (which knows how to JSON-serialize),
+/// recursing through nested shared collections.
+fn out_to_any<T: ReadTxn>(txn: &T, out: &Out) -> Any {
+    match out {
+        Out::Any(a) => a.clone(),
+        Out::YText(v) => Any::from(v.get_string(txn)),
+        Out::YXmlText(v) => Any::from(v.get_string(txn)),
+        Out::YXmlElement(v) => Any::from(v.get_string(txn)),
+        Out::YXmlFragment(v) => Any::from(v.get_string(txn)),
+        Out::YArray(arr) => {
+            let items: Vec<Any> = arr.iter(txn).map(|o| out_to_any(txn, &o)).collect();
+            Any::Array(items.into())
+        }
+        Out::YMap(m) => {
+            let mut hm: HashMap<String, Any> = HashMap::new();
+            for (k, v) in m.iter(txn) {
+                hm.insert(k.to_string(), out_to_any(txn, &v));
+            }
+            Any::Map(Arc::new(hm))
+        }
+        _ => Any::Null,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use yrs::{Doc, MapPrelim, Transact, XmlElementPrelim, XmlTextPrelim};
+
+    #[test]
+    fn prosemirror_blocks_keep_tags_and_separate_with_newlines() {
+        let doc = Doc::new();
+        let frag = doc.get_or_insert_xml_fragment("pm");
+        {
+            let mut txn = doc.transact_mut();
+            let h = frag.push_back(&mut txn, XmlElementPrelim::empty("heading"));
+            h.push_back(&mut txn, XmlTextPrelim::new("Title"));
+            let p = frag.push_back(&mut txn, XmlElementPrelim::empty("paragraph"));
+            p.push_back(&mut txn, XmlTextPrelim::new("Body"));
+        }
+        let txn = doc.transact();
+        assert_eq!(
+            xml_blocks_text(&txn, &frag),
+            "<heading>Title</heading>\n<paragraph>Body</paragraph>"
+        );
+    }
+
+    #[test]
+    fn lexical_style_sibling_text_blocks_separate_with_newlines() {
+        // Lexical stores each block as a sibling XmlText with no element tags;
+        // this is the case a flat read glued together.
+        let doc = Doc::new();
+        let frag = doc.get_or_insert_xml_fragment("lex");
+        {
+            let mut txn = doc.transact_mut();
+            frag.push_back(&mut txn, XmlTextPrelim::new("first paragraph"));
+            frag.push_back(&mut txn, XmlTextPrelim::new("second paragraph"));
+        }
+        let txn = doc.transact();
+        assert_eq!(
+            xml_blocks_text(&txn, &frag),
+            "first paragraph\nsecond paragraph"
+        );
+    }
+
+    #[test]
+    fn single_block_has_no_trailing_separator() {
+        let doc = Doc::new();
+        let frag = doc.get_or_insert_xml_fragment("one");
+        {
+            let mut txn = doc.transact_mut();
+            frag.push_back(&mut txn, XmlTextPrelim::new("only"));
+        }
+        let txn = doc.transact();
+        assert_eq!(xml_blocks_text(&txn, &frag), "only");
+    }
+
+    #[test]
+    fn empty_fragment_is_blank() {
+        let doc = Doc::new();
+        let frag = doc.get_or_insert_xml_fragment("empty");
+        let txn = doc.transact();
+        assert_eq!(xml_blocks_text(&txn, &frag), "");
+    }
+
+    #[test]
+    fn map_json_serializes_primitives_with_sorted_keys() {
+        let doc = Doc::new();
+        let map = doc.get_or_insert_map("state");
+        {
+            let mut txn = doc.transact_mut();
+            map.insert(&mut txn, "title", "Dashboard");
+            map.insert(&mut txn, "count", 3_i64);
+            map.insert(&mut txn, "active", true);
+        }
+        let txn = doc.transact();
+        assert_eq!(
+            map_json(&txn, &map),
+            r#"{"active":true,"count":3,"title":"Dashboard"}"#
+        );
+    }
+
+    #[test]
+    fn map_json_recurses_into_nested_map() {
+        let doc = Doc::new();
+        let map = doc.get_or_insert_map("state");
+        {
+            let mut txn = doc.transact_mut();
+            let inner = map.insert(&mut txn, "user", MapPrelim::default());
+            inner.insert(&mut txn, "name", "Ada");
+        }
+        let txn = doc.transact();
+        assert_eq!(map_json(&txn, &map), r#"{"user":{"name":"Ada"}}"#);
+    }
+
+    #[test]
+    fn map_json_empty_is_object() {
+        let doc = Doc::new();
+        let map = doc.get_or_insert_map("state");
+        let txn = doc.transact();
+        assert_eq!(map_json(&txn, &map), "{}");
+    }
+}

data/lib/y/decoder/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Y
+  module Decoder
+    VERSION = "0.1.0.alpha1"
+  end
+end

data/lib/y/decoder.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "y"
+require "y/decoder/version"
+
+module Y
+  # Plain-text reconstruction of a stored Yjs document, in pure Ruby — for search
+  # indexing and previews. The core `yrby` gem moves and stores opaque CRDT
+  # updates without reading them; this reads the text out of the shared type the
+  # editor uses (Lexical's `Y.XmlText`, plain `Y.Text`, or ProseMirror's
+  # `Y.XmlFragment`), in-process, on the native extension core already ships — no
+  # Node, no subprocess, no binary.
+  #
+  #   state = doc.encode_state_as_update        # opaque CRDT bytes from the store
+  #   Y::Decoder.text(state)              # => "hello world"
+  #   Y::Decoder.preview(state, 280)      # => "hello world…"
+  #
+  # Full-fidelity reconstruction (the exact Lexical EditorState / HTML, which
+  # needs @lexical/yjs) is a separate, opt-in concern — see the `yrby-decode`
+  # package's Bun binary. This gem stays pure Ruby on purpose.
+  module Decoder
+    class Error < Y::Error; end
+
+    module_function
+
+    # Plain text of the document. `field` pins the root key (Lexical: the editor
+    # id; ProseMirror: "default"); omit it to use the document's sole root.
+    def text(state, field: nil)
+      field ||= Y::Doc.new.tap { |d| d.apply_update(state) }.root_names.first
+      return "" unless field
+
+      # A plain `Y.Text` root (a simple shared-text editor) reads straight out.
+      # (A yrs root's type is fixed by its first typed access, so each reader
+      # gets a fresh doc to try a different shared type against the same state.)
+      direct = load(state).read_text(field)
+      return normalize(direct) if direct && !direct.strip.empty?
+
+      # Lexical (each block a sibling `Y.XmlText`) and ProseMirror (blocks are
+      # `Y.XmlElement`s) both come back from read_xml as block-per-line markup;
+      # strip any element tags to plain text.
+      markup = load(state).read_xml(field)
+      markup ? normalize(strip_tags(markup)) : ""
+    end
+
+    # A compact, single-line preview for list UIs.
+    def preview(state, limit: 280, field: nil)
+      body = text(state, field: field).gsub(/\s+/, " ").strip
+      body.length > limit ? "#{body[0, limit].rstrip}…" : body
+    end
+
+    def load(state)
+      Y::Doc.new.tap { |doc| doc.apply_update(state) }
+    end
+
+    def strip_tags(markup)
+      markup.gsub(/<[^>]*>/, " ")
+    end
+
+    def normalize(text)
+      text.gsub(/[ \t]+/, " ")     # collapse runs of spaces/tabs
+          .gsub(/ *\n */, "\n")    # trim spaces left around block separators
+          .gsub(/\n{3,}/, "\n\n")  # cap blank-line runs
+          .strip
+    end
+  end
+end

data/lib/y/version.rb

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

data/lib/y.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "y/version"
+
+# Load the native extension. Precompiled gems ship it in a per-Ruby-version
+# subdir (lib/y/<major.minor>/yrby.<ext>); a source build puts it flat at
+# lib/y/yrby.<ext>. Try the versioned path first, fall back.
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require_relative "y/#{Regexp.last_match(1)}/yrby"
+rescue LoadError
+  require_relative "y/yrby"
+end
+
+module Y
+  # Doc, Error, and the protocol module functions are defined in the Rust
+  # extension. The ActionCable integration (Y::ActionCable::Sync) lives in the
+  # separate `yrby-actioncable` gem; require "y/action_cable".
+end

data/lib/yrby-decoder.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name, so `Bundler.require` loads it automatically.
+require "y/decoder"

data/lib/yrby.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name, so `Bundler.require` loads it automatically.
+require "y"