@kyneta/yjs-schema 1.6.1 → 1.8.0

package/dist/index.js

@@ -1,4 +1,4 @@
-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 { BACKING_DOC, KIND, NATIVE, RECORD_INVERSE, RawPath, STRUCTURAL_YJS_CLIENT_ID, SYNC_COLLABORATIVE, Schema, applyChange, applyChanges, base64ToUint8Array, buildWritableContext, change, createBindingTarget, createDoc, createMaterializeInterpreter, createRef, deepClonePreState, deriveSchemaBinding, executeBatch, expandMapOpsToLeaves, exportEntirety, exportSince, findJsonBoundary, foldPath, interpret, invert, isJsonBoundary, isNonNullObject, isPlainObject, materializeContextFromResolver, merge, pathSchema, plainReader, richTextChange, subscribe, subscribeNode, syncShadow, uint8ArrayToBase64, unwrap, version, versionVectorCompare, versionVectorMeet } from "@kyneta/schema";
 import * as Y from "yjs";
 import { createSnapshot, decodeStateVector, encodeSnapshot, encodeStateVector, snapshot } from "yjs";
 //#region src/populate.ts
@@ -10,14 +10,10 @@ import { createSnapshot, decodeStateVector, encodeSnapshot, encodeStateVector, s
 * 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.
+* Container fields (text, product, sequence, map) are created if absent;
+* existing containers are preserved (calling `rootMap.set()` on a field
+* that already exists would be a destructive CRDT write). Scalar and sum
+* fields are no-ops — the materializer handles zeros.
 *
 * **Structural identity:** This function temporarily sets `doc.clientID`
 * to `STRUCTURAL_YJS_CLIENT_ID` (0) for the duration of container creation,
@@ -31,22 +27,16 @@ import { createSnapshot, decodeStateVector, encodeSnapshot, encodeStateVector, s
 *
 * @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) {
+function ensureContainers(doc, schema, 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);
-			}
+			for (const [key, fieldSchema] of Object.entries(schema.fields).sort(([a], [b]) => a.localeCompare(b))) ensureRootField(rootMap, binding?.forward.get(key) ?? key, fieldSchema, binding, key);
 		});
 	} finally {
 		doc.clientID = savedClientID;
@@ -60,7 +50,7 @@ function ensureContainers(doc, schema, conditional = false, binding) {
 * - `"product"` → empty Y.Map (recursive for nested products)
 * - `"sequence"` → empty Y.Array
 * - `"map"` → empty Y.Map
-* - `"scalar"` / `"sum"` → Zero.structural default
+* - `"scalar"` / `"sum"` → no-op (materializer zero fallback)
 * - `"counter"` / `"set"` / `"tree"` / `"movable"` → throw (not supported by Yjs)
 *
 * @param rootMap - The root Y.Map to set the field on.
@@ -70,6 +60,8 @@ function ensureContainers(doc, schema, conditional = false, binding) {
 * @param prefix - The absolute schema path prefix for this field (used for nested lookups).
 */
 function ensureRootField(rootMap, key, fieldSchema, binding, prefix) {
+	if (rootMap.has(key)) return;
+	if (isJsonBoundary(fieldSchema)) return;
 	switch (fieldSchema[KIND]) {
 		case "text":
 		case "richtext":
@@ -85,11 +77,7 @@ function ensureRootField(rootMap, key, fieldSchema, binding, prefix) {
 			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 "sum": return;
 		case "counter":
 		case "set":
 		case "tree":
@@ -102,7 +90,7 @@ function ensureRootField(rootMap, key, fieldSchema, binding, prefix) {
 *
 * 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.
+* Scalar and sum fields are skipped (materializer zero fallback).
 *
 * **Identity-keying:** When a `binding` is provided, computes the
 * absolute schema path for each nested field (`prefix.fieldName`) and
@@ -119,6 +107,7 @@ function ensureMapContainers(schema, binding, prefix) {
 	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;
+		if (isJsonBoundary(fieldSchema)) continue;
 		switch (fieldSchema[KIND]) {
 			case "text":
 			case "richtext":
@@ -134,11 +123,7 @@ function ensureMapContainers(schema, binding, prefix) {
 				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 "sum": break;
 			case "counter":
 			case "set":
 			case "tree":
@@ -158,68 +143,29 @@ function ensureMapContainers(schema, binding, prefix) {
 * - `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
+* `_nextSchema` is part of the `PathStepper` contract for Loro's root
+* dispatch but is unused here — Yjs's `instanceof` dispatch doesn't
+* need to look ahead at the next schema kind.
 */
-function stepIntoYjs(current, segment, identity) {
+const stepIntoYjs = (current, _nextSchema, 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.
+* Thin wrapper around `foldPath(stepIntoYjs, ...)`. Returns the
+* `PathFoldResult` shape from core — `{ resolved, schema }`.
 *
-* 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).
+* When a `binding` is provided, every product-field boundary uses the
+* identity hash from `binding.forward` instead of the field name.
 *
-* 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.
+* For an empty path, returns the root map and root schema.
 */
 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;
-		if (schema[KIND] === "sum" && i + 1 < path.length) {
-			for (let j = i + 1; j < path.length; j++) {
-				const remaining = path.segments[j];
-				if (!remaining) throw new Error(`Missing segment at index ${j}`);
-				current = current?.[remaining.resolve()];
-			}
-			return {
-				resolved: current,
-				schema
-			};
-		}
-	}
-	return {
-		resolved: current,
-		schema
-	};
+	return foldPath(rootMap, rootSchema, path, stepIntoYjs, binding);
 }
 //#endregion
 //#region src/change-mapping.ts
@@ -254,6 +200,7 @@ function applyChangeToYjs(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)}].`);
+		case "set-op": throw new Error(`Yjs substrate does not support "${change.type}" changes. Schema.set requires "add-wins-per-key" which is not in YjsLaws. Attempted SetChange at path [${pathToString(path)}].`);
 		default: throw new Error(`applyChangeToYjs: unsupported change type "${change.type}"`);
 	}
 }
@@ -284,7 +231,7 @@ function applyRichTextChange(rootMap, rootSchema, path, change, binding) {
 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));
+	const itemSchema = getItemSchema(pathSchema(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);
@@ -298,13 +245,13 @@ function applySequenceChange(rootMap, rootSchema, path, change, binding) {
 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);
+	const targetSchema = pathSchema(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 parentAbsPath = path.segments.filter((s) => s.role === "field").map((s) => s.resolve()).join(".");
 			const absPath = parentAbsPath ? `${parentAbsPath}.${key}` : key;
 			const identity = binding.forward.get(absPath);
 			if (identity) mapKey = identity;
@@ -313,24 +260,24 @@ function applyMapChange(rootMap, rootSchema, path, change, binding) {
 	}
 }
 function applyReplaceChange(rootMap, rootSchema, path, change, binding) {
-	if (path.length === 0) throw new Error("applyChangeToYjs: ReplaceChange at root path is not supported");
+	if (path.length === 0) throw new Error("Cannot replace the root document struct in a CRDT backend. The root identity is fixed. Please mutate its properties individually (e.g., `doc.myField.set(value)` instead of `doc.set({ myField: value })`).");
 	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);
+	if (parent instanceof Y.Map && (lastSeg.role === "field" || lastSeg.role === "entry")) {
+		const targetSchema = pathSchema(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(".");
+		if (binding && lastSeg.role === "field") {
+			const absPath = path.segments.filter((s) => s.role === "field").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 targetSchema = pathSchema(rootSchema, path);
 		const yjsValue = maybeCreateSharedType(change.value, targetSchema);
 		parent.delete(resolved, 1);
 		parent.insert(resolved, [yjsValue]);
@@ -346,6 +293,7 @@ function applyReplaceChange(rootMap, rootSchema, path, change, binding) {
 */
 function maybeCreateSharedType(value, schema) {
 	if (schema === void 0) return value;
+	if (isJsonBoundary(schema)) return value;
 	switch (schema[KIND]) {
 		case "text": {
 			const text = new Y.Text();
@@ -366,7 +314,7 @@ function maybeCreateSharedType(value, schema) {
 			return text;
 		}
 		case "product":
-			if (value === null || value === void 0 || typeof value !== "object" || Array.isArray(value)) return value;
+			if (!isPlainObject(value)) return value;
 			return createStructuredMap(value, schema);
 		case "sequence": {
 			if (!Array.isArray(value)) return value;
@@ -377,7 +325,7 @@ function maybeCreateSharedType(value, schema) {
 			return arr;
 		}
 		case "map": {
-			if (value === null || value === void 0 || typeof value !== "object" || Array.isArray(value)) return value;
+			if (!isPlainObject(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));
@@ -431,7 +379,7 @@ function createStructuredMap(obj, productSchema) {
 function eventsToOps(events, schema, binding) {
 	const ops = [];
 	for (const event of events) {
-		const kynetaPath = yjsPathToKynetaPath(event.path, binding);
+		const kynetaPath = yjsPathToKynetaPath(event.path, schema, binding);
 		const change = eventToChange(event, schema, kynetaPath, binding);
 		if (change) ops.push({
 			path: kynetaPath,
@@ -441,21 +389,44 @@ function eventsToOps(events, schema, binding) {
 	return expandMapOpsToLeaves(ops, schema);
 }
 /**
-* Convert a Yjs event path (array of string | number) to a kyneta Path.
+* Convert a Yjs event path to a kyneta `RawPath`, walking the schema
+* alongside so each segment is classified as field / entry / index by
+* the current schema kind.
 *
-* `event.path` from `observeDeep` is relative to the observed type.
-* Strings become key segments, numbers become index segments.
+* Why schema-aware and not "did the inverse lookup hit?": the binding's
+* inverse map only covers declared product-field positions reachable
+* without crossing a runtime-keyed container. A declared struct field
+* nested under a `record(...)` value type is reachable via Yjs but
+* absent from `binding.inverse` — without the schema walk it would be
+* misclassified as an entry and then rejected by `advanceSchema`.
 */
-function yjsPathToKynetaPath(yjsPath, binding) {
+function yjsPathToKynetaPath(yjsPath, rootSchema, binding) {
 	let path = RawPath.empty;
+	let schema = rootSchema;
 	for (const segment of yjsPath) if (typeof segment === "string") {
+		let leaf = segment;
 		const absPath = binding?.inverse.get(segment);
 		if (absPath) {
 			const lastDot = absPath.lastIndexOf(".");
-			const leaf = lastDot >= 0 ? absPath.slice(lastDot + 1) : absPath;
+			leaf = lastDot >= 0 ? absPath.slice(lastDot + 1) : absPath;
+		}
+		const kind = schema?.[KIND];
+		if (kind === "product") {
 			path = path.field(leaf);
-		} else path = path.field(segment);
-	} else if (typeof segment === "number") path = path.item(segment);
+			schema = schema?.fields[leaf];
+		} else if (kind === "map" || kind === "set" || kind === "tree") {
+			path = path.entry(leaf);
+			schema = schema?.item;
+		} else {
+			path = path.entry(leaf);
+			schema = void 0;
+		}
+	} else if (typeof segment === "number") {
+		path = path.item(segment);
+		const kind = schema?.[KIND];
+		if (kind === "sequence" || kind === "movable") schema = schema.item;
+		else schema = void 0;
+	}
 	return path;
 }
 /**
@@ -470,7 +441,7 @@ function yjsPathToKynetaPath(yjsPath, binding) {
 */
 function eventToChange(event, rootSchema, kynetaPath, binding) {
 	if (event.target instanceof Y.Text) {
-		if (resolveSchemaAtPath(rootSchema, kynetaPath)[KIND] === "richtext") return richTextEventToChange(event);
+		if (pathSchema(rootSchema, kynetaPath)[KIND] === "richtext") return richTextEventToChange(event);
 		return textEventToChange(event);
 	}
 	if (event.target instanceof Y.Array) return arrayEventToChange(event);
@@ -583,17 +554,6 @@ function extractEventValue(value) {
 	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 = advanceSchema(schema, seg);
-		if (schema[KIND] === "sum") return schema;
-	}
-	return schema;
-}
-/**
 * Get the item schema from a sequence schema, if available.
 */
 function getItemSchema(schema) {
@@ -612,35 +572,7 @@ function pathToString(path) {
 	return path.segments.map((seg) => String(seg.resolve())).join(".");
 }
 //#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 {
-	rpos;
-	doc;
-	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
+//#region src/yjs-extract.ts
 /**
 * Extract a plain value from a Yjs shared type or return a plain value as-is.
 *
@@ -674,50 +606,71 @@ function yTextToRichTextDelta(ytext) {
 	}
 	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");
+//#endregion
+//#region src/materialize.ts
+function createYjsResolver(rootMap, rootSchema, binding) {
 	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);
+		resolveValue(path) {
+			return extractValue(resolveYjsType(rootMap, rootSchema, path, binding).resolved);
 		},
-		arrayLength(path) {
-			const { resolved } = resolveYjsType(rootMap, schema, path, binding);
+		resolveText(path) {
+			const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding);
+			if (resolved instanceof Y.Text) return resolved.toJSON();
+			const value = extractValue(resolved);
+			return typeof value === "string" ? value : void 0;
+		},
+		resolveCounter(_path) {},
+		resolveRichText(path) {
+			const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding);
+			if (resolved instanceof Y.Text) return yTextToRichTextDelta(resolved);
+		},
+		resolveLength(path) {
+			const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding);
 			if (resolved instanceof Y.Array) return resolved.length;
-			if (Array.isArray(resolved)) return resolved.length;
-			return 0;
+			return Array.isArray(resolved) ? resolved.length : 0;
 		},
-		keys(path) {
-			const { resolved } = resolveYjsType(rootMap, schema, path, binding);
+		resolveKeys(path) {
+			const { resolved } = resolveYjsType(rootMap, rootSchema, 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 [];
+			return isNonNullObject(resolved) ? Object.keys(resolved) : [];
 		},
-		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;
+		resolveForest(_path) {
+			return [];
 		}
 	};
 }
+function materializeYjsShadow(doc, schema, binding) {
+	const resolver = createYjsResolver(doc.getMap("root"), schema, binding);
+	return interpret(schema, createMaterializeInterpreter(resolver), materializeContextFromResolver(resolver));
+}
+//#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 {
+	rpos;
+	doc;
+	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/version.ts
 /**
@@ -870,7 +823,7 @@ var YjsVersion = class YjsVersion {
 };
 //#endregion
 //#region src/substrate.ts
-const KYNETA_ORIGIN = "kyneta-prepare";
+const KYNETA_MARK = Symbol("kyneta:own-commit");
 /**
 * Creates a `Substrate<YjsVersion>` wrapping a user-provided Y.Doc.
 *
@@ -891,39 +844,105 @@ const KYNETA_ORIGIN = "kyneta-prepare";
 * @param binding - Optional SchemaBinding for identity-keyed containers.
 */
 function createYjsSubstrate(doc, schema, binding) {
-	const pendingChanges = [];
+	const jsonBoundaryBuffer = /* @__PURE__ */ new Map();
 	let pendingMergeOrigin;
 	let cachedCtx;
-	let accumulatedDs = Y.createDeleteSetFromStructStore(doc.store);
 	const rootMap = doc.getMap("root");
-	const reader = yjsReader(doc, schema, binding);
+	const shadow = materializeYjsShadow(doc, schema, binding);
+	const reader = plainReader(shadow);
+	/**
+	* Compute the identity-aware boundary key (or numeric index) for a
+	* json-boundary write at `prefixLength`. Mirrors the Loro substrate's
+	* `boundaryKey`; field segments inside a bound product get the
+	* identity hash, others pass through raw.
+	*/
+	function boundaryKey(path, prefixLength) {
+		const seg = path.segments[prefixLength];
+		if (seg.role === "field" && binding) {
+			const absPath = path.segments.slice(0, prefixLength + 1).filter((s) => s.role === "field").map((s) => s.resolve()).join(".");
+			const identity = binding.forward.get(absPath);
+			if (identity) return identity;
+		}
+		return seg.resolve();
+	}
+	/**
+	* Buffer a json-boundary write. The boundary value is the entire σ
+	* subtree at the boundary path — already updated by the preceding
+	* `applyChange(shadow, ...)`. Subsequent writes inside the same
+	* subtree overwrite this entry (last-write-wins by σ snapshot).
+	*
+	* Returns silently when the parent container can't be resolved
+	* (root-level json fields land in `rootMap` directly — Yjs's
+	* root is the rootMap, so the parentResolved is `rootMap`).
+	*/
+	function stageJsonBoundaryWrite(path, prefixLength) {
+		const { resolved: parent } = resolveYjsType(rootMap, schema, path.slice(0, prefixLength), binding);
+		const value = path.slice(0, prefixLength + 1).read(shadow);
+		const key = boundaryKey(path, prefixLength);
+		let target;
+		if (parent instanceof Y.Map) target = parent;
+		else if (parent instanceof Y.Array) target = parent;
+		else throw new Error(`yjs substrate: json-boundary write to unsupported parent type at path ${path.format()}`);
+		const slot = `${`${target._item?.id?.client ?? "root"}:${target._item?.id?.clock ?? "root"}`}/${String(key)}`;
+		jsonBoundaryBuffer.set(slot, {
+			target,
+			key,
+			value
+		});
+	}
+	/**
+	* Drain the json-boundary buffer into λ. Called from `afterBatch`
+	* inside the ambient `Y.transact` opened by `runBatch`. Each entry
+	* is applied as `target.set(key, value)` for Y.Map parents or as a
+	* delete+insert for Y.Array parents (Yjs Arrays don't have a
+	* `set(index, value)` primitive — replace = delete one + insert one).
+	*/
+	function flushJsonBoundaryBuffer() {
+		if (jsonBoundaryBuffer.size === 0) return;
+		for (const { target, key, value } of jsonBoundaryBuffer.values()) if (target instanceof Y.Map) target.set(String(key), value);
+		else {
+			const index = key;
+			target.delete(index, 1);
+			target.insert(index, [value]);
+		}
+		jsonBoundaryBuffer.clear();
+	}
 	const substrate = {
 		[BACKING_DOC]: doc,
 		reader,
 		prepare(path, change, options) {
 			if (options?.replay) return;
-			pendingChanges.push({
-				path,
-				change
-			});
+			const record = options?.[RECORD_INVERSE];
+			if (record && !options?.compensating) record(path, invert(deepClonePreState(path.read(shadow)), change));
+			applyChange(shadow, path, change);
+			const boundary = findJsonBoundary(schema, path, binding);
+			if (boundary !== null) {
+				stageJsonBoundaryWrite(path, boundary.prefixLength);
+				return;
+			}
+			applyChangeToYjs(rootMap, schema, path, change, binding);
 		},
-		onFlush(options) {
-			if (options?.replay) return;
-			if (pendingChanges.length === 0) return;
-			doc.transact(() => {
-				for (const { path, change } of pendingChanges) applyChangeToYjs(rootMap, schema, path, change, binding);
-			}, KYNETA_ORIGIN);
-			pendingChanges.length = 0;
+		afterBatch(options) {
+			if (options?.replay) {
+				syncShadow(shadow, materializeYjsShadow(doc, schema, binding));
+				return;
+			}
+			flushJsonBoundaryBuffer();
+		},
+		runBatch(work, options) {
+			doc.transact((tr) => {
+				tr.meta.set(KYNETA_MARK, true);
+				work();
+			}, options?.origin);
 		},
 		context() {
-			if (!cachedCtx) {
-				cachedCtx = buildWritableContext(substrate);
-				cachedCtx.nativeResolver = (nodeSchema, path) => {
+			if (!cachedCtx) cachedCtx = buildWritableContext(substrate, {
+				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) => {
+				},
+				positionResolver: (_nodeSchema, path) => {
 					return {
 						createPosition(index, side) {
 							const { resolved: ytype } = resolveYjsType(rootMap, schema, path, binding);
@@ -935,12 +954,12 @@ function createYjsSubstrate(doc, schema, binding) {
 							return new YjsPosition(Y.decodeRelativePosition(bytes), doc);
 						}
 					};
-				};
-			}
+				}
+			});
 			return cachedCtx;
 		},
 		version() {
-			return YjsVersion.fromDeleteSet(doc, accumulatedDs);
+			return YjsVersion.fromDeleteSet(doc, Y.createDeleteSetFromStructStore(doc.store));
 		},
 		baseVersion() {
 			return new YjsVersion(new Uint8Array([0]));
@@ -977,19 +996,15 @@ function createYjsSubstrate(doc, schema, binding) {
 		}
 	};
 	rootMap.observeDeep((events, transaction) => {
-		if (transaction.origin === KYNETA_ORIGIN) return;
+		if (transaction.meta.get(KYNETA_MARK)) 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);
 		executeBatch(substrate.context(), ops, {
 			origin,
 			replay: true
 		});
 	});
-	doc.on("afterTransaction", (transaction) => {
-		if (transaction.origin === KYNETA_ORIGIN && transaction.deleteSet.clients.size > 0) accumulatedDs = Y.mergeDeleteSets([accumulatedDs, transaction.deleteSet]);
-	});
 	return substrate;
 }
 /**
@@ -1103,13 +1118,13 @@ const yjsSubstrateFactory = {
 	upgrade(replica, schema) {
 		const doc = replica[BACKING_DOC];
 		const binding = trivialBinding(schema);
-		ensureContainers(doc, schema, true, binding);
+		ensureContainers(doc, schema, binding);
 		return createYjsSubstrate(doc, schema, binding);
 	},
 	create(schema) {
 		const doc = new Y.Doc();
 		const binding = trivialBinding(schema);
-		ensureContainers(doc, schema, false, binding);
+		ensureContainers(doc, schema, binding);
 		return createYjsSubstrate(doc, schema, binding);
 	},
 	fromEntirety(payload, schema) {
@@ -1156,13 +1171,13 @@ function createYjsFactory(peerId, binding) {
 		upgrade(replica, schema) {
 			const doc = replica[BACKING_DOC];
 			doc.clientID = numericClientId;
-			ensureContainers(doc, schema, true, binding);
+			ensureContainers(doc, schema, binding);
 			return createYjsSubstrate(doc, schema, binding);
 		},
 		create(schema) {
 			const doc = new Y.Doc();
 			doc.clientID = numericClientId;
-			ensureContainers(doc, schema, false, binding);
+			ensureContainers(doc, schema, binding);
 			return createYjsSubstrate(doc, schema, binding);
 		},
 		fromEntirety(payload, schema) {
@@ -1194,6 +1209,6 @@ const yjs = createBindingTarget({
 	syncProtocol: SYNC_COLLABORATIVE
 });
 //#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 };
+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, yjsReplicaFactory, yjsSubstrateFactory };
 
 //# sourceMappingURL=index.js.map