@trestleinc/replicate 0.1.0 → 1.1.0

package/README.md

@@ -1,14 +1,13 @@
-# Convex Replicate
+# Replicate
 
 **Offline-first sync library using Yjs CRDTs and Convex for real-time data synchronization.**
 
-Convex Replicate provides a dual-storage architecture for building offline-capable applications with automatic conflict resolution. It combines Yjs CRDTs (96% smaller than Automerge, no WASM) with TanStack's offline transaction system and Convex's reactive backend for real-time synchronization and efficient querying.
+Replicate provides a dual-storage architecture for building offline-capable applications with automatic conflict resolution. It combines Yjs CRDTs (96% smaller than Automerge, no WASM) with TanStack DB's reactive state management and Convex's reactive backend for real-time synchronization and efficient querying.
 
 ## Features
 
 - **Offline-first** - Works without internet, syncs when reconnected
 - **Yjs CRDTs** - Automatic conflict-free replication with Yjs (96% smaller than Automerge, no WASM)
-- **TanStack offline-transactions** - Proven outbox pattern for reliable offline sync
 - **Real-time sync** - Convex WebSocket-based synchronization
 - **TanStack DB integration** - Reactive state management for React and Svelte
 - **Dual-storage pattern** - CRDT layer for conflict resolution + main tables for queries
@@ -18,7 +17,10 @@ Convex Replicate provides a dual-storage architecture for building offline-capab
 - **SSR support** - Server-side rendering with data preloading
 - **Network resilience** - Automatic retry with exponential backoff
 - **Component-based** - Convex component for plug-and-play CRDT storage
-- **React Native compatible** - No WASM dependency, works on mobile
+- **Swappable persistence** - IndexedDB (browser), SQLite (React Native), or in-memory (testing)
+- **React Native compatible** - SQLite persistence with y-op-sqlite and op-sqlite
+- **Version history** - Create, list, restore, and delete document versions
+- **Auto-compaction** - Size-based per-document compaction (no cron jobs needed)
 
 ## Architecture
 
@@ -42,7 +44,7 @@ sequenceDiagram
 
     Note over Offline: Automatic retry with backoff
     Offline->>Yjs: Get CRDT delta
-    Offline->>Convex: insertDocument/updateDocument mutation
+    Offline->>Convex: insert/update mutation
     Convex->>Component: Append delta to event log
     Convex->>Table: Insert/Update materialized doc
 
@@ -59,7 +61,7 @@ graph LR
     Component[Component Storage<br/>Event Log<br/>CRDT Deltas]
     MainTable[Main Application Table<br/>Materialized Docs<br/>Efficient Queries]
 
-    Client -->|insertDocument/updateDocument| Component
+    Client -->|insert/update/remove| Component
     Component -->|also writes to| MainTable
     MainTable -->|subscription| Client
 ```
@@ -72,14 +74,14 @@ graph LR
 ## Installation
 
 ```bash
-# Using pnpm (recommended)
+# Using bun (recommended)
+bun add @trestleinc/replicate
+
+# Using pnpm
 pnpm add @trestleinc/replicate
 
 # Using npm (v7+)
 npm install @trestleinc/replicate
-
-# Using Bun
-bun add @trestleinc/replicate
 ```
 
 ## Quick Start
@@ -101,31 +103,31 @@ export default app;
 
 ### Step 2: Define Your Schema
 
-Use the `replicatedTable` helper to automatically inject required fields:
+Use the `schema.table()` helper to automatically inject required fields:
 
 ```typescript
 // convex/schema.ts
 import { defineSchema } from 'convex/server';
 import { v } from 'convex/values';
-import { replicatedTable } from '@trestleinc/replicate/server';
+import { schema } from '@trestleinc/replicate/server';
 
 export default defineSchema({
-  tasks: replicatedTable(
+  tasks: schema.table(
     {
       // Your application fields only!
-      // version and timestamp are automatically injected by replicatedTable
+      // version and timestamp are automatically injected by schema.table()
       id: v.string(),
       text: v.string(),
       isCompleted: v.boolean(),
     },
-    (table) => table
+    (t) => t
       .index('by_user_id', ['id'])      // Required for document lookups
       .index('by_timestamp', ['timestamp']) // Required for incremental sync
   ),
 });
 ```
 
-**What `replicatedTable` does:**
+**What `schema.table()` does:**
 - Automatically injects `version: v.number()` (for CRDT versioning)
 - Automatically injects `timestamp: v.number()` (for incremental sync)
 - You only define your business logic fields
@@ -136,88 +138,37 @@ export default defineSchema({
 
 ### Step 3: Create Replication Functions
 
-Create functions that use replication helpers for dual-storage pattern:
+Use `replicate()` to bind your component and create collection functions:
 
 ```typescript
 // convex/tasks.ts
-import { mutation, query } from './_generated/server';
+import { replicate } from '@trestleinc/replicate/server';
 import { components } from './_generated/api';
-import { v } from 'convex/values';
-import {
-  insertDocumentHelper,
-  updateDocumentHelper,
-  deleteDocumentHelper,
-} from '@trestleinc/replicate/server'; // IMPORTANT: Use /server for Convex functions!
-
-/**
- * TanStack DB endpoints - called by convexCollectionOptions
- * These receive Yjs CRDT deltas from client and write to both:
- * 1. Component storage (Yjs CRDT deltas in event log)
- * 2. Main table (materialized docs for efficient queries)
- */
-
-export const insertDocument = mutation({
-  args: {
-    collectionName: v.string(),
-    documentId: v.string(),
-    crdtBytes: v.bytes(),
-    materializedDoc: v.any(),
-    version: v.number(),
-  },
-  handler: async (ctx, args) => {
-    return await insertDocumentHelper(ctx, components, 'tasks', {
-      id: args.documentId,
-      crdtBytes: args.crdtBytes,
-      materializedDoc: args.materializedDoc,
-      version: args.version,
-    });
-  },
-});
-
-export const updateDocument = mutation({
-  args: {
-    collectionName: v.string(),
-    documentId: v.string(),
-    crdtBytes: v.bytes(),
-    materializedDoc: v.any(),
-    version: v.number(),
-  },
-  handler: async (ctx, args) => {
-    return await updateDocumentHelper(ctx, components, 'tasks', {
-      id: args.documentId,
-      crdtBytes: args.crdtBytes,
-      materializedDoc: args.materializedDoc,
-      version: args.version,
-    });
-  },
+import type { Task } from '../src/useTasks';
+
+const r = replicate(components.replicate);
+
+export const {
+  stream,
+  material,
+  insert,
+  update,
+  remove,
+  versions
+} = r<Task>({
+  collection: 'tasks',
+  compaction: { threshold: 5_000_000 },  // Optional: size threshold for auto-compaction (default: 5MB)
 });
+```
 
-export const deleteDocument = mutation({
-  args: {
-    collectionName: v.string(),
-    documentId: v.string(),
-    crdtBytes: v.bytes(),
-    version: v.number(),
-  },
-  handler: async (ctx, args) => {
-    return await deleteDocumentHelper(ctx, components, 'tasks', {
-      id: args.documentId,
-      crdtBytes: args.crdtBytes,
-      version: args.version,
-    });
-  },
-});
+**What `replicate()` generates:**
 
-/**
- * Stream endpoint for real-time subscriptions
- * Returns all active items (hard deletes are physically removed from table)
- */
-export const stream = query({
-  handler: async (ctx) => {
-    return await ctx.db.query('tasks').collect();
-  },
-});
-```
+- `stream` - Real-time CRDT stream query (for client subscriptions)
+- `material` - SSR-friendly query (for server-side rendering)
+- `insert` - Dual-storage insert mutation (auto-compacts when threshold exceeded)
+- `update` - Dual-storage update mutation (auto-compacts when threshold exceeded)
+- `remove` - Dual-storage delete mutation (auto-compacts when threshold exceeded)
+- `versions` - Version history APIs (create, list, get, restore, remove)
 
 ### Step 4: Create a Custom Hook
 
@@ -226,11 +177,7 @@ Create a hook that wraps TanStack DB with Convex collection options:
 ```typescript
 // src/useTasks.ts
 import { createCollection } from '@tanstack/react-db';
-import {
-  convexCollectionOptions,
-  createConvexCollection,
-  type ConvexCollection,
-} from '@trestleinc/replicate/client';
+import { convexCollectionOptions } from '@trestleinc/replicate/client';
 import { api } from '../convex/_generated/api';
 import { convexClient } from './router';
 import { useMemo } from 'react';
@@ -243,30 +190,22 @@ export interface Task {
 
 // Module-level singleton to prevent multiple collection instances
 // This ensures only one sync process runs, even across component remounts
-let tasksCollection: ConvexCollection<Task>;
+let tasksCollection: ReturnType<typeof createCollection<Task>>;
 
-export function useTasks(initialData?: ReadonlyArray<Task>) {
+export function useTasks(
+  initialData?: { documents: Task[], checkpoint?: any, count?: number, crdtBytes?: Uint8Array }
+) {
   return useMemo(() => {
     if (!tasksCollection) {
-      // Step 1: Create raw TanStack DB collection with ALL config
-      const rawCollection = createCollection(
+      tasksCollection = createCollection(
         convexCollectionOptions<Task>({
           convexClient,
-          api: {
-            stream: api.tasks.stream,
-            insertDocument: api.tasks.insertDocument,
-            updateDocument: api.tasks.updateDocument,
-            deleteDocument: api.tasks.deleteDocument,
-          },
-          collectionName: 'tasks',
+          api: api.tasks,
+          collection: 'tasks',
           getKey: (task) => task.id,
-          initialData,
+          material: initialData,
         })
       );
-
-      // Step 2: Wrap with Convex offline support (Yjs + TanStack)
-      // Config is automatically extracted from rawCollection
-      tasksCollection = createConvexCollection(rawCollection);
     }
     return tasksCollection;
   }, [initialData]);
@@ -331,9 +270,54 @@ export function TaskList() {
 }
 ```
 
-## Delete Pattern: Hard Delete with Event History (v0.3.0+)
+### Step 6: Server-Side Rendering (Recommended)
+
+For frameworks that support SSR (TanStack Start, Next.js, Remix, SvelteKit), preloading data on the server is the recommended approach for instant page loads and better SEO.
+
+**Why SSR is recommended:**
+- **Instant page loads** - No loading spinners on first render
+- **Better SEO** - Content visible to search engines
+- **Reduced client work** - Data already available on hydration
+- **Seamless transition** - Real-time sync takes over after hydration
 
-Convex Replicate uses **hard deletes** where items are physically removed from the main table, while the internal component preserves complete event history.
+**Step 1: Use the `material` query from replicate()**
+
+The `material` query is automatically generated by `replicate()` and returns all documents for SSR hydration.
+
+**Step 2: Load data in your route loader**
+
+```typescript
+// src/routes/index.tsx
+import { createFileRoute } from '@tanstack/react-router';
+import { ConvexHttpClient } from 'convex/browser';
+import { api } from '../convex/_generated/api';
+import type { Task } from '../useTasks';
+
+const httpClient = new ConvexHttpClient(import.meta.env.VITE_CONVEX_URL);
+
+export const Route = createFileRoute('/')({
+  loader: async () => {
+    const tasks = await httpClient.query(api.tasks.material);
+    return { tasks };
+  },
+});
+
+function TasksPage() {
+  const { tasks: initialTasks } = Route.useLoaderData();
+
+  // Pass initialData to your hook - no loading state on first render!
+  const collection = useTasks(initialTasks);
+  const { data: tasks } = useLiveQuery(collection);
+
+  return <TaskList tasks={tasks} />;
+}
+```
+
+**Note:** If your framework doesn't support SSR, the collection works just fine without `initialData` - it will fetch data on mount and show a loading state.
+
+## Delete Pattern: Hard Delete with Event History
+
+Replicate uses **hard deletes** where items are physically removed from the main table, while the internal component preserves complete event history.
 
 **Why hard delete?**
 - Clean main table (no filtering required)
@@ -356,7 +340,7 @@ const { data: tasks } = useLiveQuery(collection);
 // SSR loader - no filtering needed!
 export const Route = createFileRoute('/')({
   loader: async () => {
-    const tasks = await httpClient.query(api.tasks.stream);
+    const tasks = await httpClient.query(api.tasks.material);
     return { tasks };
   },
 });
@@ -364,142 +348,178 @@ export const Route = createFileRoute('/')({
 
 **How it works:**
 1. Client calls `collection.delete(id)`
-2. `onDelete` handler captures Yjs deletion delta
+2. `onRemove` handler captures Yjs deletion delta
 3. Delta appended to component event log (history preserved)
 4. Main table: document physically removed
 5. Other clients notified and item removed locally
 
-**Server-side:** Returns only active items (deleted items are physically removed):
+## Advanced Usage
+
+### Custom Hooks and Lifecycle Events
+
+You can customize the behavior of generated functions using optional hooks:
 
 ```typescript
 // convex/tasks.ts
-export const stream = query({
-  handler: async (ctx) => {
-    return await ctx.db.query('tasks').collect();
-  },
+import { replicate } from '@trestleinc/replicate/server';
+import { components } from './_generated/api';
+import type { Task } from '../src/useTasks';
+
+const r = replicate(components.replicate);
+
+export const {
+  stream,
+  material,
+  insert,
+  update,
+  remove,
+  versions
+} = r<Task>({
+  collection: 'tasks',
+
+  // Optional hooks for authorization and lifecycle events
+  hooks: {
+    // Permission checks (eval* hooks validate BEFORE execution, throw to deny)
+    evalRead: async (ctx, collection) => {
+      const userId = await ctx.auth.getUserIdentity();
+      if (!userId) throw new Error('Unauthorized');
+    },
+    evalWrite: async (ctx, doc) => {
+      const userId = await ctx.auth.getUserIdentity();
+      if (!userId) throw new Error('Unauthorized');
+    },
+    evalRemove: async (ctx, documentId) => {
+      const userId = await ctx.auth.getUserIdentity();
+      if (!userId) throw new Error('Unauthorized');
+    },
+    evalVersion: async (ctx, collection, documentId) => { /* auth for versioning */ },
+    evalRestore: async (ctx, collection, documentId, versionId) => { /* auth for restore */ },
+
+    // Lifecycle callbacks (on* hooks run AFTER execution)
+    onStream: async (ctx, result) => { /* after stream query */ },
+    onInsert: async (ctx, doc) => { /* after insert */ },
+    onUpdate: async (ctx, doc) => { /* after update */ },
+    onRemove: async (ctx, documentId) => { /* after remove */ },
+    onVersion: async (ctx, result) => { /* after version created */ },
+    onRestore: async (ctx, result) => { /* after restore */ },
+
+    // Transform hook (modify documents before returning)
+    transform: async (docs) => docs.filter(d => d.isPublic),
+  }
 });
 ```
 
-**Dual Storage Architecture:**
-- **Component Storage**: Append-only event log with complete history (including deletions)
-- **Main Table**: Current state only (deleted items removed)
+### Rich Text / Prose Fields
 
-## Advanced Usage
+For collaborative rich text editing, use the `schema.prose()` validator and `prose.extract()` function:
 
-### Server-Side Rendering (SSR)
+```typescript
+// convex/schema.ts
+import { schema } from '@trestleinc/replicate/server';
 
-Preload data on the server for instant page loads:
+export default defineSchema({
+  notebooks: schema.table({
+    id: v.string(),
+    title: v.string(),
+    content: schema.prose(),  // ProseMirror-compatible JSON
+  }),
+});
 
-**Step 1: Create an SSR-friendly query**
+// Client: Extract plain text for search
+import { prose } from '@trestleinc/replicate/client';
 
-```typescript
-// convex/tasks.ts
-export const getTasks = query({
-  handler: async (ctx) => {
-    return await ctx.db.query('tasks').collect();
-  },
-});
+const plainText = prose.extract(notebook.content);
+
+// Client: Get editor binding for ProseMirror/TipTap
+const binding = await collection.utils.prose(notebookId, 'content');
 ```
 
-**Step 2: Load data in your route loader**
+### Version History
+
+Create and manage document version history:
 
 ```typescript
-// src/routes/index.tsx
-import { createFileRoute } from '@tanstack/react-router';
-import { ConvexHttpClient } from 'convex/browser';
-import { api } from '../convex/_generated/api';
-import type { Task } from '../useTasks';
+// convex/tasks.ts
+export const { versions } = replicate<Task>({
+  collection: 'tasks',
+});
 
-const httpClient = new ConvexHttpClient(import.meta.env.VITE_CONVEX_URL);
+// Create a version
+await ctx.runMutation(api.tasks.versions.create, {
+  documentId: 'task-123',
+  label: 'Before major edit',
+  createdBy: 'user-456',
+});
 
-export const Route = createFileRoute('/')({
-  loader: async () => {
-    const tasks = await httpClient.query(api.tasks.getTasks);
-    return { tasks };
-  },
+// List versions
+const versionList = await ctx.runQuery(api.tasks.versions.list, {
+  documentId: 'task-123',
+  limit: 10,
 });
 
-function TasksPage() {
-  const { tasks: initialTasks } = Route.useLoaderData();
+// Get a specific version
+const version = await ctx.runQuery(api.tasks.versions.get, {
+  versionId: 'version-789',
+});
 
-  // Pass initialData to your hook
-  const collection = useTasks(initialTasks);
-  const { data: tasks } = useLiveQuery(collection);
+// Restore a version
+await ctx.runMutation(api.tasks.versions.restore, {
+  documentId: 'task-123',
+  versionId: 'version-789',
+  createBackup: true,  // Optional: create backup before restore
+});
 
-  // No loading state on first render!
-  return <TaskList tasks={tasks} />;
-}
+// Delete a version
+await ctx.runMutation(api.tasks.versions.remove, {
+  versionId: 'version-789',
+});
 ```
 
-### Direct Component Usage (Advanced)
-
-> **WARNING:** Using `ReplicateStorage` directly only writes to the component CRDT storage layer. It does NOT implement the dual-storage pattern (no writes to main table), which means:
-> - You cannot query this data efficiently in Convex
-> - You lose the benefits of reactive subscriptions on materialized docs
-> - You'll need to manually handle materialization
-> 
-> **Recommended:** Use the replication helpers (`insertDocumentHelper`, etc.) shown in Step 3 for the full dual-storage pattern.
+### Persistence Providers
 
-For advanced use cases where you need direct component access:
+Choose the right storage backend for your platform:
 
 ```typescript
-// convex/tasks.ts
-import { ReplicateStorage } from '@trestleinc/replicate/client';
-import { mutation, query } from './_generated/server';
-import { components } from './_generated/api';
-import { v } from 'convex/values';
-
-interface Task {
-  id: string;
-  text: string;
-  isCompleted: boolean;
-}
+import { persistence, adapters } from '@trestleinc/replicate/client';
 
-const tasksStorage = new ReplicateStorage<Task>(components.replicate, 'tasks');
+// Browser: IndexedDB (default, no config needed)
+convexCollectionOptions<Task>({
+  // ... other options
+  persistence: persistence.indexeddb(),
+});
 
-export const insertTask = mutation({
-  args: {
-    id: v.string(),
-    crdtBytes: v.bytes(),
-    version: v.number(),
-  },
-  handler: async (ctx, args) => {
-    return await tasksStorage.insertDocument(
-      ctx,
-      args.id,
-      args.crdtBytes,
-      args.version
-    );
-  },
+// Browser SQLite: Uses sql.js WASM with OPFS persistence
+// You initialize sql.js and pass the SQL object
+import initSqlJs from 'sql.js';
+const SQL = await initSqlJs({ locateFile: (file) => `/${file}` });
+convexCollectionOptions<Task>({
+  // ... other options
+  persistence: await persistence.sqlite.browser(SQL, 'my-app-db'),
 });
 
-export const updateTask = mutation({
-  args: {
-    id: v.string(),
-    crdtBytes: v.bytes(),
-    version: v.number(),
-  },
-  handler: async (ctx, args) => {
-    return await tasksStorage.updateDocument(
-      ctx,
-      args.id,
-      args.crdtBytes,
-      args.version
-    );
-  },
+// React Native SQLite: Uses op-sqlite (native SQLite)
+import { open } from '@op-engineering/op-sqlite';
+const db = open({ name: 'my-app-db' });
+convexCollectionOptions<Task>({
+  // ... other options
+  persistence: await persistence.sqlite.native(db, 'my-app-db'),
 });
 
-export const streamChanges = query({
-  args: {
-    checkpoint: v.object({ lastModified: v.number() }),
-    limit: v.optional(v.number()),
-  },
-  handler: async (ctx, args) => {
-    return await tasksStorage.stream(ctx, args.checkpoint, args.limit);
-  },
+// Testing: In-memory (no persistence)
+convexCollectionOptions<Task>({
+  // ... other options
+  persistence: persistence.memory(),
 });
 ```
 
+**IndexedDB** (default) - Uses y-indexeddb for Y.Doc persistence and browser-level for metadata. Browser only.
+
+**SQLite Browser** - Uses sql.js (SQLite compiled to WASM) with OPFS persistence. You initialize sql.js yourself and pass the SQL object.
+
+**SQLite Native** - Uses op-sqlite for React Native. You create the database and pass it.
+
+**Memory** - No persistence, useful for testing without IndexedDB side effects.
+
 ### Logging Configuration
 
 Configure logging for debugging and development using LogTape:
@@ -520,18 +540,6 @@ await configure({
 });
 ```
 
-Get a logger instance for custom logging:
-
-```typescript
-import { getLogger } from '@trestleinc/replicate/client';
-
-const logger = getLogger(['my-module']); // Accepts string or string array
-
-logger.info('Operation started', { userId: '123' });
-logger.warn('Something unexpected', { reason: 'timeout' });
-logger.error('Operation failed', { error });
-```
-
 ## API Reference
 
 ### Client-Side (`@trestleinc/replicate/client`)
@@ -545,14 +553,17 @@ Creates collection options for TanStack DB with Yjs CRDT integration.
 interface ConvexCollectionOptionsConfig<T> {
   convexClient: ConvexClient;
   api: {
-    stream: FunctionReference;          // Real-time subscription endpoint
-    insertDocument: FunctionReference;  // Insert mutation
-    updateDocument: FunctionReference;  // Update mutation
-    deleteDocument: FunctionReference;  // Delete mutation
+    stream: FunctionReference;    // Real-time subscription endpoint
+    insert: FunctionReference;    // Insert mutation
+    update: FunctionReference;    // Update mutation
+    remove: FunctionReference;    // Delete mutation
   };
-  collectionName: string;
+  collection: string;
   getKey: (item: T) => string | number;
-  initialData?: ReadonlyArray<T>;
+  persistence?: Persistence;      // Optional: defaults to indexeddbPersistence()
+  material?: Materialized<T>;     // SSR hydration data
+  prose?: Array<keyof T>;         // Optional: prose fields for rich text
+  undoCaptureTimeout?: number;    // Undo stack merge window (default: 500ms)
 }
 ```
 
@@ -560,177 +571,137 @@ interface ConvexCollectionOptionsConfig<T> {
 
 **Example:**
 ```typescript
-const rawCollection = createCollection(
+const collection = createCollection(
   convexCollectionOptions<Task>({
     convexClient,
-    api: {
-      stream: api.tasks.stream,
-      insertDocument: api.tasks.insertDocument,
-      updateDocument: api.tasks.updateDocument,
-      deleteDocument: api.tasks.deleteDocument,
-    },
-    collectionName: 'tasks',
+    api: api.tasks,
+    collection: 'tasks',
     getKey: (task) => task.id,
-    initialData,
+    material: initialData,
   })
 );
-
-const collection = createConvexCollection(rawCollection);
 ```
 
-#### `createConvexCollection<T>(rawCollection)`
+#### `prose.extract(proseJson)`
 
-Wraps a TanStack DB collection with offline support (Yjs + TanStack offline-transactions).
+Extract plain text from ProseMirror JSON.
 
 **Parameters:**
-- `rawCollection` - Collection created with `createCollection(convexCollectionOptions(...))`
+- `proseJson` - ProseMirror JSON structure (XmlFragmentJSON)
 
-**Returns:** `ConvexCollection<T>` (just a type alias for `Collection<T>`)
+**Returns:** `string` - Plain text content
 
 **Example:**
 ```typescript
-const collection = createConvexCollection(rawCollection);
+import { prose } from '@trestleinc/replicate/client';
 
-// Use standard TanStack DB operations
-collection.insert({ id: '1', text: 'Task 1', isCompleted: false });
-collection.update('1', (draft) => { draft.isCompleted = true });
-collection.delete('1');
+const plainText = prose.extract(task.content);
 ```
 
-#### `ReplicateStorage<TDocument>`
-
-Type-safe API for direct component access (advanced).
+#### Persistence Providers
 
-**Constructor:**
 ```typescript
-new ReplicateStorage<TDocument>(component, collectionName)
-```
-
-**Methods:**
-
-##### `insertDocument(ctx, documentId, crdtBytes, version)`
-Insert a new document with Yjs CRDT bytes.
-
-**Parameters:**
-- `ctx` - Convex mutation context
-- `documentId` - Unique document identifier
-- `crdtBytes` - ArrayBuffer containing Yjs CRDT bytes
-- `version` - CRDT version number
-
-**Returns:** `Promise<{ success: boolean }>`
-
-##### `updateDocument(ctx, documentId, crdtBytes, version)`
-Update an existing document with Yjs CRDT bytes.
-
-**Parameters:**
-- `ctx` - Convex mutation context
-- `documentId` - Unique document identifier
-- `crdtBytes` - ArrayBuffer containing Yjs CRDT bytes
-- `version` - CRDT version number
-
-**Returns:** `Promise<{ success: boolean }>`
-
-##### `deleteDocument(ctx, documentId, crdtBytes, version)`
-Delete a document (appends deletion delta to event log).
-
-**Parameters:**
-- `ctx` - Convex mutation context
-- `documentId` - Unique document identifier
-- `crdtBytes` - ArrayBuffer containing Yjs deletion delta
-- `version` - CRDT version number
-
-**Returns:** `Promise<{ success: boolean }>`
-
-##### `stream(ctx, checkpoint, limit?)`
-Pull document changes for incremental sync.
+import { persistence, adapters } from '@trestleinc/replicate/client';
 
-**Parameters:**
-- `ctx` - Convex query context
-- `checkpoint` - Object with `{ lastModified: number }`
-- `limit` - Optional max changes (default: 100)
+// Persistence providers
+persistence.indexeddb()           // Browser: IndexedDB (default)
+persistence.sqlite.browser(SQL, name)  // Browser: sql.js WASM + OPFS
+persistence.sqlite.native(db, name)    // React Native: op-sqlite
+persistence.memory()              // Testing: in-memory (no persistence)
 
-**Returns:**
-```typescript
-Promise<{
-  changes: Array<{
-    documentId: string;
-    crdtBytes: ArrayBuffer;
-    version: number;
-    timestamp: number;
-  }>;
-  checkpoint: { lastModified: number };
-  hasMore: boolean;
-}>
+// SQLite adapters (for advanced use)
+adapters.sqljs    // SqlJsAdapter class for browser
+adapters.opsqlite // OPSqliteAdapter class for React Native
 ```
 
-#### `getLogger(category)`
+**`persistence.indexeddb()`** - Browser-only, uses y-indexeddb + browser-level.
 
-Get a logger instance for custom logging.
+**`persistence.sqlite.browser(SQL, name)`** - Browser SQLite using sql.js WASM. You initialize sql.js and pass the SQL object.
 
-**Parameters:**
-- `category: string | string[]` - Logger category
+**`persistence.sqlite.native(db, name)`** - React Native SQLite using op-sqlite. You create the database and pass it.
 
-**Returns:** Logger with `debug()`, `info()`, `warn()`, `error()` methods
+**`persistence.memory()`** - In-memory, no persistence. Useful for testing.
 
-**Examples:**
-```typescript
-const logger = getLogger('my-module');
-const logger = getLogger(['hooks', 'useTasks']);
+#### Error Classes
 
-logger.debug('Task created', { id: taskId });
+```typescript
+import { errors } from '@trestleinc/replicate/client';
+
+errors.Network           // Network-related failures
+errors.IDB               // IndexedDB read errors
+errors.IDBWrite          // IndexedDB write errors
+errors.Reconciliation    // Phantom document cleanup errors
+errors.Prose             // Rich text field errors
+errors.CollectionNotReady// Collection not initialized
+errors.NonRetriable      // Errors that should not be retried (auth, validation)
 ```
 
 ### Server-Side (`@trestleinc/replicate/server`)
 
-#### `insertDocumentHelper(ctx, components, tableName, args)`
-
-Insert a document into both the CRDT component and the main application table.
-
-**Parameters:**
-- `ctx` - Convex mutation context
-- `components` - Generated components from Convex
-- `tableName` - Name of the main application table
-- `args` - `{ id: string; crdtBytes: ArrayBuffer; materializedDoc: any; version: number }`
-
-**Returns:** `Promise<{ success: boolean; metadata: {...} }>`
+#### `replicate(component)`
 
-#### `updateDocumentHelper(ctx, components, tableName, args)`
-
-Update a document in both the CRDT component and the main application table.
+Factory function that creates a bound replicate function for your collections.
 
 **Parameters:**
-- `ctx` - Convex mutation context
-- `components` - Generated components from Convex
-- `tableName` - Name of the main application table
-- `args` - `{ id: string; crdtBytes: ArrayBuffer; materializedDoc: any; version: number }`
+- `component` - Your Convex component reference (`components.replicate`)
 
-**Returns:** `Promise<{ success: boolean; metadata: {...} }>`
+**Returns:** A function `<T>(config: ReplicateConfig<T>)` that generates collection operations.
 
-#### `deleteDocumentHelper(ctx, components, tableName, args)`
+**Example:**
+```typescript
+import { replicate } from '@trestleinc/replicate/server';
+import { components } from './_generated/api';
 
-Hard delete from main table, append deletion delta to component event log.
+const r = replicate(components.replicate);
+export const tasks = r<Task>({ collection: 'tasks' });
+```
 
-**Parameters:**
-- `ctx` - Convex mutation context
-- `components` - Generated components from Convex
-- `tableName` - Name of the main application table
-- `args` - `{ id: string; crdtBytes: ArrayBuffer; version: number }`
+#### `ReplicateConfig<T>`
 
-**Returns:** `Promise<{ success: boolean; metadata: {...} }>`
+Configuration for the bound replicate function.
 
-#### `streamHelper(ctx, components, tableName, args)`
+**Config:**
+```typescript
+interface ReplicateConfig<T> {
+  collection: string;          // Collection name (e.g., 'tasks')
 
-Stream CRDT deltas from component storage for incremental sync.
+  // Optional: Auto-compaction settings
+  compaction?: {
+    threshold?: number;        // Size threshold in bytes (default: 5MB / 5_000_000)
+  };
 
-**Parameters:**
-- `ctx` - Convex query context
-- `components` - Generated components from Convex
-- `tableName` - Name of the collection
-- `args` - `{ checkpoint: { lastModified: number }; limit?: number }`
+  // Optional: Hooks for permissions and lifecycle
+  hooks?: {
+    // Permission checks (throw to reject)
+    evalRead?: (ctx, collection) => Promise<void>;
+    evalWrite?: (ctx, doc) => Promise<void>;
+    evalRemove?: (ctx, documentId) => Promise<void>;
+    evalVersion?: (ctx, collection, documentId) => Promise<void>;
+    evalRestore?: (ctx, collection, documentId, versionId) => Promise<void>;
+
+    // Lifecycle callbacks (run after operation)
+    onStream?: (ctx, result) => Promise<void>;
+    onInsert?: (ctx, doc) => Promise<void>;
+    onUpdate?: (ctx, doc) => Promise<void>;
+    onRemove?: (ctx, documentId) => Promise<void>;
+    onVersion?: (ctx, result) => Promise<void>;
+    onRestore?: (ctx, result) => Promise<void>;
+
+    // Transform hook (modify documents before returning)
+    transform?: (docs) => Promise<T[]>;
+  };
+}
+```
 
-**Returns:** `Promise<{ changes: Array<...>; checkpoint: {...}; hasMore: boolean }>`
+**Returns:** Object with generated functions:
+- `stream` - Real-time CRDT stream query
+- `material` - SSR-friendly query for hydration
+- `insert` - Dual-storage insert mutation (auto-compacts when threshold exceeded)
+- `update` - Dual-storage update mutation (auto-compacts when threshold exceeded)
+- `remove` - Dual-storage delete mutation (auto-compacts when threshold exceeded)
+- `versions` - Version history APIs (create, list, get, restore, remove)
 
-#### `replicatedTable(userFields, applyIndexes?)`
+#### `schema.table(userFields, applyIndexes?)`
 
 Automatically inject replication metadata fields (`version`, `timestamp`).
 
@@ -742,38 +713,37 @@ Automatically inject replication metadata fields (`version`, `timestamp`).
 
 **Example:**
 ```typescript
-tasks: replicatedTable(
+import { schema } from '@trestleinc/replicate/server';
+
+tasks: schema.table(
   {
     id: v.string(),
     text: v.string(),
   },
-  (table) => table
+  (t) => t
     .index('by_user_id', ['id'])
     .index('by_timestamp', ['timestamp'])
 )
 ```
 
-### SSR (`@trestleinc/replicate/ssr`)
-
-#### `loadCollection<T>(httpClient, config)`
+#### `schema.prose()`
 
-Load collection data during SSR for instant page loads.
+Validator for ProseMirror-compatible JSON fields.
 
-**Note:** This function is deprecated. For most SSR use cases, create a dedicated query that reads from your main table.
+**Returns:** Convex validator for prose fields
 
-**Parameters:**
-- `httpClient` - ConvexHttpClient instance
-- `config` - `{ api: CollectionAPI; collection: string; limit?: number }`
-
-**Returns:** `Promise<ReadonlyArray<T>>`
+**Example:**
+```typescript
+content: schema.prose()  // Validates ProseMirror JSON structure
+```
 
 ## Performance
 
 ### Storage Performance
 
-- **IndexedDB** via TanStack DB provides efficient local storage
+- **Swappable persistence** - IndexedDB (browser), SQLite (React Native), or in-memory (testing)
 - **Yjs** CRDT operations are extremely fast (96% smaller than Automerge)
-- **TanStack offline-transactions** provides batching and retry logic
+- **TanStack DB** provides optimistic updates and reactive state management
 - **Indexed queries** in Convex for fast incremental sync
 
 ### Sync Performance
@@ -787,13 +757,13 @@ Load collection data during SSR for instant page loads.
 
 - **TanStack coordination** - Built-in multi-tab sync via BroadcastChannel
 - **Yjs shared state** - Single source of truth per browser
-- **Offline executor** - Only one tab runs sync operations
+- **Leader election** - Only one tab runs sync operations
 
 ## Offline Behavior
 
 ### How It Works
 
-- **Writes** - Queue locally in Yjs CRDT, sync when online via TanStack outbox
+- **Writes** - Queue locally in Yjs CRDT, sync when online
 - **Reads** - Always work from local TanStack DB cache (instant!)
 - **UI** - Fully functional with optimistic updates
 - **Conflicts** - Auto-resolved by Yjs CRDTs (conflict-free!)
@@ -807,63 +777,29 @@ Load collection data during SSR for instant page loads.
 
 ## Examples
 
-Complete working example: `examples/tanstack-start/`
+### Interval - Linear-style Issue Tracker
 
-**Files to explore:**
-- `src/useTasks.ts` - Hook with TanStack DB integration
-- `src/routes/index.tsx` - Component usage with SSR
-- `src/routes/__root.tsx` - Logging configuration
-- `convex/tasks.ts` - Replication functions using dual-storage helpers
-- `convex/schema.ts` - Schema with `replicatedTable` helper
+A full-featured offline-first issue tracker built with Replicate, demonstrating real-world usage patterns.
 
-**Run the example:**
-```bash
-cd examples/tanstack-start
-pnpm install
-pnpm run dev
-```
+🔗 **Live Demo:** [interval.robelest.com](https://interval.robelest.com)
 
-## Development
+📦 **Source Code:** [github.com/robelest/interval](https://github.com/robelest/interval)
 
-### Building
+**Features demonstrated:**
+- Offline-first with SQLite persistence (sql.js + OPFS)
+- Rich text editing with TipTap + Yjs collaboration
+- PWA with custom service worker
+- Real-time sync across devices
+- Search with client-side text extraction (`prose.extract()`)
 
-```bash
-pnpm run build         # Build package using Rslib
-pnpm run clean         # Remove build artifacts
-pnpm run typecheck     # Type check
-```
-
-### Code Quality
-
-```bash
-pnpm run check         # Lint + format check (dry run)
-pnpm run check:fix     # Auto-fix all issues (run before committing)
-pnpm run lint          # Lint only
-pnpm run lint:fix      # Auto-fix lint issues
-pnpm run format        # Format only
-pnpm run format:check  # Check formatting
-```
-
-### Running Example
+## Development
 
 ```bash
-pnpm run dev:example   # Start example app + Convex dev environment
+bun run build         # Build with Rslib (includes ESLint + TypeScript checking)
+bun run dev           # Watch mode
+bun run clean         # Remove build artifacts
 ```
 
-## Roadmap
-
-- [ ] Partial sync (sync subset of collection)
-- [ ] Delta sync (only sync changed fields)
-- [ ] Encryption at rest
-- [ ] Attachment support (files, images)
-- [x] React Native support (works with Yjs v0.3.0+)
-- [ ] Advanced Yjs features (rich text editing, shared cursors)
-- [ ] Recovery features (restore deleted items from event log)
-
-## Contributing
-
-Contributions welcome! Please see `CLAUDE.md` for coding standards.
-
 ## License
 
 Apache-2.0 License - see [LICENSE](./LICENSE) file for details.