@trestleinc/replicate 1.1.1 → 1.1.2-preview.0

package/README.md

@@ -14,7 +14,7 @@ sequenceDiagram
     participant UI as React Component
     participant Collection as TanStack DB Collection
     participant Yjs as Yjs CRDT
-    participant Storage as Local Storage<br/>(IndexedDB/SQLite)
+    participant Storage as Local Storage<br/>(SQLite)
     participant Convex as Convex Backend
     participant Table as Main Table
 
@@ -41,7 +41,7 @@ graph TB
     subgraph Client
         TDB[TanStack DB]
         Yjs[Yjs CRDT]
-        Local[(IndexedDB/SQLite)]
+        Local[(SQLite)]
         TDB <--> Yjs
         Yjs <--> Local
     end
@@ -111,7 +111,7 @@ export default defineSchema({
       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
   ),
 });
@@ -122,7 +122,7 @@ export default defineSchema({
 - 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
@@ -144,73 +144,93 @@ export const {
   insert,
   update,
   remove,
+  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 (checkpoint-based 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)
+- `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/__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/routes/index.tsx
+// 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({
@@ -243,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"
@@ -259,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
@@ -269,55 +294,121 @@ 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 };
   },
 });
+```
+
+```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';
+
+const httpClient = new ConvexHttpClient(PUBLIC_CONVEX_URL);
+
+export async function load() {
+  const tasksMaterial = await httpClient.query(api.tasks.material);
+  return { tasksMaterial };
+}
+```
+
+**Step 2: Pass material to init() on the client**
+
+```typescript
+// TanStack Start: src/routes/__root.tsx (client component)
+import { tasks } from '../collections/tasks';
 
-function TasksPage() {
-  const { tasks: initialTasks } = Route.useLoaderData();
+function RootComponent() {
+  const { tasksMaterial } = Route.useLoaderData();
 
-  // Pass initialData to your hook - no loading state on first render!
-  const collection = useTasks(initialTasks);
-  const { data: tasks } = useLiveQuery(collection);
+  useEffect(() => {
+    // Initialize with SSR data - no loading state!
+    tasks.init(tasksMaterial);
+  }, []);
 
-  return <TaskList tasks={tasks} />;
+  return <Outlet />;
 }
 ```
 
-**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.
+```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 two complementary sync mechanisms:
+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
 
-### `stream` - Real-time Checkpoint Sync
+Clients report their sync progress to the server:
 
-The primary sync mechanism for real-time updates. Uses checkpoint-based incremental sync:
+```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
 
-1. Client subscribes with last known checkpoint (timestamp)
-2. Server returns all deltas since that checkpoint
-3. Client applies deltas and updates checkpoint
-4. Subscription stays open for live updates
+Compaction is safe because it respects peer sync state:
 
-This is efficient for ongoing sync but requires the server to have deltas going back to the client's checkpoint.
+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
 
@@ -332,12 +423,7 @@ Used on startup to reconcile client and server state using Yjs state vectors:
 **When recovery is used:**
 - App startup (before stream subscription begins)
 - After extended offline periods
-- When checkpoint-based sync can't satisfy the request (deltas compacted)
-
-**Why both?**
-- `stream` is optimized for real-time (small checkpoint, fast subscription)
-- `recovery` handles cold starts and large gaps efficiently (state vectors)
-- Together they ensure clients always sync correctly regardless of history
+- When cursor-based sync can't satisfy the request (deltas compacted)
 
 ## Delete Pattern: Hard Delete with Event History
 
@@ -398,6 +484,8 @@ export const {
   insert,
   update,
   remove,
+  mark,
+  compact,
 } = r<Task>({
   collection: 'tasks',
 
@@ -416,6 +504,16 @@ export const {
       const userId = await ctx.auth.getUserIdentity();
       if (!userId) throw new Error('Unauthorized');
     },
+    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 */ },
@@ -456,48 +554,82 @@ const binding = await collection.utils.prose(notebookId, 'content');
 
 ### Persistence Providers
 
-Choose the right storage backend for your platform:
+Choose the right storage backend for your platform. Persistence is configured in the `persistence` factory of `collection.create()`:
 
 ```typescript
-import { persistence, adapters } from '@trestleinc/replicate/client';
-
-// Browser: IndexedDB (default, no config needed)
-convexCollectionOptions<Task>({
-  // ... other options
-  persistence: persistence.indexeddb(),
-});
+import { collection, persistence } from '@trestleinc/replicate/client';
 
 // 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 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: () => ({ /* ... */ }),
 });
 
 // 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 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: () => ({ /* ... */ }),
 });
 
 // Testing: In-memory (no persistence)
-convexCollectionOptions<Task>({
-  // ... other options
-  persistence: persistence.memory(),
+export const tasks = collection.create({
+  persistence: async () => persistence.memory(),
+  config: () => ({ /* ... */ }),
 });
-```
 
-**IndexedDB** (default) - Uses y-indexeddb for Y.Doc persistence and browser-level for metadata. Browser only.
+// Custom backend: Implement StorageAdapter interface
+export const tasks = collection.create({
+  persistence: async () => persistence.custom(new MyCustomAdapter()),
+  config: () => ({ /* ... */ }),
+});
+```
 
 **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.
+**Memory** - No persistence, useful for testing.
+
+**Custom** - Implement `StorageAdapter` for any storage backend.
+
+### Custom Storage Backends
+
+Implement `StorageAdapter` for custom storage (Chrome extensions, localStorage, cloud storage):
+
+```typescript
+import { persistence, type StorageAdapter } from '@trestleinc/replicate/client';
+
+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;
+  }
+
+  async set(key: string, value: Uint8Array): Promise<void> {
+    await chrome.storage.local.set({ [key]: Array.from(value) });
+  }
+
+  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));
+  }
+}
+
+// Use custom adapter
+const chromePersistence = persistence.custom(new ChromeStorageAdapter());
+```
 
 ### Logging Configuration
 
@@ -523,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).
+
+**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
+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:
 
-**Config:**
 ```typescript
-interface ConvexCollectionOptionsConfig<T> {
-  convexClient: ConvexClient;
-  api: {
-    stream: FunctionReference;    // Real-time subscription endpoint
+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)`
@@ -580,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
@@ -644,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
@@ -655,6 +855,8 @@ interface ReplicateConfig<T> {
     evalRead?: (ctx, collection) => Promise<void>;
     evalWrite?: (ctx, doc) => Promise<void>;
     evalRemove?: (ctx, documentId) => Promise<void>;
+    evalMark?: (ctx, peerId) => Promise<void>;
+    evalCompact?: (ctx, documentId) => Promise<void>;
 
     // Lifecycle callbacks (run after operation)
     onStream?: (ctx, result) => Promise<void>;
@@ -668,13 +870,19 @@ 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 (checkpoint-based)
+- `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)
+- `mark` - Peer sync tracking mutation (reports `syncedSeq` to server)
+- `compact` - Manual compaction mutation (peer-aware, safe for active clients)
 
 #### `schema.table(userFields, applyIndexes?)`
 
@@ -696,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'])
 )
 ```
@@ -712,27 +920,68 @@ Validator for ProseMirror-compatible JSON fields.
 content: schema.prose()  // Validates ProseMirror JSON structure
 ```
 
+### Shared Types (`@trestleinc/replicate/shared`)
+
+```typescript
+import type { ProseValue } from '@trestleinc/replicate/shared';
+
+// ProseValue - branded type for prose fields in Zod schemas
+// Use the prose() helper from client to create fields of this type
+```
+
+## React Native
+
+React Native doesn't include the Web Crypto API by default. Install these polyfills:
+
+```bash
+npm install react-native-get-random-values react-native-random-uuid
+```
+
+Import them at the **very top** of your app's entry point (before any other imports):
+
+```javascript
+// index.js or app/_layout.tsx - MUST be first!
+import "react-native-get-random-values";
+import "react-native-random-uuid";
+
+// Then your other imports...
+```
+
+This provides:
+- `crypto.getRandomValues()` - Required by Yjs for CRDT operations
+- `crypto.randomUUID()` - Used for generating document and peer IDs
+
+See [`examples/expo/`](./examples/expo/) for a complete React Native example using Expo.
+
 ## Examples
 
 ### Interval - Linear-style Issue Tracker
 
 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
 ```