@kyneta/yjs-schema 1.3.0 → 1.4.0

package/dist/index.js

@@ -1,892 +1,1191 @@
-// src/index.ts
-import {
-  applyChanges,
-  change,
-  createDoc,
-  createRef,
-  exportEntirety,
-  exportSince,
-  merge,
-  NATIVE,
-  Schema,
-  subscribe,
-  subscribeNode,
-  unwrap,
-  version
-} from "@kyneta/schema";
-
-// src/bind-yjs.ts
-import {
-  BACKING_DOC as BACKING_DOC2,
-  createSubstrateNamespace,
-  STRUCTURAL_YJS_CLIENT_ID as STRUCTURAL_YJS_CLIENT_ID2
-} from "@kyneta/schema";
-import * as Y6 from "yjs";
-
-// src/populate.ts
-import { KIND, STRUCTURAL_YJS_CLIENT_ID, Zero } from "@kyneta/schema";
+import { BACKING_DOC, KIND, NATIVE, RawPath, STRUCTURAL_YJS_CLIENT_ID, SYNC_COLLABORATIVE, Schema, Zero, advanceSchema, applyChanges, base64ToUint8Array, buildWritableContext, change, createBindingTarget, createDoc, createRef, deriveSchemaBinding, executeBatch, expandMapOpsToLeaves, exportEntirety, exportSince, merge, richTextChange, subscribe, subscribeNode, uint8ArrayToBase64, unwrap, version, versionVectorCompare, versionVectorMeet } from "@kyneta/schema";
 import * as Y from "yjs";
-function ensureContainers(doc, schema, conditional = false) {
-  const rootMap = doc.getMap("root");
-  if (schema[KIND] !== "product") {
-    return;
-  }
-  const savedClientID = doc.clientID;
-  doc.clientID = STRUCTURAL_YJS_CLIENT_ID;
-  try {
-    doc.transact(() => {
-      for (const [key, fieldSchema] of Object.entries(schema.fields).sort(
-        ([a], [b]) => a.localeCompare(b)
-      )) {
-        if (conditional && rootMap.has(key)) continue;
-        ensureRootField(rootMap, key, fieldSchema);
-      }
-    });
-  } finally {
-    doc.clientID = savedClientID;
-  }
-}
-function ensureRootField(rootMap, key, fieldSchema) {
-  switch (fieldSchema[KIND]) {
-    case "text":
-      rootMap.set(key, new Y.Text());
-      return;
-    case "product":
-      rootMap.set(key, ensureMapContainers(fieldSchema));
-      return;
-    case "sequence":
-      rootMap.set(key, new Y.Array());
-      return;
-    case "map":
-      rootMap.set(key, new Y.Map());
-      return;
-    case "scalar":
-    case "sum": {
-      const zero = Zero.structural(fieldSchema);
-      if (zero !== void 0) {
-        rootMap.set(key, zero);
-      }
-      return;
-    }
-    case "counter":
-    case "set":
-    case "tree":
-    case "movable":
-      throw new Error(
-        `Yjs substrate does not support [KIND]="${fieldSchema[KIND]}". Supported kinds: text, product, sequence, map, scalar, sum. Encountered unsupported kind at root field "${key}".`
-      );
-  }
-}
-function ensureMapContainers(schema) {
-  const map = new Y.Map();
-  if (schema[KIND] !== "product") return map;
-  for (const [key, fieldSchema] of Object.entries(
-    schema.fields
-  ).sort(([a], [b]) => a.localeCompare(b))) {
-    switch (fieldSchema[KIND]) {
-      case "text":
-        map.set(key, new Y.Text());
-        break;
-      case "product":
-        map.set(key, ensureMapContainers(fieldSchema));
-        break;
-      case "sequence":
-        map.set(key, new Y.Array());
-        break;
-      case "map":
-        map.set(key, new Y.Map());
-        break;
-      case "scalar":
-      case "sum": {
-        const zero = Zero.structural(fieldSchema);
-        if (zero !== void 0) {
-          map.set(key, zero);
-        }
-        break;
-      }
-      case "counter":
-      case "set":
-      case "tree":
-      case "movable":
-        throw new Error(
-          `Yjs substrate does not support [KIND]="${fieldSchema[KIND]}". Supported kinds: text, product, sequence, map, scalar, sum. Encountered unsupported kind at nested field "${key}".`
-        );
-    }
-  }
-  return map;
+import { createSnapshot, decodeStateVector, encodeSnapshot, encodeStateVector, snapshot } from "yjs";
+//#region src/populate.ts
+/**
+* Ensure that a Y.Doc's root map contains the correct Yjs shared types
+* matching the schema structure.
+*
+* Obtains the root map via `doc.getMap("root")`, reads the root product
+* schema's fields, and creates empty containers for each field within a
+* single `doc.transact()` call for atomicity.
+*
+* When `conditional` is true, fields that already exist in the root map
+* are skipped. This is the correct mode after hydration — containers
+* present from stored state must not be overwritten (each `rootMap.set()`
+* is a CRDT write that advances the version vector and may conflict
+* with stored operations).
+*
+* When `conditional` is false (default), all fields are created
+* unconditionally. This is the correct mode for fresh documents.
+*
+* **Structural identity:** This function temporarily sets `doc.clientID`
+* to `STRUCTURAL_YJS_CLIENT_ID` (0) for the duration of container creation,
+* then restores the caller's clientID. This produces byte-identical
+* structural ops across all peers, enabling Yjs deduplication on merge.
+*
+* **Identity-keying:** When a `binding` is provided, each root field's
+* key in the root Y.Map is the identity hash from `binding.forward`
+* instead of the field name. Nested product fields are similarly keyed
+* via `ensureMapContainers`.
+*
+* @param doc - The Y.Doc to prepare
+* @param schema - The root document schema (a ProductSchema)
+* @param conditional - If true, skip fields that already exist in the root map.
+*   Context: jj:smmulzkm (two-phase substrate construction)
+* @param binding - Optional SchemaBinding for identity-keyed containers.
+*/
+function ensureContainers(doc, schema, conditional = false, binding) {
+	const rootMap = doc.getMap("root");
+	if (schema[KIND] !== "product") return;
+	const savedClientID = doc.clientID;
+	doc.clientID = STRUCTURAL_YJS_CLIENT_ID;
+	try {
+		doc.transact(() => {
+			for (const [key, fieldSchema] of Object.entries(schema.fields).sort(([a], [b]) => a.localeCompare(b))) {
+				const mapKey = binding?.forward.get(key) ?? key;
+				if (conditional && rootMap.has(mapKey)) continue;
+				ensureRootField(rootMap, mapKey, fieldSchema, binding, key);
+			}
+		});
+	} finally {
+		doc.clientID = savedClientID;
+	}
 }
-
-// src/substrate.ts
-import {
-  BACKING_DOC,
-  buildWritableContext,
-  executeBatch,
-  KIND as KIND3
-} from "@kyneta/schema";
-import * as Y5 from "yjs";
-
-// src/change-mapping.ts
-import {
-  advanceSchema as advanceSchema2,
-  expandMapOpsToLeaves,
-  KIND as KIND2,
-  RawPath
-} from "@kyneta/schema";
-import * as Y3 from "yjs";
-
-// src/yjs-resolve.ts
-import { advanceSchema } from "@kyneta/schema";
-import * as Y2 from "yjs";
-function stepIntoYjs(current, segment) {
-  const resolved = segment.resolve();
-  if (current instanceof Y2.Map) {
-    return current.get(resolved);
-  }
-  if (current instanceof Y2.Array) {
-    return current.get(resolved);
-  }
-  if (current instanceof Y2.Text) {
-    throw new Error(`yjs-resolve: cannot step into Y.Text`);
-  }
-  return void 0;
-}
-function resolveYjsType(rootMap, rootSchema, path) {
-  let current = rootMap;
-  let schema = rootSchema;
-  for (let i = 0; i < path.length; i++) {
-    const seg = path.segments[i];
-    const nextSchema = advanceSchema(schema, seg);
-    current = stepIntoYjs(current, seg);
-    schema = nextSchema;
-  }
-  return current;
+/**
+* Ensure a root-level Yjs shared type exists for a schema field.
+*
+* Dispatches on `[KIND]`:
+* - `"text"` → empty Y.Text
+* - `"product"` → empty Y.Map (recursive for nested products)
+* - `"sequence"` → empty Y.Array
+* - `"map"` → empty Y.Map
+* - `"scalar"` / `"sum"` → Zero.structural default
+* - `"counter"` / `"set"` / `"tree"` / `"movable"` → throw (not supported by Yjs)
+*
+* @param rootMap - The root Y.Map to set the field on.
+* @param key - The key to use in the root map (identity hash or field name).
+* @param fieldSchema - The schema for this field.
+* @param binding - Optional SchemaBinding for nested identity-keying.
+* @param prefix - The absolute schema path prefix for this field (used for nested lookups).
+*/
+function ensureRootField(rootMap, key, fieldSchema, binding, prefix) {
+	switch (fieldSchema[KIND]) {
+		case "text":
+		case "richtext":
+			rootMap.set(key, new Y.Text());
+			return;
+		case "product":
+			rootMap.set(key, ensureMapContainers(fieldSchema, binding, prefix));
+			return;
+		case "sequence":
+			rootMap.set(key, new Y.Array());
+			return;
+		case "map":
+			rootMap.set(key, new Y.Map());
+			return;
+		case "scalar":
+		case "sum": {
+			const zero = Zero.structural(fieldSchema);
+			if (zero !== void 0) rootMap.set(key, zero);
+			return;
+		}
+		case "counter":
+		case "set":
+		case "tree":
+		case "movable": throw new Error(`Yjs substrate does not support [KIND]="${fieldSchema[KIND]}". Supported kinds: text, richtext, product, sequence, map, scalar, sum. Encountered unsupported kind at root field "${key}".`);
+	}
 }
-
-// src/change-mapping.ts
-function applyChangeToYjs(rootMap, rootSchema, path, change2) {
-  switch (change2.type) {
-    case "text":
-      applyTextChange(rootMap, rootSchema, path, change2);
-      return;
-    case "sequence":
-      applySequenceChange(rootMap, rootSchema, path, change2);
-      return;
-    case "map":
-      applyMapChange(rootMap, rootSchema, path, change2);
-      return;
-    case "replace":
-      applyReplaceChange(rootMap, rootSchema, path, change2);
-      return;
-    case "increment":
-      throw new Error(
-        `Yjs substrate does not support "${change2.type}" changes. Counter requires a CRDT backend that supports counters (e.g. Loro). Attempted IncrementChange with amount=${change2.amount} at path [${pathToString(path)}].`
-      );
-    case "tree":
-      throw new Error(
-        `Yjs substrate does not support "${change2.type}" changes. Tree requires a CRDT backend that supports trees (e.g. Loro). Attempted TreeChange at path [${pathToString(path)}].`
-      );
-    default:
-      throw new Error(
-        `applyChangeToYjs: unsupported change type "${change2.type}"`
-      );
-  }
-}
-function applyTextChange(rootMap, rootSchema, path, change2) {
-  const resolved = resolveYjsType(rootMap, rootSchema, path);
-  if (!(resolved instanceof Y3.Text)) {
-    throw new Error(
-      `applyChangeToYjs: TextChange target at path [${pathToString(path)}] is not a Y.Text`
-    );
-  }
-  resolved.applyDelta(change2.instructions);
-}
-function applySequenceChange(rootMap, rootSchema, path, change2) {
-  const resolved = resolveYjsType(rootMap, rootSchema, path);
-  if (!(resolved instanceof Y3.Array)) {
-    throw new Error(
-      `applyChangeToYjs: SequenceChange target at path [${pathToString(path)}] is not a Y.Array`
-    );
-  }
-  const targetSchema = resolveSchemaAtPath(rootSchema, path);
-  const itemSchema = getItemSchema(targetSchema);
-  let cursor = 0;
-  for (const instruction of change2.instructions) {
-    if ("retain" in instruction) {
-      cursor += instruction.retain;
-    } else if ("delete" in instruction) {
-      resolved.delete(cursor, instruction.delete);
-    } else if ("insert" in instruction) {
-      const items = instruction.insert;
-      const yjsItems = items.map(
-        (item) => maybeCreateSharedType(item, itemSchema)
-      );
-      resolved.insert(cursor, yjsItems);
-      cursor += items.length;
-    }
-  }
-}
-function applyMapChange(rootMap, rootSchema, path, change2) {
-  const resolved = resolveYjsType(rootMap, rootSchema, path);
-  if (!(resolved instanceof Y3.Map)) {
-    throw new Error(
-      `applyChangeToYjs: MapChange target at path [${pathToString(path)}] is not a Y.Map`
-    );
-  }
-  const targetSchema = resolveSchemaAtPath(rootSchema, path);
-  if (change2.delete) {
-    for (const key of change2.delete) {
-      resolved.delete(key);
-    }
-  }
-  if (change2.set) {
-    for (const [key, value] of Object.entries(change2.set)) {
-      const fieldSchema = getFieldSchema(targetSchema, key);
-      const yjsValue = maybeCreateSharedType(value, fieldSchema);
-      resolved.set(key, yjsValue);
-    }
-  }
-}
-function applyReplaceChange(rootMap, rootSchema, path, change2) {
-  if (path.length === 0) {
-    throw new Error(
-      "applyChangeToYjs: ReplaceChange at root path is not supported"
-    );
-  }
-  const lastSeg = path.segments[path.segments.length - 1];
-  const parentPath = path.slice(0, -1);
-  const parent = resolveYjsType(rootMap, rootSchema, parentPath);
-  const resolved = lastSeg.resolve();
-  if (parent instanceof Y3.Map && lastSeg.role === "key") {
-    const targetSchema = resolveSchemaAtPath(rootSchema, path);
-    const yjsValue = maybeCreateSharedType(change2.value, targetSchema);
-    parent.set(resolved, yjsValue);
-  } else if (parent instanceof Y3.Array && lastSeg.role === "index") {
-    const targetSchema = resolveSchemaAtPath(rootSchema, path);
-    const yjsValue = maybeCreateSharedType(change2.value, targetSchema);
-    parent.delete(resolved, 1);
-    parent.insert(resolved, [yjsValue]);
-  } else {
-    throw new Error(
-      `applyChangeToYjs: ReplaceChange parent at path [${pathToString(parentPath)}] is not a Y.Map or Y.Array (got ${typeof parent})`
-    );
-  }
+/**
+* Create an empty Y.Map with nested shared type children matching
+* the product schema's field structure.
+*
+* Only creates containers for fields that require Yjs shared types
+* (text → Y.Text, product → Y.Map, sequence → Y.Array, map → Y.Map).
+* Scalar and sum fields are set to their structural zero defaults.
+*
+* **Identity-keying:** When a `binding` is provided, computes the
+* absolute schema path for each nested field (`prefix.fieldName`) and
+* looks up the identity hash from `binding.forward`. The identity hash
+* is used as the Y.Map entry key instead of the field name.
+*
+* @param schema - The product schema for this nested map.
+* @param binding - Optional SchemaBinding for identity-keyed containers.
+* @param prefix - The absolute schema path prefix (e.g. "meta" for fields under meta).
+*/
+function ensureMapContainers(schema, binding, prefix) {
+	const map = new Y.Map();
+	if (schema[KIND] !== "product") return map;
+	for (const [key, fieldSchema] of Object.entries(schema.fields).sort(([a], [b]) => a.localeCompare(b))) {
+		const absPath = prefix ? `${prefix}.${key}` : key;
+		const mapKey = binding?.forward.get(absPath) ?? key;
+		switch (fieldSchema[KIND]) {
+			case "text":
+			case "richtext":
+				map.set(mapKey, new Y.Text());
+				break;
+			case "product":
+				map.set(mapKey, ensureMapContainers(fieldSchema, binding, absPath));
+				break;
+			case "sequence":
+				map.set(mapKey, new Y.Array());
+				break;
+			case "map":
+				map.set(mapKey, new Y.Map());
+				break;
+			case "scalar":
+			case "sum": {
+				const zero = Zero.structural(fieldSchema);
+				if (zero !== void 0) map.set(mapKey, zero);
+				break;
+			}
+			case "counter":
+			case "set":
+			case "tree":
+			case "movable": throw new Error(`Yjs substrate does not support [KIND]="${fieldSchema[KIND]}". Supported kinds: text, richtext, product, sequence, map, scalar, sum. Encountered unsupported kind at nested field "${key}".`);
+		}
+	}
+	return map;
+}
+//#endregion
+//#region src/yjs-resolve.ts
+/**
+* Navigate one step deeper into the Yjs shared type tree.
+*
+* Uses `instanceof` for runtime type discrimination:
+* - `Y.Map` → `.get(key)` — uses the identity hash when provided
+* - `Y.Array` → `.get(index)`
+* - `Y.Text` → terminal (cannot step further)
+* - Plain value → terminal (return `undefined`)
+*
+* @param current - The current position (a Yjs shared type or plain value)
+* @param segment - The path segment to follow
+* @param identity - Optional identity hash to use instead of the segment's resolved value
+*/
+function stepIntoYjs(current, segment, identity) {
+	const resolved = segment.resolve();
+	if (current instanceof Y.Map) return current.get(identity ?? resolved);
+	if (current instanceof Y.Array) return current.get(resolved);
+	if (current instanceof Y.Text) throw new Error(`yjs-resolve: cannot step into Y.Text`);
+}
+/**
+* Resolve a Yjs shared type (or plain value) at the given path.
+*
+* Left-folds over path segments using `advanceSchema` for pure schema
+* descent and `stepIntoYjs` for Yjs-specific navigation.
+*
+* When a `binding` is provided, each step computes the absolute schema
+* path and looks up the identity hash from `binding.forward`. This
+* identity hash is used instead of the field name at every product-field
+* boundary (root and nested).
+*
+* Returns both the Yjs shared type (or plain value) and the schema at
+* the terminal position. For an empty path, returns the root map and
+* root schema.
+*
+* @param rootMap - The root `Y.Map` obtained via `doc.getMap("root")`
+* @param rootSchema - The root document schema
+* @param path - The path to resolve
+* @param binding - Optional SchemaBinding for identity-keyed navigation.
+*/
+function resolveYjsType(rootMap, rootSchema, path, binding) {
+	let current = rootMap;
+	let schema = rootSchema;
+	let absPath = "";
+	for (let i = 0; i < path.length; i++) {
+		const seg = path.segments[i];
+		if (!seg) throw new Error(`Missing segment at index ${i}`);
+		const nextSchema = advanceSchema(schema, seg);
+		let identity;
+		if (binding && seg.role === "key") {
+			const segStr = seg.resolve();
+			absPath = absPath ? `${absPath}.${segStr}` : segStr;
+			identity = binding.forward.get(absPath);
+		}
+		current = stepIntoYjs(current, seg, identity);
+		schema = nextSchema;
+	}
+	return {
+		resolved: current,
+		schema
+	};
+}
+//#endregion
+//#region src/change-mapping.ts
+/**
+* Apply a kyneta Change to the Yjs shared type tree imperatively.
+*
+* Resolves the target shared type at `path`, then applies the change
+* via the appropriate Yjs API. Must be called within a `doc.transact()`
+* for atomicity and correct event batching.
+*
+* @param rootMap - The root `Y.Map` obtained via `doc.getMap("root")`
+* @param rootSchema - The root document schema
+* @param path - The path to the target
+* @param change - The kyneta Change to apply
+*/
+function applyChangeToYjs(rootMap, rootSchema, path, change, binding) {
+	switch (change.type) {
+		case "text":
+			applyTextChange(rootMap, rootSchema, path, change, binding);
+			return;
+		case "richtext":
+			applyRichTextChange(rootMap, rootSchema, path, change, binding);
+			return;
+		case "sequence":
+			applySequenceChange(rootMap, rootSchema, path, change, binding);
+			return;
+		case "map":
+			applyMapChange(rootMap, rootSchema, path, change, binding);
+			return;
+		case "replace":
+			applyReplaceChange(rootMap, rootSchema, path, change, binding);
+			return;
+		case "increment": throw new Error(`Yjs substrate does not support "${change.type}" changes. Counter requires a CRDT backend that supports counters (e.g. Loro). Attempted IncrementChange with amount=${change.amount} at path [${pathToString(path)}].`);
+		case "tree": throw new Error(`Yjs substrate does not support "${change.type}" changes. Tree requires a CRDT backend that supports trees (e.g. Loro). Attempted TreeChange at path [${pathToString(path)}].`);
+		default: throw new Error(`applyChangeToYjs: unsupported change type "${change.type}"`);
+	}
 }
+function applyTextChange(rootMap, rootSchema, path, change, binding) {
+	const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding);
+	if (!(resolved instanceof Y.Text)) throw new Error(`applyChangeToYjs: TextChange target at path [${pathToString(path)}] is not a Y.Text`);
+	resolved.applyDelta(change.instructions);
+}
+function applyRichTextChange(rootMap, rootSchema, path, change, binding) {
+	const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding);
+	if (!(resolved instanceof Y.Text)) throw new Error(`applyChangeToYjs: RichTextChange target at path [${pathToString(path)}] is not a Y.Text`);
+	const delta = change.instructions.map((inst) => {
+		if ("retain" in inst) return { retain: inst.retain };
+		if ("format" in inst) return {
+			retain: inst.format,
+			attributes: inst.marks
+		};
+		if ("insert" in inst) {
+			const d = { insert: inst.insert };
+			if (inst.marks && Object.keys(inst.marks).length > 0) d.attributes = inst.marks;
+			return d;
+		}
+		if ("delete" in inst) return { delete: inst.delete };
+		throw new Error("applyRichTextChange: unknown instruction type");
+	});
+	resolved.applyDelta(delta);
+}
+function applySequenceChange(rootMap, rootSchema, path, change, binding) {
+	const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding);
+	if (!(resolved instanceof Y.Array)) throw new Error(`applyChangeToYjs: SequenceChange target at path [${pathToString(path)}] is not a Y.Array`);
+	const itemSchema = getItemSchema(resolveSchemaAtPath(rootSchema, path));
+	let cursor = 0;
+	for (const instruction of change.instructions) if ("retain" in instruction) cursor += instruction.retain;
+	else if ("delete" in instruction) resolved.delete(cursor, instruction.delete);
+	else if ("insert" in instruction) {
+		const items = instruction.insert;
+		const yjsItems = items.map((item) => maybeCreateSharedType(item, itemSchema));
+		resolved.insert(cursor, yjsItems);
+		cursor += items.length;
+	}
+}
+function applyMapChange(rootMap, rootSchema, path, change, binding) {
+	const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding);
+	if (!(resolved instanceof Y.Map)) throw new Error(`applyChangeToYjs: MapChange target at path [${pathToString(path)}] is not a Y.Map`);
+	const targetSchema = resolveSchemaAtPath(rootSchema, path);
+	if (change.delete) for (const key of change.delete) resolved.delete(key);
+	if (change.set) for (const [key, value] of Object.entries(change.set)) {
+		const yjsValue = maybeCreateSharedType(value, getFieldSchema(targetSchema, key));
+		let mapKey = key;
+		if (binding && targetSchema[KIND] === "product") {
+			const parentAbsPath = path.segments.filter((s) => s.role === "key").map((s) => s.resolve()).join(".");
+			const absPath = parentAbsPath ? `${parentAbsPath}.${key}` : key;
+			const identity = binding.forward.get(absPath);
+			if (identity) mapKey = identity;
+		}
+		resolved.set(mapKey, yjsValue);
+	}
+}
+function applyReplaceChange(rootMap, rootSchema, path, change, binding) {
+	if (path.length === 0) throw new Error("applyChangeToYjs: ReplaceChange at root path is not supported");
+	const lastSeg = path.segments.at(-1);
+	if (!lastSeg) throw new Error("replaceChangeToDiff: empty path");
+	const parentPath = path.slice(0, -1);
+	const { resolved: parent } = resolveYjsType(rootMap, rootSchema, parentPath, binding);
+	const resolved = lastSeg.resolve();
+	if (parent instanceof Y.Map && lastSeg.role === "key") {
+		const targetSchema = resolveSchemaAtPath(rootSchema, path);
+		const yjsValue = maybeCreateSharedType(change.value, targetSchema);
+		let mapKey = resolved;
+		if (binding) {
+			const absPath = path.segments.filter((s) => s.role === "key").map((s) => s.resolve()).join(".");
+			const identity = binding.forward.get(absPath);
+			if (identity) mapKey = identity;
+		}
+		parent.set(mapKey, yjsValue);
+	} else if (parent instanceof Y.Array && lastSeg.role === "index") {
+		const targetSchema = resolveSchemaAtPath(rootSchema, path);
+		const yjsValue = maybeCreateSharedType(change.value, targetSchema);
+		parent.delete(resolved, 1);
+		parent.insert(resolved, [yjsValue]);
+	} else throw new Error(`applyChangeToYjs: ReplaceChange parent at path [${pathToString(parentPath)}] is not a Y.Map or Y.Array (got ${typeof parent})`);
+}
+/**
+* If the schema says the value should be a shared type (product → Y.Map,
+* sequence → Y.Array, text → Y.Text, richtext → Y.Text), create and
+* populate it. Otherwise return the plain value as-is.
+*
+* Uses populate-then-attach: the new shared type is fully populated
+* before being returned for insertion into its parent.
+*/
 function maybeCreateSharedType(value, schema) {
-  if (schema === void 0) return value;
-  switch (schema[KIND2]) {
-    // First-class text → Y.Text
-    case "text": {
-      const text = new Y3.Text();
-      if (typeof value === "string" && value.length > 0) {
-        text.insert(0, value);
-      }
-      return text;
-    }
-    case "product": {
-      if (value === null || value === void 0 || typeof value !== "object" || Array.isArray(value)) {
-        return value;
-      }
-      return createStructuredMap(value, schema);
-    }
-    case "sequence": {
-      if (!Array.isArray(value)) return value;
-      const arr = new Y3.Array();
-      const itemSchema = schema.item;
-      const items = value.map(
-        (item) => maybeCreateSharedType(item, itemSchema)
-      );
-      arr.insert(0, items);
-      return arr;
-    }
-    case "map": {
-      if (value === null || value === void 0 || typeof value !== "object" || Array.isArray(value)) {
-        return value;
-      }
-      const map = new Y3.Map();
-      const valueSchema = schema.item;
-      for (const [k, v] of Object.entries(value)) {
-        map.set(k, maybeCreateSharedType(v, valueSchema));
-      }
-      return map;
-    }
-    // Unsupported first-class CRDT types — should not reach here
-    // (rejected at bind time by caps check)
-    case "counter":
-    case "set":
-    case "tree":
-    case "movable":
-      throw new Error(
-        `Yjs substrate does not support [KIND]="${schema[KIND2]}". This should have been caught at bind() time.`
-      );
-    default:
-      return value;
-  }
+	if (schema === void 0) return value;
+	switch (schema[KIND]) {
+		case "text": {
+			const text = new Y.Text();
+			if (typeof value === "string" && value.length > 0) text.insert(0, value);
+			return text;
+		}
+		case "richtext": {
+			const text = new Y.Text();
+			if (typeof value === "string" && value.length > 0) text.insert(0, value);
+			else if (Array.isArray(value)) {
+				const delta = value.map((span) => {
+					const d = { insert: span.text };
+					if (span.marks && Object.keys(span.marks).length > 0) d.attributes = span.marks;
+					return d;
+				});
+				if (delta.length > 0) text.applyDelta(delta);
+			}
+			return text;
+		}
+		case "product":
+			if (value === null || value === void 0 || typeof value !== "object" || Array.isArray(value)) return value;
+			return createStructuredMap(value, schema);
+		case "sequence": {
+			if (!Array.isArray(value)) return value;
+			const arr = new Y.Array();
+			const itemSchema = schema.item;
+			const items = value.map((item) => maybeCreateSharedType(item, itemSchema));
+			arr.insert(0, items);
+			return arr;
+		}
+		case "map": {
+			if (value === null || value === void 0 || typeof value !== "object" || Array.isArray(value)) return value;
+			const map = new Y.Map();
+			const valueSchema = schema.item;
+			for (const [k, v] of Object.entries(value)) map.set(k, maybeCreateSharedType(v, valueSchema));
+			return map;
+		}
+		case "counter":
+		case "set":
+		case "tree":
+		case "movable": throw new Error(`Yjs substrate does not support [KIND]="${schema[KIND]}". This should have been caught at bind() time.`);
+		default: return value;
+	}
 }
+/**
+* Create a Y.Map from a plain object, recursively creating nested
+* shared types as guided by the product schema.
+*
+* Follows populate-then-attach: fully populates the map before the
+* caller inserts it into a parent container.
+*/
 function createStructuredMap(obj, productSchema) {
-  const map = new Y3.Map();
-  if (productSchema[KIND2] !== "product") {
-    for (const [key, val] of Object.entries(obj)) {
-      map.set(key, val);
-    }
-    return map;
-  }
-  for (const [key, val] of Object.entries(obj)) {
-    if (val === void 0) continue;
-    const fieldSchema = productSchema.fields[key];
-    const yjsVal = fieldSchema ? maybeCreateSharedType(val, fieldSchema) : val;
-    map.set(key, yjsVal);
-  }
-  for (const [key, fieldSchema] of Object.entries(
-    productSchema.fields
-  )) {
-    if (key in obj) continue;
-    if (fieldSchema[KIND2] === "text") {
-      map.set(key, new Y3.Text());
-    }
-  }
-  return map;
-}
-function eventsToOps(events, schema) {
-  const ops = [];
-  for (const event of events) {
-    const kynetaPath = yjsPathToKynetaPath(event.path);
-    const change2 = eventToChange(event);
-    if (change2) {
-      ops.push({ path: kynetaPath, change: change2 });
-    }
-  }
-  return expandMapOpsToLeaves(ops, schema);
-}
-function yjsPathToKynetaPath(yjsPath) {
-  let path = RawPath.empty;
-  for (const segment of yjsPath) {
-    if (typeof segment === "string") {
-      path = path.field(segment);
-    } else if (typeof segment === "number") {
-      path = path.item(segment);
-    }
-  }
-  return path;
-}
-function eventToChange(event) {
-  if (event.target instanceof Y3.Text) {
-    return textEventToChange(event);
-  }
-  if (event.target instanceof Y3.Array) {
-    return arrayEventToChange(event);
-  }
-  if (event.target instanceof Y3.Map) {
-    return mapEventToChange(event);
-  }
-  return null;
+	const map = new Y.Map();
+	if (productSchema[KIND] !== "product") {
+		for (const [key, val] of Object.entries(obj)) map.set(key, val);
+		return map;
+	}
+	for (const [key, val] of Object.entries(obj)) {
+		if (val === void 0) continue;
+		const fieldSchema = productSchema.fields[key];
+		const yjsVal = fieldSchema ? maybeCreateSharedType(val, fieldSchema) : val;
+		map.set(key, yjsVal);
+	}
+	for (const [key, fieldSchema] of Object.entries(productSchema.fields)) {
+		if (key in obj) continue;
+		if (fieldSchema[KIND] === "text" || fieldSchema[KIND] === "richtext") map.set(key, new Y.Text());
+	}
+	return map;
 }
+/**
+* Convert `observeDeep` events into kyneta `Op[]` for changefeed delivery.
+*
+* Each `Y.YEvent` in the array maps to one Op with:
+* - `path`: derived from `event.path` (relative to the observed root Y.Map)
+* - `change`: derived from the event's delta/keys based on target type
+*
+* `event.path` in `observeDeep` is relative to the observed shared type.
+* Since we observe `rootMap` (the single root Y.Map), paths map directly
+* to kyneta `PathSegment[]`.
+*
+* @param events - The events from the `observeDeep` callback
+*/
+function eventsToOps(events, schema, binding) {
+	const ops = [];
+	for (const event of events) {
+		const kynetaPath = yjsPathToKynetaPath(event.path, binding);
+		const change = eventToChange(event, schema, kynetaPath, binding);
+		if (change) ops.push({
+			path: kynetaPath,
+			change
+		});
+	}
+	return expandMapOpsToLeaves(ops, schema);
+}
+/**
+* Convert a Yjs event path (array of string | number) to a kyneta Path.
+*
+* `event.path` from `observeDeep` is relative to the observed type.
+* Strings become key segments, numbers become index segments.
+*/
+function yjsPathToKynetaPath(yjsPath, binding) {
+	let path = RawPath.empty;
+	for (const segment of yjsPath) if (typeof segment === "string") {
+		const absPath = binding?.inverse.get(segment);
+		if (absPath) {
+			const lastDot = absPath.lastIndexOf(".");
+			const leaf = lastDot >= 0 ? absPath.slice(lastDot + 1) : absPath;
+			path = path.field(leaf);
+		} else path = path.field(segment);
+	} else if (typeof segment === "number") path = path.item(segment);
+	return path;
+}
+/**
+* Convert a single Yjs event into a kyneta Change.
+*
+* For Y.Text events, dispatches to either `textEventToChange` or
+* `richTextEventToChange` based on the schema at the event's path.
+* Both text and richtext produce `Y.YTextEvent`, so schema awareness
+* is required for correct dispatch.
+*
+* Returns null for event types we can't map.
+*/
+function eventToChange(event, rootSchema, kynetaPath, binding) {
+	if (event.target instanceof Y.Text) {
+		if (resolveSchemaAtPath(rootSchema, kynetaPath)[KIND] === "richtext") return richTextEventToChange(event);
+		return textEventToChange(event);
+	}
+	if (event.target instanceof Y.Array) return arrayEventToChange(event);
+	if (event.target instanceof Y.Map) return mapEventToChange(event, binding);
+	return null;
+}
+/**
+* Y.Text event → TextChange.
+*
+* `event.delta` uses the Quill Delta format, structurally identical to
+* kyneta `TextInstruction[]`. We strip the `attributes` field (rich text
+* formatting not surfaced by kyneta plain text).
+*/
 function textEventToChange(event) {
-  const instructions = [];
-  for (const delta of event.delta) {
-    if (delta.retain !== void 0) {
-      instructions.push({ retain: delta.retain });
-    } else if (delta.insert !== void 0) {
-      instructions.push({ insert: delta.insert });
-    } else if (delta.delete !== void 0) {
-      instructions.push({ delete: delta.delete });
-    }
-  }
-  return { type: "text", instructions };
+	const instructions = [];
+	for (const delta of event.delta) if (delta.retain !== void 0) instructions.push({ retain: delta.retain });
+	else if (delta.insert !== void 0) instructions.push({ insert: delta.insert });
+	else if (delta.delete !== void 0) instructions.push({ delete: delta.delete });
+	return {
+		type: "text",
+		instructions
+	};
+}
+/**
+* Y.Text event → RichTextChange.
+*
+* `event.delta` uses the Quill Delta format. We map each delta op to a
+* `RichTextInstruction`, preserving `attributes` as `marks` for format
+* and insert instructions.
+*/
+function richTextEventToChange(event) {
+	const instructions = [];
+	for (const delta of event.delta) if (delta.retain !== void 0) {
+		const attrs = delta.attributes;
+		if (attrs && Object.keys(attrs).length > 0) instructions.push({
+			format: delta.retain,
+			marks: attrs
+		});
+		else instructions.push({ retain: delta.retain });
+	} else if (delta.insert !== void 0) {
+		const attrs = delta.attributes;
+		if (attrs && Object.keys(attrs).length > 0) instructions.push({
+			insert: delta.insert,
+			marks: attrs
+		});
+		else instructions.push({ insert: delta.insert });
+	} else if (delta.delete !== void 0) instructions.push({ delete: delta.delete });
+	return richTextChange(instructions);
 }
+/**
+* Y.Array event → SequenceChange.
+*
+* `event.changes.delta` provides the same cursor-based ops as kyneta
+* SequenceInstruction[]. Container values (Y.Map, Y.Array) in insert
+* arrays are converted to plain objects via `.toJSON()`.
+*/
 function arrayEventToChange(event) {
-  const instructions = [];
-  for (const delta of event.changes.delta) {
-    if (delta.retain !== void 0) {
-      instructions.push({ retain: delta.retain });
-    } else if (delta.delete !== void 0) {
-      instructions.push({ delete: delta.delete });
-    } else if (delta.insert !== void 0) {
-      const items = delta.insert.map(
-        (item) => extractEventValue(item)
-      );
-      instructions.push({ insert: items });
-    }
-  }
-  return { type: "sequence", instructions };
-}
-function mapEventToChange(event) {
-  const set = {};
-  const deleteKeys = [];
-  let hasSet = false;
-  let hasDelete = false;
-  const target = event.target;
-  event.changes.keys.forEach((change2, key) => {
-    if (change2.action === "add" || change2.action === "update") {
-      const value = target.get(key);
-      set[key] = extractEventValue(value);
-      hasSet = true;
-    } else if (change2.action === "delete") {
-      deleteKeys.push(key);
-      hasDelete = true;
-    }
-  });
-  if (!hasSet && !hasDelete) return null;
-  return {
-    type: "map",
-    ...hasSet ? { set } : {},
-    ...hasDelete ? { delete: deleteKeys } : {}
-  };
+	const instructions = [];
+	for (const delta of event.changes.delta) if (delta.retain !== void 0) instructions.push({ retain: delta.retain });
+	else if (delta.delete !== void 0) instructions.push({ delete: delta.delete });
+	else if (delta.insert !== void 0) {
+		const items = delta.insert.map((item) => extractEventValue(item));
+		instructions.push({ insert: items });
+	}
+	return {
+		type: "sequence",
+		instructions
+	};
 }
+/**
+* Y.Map event → MapChange.
+*
+* `event.changes.keys` is a `Map<string, { action: 'add'|'update'|'delete', ... }>`.
+* - `action: 'add'|'update'` → `set[key] = map.get(key)`
+* - `action: 'delete'` → `delete.push(key)`
+*/
+function mapEventToChange(event, binding) {
+	const set = {};
+	const deleteKeys = [];
+	let hasSet = false;
+	let hasDelete = false;
+	const target = event.target;
+	event.changes.keys.forEach((change, key) => {
+		const absPath = binding?.inverse.get(key);
+		const fieldName = absPath ? absPath.lastIndexOf(".") >= 0 ? absPath.slice(absPath.lastIndexOf(".") + 1) : absPath : key;
+		if (change.action === "add" || change.action === "update") {
+			set[fieldName] = extractEventValue(target.get(key));
+			hasSet = true;
+		} else if (change.action === "delete") {
+			deleteKeys.push(fieldName);
+			hasDelete = true;
+		}
+	});
+	if (!hasSet && !hasDelete) return null;
+	return {
+		type: "map",
+		...hasSet ? { set } : {},
+		...hasDelete ? { delete: deleteKeys } : {}
+	};
+}
+/**
+* Convert a Yjs value from an event into a plain value.
+* Container values (Y.Map, Y.Array, Y.Text) → `.toJSON()`.
+* Plain values → returned as-is.
+*/
 function extractEventValue(value) {
-  if (value instanceof Y3.Map) return value.toJSON();
-  if (value instanceof Y3.Array) return value.toJSON();
-  if (value instanceof Y3.Text) return value.toJSON();
-  return value;
+	if (value instanceof Y.Map) return value.toJSON();
+	if (value instanceof Y.Array) return value.toJSON();
+	if (value instanceof Y.Text) return value.toJSON();
+	return value;
 }
+/**
+* Resolve the schema at a given path by walking through advanceSchema.
+*/
 function resolveSchemaAtPath(rootSchema, path) {
-  let schema = rootSchema;
-  for (const seg of path.segments) {
-    schema = advanceSchema2(schema, seg);
-  }
-  return schema;
+	let schema = rootSchema;
+	for (const seg of path.segments) schema = advanceSchema(schema, seg);
+	return schema;
 }
+/**
+* Get the item schema from a sequence schema, if available.
+*/
 function getItemSchema(schema) {
-  if (schema[KIND2] === "sequence") return schema.item;
-  if (schema[KIND2] === "movable") return schema.item;
-  return void 0;
+	if (schema[KIND] === "sequence") return schema.item;
+	if (schema[KIND] === "movable") return schema.item;
 }
+/**
+* Get the field schema from a product or map schema for a given key.
+*/
 function getFieldSchema(schema, key) {
-  if (schema[KIND2] === "product") {
-    return schema.fields[key];
-  }
-  if (schema[KIND2] === "map") {
-    return schema.item;
-  }
-  if (schema[KIND2] === "set") {
-    return schema.item;
-  }
-  return void 0;
+	if (schema[KIND] === "product") return schema.fields[key];
+	if (schema[KIND] === "map") return schema.item;
+	if (schema[KIND] === "set") return schema.item;
 }
 function pathToString(path) {
-  return path.segments.map((seg) => String(seg.resolve())).join(".");
+	return path.segments.map((seg) => String(seg.resolve())).join(".");
 }
-
-// src/reader.ts
-import * as Y4 from "yjs";
+//#endregion
+//#region src/position.ts
+/** Map kyneta Side to Yjs assoc. Left → -1 (left-sticky), Right → 0 (right-sticky). */
+function toYjsAssoc(side) {
+	return side === "left" ? -1 : 0;
+}
+/** Map Yjs assoc to kyneta Side. Negative → left, non-negative → right. */
+function fromYjsAssoc(assoc) {
+	return assoc < 0 ? "left" : "right";
+}
+var YjsPosition = class {
+	side;
+	constructor(rpos, doc) {
+		this.rpos = rpos;
+		this.doc = doc;
+		this.side = fromYjsAssoc(rpos.assoc);
+	}
+	resolve() {
+		const abs = Y.createAbsolutePositionFromRelativePosition(this.rpos, this.doc);
+		return abs ? abs.index : null;
+	}
+	encode() {
+		return Y.encodeRelativePosition(this.rpos);
+	}
+	transform(_instructions) {}
+};
+//#endregion
+//#region src/reader.ts
+/**
+* Extract a plain value from a Yjs shared type or return a plain value as-is.
+*
+* - Y.Text → `.toJSON()` (string)
+* - Y.Map → `.toJSON()` (plain object snapshot — for product/map reads)
+* - Y.Array → `.toJSON()` (plain array snapshot)
+* - Plain values (string, number, boolean, null) → returned as-is
+*/
 function extractValue(resolved) {
-  if (resolved instanceof Y4.Text) {
-    return resolved.toJSON();
-  }
-  if (resolved instanceof Y4.Map) {
-    return resolved.toJSON();
-  }
-  if (resolved instanceof Y4.Array) {
-    return resolved.toJSON();
-  }
-  return resolved;
-}
-function yjsReader(doc, schema) {
-  const rootMap = doc.getMap("root");
-  return {
-    read(path) {
-      if (path.length === 0) {
-        return rootMap.toJSON();
-      }
-      const resolved = resolveYjsType(rootMap, schema, path);
-      return extractValue(resolved);
-    },
-    arrayLength(path) {
-      const resolved = resolveYjsType(rootMap, schema, path);
-      if (resolved instanceof Y4.Array) {
-        return resolved.length;
-      }
-      if (Array.isArray(resolved)) {
-        return resolved.length;
-      }
-      return 0;
-    },
-    keys(path) {
-      const resolved = resolveYjsType(rootMap, schema, path);
-      if (resolved instanceof Y4.Map) {
-        return Array.from(resolved.keys());
-      }
-      if (resolved !== null && resolved !== void 0 && typeof resolved === "object" && !Array.isArray(resolved)) {
-        return Object.keys(resolved);
-      }
-      return [];
-    },
-    hasKey(path, key) {
-      const resolved = resolveYjsType(rootMap, schema, path);
-      if (resolved instanceof Y4.Map) {
-        return resolved.has(key);
-      }
-      if (resolved !== null && resolved !== void 0 && typeof resolved === "object" && !Array.isArray(resolved)) {
-        return key in resolved;
-      }
-      return false;
-    }
-  };
+	if (resolved instanceof Y.Text) return resolved.toJSON();
+	if (resolved instanceof Y.Map) return resolved.toJSON();
+	if (resolved instanceof Y.Array) return resolved.toJSON();
+	return resolved;
 }
-
-// src/version.ts
-import {
-  base64ToUint8Array,
-  uint8ArrayToBase64,
-  versionVectorCompare,
-  versionVectorMeet
-} from "@kyneta/schema";
-import { decodeStateVector } from "yjs";
-function encodeStateVector(map) {
-  const bytes = [];
-  function writeVarUint(value) {
-    while (value > 127) {
-      bytes.push(value & 127 | 128);
-      value >>>= 7;
-    }
-    bytes.push(value & 127);
-  }
-  writeVarUint(map.size);
-  for (const [clientId, clock] of map) {
-    writeVarUint(clientId);
-    writeVarUint(clock);
-  }
-  return new Uint8Array(bytes);
-}
-var YjsVersion = class _YjsVersion {
-  sv;
-  constructor(sv) {
-    this.sv = sv;
-  }
-  /**
-   * Serialize the state vector to a base64 string.
-   *
-   * The encoding is: raw state vector bytes → base64.
-   * This is text-safe for embedding in HTML meta tags, URL parameters, etc.
-   */
-  serialize() {
-    return uint8ArrayToBase64(this.sv);
-  }
-  /**
-   * Compare with another version using version-vector partial order.
-   *
-   * Delegates to the shared `versionVectorCompare` utility after decoding
-   * both state vectors via `Y.decodeStateVector()`.
-   *
-   * @throws If `other` is not a `YjsVersion`.
-   */
-  compare(other) {
-    if (!(other instanceof _YjsVersion)) {
-      throw new Error("YjsVersion can only be compared with another YjsVersion");
-    }
-    return versionVectorCompare(
-      decodeStateVector(this.sv),
-      decodeStateVector(other.sv)
-    );
-  }
-  /**
-   * Greatest lower bound (lattice meet) of two Yjs versions.
-   *
-   * Decodes both state vectors, computes the component-wise minimum
-   * via the shared `versionVectorMeet` utility, and encodes the result
-   * back to a Yjs state vector.
-   *
-   * @throws If `other` is not a `YjsVersion`.
-   */
-  meet(other) {
-    if (!(other instanceof _YjsVersion)) {
-      throw new Error("YjsVersion can only be meet'd with another YjsVersion");
-    }
-    const thisMap = decodeStateVector(this.sv);
-    const otherMap = decodeStateVector(other.sv);
-    const result = versionVectorMeet(thisMap, otherMap);
-    return new _YjsVersion(encodeStateVector(result));
-  }
-  /**
-   * Parse a serialized YjsVersion string back into a YjsVersion.
-   *
-   * The inverse of `serialize()`: base64 → `Uint8Array`.
-   */
-  static parse(serialized) {
-    if (serialized === "") {
-      throw new Error("Invalid YjsVersion value: (empty string)");
-    }
-    const bytes = base64ToUint8Array(serialized);
-    return new _YjsVersion(bytes);
-  }
+/**
+* Convert a Y.Text's delta (Quill format) to a kyneta RichTextDelta.
+*
+* Yjs `.toDelta()` returns `{ insert: string, attributes?: Record<string, any> }[]`.
+* Kyneta RichTextDelta is `{ text: string, marks?: MarkMap }[]`.
+*/
+function yTextToRichTextDelta(ytext) {
+	const delta = ytext.toDelta();
+	const spans = [];
+	for (const d of delta) {
+		if (typeof d.insert !== "string") continue;
+		const span = d.attributes && Object.keys(d.attributes).length > 0 ? {
+			text: d.insert,
+			marks: d.attributes
+		} : { text: d.insert };
+		spans.push(span);
+	}
+	return spans;
+}
+/**
+* Creates a Reader that navigates the Yjs shared type tree live,
+* using the schema as a type witness to determine navigation at each
+* path segment.
+*
+* The reader is a live view — mutations to the underlying Y.Doc
+* (via `doc.transact()`, or `Y.applyUpdate()`) are immediately
+* visible through the reader.
+*
+* Internally obtains the root map via `doc.getMap("root")`.
+*
+* @param doc - The Y.Doc to read from.
+* @param schema - The root schema for the document.
+* @param binding - Optional SchemaBinding for identity-keyed navigation.
+*/
+function yjsReader(doc, schema, binding) {
+	const rootMap = doc.getMap("root");
+	return {
+		read(path) {
+			if (path.length === 0) return rootMap.toJSON();
+			const { resolved, schema: nodeSchema } = resolveYjsType(rootMap, schema, path, binding);
+			if (nodeSchema[KIND] === "richtext" && resolved instanceof Y.Text) return yTextToRichTextDelta(resolved);
+			return extractValue(resolved);
+		},
+		arrayLength(path) {
+			const { resolved } = resolveYjsType(rootMap, schema, path, binding);
+			if (resolved instanceof Y.Array) return resolved.length;
+			if (Array.isArray(resolved)) return resolved.length;
+			return 0;
+		},
+		keys(path) {
+			const { resolved } = resolveYjsType(rootMap, schema, path, binding);
+			if (resolved instanceof Y.Map) return Array.from(resolved.keys());
+			if (resolved !== null && resolved !== void 0 && typeof resolved === "object" && !Array.isArray(resolved)) return Object.keys(resolved);
+			return [];
+		},
+		hasKey(path, key) {
+			const { resolved } = resolveYjsType(rootMap, schema, path, binding);
+			if (resolved instanceof Y.Map) return resolved.has(key);
+			if (resolved !== null && resolved !== void 0 && typeof resolved === "object" && !Array.isArray(resolved)) return key in resolved;
+			return false;
+		}
+	};
+}
+//#endregion
+//#region src/version.ts
+/**
+* Encode a state vector map to Yjs's binary state vector format.
+*
+* Yjs does not export `encodeStateVector(map)` — only `Y.encodeStateVector(doc)`
+* which requires a full doc. This implements the same binary format directly:
+* `[entryCount: varint, (clientId: varint, clock: varint)*]`
+*
+* Each value is encoded as an unsigned LEB128 varint.
+*/
+function encodeStateVector$1(map) {
+	const bytes = [];
+	function writeVarUint(value) {
+		while (value > 127) {
+			bytes.push(value & 127 | 128);
+			value >>>= 7;
+		}
+		bytes.push(value & 127);
+	}
+	writeVarUint(map.size);
+	for (const [clientId, clock] of map) {
+		writeVarUint(clientId);
+		writeVarUint(clock);
+	}
+	return new Uint8Array(bytes);
+}
+function arraysEqual(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+	return true;
+}
+/**
+* A Version wrapping a Yjs snapshot (state vector + delete set).
+*
+* The state vector tracks which insertions from each client have been
+* observed. The delete set tracks which of those items have been
+* tombstoned. Together they fully describe a Yjs document's state.
+*
+* - `sv` is used by `exportSince()` to compute the minimal update payload
+*   via `Y.encodeStateAsUpdate(doc, sv)`.
+* - `snapshotBytes` is the encoded Yjs `Snapshot` (SV + delete set),
+*   used for equality comparison: two documents are "equal" only when
+*   both their inserts and deletes match.
+*
+* `compare()` first performs standard version-vector partial-order
+* comparison on the state vectors. If the SVs are equal, it falls
+* through to a byte-level comparison of the snapshot bytes — if they
+* differ (same inserts, different deletes), the result is "concurrent",
+* ensuring the sync protocol pushes the divergent deletes.
+*/
+var YjsVersion = class YjsVersion {
+	/** Encoded state vector — used by exportSince(). */
+	sv;
+	/**
+	* Encoded Yjs snapshot (state vector + delete set) — used for equality
+	* comparison. Two documents are "equal" only if both their inserts
+	* (state vector) and deletes (delete set) match.
+	*/
+	snapshotBytes;
+	constructor(sv, snapshotBytes) {
+		this.sv = sv;
+		this.snapshotBytes = snapshotBytes ?? sv;
+	}
+	/**
+	* Construct a version from a live `Y.Doc` by snapshotting its full state.
+	*
+	* Walks the struct store to derive the delete set — O(n) in the number
+	* of items. Use {@link fromDeleteSet} for the incremental path.
+	*/
+	static fromDoc(doc) {
+		return new YjsVersion(encodeStateVector(doc), encodeSnapshot(snapshot(doc)));
+	}
+	/**
+	* Construct a version from a `Y.Doc`'s state vector and an externally
+	* maintained delete set — the incremental path that avoids a struct
+	* store walk.
+	*
+	* @param doc  The live Y.Doc (for the state vector).
+	* @param ds   An accumulated delete set, kept in sync by merging
+	*             `transaction.deleteSet` on each transaction.
+	*/
+	static fromDeleteSet(doc, ds) {
+		const sv = encodeStateVector(doc);
+		return new YjsVersion(sv, encodeSnapshot(createSnapshot(ds, decodeStateVector(sv))));
+	}
+	/**
+	* Serialize to a text-safe string.
+	*
+	* Format: `base64(sv) + "." + base64(snapshotBytes)`.
+	* The "." separator is unambiguous since base64 never contains ".".
+	*/
+	serialize() {
+		const svB64 = uint8ArrayToBase64(this.sv);
+		const snapB64 = uint8ArrayToBase64(this.snapshotBytes);
+		return svB64 + "." + snapB64;
+	}
+	/**
+	* Compare with another version using version-vector partial order,
+	* extended with delete-set equality checking.
+	*
+	* 1. Decode both state vectors and compare via `versionVectorCompare`.
+	* 2. If the SV comparison yields anything other than "equal", return it.
+	* 3. If the SVs are equal, compare snapshot bytes for byte equality.
+	*    If they differ (same inserts, different deletes), return "concurrent"
+	*    — both sides may have tombstones the other lacks.
+	* 4. "equal" is returned only when BOTH the state vector AND the
+	*    delete set match.
+	*
+	* @throws If `other` is not a `YjsVersion`.
+	*/
+	compare(other) {
+		if (!(other instanceof YjsVersion)) throw new Error("YjsVersion can only be compared with another YjsVersion");
+		const svResult = versionVectorCompare(decodeStateVector(this.sv), decodeStateVector(other.sv));
+		if (svResult !== "equal") return svResult;
+		return arraysEqual(this.snapshotBytes, other.snapshotBytes) ? "equal" : "concurrent";
+	}
+	/**
+	* Greatest lower bound (lattice meet) of two Yjs versions.
+	*
+	* Decodes both state vectors, computes the component-wise minimum
+	* via `versionVectorMeet`, and encodes the result back to a Yjs
+	* state vector.
+	*
+	* The meet snapshot uses the meet SV with no delete-set information
+	* (conservative lower bound). meet() feeds into advance(), which Yjs
+	* does not support incrementally, so this is safe.
+	*
+	* @throws If `other` is not a `YjsVersion`.
+	*/
+	meet(other) {
+		if (!(other instanceof YjsVersion)) throw new Error("YjsVersion can only be meet'd with another YjsVersion");
+		return new YjsVersion(encodeStateVector$1(versionVectorMeet(decodeStateVector(this.sv), decodeStateVector(other.sv))));
+	}
+	/**
+	* Parse a serialized YjsVersion string back into a YjsVersion.
+	*
+	* New format: `base64(sv) + "." + base64(snapshotBytes)`.
+	* Legacy format (no "."): `base64(sv)` only — constructed with
+	* `snapshotBytes` equal to the SV bytes. When compared against a
+	* new-format version with matching SVs, the differing snapshot bytes
+	* yield "concurrent", triggering a safe redundant sync push.
+	*/
+	static parse(serialized) {
+		if (serialized === "") throw new Error("Invalid YjsVersion value: (empty string)");
+		const dotIndex = serialized.indexOf(".");
+		if (dotIndex === -1) return new YjsVersion(base64ToUint8Array(serialized));
+		return new YjsVersion(base64ToUint8Array(serialized.slice(0, dotIndex)), base64ToUint8Array(serialized.slice(dotIndex + 1)));
+	}
 };
-
-// src/substrate.ts
-var KYNETA_ORIGIN = "kyneta-prepare";
-function createYjsSubstrate(doc, schema) {
-  const pendingChanges = [];
-  let inOurTransaction = false;
-  let pendingMergeOrigin;
-  let cachedCtx;
-  const rootMap = doc.getMap("root");
-  const reader = yjsReader(doc, schema);
-  const substrate = {
-    [BACKING_DOC]: doc,
-    reader,
-    prepare(path, change2) {
-      if (!inOurTransaction) {
-        pendingChanges.push({ path, change: change2 });
-      }
-    },
-    onFlush(_origin) {
-      if (!inOurTransaction && pendingChanges.length > 0) {
-        inOurTransaction = true;
-        try {
-          doc.transact(() => {
-            for (const { path, change: change2 } of pendingChanges) {
-              applyChangeToYjs(rootMap, schema, path, change2);
-            }
-          }, KYNETA_ORIGIN);
-          pendingChanges.length = 0;
-        } finally {
-          inOurTransaction = false;
-        }
-      }
-    },
-    context() {
-      if (!cachedCtx) {
-        cachedCtx = buildWritableContext(substrate);
-        cachedCtx.nativeResolver = (nodeSchema, path) => {
-          if (path.segments.length === 0) return doc;
-          if (nodeSchema[KIND3] === "scalar" || nodeSchema[KIND3] === "sum")
-            return void 0;
-          return resolveYjsType(rootMap, schema, path);
-        };
-      }
-      return cachedCtx;
-    },
-    version() {
-      return new YjsVersion(Y5.encodeStateVector(doc));
-    },
-    baseVersion() {
-      return new YjsVersion(new Uint8Array([0]));
-    },
-    advance(_to) {
-      throw new Error(
-        "advance() on a live Yjs substrate is not yet supported. Use advance() on a YjsReplica instead."
-      );
-    },
-    exportEntirety() {
-      return {
-        kind: "entirety",
-        encoding: "binary",
-        data: Y5.encodeStateAsUpdate(doc)
-      };
-    },
-    exportSince(since) {
-      try {
-        const bytes = Y5.encodeStateAsUpdate(doc, since.sv);
-        return { kind: "since", encoding: "binary", data: bytes };
-      } catch {
-        return null;
-      }
-    },
-    merge(payload, origin) {
-      if (payload.encoding !== "binary" || !(payload.data instanceof Uint8Array)) {
-        throw new Error(
-          "YjsSubstrate.merge expects binary-encoded payloads. If you recently switched CRDT backends, stale clients may be sending incompatible data."
-        );
-      }
-      pendingMergeOrigin = origin;
-      try {
-        Y5.applyUpdate(doc, payload.data, origin ?? "remote");
-      } finally {
-        pendingMergeOrigin = void 0;
-      }
-    }
-  };
-  rootMap.observeDeep((events, transaction) => {
-    if (transaction.origin === KYNETA_ORIGIN) {
-      return;
-    }
-    const ops = eventsToOps(events, schema);
-    if (ops.length === 0) {
-      return;
-    }
-    const origin = pendingMergeOrigin ?? (typeof transaction.origin === "string" ? transaction.origin : void 0);
-    const ctx = substrate.context();
-    inOurTransaction = true;
-    try {
-      executeBatch(ctx, ops, origin);
-    } finally {
-      inOurTransaction = false;
-    }
-  });
-  return substrate;
+//#endregion
+//#region src/substrate.ts
+const KYNETA_ORIGIN = "kyneta-prepare";
+/**
+* Creates a `Substrate<YjsVersion>` wrapping a user-provided Y.Doc.
+*
+* This is the "bring your own doc" entry point. The user creates and
+* manages the Y.Doc (possibly via a Yjs provider); this function wraps
+* it with a schema-aware overlay providing typed reads, writes,
+* versioning, and export/merge through the standard Substrate interface.
+*
+* **Event bridge contract:** A persistent `observeDeep` handler is
+* registered on the root Y.Map at construction time. All non-kyneta
+* mutations to the Y.Doc (merges, external local writes) are bridged
+* to the kyneta changefeed. Subscribing to the kyneta doc observes all
+* mutations regardless of source.
+*
+* @param doc - The Y.Doc to wrap. The substrate does NOT own the doc;
+*   the caller is responsible for its lifecycle.
+* @param schema - The root schema for the document.
+* @param binding - Optional SchemaBinding for identity-keyed containers.
+*/
+function createYjsSubstrate(doc, schema, binding) {
+	const pendingChanges = [];
+	let inOurTransaction = false;
+	let pendingMergeOrigin;
+	let cachedCtx;
+	let accumulatedDs = Y.createDeleteSetFromStructStore(doc.store);
+	const rootMap = doc.getMap("root");
+	const reader = yjsReader(doc, schema, binding);
+	const substrate = {
+		[BACKING_DOC]: doc,
+		reader,
+		prepare(path, change) {
+			if (!inOurTransaction) pendingChanges.push({
+				path,
+				change
+			});
+		},
+		onFlush(_origin) {
+			if (!inOurTransaction && pendingChanges.length > 0) {
+				inOurTransaction = true;
+				try {
+					doc.transact(() => {
+						for (const { path, change } of pendingChanges) applyChangeToYjs(rootMap, schema, path, change, binding);
+					}, KYNETA_ORIGIN);
+					pendingChanges.length = 0;
+				} finally {
+					inOurTransaction = false;
+				}
+			}
+		},
+		context() {
+			if (!cachedCtx) {
+				cachedCtx = buildWritableContext(substrate);
+				cachedCtx.nativeResolver = (nodeSchema, path) => {
+					if (path.segments.length === 0) return doc;
+					if (nodeSchema[KIND] === "scalar" || nodeSchema[KIND] === "sum") return void 0;
+					return resolveYjsType(rootMap, schema, path, binding).resolved;
+				};
+				cachedCtx.positionResolver = (_nodeSchema, path) => {
+					return {
+						createPosition(index, side) {
+							const { resolved: ytype } = resolveYjsType(rootMap, schema, path, binding);
+							if (!(ytype instanceof Y.Text)) throw new Error(`positionResolver: path does not resolve to a Y.Text`);
+							const assoc = toYjsAssoc(side);
+							return new YjsPosition(Y.createRelativePositionFromTypeIndex(ytype, index, assoc), doc);
+						},
+						decodePosition(bytes) {
+							return new YjsPosition(Y.decodeRelativePosition(bytes), doc);
+						}
+					};
+				};
+			}
+			return cachedCtx;
+		},
+		version() {
+			return YjsVersion.fromDeleteSet(doc, accumulatedDs);
+		},
+		baseVersion() {
+			return new YjsVersion(new Uint8Array([0]));
+		},
+		advance(_to) {
+			throw new Error("advance() on a live Yjs substrate is not yet supported. Use advance() on a YjsReplica instead.");
+		},
+		exportEntirety() {
+			return {
+				kind: "entirety",
+				encoding: "binary",
+				data: Y.encodeStateAsUpdate(doc)
+			};
+		},
+		exportSince(since) {
+			try {
+				return {
+					kind: "since",
+					encoding: "binary",
+					data: Y.encodeStateAsUpdate(doc, since.sv)
+				};
+			} catch {
+				return null;
+			}
+		},
+		merge(payload, origin) {
+			if (payload.encoding !== "binary" || !(payload.data instanceof Uint8Array)) throw new Error("YjsSubstrate.merge expects binary-encoded payloads. If you recently switched CRDT backends, stale clients may be sending incompatible data.");
+			pendingMergeOrigin = origin;
+			try {
+				Y.applyUpdate(doc, payload.data, origin ?? "remote");
+			} finally {
+				pendingMergeOrigin = void 0;
+			}
+		}
+	};
+	rootMap.observeDeep((events, transaction) => {
+		if (transaction.origin === KYNETA_ORIGIN) return;
+		const ops = eventsToOps(events, schema, binding);
+		if (ops.length === 0) return;
+		if (transaction.deleteSet.clients.size > 0) accumulatedDs = Y.mergeDeleteSets([accumulatedDs, transaction.deleteSet]);
+		const origin = pendingMergeOrigin ?? (typeof transaction.origin === "string" ? transaction.origin : void 0);
+		const ctx = substrate.context();
+		inOurTransaction = true;
+		try {
+			executeBatch(ctx, ops, origin);
+		} finally {
+			inOurTransaction = false;
+		}
+	});
+	doc.on("afterTransaction", (transaction) => {
+		if (transaction.origin === KYNETA_ORIGIN && transaction.deleteSet.clients.size > 0) accumulatedDs = Y.mergeDeleteSets([accumulatedDs, transaction.deleteSet]);
+	});
+	return substrate;
+}
+/**
+* Factory for constructing Yjs-backed substrates.
+*
+* - `create(schema)` — creates a fresh Y.Doc with empty containers
+*   matching the schema structure. No seed data — initial content
+*   should be applied via `change()` after construction.
+* - `fromEntirety(payload, schema)` — creates a Y.Doc from an entirety
+*   payload, returns a substrate.
+* - `parseVersion(serialized)` — deserializes a YjsVersion.
+*
+* Uses trivialBinding for identity-keying: every path maps to
+* `deriveIdentity(path, 1)` (generation 1, no renames).
+*/
+/**
+* Compute a trivial SchemaBinding for a schema with no migration history.
+* Every product field maps to `deriveIdentity(path, 1)`.
+*/
+function trivialBinding(schema) {
+	if (schema[KIND] === "product") return deriveSchemaBinding(schema, {});
+	return {
+		forward: /* @__PURE__ */ new Map(),
+		inverse: /* @__PURE__ */ new Map()
+	};
 }
+/**
+* Schema-free replica factory for Yjs substrates.
+*
+* Constructs headless `Replica<YjsVersion>` instances backed by bare
+* `Y.Doc`s — no schema walking, no container initialization, no
+* Reader, no event bridge, no changefeed. Just the CRDT runtime
+* with version tracking and export/merge.
+*
+* Used by conduit participants (stores, routing servers)
+* that need to accumulate state, compute per-peer deltas, and compact
+* storage without ever interpreting document fields.
+*/
 function createYjsReplica(doc) {
-  let currentDoc = doc;
-  let currentBase = new YjsVersion(Y5.encodeStateVector(new Y5.Doc()));
-  return {
-    get [BACKING_DOC]() {
-      return currentDoc;
-    },
-    version() {
-      return new YjsVersion(Y5.encodeStateVector(currentDoc));
-    },
-    baseVersion() {
-      return currentBase;
-    },
-    advance(to) {
-      const baseCmp = currentBase.compare(to);
-      if (baseCmp === "ahead") {
-        throw new Error("advance(): target is behind base version");
-      }
-      const currentCmp = to.compare(this.version());
-      if (currentCmp === "ahead") {
-        throw new Error("advance(): target is ahead of current version");
-      }
-      if (currentCmp !== "equal") return;
-      const update = Y5.encodeStateAsUpdate(currentDoc);
-      const newDoc = new Y5.Doc();
-      Y5.applyUpdate(newDoc, update);
-      currentDoc = newDoc;
-      currentBase = new YjsVersion(Y5.encodeStateVector(currentDoc));
-    },
-    exportEntirety() {
-      return {
-        kind: "entirety",
-        encoding: "binary",
-        data: Y5.encodeStateAsUpdate(currentDoc)
-      };
-    },
-    exportSince(since) {
-      try {
-        const bytes = Y5.encodeStateAsUpdate(currentDoc, since.sv);
-        return { kind: "since", encoding: "binary", data: bytes };
-      } catch {
-        return null;
-      }
-    },
-    merge(payload, _origin) {
-      if (payload.encoding !== "binary" || !(payload.data instanceof Uint8Array)) {
-        throw new Error(
-          "YjsReplica.merge expects binary-encoded payloads. If you recently switched CRDT backends, stale clients may be sending incompatible data."
-        );
-      }
-      Y5.applyUpdate(currentDoc, payload.data);
-    }
-  };
-}
-var yjsReplicaFactory = {
-  replicaType: ["yjs", 1, 0],
-  createEmpty() {
-    return createYjsReplica(new Y5.Doc());
-  },
-  fromEntirety(payload) {
-    if (payload.encoding !== "binary" || !(payload.data instanceof Uint8Array)) {
-      throw new Error(
-        "YjsReplicaFactory.fromEntirety only supports binary-encoded payloads"
-      );
-    }
-    const doc = new Y5.Doc();
-    Y5.applyUpdate(doc, payload.data);
-    return createYjsReplica(doc);
-  },
-  parseVersion(serialized) {
-    return YjsVersion.parse(serialized);
-  }
+	let currentDoc = doc;
+	let currentBase = new YjsVersion(Y.encodeStateVector(new Y.Doc()));
+	return {
+		get [BACKING_DOC]() {
+			return currentDoc;
+		},
+		version() {
+			return YjsVersion.fromDoc(currentDoc);
+		},
+		baseVersion() {
+			return currentBase;
+		},
+		advance(to) {
+			if (currentBase.compare(to) === "ahead") throw new Error("advance(): target is behind base version");
+			const currentCmp = to.compare(this.version());
+			if (currentCmp === "ahead") throw new Error("advance(): target is ahead of current version");
+			if (currentCmp !== "equal") return;
+			const update = Y.encodeStateAsUpdate(currentDoc);
+			const newDoc = new Y.Doc();
+			Y.applyUpdate(newDoc, update);
+			currentDoc = newDoc;
+			currentBase = YjsVersion.fromDoc(currentDoc);
+		},
+		exportEntirety() {
+			return {
+				kind: "entirety",
+				encoding: "binary",
+				data: Y.encodeStateAsUpdate(currentDoc)
+			};
+		},
+		exportSince(since) {
+			try {
+				return {
+					kind: "since",
+					encoding: "binary",
+					data: Y.encodeStateAsUpdate(currentDoc, since.sv)
+				};
+			} catch {
+				return null;
+			}
+		},
+		merge(payload, _origin) {
+			if (payload.encoding !== "binary" || !(payload.data instanceof Uint8Array)) throw new Error("YjsReplica.merge expects binary-encoded payloads. If you recently switched CRDT backends, stale clients may be sending incompatible data.");
+			Y.applyUpdate(currentDoc, payload.data);
+		}
+	};
+}
+const yjsReplicaFactory = {
+	replicaType: [
+		"yjs",
+		1,
+		0
+	],
+	createEmpty() {
+		return createYjsReplica(new Y.Doc());
+	},
+	fromEntirety(payload) {
+		if (payload.encoding !== "binary" || !(payload.data instanceof Uint8Array)) throw new Error("YjsReplicaFactory.fromEntirety only supports binary-encoded payloads");
+		const doc = new Y.Doc();
+		Y.applyUpdate(doc, payload.data);
+		return createYjsReplica(doc);
+	},
+	parseVersion(serialized) {
+		return YjsVersion.parse(serialized);
+	}
 };
-var yjsSubstrateFactory = {
-  replica: yjsReplicaFactory,
-  createReplica() {
-    return createYjsReplica(new Y5.Doc());
-  },
-  upgrade(replica, schema) {
-    const doc = replica[BACKING_DOC];
-    ensureContainers(doc, schema, true);
-    return createYjsSubstrate(doc, schema);
-  },
-  create(schema) {
-    const doc = new Y5.Doc();
-    ensureContainers(doc, schema);
-    return createYjsSubstrate(doc, schema);
-  },
-  fromEntirety(payload, schema) {
-    const replica = this.createReplica();
-    replica.merge(payload);
-    return this.upgrade(replica, schema);
-  },
-  parseVersion(serialized) {
-    return YjsVersion.parse(serialized);
-  }
+const yjsSubstrateFactory = {
+	replica: yjsReplicaFactory,
+	createReplica() {
+		return createYjsReplica(new Y.Doc());
+	},
+	upgrade(replica, schema) {
+		const doc = replica[BACKING_DOC];
+		const binding = trivialBinding(schema);
+		ensureContainers(doc, schema, true, binding);
+		return createYjsSubstrate(doc, schema, binding);
+	},
+	create(schema) {
+		const doc = new Y.Doc();
+		const binding = trivialBinding(schema);
+		ensureContainers(doc, schema, false, binding);
+		return createYjsSubstrate(doc, schema, binding);
+	},
+	fromEntirety(payload, schema) {
+		const replica = this.createReplica();
+		replica.merge(payload);
+		return this.upgrade(replica, schema);
+	},
+	parseVersion(serialized) {
+		return YjsVersion.parse(serialized);
+	}
 };
-
-// src/bind-yjs.ts
+//#endregion
+//#region src/bind-yjs.ts
+/**
+* Hash a string peerId to a deterministic numeric Yjs clientID.
+*
+* Yjs clientIDs are unsigned 32-bit integers. We use FNV-1a hash to
+* produce a deterministic uint32 from the string peerId.
+*
+* The hash is deterministic: the same string always produces the same
+* numeric clientID, across restarts and across machines.
+*/
 function hashPeerId(peerId) {
-  let hash = 2166136261;
-  for (let i = 0; i < peerId.length; i++) {
-    hash ^= peerId.charCodeAt(i);
-    hash = Math.imul(hash, 16777619);
-  }
-  const result = hash >>> 0;
-  return result === STRUCTURAL_YJS_CLIENT_ID2 ? 1 : result;
-}
-function createYjsFactory(peerId) {
-  const numericClientId = hashPeerId(peerId);
-  return {
-    replica: yjsReplicaFactory,
-    createReplica() {
-      return createYjsReplica(new Y6.Doc());
-    },
-    upgrade(replica, schema) {
-      const doc = replica[BACKING_DOC2];
-      doc.clientID = numericClientId;
-      ensureContainers(doc, schema, true);
-      return createYjsSubstrate(doc, schema);
-    },
-    create(schema) {
-      const doc = new Y6.Doc();
-      doc.clientID = numericClientId;
-      ensureContainers(doc, schema);
-      return createYjsSubstrate(doc, schema);
-    },
-    fromEntirety(payload, schema) {
-      const replica = this.createReplica();
-      replica.merge(payload);
-      return this.upgrade(replica, schema);
-    },
-    parseVersion(serialized) {
-      return YjsVersion.parse(serialized);
-    }
-  };
-}
-var yjs = createSubstrateNamespace({
-  strategies: {
-    collaborative: {
-      factory: (ctx) => createYjsFactory(ctx.peerId),
-      replicaFactory: yjsReplicaFactory
-    },
-    ephemeral: {
-      factory: (ctx) => createYjsFactory(ctx.peerId),
-      replicaFactory: yjsReplicaFactory
-    }
-  },
-  defaultStrategy: "collaborative"
+	let hash = 2166136261;
+	for (let i = 0; i < peerId.length; i++) {
+		hash ^= peerId.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	const result = hash >>> 0;
+	return result === STRUCTURAL_YJS_CLIENT_ID ? 1 : result;
+}
+/**
+* Create a SubstrateFactory<YjsVersion> that sets doc.clientID
+* on every new Y.Doc with a deterministic uint32 clientID derived
+* from the exchange's string peerId.
+*/
+function createYjsFactory(peerId, binding) {
+	const numericClientId = hashPeerId(peerId);
+	return {
+		replica: yjsReplicaFactory,
+		createReplica() {
+			return createYjsReplica(new Y.Doc());
+		},
+		upgrade(replica, schema) {
+			const doc = replica[BACKING_DOC];
+			doc.clientID = numericClientId;
+			ensureContainers(doc, schema, true, binding);
+			return createYjsSubstrate(doc, schema, binding);
+		},
+		create(schema) {
+			const doc = new Y.Doc();
+			doc.clientID = numericClientId;
+			ensureContainers(doc, schema, false, binding);
+			return createYjsSubstrate(doc, schema, binding);
+		},
+		fromEntirety(payload, schema) {
+			const replica = this.createReplica();
+			replica.merge(payload);
+			return this.upgrade(replica, schema);
+		},
+		parseVersion(serialized) {
+			return YjsVersion.parse(serialized);
+		}
+	};
+}
+/**
+* The Yjs CRDT binding target.
+*
+* - `yjs.bind(schema)` — bind a schema to Yjs with collaborative sync
+* - `yjs.replica()` — create a collaborative replica
+*
+* Laws are constrained to `YjsLaws` — schemas requiring composition laws
+* outside this set (e.g. `"additive"` from `Schema.counter()`,
+* `"positional-ot-move"` from `Schema.movableList()`) are rejected at
+* compile time.
+*
+* To access the underlying Y.Doc, use `unwrap(ref)` from `@kyneta/schema`.
+*/
+const yjs = createBindingTarget({
+	factory: (ctx) => createYjsFactory(ctx.peerId, ctx.binding),
+	replicaFactory: yjsReplicaFactory,
+	syncProtocol: SYNC_COLLABORATIVE
 });
-export {
-  NATIVE,
-  Schema,
-  YjsVersion,
-  applyChangeToYjs,
-  applyChanges,
-  change,
-  createDoc,
-  createRef,
-  createYjsSubstrate,
-  ensureContainers,
-  eventsToOps,
-  exportEntirety,
-  exportSince,
-  merge,
-  resolveYjsType,
-  stepIntoYjs,
-  subscribe,
-  subscribeNode,
-  unwrap,
-  version,
-  yjs,
-  yjsReader,
-  yjsReplicaFactory,
-  yjsSubstrateFactory
-};
+//#endregion
+export { NATIVE, Schema, YjsPosition, YjsVersion, applyChangeToYjs, applyChanges, change, createDoc, createRef, createYjsSubstrate, ensureContainers, eventsToOps, exportEntirety, exportSince, fromYjsAssoc, merge, resolveYjsType, stepIntoYjs, subscribe, subscribeNode, toYjsAssoc, unwrap, version, yjs, yjsReader, yjsReplicaFactory, yjsSubstrateFactory };
+
 //# sourceMappingURL=index.js.map