@jxsuite/collab 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/collab",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Realtime co-editing for Jx Studio — Y.Doc schema, op bridge, structural differ, wire envelope, and provider contracts shared by every collab backend",
   "license": "MIT",
   "repository": {
@@ -19,6 +19,7 @@
     "./op-bridge": "./src/op-bridge.ts",
     "./diff": "./src/diff.ts",
     "./envelope": "./src/envelope.ts",
+    "./negotiate": "./src/negotiate.ts",
     "./awareness-types": "./src/awareness-types.ts",
     "./provider": "./src/provider.ts",
     "./client": "./src/ws-client.ts",
@@ -32,7 +33,7 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "^1.4.0",
+    "@jxsuite/schema": "^1.6.0",
     "lib0": "^0.2.99",
     "y-protocols": "^1.0.6",
     "yjs": "13.6.27"

package/src/awareness-types.ts

@@ -21,8 +21,14 @@ export interface CollabAwarenessState {
   focusedPath: string | null;
   /** Which representation the client is editing (drives the Phase-B canonical lock). */
   mode?: "structure" | "source";
-  /** The client's structural (canvas) selection in the focused document. */
-  structuralSelection?: JxPath | null;
+  /**
+   * The client's structural (canvas) selection in the focused document — the whole SET.
+   *
+   * A list because `session.selection` is one (studio §6.5): a peer who has selected six cards
+   * publishes six paths, and the remote canvas draws a presence box for each. A peer with one node
+   * selected publishes a one-entry list, which draws exactly the one box it always did.
+   */
+  structuralSelection?: JxPath[] | null;
   /**
    * RESERVED for y-monaco: the in-buffer text cursor as {anchor, head} Y.RelativePosition JSON.
    * MonacoBinding owns this field via setLocalStateField("selection", …) while a code view is

package/src/envelope.ts

@@ -14,11 +14,17 @@
  * are dropped and answered with a `doc-reset` control message, upon which the client destroys its
  * Y.Doc and re-opens. The invariant "Y history is never deleted or replaced without an epoch bump"
  * is what prevents divergent-history duplicate-content merges.
+ *
+ * The layout above is what the `jx.collab.v1` WebSocket subprotocol names. A change that would make
+ * a peer mis-parse a frame is a new token, not a silent edit here — see `negotiate.ts` for the bump
+ * rule and for why the capability probe, not the socket, is where the two sides agree.
  */
 
 import * as decoding from "lib0/decoding";
 import * as encoding from "lib0/encoding";
 
+export { COLLAB_SUBPROTOCOL } from "./negotiate.ts";
+
 export const FRAME_DOC_SYNC = 0;
 export const FRAME_AWARENESS = 1;
 export const FRAME_DOC_CLOSE = 2;

package/src/negotiate.ts

@@ -0,0 +1,131 @@
+/**
+ * WebSocket subprotocol negotiation for the collab socket (RFC 6455 §1.9, §4.2.2).
+ *
+ * **The token names the wire envelope, not the package.** `jx.collab.v1` means "I speak the frame
+ * layout `envelope.ts` documents". There is one token per envelope **major**, and the rule for
+ * bumping it is narrow on purpose: bump when {@link decodeFrame} would _mis-parse_ a peer's frame —
+ * a field reordered, a type widened, a length prefix changed. **Do not bump for a new frame type.**
+ * Both halves already skip a frame type they do not know, so a v1 peer and a v1-plus-one-frame peer
+ * interoperate; bumping there would refuse a room that would have worked.
+ *
+ * **Why the capability probe does the negotiating.** RFC 6455 §4.1 requires a client that offered
+ * subprotocols and received no echo to _fail the connection_, and browsers enforce it. So a new
+ * Studio that unconditionally offered `jx.collab.v1` would lose collab entirely against an older
+ * dev server — a regression caused by the fix. The probe already exists, already returns a version
+ * the client discards, and runs before the socket: it is the one place the client can learn what
+ * the server speaks without risking the handshake. Hence {@link negotiateCollab}, which turns a
+ * probe body into the list to offer — empty against a server that advertises nothing.
+ *
+ * **Nothing here may go in the `hello` control message.** That arrives after the socket is up and
+ * after frames may already have been exchanged, which is too late to prevent the divergent-history
+ * merge `schema.ts` warns about. Negotiation has to conclude before a byte of document state
+ * moves.
+ *
+ * This module imports nothing, deliberately: the Studio platform adapters read it eagerly, before
+ * the dynamic import that pulls in Yjs, so it must not drag the CRDT into the initial bundle.
+ */
+
+/** The subprotocol token for the envelope in `envelope.ts`. One token per envelope major. */
+export const COLLAB_SUBPROTOCOL = "jx.collab.v1";
+
+/** What the client should do with the socket, given what the server advertised. */
+export interface CollabNegotiation {
+  /**
+   * The subprotocols to offer as `Sec-WebSocket-Protocol`. **Empty means offer none**, which is the
+   * correct answer against a server that advertises none: an offer it cannot echo would fail the
+   * handshake outright, where offering nothing connects exactly as it does today.
+   */
+  offer: string[];
+  /**
+   * Non-null when the peers cannot interoperate: the server advertised subprotocols and none of
+   * them is one we speak. The client must not connect — the string says which side speaks what, so
+   * the degradation is legible rather than a silent solo session.
+   */
+  refused: string | null;
+}
+
+/**
+ * Decide what to offer, from the body of a `GET /__studio/collab` capability probe.
+ *
+ * @param {unknown} probe The parsed probe body, or null if it did not parse as JSON.
+ * @returns {CollabNegotiation}
+ */
+export function negotiateCollab(probe: unknown): CollabNegotiation {
+  if (probe === null || typeof probe !== "object") {
+    // A 200 that is not a JSON object: pre-negotiation server. Connect as before, offering nothing.
+    return { offer: [], refused: null };
+  }
+  const body = probe as { collab?: unknown; protocols?: unknown };
+  if (body.collab === false) {
+    return { offer: [], refused: "This server has collaboration disabled." };
+  }
+  const { protocols } = body;
+  if (!Array.isArray(protocols) || protocols.length === 0) {
+    // A server that predates negotiation. It would echo nothing, so we must offer nothing.
+    return { offer: [], refused: null };
+  }
+  if (protocols.includes(COLLAB_SUBPROTOCOL)) {
+    return { offer: [COLLAB_SUBPROTOCOL], refused: null };
+  }
+  const theirs = protocols.filter((p) => typeof p === "string").join(", ") || "none";
+  return {
+    offer: [],
+    refused: `This server speaks collab envelope ${theirs}; this editor speaks ${COLLAB_SUBPROTOCOL}.`,
+  };
+}
+
+/**
+ * The subprotocols a client offered, from its `Sec-WebSocket-Protocol` request header.
+ *
+ * RFC 6455 §4.1 allows the field to be split across several header lines and comma-separated within
+ * one; `Headers.get` already joins repeats with `, `, so one split covers both spellings.
+ *
+ * @param {string | null} header
+ * @returns {string[]}
+ */
+export function offeredSubprotocols(header: string | null): string[] {
+  if (!header) {
+    return [];
+  }
+  return header
+    .split(",")
+    .map((token) => token.trim())
+    .filter((token) => token !== "");
+}
+
+/** What the server should do with an upgrade, given the client's offer. */
+export interface SubprotocolAnswer {
+  /** The token to echo in the 101 response, or null to echo nothing. */
+  echo: string | null;
+  /** Non-null when the handshake must be refused instead of upgraded. */
+  reject: string | null;
+}
+
+/**
+ * Choose the subprotocol to echo (RFC 6455 §4.2.2 step 4).
+ *
+ * Three cases, and the middle one is the one that is easy to get wrong:
+ *
+ * - **No offer** — an older client. Upgrade and echo nothing; it is not expecting an echo, and
+ *   refusing it would break every Studio built before this shipped.
+ * - **An offer we speak** — echo exactly that token. Echoing a token the client did not offer is
+ *   itself a protocol violation, so the echo is always a member of the offer.
+ * - **An offer we do not speak** — refuse. This is the whole point: two peers whose envelopes
+ *   disagree about merge granularity (see `collab.md` §3.1) must not end up in one room, and a
+ *   refused handshake is a far better outcome than a divergent-history merge.
+ *
+ * @param {string[]} offered
+ * @returns {SubprotocolAnswer}
+ */
+export function selectSubprotocol(offered: string[]): SubprotocolAnswer {
+  if (offered.length === 0) {
+    return { echo: null, reject: null };
+  }
+  if (offered.includes(COLLAB_SUBPROTOCOL)) {
+    return { echo: COLLAB_SUBPROTOCOL, reject: null };
+  }
+  return {
+    echo: null,
+    reject: `No supported collab subprotocol offered (this server speaks ${COLLAB_SUBPROTOCOL}).`,
+  };
+}

package/src/op-bridge.ts

@@ -14,7 +14,17 @@
 import * as Y from "yjs";
 import type { JxPath } from "@jxsuite/schema/types";
 import type { JxDocOp } from "./ops.ts";
-import { resolveYPath, toYChildren, toYNode, yValueToJson } from "./schema.ts";
+import {
+  applyTextEdit,
+  GRANULAR_OBJECT_KEYS,
+  mergeYObject,
+  resolveYPath,
+  TEXT_KEYS,
+  toYChild,
+  toYChildren,
+  toYObject,
+  yValueToJson,
+} from "./schema.ts";
 
 /** Origin of Y transactions produced by mirroring the local tab's ops. */
 export const LOCAL_ORIGIN = "jx-local";
@@ -59,8 +69,47 @@ function cloneJson<T>(value: T): T {
   return JSON.parse(JSON.stringify(value)) as T;
 }
 
-function toYChild(node: unknown): unknown {
-  return typeof node === "string" ? node : toYNode(node);
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Write a node key, preserving CRDT identity wherever the schema stores it granularly.
+ *
+ * Studio's mutators record whole-value `set-key` ops — `mutateUpdateStyle` replaces the entire
+ * style object, an inline-edit commit replaces the entire `textContent`. Writing those straight
+ * through with `Y.Map.set` mints a fresh Y type each time and throws away whatever a peer
+ * concurrently did to the old one, which is exactly how "two people typing in one paragraph" became
+ * last-writer-wins.
+ *
+ * So a whole-value op is diffed down onto the existing structure: text through {@link applyTextEdit}
+ * (character-level), granular objects through {@link mergeYObject} (per-property). Only a TYPE
+ * change — string text becoming a `$ref`, an object becoming a scalar — falls back to replacement,
+ * because then there is no shared structure left to preserve.
+ */
+function setNodeKey(node: Y.Map<unknown>, key: string, value: unknown): void {
+  const existing = node.get(key);
+  if (key === "children" && Array.isArray(value)) {
+    node.set(key, toYChildren(value));
+    return;
+  }
+  if (TEXT_KEYS.has(key) && typeof value === "string") {
+    if (existing instanceof Y.Text) {
+      applyTextEdit(existing, value);
+    } else {
+      node.set(key, new Y.Text(value));
+    }
+    return;
+  }
+  if (GRANULAR_OBJECT_KEYS.has(key) && isPlainObject(value)) {
+    if (existing instanceof Y.Map) {
+      mergeYObject(existing, value);
+    } else {
+      node.set(key, toYObject(value));
+    }
+    return;
+  }
+  node.set(key, cloneJson(value));
 }
 
 function applyOneOp(doc: Y.Doc, op: JxDocOp): void {
@@ -69,10 +118,8 @@ function applyOneOp(doc: Y.Doc, op: JxDocOp): void {
       const node = requireNode(doc, op.path);
       if (op.value === undefined) {
         node.delete(op.key);
-      } else if (op.key === "children" && Array.isArray(op.value)) {
-        node.set(op.key, toYChildren(op.value));
       } else {
-        node.set(op.key, cloneJson(op.value));
+        setNodeKey(node, op.key, op.value);
       }
       return;
     }
@@ -97,6 +144,14 @@ function applyOneOp(doc: Y.Doc, op: JxDocOp): void {
       if (op.index < 0 || op.index >= children.length) {
         throw new CollabPathError([...op.parentPath, "children", op.index]);
       }
+      // Text child → text child: edit the existing Y.Text in place. A delete+insert would replace the
+      // Whole element and discard a peer's concurrent characters, which is the same clobber
+      // `setNodeKey` avoids for `textContent` — bare-string children are the other half of prose.
+      const existing = children.get(op.index);
+      if (existing instanceof Y.Text && typeof op.node === "string") {
+        applyTextEdit(existing, op.node);
+        return;
+      }
       children.delete(op.index, 1);
       children.insert(op.index, [toYChild(op.node)]);
       return;
@@ -139,6 +194,34 @@ export function applyDocOpsToY(doc: Y.Doc, ops: readonly JxDocOp[], origin: unkn
   }, origin);
 }
 
+/**
+ * When `path` addresses a granular container (or something nested inside one), the node that owns
+ * it and the key it sits under; otherwise null.
+ *
+ * The event path is relative to the structure map, so the first segment matching a granular key
+ * marks the boundary: everything before it is the node path, and anything after it is interior
+ * detail the op log does not model.
+ *
+ * `children`/index segments need no special handling: they are not granular keys, so the scan
+ * passes over them and the returned node path keeps the full prefix — `["children", 0, "style"]`
+ * resolves to the style of the node at `children/0`, not of the root.
+ */
+function granularOwner(path: JxPath): { nodePath: JxPath; key: string } | null {
+  for (let i = 0; i < path.length; i++) {
+    const segment = path[i];
+    if (typeof segment !== "string") {
+      continue;
+    }
+    if (GRANULAR_OBJECT_KEYS.has(segment)) {
+      return { key: segment, nodePath: path.slice(0, i) };
+    }
+    if (TEXT_KEYS.has(segment)) {
+      return { key: segment, nodePath: path.slice(0, i) };
+    }
+  }
+  return null;
+}
+
 function isStructurePath(segments: readonly (string | number)[]): segments is JxPath {
   return segments.every((seg) => typeof seg === "string" || typeof seg === "number");
 }
@@ -179,6 +262,45 @@ export function yEventsToDocOps(events: readonly Y.YEvent<never>[]): JxDocOp[] |
   const ops: JxDocOp[] = [];
   for (const event of events) {
     const path = event.path as JxPath;
+    /*
+     * A remote edit inside a granular container (a `Y.Text` for prose, a nested `Y.Map` for
+     * style/attributes/$props) reports its event at the CONTAINER's path, not the node's. Studio's op
+     * vocabulary addresses nodes, so those collapse back to one whole-value op for the owning key —
+     * the same shape a local mutator would have produced. Granularity buys merge; it deliberately does
+     * not leak into the op log, the canvas patcher, or the history ring.
+     */
+    const granular = granularOwner(path);
+    if (granular) {
+      const { doc } = event.target as { doc?: Y.Doc | null };
+      if (!doc) {
+        return null;
+      }
+      const container = resolveYPath(doc, [...granular.nodePath, granular.key]);
+      if (container === undefined) {
+        return null;
+      }
+      ops.push({
+        key: granular.key,
+        op: "set-key",
+        path: granular.nodePath,
+        value: yValueToJson(container),
+      });
+      continue;
+    }
+    if (event instanceof Y.YTextEvent) {
+      // A bare-string child: the text IS the child, so it round-trips as a child replacement.
+      const index = path.at(-1);
+      if (path.at(-2) === "children" && typeof index === "number") {
+        ops.push({
+          index,
+          node: (event.target as Y.Text).toString(),
+          op: "set-child",
+          parentPath: path.slice(0, -2),
+        });
+        continue;
+      }
+      return null;
+    }
     if (event instanceof Y.YMapEvent) {
       const target = event.target as Y.Map<unknown>;
       for (const [key, change] of event.changes.keys) {

package/src/schema.ts

@@ -4,15 +4,24 @@
  * Layout (all top-level types, created on demand): - `meta: Y.Map` — schemaVersion,
  * structureSeeded, canonical ("structure" | "source"), canonicalRev (representation-flip counter —
  * distinct from the provider's wire docEpoch), sourceFormat. - `frontmatter: Y.Map` — per-field
- * plain-JSON values (LWW per field). - `structure: Y.Map` — the root JxMutableNode. Every node is a
- * Y.Map whose ONLY nested Y container is "children" (a Y.Array of node Y.Maps and plain strings);
- * every other key holds a plain deep-JSON value merged whole (LWW). The CRDT granularity
- * deliberately equals Studio's op-log granularity — mutators emit whole-value set-keys and children
- * splices, so deeper Y types would add merge surface nothing can target. - `source: Y.Text` — the
- * serialized source. THE authoritative file content: providers persist
+ * plain-JSON values (LWW per field). - `structure: Y.Map` — the root JxMutableNode. - `source:
+ * Y.Text` — the serialized source. THE authoritative file content: providers persist
  * `getText("source").toString()` and never parse or serialize Jx documents themselves; the
  * structure tree is a Studio-side projection kept in sync by the bridge.
  *
+ * **CRDT granularity is deliberately FINER than Studio's op-log granularity.** Every node is a
+ * Y.Map; within it, "children" is a Y.Array, {@link TEXT_KEYS} are `Y.Text`,
+ * {@link GRANULAR_OBJECT_KEYS} are nested Y.Maps, and everything else is a whole-JSON LWW value.
+ *
+ * The two granularities used to match, on the reasoning that mutators emit whole-value set-keys so
+ * deeper Y types would add merge surface nothing targets. That reasoning was wrong: it conflated
+ * what an EDIT addresses with what a MERGE must resolve. Two authors typing in one paragraph, or
+ * setting `color` and `padding` on one element, produce whole-value ops that a whole-value CRDT can
+ * only resolve by discarding one of them. The bridge therefore diffs a whole-value op down onto the
+ * granular representation ({@link applyTextEdit}, {@link mergeYObject}) and {@link yValueToJson}
+ * reassembles whole values on the way out — so `JxDocOp`, the canvas patcher and the history ring
+ * are unchanged, while concurrent edits actually merge.
+ *
  * Seeding contract: providers seed only `source` (from file bytes). Clients derive `structure` on
  * first sync via {@link seedStructure}, which is convergence-safe under concurrent seeders because
  * it only performs whole-key Y.Map sets (per-key LWW picks one seeder's subtrees wholesale) — never
@@ -27,7 +36,16 @@ export const FRONTMATTER_KEY = "frontmatter";
 export const STRUCTURE_KEY = "structure";
 export const SOURCE_KEY = "source";
 
-export const COLLAB_SCHEMA_VERSION = 1;
+/**
+ * Bumped to 2 when prose moved to `Y.Text` and style/attributes/$props to nested `Y.Map`s.
+ *
+ * Written into `meta` at seed time and not currently validated on load. A room persisted under 1
+ * still READS correctly ({@link yValueToJson} passes plain values through) and self-heals on the
+ * first edit to a given key, since the bridge replaces a non-granular container. Two clients
+ * running DIFFERENT versions in one room would disagree about merge granularity — see §5 of
+ * specs/collab.md on version skew, which this does not attempt to solve.
+ */
+export const COLLAB_SCHEMA_VERSION = 2;
 
 export function metaMap(doc: Y.Doc): Y.Map<unknown> {
   return doc.getMap(META_KEY);
@@ -55,17 +73,137 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/** A children array becomes a Y.Array of node Y.Maps and plain strings. */
+/**
+ * Node keys whose STRING value is stored as a `Y.Text` rather than an opaque string.
+ *
+ * This is the character-level-collaboration decision. Whole-paragraph last-writer-wins was never a
+ * Yjs limitation — it was this schema storing prose as a plain LWW value, so two people typing in
+ * one paragraph clobbered each other and only `source` (which the canvas does not edit) merged per
+ * character.
+ *
+ * `innerHTML` is deliberately absent: it is an opaque markup blob, never caret-edited.
+ */
+export const TEXT_KEYS: ReadonlySet<string> = new Set(["textContent"]);
+
+/**
+ * Node keys stored as a nested `Y.Map` so concurrent edits to DIFFERENT properties both survive.
+ *
+ * `mutateUpdateStyle` and friends record a whole-object `set-key`, so writing the object as one LWW
+ * value meant A's `color` and B's `padding` raced and one lost. Per-property merge fixes that
+ * without touching the op vocabulary: {@link yValueToJson} reassembles the whole object on the way
+ * out, so `JxDocOp`, the canvas patcher and the history ring keep seeing whole values.
+ *
+ * Declaration VALUES stay plain (a CSS value is never partially edited); only the key space is
+ * granular. Nesting recurses, which covers `style`'s media (`@--sm`) and pseudo (`&:hover`)
+ * blocks.
+ */
+export const GRANULAR_OBJECT_KEYS: ReadonlySet<string> = new Set(["style", "attributes", "$props"]);
+
+/**
+ * Rewrite a `Y.Text` to `next` with a minimal edit (common prefix/suffix trimmed).
+ *
+ * Minimal rather than replace-all for two reasons: the wire carries only the delta, and — the
+ * load-bearing one — the surviving characters keep their identity, so a concurrent remote insert
+ * inside the untouched region merges instead of being clobbered. Returns false when already equal.
+ */
+export function applyTextEdit(text: Y.Text, next: string): boolean {
+  const current = text.toString();
+  if (current === next) {
+    return false;
+  }
+  let start = 0;
+  const minLen = Math.min(current.length, next.length);
+  while (start < minLen && current[start] === next[start]) {
+    start += 1;
+  }
+  let endCurrent = current.length;
+  let endNext = next.length;
+  while (endCurrent > start && endNext > start && current[endCurrent - 1] === next[endNext - 1]) {
+    endCurrent -= 1;
+    endNext -= 1;
+  }
+  if (endCurrent > start) {
+    text.delete(start, endCurrent - start);
+  }
+  if (endNext > start) {
+    text.insert(start, next.slice(start, endNext));
+  }
+  return true;
+}
+
+/** A plain object becomes a Y.Map, recursing into nested objects; other values stay plain JSON. */
+export function toYObject(value: Record<string, unknown>): Y.Map<unknown> {
+  const map = new Y.Map<unknown>();
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry === undefined) {
+      continue;
+    }
+    map.set(key, isPlainObject(entry) ? toYObject(entry) : cloneJson(entry));
+  }
+  return map;
+}
+
+/**
+ * Merge a plain object into an existing Y.Map per key: set changed keys, delete removed ones,
+ * recurse into nested maps. Whole-value replacement would mint a new Y.Map and discard a peer's
+ * concurrent edit to an untouched sibling property — the very thing granularity exists to prevent.
+ */
+export function mergeYObject(map: Y.Map<unknown>, value: Record<string, unknown>): void {
+  // Detached key list: deleting from a Y.Map while iterating its live keys is unsafe.
+  // oxlint-disable-next-line unicorn/no-useless-spread -- the copy is the point (mutation during iteration)
+  for (const key of [...map.keys()]) {
+    if (!(key in value) || value[key] === undefined) {
+      map.delete(key);
+    }
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry === undefined) {
+      continue;
+    }
+    const existing = map.get(key);
+    if (isPlainObject(entry)) {
+      if (existing instanceof Y.Map) {
+        mergeYObject(existing, entry);
+      } else {
+        map.set(key, toYObject(entry));
+      }
+    } else if (!deepEqualJson(existing, entry)) {
+      map.set(key, cloneJson(entry));
+    }
+  }
+}
+
+/** Structural equality over plain JSON, used to skip no-op key writes. */
+function deepEqualJson(a: unknown, b: unknown): boolean {
+  if (a === b) {
+    return true;
+  }
+  if (a instanceof Y.Map || a instanceof Y.Array || a instanceof Y.Text) {
+    return false;
+  }
+  return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+
+/** A child value: a bare string becomes a Y.Text (per-character merge), a node becomes a Y.Map. */
+export function toYChild(child: unknown): unknown {
+  return typeof child === "string" ? new Y.Text(child) : toYNode(child);
+}
+
+/** A children array becomes a Y.Array of node Y.Maps and Y.Texts. */
 export function toYChildren(children: readonly unknown[]): Y.Array<unknown> {
   const arr = new Y.Array<unknown>();
   arr.insert(
     0,
-    children.map((child) => (typeof child === "string" ? child : toYNode(child))),
+    children.map((child) => toYChild(child)),
   );
   return arr;
 }
 
-/** A node object becomes a Y.Map; only its "children" key nests further Y types. */
+/**
+ * A node object becomes a Y.Map. Nesting is no longer limited to `children`: text keys become
+ * `Y.Text` and {@link GRANULAR_OBJECT_KEYS} become nested `Y.Map`s, so the CRDT merges at the
+ * granularity edits actually happen at. Everything else stays a whole-JSON LWW value.
+ */
 export function toYNode(node: unknown): Y.Map<unknown> {
   if (!isPlainObject(node)) {
     throw new TypeError("collab-schema: a document node must be a plain object");
@@ -77,6 +215,10 @@ export function toYNode(node: unknown): Y.Map<unknown> {
     }
     if (key === "children" && Array.isArray(value)) {
       map.set(key, toYChildren(value));
+    } else if (TEXT_KEYS.has(key) && typeof value === "string") {
+      map.set(key, new Y.Text(value));
+    } else if (GRANULAR_OBJECT_KEYS.has(key) && isPlainObject(value)) {
+      map.set(key, toYObject(value));
     } else {
       map.set(key, cloneJson(value));
     }
@@ -84,7 +226,7 @@ export function toYNode(node: unknown): Y.Map<unknown> {
   return map;
 }
 
-/** Convert any structure value (Y.Map node, Y.Array children, or plain leaf) back to JSON. */
+/** Convert any structure value (Y.Map, Y.Array, Y.Text, or plain leaf) back to JSON. */
 export function yValueToJson(value: unknown): unknown {
   if (value instanceof Y.Map) {
     const out: Record<string, unknown> = {};
@@ -96,6 +238,9 @@ export function yValueToJson(value: unknown): unknown {
   if (value instanceof Y.Array) {
     return value.toArray().map((entry) => yValueToJson(entry));
   }
+  if (value instanceof Y.Text) {
+    return value.toString();
+  }
   return value;
 }
 
@@ -132,28 +277,11 @@ export function resolveYPath(doc: Y.Doc, path: JxPath): unknown {
  */
 export function updateSourceText(doc: Y.Doc, next: string, origin?: unknown): boolean {
   const text = sourceText(doc);
-  const current = text.toString();
-  if (current === next) {
+  if (text.toString() === next) {
     return false;
   }
-  let start = 0;
-  const minLen = Math.min(current.length, next.length);
-  while (start < minLen && current[start] === next[start]) {
-    start += 1;
-  }
-  let endCurrent = current.length;
-  let endNext = next.length;
-  while (endCurrent > start && endNext > start && current[endCurrent - 1] === next[endNext - 1]) {
-    endCurrent -= 1;
-    endNext -= 1;
-  }
   doc.transact(() => {
-    if (endCurrent > start) {
-      text.delete(start, endCurrent - start);
-    }
-    if (endNext > start) {
-      text.insert(start, next.slice(start, endNext));
-    }
+    applyTextEdit(text, next);
   }, origin);
   return true;
 }

package/src/ws-client.ts

@@ -34,8 +34,17 @@ export interface WsLike {
 export interface WsCollabConnectionOptions {
   /** The ws(s):// endpoint for this project's collab socket. */
   url: string;
+  /**
+   * Subprotocols to offer (`Sec-WebSocket-Protocol`), normally `negotiateCollab`'s `offer`.
+   *
+   * Left empty or undefined deliberately when the server advertised none: RFC 6455 §4.1 makes a
+   * client that offers a subprotocol and receives no echo fail the connection, so an unconditional
+   * offer would break collab against every server built before negotiation shipped. The caller
+   * decides, from the capability probe, and `negotiate.ts` holds the reasoning.
+   */
+  protocols?: string[];
   /** WebSocket constructor override (tests, non-browser runtimes). */
-  webSocketImpl?: new (url: string) => WsLike;
+  webSocketImpl?: new (url: string, protocols?: string[]) => WsLike;
   /**
    * Called when the server refuses a doc with content-not-loaded: hydrate the file over HTTP (which
    * caches it server-side) so the retry can seed. One retry per open.
@@ -74,7 +83,8 @@ interface DocEntry {
 
 export function createWsCollabConnection(options: WsCollabConnectionOptions): WsCollabConnection {
   const WebSocketCtor =
-    options.webSocketImpl ?? (globalThis.WebSocket as unknown as new (url: string) => WsLike);
+    options.webSocketImpl ??
+    (globalThis.WebSocket as unknown as new (url: string, protocols?: string[]) => WsLike);
   const openTimeoutMs = options.openTimeoutMs ?? 10_000;
   const docs = new Map<string, DocEntry>();
   const statusCbs = new Set<(status: CollabStatus) => void>();
@@ -257,7 +267,13 @@ export function createWsCollabConnection(options: WsCollabConnectionOptions): Ws
       return;
     }
     setStatus("connecting");
-    const ws = new WebSocketCtor(options.url);
+    /* Re-offered on every reconnect: a socket that comes back after the server was restarted must
+       negotiate again, and the offer is a property of this client's envelope, not of one socket. */
+    const offer = options.protocols;
+    const ws =
+      offer === undefined || offer.length === 0
+        ? new WebSocketCtor(options.url)
+        : new WebSocketCtor(options.url, offer);
     socket = ws;
     ws.binaryType = "arraybuffer";
     /* Each connect() builds a FRESH socket; single-assignment handlers are the point (and keep