yrby 0.7.1 → 0.8.0

data/ext/yrby/crates/html-core/Cargo.toml

@@ -3,7 +3,7 @@ name = "yjs-html-core"
 description = "Internal core for the lexical-yjs-html and prosemirror-yjs-html renderer crates; depend on those instead"
 repository = "https://github.com/jpcamara/yrby"
 readme = "README.md"
-version = "0.1.1"
+version = "0.1.3"
 edition = "2024"
 rust-version = "1.85"
 authors = ["JP Camara <johnpcamara@gmail.com>"]

data/ext/yrby/crates/html-core/src/lib.rs

@@ -1,21 +1,21 @@
-//! Custom render rules and segmented output — the extensibility core shared
-//! by both HTML renderers.
+//! The custom render rules and segmented output that both HTML renderers
+//! share.
 //!
-//! Callers register per-node rules. Two tiers:
+//! Callers register a rule per node. There are two tiers:
 //!
-//! - **Declarative rules** (tag, attributes, text, content slot) compile to
-//!   [`NodeRule`]/[`MarkRule`] here and render natively, inside the document
+//! - A declarative rule (tag, attributes, text, content slot) compiles to a
+//!   [`NodeRule`] or [`MarkRule`] and renders natively, inside the document
 //!   transaction, at full speed. This covers the tiptap-php `renderHTML`
 //!   shape: markup as data.
-//! - **Callback rules** defer to the caller. Rendering never runs app code
-//!   while the document is locked — the renderer emits [`Segment::Deferred`]
-//!   entries carrying the node's type, attributes (as JSON), and its
-//!   already-rendered children, and the caller fills them in after the
-//!   render returns. (In the Ruby gem, that caller is the app's block, run
-//!   once the transaction has closed and the GVL is held again.)
+//! - A callback rule defers to the caller. The renderer never runs
+//!   application code while the document is locked. It emits
+//!   [`Segment::Deferred`] entries with the node type, the attributes as
+//!   JSON, and the already-rendered children, and the caller fills them in
+//!   after the render returns. In the Ruby gem that caller is the app's
+//!   block, run once the transaction has closed and the GVL is held again.
 //!
-//! Rules arrive as one JSON document (see `parse`), so the same format
-//! serves any binding or caller.
+//! Rules arrive as one JSON document (see `parse`), so one format serves
+//! every binding and caller.
 
 use std::collections::{BTreeMap, BTreeSet, HashMap};
 use yrs::{Any, Out, ReadTxn, Xml};

data/ext/yrby/crates/lexical-html/Cargo.toml

@@ -3,7 +3,7 @@ name = "lexical-yjs-html"
 description = "Render Lexical-shaped yrs documents to HTML, no browser or Node required"
 repository = "https://github.com/jpcamara/yrby"
 readme = "README.md"
-version = "0.1.1"
+version = "0.1.3"
 edition = "2024"
 rust-version = "1.85"
 authors = ["JP Camara <johnpcamara@gmail.com>"]
@@ -14,4 +14,4 @@ categories = ["text-processing", "web-programming"]
 [dependencies]
 yrs = { version = "0.27", features = ["sync"] }
 serde_json = "1.0"
-yjs-html-core = { path = "../html-core", version = "0.1.1" }
+yjs-html-core = { path = "../html-core", version = "0.1.3" }

data/ext/yrby/crates/lexical-html/src/lib.rs

@@ -1,48 +1,61 @@
-//! Native HTML rendering of Lexical documents from the yrs collab structure —
-//! no Node process, no headless editor.
+//! HTML for Lexical documents, rendered from the Yjs structure the editor
+//! syncs. No Node process and no headless editor. A server that holds the
+//! document bytes produces the markup itself.
 //!
-//! This renders **core Lexical**: paragraphs, headings, quotes, code, lists
-//! and list items, tables, horizontal rules, links, and the whole text-format
-//! model. Everything Lexxy-specific — its own node types (attachments,
+//! This renders core Lexical: paragraphs, headings, quotes, code blocks,
+//! lists and list items, tables, horizontal rules, links, and the whole
+//! text-format model. Lexxy's additions live in the Ruby layer, as the
+//! `Y::Lexxy` renderer's rule set: its own node types (attachments,
 //! galleries, `early_escape_code`, `horizontal_divider`) and its decorations
-//! of core nodes (the table figure wrapper, header-cell styling, the
-//! nested-list-item class) — lives in the Ruby layer as the `Y::Lexxy`
-//! renderer's rule set, built on the same extension API apps use
-//! (`Y::Lexical` is the core base class). The Lexxy byte-parity guarantee is
-//! held there: the Ruby fixture tests and the live headless-Chrome e2e pin
-//! `Y::Lexxy#to_html` against a real editor's own serialized value. The
-//! native tests pin core output as regression goldens (stock Lexical has no
-//! canonical serializer to capture against).
+//! of core nodes (the figure around a table, header-cell styling, the
+//! nested-list-item class). That rule set uses the same extension API
+//! applications use. `Y::Lexical` is the core base class. The byte-parity
+//! guarantee is held there too: the Ruby fixture tests and the
+//! headless-Chrome end-to-end run pin `Y::Lexxy#to_html` against a real
+//! editor's serialized value. The tests in this crate pin core output as
+//! regression goldens. Stock Lexical has no canonical serializer to capture
+//! from.
 //!
-//! Prior art: `ueberdosis/tiptap-php` renders ProseMirror JSON to HTML in pure
-//! PHP — a schema-pinned renderer outside the JS runtime. This works from the
-//! collab (Yjs) structure rather than JSON.
+//! Prior art: `ueberdosis/tiptap-php` renders ProseMirror JSON to HTML in
+//! plain PHP, outside any JavaScript runtime. This crate does the same job
+//! from the collaborative (Yjs) structure.
 //!
-//! Storage model (verified against bytes captured from a live editor):
-//! - Blocks are `Y.XmlText` with a `__type` attribute (`paragraph`, `heading`
-//!   (+`__tag`), `quote`, `code` (+`__language`), `list`/`listitem`,
-//!   `table`/`tablerow`/`tablecell`, `link`/`autolink` (inline)).
-//! - Text runs are preceded by an embedded `Y.Map` carrying per-run metadata
-//!   (`__type: "text" | "code-highlight" | "tab"`, `__format` bitmask).
-//! - `linebreak` is a bare metadata map; `tab` is a map followed by a "\t" run.
-//! - Decorator nodes are `Y.XmlElement`s with their fields as plain
-//!   attributes (`horizontalrule` here; app/Lexxy decorators via rules).
+//! How Lexical stores a document, checked against bytes captured from a live
+//! editor:
 //!
-//! Text-format rendering follows the export pipeline Lexxy runs (Lexical's
-//! `$generateHtmlFromNodes` + sanitize), which is the only externally
-//! pinnable truth for formatting: inner tag `strong` (bold) / `em` (italic,
-//! when not bold); outer tag `code` / `mark` / `sub` / `sup`; an `<i>` wrap
-//! only when bold+italic combine (the `em` slot is taken); `<s>` / `<u>`
-//! wraps always; `<span>`s are unwrapped, so unformatted text is bare. A
-//! run's `__style` (highlight colors) survives on the createDOM tag,
-//! filtered to color/background-color; on a plain or s/u-only run it dies
-//! with the unwrapped span. Case-transform format bits are never rendered
-//! (their text-transform style is outside the sanitize whitelist).
+//! - Blocks are `Y.XmlText` with a `__type` attribute: `paragraph`,
+//!   `heading` (plus `__tag`), `quote`, `code` (plus `__language`), `list`
+//!   and `listitem`, `table`, `tablerow` and `tablecell`, and the inline
+//!   `link` and `autolink`.
+//! - Each text run is preceded by an embedded `Y.Map` with its metadata: a
+//!   `__type` of `text`, `code-highlight`, or `tab`, and a `__format`
+//!   bitmask.
+//! - A `linebreak` is a bare metadata map. A `tab` is a map followed by a
+//!   `"\t"` run.
+//! - Decorator nodes are `Y.XmlElement`s whose fields are plain attributes.
+//!   `horizontalrule` is handled here. Application and Lexxy decorators come
+//!   in through rules.
 //!
-//! Custom nodes: rules are registered by `__type` (see `yjs-html-core`) and
-//! consulted before the built-in arms, so they extend the schema or override
-//! a built-in. Declarative rules render here; callback rules emit
-//! `Segment::Deferred` for the caller to fill in after the render.
+//! Text formatting follows the export pipeline Lexxy runs: Lexical's
+//! `$generateHtmlFromNodes`, then sanitize. That output is the only
+//! formatting truth that can be pinned from outside. The inner tag is
+//! `strong` for bold, or `em` for italic without bold. The outer tag is
+//! `code`, `mark`, `sub`, or `sup`. An `<i>` wraps only when bold and italic
+//! combine, because the `em` slot is taken. `<s>` and `<u>` wrap whenever
+//! present. `<span>`s are unwrapped, so unformatted text is bare. A run's
+//! `__style` (highlight colors) survives on the createDOM tag, filtered to
+//! color and background-color. On a plain run, or one with only strike or
+//! underline, it goes away with the span. The case-transform format bits
+//! never render; their text-transform style is outside the sanitize
+//! whitelist.
+//!
+//! A node type with no rule still renders its text and child blocks, just
+//! unwrapped.
+//!
+//! Custom nodes register rules by `__type` (see `yjs-html-core`). A rule is
+//! consulted before the built-in arms, so it can extend the schema or
+//! replace a built-in. Declarative rules render here. Callback rules emit
+//! `Segment::Deferred` for the caller to fill in after the render returns.
 
 // README examples are living code: compile-checked on every cargo test.
 #[cfg(doctest)]

data/ext/yrby/crates/prosemirror-html/Cargo.toml

@@ -3,7 +3,7 @@ name = "prosemirror-yjs-html"
 description = "Render ProseMirror-shaped yrs documents to HTML, no browser or Node required"
 repository = "https://github.com/jpcamara/yrby"
 readme = "README.md"
-version = "0.1.2"
+version = "0.1.4"
 edition = "2024"
 rust-version = "1.85"
 authors = ["JP Camara <johnpcamara@gmail.com>"]
@@ -14,4 +14,4 @@ categories = ["text-processing", "web-programming"]
 [dependencies]
 yrs = { version = "0.27", features = ["sync"] }
 serde_json = "1.0"
-yjs-html-core = { path = "../html-core", version = "0.1.1" }
+yjs-html-core = { path = "../html-core", version = "0.1.3" }

data/ext/yrby/crates/prosemirror-html/src/lib.rs

@@ -1,40 +1,45 @@
-//! Native HTML rendering of ProseMirror/Tiptap documents from the yrs collab
-//! structure — no Node process, no headless editor.
+//! HTML for ProseMirror and Tiptap documents, rendered from the Yjs
+//! structure the editor syncs. No Node process and no headless editor.
 //!
-//! The y-prosemirror binding stores a document in a Y.XmlFragment: block nodes
-//! are Y.XmlElement (the tag is the node type, its attributes are the node
-//! attrs), and text is Y.XmlText whose per-run formatting attributes are the
-//! marks. Node and mark names come from the editor's schema, so this accepts
-//! both spellings in use: Tiptap's camelCase (`bulletList`, `bold`) and the
-//! prosemirror-schema-basic snake_case (`bullet_list`, `strong`).
+//! The y-prosemirror binding stores a document in a `Y.XmlFragment`. Block
+//! nodes are `Y.XmlElement`s: the tag is the node type and the attributes
+//! are the node attrs. Text is `Y.XmlText`, and each run's formatting
+//! attributes are its marks. Node and mark names come from the editor's
+//! schema, so both spellings are accepted: Tiptap's camelCase (`bulletList`,
+//! `bold`) and prosemirror-schema-basic's snake_case (`bullet_list`,
+//! `strong`).
 //!
-//! This renders **core ProseMirror**: the prosemirror-schema-basic node set
-//! plus the prosemirror-tables family — paragraphs, headings, blockquotes,
-//! code blocks, bullet/ordered lists, images, hard breaks, horizontal rules,
-//! and tables (semantic `<table><tbody>…`, without the `<colgroup>`/
-//! `min-width` styling editor views inject). Tiptap's extension nodes — task
-//! lists, mentions, the details family — live in the Ruby layer as the
-//! `Y::Tiptap` renderer's rule set, built on the same extension API apps use
-//! (`Y::ProseMirror` is the core base class). Output follows
-//! `ueberdosis/tiptap-php`, and with `Y::Tiptap`'s rules it matches Tiptap's
-//! own `getHTML()` byte for byte on the captured fixtures — that guarantee
-//! is held at the Ruby layer; the native tests pin core output as goldens
-//! where a fixture contains Tiptap-only nodes.
+//! This renders core ProseMirror: the prosemirror-schema-basic node set plus
+//! the prosemirror-tables family. That is paragraphs, headings, blockquotes,
+//! code blocks, bullet and ordered lists, images, hard breaks, horizontal
+//! rules, and tables as semantic `<table><tbody>…`, without the
+//! `<colgroup>` and `min-width` styling an editor view injects. Tiptap's
+//! extension nodes (task lists, mentions, the details family) live in the
+//! Ruby layer as the `Y::Tiptap` renderer's rule set, built on the same
+//! extension API applications use. `Y::ProseMirror` is the core base class.
+//! The output follows `ueberdosis/tiptap-php`. With `Y::Tiptap`'s rules it
+//! matches Tiptap's own `getHTML()` byte for byte on the captured fixtures.
+//! That guarantee is held at the Ruby layer. Where a fixture contains
+//! Tiptap-only nodes, the tests here pin core output as goldens.
 //!
-//! Marks stay native on purpose: mark serialization is text-run machinery
-//! (nesting order, textStyle's CSS, code's exclusivity), which the rule
-//! system can't express. The built-in set covers schema-basic's marks and
-//! Tiptap's — nesting outermost-first: link, a textStyle span, bold, italic,
-//! strike, underline, highlight, then subscript/superscript. `code` excludes
-//! the other formatting marks, so a code run is `<code>` alone — though a
+//! Marks stay native on purpose. Mark serialization is text-run machinery
+//! (nesting order, textStyle's CSS, code's exclusivity) that the rule system
+//! cannot express. The built-in set covers schema-basic's marks and
+//! Tiptap's, nested outermost-first: link, a textStyle span, bold, italic,
+//! strike, underline, highlight, then subscript and superscript. `code`
+//! excludes the other formatting marks, so a code run is `<code>` alone. A
 //! link still wraps it (see `render_run`).
 //!
-//! Custom nodes and marks: apps register rules by node type and mark name
-//! (see `render_rules`). A node rule is consulted before the built-in arms, so
-//! it can extend the schema or override a built-in; a mark rule claims its
-//! mark from the built-in wraps and wraps outside everything, link included.
-//! Declarative rules render here; callback rules emit `Segment::Deferred` for
-//! the caller to fill in after the render.
+//! A node type with no rule still renders its text and child blocks, just
+//! unwrapped.
+//!
+//! Applications register custom nodes and marks as rules keyed by node type
+//! and mark name (see `render_rules`). A node rule is consulted before the
+//! built-in arms, so it can extend the schema or replace a built-in. A mark
+//! rule claims its mark from the built-in wraps and wraps outside
+//! everything, link included. Declarative rules render here. Callback rules
+//! emit `Segment::Deferred` for the caller to fill in after the render
+//! returns.
 
 // README examples are living code: compile-checked on every cargo test.
 #[cfg(doctest)]

data/ext/yrby/src/lib.rs

@@ -168,7 +168,7 @@ impl RbDoc {
         let doc = &self.0;
         nogvl(move || {
             // Exactly ONE transaction per call. Opening a second while the
-            // first is still held deadlocks against a waiting writer — and
+            // first is still held deadlocks against a waiting writer, and
             // inside nogvl that hang can't be interrupted.
             let txn = doc.transact();
             txn.get_text(name.as_str()).map(|t| t.get_string(&txn))
@@ -200,8 +200,22 @@ impl RbDoc {
         })
     }
 
+    /// A `Y.Array` root serialized to a JSON array string (values recursive, in
+    /// array order). The counterpart to read_map for documents whose root is an
+    /// array: a board's cards, a sheet's rows. Callers parse the JSON (e.g.
+    /// `JSON.parse(doc.read_array("cards"))`). The serialization lives in
+    /// `read::array_json` (pure, Rust-tested).
+    fn read_array(&self, name: String) -> Option<String> {
+        let doc = &self.0;
+        nogvl(move || {
+            let txn = doc.transact();
+            let array = txn.get_array(name.as_str())?;
+            Some(read::array_json(&txn, &array))
+        })
+    }
+
     /// True if the doc holds un-integrable pending structs or a pending delete
-    /// set — content that couldn't integrate because a causally-prior update is
+    /// set: content that couldn't integrate because a causally-prior update is
     /// missing. Such content is a recovery buffer, not document state; it heals if
     /// the missing dependency later arrives. A pure read.
     fn pending(&self) -> bool {
@@ -211,7 +225,7 @@ impl RbDoc {
 
     /// Like `encode_state_as_update` (full state), but **gap-free**: it excludes
     /// any pending (un-integrable) structs and pending delete set. Use this when
-    /// persisting or serving state that other peers will apply — serving pending
+    /// persisting or serving state that other peers will apply. Serving pending
     /// content poisons their sync. Non-destructive: this doc keeps its pending, so
     /// a genuine gap still heals if its dependency arrives. (`encode_state_as_update`
     /// stays lossless for raw-update recovery.)
@@ -337,12 +351,12 @@ impl RbDoc {
 }
 
 // ============================================================================
-// Y::Lexical — schema-pinned rendering of Lexical/Lexxy documents
+// Y::Lexical: schema-pinned rendering of Lexical/Lexxy documents
 // ============================================================================
 
 /// A Lexical view over a `Y::Doc`. The schema knowledge lives here rather
 /// than on the schema-agnostic `Doc`: core Lexical natively, everything else
-/// through the render rules compiled at construction (see `render_rules` —
+/// through the render rules compiled at construction (see `render_rules`;
 /// the `Y::Lexxy` facade's rule set arrives that way). Holds a cheap clone of
 /// the doc (yrs `Doc` is an Arc handle), so it reads live state.
 ///
@@ -357,7 +371,7 @@ struct RbLexical {
 }
 
 impl RbLexical {
-    /// `Y::NativeLexical.new(doc, rules_json)` — the Y::Lexical facade
+    /// `Y::NativeLexical.new(doc, rules_json)`; the Y::Lexical facade
     /// compiles its `nodes:` config to the rules JSON.
     fn native_new(doc: &RbDoc, rules_json: String) -> Result<Self, Error> {
         Ok(RbLexical {
@@ -367,7 +381,7 @@ impl RbLexical {
     }
 
     /// Render the document's XML root (default `"root"`, Lexical's standard
-    /// collab root name) natively — no Node process or headless editor. The
+    /// collab root name) natively, with no Node process or headless editor. The
     /// native side renders core Lexical plus whatever the rules cover; with
     /// the rule set `Y::Lexxy` passes, output matches Lexxy's own serializer
     /// byte-for-byte on the reference fixtures (see `lexical_html.rs`). Returns nil when the root is missing or not
@@ -386,7 +400,7 @@ impl RbLexical {
         segments_result(segments)
     }
 
-    /// The document's node types as observed facts, JSON-encoded — the
+    /// The document's node types as observed facts, JSON-encoded, the
     /// native half of the facade's `node_types` discovery aid. Nil when the
     /// root is missing or not Lexical-shaped.
     fn node_types(&self, args: &[Value]) -> Result<Value, Error> {
@@ -415,13 +429,13 @@ impl RbLexical {
 }
 
 // ============================================================================
-// Y::ProseMirror — schema-pinned rendering of ProseMirror/Tiptap documents
+// Y::ProseMirror: schema-pinned rendering of ProseMirror/Tiptap documents
 // ============================================================================
 
 /// A ProseMirror view over a `Y::Doc`. The schema knowledge lives here rather
 /// than on the schema-agnostic `Doc`: core ProseMirror natively, everything
 /// else through the render rules compiled at construction (see
-/// `render_rules` — the `Y::Tiptap` facade's rule set arrives that way).
+/// `render_rules`; the `Y::Tiptap` facade's rule set arrives that way).
 /// Holds a cheap clone of the doc (yrs `Doc` is an Arc handle), so it reads
 /// live state.
 ///
@@ -436,7 +450,7 @@ struct RbProseMirror {
 }
 
 impl RbProseMirror {
-    /// `Y::NativeProseMirror.new(doc, rules_json)` — the Y::ProseMirror facade
+    /// `Y::NativeProseMirror.new(doc, rules_json)`; the Y::ProseMirror facade
     /// compiles its `nodes:`/`marks:` config to the rules JSON.
     fn native_new(doc: &RbDoc, rules_json: String) -> Result<Self, Error> {
         Ok(RbProseMirror {
@@ -466,7 +480,7 @@ impl RbProseMirror {
         segments_result(segments)
     }
 
-    /// The document's node types as observed facts, JSON-encoded — the
+    /// The document's node types as observed facts, JSON-encoded, the
     /// native half of the facade's `node_types` discovery aid. Nil when the
     /// root is missing or not ProseMirror-shaped.
     fn node_types(&self, args: &[Value]) -> Result<Value, Error> {
@@ -627,6 +641,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     doc_class.define_method("read_text", method!(RbDoc::read_text, 1))?;
     doc_class.define_method("read_xml", method!(RbDoc::read_xml, 1))?;
     doc_class.define_method("read_map", method!(RbDoc::read_map, 1))?;
+    doc_class.define_method("read_array", method!(RbDoc::read_array, 1))?;
     doc_class.define_method("pending?", method!(RbDoc::pending, 0))?;
     doc_class.define_method(
         "compacted_state_update",

data/ext/yrby/src/protocol.rs

@@ -71,24 +71,24 @@ pub(crate) fn merged_doc_update(bytes: &[u8]) -> Result<Option<Vec<u8>>, String>
 ///
 /// This must be EXACT: the sync layer records on "ready" and resyncs on "not
 /// ready", and a parked update that slipped through would look like an
-/// already-applied retry downstream — acked and dropped, losing real content.
+/// already-applied retry downstream: acked and dropped, losing real content.
 ///
 /// Clocks alone can't decide it. An update can satisfy every per-client clock
 /// and still fail to integrate: its items may reference other clients' blocks
 /// (origins/parents), and merged updates hide internal gaps behind Skip blocks.
 /// So the clock lower bound serves only as a cheap definitive REJECT; "ready"
 /// is decided by trial-integrating on a throwaway probe seeded with the doc's
-/// integrated state — ready iff nothing parks.
+/// integrated state: ready iff nothing parks.
 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())?;
-    // Partial order: "not covered" includes incomparable — not ready either way.
+    // Partial order: "not covered" includes incomparable: not ready either way.
     let lower_covered = doc.transact().state_vector() >= update.state_vector_lower();
     if !lower_covered {
         return Ok(false);
     }
     // Seed the probe with the doc's INTEGRATED state (gap-free), for two
     // reasons. A lossless seed would replant the doc's own pre-existing
-    // pending in the probe, making has_pending true for EVERY update — the
+    // pending in the probe, making has_pending true for EVERY update: the
     // verdict must be about this update, not the doc's baggage. And an update
     // whose dependency exists only in that pending buffer is genuinely not
     // ready: recording it would put a gap in the durable log; a resync heals
@@ -118,13 +118,13 @@ pub(crate) fn update_is_ready(doc: &Doc, update_bytes: &[u8]) -> Result<bool, St
 /// doc), then compare the probe before and after applying the update:
 ///
 /// - **Insert/format-only updates** grow the probe's state vector, so comparing
-///   the state vector is enough — and cheaper than a full re-encode.
+///   the state vector is enough, and cheaper than a full re-encode.
 /// - **Delete-bearing updates** don't move the state vector (a deletion tombstones
 ///   an existing struct rather than adding one), so we compare the full encoded
 ///   state, which carries the delete set. An already-applied pure-delete retry
 ///   re-encodes byte-identically → false; a genuinely new deletion changes the
 ///   delete set → true. This is exact but pays for two full encodes, so only
-///   delete-bearing frames — a minority — take that path.
+///   delete-bearing frames, a minority, take that path.
 ///
 /// Earlier this branch was conservative: any delete-bearing update returned true
 /// (record it), which double-recorded and re-broadcast pure-delete retries the
@@ -157,7 +157,7 @@ pub(crate) fn update_advances_doc(doc: &Doc, update_bytes: &[u8]) -> Result<bool
     }
 
     // Fast path: blocks beyond the doc's state vector are content the doc
-    // lacks — the update advances, no probe needed. The common case (a novel
+    // lacks: the update advances, no probe needed. The common case (a novel
     // edit) exits here; only retries and ambiguous diffs pay for the probe.
     if !has_deletes {
         let covered = doc.transact().state_vector() >= update.state_vector();
@@ -206,10 +206,10 @@ pub(crate) fn update_advances_doc(doc: &Doc, update_bytes: &[u8]) -> Result<bool
             return Ok(true);
         }
         // An unchanged state vector is ambiguous. Usually it means the doc
-        // already had everything in this update (a retry — return false, don't
+        // already had everything in this update (a retry: return false, don't
         // re-record). But it can ALSO mean the update failed to integrate and
         // was stashed as pending, which doesn't move the state vector either.
-        // That case is missing content, not a duplicate — returning false would
+        // That case is missing content, not a duplicate: returning false would
         // let a caller ack it and drop it. Distinguish the two by whether the
         // probe gained pending. (The sync flow screens gaps out with
         // update_is_ready before calling this; the check guards direct callers.)
@@ -240,7 +240,7 @@ pub(crate) fn has_pending(doc: &Doc) -> bool {
 /// Non-destructive: the prune happens only on the throwaway copy; `doc` keeps its
 /// pending, so a genuine gap still heals if its missing dependency later arrives.
 pub(crate) fn integrated_update(doc: &Doc, sv: &StateVector) -> Result<Vec<u8>, String> {
-    // Pending check and encode share ONE transaction — with two, a concurrent
+    // Pending check and encode share ONE transaction. With two, a concurrent
     // gappy apply_update could slip between them and the encode would serve
     // the very pending this function exists to exclude.
     let full = {
@@ -548,7 +548,7 @@ mod tests {
     // it and types between C's characters, so A's delta references C's blocks as
     // origins. Returns (c_update, a_delta). On a doc missing `c_update`, the
     // per-client clock lower bound of `a_delta` is satisfied (A starts at clock
-    // 0) but integration parks — the case a clock-only readiness check misses.
+    // 0) but integration parks: the case a clock-only readiness check misses.
     fn cross_client_origin_gap() -> (Vec<u8>, Vec<u8>) {
         let c = Doc::new();
         let ct = c.get_or_insert_text("t");
@@ -573,7 +573,7 @@ mod tests {
         let (c_update, a_delta) = cross_client_origin_gap();
 
         // A server that never saw C's content: the clock lower bound passes, but
-        // the update can't integrate — it must NOT be ready (previously it was,
+        // the update can't integrate: it must NOT be ready (previously it was,
         // and the downstream advances? probe then acked-and-dropped it).
         let server = Doc::new();
         assert!(
@@ -617,7 +617,7 @@ mod tests {
     fn a_doc_with_legacy_pending_still_accepts_healthy_updates() {
         // Why update_is_ready seeds its probe with the INTEGRATED state: with a
         // lossless seed, the doc's own pre-existing pending would park in the
-        // probe and every verdict would come back "not ready" — a server with
+        // probe and every verdict would come back "not ready": a server with
         // one legacy gap would reject every healthy keystroke forever.
         let (_first, dependent) = gap_pair();
         let doc = Doc::new();
@@ -645,7 +645,7 @@ mod tests {
     #[test]
     fn an_update_depending_only_on_pending_content_is_not_ready() {
         // The other half of the integrated-only seed: a dependency that exists
-        // solely in the doc's pending buffer doesn't count — recording such an
+        // solely in the doc's pending buffer doesn't count: recording such an
         // update would put a gap in the durable log. Not ready; resync heals
         // both as one complete delta.
         let src = Doc::new();
@@ -674,7 +674,7 @@ mod tests {
     #[test]
     fn update_advances_reports_true_when_the_update_would_park() {
         // Defense in depth for callers using advances? without the ready gate: a
-        // gappy update parks pending — that changes the doc, so it advances (it
+        // gappy update parks pending: that changes the doc, so it advances (it
         // must never be misread as an already-applied retry and dropped).
         let (_c_update, a_delta) = cross_client_origin_gap();
         let server = Doc::new();
@@ -896,7 +896,7 @@ mod tests {
         // for a fresh peer.
         //
         // Scope: this can't hit the original check-vs-encode race (its window
-        // is nanoseconds; never reproduced even at 20k iterations) — that fix
+        // is nanoseconds; never reproduced even at 20k iterations). That fix
         // is guaranteed by using a single transaction. What this catches is
         // coarser: encoding outside the lock, or a fast path skipping the
         // pending check.
@@ -914,7 +914,7 @@ mod tests {
             let first = first.clone();
             std::thread::spawn(move || {
                 while !stop.load(Ordering::Relaxed) {
-                    // Park a pending struct, then heal it, over and over — the
+                    // Park a pending struct, then heal it, over and over: the
                     // encode below keeps racing both transitions.
                     doc.transact_mut()
                         .apply_update(yrs::Update::decode_v1(&dependent).unwrap())