@kyneta/yjs-schema 1.0.0 → 1.2.0

package/dist/index.js

@@ -1,14 +1,27 @@
+// src/index.ts
+import {
+  applyChanges,
+  change,
+  Schema,
+  subscribe,
+  subscribeNode
+} from "@kyneta/schema";
+
 // src/create.ts
-import { interpret, registerSubstrate } from "@kyneta/schema";
-import { changefeed, readable, writable } from "@kyneta/schema";
+import {
+  interpret,
+  observation,
+  readable,
+  registerSubstrate,
+  writable
+} from "@kyneta/schema";
 
 // src/substrate.ts
-import { buildWritableContext, executeBatch } from "@kyneta/schema";
+import { BACKING_DOC, buildWritableContext, executeBatch } from "@kyneta/schema";
 import * as Y5 from "yjs";
 
 // src/change-mapping.ts
-import { advanceSchema as advanceSchema2, expandMapOpsToLeaves } from "@kyneta/schema";
-import { RawPath } from "@kyneta/schema";
+import { advanceSchema as advanceSchema2, expandMapOpsToLeaves, KIND as KIND2, RawPath } from "@kyneta/schema";
 import * as Y2 from "yjs";
 
 // src/yjs-resolve.ts
@@ -23,19 +36,13 @@ function stepIntoYjs(current, segment) {
     return current.get(resolved);
   }
   if (current instanceof Y.Text) {
-    throw new Error(
-      `yjs-resolve: cannot step into Y.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;
-  let rootProduct = rootSchema;
-  while (rootProduct._kind === "annotated" && rootProduct.schema !== void 0) {
-    rootProduct = rootProduct.schema;
-  }
   for (let i = 0; i < path.length; i++) {
     const seg = path.segments[i];
     const nextSchema = advanceSchema(schema, seg);
@@ -62,11 +69,11 @@ function applyChangeToYjs(rootMap, rootSchema, path, change2) {
       return;
     case "increment":
       throw new Error(
-        `Yjs substrate does not support counter annotations. Use Schema.number() with ReplaceChange instead. Attempted IncrementChange with amount=${change2.amount} at path [${pathToString(path)}].`
+        `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 tree annotations. Yjs has no native tree type. Attempted TreeChange at path [${pathToString(path)}].`
+        `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(
@@ -156,34 +163,25 @@ function applyReplaceChange(rootMap, rootSchema, path, change2) {
 }
 function maybeCreateSharedType(value, schema) {
   if (schema === void 0) return value;
-  const structural = unwrapAnnotations(schema);
-  const tag = schema._kind === "annotated" ? schema.tag : void 0;
-  if (tag === "text") {
-    const text2 = new Y2.Text();
-    if (typeof value === "string" && value.length > 0) {
-      text2.insert(0, value);
+  switch (schema[KIND2]) {
+    // First-class text → Y.Text
+    case "text": {
+      const text = new Y2.Text();
+      if (typeof value === "string" && value.length > 0) {
+        text.insert(0, value);
+      }
+      return text;
     }
-    return text2;
-  }
-  if (tag === "counter" || tag === "movable" || tag === "tree") {
-    throw new Error(
-      `Yjs substrate does not support "${tag}" annotations.`
-    );
-  }
-  switch (structural._kind) {
     case "product": {
       if (value === null || value === void 0 || typeof value !== "object" || Array.isArray(value)) {
         return value;
       }
-      return createStructuredMap(
-        value,
-        structural
-      );
+      return createStructuredMap(value, schema);
     }
     case "sequence": {
       if (!Array.isArray(value)) return value;
       const arr = new Y2.Array();
-      const itemSchema = structural.item;
+      const itemSchema = schema.item;
       const items = value.map(
         (item) => maybeCreateSharedType(item, itemSchema)
       );
@@ -195,22 +193,28 @@ function maybeCreateSharedType(value, schema) {
         return value;
       }
       const map = new Y2.Map();
-      const valueSchema = structural.item;
-      for (const [k, v] of Object.entries(
-        value
-      )) {
+      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;
   }
 }
 function createStructuredMap(obj, productSchema) {
   const map = new Y2.Map();
-  const structural = unwrapAnnotations(productSchema);
-  if (structural._kind !== "product") {
+  if (productSchema[KIND2] !== "product") {
     for (const [key, val] of Object.entries(obj)) {
       map.set(key, val);
     }
@@ -218,22 +222,21 @@ function createStructuredMap(obj, productSchema) {
   }
   for (const [key, val] of Object.entries(obj)) {
     if (val === void 0) continue;
-    const fieldSchema = structural.fields[key];
+    const fieldSchema = productSchema.fields[key];
     const yjsVal = fieldSchema ? maybeCreateSharedType(val, fieldSchema) : val;
     map.set(key, yjsVal);
   }
   for (const [key, fieldSchema] of Object.entries(
-    structural.fields
+    productSchema.fields
   )) {
     if (key in obj) continue;
-    const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : void 0;
-    if (tag === "text") {
+    if (fieldSchema[KIND2] === "text") {
       map.set(key, new Y2.Text());
     }
   }
   return map;
 }
-function eventsToOps(events) {
+function eventsToOps(events, schema) {
   const ops = [];
   for (const event of events) {
     const kynetaPath = yjsPathToKynetaPath(event.path);
@@ -242,7 +245,7 @@ function eventsToOps(events) {
       ops.push({ path: kynetaPath, change: change2 });
     }
   }
-  return expandMapOpsToLeaves(ops);
+  return expandMapOpsToLeaves(ops, schema);
 }
 function yjsPathToKynetaPath(yjsPath) {
   let path = RawPath.empty;
@@ -302,18 +305,16 @@ function mapEventToChange(event) {
   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;
-      }
+  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",
@@ -327,13 +328,6 @@ function extractEventValue(value) {
   if (value instanceof Y2.Text) return value.toJSON();
   return value;
 }
-function unwrapAnnotations(schema) {
-  let s = schema;
-  while (s._kind === "annotated" && s.schema !== void 0) {
-    s = s.schema;
-  }
-  return s;
-}
 function resolveSchemaAtPath(rootSchema, path) {
   let schema = rootSchema;
   for (const seg of path.segments) {
@@ -342,16 +336,19 @@ function resolveSchemaAtPath(rootSchema, path) {
   return schema;
 }
 function getItemSchema(schema) {
-  const structural = unwrapAnnotations(schema);
-  return structural._kind === "sequence" ? structural.item : void 0;
+  if (schema[KIND2] === "sequence") return schema.item;
+  if (schema[KIND2] === "movable") return schema.item;
+  return void 0;
 }
 function getFieldSchema(schema, key) {
-  const structural = unwrapAnnotations(schema);
-  if (structural._kind === "product") {
-    return structural.fields[key];
+  if (schema[KIND2] === "product") {
+    return schema.fields[key];
+  }
+  if (schema[KIND2] === "map") {
+    return schema.item;
   }
-  if (structural._kind === "map") {
-    return structural.item;
+  if (schema[KIND2] === "set") {
+    return schema.item;
   }
   return void 0;
 }
@@ -360,46 +357,35 @@ function pathToString(path) {
 }
 
 // src/populate.ts
-import { Zero } from "@kyneta/schema";
+import { KIND as KIND3, STRUCTURAL_YJS_CLIENT_ID, Zero } from "@kyneta/schema";
 import * as Y3 from "yjs";
-function ensureContainers(doc, schema) {
+function ensureContainers(doc, schema, conditional = false) {
   const rootMap = doc.getMap("root");
-  let rootProduct = schema;
-  while (rootProduct._kind === "annotated" && rootProduct.schema !== void 0) {
-    rootProduct = rootProduct.schema;
-  }
-  if (rootProduct._kind !== "product") {
+  if (schema[KIND3] !== "product") {
     return;
   }
-  doc.transact(() => {
-    for (const [key, fieldSchema] of Object.entries(rootProduct.fields)) {
-      ensureRootField(rootMap, key, fieldSchema);
-    }
-  });
+  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) {
-  const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : void 0;
-  switch (tag) {
+  switch (fieldSchema[KIND3]) {
     case "text":
       rootMap.set(key, new Y3.Text());
       return;
-    case "counter":
-      throw new Error(
-        `Yjs substrate does not support counter annotations. Use Schema.number() with ReplaceChange instead. Encountered counter annotation at root field "${key}".`
-      );
-    case "movable":
-      throw new Error(
-        `Yjs substrate does not support movable list annotations. Yjs has no native movable list type. Encountered movable annotation at root field "${key}".`
-      );
-    case "tree":
-      throw new Error(
-        `Yjs substrate does not support tree annotations. Yjs has no native tree type. Encountered tree annotation at root field "${key}".`
-      );
-  }
-  const structural = unwrapAnnotations2(fieldSchema);
-  switch (structural._kind) {
     case "product":
-      rootMap.set(key, ensureMapContainers(structural));
+      rootMap.set(key, ensureMapContainers(fieldSchema));
       return;
     case "sequence":
       rootMap.set(key, new Y3.Array());
@@ -415,22 +401,25 @@ function ensureRootField(rootMap, key, fieldSchema) {
       }
       return;
     }
+    case "counter":
+    case "set":
+    case "tree":
+    case "movable":
+      throw new Error(
+        `Yjs substrate does not support [KIND]="${fieldSchema[KIND3]}". Supported kinds: text, product, sequence, map, scalar, sum. Encountered unsupported kind at root field "${key}".`
+      );
   }
 }
 function ensureMapContainers(schema) {
   const map = new Y3.Map();
-  const structural = unwrapAnnotations2(schema);
-  if (structural._kind !== "product") return map;
+  if (schema[KIND3] !== "product") return map;
   for (const [key, fieldSchema] of Object.entries(
-    structural.fields
-  )) {
-    const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : void 0;
-    if (tag === "text") {
-      map.set(key, new Y3.Text());
-      continue;
-    }
-    const fs = unwrapAnnotations2(fieldSchema);
-    switch (fs._kind) {
+    schema.fields
+  ).sort(([a], [b]) => a.localeCompare(b))) {
+    switch (fieldSchema[KIND3]) {
+      case "text":
+        map.set(key, new Y3.Text());
+        break;
       case "product":
         map.set(key, ensureMapContainers(fieldSchema));
         break;
@@ -448,19 +437,19 @@ function ensureMapContainers(schema) {
         }
         break;
       }
+      case "counter":
+      case "set":
+      case "tree":
+      case "movable":
+        throw new Error(
+          `Yjs substrate does not support [KIND]="${fieldSchema[KIND3]}". Supported kinds: text, product, sequence, map, scalar, sum. Encountered unsupported kind at nested field "${key}".`
+        );
     }
   }
   return map;
 }
-function unwrapAnnotations2(schema) {
-  let s = schema;
-  while (s._kind === "annotated" && s.schema !== void 0) {
-    s = s.schema;
-  }
-  return s;
-}
 
-// src/store-reader.ts
+// src/reader.ts
 import * as Y4 from "yjs";
 function extractValue(resolved) {
   if (resolved instanceof Y4.Text) {
@@ -474,7 +463,7 @@ function extractValue(resolved) {
   }
   return resolved;
 }
-function yjsStoreReader(doc, schema) {
+function yjsReader(doc, schema) {
   const rootMap = doc.getMap("root");
   return {
     read(path) {
@@ -518,6 +507,7 @@ function yjsStoreReader(doc, schema) {
 }
 
 // src/version.ts
+import { versionVectorMeet } from "@kyneta/schema";
 import { decodeStateVector } from "yjs";
 function uint8ArrayToBase64(bytes) {
   let binary = "";
@@ -534,6 +524,22 @@ function base64ToUint8Array(base64) {
   }
   return bytes;
 }
+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) {
@@ -565,9 +571,7 @@ var YjsVersion = class _YjsVersion {
    */
   compare(other) {
     if (!(other instanceof _YjsVersion)) {
-      throw new Error(
-        "YjsVersion can only be compared with another YjsVersion"
-      );
+      throw new Error("YjsVersion can only be compared with another YjsVersion");
     }
     const thisMap = decodeStateVector(this.sv);
     const otherMap = decodeStateVector(other.sv);
@@ -593,6 +597,26 @@ var YjsVersion = class _YjsVersion {
     if (hasGreater && !hasLess) return "ahead";
     return "equal";
   }
+  /**
+   * 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.
    *
@@ -607,47 +631,24 @@ var YjsVersion = class _YjsVersion {
   }
 };
 
-// src/yjs-escape.ts
-import { unwrap } from "@kyneta/schema";
-var substrateToYjsDoc = /* @__PURE__ */ new WeakMap();
-function registerYjsSubstrate(substrate, doc) {
-  substrateToYjsDoc.set(substrate, doc);
-}
-function yjs(ref) {
-  let substrate;
-  try {
-    substrate = unwrap(ref);
-  } catch {
-    throw new Error(
-      "yjs() requires a ref backed by a Yjs substrate. Use a doc created by exchange.get() with a bindYjs() schema, or by createYjsDoc()."
-    );
-  }
-  const doc = substrateToYjsDoc.get(substrate);
-  if (!doc) {
-    throw new Error(
-      "yjs() requires a ref backed by a Yjs substrate. The ref has a substrate but it is not a Yjs substrate. Use a doc created with a bindYjs() schema or createYjsDoc()."
-    );
-  }
-  return doc;
-}
-
 // src/substrate.ts
 var KYNETA_ORIGIN = "kyneta-prepare";
 function createYjsSubstrate(doc, schema) {
   const pendingChanges = [];
   let inOurTransaction = false;
-  let pendingImportOrigin;
+  let pendingMergeOrigin;
   let cachedCtx;
   const rootMap = doc.getMap("root");
-  const reader = yjsStoreReader(doc, schema);
+  const reader = yjsReader(doc, schema);
   const substrate = {
-    store: reader,
+    [BACKING_DOC]: doc,
+    reader,
     prepare(path, change2) {
       if (!inOurTransaction) {
         pendingChanges.push({ path, change: change2 });
       }
     },
-    onFlush(origin) {
+    onFlush(_origin) {
       if (!inOurTransaction && pendingChanges.length > 0) {
         inOurTransaction = true;
         try {
@@ -671,8 +672,17 @@ function createYjsSubstrate(doc, schema) {
     version() {
       return new YjsVersion(Y5.encodeStateVector(doc));
     },
-    exportSnapshot() {
+    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)
       };
@@ -680,22 +690,22 @@ function createYjsSubstrate(doc, schema) {
     exportSince(since) {
       try {
         const bytes = Y5.encodeStateAsUpdate(doc, since.sv);
-        return { encoding: "binary", data: bytes };
+        return { kind: "since", encoding: "binary", data: bytes };
       } catch {
         return null;
       }
     },
-    importDelta(payload, origin) {
+    merge(payload, origin) {
       if (payload.encoding !== "binary" || !(payload.data instanceof Uint8Array)) {
         throw new Error(
-          "YjsSubstrate.importDelta only supports binary-encoded payloads"
+          "YjsSubstrate.merge expects binary-encoded payloads. If you recently switched CRDT backends, stale clients may be sending incompatible data."
         );
       }
-      pendingImportOrigin = origin;
+      pendingMergeOrigin = origin;
       try {
         Y5.applyUpdate(doc, payload.data, origin ?? "remote");
       } finally {
-        pendingImportOrigin = void 0;
+        pendingMergeOrigin = void 0;
       }
     }
   };
@@ -703,11 +713,11 @@ function createYjsSubstrate(doc, schema) {
     if (transaction.origin === KYNETA_ORIGIN) {
       return;
     }
-    const ops = eventsToOps(events);
+    const ops = eventsToOps(events, schema);
     if (ops.length === 0) {
       return;
     }
-    const origin = pendingImportOrigin ?? (typeof transaction.origin === "string" ? transaction.origin : void 0);
+    const origin = pendingMergeOrigin ?? (typeof transaction.origin === "string" ? transaction.origin : void 0);
     const ctx = substrate.context();
     inOurTransaction = true;
     try {
@@ -716,25 +726,103 @@ function createYjsSubstrate(doc, schema) {
       inOurTransaction = false;
     }
   });
-  registerYjsSubstrate(substrate, doc);
   return substrate;
 }
-var yjsSubstrateFactory = {
-  create(schema) {
-    const doc = new Y5.Doc();
-    ensureContainers(doc, schema);
-    return createYjsSubstrate(doc, schema);
+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());
   },
-  fromSnapshot(payload, schema) {
+  fromEntirety(payload) {
     if (payload.encoding !== "binary" || !(payload.data instanceof Uint8Array)) {
       throw new Error(
-        "YjsSubstrateFactory.fromSnapshot only supports binary-encoded payloads"
+        "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);
+  }
+};
+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);
   }
@@ -746,13 +834,13 @@ function getSubstrate(doc) {
   const s = substrates.get(doc);
   if (!s) {
     throw new Error(
-      "version/exportSnapshot/importDelta called on an object without a YjsSubstrate. Use a doc created by createYjsDoc() or createYjsDocFromSnapshot()."
+      "version/exportEntirety/merge called on an object without a YjsSubstrate. Use a doc created by createYjsDoc() or createYjsDocFromEntirety()."
     );
   }
   return s;
 }
 function registerDoc(schema, substrate) {
-  const doc = interpret(schema, substrate.context()).with(readable).with(writable).with(changefeed).done();
+  const doc = interpret(schema, substrate.context()).with(readable).with(writable).with(observation).done();
   substrates.set(doc, substrate);
   registerSubstrate(doc, substrate);
   return doc;
@@ -767,30 +855,29 @@ var createYjsDoc = (schema, doc) => {
   }
   return registerDoc(schema, yjsSubstrateFactory.create(schema));
 };
-var createYjsDocFromSnapshot = (schema, payload) => registerDoc(schema, yjsSubstrateFactory.fromSnapshot(payload, schema));
+var createYjsDocFromEntirety = (schema, payload) => registerDoc(schema, yjsSubstrateFactory.fromEntirety(payload, schema));
 
 // src/sync.ts
 function version(doc) {
   return getSubstrate(doc).version();
 }
-function exportSnapshot(doc) {
-  return getSubstrate(doc).exportSnapshot();
+function exportEntirety(doc) {
+  return getSubstrate(doc).exportEntirety();
 }
 function exportSince(doc, since) {
   return getSubstrate(doc).exportSince(since);
 }
-function importDelta(doc, payload, origin) {
-  getSubstrate(doc).importDelta(payload, origin);
+function merge(doc, payload, origin) {
+  getSubstrate(doc).merge(payload, origin);
 }
 
-// src/index.ts
-import { applyChanges, change } from "@kyneta/schema";
-import { subscribe, subscribeNode } from "@kyneta/schema";
-import { Schema } from "@kyneta/schema";
-import { Schema as Schema2 } from "@kyneta/schema";
-
 // src/bind-yjs.ts
-import { bind } from "@kyneta/schema";
+import {
+  BACKING_DOC as BACKING_DOC2,
+  createSubstrateNamespace,
+  STRUCTURAL_YJS_CLIENT_ID as STRUCTURAL_YJS_CLIENT_ID2,
+  unwrap
+} from "@kyneta/schema";
 import * as Y6 from "yjs";
 function hashPeerId(peerId) {
   let hash = 2166136261;
@@ -798,68 +885,92 @@ function hashPeerId(peerId) {
     hash ^= peerId.charCodeAt(i);
     hash = Math.imul(hash, 16777619);
   }
-  return hash >>> 0;
+  const result = hash >>> 0;
+  return result === STRUCTURAL_YJS_CLIENT_ID2 ? 1 : result;
 }
 function createYjsFactory(peerId) {
   const numericClientId = hashPeerId(peerId);
   return {
-    create(schema) {
-      const doc = new Y6.Doc();
+    replica: yjsReplicaFactory,
+    createReplica() {
+      return createYjsReplica(new Y6.Doc());
+    },
+    upgrade(replica, schema) {
+      const doc = replica[BACKING_DOC2];
       doc.clientID = numericClientId;
-      ensureContainers(doc, schema);
+      ensureContainers(doc, schema, true);
       return createYjsSubstrate(doc, schema);
     },
-    fromSnapshot(payload, schema) {
-      if (payload.encoding !== "binary" || !(payload.data instanceof Uint8Array)) {
-        throw new Error(
-          "YjsSubstrateFactory.fromSnapshot only supports binary-encoded payloads"
-        );
-      }
+    create(schema) {
       const doc = new Y6.Doc();
       doc.clientID = numericClientId;
-      Y6.applyUpdate(doc, payload.data);
+      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);
     }
   };
 }
-function bindYjs(schema) {
-  return bind({
-    schema,
-    factory: (ctx) => createYjsFactory(ctx.peerId),
-    strategy: "causal"
-  });
-}
-
-// src/index.ts
-function text() {
-  return Schema2.annotated("text");
-}
+var yjs = {
+  ...createSubstrateNamespace({
+    strategies: {
+      collaborative: {
+        factory: (ctx) => createYjsFactory(ctx.peerId),
+        replicaFactory: yjsReplicaFactory
+      },
+      ephemeral: {
+        factory: (ctx) => createYjsFactory(ctx.peerId),
+        replicaFactory: yjsReplicaFactory
+      }
+    },
+    defaultStrategy: "collaborative"
+  }),
+  unwrap(ref) {
+    let substrate;
+    try {
+      substrate = unwrap(ref);
+    } catch {
+      throw new Error(
+        "yjs.unwrap() requires a ref backed by a Yjs substrate. Use a doc created by exchange.get() with a yjs.bind() schema, or by createYjsDoc()."
+      );
+    }
+    const doc = substrate[BACKING_DOC2];
+    if (!doc || typeof doc !== "object" || typeof doc.getMap !== "function" || typeof doc.clientID !== "number") {
+      throw new Error(
+        "yjs.unwrap() requires a ref backed by a Yjs substrate. The ref has a substrate but it is not a Yjs substrate. Use a doc created with a yjs.bind() schema or createYjsDoc()."
+      );
+    }
+    return doc;
+  }
+};
 export {
   Schema,
   YjsVersion,
   applyChangeToYjs,
   applyChanges,
-  bindYjs,
   change,
   createYjsDoc,
-  createYjsDocFromSnapshot,
+  createYjsDocFromEntirety,
   createYjsSubstrate,
   ensureContainers,
   eventsToOps,
+  exportEntirety,
   exportSince,
-  exportSnapshot,
-  importDelta,
+  merge,
   resolveYjsType,
   stepIntoYjs,
   subscribe,
   subscribeNode,
-  text,
   version,
   yjs,
-  yjsStoreReader,
+  yjsReader,
+  yjsReplicaFactory,
   yjsSubstrateFactory
 };
 //# sourceMappingURL=index.js.map