@kyneta/yjs-schema 1.6.1 → 1.7.0

package/src/materialize.ts

@@ -0,0 +1,109 @@
+// materialize — Yjs→PlainState materialization via generic resolver.
+//
+// Implements `createYjsResolver`, a closure-based `MaterializeResolver`
+// that navigates the Yjs shared type tree via `resolveYjsType`. The
+// generic `createMaterializeInterpreter` drives the catamorphism; the
+// resolver handles only the CRDT-specific value extraction.
+//
+// Unsupported types (counter, tree, movable) return `undefined` from
+// the resolver, triggering the generic interpreter's zero fallback.
+//
+// Zero fallback for missing values is handled canonically by the
+// generic interpreter — not inlined here.
+
+import type {
+  MaterializeResolver,
+  Path,
+  PlainState,
+  RichTextDelta,
+  SchemaBinding,
+  Schema as SchemaNode,
+} from "@kyneta/schema"
+import {
+  createMaterializeInterpreter,
+  interpret,
+  isNonNullObject,
+  materializeContextFromResolver,
+} from "@kyneta/schema"
+import * as Y from "yjs"
+import { extractValue, yTextToRichTextDelta } from "./yjs-extract.js"
+import { resolveYjsType } from "./yjs-resolve.js"
+
+// ---------------------------------------------------------------------------
+// Yjs resolver
+// ---------------------------------------------------------------------------
+
+function createYjsResolver(
+  rootMap: Y.Map<any>,
+  rootSchema: SchemaNode,
+  binding?: SchemaBinding,
+): MaterializeResolver {
+  return {
+    resolveValue(path: Path): unknown {
+      const result = resolveYjsType(rootMap, rootSchema, path, binding)
+      return extractValue(result.resolved)
+    },
+
+    resolveText(path: Path): string | undefined {
+      const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding)
+      if (resolved instanceof Y.Text) {
+        return resolved.toJSON()
+      }
+      const value = extractValue(resolved)
+      return typeof value === "string" ? value : undefined
+    },
+
+    // Yjs does not support counters — schemas with counter types are
+    // rejected at bind time. Return undefined to trigger zero fallback.
+    resolveCounter(_path: Path): number | undefined {
+      return undefined
+    },
+
+    resolveRichText(path: Path): RichTextDelta | undefined {
+      const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding)
+      if (resolved instanceof Y.Text) {
+        return yTextToRichTextDelta(resolved)
+      }
+      return undefined
+    },
+
+    resolveLength(path: Path): number {
+      const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding)
+      if (resolved instanceof Y.Array) {
+        return resolved.length
+      }
+      return Array.isArray(resolved) ? resolved.length : 0
+    },
+
+    resolveKeys(path: Path): string[] {
+      const { resolved } = resolveYjsType(rootMap, rootSchema, path, binding)
+      if (resolved instanceof Y.Map) {
+        return Array.from(resolved.keys())
+      }
+      return isNonNullObject(resolved) ? Object.keys(resolved) : []
+    },
+
+    // Yjs has no tree primitive — schemas with `Schema.tree` are rejected
+    // at bind time. Defensive [] for any caller that reaches here.
+    resolveForest(_path: Path): readonly never[] {
+      return []
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function materializeYjsShadow(
+  doc: Y.Doc,
+  schema: SchemaNode,
+  binding?: SchemaBinding,
+): PlainState {
+  const rootMap = doc.getMap("root")
+  const resolver = createYjsResolver(rootMap, schema, binding)
+  const interp = createMaterializeInterpreter(resolver)
+  const ctx = materializeContextFromResolver(resolver)
+  const result = interpret(schema, interp, ctx)
+  return result as PlainState
+}

package/src/populate.ts

@@ -1,14 +1,11 @@
 // populate — Yjs container creation from schema structure.
 //
 // Ensures that the correct Yjs shared types (Y.Text, Y.Array, Y.Map)
-// exist in a Y.Doc's root map to match the schema structure, and that
-// scalar/sum fields are initialized with Zero.structural defaults.
+// exist in a Y.Doc's root map to match the schema structure.
 //
-// This is NOT seed data — it's structural completeness, matching what
-// PlainSubstrate does when it initializes its store with Zero.structural.
-// The Yjs store reader expects to find values at every schema path;
-// without this, unset scalars would return undefined instead of their
-// type-correct zero ("", 0, false).
+// Only container types (text, product, sequence, map) require CRDT
+// writes here. Scalar and sum fields are handled by the materializer's
+// zero fallback — no Yjs writes are needed for non-container types.
 //
 // Root container strategy: All schema fields are children of a single
 // root `Y.Map` obtained via `doc.getMap("root")`. This root map holds
@@ -20,7 +17,7 @@
 // functions: ensureContainers, ensureRootField, ensureMapContainers.
 
 import type { SchemaBinding, Schema as SchemaNode } from "@kyneta/schema"
-import { KIND, STRUCTURAL_YJS_CLIENT_ID, Zero } from "@kyneta/schema"
+import { KIND, STRUCTURAL_YJS_CLIENT_ID } from "@kyneta/schema"
 import * as Y from "yjs"
 
 // ---------------------------------------------------------------------------
@@ -35,14 +32,10 @@ import * as Y from "yjs"
  * 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.
+ * Container fields (text, product, sequence, map) are created if absent;
+ * existing containers are preserved (calling `rootMap.set()` on a field
+ * that already exists would be a destructive CRDT write). Scalar and sum
+ * fields are no-ops — the materializer handles zeros.
  *
  * **Structural identity:** This function temporarily sets `doc.clientID`
  * to `STRUCTURAL_YJS_CLIENT_ID` (0) for the duration of container creation,
@@ -56,14 +49,11 @@ import * as Y from "yjs"
  *
  * @param doc - The Y.Doc to prepare
  * @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)
  * @param binding - Optional SchemaBinding for identity-keyed containers.
  */
 export function ensureContainers(
   doc: Y.Doc,
   schema: SchemaNode,
-  conditional = false,
   binding?: SchemaBinding,
 ): void {
   const rootMap = doc.getMap("root")
@@ -84,7 +74,6 @@ export function ensureContainers(
       )) {
         const identity = binding?.forward.get(key) as string | undefined
         const mapKey = identity ?? key
-        if (conditional && rootMap.has(mapKey)) continue
         ensureRootField(
           rootMap,
           mapKey,
@@ -112,7 +101,7 @@ export function ensureContainers(
  * - `"product"` → empty Y.Map (recursive for nested products)
  * - `"sequence"` → empty Y.Array
  * - `"map"` → empty Y.Map
- * - `"scalar"` / `"sum"` → Zero.structural default
+ * - `"scalar"` / `"sum"` → no-op (materializer zero fallback)
  * - `"counter"` / `"set"` / `"tree"` / `"movable"` → throw (not supported by Yjs)
  *
  * @param rootMap - The root Y.Map to set the field on.
@@ -128,6 +117,12 @@ function ensureRootField(
   binding?: SchemaBinding,
   prefix?: string,
 ): void {
+  // Skip fields that already exist — calling rootMap.set() on an existing
+  // shared type would replace it (a destructive CRDT write), and scalars
+  // are no-ops regardless. This is safe on fresh docs (nothing to skip)
+  // and necessary on hydrated docs (preserves existing data).
+  if (rootMap.has(key)) return
+
   switch (fieldSchema[KIND]) {
     case "text":
     case "richtext":
@@ -147,16 +142,10 @@ function ensureRootField(
       return
 
     case "scalar":
-    case "sum": {
-      // Plain values don't need shared type containers, but they DO
-      // need structural zero defaults so the store reader returns
-      // type-correct values (e.g. "" not undefined for strings).
-      const zero = Zero.structural(fieldSchema)
-      if (zero !== undefined) {
-        rootMap.set(key, zero)
-      }
+    case "sum":
+      // Value concerns are handled by the materializer's zero fallback.
+      // No CRDT writes needed for non-container types.
       return
-    }
 
     case "counter":
     case "set":
@@ -180,7 +169,7 @@ 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 set to their structural zero defaults.
+ * Scalar and sum fields are skipped (materializer zero fallback).
  *
  * **Identity-keying:** When a `binding` is provided, computes the
  * absolute schema path for each nested field (`prefix.fieldName`) and
@@ -226,13 +215,10 @@ function ensureMapContainers(
         break
 
       case "scalar":
-      case "sum": {
-        const zero = Zero.structural(fieldSchema)
-        if (zero !== undefined) {
-          map.set(mapKey, zero)
-        }
+      case "sum":
+        // Value concerns are handled by the materializer's zero fallback.
+        // No CRDT writes needed for non-container types.
         break
-      }
 
       case "counter":
       case "set":

package/src/substrate.ts

@@ -26,6 +26,7 @@ import type {
   BatchOptions,
   ChangeBase,
   Path,
+  PlainState,
   PositionCapable,
   ProductSchema,
   Reader,
@@ -41,17 +42,19 @@ import type {
   WritableContext,
 } from "@kyneta/schema"
 import {
+  applyChange,
   BACKING_DOC,
   buildWritableContext,
   deriveSchemaBinding,
   executeBatch,
   KIND,
+  plainReader,
 } from "@kyneta/schema"
 import * as Y from "yjs"
 import { applyChangeToYjs, eventsToOps } from "./change-mapping.js"
+import { materializeYjsShadow } from "./materialize.js"
 import { ensureContainers } from "./populate.js"
 import { toYjsAssoc, YjsPosition } from "./position.js"
-import { yjsReader } from "./reader.js"
 import { YjsVersion } from "./version.js"
 import { resolveYjsType } from "./yjs-resolve.js"
 
@@ -111,8 +114,10 @@ export function createYjsSubstrate(
   // The root Y.Map — all schema fields are children of this single map.
   const rootMap = doc.getMap("root")
 
-  // The Reader — live view over the Yjs shared type tree.
-  const reader: Reader = yjsReader(doc, schema, binding)
+  // The shadow — a plain JS object materialized from the Y.Doc.
+  // Kept in sync by applyChange() in prepare().
+  const shadow: PlainState = materializeYjsShadow(doc, schema, binding)
+  const reader: Reader = plainReader(shadow)
 
   // --- Substrate object ---
 
@@ -122,20 +127,31 @@ export function createYjsSubstrate(
     reader: reader,
 
     prepare(path: Path, change: ChangeBase, options?: BatchOptions): void {
+      // Local writes: apply eagerly to the shadow so reads are
+      // immediately consistent. Replay writes: skip — the shadow
+      // will be re-materialized from the Y.Doc in onFlush(replay).
+      if (!options?.replay) {
+        applyChange(shadow, path, change)
+      }
+
       if (options?.replay) {
-        // Yjs already has these ops (the bridge is replaying them
-        // through kyneta solely so the changefeed layer can deliver
-        // notifications — wrappedPrepare buffered the op upstream).
         return
       }
-      // Mutations happen in onFlush inside a single Yjs transaction.
       pendingChanges.push({ path, change })
     },
 
     onFlush(options?: BatchOptions): void {
       if (options?.replay) {
-        // Yjs already committed; wrappedFlush still delivers
-        // notifications upstream.
+        // Re-materialize shadow from the Y.Doc (already committed).
+        const fresh = materializeYjsShadow(doc, schema, binding)
+        for (const key of Object.keys(fresh)) {
+          shadow[key] = fresh[key]
+        }
+        for (const key of Object.keys(shadow)) {
+          if (!(key in fresh)) {
+            delete shadow[key]
+          }
+        }
         return
       }
       if (pendingChanges.length === 0) return
@@ -474,17 +490,14 @@ export const yjsSubstrateFactory: SubstrateFactory<YjsVersion> = {
     const doc = (replica as any)[BACKING_DOC] as Y.Doc
     const binding = trivialBinding(schema)
     // No identity injection for the standalone factory (no peerId).
-    // Conditional ensureContainers: skip fields that already exist
-    // from hydrated state.
-    ensureContainers(doc, schema, true, binding)
+    ensureContainers(doc, schema, binding)
     return createYjsSubstrate(doc, schema, binding)
   },
 
   create(schema: SchemaNode): Substrate<YjsVersion> {
-    // Fresh doc — unconditional ensureContainers (nothing to conflict with).
     const doc = new Y.Doc()
     const binding = trivialBinding(schema)
-    ensureContainers(doc, schema, false, binding)
+    ensureContainers(doc, schema, binding)
     return createYjsSubstrate(doc, schema, binding)
   },
 

package/src/yjs-extract.ts

@@ -0,0 +1,52 @@
+// yjs-extract — shared value-extraction helpers for Yjs shared types.
+//
+// These functions are used by both the reader (yjsReader) and the
+// materialize interpreter to convert Yjs shared types into plain values.
+
+import type { RichTextDelta, RichTextSpan } from "@kyneta/schema"
+import * as Y from "yjs"
+
+/**
+ * Extract a plain value from a Yjs shared type or return a plain value as-is.
+ *
+ * - Y.Text → `.toJSON()` (string)
+ * - Y.Map → `.toJSON()` (plain object snapshot — for product/map reads)
+ * - Y.Array → `.toJSON()` (plain array snapshot)
+ * - Plain values (string, number, boolean, null) → returned as-is
+ */
+export function extractValue(resolved: unknown): unknown {
+  if (resolved instanceof Y.Text) {
+    return resolved.toJSON()
+  }
+  if (resolved instanceof Y.Map) {
+    return resolved.toJSON()
+  }
+  if (resolved instanceof Y.Array) {
+    return resolved.toJSON()
+  }
+  // Plain scalar value (string, number, boolean, null, etc.)
+  return resolved
+}
+
+/**
+ * Convert a Y.Text's delta (Quill format) to a kyneta RichTextDelta.
+ *
+ * Yjs `.toDelta()` returns `{ insert: string, attributes?: Record<string, any> }[]`.
+ * Kyneta RichTextDelta is `{ text: string, marks?: MarkMap }[]`.
+ */
+export function yTextToRichTextDelta(ytext: Y.Text): RichTextDelta {
+  const delta = ytext.toDelta() as Array<{
+    insert: string
+    attributes?: Record<string, unknown>
+  }>
+  const spans: RichTextSpan[] = []
+  for (const d of delta) {
+    if (typeof d.insert !== "string") continue
+    const span: RichTextSpan =
+      d.attributes && Object.keys(d.attributes).length > 0
+        ? { text: d.insert, marks: d.attributes }
+        : { text: d.insert }
+    spans.push(span)
+  }
+  return spans
+}

package/src/yjs-resolve.ts

@@ -1,35 +1,29 @@
 // yjs-resolve — Yjs-specific path resolution.
 //
-// Implements stepIntoYjs and resolveYjsType for schema-guided
-// navigation of the Yjs shared type tree.
-//
-// resolveYjsType is a left-fold over path segments, accumulating
-// (currentType, currentSchema) at each step. This mirrors how
-// resolveContainer works for Loro — but uses `instanceof` for
-// runtime type discrimination instead of Loro's `.kind()` method.
+// `stepIntoYjs` is the per-step substrate dispatch; `resolveYjsType`
+// applies the core `foldPath` primitive (from `@kyneta/schema`) around
+// it. The semantic invariants of the fold — identity-keying at
+// product-field boundaries, sum-boundary short-circuit — live in
+// `fold-path.ts`, not here.
 //
 // Root container strategy: All schema fields are children of a single
 // root `Y.Map` obtained via `doc.getMap("root")`. This root map holds
 // shared types (Y.Text, Y.Array, Y.Map) and plain values uniformly.
 // Using a single root Y.Map enables one `observeDeep` call that
 // captures all mutations with correct relative paths.
-//
-// Identity-keying: when a SchemaBinding is provided, every product-field
-// boundary uses the identity hash (from binding.forward) instead of the
-// field name as the Y.Map key. The binding is threaded through
-// resolveYjsType and stepIntoYjs.
 
-import type {
-  Path,
-  SchemaBinding,
-  Schema as SchemaNode,
-  Segment,
+import {
+  foldPath,
+  type Path,
+  type PathFoldResult,
+  type PathStepper,
+  type SchemaBinding,
+  type Schema as SchemaNode,
 } from "@kyneta/schema"
-import { advanceSchema, KIND } from "@kyneta/schema"
 import * as Y from "yjs"
 
 // ---------------------------------------------------------------------------
-// stepIntoYjs — single step of the fold
+// stepIntoYjs — per-step substrate dispatch (PathStepper for Yjs)
 // ---------------------------------------------------------------------------
 
 /**
@@ -41,15 +35,16 @@ import * as Y from "yjs"
  * - `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
- * @param identity - Optional identity hash to use instead of the segment's resolved value
+ * `_nextSchema` is part of the `PathStepper` contract for Loro's root
+ * dispatch but is unused here — Yjs's `instanceof` dispatch doesn't
+ * need to look ahead at the next schema kind.
  */
-export function stepIntoYjs(
-  current: unknown,
-  segment: Segment,
-  identity?: string,
-): unknown {
+export const stepIntoYjs: PathStepper = (
+  current,
+  _nextSchema,
+  segment,
+  identity,
+) => {
   const resolved = segment.resolve()
 
   if (current instanceof Y.Map) {
@@ -69,85 +64,25 @@ export function stepIntoYjs(
 }
 
 // ---------------------------------------------------------------------------
-// resolveYjsType — full path resolution via left-fold
+// resolveYjsType — full path resolution via foldPath
 // ---------------------------------------------------------------------------
 
-/**
- * Result of resolving a Yjs shared type at a path.
- *
- * Includes both the resolved Yjs value and the schema at that position,
- * enabling callers to distinguish between schema kinds that map to the
- * same Yjs type (e.g. "text" vs "richtext" both use Y.Text).
- */
-export interface ResolvedYjs {
-  readonly resolved: unknown
-  readonly schema: SchemaNode
-}
-
 /**
  * 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.
+ * Thin wrapper around `foldPath(stepIntoYjs, ...)`. Returns the
+ * `PathFoldResult` shape from core — `{ resolved, schema }`.
  *
- * When a `binding` is provided, each step computes the absolute schema
- * path and looks up the identity hash from `binding.forward`. This
- * identity hash is used instead of the field name at every product-field
- * boundary (root and nested).
+ * When a `binding` is provided, every product-field boundary uses the
+ * identity hash from `binding.forward` instead of the field name.
  *
- * Returns both the Yjs shared type (or plain value) and the schema at
- * the terminal position. For an empty path, returns the root map and
- * root schema.
- *
- * @param rootMap - The root `Y.Map` obtained via `doc.getMap("root")`
- * @param rootSchema - The root document schema
- * @param path - The path to resolve
- * @param binding - Optional SchemaBinding for identity-keyed navigation.
+ * For an empty path, returns the root map and root schema.
  */
 export function resolveYjsType(
   rootMap: Y.Map<any>,
   rootSchema: SchemaNode,
   path: Path,
   binding?: SchemaBinding,
-): ResolvedYjs {
-  let current: unknown = rootMap
-  let schema = rootSchema
-  // Track the accumulated absolute schema path for identity lookup.
-  // Only string (key) segments contribute — index segments are structural
-  // and don't participate in identity-keying.
-  let absPath = ""
-
-  for (let i = 0; i < path.length; i++) {
-    const seg = path.segments[i]
-    if (!seg) throw new Error(`Missing segment at index ${i}`)
-    const nextSchema = advanceSchema(schema, seg)
-
-    // Compute identity for this step if binding is provided and the
-    // segment is a key (field name at a product boundary).
-    let identity: string | undefined
-    if (binding && seg.role === "key") {
-      const segStr = seg.resolve() as string
-      absPath = absPath ? `${absPath}.${segStr}` : segStr
-      identity = binding.forward.get(absPath) as string | undefined
-    }
-
-    current = stepIntoYjs(current, seg, identity)
-    schema = nextSchema
-
-    // Sum variants are always PlainSchema — no CRDT containers inside.
-    // Once we land on a sum, resolve remaining segments via plain JS
-    // property access on the (JSON) value.
-    if (schema[KIND] === "sum" && i + 1 < path.length) {
-      for (let j = i + 1; j < path.length; j++) {
-        const remaining = path.segments[j]
-        if (!remaining) throw new Error(`Missing segment at index ${j}`)
-        current = (current as Record<string, unknown>)?.[
-          remaining.resolve() as string
-        ]
-      }
-      return { resolved: current, schema }
-    }
-  }
-
-  return { resolved: current, schema }
+): PathFoldResult {
+  return foldPath(rootMap, rootSchema, path, stepIntoYjs, binding)
 }