@jxsuite/collab 0.11.1 → 0.11.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/collab",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "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": {
@@ -35,7 +35,7 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "^3.0.0",
+    "@jxsuite/schema": "^4.0.0",
     "lib0": "^0.2.119",
     "y-protocols": "^1.0.7",
     "yjs": "13.6.33"

package/src/diff-core.ts

@@ -13,11 +13,12 @@
  * identical siblings therefore degrade to remove+insert — exactly what the Y move mapping does, so
  * no fidelity is lost relative to the wire.
  *
- * **This file has no runtime imports, and that is its reason for existing.** It was the top of
- * `./diff.ts`, which value-imports `./schema.ts` for `replaceYStructure` alone — and `schema.ts`
- * imports yjs. So every consumer of the alignment logic paid for yjs, which put the studio's diff
- * highlighting (`canvas/diff-marks.ts`) behind a lazy import for a computation that never touches a
- * Y type. `diff.ts` re-exports everything here, so nothing that already imported it changed.
+ * **This file imports nothing that reaches yjs, and that is its reason for existing.** Its only
+ * runtime import is the dependency-free `@jxsuite/schema/guards`. It was the top of `./diff.ts`,
+ * which value-imports `./schema.ts` for `replaceYStructure` alone — and `schema.ts` imports yjs. So
+ * every consumer of the alignment logic paid for yjs, which put the studio's diff highlighting
+ * (`canvas/diff-marks.ts`) behind a lazy import for a computation that never touches a Y type.
+ * `diff.ts` re-exports everything here, so nothing that already imported it changed.
  *
  * {@link matchChildren} is exported for that studio caller: `diffDocs` emits a REPLAY SCRIPT whose
  * paths are post-splice coordinates valid only in `b`, and a side-by-side comparison needs both
@@ -25,7 +26,8 @@
  * it would mean a second definition of "the same node".
  */
 
-import type { JxMutableNode, JxPath } from "@jxsuite/schema/types";
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import type { JxDocumentValue, JxMutableNode, JxPath } from "@jxsuite/schema/types";
 import type { JxDocOp } from "./ops.ts";
 
 export interface DiffOptions {
@@ -36,22 +38,21 @@ export interface DiffOptions {
 const DEFAULT_MAX_OPS = 500;
 
 class MaxOpsExceededError extends Error {
-  override name = "MaxOpsExceededError";
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+  constructor() {
+    super();
+    this.name = "MaxOpsExceededError";
+  }
 }
 
 /** Order-insensitive for object keys, order-sensitive for arrays. */
-export function deepEqual(a: unknown, b: unknown): boolean {
+export function deepEqual(a: JxDocumentValue | undefined, b: JxDocumentValue | undefined): boolean {
   if (a === b) {
     return true;
   }
   if (Array.isArray(a) && Array.isArray(b)) {
     return a.length === b.length && a.every((item, i) => deepEqual(item, b[i]));
   }
-  if (isPlainObject(a) && isPlainObject(b)) {
+  if (isJsonObject(a) && isJsonObject(b)) {
     const keysA = Object.keys(a);
     const keysB = Object.keys(b);
     return (
@@ -70,23 +71,22 @@ function contentHash(text: string): string {
 }
 
 /** Full-content identity: equal strong keys mean "treat as the same unchanged child". */
-function strongKey(item: unknown): string {
-  return typeof item === "string" ? `s:${item}` : `n:${contentHash(JSON.stringify(item))}`;
+function strongKey(item: JxMutableNode | string): string {
+  return isString(item) ? `s:${item}` : `n:${contentHash(JSON.stringify(item))}`;
 }
 
 /** Alignment identity: equal weak keys mean "same logical child, diff its contents". */
-function weakKey(item: unknown): string {
-  if (typeof item === "string") {
+function weakKey(item: JxMutableNode | string): string {
+  if (isString(item)) {
     return "s";
   }
-  const node = item as Record<string, unknown>;
-  const attrs = node["attributes"];
-  const props = node["$props"];
+  const attrs = item["attributes"];
+  const props = item["$props"];
   const id =
-    (isPlainObject(attrs) ? attrs["id"] : undefined) ??
-    (isPlainObject(props) ? props["key"] : undefined) ??
+    (isJsonObject(attrs) ? attrs["id"] : undefined) ??
+    (isJsonObject(props) ? props["key"] : undefined) ??
     "";
-  return `w:${String(node["tagName"] ?? "")}:${String(id)}`;
+  return `w:${String(item["tagName"] ?? "")}:${String(id)}`;
 }
 
 /**
@@ -160,8 +160,8 @@ export interface MatchOptions {
  * exists to prevent.
  */
 export function matchChildren(
-  a: readonly unknown[],
-  b: readonly unknown[],
+  a: readonly (JxMutableNode | string)[],
+  b: readonly (JxMutableNode | string)[],
   opts: MatchOptions = {},
 ): ChildMatch[] {
   const maxCells = opts.maxCells ?? Number.POSITIVE_INFINITY;
@@ -195,75 +195,75 @@ export function matchChildren(
   return matches.toSorted((x, y) => x.aIndex - y.aIndex);
 }
 
-class Differ {
-  private readonly ops: JxDocOp[] = [];
-  private readonly maxOps: number;
-
-  constructor(maxOps: number) {
-    this.maxOps = maxOps;
-  }
-
-  result(): JxDocOp[] {
-    return this.ops;
-  }
+/**
+ * The ops emitted so far and the ceiling on them. A plain record threaded through the recursion
+ * rather than a class: it carries no behaviour of its own.
+ */
+interface DiffScript {
+  readonly ops: JxDocOp[];
+  readonly maxOps: number;
+}
 
-  private push(op: JxDocOp): void {
-    if (this.ops.length >= this.maxOps) {
-      throw new MaxOpsExceededError();
-    }
-    this.ops.push(op);
+function pushOp(script: DiffScript, op: JxDocOp): void {
+  if (script.ops.length >= script.maxOps) {
+    throw new MaxOpsExceededError();
   }
+  script.ops.push(op);
+}
 
-  diffNode(path: JxPath, a: Record<string, unknown>, b: Record<string, unknown>): void {
-    for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
-      if (key === "children") {
-        continue;
-      }
-      if (!(key in b)) {
-        this.push({ key, op: "set-key", path });
-      } else if (!deepEqual(a[key], b[key])) {
-        this.push({ key, op: "set-key", path, value: b[key] });
-      }
+function diffNode(script: DiffScript, path: JxPath, a: JxMutableNode, b: JxMutableNode): void {
+  for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
+    if (key === "children") {
+      continue;
     }
-    const ca = a["children"];
-    const cb = b["children"];
-    if (Array.isArray(ca) && Array.isArray(cb)) {
-      this.diffChildren(path, ca, cb);
-    } else if (!deepEqual(ca, cb)) {
-      // Mapped-array children (or one side missing entirely) replace whole, like the mutators do.
-      this.push({ key: "children", op: "set-key", path, value: cb });
+    if (!(key in b)) {
+      pushOp(script, { key, op: "set-key", path });
+    } else if (!deepEqual(a[key], b[key])) {
+      pushOp(script, { key, op: "set-key", path, value: b[key] });
     }
   }
+  const ca = a["children"];
+  const cb = b["children"];
+  if (Array.isArray(ca) && Array.isArray(cb)) {
+    diffChildren(script, path, ca, cb);
+  } else if (!deepEqual(ca, cb)) {
+    // Mapped-array children (or one side missing entirely) replace whole, like the mutators do.
+    pushOp(script, { key: "children", op: "set-key", path, value: cb });
+  }
+}
 
-  private diffChildren(path: JxPath, a: readonly unknown[], b: readonly unknown[]): void {
-    const matches = matchChildren(a, b);
-    const matchedA = new Set(matches.map((match) => match.aIndex));
-    const byB = new Map(matches.map((match) => [match.bIndex, match]));
+function diffChildren(
+  script: DiffScript,
+  path: JxPath,
+  a: readonly (JxMutableNode | string)[],
+  b: readonly (JxMutableNode | string)[],
+): void {
+  const matches = matchChildren(a, b);
+  const matchedA = new Set(matches.map((match) => match.aIndex));
+  const byB = new Map(matches.map((match) => [match.bIndex, match]));
 
-    // Removals first, in descending original index — each splice leaves lower indices intact.
-    for (let i = a.length - 1; i >= 0; i--) {
-      if (!matchedA.has(i)) {
-        this.push({ index: i, op: "remove-child", parentPath: path });
-      }
+  // Removals first, in descending original index — each splice leaves lower indices intact.
+  for (let i = a.length - 1; i >= 0; i--) {
+    if (!matchedA.has(i)) {
+      pushOp(script, { index: i, op: "remove-child", parentPath: path });
+    }
+  }
+  // Then walk b ascending: inserts land at their final index; matched pairs already sit there
+  // (matches never cross), so recursion paths are valid as emitted.
+  for (const [i, bItem] of b.entries()) {
+    const match = byB.get(i);
+    if (!match) {
+      pushOp(script, { index: i, node: bItem, op: "insert-child", parentPath: path });
+      continue;
+    }
+    if (match.identical) {
+      continue;
     }
-    // Then walk b ascending: inserts land at their final index; matched pairs already sit there
-    // (matches never cross), so recursion paths are valid as emitted.
-    for (let i = 0; i < b.length; i++) {
-      const match = byB.get(i);
-      if (!match) {
-        this.push({ index: i, node: b[i], op: "insert-child", parentPath: path });
-        continue;
-      }
-      if (match.identical) {
-        continue;
-      }
-      const aItem = a[match.aIndex];
-      const bItem = b[i];
-      if (isPlainObject(aItem) && isPlainObject(bItem)) {
-        this.diffNode([...path, "children", i], aItem, bItem);
-      } else if (!deepEqual(aItem, bItem)) {
-        this.push({ index: i, node: bItem, op: "set-child", parentPath: path });
-      }
+    const aItem = a[match.aIndex];
+    if (isJsonObject(aItem) && isJsonObject(bItem)) {
+      diffNode(script, [...path, "children", i], aItem, bItem);
+    } else if (!deepEqual(aItem, bItem)) {
+      pushOp(script, { index: i, node: bItem, op: "set-child", parentPath: path });
     }
   }
 }
@@ -277,14 +277,14 @@ export function diffDocs(
   b: JxMutableNode,
   opts: DiffOptions = {},
 ): JxDocOp[] | null {
-  const differ = new Differ(opts.maxOps ?? DEFAULT_MAX_OPS);
+  const script: DiffScript = { maxOps: opts.maxOps ?? DEFAULT_MAX_OPS, ops: [] };
   try {
-    differ.diffNode([], a as Record<string, unknown>, b as Record<string, unknown>);
+    diffNode(script, [], a, b);
   } catch (error) {
     if (error instanceof MaxOpsExceededError) {
       return null;
     }
     throw error;
   }
-  return differ.result();
+  return script.ops;
 }

package/src/diff.ts

@@ -9,6 +9,7 @@
  * a yjs-sized chunk with them.
  */
 
+import { cloneValue } from "@jxsuite/schema/doc-ops";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 import { metaMap, structureMap, toYChildren } from "./schema.ts";
 import type * as Y from "yjs";
@@ -19,26 +20,24 @@ export * from "./diff-core.ts";
  * Hard-replace the structure tree with `document` (the diff-overflow escape hatch) and bump the
  * in-doc canonicalRev so stale mirror writes computed against the old tree are discarded.
  */
-export function replaceYStructure(doc: Y.Doc, document: JxMutableNode, origin: unknown): void {
+export function replaceYStructure(doc: Y.Doc, document: JxMutableNode, origin: string): void {
   doc.transact(() => {
     const structure = structureMap(doc);
-    const next = document as Record<string, unknown>;
     // Detached copy: keys are deleted while iterating.
     const existingKeys = [...structure.keys()];
     for (const key of existingKeys) {
-      if (!(key in next) || next[key] === undefined) {
+      if (!(key in document) || document[key] === undefined) {
         structure.delete(key);
       }
     }
-    for (const [key, value] of Object.entries(next)) {
+    for (const [key, value] of Object.entries(document)) {
       if (value === undefined) {
         continue;
       }
       if (key === "children" && Array.isArray(value)) {
         structure.set(key, toYChildren(value));
       } else {
-        // oxlint-disable-next-line unicorn/prefer-structured-clone -- JSON normalization is the point
-        structure.set(key, JSON.parse(JSON.stringify(value)));
+        structure.set(key, cloneValue(value));
       }
     }
     const meta = metaMap(doc);

package/src/envelope.ts

@@ -22,6 +22,7 @@
 
 import * as decoding from "lib0/decoding";
 import * as encoding from "lib0/encoding";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 
 export { COLLAB_SUBPROTOCOL } from "./negotiate.ts";
 
@@ -79,8 +80,18 @@ export class EnvelopeError extends Error {
   }
 }
 
+/**
+ * A parsed control payload: an object whose `type` is a string. That is all the envelope checks;
+ * each receiver dispatches on `type` and skips a kind it does not know.
+ */
+function isControlMessage(value: unknown): value is ControlMessage {
+  return isNonNullObject(value) && "type" in value && isString(value.type);
+}
+
 export function encodeFrame(frame: CollabFrame): Uint8Array {
   const encoder = encoding.createEncoder();
+  // Read before the switch: a caller outside the type system may pass a kind the union does not name.
+  const { type: kind } = frame;
   switch (frame.type) {
     case "doc-sync": {
       encoding.writeVarUint(encoder, FRAME_DOC_SYNC);
@@ -105,7 +116,7 @@ export function encodeFrame(frame: CollabFrame): Uint8Array {
       break;
     }
     default: {
-      throw new EnvelopeError(`unknown-frame:${(frame as CollabFrame).type}`);
+      throw new EnvelopeError(`unknown-frame:${kind}`);
     }
   }
   return encoding.toUint8Array(encoder);
@@ -129,8 +140,8 @@ export function decodeFrame(data: Uint8Array): CollabFrame {
         return { path: decoding.readVarString(decoder), type: "doc-close" };
       }
       case FRAME_CONTROL: {
-        const message = JSON.parse(decoding.readVarString(decoder)) as ControlMessage;
-        if (typeof message !== "object" || typeof message.type !== "string") {
+        const message: unknown = JSON.parse(decoding.readVarString(decoder));
+        if (!isControlMessage(message)) {
           throw new EnvelopeError("malformed-control");
         }
         return { message, type: "control" };

package/src/negotiate.ts

@@ -21,10 +21,14 @@
  * 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.
+ * This module imports nothing but the dependency-free `@jxsuite/schema/guards`, 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.
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
+
 /** The subprotocol token for the envelope in `envelope.ts`. One token per envelope major. */
 export const COLLAB_SUBPROTOCOL = "jx.collab.v1";
 
@@ -47,22 +51,22 @@ export interface CollabNegotiation {
 /**
  * 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.
+ * @param {JsonValue} 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.
+export function negotiateCollab(probe: JsonValue): CollabNegotiation {
+  if (!isJsonObject(probe)) {
+    /* A 200 that is not a JSON object: pre-negotiation server. Connect as before, offering nothing.
+       (A JSON array lands here too; it carries no `protocols`, so it always meant the same.) */
     return { offer: [], refused: null };
   }
-  const body = probe as { collab?: unknown; detail?: unknown; protocols?: unknown };
-  if (body.collab === false) {
+  const { collab, detail, protocols } = probe;
+  if (collab === false) {
     /* The server's own sentence wins when it sends one. "Disabled" is true of a flag that is off,
        and false of a room an action would open: that server knows which it is and says so. */
-    const detail = typeof body.detail === "string" ? body.detail.trim() : "";
-    return { offer: [], refused: detail || "This server has collaboration disabled." };
+    const sentence = isString(detail) ? detail.trim() : "";
+    return { offer: [], refused: sentence || "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 };
@@ -70,7 +74,7 @@ export function negotiateCollab(probe: unknown): CollabNegotiation {
   if (protocols.includes(COLLAB_SUBPROTOCOL)) {
     return { offer: [COLLAB_SUBPROTOCOL], refused: null };
   }
-  const theirs = protocols.filter((p) => typeof p === "string").join(", ") || "none";
+  const theirs = protocols.filter((p) => isString(p)).join(", ") || "none";
   return {
     offer: [],
     refused: `This server speaks collab envelope ${theirs}; this editor speaks ${COLLAB_SUBPROTOCOL}.`,

package/src/op-bridge.ts

@@ -12,7 +12,9 @@
  */
 
 import * as Y from "yjs";
-import type { JxPath } from "@jxsuite/schema/types";
+import { cloneValue } from "@jxsuite/schema/doc-ops";
+import { isJsonObject, isNumber, isString } from "@jxsuite/schema/guards";
+import type { JxDocumentValue, JxPath } from "@jxsuite/schema/types";
 import type { JxDocOp } from "./ops.ts";
 import {
   applyTextEdit,
@@ -23,8 +25,10 @@ import {
   toYChild,
   toYChildren,
   toYObject,
+  yChildToJson,
   yValueToJson,
 } from "./schema.ts";
+import type { YStructureValue } from "./schema.ts";
 
 /** Origin of Y transactions produced by mirroring the local tab's ops. */
 export const LOCAL_ORIGIN = "jx-local";
@@ -41,7 +45,7 @@ export class CollabPathError extends Error {
   }
 }
 
-function requireNode(doc: Y.Doc, path: JxPath): Y.Map<unknown> {
+function requireNode(doc: Y.Doc, path: JxPath): Y.Map<YStructureValue> {
   const target = resolveYPath(doc, path);
   if (!(target instanceof Y.Map)) {
     throw new CollabPathError(path);
@@ -49,30 +53,20 @@ function requireNode(doc: Y.Doc, path: JxPath): Y.Map<unknown> {
   return target;
 }
 
-function childrenOf(doc: Y.Doc, parentPath: JxPath, create: boolean): Y.Array<unknown> {
+function childrenOf(doc: Y.Doc, parentPath: JxPath, create: boolean): Y.Array<YStructureValue> {
   const parent = requireNode(doc, parentPath);
   const children = parent.get("children");
   if (children instanceof Y.Array) {
     return children;
   }
   if (create && children === undefined) {
-    const fresh = new Y.Array<unknown>();
+    const fresh = new Y.Array<YStructureValue>();
     parent.set("children", fresh);
     return fresh;
   }
   throw new CollabPathError([...parentPath, "children"]);
 }
 
-/** JSON round-trip clone (matches the ops applier's normalization). */
-function cloneJson<T>(value: T): T {
-  // oxlint-disable-next-line unicorn/prefer-structured-clone -- JSON normalization is the point
-  return JSON.parse(JSON.stringify(value)) as T;
-}
-
-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.
  *
@@ -87,13 +81,13 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
  * 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 {
+function setNodeKey(node: Y.Map<YStructureValue>, key: string, value: JxDocumentValue): 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 (TEXT_KEYS.has(key) && isString(value)) {
     if (existing instanceof Y.Text) {
       applyTextEdit(existing, value);
     } else {
@@ -101,7 +95,7 @@ function setNodeKey(node: Y.Map<unknown>, key: string, value: unknown): void {
     }
     return;
   }
-  if (GRANULAR_OBJECT_KEYS.has(key) && isPlainObject(value)) {
+  if (GRANULAR_OBJECT_KEYS.has(key) && isJsonObject(value)) {
     if (existing instanceof Y.Map) {
       mergeYObject(existing, value);
     } else {
@@ -109,10 +103,12 @@ function setNodeKey(node: Y.Map<unknown>, key: string, value: unknown): void {
     }
     return;
   }
-  node.set(key, cloneJson(value));
+  node.set(key, cloneValue(value));
 }
 
 function applyOneOp(doc: Y.Doc, op: JxDocOp): void {
+  // Read before the switch: an op from outside may carry a kind the union does not name.
+  const { op: kind } = op;
   switch (op.op) {
     case "set-key": {
       const node = requireNode(doc, op.path);
@@ -148,7 +144,7 @@ function applyOneOp(doc: Y.Doc, op: JxDocOp): void {
       // 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") {
+      if (existing instanceof Y.Text && isString(op.node)) {
         applyTextEdit(existing, op.node);
         return;
       }
@@ -176,7 +172,7 @@ function applyOneOp(doc: Y.Doc, op: JxDocOp): void {
       return;
     }
     default: {
-      throw new Error(`unknown-doc-op:${(op as JxDocOp).op}`);
+      throw new Error(`unknown-doc-op:${kind}`);
     }
   }
 }
@@ -186,7 +182,7 @@ function applyOneOp(doc: Y.Doc, op: JxDocOp): void {
  * when any op's path does not resolve — the transaction still commits the ops applied before the
  * failure, so callers catching it must reconcile by diff (which corrects any partial state).
  */
-export function applyDocOpsToY(doc: Y.Doc, ops: readonly JxDocOp[], origin: unknown): void {
+export function applyDocOpsToY(doc: Y.Doc, ops: readonly JxDocOp[], origin: string): void {
   doc.transact(() => {
     for (const op of ops) {
       applyOneOp(doc, op);
@@ -209,7 +205,7 @@ export function applyDocOpsToY(doc: Y.Doc, ops: readonly JxDocOp[], origin: unkn
 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") {
+    if (!isString(segment)) {
       continue;
     }
     if (GRANULAR_OBJECT_KEYS.has(segment)) {
@@ -222,8 +218,17 @@ function granularOwner(path: JxPath): { nodePath: JxPath; key: string } | null {
   return null;
 }
 
+/**
+ * Whether a remote children-array item has a shape this package writes: a node Y.Map or a Y.Text
+ * (`toYChild`), or a plain string from a peer still on schema version 1. Anything else came from an
+ * off-contract peer, so the inbound fast path bails and the caller reconciles by diffing.
+ */
+function isChildItem(item: unknown): item is Y.Text | Y.Map<YStructureValue> | string {
+  return item instanceof Y.Text || item instanceof Y.Map || isString(item);
+}
+
 function isStructurePath(segments: readonly (string | number)[]): segments is JxPath {
-  return segments.every((seg) => typeof seg === "string" || typeof seg === "number");
+  return segments.every((seg) => isString(seg) || isNumber(seg));
 }
 
 /**
@@ -232,7 +237,9 @@ function isStructurePath(segments: readonly (string | number)[]): segments is Jx
  * overlapping events, more than one array event, or non-contiguous delete runs — and the caller
  * must reconcile by diffing instead.
  */
-export function yEventsToDocOps(events: readonly Y.YEvent<never>[]): JxDocOp[] | null {
+export function yEventsToDocOps(
+  events: readonly Y.YEvent<Y.AbstractType<unknown>>[],
+): JxDocOp[] | null {
   if (events.length === 0) {
     return [];
   }
@@ -261,7 +268,7 @@ export function yEventsToDocOps(events: readonly Y.YEvent<never>[]): JxDocOp[] |
 
   const ops: JxDocOp[] = [];
   for (const event of events) {
-    const path = event.path as JxPath;
+    const { path } = event;
     /*
      * 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
@@ -271,7 +278,7 @@ export function yEventsToDocOps(events: readonly Y.YEvent<never>[]): JxDocOp[] |
      */
     const granular = granularOwner(path);
     if (granular) {
-      const { doc } = event.target as { doc?: Y.Doc | null };
+      const { doc } = event.target;
       if (!doc) {
         return null;
       }
@@ -290,10 +297,10 @@ export function yEventsToDocOps(events: readonly Y.YEvent<never>[]): JxDocOp[] |
     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") {
+      if (path.at(-2) === "children" && isNumber(index)) {
         ops.push({
           index,
-          node: (event.target as Y.Text).toString(),
+          node: event.target.toString(),
           op: "set-child",
           parentPath: path.slice(0, -2),
         });
@@ -302,7 +309,10 @@ export function yEventsToDocOps(events: readonly Y.YEvent<never>[]): JxDocOp[] |
       return null;
     }
     if (event instanceof Y.YMapEvent) {
-      const target = event.target as Y.Map<unknown>;
+      /* SAFETY: these events come from observing the structure map, and a map event that reached
+         here is not inside a granular container (handled above), so its target is a node Y.Map,
+         which the writers in ./schema.ts fill only with YStructureValue entries. */
+      const target = event.target as Y.Map<YStructureValue>;
       for (const [key, change] of event.changes.keys) {
         if (change.action === "delete") {
           ops.push({ key, op: "set-key", path });
@@ -327,7 +337,10 @@ export function yEventsToDocOps(events: readonly Y.YEvent<never>[]): JxDocOp[] |
         } else if (delta.insert !== undefined) {
           const items = Array.isArray(delta.insert) ? delta.insert : [delta.insert];
           for (const item of items) {
-            ops.push({ index, node: yValueToJson(item), op: "insert-child", parentPath });
+            if (!isChildItem(item)) {
+              return null;
+            }
+            ops.push({ index, node: yChildToJson(item), op: "insert-child", parentPath });
             index += 1;
           }
         }

package/src/reconnect.ts

@@ -89,11 +89,7 @@ export function createReconnectScheduler(
   connect: () => void,
   opts: ReconnectPolicy & ReconnectWakeSources = {},
 ): ReconnectScheduler {
-  const win =
-    opts.win ??
-    (typeof window === "undefined"
-      ? undefined
-      : (window as Pick<Window, "addEventListener" | "removeEventListener">));
+  const win = opts.win ?? (typeof window === "undefined" ? undefined : window);
   const doc = opts.doc ?? (typeof document === "undefined" ? undefined : document);
   let attempt = 0;
   let timer: ReturnType<typeof setTimeout> | null = null;
@@ -118,9 +114,9 @@ export function createReconnectScheduler(
     fire();
   };
 
-  const onPageShow = (event: Event) => {
+  const onPageShow = (event: PageTransitionEvent) => {
     // A fresh load is not a wake: only a page restored from the back/forward cache was frozen.
-    if ((event as PageTransitionEvent).persisted) {
+    if (event.persisted) {
       wake();
     }
   };

package/src/schema.ts

@@ -29,7 +29,9 @@
  */
 
 import * as Y from "yjs";
-import type { JxMutableNode, JxPath } from "@jxsuite/schema/types";
+import { cloneValue } from "@jxsuite/schema/doc-ops";
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import type { JxDocumentValue, JxMutableNode, JxPath } from "@jxsuite/schema/types";
 
 export const META_KEY = "meta";
 export const FRONTMATTER_KEY = "frontmatter";
@@ -47,6 +49,33 @@ export const SOURCE_KEY = "source";
  */
 export const COLLAB_SCHEMA_VERSION = 2;
 
+/**
+ * What one slot of the structure tree holds: a node or granular-object `Y.Map`, a children
+ * `Y.Array`, a prose `Y.Text`, or a whole-JSON LWW leaf. Every writer in this package goes through
+ * {@link toYNode}, {@link toYChildren}, {@link toYObject} or a JSON clone, so nothing else is ever
+ * stored there.
+ */
+export type YStructureValue =
+  | Y.Map<YStructureValue>
+  | Y.Array<YStructureValue>
+  | Y.Text
+  | JxDocumentValue;
+
+/**
+ * A plain object read out of, or written into, the structure tree: a node, a style block, an
+ * attribute map. A key an editor cleared may still hold `undefined`, which every writer skips.
+ */
+export type DocumentRecord = Record<string, JxDocumentValue | undefined>;
+
+/**
+ * A plain object (not null, not an array). Only the shape is checked: its values are whatever the
+ * document holds, including the `undefined` a cleared key leaves behind, which is why this narrows
+ * to {@link DocumentRecord} rather than a fully-validated JSON object.
+ */
+function isDocumentRecord(value: JxDocumentValue | undefined): value is DocumentRecord {
+  return isJsonObject(value);
+}
+
 export function metaMap(doc: Y.Doc): Y.Map<unknown> {
   return doc.getMap(META_KEY);
 }
@@ -55,24 +84,18 @@ export function frontmatterMap(doc: Y.Doc): Y.Map<unknown> {
   return doc.getMap(FRONTMATTER_KEY);
 }
 
-export function structureMap(doc: Y.Doc): Y.Map<unknown> {
-  return doc.getMap(STRUCTURE_KEY);
+/**
+ * The root node's `Y.Map`. Its type argument is the {@link YStructureValue} invariant the writers in
+ * this module maintain; Yjs itself does not check what a map holds.
+ */
+export function structureMap(doc: Y.Doc): Y.Map<YStructureValue> {
+  return doc.getMap<YStructureValue>(STRUCTURE_KEY);
 }
 
 export function sourceText(doc: Y.Doc): Y.Text {
   return doc.getText(SOURCE_KEY);
 }
 
-/** JSON round-trip clone (normalizes away proxies/undefined; matches the ops applier). */
-function cloneJson<T>(value: T): T {
-  // oxlint-disable-next-line unicorn/prefer-structured-clone -- JSON normalization is the point
-  return JSON.parse(JSON.stringify(value)) as T;
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * Node keys whose STRING value is stored as a `Y.Text` rather than an opaque string.
  *
@@ -132,13 +155,13 @@ export function applyTextEdit(text: Y.Text, next: string): boolean {
 }
 
 /** 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>();
+export function toYObject(value: DocumentRecord): Y.Map<YStructureValue> {
+  const map = new Y.Map<YStructureValue>();
   for (const [key, entry] of Object.entries(value)) {
     if (entry === undefined) {
       continue;
     }
-    map.set(key, isPlainObject(entry) ? toYObject(entry) : cloneJson(entry));
+    map.set(key, isDocumentRecord(entry) ? toYObject(entry) : cloneValue(entry));
   }
   return map;
 }
@@ -148,7 +171,7 @@ export function toYObject(value: Record<string, unknown>): Y.Map<unknown> {
  * 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 {
+export function mergeYObject(map: Y.Map<YStructureValue>, value: DocumentRecord): 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()]) {
@@ -161,20 +184,20 @@ export function mergeYObject(map: Y.Map<unknown>, value: Record<string, unknown>
       continue;
     }
     const existing = map.get(key);
-    if (isPlainObject(entry)) {
+    if (isDocumentRecord(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));
+      map.set(key, cloneValue(entry));
     }
   }
 }
 
 /** Structural equality over plain JSON, used to skip no-op key writes. */
-function deepEqualJson(a: unknown, b: unknown): boolean {
+function deepEqualJson(a: YStructureValue | undefined, b: JxDocumentValue): boolean {
   if (a === b) {
     return true;
   }
@@ -184,14 +207,17 @@ function deepEqualJson(a: unknown, b: unknown): boolean {
   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 child value: a bare string becomes a Y.Text (per-character merge), a node becomes a Y.Map.
+ * Anything else is not a child, and {@link toYNode} throws for it.
+ */
+export function toYChild(child: JxDocumentValue | undefined): Y.Text | Y.Map<YStructureValue> {
+  return isString(child) ? 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>();
+export function toYChildren(children: readonly JxDocumentValue[]): Y.Array<YStructureValue> {
+  const arr = new Y.Array<YStructureValue>();
   arr.insert(
     0,
     children.map((child) => toYChild(child)),
@@ -204,36 +230,54 @@ export function toYChildren(children: readonly unknown[]): Y.Array<unknown> {
  * `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)) {
+export function toYNode(node: JxDocumentValue | undefined): Y.Map<YStructureValue> {
+  if (!isDocumentRecord(node)) {
     throw new TypeError("collab-schema: a document node must be a plain object");
   }
-  const map = new Y.Map<unknown>();
+  const map = new Y.Map<YStructureValue>();
   for (const [key, value] of Object.entries(node)) {
     if (value === undefined) {
       continue;
     }
     if (key === "children" && Array.isArray(value)) {
       map.set(key, toYChildren(value));
-    } else if (TEXT_KEYS.has(key) && typeof value === "string") {
+    } else if (TEXT_KEYS.has(key) && isString(value)) {
       map.set(key, new Y.Text(value));
-    } else if (GRANULAR_OBJECT_KEYS.has(key) && isPlainObject(value)) {
+    } else if (GRANULAR_OBJECT_KEYS.has(key) && isDocumentRecord(value)) {
       map.set(key, toYObject(value));
     } else {
-      map.set(key, cloneJson(value));
+      map.set(key, cloneValue(value));
     }
   }
   return map;
 }
 
+/** A node or granular-object Y.Map back to its plain object (deep, detached copy). */
+function yMapToJson(map: Y.Map<YStructureValue>): DocumentRecord {
+  return Object.fromEntries(
+    Array.from(map.entries(), ([key, entry]) => [key, yValueToJson(entry)]),
+  );
+}
+
+/**
+ * A children-array member back to JSON: a Y.Text is a bare-string child, a Y.Map a node. A plain
+ * string is a bare-string child written under schema version 1, before prose moved to Y.Text.
+ */
+export function yChildToJson(
+  child: Y.Text | Y.Map<YStructureValue> | string,
+): JxMutableNode | string {
+  if (isString(child)) {
+    return child;
+  }
+  return child instanceof Y.Text ? child.toString() : yMapToJson(child);
+}
+
 /** Convert any structure value (Y.Map, Y.Array, Y.Text, or plain leaf) back to JSON. */
-export function yValueToJson(value: unknown): unknown {
+export function yValueToJson(value: YStructureValue): JxDocumentValue;
+export function yValueToJson(value: YStructureValue | undefined): JxDocumentValue | undefined;
+export function yValueToJson(value: YStructureValue | undefined): JxDocumentValue | undefined {
   if (value instanceof Y.Map) {
-    const out: Record<string, unknown> = {};
-    for (const [key, entry] of value.entries()) {
-      out[key] = yValueToJson(entry);
-    }
-    return out;
+    return yMapToJson(value);
   }
   if (value instanceof Y.Array) {
     return value.toArray().map((entry) => yValueToJson(entry));
@@ -246,20 +290,20 @@ export function yValueToJson(value: unknown): unknown {
 
 /** The whole structure tree as a plain document (deep, detached copy). */
 export function yDocToJson(doc: Y.Doc): JxMutableNode {
-  return yValueToJson(structureMap(doc)) as JxMutableNode;
+  return yMapToJson(structureMap(doc));
 }
 
 /**
  * Resolve a JxPath against the structure tree. Returns the Y value at the path (a node Y.Map, a
  * children Y.Array, a string child, or a plain leaf) or undefined when any segment is missing.
  */
-export function resolveYPath(doc: Y.Doc, path: JxPath): unknown {
-  let current: unknown = structureMap(doc);
+export function resolveYPath(doc: Y.Doc, path: JxPath): YStructureValue | undefined {
+  let current: YStructureValue | undefined = structureMap(doc);
   for (const segment of path) {
     if (current instanceof Y.Map) {
       current = current.get(String(segment));
     } else if (current instanceof Y.Array) {
-      const index = typeof segment === "number" ? segment : Number(segment);
+      const index = Number(segment);
       if (!Number.isInteger(index) || index < 0 || index >= current.length) {
         return undefined;
       }
@@ -275,7 +319,7 @@ export function resolveYPath(doc: Y.Doc, path: JxPath): unknown {
  * Update the source Y.Text to `next` with a minimal edit (common prefix/suffix trimmed), so mirror
  * refreshes don't ship the whole document over the wire. Returns false when already identical.
  */
-export function updateSourceText(doc: Y.Doc, next: string, origin?: unknown): boolean {
+export function updateSourceText(doc: Y.Doc, next: string, origin?: string): boolean {
   const text = sourceText(doc);
   if (text.toString() === next) {
     return false;
@@ -296,9 +340,9 @@ export function seedStructure(
   doc: Y.Doc,
   document: JxMutableNode,
   opts: {
-    frontmatter?: Record<string, unknown>;
+    frontmatter?: DocumentRecord;
     sourceFormat?: string | null;
-    origin?: unknown;
+    origin?: string;
   } = {},
 ): boolean {
   const meta = metaMap(doc);
@@ -314,13 +358,13 @@ export function seedStructure(
       if (key === "children" && Array.isArray(value)) {
         structure.set(key, toYChildren(value));
       } else {
-        structure.set(key, cloneJson(value));
+        structure.set(key, cloneValue(value));
       }
     }
     const frontmatter = frontmatterMap(doc);
     for (const [key, value] of Object.entries(opts.frontmatter ?? {})) {
       if (value !== undefined) {
-        frontmatter.set(key, cloneJson(value));
+        frontmatter.set(key, cloneValue(value));
       }
     }
     meta.set("schemaVersion", COLLAB_SCHEMA_VERSION);

package/src/source-lock.ts

@@ -30,7 +30,7 @@ export function canonicalRevOf(doc: Doc): number {
  * Flip canonical to "source", seeding the text from `serialized` (the flipper's serialization of
  * the current structure). No-op (false) when source already holds the lock.
  */
-export function acquireSourceCanonical(doc: Doc, serialized: string, origin: unknown): boolean {
+export function acquireSourceCanonical(doc: Doc, serialized: string, origin: string): boolean {
   if (canonicalOf(doc) === "source") {
     return false;
   }
@@ -44,7 +44,7 @@ export function acquireSourceCanonical(doc: Doc, serialized: string, origin: unk
 }
 
 /** Flip canonical back to "structure" (the mirror is the caller's responsibility beforehand). */
-export function releaseSourceCanonical(doc: Doc, origin: unknown): boolean {
+export function releaseSourceCanonical(doc: Doc, origin: string): boolean {
   if (canonicalOf(doc) !== "source") {
     return false;
   }
@@ -64,6 +64,9 @@ export function otherSourceEditors(
 ): number[] {
   const editors: number[] = [];
   for (const [clientId, raw] of awareness.getStates()) {
+    /* SAFETY: a peer publishes its own awareness state, so nothing is guaranteed about it, and
+       `Partial` keeps every field optional. The fields are only compared with `===` against a
+       literal or `path`, so a malformed state fails the match instead of being misread. */
     const state = raw as Partial<CollabAwarenessState>;
     if (clientId !== selfClientId && state.mode === "source" && state.focusedPath === path) {
       editors.push(clientId);
@@ -78,12 +81,17 @@ export function otherSourceEditors(
  */
 export function isSourceReconciler(awareness: Awareness, path: string): boolean {
   const self = awareness.clientID;
+  /* SAFETY: every awareness state is peer-published and unchecked (this one is our own, but read
+     back through the same untyped map). `Partial` keeps every field optional, and each is only
+     compared with `===`/`!==` against a literal or `path`, so a malformed state fails the match. */
   const selfState = awareness.getStates().get(self) as Partial<CollabAwarenessState> | undefined;
   if (selfState?.mode !== "source" || selfState.focusedPath !== path) {
     return false;
   }
   let lowest = self;
   for (const [clientId, raw] of awareness.getStates()) {
+    /* SAFETY: peer-published and unchecked; `mode`, `focusedPath` and `canWrite` are only compared
+       with `===`/`!==` against a literal or `path`, so a malformed state just loses the election. */
     const state = raw as Partial<CollabAwarenessState>;
     if (
       state.mode === "source" &&

package/src/ws-client.ts

@@ -18,6 +18,7 @@ import {
 import * as syncProtocol from "y-protocols/sync";
 import { decodeFrame, encodeFrame } from "./envelope.ts";
 import { createReconnectScheduler } from "./reconnect.ts";
+import type { ReconnectPolicy } from "./reconnect.ts";
 import type { CollabFrame, ControlMessage } from "./envelope.ts";
 import type { CollabHandle, CollabIdentity, CollabStatus } from "./provider.ts";
 
@@ -71,6 +72,13 @@ export interface WsCollabConnection {
 
 const WS_OPEN = 1;
 
+/**
+ * The origin a transaction on a handle's Y.Doc carries: a Jx writer's string tag (`"remote"` for an
+ * update this connection applied off the wire), the `Y.UndoManager` replaying an undo or redo, or
+ * `null` for an untagged transaction.
+ */
+type DocTransactionOrigin = string | Y.UndoManager | null;
+
 interface DocEntry {
   doc: Y.Doc;
   epoch: number;
@@ -89,9 +97,13 @@ interface DocEntry {
 }
 
 export function createWsCollabConnection(options: WsCollabConnectionOptions): WsCollabConnection {
+  /* SAFETY: a browser WebSocket does everything WsLike promises. The connection only sets
+     `binaryType`, reads `readyState`, sends a Uint8Array, closes, and assigns its own handlers,
+     which ignore the Event they are given and read only `data` off a MessageEvent. The declared
+     types differ only in the DOM handler signatures' `this` and event parameters. */
   const WebSocketCtor =
     options.webSocketImpl ??
-    (globalThis.WebSocket as unknown as new (url: string, protocols?: string[]) => WsLike);
+    (globalThis.WebSocket 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>();
@@ -135,7 +147,9 @@ export function createWsCollabConnection(options: WsCollabConnectionOptions): Ws
   // Reconnect via the full-state re-publish below).
   awareness.on(
     "update",
-    (changes: { added: number[]; updated: number[]; removed: number[] }, origin: unknown) => {
+    /* Every awareness origin is a string: "remote" for what came off the wire, "local" for
+       `setLocalState`, "destroy" for the teardown removal, and "timeout" for y-protocols' expiry. */
+    (changes: { added: number[]; updated: number[]; removed: number[] }, origin: string) => {
       if (origin === "remote") {
         return;
       }
@@ -147,13 +161,18 @@ export function createWsCollabConnection(options: WsCollabConnectionOptions): Ws
   const handleControl = (message: ControlMessage) => {
     switch (message.type) {
       case "hello": {
-        identity = {
+        const next: CollabIdentity = {
           color: message.color,
           login: message.login,
           permission: message.permission,
-          ...(message.name === undefined ? {} : { name: message.name }),
-          ...(message.avatarUrl === undefined ? {} : { avatarUrl: message.avatarUrl }),
         };
+        if (message.name !== undefined) {
+          next.name = message.name;
+        }
+        if (message.avatarUrl !== undefined) {
+          next.avatarUrl = message.avatarUrl;
+        }
+        identity = next;
         return;
       }
       case "opened": {
@@ -346,10 +365,14 @@ export function createWsCollabConnection(options: WsCollabConnectionOptions): Ws
       // The close handler follows and owns retry.
     };
   };
-  const reconnect = createReconnectScheduler(connect, {
-    ...(options.reconnectDelayMs === undefined ? {} : { baseMs: options.reconnectDelayMs }),
-    ...(options.reconnectRandom === undefined ? {} : { random: options.reconnectRandom }),
-  });
+  const policy: ReconnectPolicy = {};
+  if (options.reconnectDelayMs !== undefined) {
+    policy.baseMs = options.reconnectDelayMs;
+  }
+  if (options.reconnectRandom !== undefined) {
+    policy.random = options.reconnectRandom;
+  }
+  const reconnect = createReconnectScheduler(connect, policy);
   connect();
 
   return {
@@ -400,7 +423,7 @@ export function createWsCollabConnection(options: WsCollabConnectionOptions): Ws
       docs.set(path, entry);
 
       // Local doc updates go to the wire (unless they came FROM the wire).
-      entry.doc.on("update", (update: Uint8Array, origin: unknown) => {
+      entry.doc.on("update", (update: Uint8Array, origin: DocTransactionOrigin) => {
         if (origin === "remote" || !entry.opened) {
           return;
         }

package/src/ws-room.ts

@@ -16,6 +16,7 @@ import {
   removeAwarenessStates,
 } from "y-protocols/awareness";
 import * as syncProtocol from "y-protocols/sync";
+import { isString } from "@jxsuite/schema/guards";
 import { decodeFrame, encodeFrame } from "./envelope.ts";
 import type { CollabFrame, ControlMessage } from "./envelope.ts";
 import type { CollabIdentity } from "./provider.ts";
@@ -42,7 +43,7 @@ export interface CollabHostOptions {
 interface Room {
   doc: Y.Doc;
   epoch: number;
-  subscribers: Set<HostConnection>;
+  subscribers: Set<InternalConnection>;
   ready: Promise<void>;
   /** The source text as of the last persist (seed or markPersisted) — the room-dirty baseline. */
   baseline: string;
@@ -55,6 +56,17 @@ export interface HostConnection {
   close: () => void;
 }
 
+/** The host's own view of a connection: the embedder only ever sees the {@link HostConnection}. */
+interface InternalConnection extends HostConnection {
+  socket: RoomSocket;
+  identity: CollabIdentity;
+  subscribed: Set<string>;
+  /** Awareness clientIDs this socket controls (removed on close). */
+  controlledIds: Set<number>;
+  warnedReadOnly: boolean;
+  closed: boolean;
+}
+
 export interface CollabHost {
   connect: (socket: RoomSocket, identity: CollabIdentity) => HostConnection;
   /**
@@ -87,16 +99,6 @@ export function createCollabHost(options: CollabHostOptions): CollabHost {
   // The host's own (empty) local state must not leak into rosters.
   awareness.setLocalState(null);
 
-  interface InternalConnection extends HostConnection {
-    socket: RoomSocket;
-    identity: CollabIdentity;
-    subscribed: Set<string>;
-    /** Awareness clientIDs this socket controls (removed on close). */
-    controlledIds: Set<number>;
-    warnedReadOnly: boolean;
-    closed: boolean;
-  }
-
   const send = (conn: InternalConnection, frame: CollabFrame) => {
     try {
       conn.socket.send(encodeFrame(frame));
@@ -111,8 +113,7 @@ export function createCollabHost(options: CollabHostOptions): CollabHost {
 
   const broadcastToRoom = (room: Room, frame: CollabFrame, except?: InternalConnection) => {
     const data = encodeFrame(frame);
-    for (const subscriber of room.subscribers) {
-      const target = subscriber as InternalConnection;
+    for (const target of room.subscribers) {
       if (target !== except && !target.closed) {
         try {
           target.socket.send(data);
@@ -150,7 +151,9 @@ export function createCollabHost(options: CollabHostOptions): CollabHost {
         sourceText(doc).insert(0, source);
       }, "seed");
     })();
-    doc.on("update", (update: Uint8Array, origin: unknown) => {
+    /* A room doc is written only here: the "seed" transaction above, and the sync-protocol reads in
+       `handleDocSync`, which tag the update with the connection it came from. */
+    doc.on("update", (update: Uint8Array, origin: InternalConnection | string) => {
       const current = rooms.get(path);
       if (!current || current.doc !== doc) {
         return;
@@ -160,7 +163,8 @@ export function createCollabHost(options: CollabHostOptions): CollabHost {
       broadcastToRoom(
         current,
         { body: encoding.toUint8Array(body), epoch: current.epoch, path, type: "doc-sync" },
-        origin instanceof Object && "socket" in origin ? (origin as InternalConnection) : undefined,
+        // The sender already has the update, so it is the one subscriber the relay skips.
+        isString(origin) ? undefined : origin,
       );
       options.onSourceChange?.(path);
       // Room-level dirty: broadcast on transition so every peer's Save affordance stays in sync.
@@ -379,14 +383,19 @@ export function createCollabHost(options: CollabHostOptions): CollabHost {
         warnedReadOnly: false,
       };
       connections.add(conn);
-      sendControl(conn, {
+      const hello: Extract<ControlMessage, { type: "hello" }> = {
         color: identity.color,
         login: identity.login,
         permission: identity.permission,
         type: "hello",
-        ...(identity.name === undefined ? {} : { name: identity.name }),
-        ...(identity.avatarUrl === undefined ? {} : { avatarUrl: identity.avatarUrl }),
-      });
+      };
+      if (identity.name !== undefined) {
+        hello.name = identity.name;
+      }
+      if (identity.avatarUrl !== undefined) {
+        hello.avatarUrl = identity.avatarUrl;
+      }
+      sendControl(conn, hello);
       // Late joiners receive the current presence roster immediately.
       const states = awareness.getStates();
       if (states.size > 0) {
@@ -447,7 +456,7 @@ export function createCollabHost(options: CollabHostOptions): CollabHost {
         type: "control",
       });
       for (const subscriber of room.subscribers) {
-        (subscriber as InternalConnection).subscribed.delete(path);
+        subscriber.subscribed.delete(path);
       }
       room.doc.destroy();
       rooms.delete(path);