@kyneta/yjs-schema 1.1.0 → 1.2.0

package/src/change-mapping.ts

@@ -29,7 +29,7 @@ import type {
   TextChange,
   TextInstruction,
 } from "@kyneta/schema"
-import { advanceSchema, expandMapOpsToLeaves, RawPath } from "@kyneta/schema"
+import { advanceSchema, expandMapOpsToLeaves, KIND, RawPath } from "@kyneta/schema"
 import * as Y from "yjs"
 import { resolveYjsType } from "./yjs-resolve.js"
 
@@ -74,15 +74,15 @@ export function applyChangeToYjs(
 
     case "increment":
       throw new Error(
-        "Yjs substrate does not support counter annotations. " +
-          "Use Schema.number() with ReplaceChange instead. " +
+        `Yjs substrate does not support "${change.type}" changes. ` +
+          `Counter requires a CRDT backend that supports counters (e.g. Loro). ` +
           `Attempted IncrementChange with amount=${(change as IncrementChange).amount} at path [${pathToString(path)}].`,
       )
 
     case "tree":
       throw new Error(
-        "Yjs substrate does not support tree annotations. " +
-          "Yjs has no native tree type. " +
+        `Yjs substrate does not support "${change.type}" changes. ` +
+          `Tree requires a CRDT backend that supports trees (e.g. Loro). ` +
           `Attempted TreeChange at path [${pathToString(path)}].`,
       )
 
@@ -250,24 +250,16 @@ function maybeCreateSharedType(
 ): unknown {
   if (schema === undefined) return value
 
-  const structural = unwrapAnnotations(schema)
-  const tag = schema._kind === "annotated" ? schema.tag : undefined
-
-  // Annotated text → Y.Text
-  if (tag === "text") {
-    const text = new Y.Text()
-    if (typeof value === "string" && value.length > 0) {
-      text.insert(0, value)
+  switch (schema[KIND]) {
+    // First-class text → Y.Text
+    case "text": {
+      const text = new Y.Text()
+      if (typeof value === "string" && value.length > 0) {
+        text.insert(0, value)
+      }
+      return text
     }
-    return text
-  }
-
-  // Annotated counter/movable/tree → should not reach here (thrown earlier)
-  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 ||
@@ -277,13 +269,13 @@ function maybeCreateSharedType(
       ) {
         return value
       }
-      return createStructuredMap(value as Record<string, unknown>, structural)
+      return createStructuredMap(value as Record<string, unknown>, schema)
     }
 
     case "sequence": {
       if (!Array.isArray(value)) return value
       const arr = new Y.Array()
-      const itemSchema = structural.item
+      const itemSchema = schema.item
       const items = (value as unknown[]).map(item =>
         maybeCreateSharedType(item, itemSchema),
       )
@@ -301,15 +293,26 @@ function maybeCreateSharedType(
         return value
       }
       const map = new Y.Map()
-      const valueSchema = structural.item
+      const valueSchema = schema.item
       for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
         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[KIND]}". ` +
+          `This should have been caught at bind() time.`,
+      )
+
     default:
-      // Scalar, sum, or other — return as plain value
+      // Scalar, sum — return as plain value
       return value
   }
 }
@@ -326,9 +329,8 @@ function createStructuredMap(
   productSchema: SchemaNode,
 ): Y.Map<any> {
   const map = new Y.Map()
-  const structural = unwrapAnnotations(productSchema)
 
-  if (structural._kind !== "product") {
+  if (productSchema[KIND] !== "product") {
     // Fallback: set all values as plain
     for (const [key, val] of Object.entries(obj)) {
       map.set(key, val)
@@ -339,25 +341,22 @@ function createStructuredMap(
   // Process fields present in the value object
   for (const [key, val] of Object.entries(obj)) {
     if (val === undefined) continue
-    const fieldSchema = structural.fields[key]
+    const fieldSchema = productSchema.fields[key]
     const yjsVal = fieldSchema ? maybeCreateSharedType(val, fieldSchema) : val
     map.set(key, yjsVal)
   }
 
-  // Create shared types for annotated fields declared in the schema
+  // Create shared types for first-class CRDT fields declared in the schema
   // but missing from the value object. This ensures Yjs containers
   // exist for later mutation (e.g. .insert() on a text field inside
   // a struct inside a record/list).
   for (const [key, fieldSchema] of Object.entries(
-    structural.fields as Record<string, SchemaNode>,
+    productSchema.fields as Record<string, SchemaNode>,
   )) {
     if (key in obj) continue // already processed above
-    const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : undefined
-    if (tag === "text") {
+    if (fieldSchema[KIND] === "text") {
       map.set(key, new Y.Text())
     }
-    // Other annotated container types (counter, movable, tree) are
-    // unsupported in Yjs and will throw if used elsewhere.
   }
 
   return map
@@ -380,7 +379,7 @@ function createStructuredMap(
  *
  * @param events - The events from the `observeDeep` callback
  */
-export function eventsToOps(events: Y.YEvent<any>[]): Op[] {
+export function eventsToOps(events: Y.YEvent<any>[], schema: SchemaNode): Op[] {
   const ops: Op[] = []
 
   for (const event of events) {
@@ -391,7 +390,7 @@ export function eventsToOps(events: Y.YEvent<any>[]): Op[] {
     }
   }
 
-  return expandMapOpsToLeaves(ops)
+  return expandMapOpsToLeaves(ops, schema)
 }
 
 // ---------------------------------------------------------------------------
@@ -541,17 +540,6 @@ function extractEventValue(value: unknown): unknown {
 // Schema helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Unwrap annotation wrappers to reach the structural schema node.
- */
-function unwrapAnnotations(schema: SchemaNode): SchemaNode {
-  let s = schema
-  while (s._kind === "annotated" && s.schema !== undefined) {
-    s = s.schema
-  }
-  return s
-}
-
 /**
  * Resolve the schema at a given path by walking through advanceSchema.
  */
@@ -567,8 +555,9 @@ function resolveSchemaAtPath(rootSchema: SchemaNode, path: Path): SchemaNode {
  * Get the item schema from a sequence schema, if available.
  */
 function getItemSchema(schema: SchemaNode): SchemaNode | undefined {
-  const structural = unwrapAnnotations(schema)
-  return structural._kind === "sequence" ? structural.item : undefined
+  if (schema[KIND] === "sequence") return schema.item
+  if (schema[KIND] === "movable") return schema.item
+  return undefined
 }
 
 /**
@@ -578,12 +567,14 @@ function getFieldSchema(
   schema: SchemaNode,
   key: string,
 ): SchemaNode | undefined {
-  const structural = unwrapAnnotations(schema)
-  if (structural._kind === "product") {
-    return structural.fields[key]
+  if (schema[KIND] === "product") {
+    return schema.fields[key]
   }
-  if (structural._kind === "map") {
-    return structural.item
+  if (schema[KIND] === "map") {
+    return schema.item
+  }
+  if (schema[KIND] === "set") {
+    return schema.item
   }
   return undefined
 }
@@ -594,4 +585,4 @@ function getFieldSchema(
 
 function pathToString(path: Path): string {
   return path.segments.map(seg => String(seg.resolve())).join(".")
-}
+}

package/src/create.ts

@@ -21,8 +21,8 @@ import type {
   SubstratePayload,
 } from "@kyneta/schema"
 import {
-  changefeed,
   interpret,
+  observation,
   readable,
   registerSubstrate,
   writable,
@@ -71,7 +71,7 @@ function registerDoc(
   const doc: any = (interpret as any)(schema, substrate.context())
     .with(readable)
     .with(writable)
-    .with(changefeed)
+    .with(observation)
     .done()
   substrates.set(doc, substrate)
   // Also register in the general unwrap() registry so that the

package/src/index.ts

@@ -34,33 +34,18 @@ export {
   version,
 } from "./sync.js"
 
-// Text annotation convenience — so users don't need LoroSchema just for text()
-import type { AnnotatedSchema } from "@kyneta/schema"
-import { Schema } from "@kyneta/schema"
-
-/**
- * Collaborative text (CRDT). Produces `annotated("text")`.
- *
- * The annotation implies scalar string semantics for reads,
- * but the Yjs substrate provides collaborative editing (insert, delete)
- * via Y.Text.
- *
- * This is a convenience re-export so that `@kyneta/yjs-schema` users
- * don't need to import `LoroSchema` just for `text()`.
- */
-export function text(): AnnotatedSchema<"text", undefined> {
-  return Schema.annotated("text")
-}
-
 // Types (re-exported for convenience)
-export type { Changeset, Op, Ref, SubstratePayload } from "@kyneta/schema"
+export type { Changeset } from "@kyneta/changefeed"
+export type { Op, Ref, SubstratePayload } from "@kyneta/schema"
 
 // ---------------------------------------------------------------------------
 // Low-level primitives — for power users and custom substrate compositions
 // ---------------------------------------------------------------------------
 
-// Bind — convenience wrapper for Yjs CRDT substrate
-export { bindYjs } from "./bind-yjs.js"
+// Namespace — the yjs substrate namespace (replaces standalone escape hatch;
+// the old `yjs(ref)` call is now `yjs.unwrap(ref)`)
+export { yjs } from "./bind-yjs.js"
+export type { YjsCaps } from "./bind-yjs.js"
 // Change mapping
 export { applyChangeToYjs, eventsToOps } from "./change-mapping.js"
 // Container creation
@@ -68,10 +53,12 @@ export { ensureContainers } from "./populate.js"
 // Reader
 export { yjsReader } from "./reader.js"
 // Substrate
-export { createYjsSubstrate, yjsSubstrateFactory } from "./substrate.js"
+export {
+  createYjsSubstrate,
+  yjsReplicaFactory,
+  yjsSubstrateFactory,
+} from "./substrate.js"
 // Version
 export { YjsVersion } from "./version.js"
-// Escape hatch — access the underlying Y.Doc from a ref
-export { yjs } from "./yjs-escape.js"
 // Container resolution
-export { resolveYjsType, stepIntoYjs } from "./yjs-resolve.js"
+export { resolveYjsType, stepIntoYjs } from "./yjs-resolve.js"

package/src/populate.ts

@@ -15,7 +15,7 @@
 // shared types (Y.Text, Y.Array, Y.Map) and plain value slots uniformly.
 
 import type { Schema as SchemaNode } from "@kyneta/schema"
-import { STRUCTURAL_YJS_CLIENT_ID, Zero } from "@kyneta/schema"
+import { KIND, STRUCTURAL_YJS_CLIENT_ID, Zero } from "@kyneta/schema"
 import * as Y from "yjs"
 
 // ---------------------------------------------------------------------------
@@ -26,9 +26,9 @@ import * as Y from "yjs"
  * 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
@@ -45,7 +45,7 @@ import * as Y from "yjs"
  * 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)
  */
@@ -56,15 +56,7 @@ export function ensureContainers(
 ): void {
   const rootMap = doc.getMap("root")
 
-  let rootProduct = schema
-  while (
-    rootProduct._kind === "annotated" &&
-    rootProduct.schema !== undefined
-  ) {
-    rootProduct = rootProduct.schema
-  }
-
-  if (rootProduct._kind !== "product") {
+  if (schema[KIND] !== "product") {
     return
   }
 
@@ -75,7 +67,7 @@ export function ensureContainers(
 
   try {
     doc.transact(() => {
-      for (const [key, fieldSchema] of Object.entries(rootProduct.fields).sort(
+      for (const [key, fieldSchema] of Object.entries(schema.fields).sort(
         ([a], [b]) => a.localeCompare(b),
       )) {
         if (conditional && rootMap.has(key)) continue
@@ -95,62 +87,36 @@ export function ensureContainers(
 /**
  * Ensure a root-level Yjs shared type exists for a schema field.
  *
- * Dispatches based on the schema annotation tag and structural kind:
- * - `annotated("text")` → empty Y.Text
- * - `annotated("counter")` → throws (unsupported in Yjs)
- * - `annotated("movable")` → throws (unsupported in Yjs)
- * - `annotated("tree")` → throws (unsupported in Yjs)
- * - `product` → empty Y.Map (recursive for nested products)
- * - `sequence` → empty Y.Array
- * - `map` → empty Y.Map
- * - `scalar`/`sum` → no-op (plain values don't need containers)
+ * Dispatches on `[KIND]`:
+ * - `"text"` → empty Y.Text
+ * - `"product"` → empty Y.Map (recursive for nested products)
+ * - `"sequence"` → empty Y.Array
+ * - `"map"` → empty Y.Map
+ * - `"scalar"` / `"sum"` → Zero.structural default
+ * - `"counter"` / `"set"` / `"tree"` / `"movable"` → throw (not supported by Yjs)
  */
 function ensureRootField(
   rootMap: Y.Map<unknown>,
   key: string,
   fieldSchema: SchemaNode,
 ): void {
-  const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : undefined
-
-  switch (tag) {
+  switch (fieldSchema[KIND]) {
     case "text":
       rootMap.set(key, new Y.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 = unwrapAnnotations(fieldSchema)
-
-  switch (structural._kind) {
     case "product":
-      rootMap.set(key, ensureMapContainers(structural))
+      rootMap.set(key, ensureMapContainers(fieldSchema))
       return
+
     case "sequence":
       rootMap.set(key, new Y.Array())
       return
+
     case "map":
       rootMap.set(key, new Y.Map())
       return
+
     case "scalar":
     case "sum": {
       // Plain values don't need shared type containers, but they DO
@@ -162,6 +128,16 @@ function ensureRootField(
       }
       return
     }
+
+    case "counter":
+    case "set":
+    case "tree":
+    case "movable":
+      throw new Error(
+        `Yjs substrate does not support [KIND]="${fieldSchema[KIND]}". ` +
+          `Supported kinds: text, product, sequence, map, scalar, sum. ` +
+          `Encountered unsupported kind at root field "${key}".`,
+      )
   }
 }
 
@@ -175,37 +151,33 @@ function ensureRootField(
  *
  * Only creates containers for fields that require Yjs shared types
  * (text → Y.Text, product → Y.Map, sequence → Y.Array, map → Y.Map).
- * Scalar and sum fields are left empty — they'll be written as plain
- * values via change() when needed.
+ * Scalar and sum fields are set to their structural zero defaults.
  */
 function ensureMapContainers(schema: SchemaNode): Y.Map<unknown> {
   const map = new Y.Map()
-  const structural = unwrapAnnotations(schema)
 
-  if (structural._kind !== "product") return map
+  if (schema[KIND] !== "product") return map
 
   for (const [key, fieldSchema] of Object.entries(
-    structural.fields as Record<string, SchemaNode>,
+    schema.fields as Record<string, SchemaNode>,
   ).sort(([a], [b]) => a.localeCompare(b))) {
-    const tag = fieldSchema._kind === "annotated" ? fieldSchema.tag : undefined
-
-    if (tag === "text") {
-      map.set(key, new Y.Text())
-      continue
-    }
-
-    const fs = unwrapAnnotations(fieldSchema)
+    switch (fieldSchema[KIND]) {
+      case "text":
+        map.set(key, new Y.Text())
+        break
 
-    switch (fs._kind) {
       case "product":
         map.set(key, ensureMapContainers(fieldSchema))
         break
+
       case "sequence":
         map.set(key, new Y.Array())
         break
+
       case "map":
         map.set(key, new Y.Map())
         break
+
       case "scalar":
       case "sum": {
         const zero = Zero.structural(fieldSchema)
@@ -214,23 +186,18 @@ function ensureMapContainers(schema: SchemaNode): Y.Map<unknown> {
         }
         break
       }
+
+      case "counter":
+      case "set":
+      case "tree":
+      case "movable":
+        throw new Error(
+          `Yjs substrate does not support [KIND]="${fieldSchema[KIND]}". ` +
+            `Supported kinds: text, product, sequence, map, scalar, sum. ` +
+            `Encountered unsupported kind at nested field "${key}".`,
+        )
     }
   }
 
   return map
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Unwrap annotation wrappers to reach the structural schema node.
- */
-function unwrapAnnotations(schema: SchemaNode): SchemaNode {
-  let s = schema
-  while (s._kind === "annotated" && s.schema !== undefined) {
-    s = s.schema
-  }
-  return s
-}
+}

package/src/substrate.ts

@@ -101,7 +101,7 @@ export function createYjsSubstrate(
       // wrappedPrepare (changefeed layer) still buffers the op.
     },
 
-    onFlush(origin?: string): void {
+    onFlush(_origin?: string): void {
       if (!inOurTransaction && pendingChanges.length > 0) {
         // Local write: apply accumulated changes within a single
         // Yjs transaction tagged with our origin for echo suppression.
@@ -132,6 +132,18 @@ export function createYjsSubstrate(
       return new YjsVersion(Y.encodeStateVector(doc))
     },
 
+    baseVersion(): YjsVersion {
+      // Yjs substrate: base is always the initial state (no advance supported).
+      return new YjsVersion(new Uint8Array([0]))
+    },
+
+    advance(_to: YjsVersion): void {
+      throw new Error(
+        "advance() on a live Yjs substrate is not yet supported. " +
+          "Use advance() on a YjsReplica instead.",
+      )
+    },
+
     exportEntirety(): SubstratePayload {
       return {
         kind: "entirety",
@@ -180,7 +192,7 @@ export function createYjsSubstrate(
     }
 
     // Convert Yjs events → kyneta Ops
-    const ops = eventsToOps(events)
+    const ops = eventsToOps(events, schema)
     if (ops.length === 0) {
       return
     }
@@ -239,24 +251,57 @@ export function createYjsSubstrate(
  * storage without ever interpreting document fields.
  */
 export function createYjsReplica(doc: Y.Doc): Replica<YjsVersion> {
+  let currentDoc = doc
+  let currentBase: YjsVersion = new YjsVersion(
+    Y.encodeStateVector(new Y.Doc()),
+  )
+
   return {
-    [BACKING_DOC]: doc,
+    get [BACKING_DOC]() {
+      return currentDoc
+    },
 
     version(): YjsVersion {
-      return new YjsVersion(Y.encodeStateVector(doc))
+      return new YjsVersion(Y.encodeStateVector(currentDoc))
+    },
+
+    baseVersion(): YjsVersion {
+      return currentBase
+    },
+
+    advance(to: YjsVersion): void {
+      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")
+      }
+
+      // Yjs can only do full projection (to = version).
+      // For any to < version, it's a no-op — undershoot contract.
+      if (currentCmp !== "equal") return
+
+      // Full projection: create a new doc with current state, no history.
+      const update = Y.encodeStateAsUpdate(currentDoc)
+      const newDoc = new Y.Doc()
+      Y.applyUpdate(newDoc, update)
+      currentDoc = newDoc
+      currentBase = new YjsVersion(Y.encodeStateVector(currentDoc))
     },
 
     exportEntirety(): SubstratePayload {
       return {
         kind: "entirety",
         encoding: "binary",
-        data: Y.encodeStateAsUpdate(doc),
+        data: Y.encodeStateAsUpdate(currentDoc),
       }
     },
 
     exportSince(since: YjsVersion): SubstratePayload | null {
       try {
-        const bytes = Y.encodeStateAsUpdate(doc, since.sv)
+        const bytes = Y.encodeStateAsUpdate(currentDoc, since.sv)
         return { kind: "since", encoding: "binary", data: bytes }
       } catch {
         return null
@@ -273,7 +318,7 @@ export function createYjsReplica(doc: Y.Doc): Replica<YjsVersion> {
             "If you recently switched CRDT backends, stale clients may be sending incompatible data.",
         )
       }
-      Y.applyUpdate(doc, payload.data)
+      Y.applyUpdate(currentDoc, payload.data)
     },
   } as Replica<YjsVersion>
 }