@kyneta/yjs-schema 1.7.0 → 1.8.0

package/README.md

@@ -139,6 +139,8 @@ yjsDoc.getMap("root").toJSON()  // raw state
 yjsDoc.clientID                  // client ID
 ```
 
+*Note for raw Y.Doc consumers:* Subscribers attached directly to the underlying `Y.Doc` will newly see `options.origin` faithfully on `transaction.origin` (where previously it was silently dropped).
+
 ## Yjs Ecosystem Compatibility
 
 Because `yjs(doc)` returns a standard `Y.Doc`, the entire Yjs provider ecosystem works out of the box:

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/native-map.ts","../src/bind-yjs.ts","../src/change-mapping.ts","../src/populate.ts","../src/position.ts","../src/version.ts","../src/substrate.ts","../src/yjs-resolve.ts"],"mappings":";;;;;;;;;;AAwBA;;;;;;;;;;;;UAAiB,YAAA,SAAqB,SAAA;EAAA,SAC3B,IAAA,EAAM,CAAA,CAAE,GAAA;EAAA,SACR,IAAA,EAAM,CAAA,CAAE,IAAA;EAAA,SACR,OAAA;EAAA,SACA,IAAA,EAAM,CAAA,CAAE,KAAA;EAAA,SACR,WAAA;EAAA,SACA,MAAA,EAAQ,CAAA,CAAE,GAAA;EAAA,SACV,GAAA,EAAK,CAAA,CAAE,GAAA;EAAA,SACP,IAAA;EAAA,SACA,GAAA;EAAA,SACA,MAAA;EAAA,SACA,GAAA;AAAA;;;;;;;KC8GC,OAAA;;;;;;;;;;;;;;cAmBC,GAAA,EAAK,aAAA,CAAc,OAAA,EAAS,YAAA;;;;;;;AD5IzC;;;;;;;;iBEqCgB,gBAAA,CACd,OAAA,EAAS,CAAA,CAAE,GAAA,OACX,UAAA,EAAY,QAAA,EACZ,IAAA,EAAM,IAAA,EACN,MAAA,EAAQ,UAAA,EACR,OAAA,GAAU,aAAA;;;;;;;;;;;;;;iBAscI,WAAA,CACd,MAAA,EAAQ,CAAA,CAAE,MAAA,SACV,MAAA,EAAQ,QAAA,EACR,OAAA,GAAU,aAAA,GACT,IAAA;;;;;;;AFpfH;;;;;;;;;;;;;;;;;;;;;;;iBG6BgB,gBAAA,CACd,GAAA,EAAK,CAAA,CAAE,GAAA,EACP,MAAA,EAAQ,QAAA,EACR,OAAA,GAAU,aAAA;;;;iBC9CI,UAAA,CAAW,IAAU,EAAJ,IAAI;;iBAKrB,YAAA,CAAa,KAAA,WAAgB,IAAI;AAAA,cAIpC,WAAA,YAAuB,QAAA;EAAA,iBAIf,IAAA;EAAA,iBACA,GAAA;EAAA,SAJV,IAAA,EAAM,IAAA;cAGI,IAAA,EAAM,CAAA,CAAE,gBAAA,EACR,GAAA,EAAK,CAAA,CAAE,GAAA;EAK1B,OAAA,CAAA;EAQA,MAAA,CAAA,GAAU,UAAA;EAIV,SAAA,CAAU,aAAA,WAAwB,WAAA;AAAA;;;;;;;AJjBpC;;;;;;;;;;;;;;;cK8Ea,UAAA,YAAsB,OAAA;EL5ElB;EAAA,SK8EN,EAAA,EAAI,UAAA;EL7EJ;;;;;EAAA,SKoFA,aAAA,EAAe,UAAA;cAEZ,EAAA,EAAI,UAAA,EAAY,aAAA,GAAgB,UAAA;ELnFzB;;;;;;EAAA,OK+FZ,OAAA,CAAQ,GAAA,EAAK,GAAA,GAAM,UAAA;EL1FjB;;AAAG;;;;AC8Gd;;;ED9GW,OKyGF,aAAA,CACL,GAAA,EAAK,GAAA,EACL,EAAA,EAAI,UAAA,QADI,CAAA,CAC4B,eAAA,IACnC,UAAA;EJEc;AAmBnB;;;;;EIRE,SAAA,CAAA;EJQ6B;;;;;;AAAsB;;;;ACvGrD;;;;EGmHE,OAAA,CAAQ,KAAA,EAAO,OAAA;EHhHT;;;;;;;;;;;;;EG4IN,IAAA,CAAK,KAAA,EAAO,OAAA,GAAU,UAAA;EH1IZ;;;AAAa;AAsczB;;;;;EAtcY,OG+JH,KAAA,CAAM,UAAA,WAAqB,UAAA;AAAA;;;;;;ALzMpC;;;;;;;;;;;;;;;;iBMiEgB,kBAAA,CACd,GAAA,EAAK,CAAA,CAAE,GAAA,EACP,MAAA,EAAQ,QAAA,EACR,OAAA,GAAU,aAAA,GACT,SAAA,CAAU,UAAA;AAAA,cAkWA,iBAAA,EAAmB,cAAc,CAAC,UAAA;AAAA,cA8BlC,mBAAA,EAAqB,gBAAgB,CAAC,UAAA;;;;;;;ANrcnD;;;;;;;;;cOiBa,WAAA,EAAa,WAsBzB;;;;;;;;;;;;iBAiBe,cAAA,CACd,OAAA,EAAS,CAAA,CAAE,GAAA,OACX,UAAA,EAAY,QAAA,EACZ,IAAA,EAAM,IAAA,EACN,OAAA,GAAU,aAAA,GACT,cAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/native-map.ts","../src/bind-yjs.ts","../src/change-mapping.ts","../src/populate.ts","../src/position.ts","../src/version.ts","../src/substrate.ts","../src/yjs-resolve.ts"],"mappings":";;;;;;;;;;AAwBA;;;;;;;;;;;;UAAiB,YAAA,SAAqB,SAAA;EAAA,SAC3B,IAAA,EAAM,CAAA,CAAE,GAAA;EAAA,SACR,IAAA,EAAM,CAAA,CAAE,IAAA;EAAA,SACR,OAAA;EAAA,SACA,IAAA,EAAM,CAAA,CAAE,KAAA;EAAA,SACR,WAAA;EAAA,SACA,MAAA,EAAQ,CAAA,CAAE,GAAA;EAAA,SACV,GAAA,EAAK,CAAA,CAAE,GAAA;EAAA,SACP,IAAA;EAAA,SACA,GAAA;EAAA,SACA,MAAA;EAAA,SACA,GAAA;AAAA;;;;;;;KC8GC,OAAA;;;;;;;;;;;;;;cAmBC,GAAA,EAAK,aAAA,CAAc,OAAA,EAAS,YAAA;;;;;;;AD5IzC;;;;;;;;iBEuCgB,gBAAA,CACd,OAAA,EAAS,CAAA,CAAE,GAAA,OACX,UAAA,EAAY,QAAA,EACZ,IAAA,EAAM,IAAA,EACN,MAAA,EAAQ,UAAA,EACR,OAAA,GAAU,aAAA;;;;;;;;;;;;;;iBAkcI,WAAA,CACd,MAAA,EAAQ,CAAA,CAAE,MAAA,SACV,MAAA,EAAQ,QAAA,EACR,OAAA,GAAU,aAAA,GACT,IAAA;;;;;;;AFlfH;;;;;;;;;;;;;;;;;;;;;;;iBG6BgB,gBAAA,CACd,GAAA,EAAK,CAAA,CAAE,GAAA,EACP,MAAA,EAAQ,QAAA,EACR,OAAA,GAAU,aAAA;;;;iBC9CI,UAAA,CAAW,IAAU,EAAJ,IAAI;;iBAKrB,YAAA,CAAa,KAAA,WAAgB,IAAI;AAAA,cAIpC,WAAA,YAAuB,QAAA;EAAA,iBAIf,IAAA;EAAA,iBACA,GAAA;EAAA,SAJV,IAAA,EAAM,IAAA;cAGI,IAAA,EAAM,CAAA,CAAE,gBAAA,EACR,GAAA,EAAK,CAAA,CAAE,GAAA;EAK1B,OAAA,CAAA;EAQA,MAAA,CAAA,GAAU,UAAA;EAIV,SAAA,CAAU,aAAA,WAAwB,WAAA;AAAA;;;;;;;AJjBpC;;;;;;;;;;;;;;;cK8Ea,UAAA,YAAsB,OAAA;EL5ElB;EAAA,SK8EN,EAAA,EAAI,UAAA;EL7EJ;;;;;EAAA,SKoFA,aAAA,EAAe,UAAA;cAEZ,EAAA,EAAI,UAAA,EAAY,aAAA,GAAgB,UAAA;ELnFzB;;;;;;EAAA,OK+FZ,OAAA,CAAQ,GAAA,EAAK,GAAA,GAAM,UAAA;EL1FjB;;AAAG;;;;AC8Gd;;;ED9GW,OKyGF,aAAA,CACL,GAAA,EAAK,GAAA,EACL,EAAA,EAAI,UAAA,QADI,CAAA,CAC4B,eAAA,IACnC,UAAA;EJEc;AAmBnB;;;;;EIRE,SAAA,CAAA;EJQ6B;;;;;;AAAsB;;;;ACrGrD;;;;EGiHE,OAAA,CAAQ,KAAA,EAAO,OAAA;EH9GT;;;;;;;;;;;;;EG0IN,IAAA,CAAK,KAAA,EAAO,OAAA,GAAU,UAAA;EHxIZ;;;AAAa;AAkczB;;;;;EAlcY,OG6JH,KAAA,CAAM,UAAA,WAAqB,UAAA;AAAA;;;;;;ALzMpC;;;;;;;;;;;;;;;;iBMiGgB,kBAAA,CACd,GAAA,EAAK,CAAA,CAAE,GAAA,EACP,MAAA,EAAQ,QAAA,EACR,OAAA,GAAU,aAAA,GACT,SAAA,CAAU,UAAA;AAAA,cA2dA,iBAAA,EAAmB,cAAc,CAAC,UAAA;AAAA,cA8BlC,mBAAA,EAAqB,gBAAgB,CAAC,UAAA;;;;;;;AN9lBnD;;;;;;;;;cOiBa,WAAA,EAAa,WAsBzB;;;;;;;;;;;;iBAiBe,cAAA,CACd,OAAA,EAAS,CAAA,CAAE,GAAA,OACX,UAAA,EAAY,QAAA,EACZ,IAAA,EAAM,IAAA,EACN,OAAA,GAAU,aAAA,GACT,cAAA"}

package/dist/index.js

@@ -1,4 +1,4 @@
-import { BACKING_DOC, KIND, NATIVE, RawPath, STRUCTURAL_YJS_CLIENT_ID, SYNC_COLLABORATIVE, Schema, applyChange, applyChanges, base64ToUint8Array, buildWritableContext, change, createBindingTarget, createDoc, createMaterializeInterpreter, createRef, deriveSchemaBinding, executeBatch, expandMapOpsToLeaves, exportEntirety, exportSince, foldPath, interpret, isNonNullObject, materializeContextFromResolver, merge, pathSchema, plainReader, 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
@@ -61,6 +61,7 @@ function ensureContainers(doc, schema, binding) {
 */
 function ensureRootField(rootMap, key, fieldSchema, binding, prefix) {
 	if (rootMap.has(key)) return;
+	if (isJsonBoundary(fieldSchema)) return;
 	switch (fieldSchema[KIND]) {
 		case "text":
 		case "richtext":
@@ -106,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":
@@ -258,7 +260,7 @@ 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);
@@ -291,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();
@@ -311,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;
@@ -322,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));
@@ -820,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.
 *
@@ -841,46 +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 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) applyChange(shadow, path, change);
 			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) {
+		afterBatch(options) {
 			if (options?.replay) {
-				const fresh = materializeYjsShadow(doc, schema, binding);
-				for (const key of Object.keys(fresh)) shadow[key] = fresh[key];
-				for (const key of Object.keys(shadow)) if (!(key in fresh)) delete shadow[key];
+				syncShadow(shadow, materializeYjsShadow(doc, schema, binding));
 				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;
+			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);
@@ -892,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]));
@@ -934,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;
 }
 /**