@kyneta/yjs-schema 1.6.1 → 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

@@ -1,4 +1,4 @@
-import { BindingTarget, ChangeBase, DocRef, Instruction, NATIVE, NativeMap, Op, Op as Op$1, Path, Position, Reader, Ref, ReplicaFactory, Schema, Schema as Schema$1, SchemaBinding, Segment, Side, Substrate, SubstrateFactory, SubstratePayload, Version, applyChanges, change, createDoc, createRef, exportEntirety, exportSince, merge, subscribe, subscribeNode, unwrap, version } from "@kyneta/schema";
+import { BindingTarget, ChangeBase, DocRef, Instruction, NATIVE, NativeMap, Op, Op as Op$1, Path, PathFoldResult, PathStepper, Position, Ref, ReplicaFactory, Schema, Schema as Schema$1, SchemaBinding, Side, Substrate, SubstrateFactory, SubstratePayload, Version, applyChanges, change, createDoc, createRef, exportEntirety, exportSince, merge, subscribe, subscribeNode, unwrap, version } from "@kyneta/schema";
 import * as Y from "yjs";
 import { Doc } from "yjs";
 import { Changeset } from "@kyneta/changefeed";
@@ -93,14 +93,10 @@ declare function eventsToOps(events: Y.YEvent<any>[], schema: Schema$1, binding?
  * 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,
@@ -114,11 +110,9 @@ declare function eventsToOps(events: Y.YEvent<any>[], schema: Schema$1, binding?
  *
  * @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.
  */
-declare function ensureContainers(doc: Y.Doc, schema: Schema$1, conditional?: boolean, binding?: SchemaBinding): void;
+declare function ensureContainers(doc: Y.Doc, schema: Schema$1, binding?: SchemaBinding): void;
 //#endregion
 //#region src/position.d.ts
 /** Map kyneta Side to Yjs assoc. Left → -1 (left-sticky), Right → 0 (right-sticky). */
@@ -135,24 +129,6 @@ declare class YjsPosition implements Position {
   transform(_instructions: readonly Instruction[]): void;
 }
 //#endregion
-//#region src/reader.d.ts
-/**
- * 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.
- */
-declare function yjsReader(doc: Y.Doc, schema: Schema$1, binding?: SchemaBinding): Reader;
-//#endregion
 //#region src/version.d.ts
 /**
  * A Version wrapping a Yjs snapshot (state vector + delete set).
@@ -282,43 +258,23 @@ declare const yjsSubstrateFactory: SubstrateFactory<YjsVersion>;
  * - `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.
  */
-declare function stepIntoYjs(current: unknown, segment: Segment, identity?: string): unknown;
-/**
- * Result of resolving a Yjs shared type at a path.
- *
- * Includes both the resolved Yjs value and the schema at that position,
- * enabling callers to distinguish between schema kinds that map to the
- * same Yjs type (e.g. "text" vs "richtext" both use Y.Text).
- */
-interface ResolvedYjs {
-  readonly resolved: unknown;
-  readonly schema: Schema$1;
-}
+declare const stepIntoYjs: PathStepper;
 /**
  * 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.
  */
-declare function resolveYjsType(rootMap: Y.Map<any>, rootSchema: Schema$1, path: Path, binding?: SchemaBinding): ResolvedYjs;
+declare function resolveYjsType(rootMap: Y.Map<any>, rootSchema: Schema$1, path: Path, binding?: SchemaBinding): PathFoldResult;
 //#endregion
-export { type Changeset, type DocRef, NATIVE, type Op, type Ref, Schema, type SubstratePayload, type YjsLaws, type YjsNativeMap, 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 { type Changeset, type DocRef, NATIVE, type Op, type Ref, Schema, type SubstratePayload, type YjsLaws, type YjsNativeMap, 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.d.ts.map

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/reader.ts","../src/version.ts","../src/substrate.ts","../src/yjs-resolve.ts"],"mappings":"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"}
+{"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"}