@syncular/client-plugin-yjs 0.0.0

package/README.md

@@ -0,0 +1,59 @@
+# @syncular/client-plugin-crdt-yjs
+
+Yjs-first CRDT plugin for Syncular client integration.
+
+Implemented:
+- Rule-based field mapping: `{ table, field, stateColumn }`.
+- Kind-aware materialization: `text`, `xml-fragment`, `prosemirror`.
+- Stable payload envelope key: `__yjs`.
+- `beforePush` transformation:
+  - Applies Yjs update envelopes to local state.
+  - Materializes projection field values.
+  - Stores canonical snapshot state in `stateColumn`.
+  - Strips the envelope key by default to keep payload DB-safe.
+  - Can keep envelope for server-side CRDT merge via `stripEnvelopeBeforePush: false`.
+- `afterPull` transformation for snapshot and incremental rows.
+- `beforeApplyWsChanges` transformation for websocket inline rows.
+- Helpers:
+  - `buildYjsTextUpdate`
+  - `applyYjsTextUpdates`
+
+## Envelope Format
+
+Outgoing payload example:
+
+```ts
+{
+  __yjs: {
+    content: {
+      updateId: "upd-123",
+      updateBase64: "<base64-encoded-yjs-update>"
+    }
+  }
+}
+```
+
+The plugin converts this to:
+
+```ts
+{
+  content: "materialized text",
+  content_yjs_state: "<base64-encoded-yjs-snapshot>"
+}
+```
+
+## Example
+
+```ts
+import { createYjsClientPlugin } from '@syncular/client-plugin-crdt-yjs';
+
+const yjs = createYjsClientPlugin({
+  rules: [
+    {
+      table: 'tasks',
+      field: 'content',
+      stateColumn: 'content_yjs_state',
+    },
+  ],
+});
+```

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@syncular/client-plugin-yjs",
+  "version": "0.0.0",
+  "description": "Yjs CRDT plugin primitives for Syncular client integration",
+  "license": "Apache-2.0",
+  "author": "Benjamin Kniffler",
+  "homepage": "https://syncular.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncular/syncular.git",
+    "directory": "plugins/crdt-yjs/client"
+  },
+  "bugs": {
+    "url": "https://github.com/syncular/syncular/issues"
+  },
+  "keywords": [
+    "sync",
+    "offline-first",
+    "realtime",
+    "database",
+    "typescript",
+    "crdt",
+    "yjs"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "browser": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "test": "bun test --pass-with-no-tests",
+    "tsgo": "tsgo --noEmit",
+    "build": "tsgo",
+    "release": "bunx syncular-publish"
+  },
+  "dependencies": {
+    "@syncular/client": "0.0.0",
+    "yjs": "^13.6.29"
+  },
+  "devDependencies": {
+    "@syncular/config": "0.0.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,541 @@
+import { describe, expect, it } from 'bun:test';
+import type {
+  SyncClientLocalMutationArgs,
+  SyncClientPluginContext,
+  SyncClientWsDeliveryArgs,
+  SyncPullResponse,
+  SyncPushRequest,
+  SyncSubscriptionRequest,
+} from '@syncular/client';
+import * as Y from 'yjs';
+import {
+  applyYjsTextUpdates,
+  buildYjsTextUpdate,
+  createYjsClientPlugin,
+  YJS_PAYLOAD_KEY,
+  type YjsClientUpdateEnvelope,
+} from './index';
+
+const ctx: SyncClientPluginContext = {
+  actorId: 'actor-1',
+  clientId: 'client-1',
+};
+
+const emptyPullRequest = {
+  clientId: 'client-1',
+  limitCommits: 100,
+  subscriptions: [] as SyncSubscriptionRequest[],
+};
+
+async function callBeforePush(
+  plugin: ReturnType<typeof createYjsClientPlugin>,
+  request: SyncPushRequest
+): Promise<SyncPushRequest> {
+  const hook = plugin.beforePush;
+  if (!hook) {
+    throw new Error('Expected beforePush hook');
+  }
+  return await hook(ctx, request);
+}
+
+async function callAfterPull(
+  plugin: ReturnType<typeof createYjsClientPlugin>,
+  response: SyncPullResponse
+): Promise<SyncPullResponse> {
+  const hook = plugin.afterPull;
+  if (!hook) {
+    throw new Error('Expected afterPull hook');
+  }
+  return await hook(ctx, {
+    request: emptyPullRequest,
+    response,
+  });
+}
+
+async function callBeforeApplyWsChanges(
+  plugin: ReturnType<typeof createYjsClientPlugin>,
+  args: SyncClientWsDeliveryArgs
+): Promise<SyncClientWsDeliveryArgs> {
+  const hook = plugin.beforeApplyWsChanges;
+  if (!hook) {
+    throw new Error('Expected beforeApplyWsChanges hook');
+  }
+  return await hook(ctx, args);
+}
+
+async function callBeforeApplyLocalMutations(
+  plugin: ReturnType<typeof createYjsClientPlugin>,
+  args: SyncClientLocalMutationArgs
+): Promise<SyncClientLocalMutationArgs> {
+  const hook = plugin.beforeApplyLocalMutations;
+  if (!hook) {
+    throw new Error('Expected beforeApplyLocalMutations hook');
+  }
+  return await hook(ctx, args);
+}
+
+function createUpdate(
+  text: string,
+  previousStateBase64?: string
+): { update: YjsClientUpdateEnvelope; state: string } {
+  const built = buildYjsTextUpdate({
+    previousStateBase64,
+    nextText: text,
+    containerKey: 'content',
+  });
+  return { update: built.update, state: built.nextStateBase64 };
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64');
+}
+
+function createXmlState(text: string): string {
+  const doc = new Y.Doc();
+  const fragment = doc.getXmlFragment('content');
+  doc.transact(() => {
+    const paragraph = new Y.XmlElement('p');
+    const xmlText = new Y.XmlText();
+    xmlText.insert(0, text);
+    paragraph.insert(0, [xmlText]);
+    fragment.insert(0, [paragraph]);
+  });
+  const state = bytesToBase64(Y.encodeStateAsUpdate(doc));
+  doc.destroy();
+  return state;
+}
+
+describe('@syncular/client-plugin-crdt-yjs', () => {
+  it('merges concurrent prepend and append updates without text duplication', () => {
+    const base = buildYjsTextUpdate({
+      nextText: '123',
+      containerKey: 'content',
+    });
+    const prepend = buildYjsTextUpdate({
+      previousStateBase64: base.nextStateBase64,
+      nextText: '0123',
+      containerKey: 'content',
+    });
+    const append = buildYjsTextUpdate({
+      previousStateBase64: base.nextStateBase64,
+      nextText: '1234',
+      containerKey: 'content',
+    });
+
+    const mergedForward = applyYjsTextUpdates({
+      previousStateBase64: base.nextStateBase64,
+      updates: [prepend.update, append.update],
+      containerKey: 'content',
+    });
+    const mergedReverse = applyYjsTextUpdates({
+      previousStateBase64: base.nextStateBase64,
+      updates: [append.update, prepend.update],
+      containerKey: 'content',
+    });
+
+    expect(mergedForward.text).toBe('01234');
+    expect(mergedReverse.text).toBe('01234');
+  });
+
+  it('materializes outgoing payload from Yjs envelope updates and strips envelope key', async () => {
+    const plugin = createYjsClientPlugin({
+      rules: [
+        {
+          table: 'tasks',
+          field: 'content',
+          stateColumn: 'content_yjs_state',
+        },
+      ],
+    });
+
+    const { update } = createUpdate('Hello Yjs');
+    const request: SyncPushRequest = {
+      clientId: 'client-1',
+      clientCommitId: 'commit-1',
+      schemaVersion: 1,
+      operations: [
+        {
+          table: 'tasks',
+          row_id: 'task-1',
+          op: 'upsert',
+          payload: {
+            [YJS_PAYLOAD_KEY]: {
+              content: update,
+            },
+          },
+          base_version: null,
+        },
+      ],
+    };
+
+    const next = await callBeforePush(plugin, request);
+    const op = next.operations[0];
+    if (!op || op.op !== 'upsert' || !op.payload) {
+      throw new Error('Expected transformed upsert payload');
+    }
+
+    expect(op.payload.content).toBe('Hello Yjs');
+    expect(typeof op.payload.content_yjs_state).toBe('string');
+    expect(YJS_PAYLOAD_KEY in op.payload).toBe(false);
+  });
+
+  it('can keep envelope key on push while still materializing payload', async () => {
+    const plugin = createYjsClientPlugin({
+      rules: [
+        {
+          table: 'tasks',
+          field: 'content',
+          stateColumn: 'content_yjs_state',
+        },
+      ],
+      stripEnvelopeBeforePush: false,
+      stripEnvelopeBeforeApplyLocalMutations: true,
+    });
+
+    const { update } = createUpdate('Hello merge');
+    const request: SyncPushRequest = {
+      clientId: 'client-1',
+      clientCommitId: 'commit-keep-envelope',
+      schemaVersion: 1,
+      operations: [
+        {
+          table: 'tasks',
+          row_id: 'task-1',
+          op: 'upsert',
+          payload: {
+            [YJS_PAYLOAD_KEY]: {
+              content: update,
+            },
+          },
+          base_version: null,
+        },
+      ],
+    };
+
+    const pushed = await callBeforePush(plugin, request);
+    const pushedPayload = pushed.operations[0]?.payload as
+      | Record<string, unknown>
+      | undefined;
+    if (!pushedPayload) {
+      throw new Error('Expected transformed push payload');
+    }
+    expect(pushedPayload.content).toBe('Hello merge');
+    expect(typeof pushedPayload.content_yjs_state).toBe('string');
+    expect(YJS_PAYLOAD_KEY in pushedPayload).toBe(true);
+
+    const local = await callBeforeApplyLocalMutations(plugin, {
+      operations: request.operations,
+    });
+    const localPayload = local.operations[0]?.payload as
+      | Record<string, unknown>
+      | undefined;
+    if (!localPayload) {
+      throw new Error('Expected transformed local payload');
+    }
+    expect(localPayload.content).toBe('Hello merge');
+    expect(typeof localPayload.content_yjs_state).toBe('string');
+    expect(YJS_PAYLOAD_KEY in localPayload).toBe(false);
+  });
+
+  it('uses cached row state from pull to apply future delta-only updates', async () => {
+    const plugin = createYjsClientPlugin({
+      rules: [
+        {
+          table: 'tasks',
+          field: 'content',
+          stateColumn: 'content_yjs_state',
+        },
+      ],
+    });
+
+    const first = createUpdate('Hello');
+    const second = createUpdate('Hello world', first.state);
+
+    const pulled = await callAfterPull(plugin, {
+      ok: true,
+      subscriptions: [
+        {
+          id: 'tasks',
+          status: 'active',
+          scopes: {},
+          bootstrap: true,
+          nextCursor: 1,
+          bootstrapState: null,
+          commits: [],
+          snapshots: [
+            {
+              table: 'tasks',
+              rows: [
+                {
+                  id: 'task-1',
+                  content: 'stale',
+                  content_yjs_state: first.state,
+                  [YJS_PAYLOAD_KEY]: {
+                    should_be_removed: true,
+                  },
+                },
+              ],
+              isFirstPage: true,
+              isLastPage: true,
+            },
+          ],
+        },
+      ],
+    });
+
+    const snapshotRow = pulled.subscriptions[0]?.snapshots?.[0]?.rows?.[0] as
+      | Record<string, unknown>
+      | undefined;
+    if (!snapshotRow) {
+      throw new Error('Expected transformed snapshot row');
+    }
+    expect(snapshotRow.content).toBe('Hello');
+    expect(YJS_PAYLOAD_KEY in snapshotRow).toBe(false);
+
+    const request: SyncPushRequest = {
+      clientId: 'client-1',
+      clientCommitId: 'commit-2',
+      schemaVersion: 1,
+      operations: [
+        {
+          table: 'tasks',
+          row_id: 'task-1',
+          op: 'upsert',
+          payload: {
+            [YJS_PAYLOAD_KEY]: {
+              content: second.update,
+            },
+          },
+          base_version: 1,
+        },
+      ],
+    };
+
+    const next = await callBeforePush(plugin, request);
+    const payload = next.operations[0]?.payload as Record<string, unknown>;
+    expect(payload.content).toBe('Hello world');
+    expect(typeof payload.content_yjs_state).toBe('string');
+  });
+
+  it('materializes websocket inline changes through beforeApplyWsChanges', async () => {
+    const plugin = createYjsClientPlugin({
+      rules: [
+        {
+          table: 'tasks',
+          field: 'content',
+          stateColumn: 'content_yjs_state',
+        },
+      ],
+    });
+
+    const first = createUpdate('Live update');
+    const next = await callBeforeApplyWsChanges(plugin, {
+      cursor: 10,
+      changes: [
+        {
+          table: 'tasks',
+          row_id: 'task-1',
+          op: 'upsert',
+          row_json: {
+            id: 'task-1',
+            content: 'stale',
+            content_yjs_state: first.state,
+            [YJS_PAYLOAD_KEY]: {
+              should_be_removed: true,
+            },
+          },
+          row_version: 2,
+          scopes: {},
+        },
+      ],
+    });
+
+    const row = next.changes[0]?.row_json as
+      | Record<string, unknown>
+      | undefined;
+    if (!row) {
+      throw new Error('Expected transformed row_json');
+    }
+    expect(row.content).toBe('Live update');
+    expect(YJS_PAYLOAD_KEY in row).toBe(false);
+  });
+
+  it('materializes local mutation payloads through beforeApplyLocalMutations', async () => {
+    const plugin = createYjsClientPlugin({
+      rules: [
+        {
+          table: 'tasks',
+          field: 'content',
+          stateColumn: 'content_yjs_state',
+        },
+      ],
+    });
+
+    const { update } = createUpdate('Local update');
+    const next = await callBeforeApplyLocalMutations(plugin, {
+      operations: [
+        {
+          table: 'tasks',
+          row_id: 'task-1',
+          op: 'upsert',
+          payload: {
+            [YJS_PAYLOAD_KEY]: {
+              content: update,
+            },
+          },
+          base_version: null,
+        },
+      ],
+    });
+
+    const payload = next.operations[0]?.payload as
+      | Record<string, unknown>
+      | null
+      | undefined;
+    if (!payload) {
+      throw new Error('Expected transformed local payload');
+    }
+    expect(payload.content).toBe('Local update');
+    expect(typeof payload.content_yjs_state).toBe('string');
+    expect(YJS_PAYLOAD_KEY in payload).toBe(false);
+  });
+
+  it('materializes rows when state is delivered as UTF-8 bytes of base64 text', async () => {
+    const plugin = createYjsClientPlugin({
+      rules: [
+        {
+          table: 'tasks',
+          field: 'content',
+          stateColumn: 'content_yjs_state',
+        },
+      ],
+    });
+
+    const first = createUpdate('Bytes snapshot');
+    const next = await callAfterPull(plugin, {
+      ok: true,
+      subscriptions: [
+        {
+          id: 'tasks',
+          status: 'active',
+          scopes: {},
+          bootstrap: true,
+          nextCursor: 1,
+          bootstrapState: null,
+          commits: [],
+          snapshots: [
+            {
+              table: 'tasks',
+              rows: [
+                {
+                  id: 'task-1',
+                  content: 'stale',
+                  content_yjs_state: new TextEncoder().encode(first.state),
+                },
+              ],
+              isFirstPage: true,
+              isLastPage: true,
+            },
+          ],
+        },
+      ],
+    });
+
+    const row = next.subscriptions[0]?.snapshots?.[0]?.rows?.[0] as
+      | Record<string, unknown>
+      | undefined;
+    if (!row) {
+      throw new Error('Expected transformed snapshot row');
+    }
+    expect(row.content).toBe('Bytes snapshot');
+  });
+
+  it('materializes xml-fragment kind rows during pull', async () => {
+    const plugin = createYjsClientPlugin({
+      rules: [
+        {
+          table: 'tasks',
+          field: 'content',
+          stateColumn: 'content_yjs_state',
+          kind: 'xml-fragment',
+        },
+      ],
+    });
+
+    const xmlState = createXmlState('Hello XML');
+    const next = await callAfterPull(plugin, {
+      ok: true,
+      subscriptions: [
+        {
+          id: 'tasks',
+          status: 'active',
+          scopes: {},
+          bootstrap: true,
+          nextCursor: 1,
+          bootstrapState: null,
+          commits: [],
+          snapshots: [
+            {
+              table: 'tasks',
+              rows: [
+                {
+                  id: 'task-1',
+                  content: 'stale',
+                  content_yjs_state: xmlState,
+                },
+              ],
+              isFirstPage: true,
+              isLastPage: true,
+            },
+          ],
+        },
+      ],
+    });
+
+    const row = next.subscriptions[0]?.snapshots?.[0]?.rows?.[0] as
+      | Record<string, unknown>
+      | undefined;
+    if (!row) {
+      throw new Error('Expected transformed snapshot row');
+    }
+    expect(typeof row.content).toBe('string');
+    expect(String(row.content)).toContain('Hello XML');
+  });
+
+  it('throws when strict mode is enabled and envelope references unknown fields', async () => {
+    const plugin = createYjsClientPlugin({
+      rules: [
+        {
+          table: 'tasks',
+          field: 'content',
+          stateColumn: 'content_yjs_state',
+        },
+      ],
+      strict: true,
+    });
+
+    const { update } = createUpdate('Hello');
+    const request: SyncPushRequest = {
+      clientId: 'client-1',
+      clientCommitId: 'commit-3',
+      schemaVersion: 1,
+      operations: [
+        {
+          table: 'tasks',
+          row_id: 'task-1',
+          op: 'upsert',
+          payload: {
+            [YJS_PAYLOAD_KEY]: {
+              unknown_field: update,
+            },
+          },
+          base_version: 1,
+        },
+      ],
+    };
+
+    await expect(callBeforePush(plugin, request)).rejects.toThrow(
+      'No Yjs rule found for envelope field "unknown_field"'
+    );
+  });
+});

package/src/index.ts

@@ -0,0 +1,784 @@
+import {
+  PluginPriority,
+  type SyncChange,
+  type SyncClientLocalMutationArgs,
+  type SyncClientPlugin,
+  type SyncClientWsDeliveryArgs,
+  type SyncPullResponse,
+  type SyncPullSubscriptionResponse,
+  type SyncPushRequest,
+} from '@syncular/client';
+import * as Y from 'yjs';
+
+export const YJS_PAYLOAD_KEY = '__yjs';
+
+const BASE64_PATTERN =
+  /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+
+export type YjsFieldKind = 'text' | 'xml-fragment' | 'prosemirror';
+
+export interface YjsClientFieldRule {
+  table: string;
+  field: string;
+  /**
+   * Column that stores canonical serialized Yjs state.
+   * Example: "content_yjs_state"
+   */
+  stateColumn: string;
+  /**
+   * Container key inside the Yjs document. Defaults to `field`.
+   */
+  containerKey?: string;
+  /**
+   * Snapshot row id column. Defaults to `id`.
+   */
+  rowIdField?: string;
+  /**
+   * CRDT container type.
+   */
+  kind?: YjsFieldKind;
+}
+
+interface ResolvedYjsClientFieldRule extends YjsClientFieldRule {
+  containerKey: string;
+  rowIdField: string;
+  kind: YjsFieldKind;
+}
+
+export interface YjsClientUpdateEnvelope {
+  updateId: string;
+  updateBase64: string;
+}
+
+export type YjsClientUpdateInput =
+  | YjsClientUpdateEnvelope
+  | readonly YjsClientUpdateEnvelope[];
+
+export interface YjsClientPayloadEnvelope {
+  [field: string]: YjsClientUpdateInput;
+}
+
+export interface BuildYjsTextUpdateArgs {
+  previousStateBase64?: string | Uint8Array | null;
+  nextText: string;
+  containerKey?: string;
+  updateId?: string;
+}
+
+export interface BuildYjsTextUpdateResult {
+  update: YjsClientUpdateEnvelope;
+  nextStateBase64: string;
+  nextText: string;
+}
+
+export interface ApplyYjsTextUpdatesArgs {
+  previousStateBase64?: string | Uint8Array | null;
+  updates: readonly YjsClientUpdateEnvelope[];
+  containerKey?: string;
+}
+
+export interface ApplyYjsTextUpdatesResult {
+  nextStateBase64: string;
+  text: string;
+}
+
+export interface CreateYjsClientPluginOptions {
+  name?: string;
+  rules: readonly YjsClientFieldRule[];
+  envelopeKey?: string;
+  priority?: number;
+  /**
+   * Throw when envelope payload references fields without matching rules.
+   * @default true
+   */
+  strict?: boolean;
+  /**
+   * Remove the Yjs envelope key from outgoing/incoming records.
+   * @default true
+   */
+  stripEnvelope?: boolean;
+  /**
+   * Remove the Yjs envelope key from push payloads.
+   * Default inherits from `stripEnvelope`.
+   */
+  stripEnvelopeBeforePush?: boolean;
+  /**
+   * Remove the Yjs envelope key from local optimistic mutation payloads.
+   * Default inherits from `stripEnvelope`.
+   */
+  stripEnvelopeBeforeApplyLocalMutations?: boolean;
+}
+
+type RuleIndex = Map<string, Map<string, ResolvedYjsClientFieldRule>>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64');
+  }
+
+  let binary = '';
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+function tryReadBase64TextFromBytes(bytes: Uint8Array): string | null {
+  if (bytes.length === 0) return null;
+  try {
+    const decoded = new TextDecoder().decode(bytes).trim();
+    if (!decoded || !BASE64_PATTERN.test(decoded)) return null;
+    return decoded;
+  } catch {
+    return null;
+  }
+}
+
+function base64ToBytes(base64: string): Uint8Array {
+  if (!BASE64_PATTERN.test(base64)) {
+    throw new Error('Invalid base64 string');
+  }
+
+  if (typeof Buffer !== 'undefined') {
+    return new Uint8Array(Buffer.from(base64, 'base64'));
+  }
+
+  const binary = atob(base64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    out[i] = binary.charCodeAt(i);
+  }
+  return out;
+}
+
+function stateValueToBytes(value: unknown): Uint8Array | null {
+  if (value instanceof Uint8Array) {
+    const encoded = tryReadBase64TextFromBytes(value);
+    if (encoded) return base64ToBytes(encoded);
+    return value;
+  }
+  const str = readString(value);
+  if (!str) return null;
+  return base64ToBytes(str);
+}
+
+function stateValueToBase64(value: unknown): string | null {
+  const str = readString(value);
+  if (str) return str;
+  if (value instanceof Uint8Array) {
+    const encoded = tryReadBase64TextFromBytes(value);
+    if (encoded) return encoded;
+    return bytesToBase64(value);
+  }
+  return null;
+}
+
+function createDocFromState(stateValue: unknown): Y.Doc {
+  const doc = new Y.Doc();
+  const bytes = stateValueToBytes(stateValue);
+  if (bytes && bytes.length > 0) {
+    Y.applyUpdate(doc, bytes);
+  }
+  return doc;
+}
+
+function exportSnapshotBase64(doc: Y.Doc): string {
+  return bytesToBase64(Y.encodeStateAsUpdate(doc));
+}
+
+function replaceText(doc: Y.Doc, containerKey: string, nextText: string): void {
+  const text = doc.getText(containerKey);
+  const currentLength = text.length;
+  doc.transact(() => {
+    if (currentLength > 0) {
+      text.delete(0, currentLength);
+    }
+    if (nextText.length > 0) {
+      text.insert(0, nextText);
+    }
+  });
+}
+
+function patchText(doc: Y.Doc, containerKey: string, nextText: string): void {
+  const text = doc.getText(containerKey);
+  const currentText = text.toString();
+  if (currentText === nextText) return;
+
+  const minLength = Math.min(currentText.length, nextText.length);
+  let prefixLength = 0;
+  while (
+    prefixLength < minLength &&
+    currentText.charCodeAt(prefixLength) === nextText.charCodeAt(prefixLength)
+  ) {
+    prefixLength += 1;
+  }
+
+  let currentSuffixStart = currentText.length;
+  let nextSuffixStart = nextText.length;
+  while (
+    currentSuffixStart > prefixLength &&
+    nextSuffixStart > prefixLength &&
+    currentText.charCodeAt(currentSuffixStart - 1) ===
+      nextText.charCodeAt(nextSuffixStart - 1)
+  ) {
+    currentSuffixStart -= 1;
+    nextSuffixStart -= 1;
+  }
+
+  const deleteLength = currentSuffixStart - prefixLength;
+  const insertSegment = nextText.slice(prefixLength, nextSuffixStart);
+
+  doc.transact(() => {
+    if (deleteLength > 0) {
+      text.delete(prefixLength, deleteLength);
+    }
+    if (insertSegment.length > 0) {
+      text.insert(prefixLength, insertSegment);
+    }
+  });
+}
+
+function ensureTextContainer(doc: Y.Doc, containerKey: string): string {
+  return doc.getText(containerKey).toString();
+}
+
+function ensureXmlFragmentContainer(doc: Y.Doc, containerKey: string): string {
+  return doc.getXmlFragment(containerKey).toString();
+}
+
+function materializeRuleValue(
+  doc: Y.Doc,
+  rule: ResolvedYjsClientFieldRule
+): unknown {
+  if (rule.kind === 'text') {
+    return ensureTextContainer(doc, rule.containerKey);
+  }
+  return ensureXmlFragmentContainer(doc, rule.containerKey);
+}
+
+function seedRuleValueFromPayload(
+  doc: Y.Doc,
+  rule: ResolvedYjsClientFieldRule,
+  source: Record<string, unknown>
+): void {
+  if (rule.kind !== 'text') return;
+  const initialText = readString(source[rule.field]);
+  if (initialText) {
+    replaceText(doc, rule.containerKey, initialText);
+  }
+}
+
+function buildRuleIndex(rules: readonly YjsClientFieldRule[]): {
+  index: RuleIndex;
+  normalizedRules: readonly ResolvedYjsClientFieldRule[];
+} {
+  const index: RuleIndex = new Map();
+  const normalizedRules: ResolvedYjsClientFieldRule[] = [];
+  const seen = new Set<string>();
+
+  for (const rule of rules) {
+    if (!rule.table.trim()) {
+      throw new Error('YjsClientFieldRule.table cannot be empty');
+    }
+    if (!rule.field.trim()) {
+      throw new Error('YjsClientFieldRule.field cannot be empty');
+    }
+    if (!rule.stateColumn.trim()) {
+      throw new Error('YjsClientFieldRule.stateColumn cannot be empty');
+    }
+
+    const key = `${rule.table}\u001f${rule.field}`;
+    if (seen.has(key)) {
+      throw new Error(
+        `Duplicate Yjs client rule for table "${rule.table}", field "${rule.field}"`
+      );
+    }
+    seen.add(key);
+
+    const resolved: ResolvedYjsClientFieldRule = {
+      ...rule,
+      containerKey: rule.containerKey ?? rule.field,
+      rowIdField: rule.rowIdField ?? 'id',
+      kind: rule.kind ?? 'text',
+    };
+    normalizedRules.push(resolved);
+
+    const tableRules = index.get(resolved.table) ?? new Map();
+    tableRules.set(resolved.field, resolved);
+    index.set(resolved.table, tableRules);
+  }
+
+  return { index, normalizedRules };
+}
+
+function rowFieldCacheKey(table: string, rowId: string, field: string): string {
+  return `${table}\u001f${rowId}\u001f${field}`;
+}
+
+function resolveSnapshotRowId(
+  row: Record<string, unknown>,
+  rule: ResolvedYjsClientFieldRule
+): string | null {
+  const candidate = row[rule.rowIdField];
+  return typeof candidate === 'string' && candidate.length > 0
+    ? candidate
+    : null;
+}
+
+function normalizeUpdateEnvelope(
+  value: unknown,
+  context: string
+): YjsClientUpdateEnvelope {
+  if (!isRecord(value)) {
+    throw new Error(`${context} must be an object`);
+  }
+  const updateId = readString(value.updateId);
+  const updateBase64 = readString(value.updateBase64);
+  if (!updateId) {
+    throw new Error(`${context}.updateId must be a non-empty string`);
+  }
+  if (!updateBase64) {
+    throw new Error(
+      `${context}.updateBase64 must be a non-empty base64 string`
+    );
+  }
+  return { updateId, updateBase64 };
+}
+
+function normalizeUpdateEnvelopes(
+  value: unknown,
+  context: string
+): YjsClientUpdateEnvelope[] {
+  if (Array.isArray(value)) {
+    return value.map((entry, i) =>
+      normalizeUpdateEnvelope(entry, `${context}[${i}]`)
+    );
+  }
+  return [normalizeUpdateEnvelope(value, context)];
+}
+
+function createUpdateId(): string {
+  const randomUUID = globalThis.crypto?.randomUUID;
+  if (typeof randomUUID === 'function') {
+    return randomUUID.call(globalThis.crypto);
+  }
+  const ts = Date.now().toString(36);
+  const rnd = Math.random().toString(36).slice(2, 12);
+  return `yjs-${ts}-${rnd}`;
+}
+
+export function applyYjsTextUpdates(
+  args: ApplyYjsTextUpdatesArgs
+): ApplyYjsTextUpdatesResult {
+  const containerKey = args.containerKey ?? 'text';
+  const doc = createDocFromState(args.previousStateBase64);
+  try {
+    for (const update of args.updates) {
+      Y.applyUpdate(doc, base64ToBytes(update.updateBase64));
+    }
+    const text = ensureTextContainer(doc, containerKey);
+    const nextStateBase64 = exportSnapshotBase64(doc);
+    return { nextStateBase64, text };
+  } finally {
+    doc.destroy();
+  }
+}
+
+export function buildYjsTextUpdate(
+  args: BuildYjsTextUpdateArgs
+): BuildYjsTextUpdateResult {
+  const containerKey = args.containerKey ?? 'text';
+  const doc = createDocFromState(args.previousStateBase64);
+  try {
+    const from = Y.encodeStateVector(doc);
+    patchText(doc, containerKey, args.nextText);
+    const update = bytesToBase64(Y.encodeStateAsUpdate(doc, from));
+    const nextText = ensureTextContainer(doc, containerKey);
+    const nextStateBase64 = exportSnapshotBase64(doc);
+
+    return {
+      update: {
+        updateId: args.updateId ?? createUpdateId(),
+        updateBase64: update,
+      },
+      nextStateBase64,
+      nextText,
+    };
+  } finally {
+    doc.destroy();
+  }
+}
+
+function materializeRowFromState(args: {
+  table: string;
+  rowId: string | null;
+  row: Record<string, unknown>;
+  index: RuleIndex;
+  stateByRowField: Map<string, string>;
+  envelopeKey: string;
+  stripEnvelope: boolean;
+}): Record<string, unknown> {
+  const tableRules = args.index.get(args.table);
+  if (!tableRules) {
+    if (args.stripEnvelope && args.envelopeKey in args.row) {
+      const next = { ...args.row };
+      delete next[args.envelopeKey];
+      return next;
+    }
+    return args.row;
+  }
+
+  let nextRow: Record<string, unknown> | null = null;
+  const ensureRow = (): Record<string, unknown> => {
+    if (nextRow) return nextRow;
+    nextRow = { ...args.row };
+    return nextRow;
+  };
+
+  for (const rule of tableRules.values()) {
+    const source = nextRow ?? args.row;
+    const stateBase64 = stateValueToBase64(source[rule.stateColumn]);
+    if (!stateBase64) continue;
+
+    const doc = createDocFromState(stateBase64);
+    try {
+      const nextValue = materializeRuleValue(doc, rule);
+      if (source[rule.field] !== nextValue) {
+        ensureRow()[rule.field] = nextValue;
+      }
+      if (args.rowId) {
+        args.stateByRowField.set(
+          rowFieldCacheKey(args.table, args.rowId, rule.field),
+          stateBase64
+        );
+      }
+    } finally {
+      doc.destroy();
+    }
+  }
+
+  if (args.stripEnvelope) {
+    const source = nextRow ?? args.row;
+    if (args.envelopeKey in source) {
+      const target = ensureRow();
+      delete target[args.envelopeKey];
+    }
+  }
+
+  return nextRow ?? args.row;
+}
+
+function transformPushPayload(args: {
+  table: string;
+  rowId: string;
+  payload: Record<string, unknown>;
+  index: RuleIndex;
+  stateByRowField: Map<string, string>;
+  envelopeKey: string;
+  stripEnvelope: boolean;
+  strict: boolean;
+}): Record<string, unknown> {
+  const tableRules = args.index.get(args.table);
+  const rawEnvelope = args.payload[args.envelopeKey];
+
+  if (!tableRules) {
+    if (rawEnvelope !== undefined && args.strict) {
+      throw new Error(
+        `Yjs envelope provided for table "${args.table}" without matching rules`
+      );
+    }
+    if (args.stripEnvelope && rawEnvelope !== undefined) {
+      const next = { ...args.payload };
+      delete next[args.envelopeKey];
+      return next;
+    }
+    return args.payload;
+  }
+
+  let nextPayload: Record<string, unknown> | null = null;
+  const ensurePayload = (): Record<string, unknown> => {
+    if (nextPayload) return nextPayload;
+    nextPayload = { ...args.payload };
+    return nextPayload;
+  };
+
+  const sourceEnvelope = rawEnvelope;
+  if (sourceEnvelope !== undefined && !isRecord(sourceEnvelope)) {
+    throw new Error(
+      `Yjs payload key "${args.envelopeKey}" must be an object for table "${args.table}"`
+    );
+  }
+
+  for (const rule of tableRules.values()) {
+    const source = nextPayload ?? args.payload;
+    const stateBase64 = stateValueToBase64(source[rule.stateColumn]);
+    if (stateBase64) {
+      args.stateByRowField.set(
+        rowFieldCacheKey(args.table, args.rowId, rule.field),
+        stateBase64
+      );
+    }
+  }
+
+  if (sourceEnvelope) {
+    for (const [field, rawUpdateInput] of Object.entries(sourceEnvelope)) {
+      const rule = tableRules.get(field);
+      if (!rule) {
+        if (args.strict) {
+          throw new Error(
+            `No Yjs rule found for envelope field "${field}" on table "${args.table}"`
+          );
+        }
+        continue;
+      }
+
+      const updates = normalizeUpdateEnvelopes(
+        rawUpdateInput,
+        `yjs.${args.table}.${field}`
+      );
+      const cacheKey = rowFieldCacheKey(args.table, args.rowId, rule.field);
+      const source = nextPayload ?? args.payload;
+      const baseState =
+        stateValueToBase64(source[rule.stateColumn]) ??
+        args.stateByRowField.get(cacheKey) ??
+        null;
+
+      const doc = createDocFromState(baseState);
+      try {
+        if (!baseState) {
+          seedRuleValueFromPayload(doc, rule, source);
+        }
+
+        for (const update of updates) {
+          Y.applyUpdate(doc, base64ToBytes(update.updateBase64));
+        }
+
+        const nextValue = materializeRuleValue(doc, rule);
+        const nextStateBase64 = exportSnapshotBase64(doc);
+        const target = ensurePayload();
+        target[rule.field] = nextValue;
+        target[rule.stateColumn] = nextStateBase64;
+        args.stateByRowField.set(cacheKey, nextStateBase64);
+      } finally {
+        doc.destroy();
+      }
+    }
+  }
+
+  if (args.stripEnvelope) {
+    const source = nextPayload ?? args.payload;
+    if (args.envelopeKey in source) {
+      const target = ensurePayload();
+      delete target[args.envelopeKey];
+    }
+  }
+
+  return nextPayload ?? args.payload;
+}
+
+function transformPullSubscription(args: {
+  sub: SyncPullSubscriptionResponse;
+  index: RuleIndex;
+  stateByRowField: Map<string, string>;
+  envelopeKey: string;
+  stripEnvelope: boolean;
+}): SyncPullSubscriptionResponse {
+  const nextSnapshots = (args.sub.snapshots ?? []).map((snapshot) => ({
+    ...snapshot,
+    rows: (snapshot.rows ?? []).map((row) => {
+      if (!isRecord(row)) return row;
+      const tableRules = args.index.get(snapshot.table);
+      if (!tableRules) {
+        return materializeRowFromState({
+          table: snapshot.table,
+          rowId: null,
+          row,
+          index: args.index,
+          stateByRowField: args.stateByRowField,
+          envelopeKey: args.envelopeKey,
+          stripEnvelope: args.stripEnvelope,
+        });
+      }
+
+      let rowId: string | null = null;
+      for (const rule of tableRules.values()) {
+        rowId = resolveSnapshotRowId(row, rule);
+        if (rowId) break;
+      }
+
+      return materializeRowFromState({
+        table: snapshot.table,
+        rowId,
+        row,
+        index: args.index,
+        stateByRowField: args.stateByRowField,
+        envelopeKey: args.envelopeKey,
+        stripEnvelope: args.stripEnvelope,
+      });
+    }),
+  }));
+
+  const nextCommits = (args.sub.commits ?? []).map((commit) => ({
+    ...commit,
+    changes: (commit.changes ?? []).map((change) => {
+      if (change.op !== 'upsert' || !isRecord(change.row_json)) return change;
+      const nextRow = materializeRowFromState({
+        table: change.table,
+        rowId: change.row_id,
+        row: change.row_json,
+        index: args.index,
+        stateByRowField: args.stateByRowField,
+        envelopeKey: args.envelopeKey,
+        stripEnvelope: args.stripEnvelope,
+      });
+      if (nextRow === change.row_json) return change;
+      return { ...change, row_json: nextRow };
+    }),
+  }));
+
+  return {
+    ...args.sub,
+    snapshots: nextSnapshots,
+    commits: nextCommits,
+  };
+}
+
+function transformWsChanges(args: {
+  changes: SyncChange[];
+  index: RuleIndex;
+  stateByRowField: Map<string, string>;
+  envelopeKey: string;
+  stripEnvelope: boolean;
+}): SyncChange[] {
+  return args.changes.map((change) => {
+    if (change.op !== 'upsert' || !isRecord(change.row_json)) return change;
+    const nextRow = materializeRowFromState({
+      table: change.table,
+      rowId: change.row_id,
+      row: change.row_json,
+      index: args.index,
+      stateByRowField: args.stateByRowField,
+      envelopeKey: args.envelopeKey,
+      stripEnvelope: args.stripEnvelope,
+    });
+    if (nextRow === change.row_json) return change;
+    return { ...change, row_json: nextRow };
+  });
+}
+
+export function createYjsClientPlugin(
+  options: CreateYjsClientPluginOptions
+): SyncClientPlugin {
+  if (options.rules.length === 0) {
+    throw new Error(
+      'createYjsClientPlugin requires at least one table/field rule'
+    );
+  }
+
+  const envelopeKey = options.envelopeKey ?? YJS_PAYLOAD_KEY;
+  const strict = options.strict ?? true;
+  const stripEnvelope = options.stripEnvelope ?? true;
+  const stripEnvelopeBeforePush =
+    options.stripEnvelopeBeforePush ?? stripEnvelope;
+  const stripEnvelopeBeforeApplyLocalMutations =
+    options.stripEnvelopeBeforeApplyLocalMutations ?? stripEnvelope;
+  const { index } = buildRuleIndex(options.rules);
+  const stateByRowField = new Map<string, string>();
+
+  return {
+    name: options.name ?? 'crdt-yjs-client',
+    priority: options.priority ?? PluginPriority.DEFAULT,
+
+    beforePush(_ctx, request): SyncPushRequest {
+      const nextOperations = request.operations.map((op) => {
+        if (op.op !== 'upsert') return op;
+        if (!isRecord(op.payload)) return op;
+
+        const nextPayload = transformPushPayload({
+          table: op.table,
+          rowId: op.row_id,
+          payload: op.payload,
+          index,
+          stateByRowField,
+          envelopeKey,
+          stripEnvelope: stripEnvelopeBeforePush,
+          strict,
+        });
+
+        if (nextPayload === op.payload) return op;
+        return { ...op, payload: nextPayload };
+      });
+
+      return { ...request, operations: nextOperations };
+    },
+
+    beforeApplyLocalMutations(
+      _ctx,
+      args: SyncClientLocalMutationArgs
+    ): SyncClientLocalMutationArgs {
+      const nextOperations = args.operations.map((op) => {
+        if (op.op !== 'upsert') return op;
+        if (!isRecord(op.payload)) return op;
+
+        const nextPayload = transformPushPayload({
+          table: op.table,
+          rowId: op.row_id,
+          payload: op.payload,
+          index,
+          stateByRowField,
+          envelopeKey,
+          stripEnvelope: stripEnvelopeBeforeApplyLocalMutations,
+          strict,
+        });
+
+        if (nextPayload === op.payload) return op;
+        return { ...op, payload: nextPayload };
+      });
+
+      return { ...args, operations: nextOperations };
+    },
+
+    afterPull(_ctx, args: { response: SyncPullResponse }): SyncPullResponse {
+      const nextSubscriptions = args.response.subscriptions.map((sub) =>
+        transformPullSubscription({
+          sub,
+          index,
+          stateByRowField,
+          envelopeKey,
+          stripEnvelope,
+        })
+      );
+
+      return {
+        ...args.response,
+        subscriptions: nextSubscriptions,
+      };
+    },
+
+    beforeApplyWsChanges(
+      _ctx,
+      args: SyncClientWsDeliveryArgs
+    ): SyncClientWsDeliveryArgs {
+      const nextChanges = transformWsChanges({
+        changes: args.changes,
+        index,
+        stateByRowField,
+        envelopeKey,
+        stripEnvelope,
+      });
+
+      return {
+        ...args,
+        changes: nextChanges,
+      };
+    },
+  };
+}