@kyneta/yjs-schema 1.1.0 → 1.2.0

package/src/version.ts

@@ -12,6 +12,7 @@
 // decoded `Map<number, number>` (clientID → clock) maps ourselves.
 
 import type { Version } from "@kyneta/schema"
+import { versionVectorMeet } from "@kyneta/schema"
 import { decodeStateVector } from "yjs"
 
 // ---------------------------------------------------------------------------
@@ -35,6 +36,39 @@ function base64ToUint8Array(base64: string): Uint8Array {
   return bytes
 }
 
+// ---------------------------------------------------------------------------
+// State vector encoding — manual varint (unsigned LEB128)
+// ---------------------------------------------------------------------------
+
+/**
+ * Encode a state vector map to Yjs's binary state vector format.
+ *
+ * Yjs does not export `encodeStateVector(map)` — only `Y.encodeStateVector(doc)`
+ * which requires a full doc. This implements the same binary format directly:
+ * `[entryCount: varint, (clientId: varint, clock: varint)*]`
+ *
+ * Each value is encoded as an unsigned LEB128 varint.
+ */
+function encodeStateVector(map: Map<number, number>): Uint8Array {
+  const bytes: number[] = []
+
+  function writeVarUint(value: number): void {
+    while (value > 0x7f) {
+      bytes.push((value & 0x7f) | 0x80)
+      value >>>= 7
+    }
+    bytes.push(value & 0x7f)
+  }
+
+  writeVarUint(map.size)
+  for (const [clientId, clock] of map) {
+    writeVarUint(clientId)
+    writeVarUint(clock)
+  }
+
+  return new Uint8Array(bytes)
+}
+
 // ---------------------------------------------------------------------------
 // YjsVersion
 // ---------------------------------------------------------------------------
@@ -121,6 +155,27 @@ export class YjsVersion implements Version {
     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: Version): YjsVersion {
+    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.
    *

package/src/yjs-resolve.ts

@@ -15,7 +15,7 @@
 // captures all mutations with correct relative paths.
 
 import type { Path, Schema as SchemaNode, Segment } from "@kyneta/schema"
-import { advanceSchema } from "@kyneta/schema"
+import { advanceSchema, KIND } from "@kyneta/schema"
 import * as Y from "yjs"
 
 // ---------------------------------------------------------------------------
@@ -78,16 +78,6 @@ export function resolveYjsType(
   let current: unknown = rootMap
   let schema = rootSchema
 
-  // Unwrap the root annotation (e.g. annotated("doc", product))
-  // to reach the product schema whose fields are the root map's children.
-  let rootProduct = rootSchema
-  while (
-    rootProduct._kind === "annotated" &&
-    rootProduct.schema !== undefined
-  ) {
-    rootProduct = rootProduct.schema
-  }
-
   for (let i = 0; i < path.length; i++) {
     const seg = path.segments[i]!
     const nextSchema = advanceSchema(schema, seg)

package/src/yjs-escape.ts

@@ -1,84 +0,0 @@
-// yjs-escape — Yjs-specific escape hatch for accessing the Y.Doc
-// backing a ref.
-//
-// `yjs(ref)` returns the `Y.Doc` backing a root document ref.
-//
-// The substrate exposes its backing Y.Doc via the `BACKING_DOC` symbol
-// (from `@kyneta/schema`). The `yjs()` function uses `unwrap()` to get
-// the substrate, then reads `[BACKING_DOC]` to get the Y.Doc.
-//
-// This two-step approach (ref → substrate → Y.Doc) avoids duplicating
-// the ref-tracking WeakMap and composes cleanly with the general
-// `unwrap()` escape hatch.
-//
-// Context: jj:smmulzkm (BACKING_DOC replaces WeakMap + registerYjsSubstrate)
-//
-// Usage:
-//   import { yjs } from "@kyneta/yjs-schema"
-//
-//   const doc = exchange.get("my-doc", TodoDoc)
-//   const yjsDoc = yjs(doc)  // Y.Doc
-//   yjsDoc.getMap("root").toJSON()  // raw Yjs inspection
-
-import { BACKING_DOC, unwrap } from "@kyneta/schema"
-import type { Doc as YDoc } from "yjs"
-
-// ---------------------------------------------------------------------------
-// yjs — Yjs-specific escape hatch
-// ---------------------------------------------------------------------------
-
-/**
- * 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"
- *
- * 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
- * ```
- */
-export function yjs(ref: object): YDoc {
-  let substrate: any
-  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 = substrate[BACKING_DOC]
-  // Duck-type check: Y.Doc has getMap, encodeStateVector-compatible API,
-  // and a numeric clientID. A PlainState (plain object) or LoroDoc would
-  // not have getMap as a function.
-  if (
-    !doc ||
-    typeof doc !== "object" ||
-    typeof (doc as any).getMap !== "function" ||
-    typeof (doc as any).clientID !== "number"
-  ) {
-    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 as YDoc
-}