@kyneta/yjs-schema 1.6.1 → 1.7.0

package/src/__tests__/materialize.test.ts

@@ -0,0 +1,227 @@
+// materialize — Tests for materializeYjsShadow.
+//
+// Validates that the Yjs→PlainState materialization produces correct
+// plain JS objects for all supported schema types: text, scalar,
+// sequence, nested struct, and empty documents.
+//
+// Yjs does not support counter, tree, or movableList — those are skipped.
+
+import type { ProductSchema, SchemaBinding } from "@kyneta/schema"
+import {
+  BACKING_DOC,
+  change,
+  createDoc,
+  deriveSchemaBinding,
+  KIND,
+  Schema,
+  type SchemaNode,
+  SUBSTRATE,
+} from "@kyneta/schema"
+import { describe, expect, it } from "vitest"
+import type * as Y from "yjs"
+import { yjs } from "../bind-yjs.js"
+import { materializeYjsShadow } from "../materialize.js"
+
+// ===========================================================================
+// Helpers
+// ===========================================================================
+
+function trivialBinding(schema: SchemaNode): SchemaBinding {
+  if (schema[KIND] === "product") {
+    return deriveSchemaBinding(schema as ProductSchema, {})
+  }
+  return { forward: new Map(), inverse: new Map() }
+}
+
+function getYDoc(docRef: unknown): Y.Doc {
+  const substrate = (docRef as any)[SUBSTRATE]
+  return (substrate as any)[BACKING_DOC] as Y.Doc
+}
+
+// ===========================================================================
+// Test schemas
+// ===========================================================================
+
+const TextSchema = Schema.struct({
+  title: Schema.text(),
+})
+
+const ScalarSchema = Schema.struct({
+  name: Schema.string(),
+  age: Schema.number(),
+  active: Schema.boolean(),
+})
+
+const SequenceSchema = Schema.struct({
+  items: Schema.list(Schema.string()),
+})
+
+const NestedSchema = Schema.struct({
+  meta: Schema.struct({
+    author: Schema.string(),
+    version: Schema.number(),
+  }),
+})
+
+const FullSchema = Schema.struct({
+  title: Schema.text(),
+  theme: Schema.string(),
+  tags: Schema.list(Schema.string()),
+  settings: Schema.struct({
+    darkMode: Schema.boolean(),
+    fontSize: Schema.number(),
+  }),
+})
+
+// ===========================================================================
+// Tests
+// ===========================================================================
+
+describe("materializeYjsShadow", () => {
+  it("materializes text fields", () => {
+    const doc = createDoc(yjs.bind(TextSchema))
+    change(doc, (d: any) => {
+      d.title.insert(0, "hello")
+    })
+
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(TextSchema)
+    const result = materializeYjsShadow(yDoc, TextSchema, binding)
+
+    expect(result).toEqual({ title: "hello" })
+  })
+
+  it("materializes scalar fields", () => {
+    const doc = createDoc(yjs.bind(ScalarSchema))
+    change(doc, (d: any) => {
+      d.name.set("Alice")
+      d.age.set(30)
+      d.active.set(true)
+    })
+
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(ScalarSchema)
+    const result = materializeYjsShadow(yDoc, ScalarSchema, binding)
+
+    expect(result).toEqual({ name: "Alice", age: 30, active: true })
+  })
+
+  it("materializes sequence fields", () => {
+    const doc = createDoc(yjs.bind(SequenceSchema))
+    // Separate change() calls for list pushes to preserve order
+    // (Yjs reverses order within a single transaction)
+    change(doc, (d: any) => d.items.push("alpha"))
+    change(doc, (d: any) => d.items.push("beta"))
+    change(doc, (d: any) => d.items.push("gamma"))
+
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(SequenceSchema)
+    const result = materializeYjsShadow(yDoc, SequenceSchema, binding)
+
+    expect(result).toEqual({ items: ["alpha", "beta", "gamma"] })
+  })
+
+  it("materializes nested struct fields", () => {
+    const doc = createDoc(yjs.bind(NestedSchema))
+    change(doc, (d: any) => {
+      d.meta.author.set("Bob")
+      d.meta.version.set(42)
+    })
+
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(NestedSchema)
+    const result = materializeYjsShadow(yDoc, NestedSchema, binding)
+
+    expect(result).toEqual({
+      meta: { author: "Bob", version: 42 },
+    })
+  })
+
+  it("materializes empty document to structural zeros", () => {
+    const doc = createDoc(yjs.bind(FullSchema))
+
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(FullSchema)
+    const result = materializeYjsShadow(yDoc, FullSchema, binding)
+
+    expect(result).toEqual({
+      title: "",
+      theme: "",
+      tags: [],
+      settings: { darkMode: false, fontSize: 0 },
+    })
+  })
+
+  it("uses raw field names, not identity hashes", () => {
+    const doc = createDoc(yjs.bind(TextSchema))
+    change(doc, (d: any) => {
+      d.title.insert(0, "test")
+    })
+
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(TextSchema)
+    const result = materializeYjsShadow(yDoc, TextSchema, binding)
+
+    // Keys should be the raw field name "title", not an identity hash
+    const keys = Object.keys(result as Record<string, unknown>)
+    expect(keys).toContain("title")
+    expect(keys).toHaveLength(1)
+    // No key should look like a hash (long alphanumeric string)
+    for (const key of keys) {
+      expect(key).toBe("title")
+    }
+  })
+
+  it("materializes a complex document with multiple field types", () => {
+    const doc = createDoc(yjs.bind(FullSchema))
+
+    change(doc, (d: any) => {
+      d.title.insert(0, "My Doc")
+      d.theme.set("dark")
+      d.settings.darkMode.set(true)
+      d.settings.fontSize.set(16)
+    })
+    change(doc, (d: any) => d.tags.push("important"))
+    change(doc, (d: any) => d.tags.push("urgent"))
+
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(FullSchema)
+    const result = materializeYjsShadow(yDoc, FullSchema, binding)
+
+    expect(result).toEqual({
+      title: "My Doc",
+      theme: "dark",
+      tags: ["important", "urgent"],
+      settings: { darkMode: true, fontSize: 16 },
+    })
+  })
+
+  it("materializes without binding (undefined binding)", () => {
+    const doc = createDoc(yjs.bind(TextSchema))
+    change(doc, (d: any) => {
+      d.title.insert(0, "no binding")
+    })
+
+    const yDoc = getYDoc(doc)
+    // Pass no binding — materialize should still work
+    const result = materializeYjsShadow(yDoc, TextSchema)
+
+    // Without binding, keys may be identity hashes — but the values
+    // should still be correct and the result should be an object.
+    expect(result).toBeDefined()
+    expect(typeof result).toBe("object")
+  })
+
+  it("nested nullable materializes to null on fresh doc", () => {
+    const schema = Schema.struct({
+      settings: Schema.struct({
+        theme: Schema.string().nullable(),
+      }),
+    })
+    const doc = createDoc(yjs.bind(schema))
+    const yDoc = getYDoc(doc)
+    const binding = trivialBinding(schema)
+    const result = materializeYjsShadow(yDoc, schema, binding)
+    expect(result).toEqual({ settings: { theme: null } })
+  })
+})

package/src/__tests__/position.test.ts

@@ -20,7 +20,7 @@ import {
 import {
   type PositionTestEnv,
   positionConformance,
-} from "@kyneta/schema/src/__tests__/position-conformance.js"
+} from "@kyneta/schema/testing"
 import { describe, expect, it } from "vitest"
 import * as Y from "yjs"
 import { ensureContainers } from "../populate.js"
@@ -118,7 +118,7 @@ describe("YjsPosition: concurrent edits", () => {
     // --- Doc 2: fork from doc1's state ---
     const doc2 = new Y.Doc()
     Y.applyUpdate(doc2, Y.encodeStateAsUpdate(doc1))
-    ensureContainers(doc2, TextSchema, true)
+    ensureContainers(doc2, TextSchema)
     const substrate2 = createYjsSubstrate(doc2, TextSchema)
     const ref2 = createRef(TextSchema, substrate2) as any
 
@@ -175,7 +175,7 @@ describe("YjsPosition: concurrent edits", () => {
     // --- Doc 2: fork ---
     const doc2 = new Y.Doc()
     Y.applyUpdate(doc2, Y.encodeStateAsUpdate(doc1))
-    ensureContainers(doc2, TextSchema, true)
+    ensureContainers(doc2, TextSchema)
     const substrate2 = createYjsSubstrate(doc2, TextSchema)
     const ref2 = createRef(TextSchema, substrate2) as any
 
@@ -229,7 +229,7 @@ describe("YjsPosition: concurrent edits", () => {
     // --- Doc 2: fork ---
     const doc2 = new Y.Doc()
     Y.applyUpdate(doc2, Y.encodeStateAsUpdate(doc1))
-    ensureContainers(doc2, TextSchema, true)
+    ensureContainers(doc2, TextSchema)
     const substrate2 = createYjsSubstrate(doc2, TextSchema)
     const ref2 = createRef(TextSchema, substrate2) as any
 
@@ -285,7 +285,7 @@ describe("YjsPosition: concurrent edits", () => {
     // Decode on a different doc that has the same state
     const doc2 = new Y.Doc()
     Y.applyUpdate(doc2, Y.encodeStateAsUpdate(doc1))
-    ensureContainers(doc2, TextSchema, true)
+    ensureContainers(doc2, TextSchema)
     const substrate2 = createYjsSubstrate(doc2, TextSchema)
     const ref2 = createRef(TextSchema, substrate2) as any
 
@@ -310,13 +310,13 @@ describe("YjsPosition: concurrent edits", () => {
 
     const doc2 = new Y.Doc()
     Y.applyUpdate(doc2, Y.encodeStateAsUpdate(doc1))
-    ensureContainers(doc2, TextSchema, true)
+    ensureContainers(doc2, TextSchema)
     const substrate2 = createYjsSubstrate(doc2, TextSchema)
     const ref2 = createRef(TextSchema, substrate2) as any
 
     const doc3 = new Y.Doc()
     Y.applyUpdate(doc3, Y.encodeStateAsUpdate(doc1))
-    ensureContainers(doc3, TextSchema, true)
+    ensureContainers(doc3, TextSchema)
     const substrate3 = createYjsSubstrate(doc3, TextSchema)
     const ref3 = createRef(TextSchema, substrate3) as any
 

package/src/__tests__/structural-merge.test.ts

@@ -60,7 +60,7 @@ describe("structural merge protocol (Yjs)", () => {
     // Peer A creates doc and writes text
     const docA = new Y.Doc()
     docA.clientID = 100
-    ensureContainers(docA, TestSchema, false, binding)
+    ensureContainers(docA, TestSchema, binding)
     docA.transact(() => {
       const root = docA.getMap("root")
       ;(root.get(id("title")) as Y.Text).insert(0, "Hello from A")
@@ -70,7 +70,7 @@ describe("structural merge protocol (Yjs)", () => {
     // Peer B independently creates same doc and writes different text
     const docB = new Y.Doc()
     docB.clientID = 200
-    ensureContainers(docB, TestSchema, false, binding)
+    ensureContainers(docB, TestSchema, binding)
     docB.transact(() => {
       const root = docB.getMap("root")
       ;(root.get(id("title")) as Y.Text).insert(0, "Hello from B")
@@ -105,7 +105,7 @@ describe("structural merge protocol (Yjs)", () => {
     const docs = [100, 200, 300].map(cid => {
       const doc = new Y.Doc()
       doc.clientID = cid
-      ensureContainers(doc, TestSchema, false, binding)
+      ensureContainers(doc, TestSchema, binding)
       doc.transact(() => {
         const root = doc.getMap("root")
         ;(root.get(id("title")) as Y.Text).insert(0, `Peer${cid}`)
@@ -145,7 +145,7 @@ describe("structural merge protocol (Yjs)", () => {
     // Create and write
     const doc1 = new Y.Doc()
     doc1.clientID = 42
-    ensureContainers(doc1, TestSchema, false, binding)
+    ensureContainers(doc1, TestSchema, binding)
     doc1.transact(() => {
       const root = doc1.getMap("root")
       ;(root.get(id("title")) as Y.Text).insert(0, "Persistent")
@@ -159,7 +159,7 @@ describe("structural merge protocol (Yjs)", () => {
     const doc2 = new Y.Doc()
     doc2.clientID = 42
     Y.applyUpdate(doc2, snapshot)
-    ensureContainers(doc2, TestSchema, true, binding) // conditional
+    ensureContainers(doc2, TestSchema, binding)
 
     // Data preserved
     const root2 = doc2.getMap("root")
@@ -190,10 +190,10 @@ describe("structural merge protocol (Yjs)", () => {
     const bindingB = trivialBinding(schemaB)
 
     const docA = new Y.Doc()
-    ensureContainers(docA, schemaA, false, bindingA)
+    ensureContainers(docA, schemaA, bindingA)
 
     const docB = new Y.Doc()
-    ensureContainers(docB, schemaB, false, bindingB)
+    ensureContainers(docB, schemaB, bindingB)
 
     // Both should produce byte-identical structural state
     const stateA = Y.encodeStateAsUpdate(docA)
@@ -221,7 +221,7 @@ describe("structural merge protocol (Yjs)", () => {
     // Peer A: create v1, write data, export
     const docA = new Y.Doc()
     docA.clientID = 100
-    ensureContainers(docA, v1Schema, false, v1Binding)
+    ensureContainers(docA, v1Schema, v1Binding)
     docA.transact(() => {
       const root = docA.getMap("root")
       ;(root.get(id("title")) as Y.Text).insert(0, "Title")
@@ -229,17 +229,17 @@ describe("structural merge protocol (Yjs)", () => {
     })
     const v1State = Y.encodeStateAsUpdate(docA)
 
-    // Peer B: independently create v2, hydrate v1 data, conditional containers
+    // Peer B: independently create v2, hydrate v1 data, ensure containers
     const docB = new Y.Doc()
     docB.clientID = 200
     Y.applyUpdate(docB, v1State)
-    ensureContainers(docB, v2Schema, true, v2Binding) // conditional — only creates "notes"
+    ensureContainers(docB, v2Schema, v2Binding)
 
     // Another peer C: same thing independently
     const docC = new Y.Doc()
     docC.clientID = 300
     Y.applyUpdate(docC, v1State)
-    ensureContainers(docC, v2Schema, true, v2Binding)
+    ensureContainers(docC, v2Schema, v2Binding)
 
     // B and C's structural ops for "notes" should be identical (both at clientID 0)
     const stateB = Y.encodeStateAsUpdate(docB)
@@ -270,7 +270,7 @@ describe("structural merge protocol (Yjs)", () => {
 
     const doc = new Y.Doc()
     doc.clientID = 999
-    ensureContainers(doc, TestSchema, false, binding)
+    ensureContainers(doc, TestSchema, binding)
 
     // clientID should be restored
     expect(doc.clientID).toBe(999)
@@ -285,7 +285,7 @@ describe("structural merge protocol (Yjs)", () => {
 
     const doc = new Y.Doc()
     doc.clientID = 777
-    ensureContainers(doc, TestSchema, false, binding)
+    ensureContainers(doc, TestSchema, binding)
 
     // The state vector should NOT contain the caller's clientID —
     // only STRUCTURAL_YJS_CLIENT_ID (0) should have produced ops.
@@ -399,19 +399,19 @@ describe("structural merge protocol (Yjs)", () => {
     expect(rootA.get(id("count"))).toBe(rootB.get(id("count")))
   })
 
-  // ── Conditional ensureContainers is idempotent ──
+  // ── ensureContainers is idempotent ──
 
-  it("conditional ensureContainers is idempotent on hydrated doc", () => {
+  it("ensureContainers after hydration preserves existing data", () => {
     const binding = trivialBinding(TestSchema)
 
     const doc = new Y.Doc()
     doc.clientID = 50
-    ensureContainers(doc, TestSchema, false, binding)
+    ensureContainers(doc, TestSchema, binding)
 
     const stateBefore = Y.encodeStateAsUpdate(doc)
 
-    // Conditional call should not create new ops (everything already exists)
-    ensureContainers(doc, TestSchema, true, binding)
+    // Repeated call should not create new ops (everything already exists)
+    ensureContainers(doc, TestSchema, binding)
 
     const stateAfter = Y.encodeStateAsUpdate(doc)
     expect(stateAfter).toEqual(stateBefore)

package/src/__tests__/substrate.test.ts

@@ -618,7 +618,7 @@ describe("YjsSubstrate", () => {
   // Context: jj:qpultxsw.
 
   describe("re-entrant write during merge replay", () => {
-    it("subscriber's local change() inside a merge-replay batch lands in Yjs", async () => {
+    it("subscriber's local change() inside a merge-replay batch lands in Yjs", () => {
       const docA = createDoc(yjs.bind(SimpleSchema))
       const docB = createDoc(yjs.bind(SimpleSchema))
 
@@ -647,8 +647,6 @@ describe("YjsSubstrate", () => {
       const delta = exportSince(docA, v0)!
       merge(docB, delta, { origin: "sync" })
 
-      await new Promise<void>(r => queueMicrotask(r))
-
       expect(docB.title()).toBe("seedmore")
       expect(docB.count()).toBe(42)
       expect(writes).toBe(1)

package/src/bind-yjs.ts

@@ -105,17 +105,15 @@ function createYjsFactory(
       // Set stable identity AFTER hydration — avoids Yjs clientID
       // conflict detection that would reassign to a random value.
       doc.clientID = numericClientId
-      // Conditional ensureContainers: skip fields that already exist
-      // from hydrated state (each set() is a CRDT write).
-      ensureContainers(doc, schema, true, binding)
+      ensureContainers(doc, schema, binding)
       return createYjsSubstrate(doc, schema, binding)
     },
 
     create(schema: SchemaNode): Substrate<YjsVersion> {
-      // Fresh doc — set identity immediately, unconditional containers.
+      // Fresh doc — set identity immediately.
       const doc = new Y.Doc()
       doc.clientID = numericClientId
-      ensureContainers(doc, schema, false, binding)
+      ensureContainers(doc, schema, binding)
       return createYjsSubstrate(doc, schema, binding)
     },
 

package/src/change-mapping.ts

@@ -22,6 +22,7 @@ import type {
   MapChange,
   Op,
   Path,
+  ProductSchema,
   ReplaceChange,
   RichTextChange,
   RichTextInstruction,
@@ -33,9 +34,9 @@ import type {
   TextInstruction,
 } from "@kyneta/schema"
 import {
-  advanceSchema,
   expandMapOpsToLeaves,
   KIND,
+  pathSchema,
   RawPath,
   richTextChange,
 } from "@kyneta/schema"
@@ -118,6 +119,17 @@ export function applyChangeToYjs(
           `Attempted TreeChange at path [${pathToString(path)}].`,
       )
 
+    case "set-op":
+      // Sets (`Schema.set`) are rejected by `yjs.bind` at compile time
+      // (`"add-wins-per-key"` is not in `YjsLaws`). Unreachable from any
+      // bound Yjs substrate today; kept against the new `SetChange`
+      // vocabulary so future law-set expansion has a clear extension point.
+      throw new Error(
+        `Yjs substrate does not support "${change.type}" changes. ` +
+          `Schema.set requires "add-wins-per-key" which is not in YjsLaws. ` +
+          `Attempted SetChange at path [${pathToString(path)}].`,
+      )
+
     default:
       throw new Error(
         `applyChangeToYjs: unsupported change type "${change.type}"`,
@@ -201,7 +213,7 @@ function applySequenceChange(
   }
 
   // Resolve the item schema for structured insert detection
-  const targetSchema = resolveSchemaAtPath(rootSchema, path)
+  const targetSchema = pathSchema(rootSchema, path)
   const itemSchema = getItemSchema(targetSchema)
 
   let cursor = 0
@@ -241,7 +253,7 @@ function applyMapChange(
   }
 
   // Resolve the schema at this path for structured value detection
-  const targetSchema = resolveSchemaAtPath(rootSchema, path)
+  const targetSchema = pathSchema(rootSchema, path)
 
   // Apply deletes first
   if (change.delete) {
@@ -259,9 +271,10 @@ function applyMapChange(
       // For map schemas (records), use the key as-is (no identity-keying).
       let mapKey = key
       if (binding && targetSchema[KIND] === "product") {
-        // Compute absolute schema path for this field.
+        // Compute absolute schema path for this field — only product-field
+        // segments contribute (entry segments are runtime keys).
         const parentAbsPath = path.segments
-          .filter(s => s.role === "key")
+          .filter(s => s.role === "field")
           .map(s => s.resolve() as string)
           .join(".")
         const absPath = parentAbsPath ? `${parentAbsPath}.${key}` : key
@@ -303,15 +316,19 @@ function applyReplaceChange(
   )
 
   const resolved = lastSeg.resolve()
-  if (parent instanceof Y.Map && lastSeg.role === "key") {
+  if (
+    parent instanceof Y.Map &&
+    (lastSeg.role === "field" || lastSeg.role === "entry")
+  ) {
     // Resolve schema for the target field for structured value detection
-    const targetSchema = resolveSchemaAtPath(rootSchema, path)
+    const targetSchema = pathSchema(rootSchema, path)
     const yjsValue = maybeCreateSharedType(change.value, targetSchema)
-    // Use identity hash for product-field boundaries.
+    // Identity-keying applies only at product-field boundaries; entry
+    // segments use the runtime key as-is.
     let mapKey = resolved as string
-    if (binding) {
+    if (binding && lastSeg.role === "field") {
       const absPath = path.segments
-        .filter(s => s.role === "key")
+        .filter(s => s.role === "field")
         .map(s => s.resolve() as string)
         .join(".")
       const identity = binding.forward.get(absPath) as string | undefined
@@ -319,7 +336,7 @@ function applyReplaceChange(
     }
     parent.set(mapKey, yjsValue)
   } else if (parent instanceof Y.Array && lastSeg.role === "index") {
-    const targetSchema = resolveSchemaAtPath(rootSchema, path)
+    const targetSchema = pathSchema(rootSchema, path)
     const yjsValue = maybeCreateSharedType(change.value, targetSchema)
     parent.delete(resolved as number, 1)
     parent.insert(resolved as number, [yjsValue])
@@ -509,7 +526,7 @@ export function eventsToOps(
   const ops: Op[] = []
 
   for (const event of events) {
-    const kynetaPath = yjsPathToKynetaPath(event.path, binding)
+    const kynetaPath = yjsPathToKynetaPath(event.path, schema, binding)
     const change = eventToChange(event, schema, kynetaPath, binding)
     if (change) {
       ops.push({ path: kynetaPath, change })
@@ -524,31 +541,55 @@ export function eventsToOps(
 // ---------------------------------------------------------------------------
 
 /**
- * Convert a Yjs event path (array of string | number) to a kyneta Path.
+ * Convert a Yjs event path to a kyneta `RawPath`, walking the schema
+ * alongside so each segment is classified as field / entry / index by
+ * the current schema kind.
  *
- * `event.path` from `observeDeep` is relative to the observed type.
- * Strings become key segments, numbers become index segments.
+ * Why schema-aware and not "did the inverse lookup hit?": the binding's
+ * inverse map only covers declared product-field positions reachable
+ * without crossing a runtime-keyed container. A declared struct field
+ * nested under a `record(...)` value type is reachable via Yjs but
+ * absent from `binding.inverse` — without the schema walk it would be
+ * misclassified as an entry and then rejected by `advanceSchema`.
  */
 function yjsPathToKynetaPath(
   yjsPath: (string | number)[],
+  rootSchema: SchemaNode,
   binding?: SchemaBinding,
 ): RawPath {
   let path = RawPath.empty
+  let schema: SchemaNode | undefined = rootSchema
   for (const segment of yjsPath) {
     if (typeof segment === "string") {
-      // Reverse-map identity hash → absolute schema path → leaf field name.
-      // Yjs events emit identity-keyed strings at product-field positions;
-      // we need to recover the original field name for kyneta schema paths.
+      // Inverse-lookup recovers the original declared field name when
+      // the segment IS an identity hash; otherwise we keep the string.
+      let leaf = segment
       const absPath = binding?.inverse.get(segment as any)
       if (absPath) {
         const lastDot = absPath.lastIndexOf(".")
-        const leaf = lastDot >= 0 ? absPath.slice(lastDot + 1) : absPath
+        leaf = lastDot >= 0 ? absPath.slice(lastDot + 1) : absPath
+      }
+      const kind = schema?.[KIND]
+      if (kind === "product") {
         path = path.field(leaf)
+        schema = (schema as ProductSchema | undefined)?.fields[leaf]
+      } else if (kind === "map" || kind === "set" || kind === "tree") {
+        path = path.entry(leaf)
+        schema = (schema as any)?.item
       } else {
-        path = path.field(segment)
+        // Unknown / sum / unrecognized — fall back to entry. Subsequent
+        // segments are likely walking plain JSON inside a sum variant.
+        path = path.entry(leaf)
+        schema = undefined
       }
     } else if (typeof segment === "number") {
       path = path.item(segment)
+      const kind = schema?.[KIND]
+      if (kind === "sequence" || kind === "movable") {
+        schema = (schema as any).item
+      } else {
+        schema = undefined
+      }
     }
   }
   return path
@@ -576,7 +617,7 @@ function eventToChange(
 ): ChangeBase | null {
   if (event.target instanceof Y.Text) {
     // Both text and richtext use Y.Text — resolve the schema to dispatch.
-    const schemaAtPath = resolveSchemaAtPath(rootSchema, kynetaPath)
+    const schemaAtPath = pathSchema(rootSchema, kynetaPath)
     if (schemaAtPath[KIND] === "richtext") {
       return richTextEventToChange(event)
     }
@@ -739,20 +780,6 @@ function extractEventValue(value: unknown): unknown {
 // Schema helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Resolve the schema at a given path by walking through advanceSchema.
- */
-function resolveSchemaAtPath(rootSchema: SchemaNode, path: Path): SchemaNode {
-  let schema = rootSchema
-  for (const seg of path.segments) {
-    schema = advanceSchema(schema, seg)
-    // Sum variants are always PlainSchema — cannot advance further.
-    // Return early; remaining segments address plain JSON values.
-    if (schema[KIND] === "sum") return schema
-  }
-  return schema
-}
-
 /**
  * Get the item schema from a sequence schema, if available.
  */

package/src/index.ts

@@ -50,8 +50,7 @@ export type { YjsNativeMap } from "./native-map.js"
 export { ensureContainers } from "./populate.js"
 // Position conformance
 export { fromYjsAssoc, toYjsAssoc, YjsPosition } from "./position.js"
-// Reader
-export { yjsReader } from "./reader.js"
+
 // Substrate
 export {
   createYjsSubstrate,