@trestleinc/replicate 1.1.0 → 1.1.2-preview.0

package/README.md

@@ -2,74 +2,64 @@
 
 **Offline-first sync library using Yjs CRDTs and Convex for real-time data synchronization.**
 
-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)
-- **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
-- **Event sourcing** - Append-only event log preserves complete history
-- **Type-safe** - Full TypeScript support
-- **Multi-tab sync** - Changes sync instantly across browser tabs via TanStack coordination
-- **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
-- **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)
+Replicate provides a dual-storage architecture for building offline-capable applications with automatic conflict resolution. It combines Yjs CRDTs with TanStack DB's reactive state management and Convex's reactive backend for real-time synchronization and efficient querying.
+
 
 ## Architecture
 
-### Data Flow: Real-Time Sync
+### Data Flow
 
 ```mermaid
 sequenceDiagram
-    participant User
-    participant UI as React/Svelte Component
-    participant TDB as TanStack DB
+    participant UI as React Component
+    participant Collection as TanStack DB Collection
     participant Yjs as Yjs CRDT
-    participant Offline as Offline Executor
-    participant Convex as Convex Component
+    participant Storage as Local Storage<br/>(SQLite)
+    participant Convex as Convex Backend
     participant Table as Main Table
 
-    User->>UI: Create/Update Task
-    UI->>TDB: collection.insert/update
-    TDB->>Yjs: Update Yjs CRDT
-    Yjs-->>TDB: Notify change
-    TDB-->>UI: Re-render (optimistic)
+    Note over UI,Storage: Client-side (offline-capable)
+    UI->>Collection: insert/update/delete
+    Collection->>Yjs: Apply change to Y.Doc
+    Yjs->>Storage: Persist locally
+    Collection-->>UI: Re-render (optimistic)
 
-    Note over Offline: Automatic retry with backoff
-    Offline->>Yjs: Get CRDT delta
-    Offline->>Convex: insert/update mutation
-    Convex->>Component: Append delta to event log
-    Convex->>Table: Insert/Update materialized doc
+    Note over Collection,Convex: Sync layer
+    Collection->>Convex: Send CRDT delta
+    Convex->>Convex: Append to event log
+    Convex->>Table: Update materialized doc
 
-    Note over Convex,Table: Change detected
-    Table-->>UI: Subscription update
-    UI-->>User: Re-render with synced data
+    Note over Convex,UI: Real-time updates
+    Table-->>Collection: stream subscription
+    Collection-->>UI: Re-render with server state
 ```
 
-### Dual-Storage Architecture
+### Dual-Storage Pattern
 
 ```mermaid
-graph LR
-    Client[Client<br/>Yjs CRDT]
-    Component[Component Storage<br/>Event Log<br/>CRDT Deltas]
-    MainTable[Main Application Table<br/>Materialized Docs<br/>Efficient Queries]
-
-    Client -->|insert/update/remove| Component
-    Component -->|also writes to| MainTable
-    MainTable -->|subscription| Client
+graph TB
+    subgraph Client
+        TDB[TanStack DB]
+        Yjs[Yjs CRDT]
+        Local[(SQLite)]
+        TDB <--> Yjs
+        Yjs <--> Local
+    end
+
+    subgraph Convex
+        Component[(Event Log<br/>CRDT Deltas)]
+        Main[(Main Table<br/>Materialized Docs)]
+        Component --> Main
+    end
+
+    Yjs -->|insert/update/remove| Component
+    Main -->|stream subscription| TDB
 ```
 
-**Why both?**
-- **Component Storage (Event Log)**: Append-only CRDT deltas, complete history, conflict resolution
-- **Main Tables (Read Model)**: Current state, efficient server-side queries, indexes, and reactive subscriptions
-- Similar to CQRS/Event Sourcing: component = event log, main table = materialized view
+**Why dual storage?**
+- **Event Log (Component)**: Append-only CRDT deltas for conflict resolution and history
+- **Main Table**: Materialized current state for efficient queries and indexes
+- Similar to CQRS: event log = write model, main table = read model
 
 ## Installation
 
@@ -115,25 +105,24 @@ export default defineSchema({
   tasks: schema.table(
     {
       // Your application fields only!
-      // version and timestamp are automatically injected by schema.table()
+      // timestamp is automatically injected by schema.table()
       id: v.string(),
       text: v.string(),
       isCompleted: v.boolean(),
     },
     (t) => t
-      .index('by_user_id', ['id'])      // Required for document lookups
+      .index('by_doc_id', ['id'])      // Required for document lookups
       .index('by_timestamp', ['timestamp']) // Required for incremental sync
   ),
 });
 ```
 
 **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
 
 **Required indexes:**
-- `by_user_id` on `['id']` - Enables fast document lookups during updates
+- `by_doc_id` on `['id']` - Enables fast document lookups during updates
 - `by_timestamp` on `['timestamp']` - Enables efficient incremental synchronization
 
 ### Step 3: Create Replication Functions
@@ -151,77 +140,97 @@ const r = replicate(components.replicate);
 export const {
   stream,
   material,
+  recovery,
   insert,
   update,
   remove,
-  versions
+  mark,     // Peer sync progress tracking
+  compact,  // Manual compaction trigger
 } = r<Task>({
   collection: 'tasks',
-  compaction: { threshold: 5_000_000 },  // Optional: size threshold for auto-compaction (default: 5MB)
+  compaction: {
+    sizeThreshold: "5mb",  // Type-safe size: "100kb", "5mb", "1gb"
+    peerTimeout: "24h",    // Type-safe duration: "30m", "24h", "7d"
+  },
 });
 ```
 
 **What `replicate()` generates:**
 
-- `stream` - Real-time CRDT stream query (for client subscriptions)
+- `stream` - Real-time CRDT stream query (cursor-based subscriptions with `seq` numbers)
 - `material` - SSR-friendly query (for server-side rendering)
+- `recovery` - State vector sync query (for startup reconciliation)
 - `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)
+- `mark` - Report sync progress to server (peer tracking for safe compaction)
+- `compact` - Manual compaction trigger (peer-aware, respects active peer sync state)
 
-### Step 4: Create a Custom Hook
+### Step 4: Define Your Collection
 
-Create a hook that wraps TanStack DB with Convex collection options:
+Create a collection definition using `collection.create()`. This is SSR-safe because persistence and config are deferred until `init()` is called in the browser:
 
 ```typescript
-// src/useTasks.ts
-import { createCollection } from '@tanstack/react-db';
-import { convexCollectionOptions } from '@trestleinc/replicate/client';
-import { api } from '../convex/_generated/api';
-import { convexClient } from './router';
-import { useMemo } from 'react';
+// src/collections/tasks.ts
+import { collection, persistence } from '@trestleinc/replicate/client';
+import { ConvexClient } from 'convex/browser';
+import { api } from '../../convex/_generated/api';
+import initSqlJs from 'sql.js';
+import { z } from 'zod';
 
-export interface Task {
-  id: string;
-  text: string;
-  isCompleted: boolean;
-}
+// Define your Zod schema (required)
+const taskSchema = z.object({
+  id: z.string(),
+  text: z.string(),
+  isCompleted: z.boolean(),
+});
 
-// Module-level singleton to prevent multiple collection instances
-// This ensures only one sync process runs, even across component remounts
-let tasksCollection: ReturnType<typeof createCollection<Task>>;
-
-export function useTasks(
-  initialData?: { documents: Task[], checkpoint?: any, count?: number, crdtBytes?: Uint8Array }
-) {
-  return useMemo(() => {
-    if (!tasksCollection) {
-      tasksCollection = createCollection(
-        convexCollectionOptions<Task>({
-          convexClient,
-          api: api.tasks,
-          collection: 'tasks',
-          getKey: (task) => task.id,
-          material: initialData,
-        })
-      );
-    }
-    return tasksCollection;
-  }, [initialData]);
-}
+export type Task = z.infer<typeof taskSchema>;
+
+// Create lazy-initialized collection (SSR-safe)
+export const tasks = collection.create({
+  // Async factory - only called in browser during init()
+  persistence: async () => {
+    const SQL = await initSqlJs({ locateFile: (f) => `/${f}` });
+    return persistence.sqlite.browser(SQL, 'tasks');
+  },
+  // Sync factory - only called in browser during init()
+  config: () => ({
+    schema: taskSchema,
+    convexClient: new ConvexClient(import.meta.env.VITE_CONVEX_URL),
+    api: api.tasks,
+    getKey: (task) => task.id,
+  }),
+});
 ```
 
-### Step 5: Use in Components
+**Key points:**
+- `collection.create()` returns a lazy collection that's safe to import during SSR
+- `persistence` and `config` are factory functions, not values - they're only called during `init()`
+- `schema` is required (Zod schema for type inference and prose field detection)
+- Collection name is auto-extracted from `api.tasks` function path
+
+### Step 5: Initialize and Use in Components
+
+Initialize the collection once in your app's entry point (browser only), then use it in components:
 
 ```typescript
-// src/routes/index.tsx
+// src/routes/__root.tsx (or app entry point)
+import { tasks } from '../collections/tasks';
+
+// Initialize once during app startup (browser only)
+// For SSR frameworks, do this in a client-side effect or loader
+await tasks.init();
+```
+
+```typescript
+// src/components/TaskList.tsx
 import { useLiveQuery } from '@tanstack/react-db';
-import { useTasks } from '../useTasks';
+import { tasks, type Task } from '../collections/tasks';
 
 export function TaskList() {
-  const collection = useTasks();
-  const { data: tasks, isLoading, isError } = useLiveQuery(collection);
+  const collection = tasks.get();
+  const { data: taskList, isLoading, isError } = useLiveQuery(collection);
 
   const handleCreate = () => {
     collection.insert({
@@ -254,7 +263,7 @@ export function TaskList() {
     <div>
       <button onClick={handleCreate}>Add Task</button>
 
-      {tasks.map((task) => (
+      {taskList.map((task) => (
         <div key={task.id}>
           <input
             type="checkbox"
@@ -270,9 +279,14 @@ export function TaskList() {
 }
 ```
 
+**Lifecycle:**
+1. `collection.create()` - Define collection (module-level, SSR-safe)
+2. `await tasks.init()` - Initialize persistence and config (browser only, call once)
+3. `tasks.get()` - Get the TanStack DB collection instance (after init)
+
 ### 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.
+For frameworks that support SSR (TanStack Start, Next.js, Remix, SvelteKit), preloading data on the server enables instant page loads.
 
 **Why SSR is recommended:**
 - **Instant page loads** - No loading spinners on first render
@@ -280,40 +294,136 @@ For frameworks that support SSR (TanStack Start, Next.js, Remix, SvelteKit), pre
 - **Reduced client work** - Data already available on hydration
 - **Seamless transition** - Real-time sync takes over after hydration
 
-**Step 1: Use the `material` query from replicate()**
-
-The `material` query is automatically generated by `replicate()` and returns all documents for SSR hydration.
+**Step 1: Prefetch material on the server**
 
-**Step 2: Load data in your route loader**
+Use `ConvexHttpClient` to fetch data during SSR. The `material` query is generated by `replicate()`:
 
 ```typescript
-// src/routes/index.tsx
-import { createFileRoute } from '@tanstack/react-router';
+// TanStack Start: src/routes/__root.tsx
+import { createRootRoute } 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('/')({
+export const Route = createRootRoute({
   loader: async () => {
-    const tasks = await httpClient.query(api.tasks.material);
-    return { tasks };
+    const tasksMaterial = await httpClient.query(api.tasks.material);
+    return { tasksMaterial };
   },
 });
+```
 
-function TasksPage() {
-  const { tasks: initialTasks } = Route.useLoaderData();
+```typescript
+// SvelteKit: src/routes/+layout.server.ts
+import { ConvexHttpClient } from 'convex/browser';
+import { api } from '../convex/_generated/api';
+import { PUBLIC_CONVEX_URL } from '$env/static/public';
 
-  // Pass initialData to your hook - no loading state on first render!
-  const collection = useTasks(initialTasks);
-  const { data: tasks } = useLiveQuery(collection);
+const httpClient = new ConvexHttpClient(PUBLIC_CONVEX_URL);
 
-  return <TaskList tasks={tasks} />;
+export async function load() {
+  const tasksMaterial = await httpClient.query(api.tasks.material);
+  return { tasksMaterial };
 }
 ```
 
-**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.
+**Step 2: Pass material to init() on the client**
+
+```typescript
+// TanStack Start: src/routes/__root.tsx (client component)
+import { tasks } from '../collections/tasks';
+
+function RootComponent() {
+  const { tasksMaterial } = Route.useLoaderData();
+
+  useEffect(() => {
+    // Initialize with SSR data - no loading state!
+    tasks.init(tasksMaterial);
+  }, []);
+
+  return <Outlet />;
+}
+```
+
+```svelte
+<!-- SvelteKit: src/routes/+layout.svelte -->
+<script lang="ts">
+  import { tasks } from '../collections/tasks';
+  import { onMount } from 'svelte';
+
+  export let data; // From +layout.server.ts
+
+  onMount(async () => {
+    await tasks.init(data.tasksMaterial);
+  });
+</script>
+```
+
+**Note:** If your framework doesn't support SSR, just call `await tasks.init()` without arguments - it will fetch data on mount and show a loading state.
+
+## Sync Protocol
+
+Replicate uses cursor-based sync with peer tracking for safe compaction.
+
+### `stream` - Cursor-Based Real-Time Sync
+
+The primary sync mechanism uses monotonically increasing sequence numbers (`seq`):
+
+1. Client subscribes with last known `cursor` (seq number)
+2. Server returns all changes with `seq > cursor`
+3. Client applies changes and updates local cursor
+4. Client calls `mark` to report sync progress to server
+5. Subscription stays open for live updates
+
+This approach enables:
+- **Safe compaction**: Server knows which deltas each peer has synced
+- **Peer tracking**: Active peers are tracked via `mark` calls
+- **No data loss**: Compaction only removes deltas all active peers have received
+
+### `mark` - Peer Sync Tracking
+
+Clients report their sync progress to the server:
+
+```typescript
+// Called automatically after applying changes
+await convexClient.mutation(api.tasks.mark, {
+  peerId: "client-uuid",
+  syncedSeq: 42,  // Last processed seq number
+});
+```
+
+The server tracks:
+- Which peers are actively syncing
+- Each peer's last synced `seq` number
+- Peer timeout for cleanup (configurable via `peerTimeout`)
+
+### `compact` - Peer-Aware Compaction
+
+Compaction is safe because it respects peer sync state:
+
+1. Server checks minimum `syncedSeq` across all active peers
+2. Only deletes deltas where `seq < minSyncedSeq`
+3. Ensures no active peer loses data they haven't synced
+
+**Compaction triggers:**
+- **Automatic**: When document deltas exceed `sizeThreshold`
+- **Manual**: Via `compact` mutation
+
+### `recovery` - State Vector Sync
+
+Used on startup to reconcile client and server state using Yjs state vectors:
+
+1. Client encodes its local Y.Doc state vector (compact representation of what it has)
+2. Server merges all snapshots + deltas into full state
+3. Server computes diff between its state and client's state vector
+4. Server returns only the missing bytes
+5. Client applies the diff to catch up
+
+**When recovery is used:**
+- App startup (before stream subscription begins)
+- After extended offline periods
+- When cursor-based sync can't satisfy the request (deltas compacted)
 
 ## Delete Pattern: Hard Delete with Event History
 
@@ -370,10 +480,12 @@ const r = replicate(components.replicate);
 export const {
   stream,
   material,
+  recovery,
   insert,
   update,
   remove,
-  versions
+  mark,
+  compact,
 } = r<Task>({
   collection: 'tasks',
 
@@ -392,16 +504,22 @@ export const {
       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 */ },
+    evalMark: async (ctx, peerId) => {
+      // Validate peer identity
+      const userId = await ctx.auth.getUserIdentity();
+      if (!userId) throw new Error('Unauthorized');
+    },
+    evalCompact: async (ctx, documentId) => {
+      // Restrict compaction to admin users
+      const userId = await ctx.auth.getUserIdentity();
+      if (!userId) throw new Error('Unauthorized');
+    },
 
     // 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),
@@ -434,91 +552,84 @@ const plainText = prose.extract(notebook.content);
 const binding = await collection.utils.prose(notebookId, 'content');
 ```
 
-### Version History
+### Persistence Providers
 
-Create and manage document version history:
+Choose the right storage backend for your platform. Persistence is configured in the `persistence` factory of `collection.create()`:
 
 ```typescript
-// convex/tasks.ts
-export const { versions } = replicate<Task>({
-  collection: 'tasks',
-});
+import { collection, persistence } from '@trestleinc/replicate/client';
 
-// Create a version
-await ctx.runMutation(api.tasks.versions.create, {
-  documentId: 'task-123',
-  label: 'Before major edit',
-  createdBy: 'user-456',
-});
-
-// List versions
-const versionList = await ctx.runQuery(api.tasks.versions.list, {
-  documentId: 'task-123',
-  limit: 10,
+// Browser SQLite: Uses sql.js WASM with OPFS persistence
+export const tasks = collection.create({
+  persistence: async () => {
+    const initSqlJs = (await import('sql.js')).default;
+    const SQL = await initSqlJs({ locateFile: (f) => `/${f}` });
+    return persistence.sqlite.browser(SQL, 'my-app-db');
+  },
+  config: () => ({ /* ... */ }),
 });
 
-// Get a specific version
-const version = await ctx.runQuery(api.tasks.versions.get, {
-  versionId: 'version-789',
+// React Native SQLite: Uses op-sqlite (native SQLite)
+export const tasks = collection.create({
+  persistence: async () => {
+    const { open } = await import('@op-engineering/op-sqlite');
+    const db = open({ name: 'my-app-db' });
+    return persistence.sqlite.native(db, 'my-app-db');
+  },
+  config: () => ({ /* ... */ }),
 });
 
-// Restore a version
-await ctx.runMutation(api.tasks.versions.restore, {
-  documentId: 'task-123',
-  versionId: 'version-789',
-  createBackup: true,  // Optional: create backup before restore
+// Testing: In-memory (no persistence)
+export const tasks = collection.create({
+  persistence: async () => persistence.memory(),
+  config: () => ({ /* ... */ }),
 });
 
-// Delete a version
-await ctx.runMutation(api.tasks.versions.remove, {
-  versionId: 'version-789',
+// Custom backend: Implement StorageAdapter interface
+export const tasks = collection.create({
+  persistence: async () => persistence.custom(new MyCustomAdapter()),
+  config: () => ({ /* ... */ }),
 });
 ```
 
-### Persistence Providers
+**SQLite Browser** - Uses sql.js (SQLite compiled to WASM) with OPFS persistence. You initialize sql.js yourself and pass the SQL object.
 
-Choose the right storage backend for your platform:
+**SQLite Native** - Uses op-sqlite for React Native. You create the database and pass it.
 
-```typescript
-import { persistence, adapters } from '@trestleinc/replicate/client';
+**Memory** - No persistence, useful for testing.
 
-// Browser: IndexedDB (default, no config needed)
-convexCollectionOptions<Task>({
-  // ... other options
-  persistence: persistence.indexeddb(),
-});
+**Custom** - Implement `StorageAdapter` for any storage backend.
 
-// 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'),
-});
+### Custom Storage Backends
 
-// 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'),
-});
+Implement `StorageAdapter` for custom storage (Chrome extensions, localStorage, cloud storage):
 
-// Testing: In-memory (no persistence)
-convexCollectionOptions<Task>({
-  // ... other options
-  persistence: persistence.memory(),
-});
-```
+```typescript
+import { persistence, type StorageAdapter } from '@trestleinc/replicate/client';
 
-**IndexedDB** (default) - Uses y-indexeddb for Y.Doc persistence and browser-level for metadata. Browser only.
+class ChromeStorageAdapter implements StorageAdapter {
+  async get(key: string): Promise<Uint8Array | undefined> {
+    const result = await chrome.storage.local.get(key);
+    return result[key] ? new Uint8Array(result[key]) : undefined;
+  }
 
-**SQLite Browser** - Uses sql.js (SQLite compiled to WASM) with OPFS persistence. You initialize sql.js yourself and pass the SQL object.
+  async set(key: string, value: Uint8Array): Promise<void> {
+    await chrome.storage.local.set({ [key]: Array.from(value) });
+  }
 
-**SQLite Native** - Uses op-sqlite for React Native. You create the database and pass it.
+  async delete(key: string): Promise<void> {
+    await chrome.storage.local.remove(key);
+  }
+
+  async keys(prefix: string): Promise<string[]> {
+    const all = await chrome.storage.local.get(null);
+    return Object.keys(all).filter(k => k.startsWith(prefix));
+  }
+}
 
-**Memory** - No persistence, useful for testing without IndexedDB side effects.
+// Use custom adapter
+const chromePersistence = persistence.custom(new ChromeStorageAdapter());
+```
 
 ### Logging Configuration
 
@@ -544,42 +655,90 @@ await configure({
 
 ### Client-Side (`@trestleinc/replicate/client`)
 
-#### `convexCollectionOptions<T>(config)`
+#### `collection.create({ persistence, config })`
 
-Creates collection options for TanStack DB with Yjs CRDT integration.
+Creates a lazy-initialized collection with deferred persistence and config resolution. Both `persistence` and `config` are factory functions that are only called when `init()` is invoked (browser-only).
 
-**Config:**
+**Parameters:**
+- `persistence` - Async factory function that returns a `Persistence` instance
+- `config` - Sync factory function that returns the collection config (ConvexClient, schema, api, etc.)
+
+**Returns:** `LazyCollection` with `init(material?)` and `get()` methods
+
+**Example:**
 ```typescript
-interface ConvexCollectionOptionsConfig<T> {
-  convexClient: ConvexClient;
-  api: {
-    stream: FunctionReference;    // Real-time subscription endpoint
+import { collection, persistence } from '@trestleinc/replicate/client';
+import { ConvexClient } from 'convex/browser';
+import initSqlJs from 'sql.js';
+
+export const tasks = collection.create({
+  persistence: async () => {
+    const SQL = await initSqlJs({ locateFile: (f) => `/${f}` });
+    return persistence.sqlite.browser(SQL, 'tasks');
+  },
+  config: () => ({
+    schema: taskSchema,
+    convexClient: new ConvexClient(import.meta.env.VITE_CONVEX_URL),
+    api: api.tasks,
+    getKey: (task) => task.id,
+  }),
+});
+
+// In your app initialization (browser only):
+// Pass SSR-prefetched material for instant hydration
+await tasks.init(material);
+const collection = tasks.get();
+```
+
+**SSR Prefetch (server-side):**
+```typescript
+// SvelteKit: +layout.server.ts
+import { ConvexHttpClient } from 'convex/browser';
+const httpClient = new ConvexHttpClient(PUBLIC_CONVEX_URL);
+
+export async function load() {
+  const material = await httpClient.query(api.tasks.material);
+  return { material };
+}
+```
+
+#### Collection Config Options
+
+The `config` factory in `collection.create()` accepts these options:
+
+```typescript
+interface CollectionConfig<T> {
+  schema: ZodObject;              // Required: Zod schema for type inference
+  getKey: (item: T) => string | number;  // Extract unique key from item
+  convexClient: ConvexClient;     // Convex client instance
+  api: {                          // API from replicate()
+    stream: FunctionReference;    // Real-time subscription
     insert: FunctionReference;    // Insert mutation
     update: FunctionReference;    // Update mutation
     remove: FunctionReference;    // Delete mutation
+    recovery: FunctionReference;  // State vector sync
+    mark: FunctionReference;      // Peer sync tracking
+    compact: FunctionReference;   // Manual compaction
+    material?: FunctionReference; // SSR hydration query
   };
-  collection: string;
-  getKey: (item: T) => string | number;
-  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)
 }
 ```
 
-**Returns:** Collection options for `createCollection()`
-
 **Example:**
 ```typescript
-const collection = createCollection(
-  convexCollectionOptions<Task>({
-    convexClient,
-    api: api.tasks,
-    collection: 'tasks',
+export const tasks = collection.create({
+  persistence: async () => {
+    const SQL = await initSqlJs({ locateFile: (f) => `/${f}` });
+    return persistence.sqlite.browser(SQL, 'tasks');
+  },
+  config: () => ({
+    schema: taskSchema,
     getKey: (task) => task.id,
-    material: initialData,
-  })
-);
+    convexClient: new ConvexClient(import.meta.env.VITE_CONVEX_URL),
+    api: api.tasks,
+  }),
+});
 ```
 
 #### `prose.extract(proseJson)`
@@ -601,35 +760,54 @@ const plainText = prose.extract(task.content);
 #### Persistence Providers
 
 ```typescript
-import { persistence, adapters } from '@trestleinc/replicate/client';
+import { persistence, type StorageAdapter } from '@trestleinc/replicate/client';
 
-// Persistence providers
-persistence.indexeddb()           // Browser: IndexedDB (default)
+// Persistence providers (use in collection.create persistence factory)
 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)
-
-// SQLite adapters (for advanced use)
-adapters.sqljs    // SqlJsAdapter class for browser
-adapters.opsqlite // OPSqliteAdapter class for React Native
+persistence.memory()                   // Testing: in-memory (no persistence)
+persistence.custom(adapter)            // Custom: your StorageAdapter implementation
 ```
 
-**`persistence.indexeddb()`** - Browser-only, uses y-indexeddb + browser-level.
-
 **`persistence.sqlite.browser(SQL, name)`** - Browser SQLite using sql.js WASM. You initialize sql.js and pass the SQL object.
 
 **`persistence.sqlite.native(db, name)`** - React Native SQLite using op-sqlite. You create the database and pass it.
 
 **`persistence.memory()`** - In-memory, no persistence. Useful for testing.
 
+**`persistence.custom(adapter)`** - Custom storage backend. Pass your `StorageAdapter` implementation.
+
+#### `StorageAdapter` Interface
+
+Implement for custom storage backends:
+
+```typescript
+interface StorageAdapter {
+  /** Get value by key, returns undefined if not found */
+  get(key: string): Promise<Uint8Array | undefined>;
+
+  /** Set value by key */
+  set(key: string, value: Uint8Array): Promise<void>;
+
+  /** Delete value by key */
+  delete(key: string): Promise<void>;
+
+  /** List all keys matching prefix */
+  keys(prefix: string): Promise<string[]>;
+
+  /** Optional: cleanup when persistence is destroyed */
+  close?(): void;
+}
+```
+
 #### Error Classes
 
 ```typescript
 import { errors } from '@trestleinc/replicate/client';
 
 errors.Network           // Network-related failures
-errors.IDB               // IndexedDB read errors
-errors.IDBWrite          // IndexedDB write errors
+errors.IDB               // Storage read errors
+errors.IDBWrite          // Storage write errors
 errors.Reconciliation    // Phantom document cleanup errors
 errors.Prose             // Rich text field errors
 errors.CollectionNotReady// Collection not initialized
@@ -665,9 +843,10 @@ Configuration for the bound replicate function.
 interface ReplicateConfig<T> {
   collection: string;          // Collection name (e.g., 'tasks')
 
-  // Optional: Auto-compaction settings
+  // Optional: Compaction settings with type-safe values
   compaction?: {
-    threshold?: number;        // Size threshold in bytes (default: 5MB / 5_000_000)
+    sizeThreshold?: Size;      // Size threshold: "100kb", "5mb", "1gb" (default: "5mb")
+    peerTimeout?: Duration;    // Peer timeout: "30m", "24h", "7d" (default: "24h")
   };
 
   // Optional: Hooks for permissions and lifecycle
@@ -676,16 +855,14 @@ interface ReplicateConfig<T> {
     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>;
+    evalMark?: (ctx, peerId) => Promise<void>;
+    evalCompact?: (ctx, documentId) => 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[]>;
@@ -693,17 +870,23 @@ interface ReplicateConfig<T> {
 }
 ```
 
+**Type-safe values:**
+- `Size`: `"100kb"`, `"5mb"`, `"1gb"`, etc.
+- `Duration`: `"30m"`, `"24h"`, `"7d"`, etc.
+
 **Returns:** Object with generated functions:
-- `stream` - Real-time CRDT stream query
+- `stream` - Real-time CRDT stream query (cursor-based with `seq` numbers)
 - `material` - SSR-friendly query for hydration
+- `recovery` - State vector sync query (for startup reconciliation)
 - `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)
+- `mark` - Peer sync tracking mutation (reports `syncedSeq` to server)
+- `compact` - Manual compaction mutation (peer-aware, safe for active clients)
 
 #### `schema.table(userFields, applyIndexes?)`
 
-Automatically inject replication metadata fields (`version`, `timestamp`).
+Automatically inject `timestamp` field for incremental sync.
 
 **Parameters:**
 - `userFields` - User's business logic fields
@@ -721,7 +904,7 @@ tasks: schema.table(
     text: v.string(),
   },
   (t) => t
-    .index('by_user_id', ['id'])
+    .index('by_doc_id', ['id'])
     .index('by_timestamp', ['timestamp'])
 )
 ```
@@ -737,43 +920,38 @@ Validator for ProseMirror-compatible JSON fields.
 content: schema.prose()  // Validates ProseMirror JSON structure
 ```
 
-## Performance
-
-### Storage Performance
+### Shared Types (`@trestleinc/replicate/shared`)
 
-- **Swappable persistence** - IndexedDB (browser), SQLite (React Native), or in-memory (testing)
-- **Yjs** CRDT operations are extremely fast (96% smaller than Automerge)
-- **TanStack DB** provides optimistic updates and reactive state management
-- **Indexed queries** in Convex for fast incremental sync
+```typescript
+import type { ProseValue } from '@trestleinc/replicate/shared';
 
-### Sync Performance
+// ProseValue - branded type for prose fields in Zod schemas
+// Use the prose() helper from client to create fields of this type
+```
 
-- **Real-time updates** - WebSocket-based change notifications
-- **Delta encoding** - Only send what changed (< 1KB per change vs 100KB+ full state)
-- **Event sourcing** - Append-only writes, no update conflicts
-- **Optimistic UI** - Instant updates without waiting for server
+## React Native
 
-### Multi-Tab Sync
+React Native doesn't include the Web Crypto API by default. Install these polyfills:
 
-- **TanStack coordination** - Built-in multi-tab sync via BroadcastChannel
-- **Yjs shared state** - Single source of truth per browser
-- **Leader election** - Only one tab runs sync operations
+```bash
+npm install react-native-get-random-values react-native-random-uuid
+```
 
-## Offline Behavior
+Import them at the **very top** of your app's entry point (before any other imports):
 
-### How It Works
+```javascript
+// index.js or app/_layout.tsx - MUST be first!
+import "react-native-get-random-values";
+import "react-native-random-uuid";
 
-- **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!)
+// Then your other imports...
+```
 
-### Network Resilience
+This provides:
+- `crypto.getRandomValues()` - Required by Yjs for CRDT operations
+- `crypto.randomUUID()` - Used for generating document and peer IDs
 
-- Automatic retry with exponential backoff
-- Network error detection (fetch errors, connection issues)
-- Queue changes while offline
-- Graceful degradation
+See [`examples/expo/`](./examples/expo/) for a complete React Native example using Expo.
 
 ## Examples
 
@@ -781,21 +959,29 @@ content: schema.prose()  // Validates ProseMirror JSON structure
 
 A full-featured offline-first issue tracker built with Replicate, demonstrating real-world usage patterns.
 
-🔗 **Live Demo:** [interval.robelest.com](https://interval.robelest.com)
+**Live Demo:** [interval.robelest.com](https://interval.robelest.com)
 
-📦 **Source Code:** [github.com/robelest/interval](https://github.com/robelest/interval)
+**Source Code:** Available in three framework variants:
+- [`examples/tanstack-start/`](./examples/tanstack-start/) - TanStack Start (React, web)
+- [`examples/sveltekit/`](./examples/sveltekit/) - SvelteKit (Svelte, web)
+- [`examples/expo/`](./examples/expo/) - Expo (React Native, mobile)
 
-**Features demonstrated:**
+**Web 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()`)
 
+**Mobile features demonstrated (Expo):**
+- Native SQLite persistence (op-sqlite)
+- Plain TextInput prose binding via `useProseField` hook
+- Crypto polyfills for React Native
+
 ## Development
 
 ```bash
-bun run build         # Build with Rslib (includes ESLint + TypeScript checking)
+bun run build         # Build with tsdown (includes ESLint + TypeScript checking)
 bun run dev           # Watch mode
 bun run clean         # Remove build artifacts
 ```