@kyneta/yjs-schema 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { Version, Schema, Ref, SubstratePayload, StoreReader, Path, Segment, ChangeBase, Op, Substrate, SubstrateFactory, BoundSchema, AnnotatedSchema } from '@kyneta/schema';
-export { Changeset, Op, Ref, Schema, SubstratePayload, applyChanges, change, subscribe, subscribeNode } from '@kyneta/schema';
+import { Version, Schema, Ref, SubstratePayload, SubstrateNamespace, CrdtStrategy, Path, ChangeBase, Op, Reader, Substrate, ReplicaFactory, SubstrateFactory, Segment } from '@kyneta/schema';
+export { Op, Ref, Schema, SubstratePayload, applyChanges, change, subscribe, subscribeNode } from '@kyneta/schema';
 import * as Y from 'yjs';
-import { Doc } from 'yjs';
+export { Changeset } from '@kyneta/changefeed';
 
 /**
  * A Version wrapping a Yjs state vector.
@@ -41,6 +41,16 @@ declare class YjsVersion implements Version {
      * Throws if `other` is not a `YjsVersion`.
      */
     compare(other: Version): "behind" | "equal" | "ahead" | "concurrent";
+    /**
+     * 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: Version): YjsVersion;
     /**
      * Parse a serialized YjsVersion string back into a YjsVersion.
      *
@@ -74,7 +84,7 @@ declare class YjsVersion implements Version {
  * CRDT collaboration support.
  *
  * The returned ref observes **all** mutations to the underlying Y.Doc,
- * regardless of source (local kyneta writes, importDelta, external
+ * regardless of source (local kyneta writes, merge, external
  * `Y.applyUpdate()`, external raw Yjs API mutations).
  *
  * @param schema - The schema describing the document structure.
@@ -83,21 +93,21 @@ declare class YjsVersion implements Version {
  */
 type CreateYjsDoc = <S extends Schema>(schema: S, doc?: Y.Doc) => Ref<S>;
 declare const createYjsDoc: CreateYjsDoc;
-type CreateYjsDocFromSnapshot = <S extends Schema>(schema: S, payload: SubstratePayload) => Ref<S>;
+type CreateYjsDocFromEntirety = <S extends Schema>(schema: S, payload: SubstratePayload) => Ref<S>;
 /**
- * Reconstruct a live Yjs-backed document from a substrate snapshot payload.
+ * Reconstruct a live Yjs-backed document from a substrate entirety payload.
  *
- * The payload must have been produced by `exportSnapshot()` on a
+ * The payload must have been produced by `exportEntirety()` on a
  * compatible document. This is the entry point for SSR hydration
  * and reconnection past log compaction.
  *
  * ```ts
- * const payload = exportSnapshot(docA)
- * const docB = createYjsDocFromSnapshot(MySchema, payload)
+ * const payload = exportEntirety(docA)
+ * const docB = createYjsDocFromEntirety(MySchema, payload)
  * // docB has the same state as docA at the time of export
  * ```
  */
-declare const createYjsDocFromSnapshot: CreateYjsDocFromSnapshot;
+declare const createYjsDocFromEntirety: CreateYjsDocFromEntirety;
 
 /**
  * Current version as a `YjsVersion` (wrapping a Yjs state vector).
@@ -105,20 +115,20 @@ declare const createYjsDocFromSnapshot: CreateYjsDocFromSnapshot;
  * Use `.serialize()` to get a text-safe string for embedding in HTML
  * meta tags, URL parameters, etc.
  *
- * @param doc - A document created by `createYjsDoc` or `createYjsDocFromSnapshot`.
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ * @param doc - A document created by `createYjsDoc` or `createYjsDocFromEntirety`.
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
  */
 declare function version(doc: object): YjsVersion;
 /**
- * Export the full substrate snapshot — sufficient for a new peer to
- * reconstruct an equivalent document via `createYjsDocFromSnapshot()`.
+ * Export the full substrate entirety — sufficient for a new peer to
+ * reconstruct an equivalent document via `createYjsDocFromEntirety()`.
  *
  * Returns a binary `SubstratePayload` (Yjs state-as-update bytes).
  *
- * @param doc - A document created by `createYjsDoc` or `createYjsDocFromSnapshot`.
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ * @param doc - A document created by `createYjsDoc` or `createYjsDocFromEntirety`.
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
  */
-declare function exportSnapshot(doc: object): SubstratePayload;
+declare function exportEntirety(doc: object): SubstratePayload;
 /**
  * Export a delta payload containing all changes since the given version.
  *
@@ -129,78 +139,53 @@ declare function exportSnapshot(doc: object): SubstratePayload;
  * const v0 = version(docA)
  * change(docA, d => d.title.insert(0, "Hi"))
  * const delta = exportSince(docA, v0)
- * importDelta(docB, delta!)
+ * merge(docB, delta!)
  * ```
  *
- * @param doc - A document created by `createYjsDoc` or `createYjsDocFromSnapshot`.
+ * @param doc - A document created by `createYjsDoc` or `createYjsDocFromEntirety`.
  * @param since - The version to diff from.
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
  */
 declare function exportSince(doc: object, since: YjsVersion): SubstratePayload | null;
 /**
  * Import a delta payload into a live document.
  *
  * The payload must have been produced by `exportSince()` or
- * `exportSnapshot()` on a compatible document.
+ * `exportEntirety()` on a compatible document.
  *
  * After import, the changefeed fires for all subscribers — the event
  * bridge handles this automatically.
  *
  * ```ts
  * const delta = exportSince(docA, sinceVersion)
- * importDelta(docB, delta!, "sync")
+ * merge(docB, delta!, "sync")
  * ```
  *
- * @param doc - A document created by `createYjsDoc` or `createYjsDocFromSnapshot`.
- * @param payload - The delta or snapshot payload to import.
+ * @param doc - A document created by `createYjsDoc` or `createYjsDocFromEntirety`.
+ * @param payload - The delta or entirety payload to merge.
  * @param origin - Optional provenance tag for the changeset.
- * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromSnapshot`.
+ * @throws If `doc` was not created by `createYjsDoc` / `createYjsDocFromEntirety`.
  */
-declare function importDelta(doc: object, payload: SubstratePayload, origin?: string): void;
+declare function merge(doc: object, payload: SubstratePayload, origin?: string): void;
 
 /**
- * Creates a StoreReader that navigates the Yjs shared type tree live,
- * using the schema as a type witness to determine navigation at each
- * path segment.
+ * The Yjs CRDT substrate namespace.
  *
- * The reader is a live view — mutations to the underlying Y.Doc
- * (via `doc.transact()`, or `Y.applyUpdate()`) are immediately
- * visible through the reader.
+ * - `yjs.bind(schema)` — collaborative sync (default)
+ * - `yjs.bind(schema, "ephemeral")` — ephemeral/presence broadcast
+ * - `yjs.replica()` — collaborative replication (default)
+ * - `yjs.replica("ephemeral")` — ephemeral replication
+ * - `yjs.unwrap(ref)` — access the underlying Y.Doc
  *
- * 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.
+ * Strategy is constrained to `CrdtStrategy` (`"collaborative" | "ephemeral"`).
+ * Passing `"authoritative"` is a compile error.
  */
-declare function yjsStoreReader(doc: Y.Doc, schema: Schema): StoreReader;
-
-/**
- * Navigate one step deeper into the Yjs shared type tree.
- *
- * Uses `instanceof` for runtime type discrimination:
- * - `Y.Map` → `.get(key)`
- * - `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
- */
-declare function stepIntoYjs(current: unknown, segment: Segment): unknown;
-/**
- * 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.
- *
- * Returns the Yjs shared type or plain value at the terminal position.
- * For an empty path, returns the root map itself.
- *
- * @param rootMap - The root `Y.Map` obtained via `doc.getMap("root")`
- * @param rootSchema - The root document schema
- * @param path - The path to resolve
- */
-declare function resolveYjsType(rootMap: Y.Map<any>, rootSchema: Schema, path: Path): unknown;
+/** The closed set of capability tags that the Yjs substrate supports. */
+type YjsCaps = "text" | "json";
+declare const yjs: SubstrateNamespace<CrdtStrategy, YjsCaps> & {
+    /** Access the underlying `Y.Doc` backing a ref. */
+    unwrap(ref: object): Y.Doc;
+};
 
 /**
  * Apply a kyneta Change to the Yjs shared type tree imperatively.
@@ -228,24 +213,52 @@ declare function applyChangeToYjs(rootMap: Y.Map<any>, rootSchema: Schema, path:
  *
  * @param events - The events from the `observeDeep` callback
  */
-declare function eventsToOps(events: Y.YEvent<any>[]): Op[];
+declare function eventsToOps(events: Y.YEvent<any>[], schema: Schema): Op[];
 
 /**
  * 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")`, unwraps the root product
- * schema, and creates empty containers for each field within a single
- * `doc.transact()` call for atomicity.
+ * 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.
  *
- * No values are written — the containers are empty after this call.
- * Initial content should be applied via `change()` after substrate
- * construction.
+ * **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.
  *
  * @param doc - The Y.Doc to prepare
- * @param schema - The root document schema (typically annotated("doc", product))
+ * @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)
+ */
+declare function ensureContainers(doc: Y.Doc, schema: Schema, conditional?: boolean): void;
+
+/**
+ * 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.
  */
-declare function ensureContainers(doc: Y.Doc, schema: Schema): void;
+declare function yjsReader(doc: Y.Doc, schema: Schema): Reader;
 
 /**
  * Creates a `Substrate<YjsVersion>` wrapping a user-provided Y.Doc.
@@ -253,11 +266,11 @@ declare function ensureContainers(doc: Y.Doc, schema: Schema): void;
  * 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/import through the standard Substrate interface.
+ * 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 (imports, external local writes) are bridged
+ * 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.
  *
@@ -266,86 +279,35 @@ declare function ensureContainers(doc: Y.Doc, schema: Schema): void;
  * @param schema - The root schema for the document.
  */
 declare function createYjsSubstrate(doc: Y.Doc, schema: Schema): Substrate<YjsVersion>;
-/**
- * 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.
- * - `fromSnapshot(payload, schema)` — creates a Y.Doc from a snapshot
- *   payload, returns a substrate.
- * - `parseVersion(serialized)` — deserializes a YjsVersion.
- */
+declare const yjsReplicaFactory: ReplicaFactory<YjsVersion>;
 declare const yjsSubstrateFactory: SubstrateFactory<YjsVersion>;
 
 /**
- * Bind a schema to the Yjs CRDT substrate with causal merge strategy.
- *
- * This is the recommended way to declare a Yjs-backed document type.
- * The factory builder injects a deterministic numeric Yjs clientID derived
- * from the exchange's string peerId, ensuring consistent change attribution
- * across all documents and sessions.
+ * Navigate one step deeper into the Yjs shared type tree.
  *
- * **Unsupported annotations:** Yjs has no native counter, movable list,
- * or tree types. Schemas passed to `bindYjs` must not contain
- * `Schema.annotated("counter")`, `Schema.annotated("movable")`, or
- * `Schema.annotated("tree")`. These will throw at construction time.
+ * Uses `instanceof` for runtime type discrimination:
+ * - `Y.Map` → `.get(key)`
+ * - `Y.Array` → `.get(index)`
+ * - `Y.Text` → terminal (cannot step further)
+ * - Plain value → terminal (return `undefined`)
  *
- * @example
- * ```ts
- * import { bindYjs } from "@kyneta/yjs-schema"
- * import { Schema } from "@kyneta/schema"
- *
- * const TodoDoc = bindYjs(Schema.doc({
- *   title: Schema.annotated("text"),
- *   items: Schema.list(Schema.struct({
- *     name: Schema.string(),
- *     done: Schema.boolean(),
- *   })),
- * }))
- *
- * const doc = exchange.get("my-todos", TodoDoc)
- * ```
+ * @param current - The current position (a Yjs shared type or plain value)
+ * @param segment - The path segment to follow
  */
-declare function bindYjs<S extends Schema>(schema: S): BoundSchema<S>;
-
+declare function stepIntoYjs(current: unknown, segment: Segment): unknown;
 /**
- * Returns the `Y.Doc` backing the given ref.
- *
- * This is the Yjs-specific escape hatch for accessing substrate-level
- * capabilities: raw Yjs API, y-prosemirror/y-codemirror bindings,
- * undo manager, awareness protocol, Yjs providers (y-websocket,
- * y-indexeddb, y-webrtc, Hocuspocus, Liveblocks), etc.
- *
- * Currently supports root document refs only. Child-level resolution
- * (e.g. `yjs(doc.title)` → `Y.Text`) is future work.
- *
- * @param ref - A root document ref backed by a Yjs substrate
- * @returns The `Y.Doc` backing the ref
- * @throws If the ref is not backed by a Yjs substrate
- *
- * @example
- * ```ts
- * import { yjs } from "@kyneta/yjs-schema"
+ * Resolve a Yjs shared type (or plain value) at the given path.
  *
- * const doc = exchange.get("my-doc", TodoDoc)
- * const yjsDoc = yjs(doc)
- * console.log(yjsDoc.getMap("root").toJSON())  // raw state
- * console.log(yjsDoc.clientID)                  // client ID
- * ```
- */
-declare function yjs(ref: object): Doc;
-
-/**
- * Collaborative text (CRDT). Produces `annotated("text")`.
+ * Left-folds over path segments using `advanceSchema` for pure schema
+ * descent and `stepIntoYjs` for Yjs-specific navigation.
  *
- * The annotation implies scalar string semantics for reads,
- * but the Yjs substrate provides collaborative editing (insert, delete)
- * via Y.Text.
+ * Returns the Yjs shared type or plain value at the terminal position.
+ * For an empty path, returns the root map itself.
  *
- * This is a convenience re-export so that `@kyneta/yjs-schema` users
- * don't need to import `LoroSchema` just for `text()`.
+ * @param rootMap - The root `Y.Map` obtained via `doc.getMap("root")`
+ * @param rootSchema - The root document schema
+ * @param path - The path to resolve
  */
-declare function text(): AnnotatedSchema<"text", undefined>;
+declare function resolveYjsType(rootMap: Y.Map<any>, rootSchema: Schema, path: Path): unknown;
 
-export { YjsVersion, applyChangeToYjs, bindYjs, createYjsDoc, createYjsDocFromSnapshot, createYjsSubstrate, ensureContainers, eventsToOps, exportSince, exportSnapshot, importDelta, resolveYjsType, stepIntoYjs, text, version, yjs, yjsStoreReader, yjsSubstrateFactory };
+export { type YjsCaps, YjsVersion, applyChangeToYjs, createYjsDoc, createYjsDocFromEntirety, createYjsSubstrate, ensureContainers, eventsToOps, exportEntirety, exportSince, merge, resolveYjsType, stepIntoYjs, version, yjs, yjsReader, yjsReplicaFactory, yjsSubstrateFactory };