@revealui/sync 0.3.6 → 0.3.7

package/README.md

@@ -1,6 +1,6 @@
 # @revealui/sync
 
-ElectricSQL sync utilities for RevealUI — real-time data synchronization with local-first architecture.
+ElectricSQL sync utilities for RevealUI  -  real-time data synchronization with local-first architecture.
 
 ## Features
 
@@ -28,7 +28,7 @@ import { ElectricProvider } from '@revealui/sync/provider'
 
 export default function App() {
   return (
-    <ElectricProvider proxyBaseUrl="https://cms.revealui.com">
+    <ElectricProvider proxyBaseUrl="https://admin.revealui.com">
       <YourComponents />
     </ElectricProvider>
   )
@@ -122,7 +122,7 @@ const {
 
 ### `useConversations(userId)`
 
-Subscribe to conversation history. Server-side proxy enforces row-level filtering by session — the `userId` parameter is for API compatibility but filtering is handled server-side.
+Subscribe to conversation history. Server-side proxy enforces row-level filtering by session  -  the `userId` parameter is for API compatibility but filtering is handled server-side.
 
 ```typescript
 const {
@@ -187,13 +187,13 @@ pnpm --filter @revealui/sync typecheck  # Type check
 - You need real-time data sync between your database and React UI via ElectricSQL
 - You want CRDT-based collaborative editing (Yjs) for multi-user document workflows
 - You need React hooks that subscribe to live database changes with automatic mutation support
-- **Not** for batch data loading or static pages — use server components with `@revealui/db` directly
-- **Not** for offline-first mobile apps — ElectricSQL targets web clients with persistent connections
+- **Not** for batch data loading or static pages  -  use server components with `@revealui/db` directly
+- **Not** for offline-first mobile apps  -  ElectricSQL targets web clients with persistent connections
 
 ## JOSHUA Alignment
 
-- **Adaptive**: Shape subscriptions dynamically sync only the data your component needs — scales from one user to many
-- **Sovereign**: Sync runs through your own CMS proxy and PostgreSQL — no third-party real-time service required
+- **Adaptive**: Shape subscriptions dynamically sync only the data your component needs  -  scales from one user to many
+- **Sovereign**: Sync runs through your own CMS proxy and PostgreSQL  -  no third-party real-time service required
 - **Hermetic**: All mutations go through authenticated REST endpoints; ElectricSQL replication is read-only on the client
 
 ## License

package/dist/collab/use-collab-document.js

@@ -1,12 +1,12 @@
 import { useShape } from '@electric-sql/react';
 import { fetchWithTimeout } from '../fetch-with-timeout.js';
 import { useElectricConfig } from '../provider/index.js';
-// UUID v4 pattern — only format accepted as a yjs_documents PK
+// UUID v4 pattern  -  only format accepted as a yjs_documents PK
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export function useCollabDocument(documentId) {
     const { proxyBaseUrl } = useElectricConfig();
     // Validate before interpolating into the WHERE clause. yjs_documents PKs are
-    // always UUIDs — reject anything else so no untrusted string enters the query.
+    // always UUIDs  -  reject anything else so no untrusted string enters the query.
     const isValidId = UUID_RE.test(documentId);
     // Hook must always be called (Rules of Hooks). Pass an impossible WHERE when
     // the ID is invalid so the shape returns no rows but the hook still runs.

package/dist/conflict-resolution.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Conflict Resolution for Offline Edits
+ *
+ * Provides version-based conflict detection and configurable resolution
+ * strategies for mutations queued while offline.
+ *
+ * Architecture:
+ *   - Each mutation carries a `baseVersion` (the version of the resource
+ *     at the time the edit was made offline).
+ *   - On replay, the server may respond with 409 Conflict if the resource
+ *     has been modified since `baseVersion`.
+ *   - The resolution strategy determines how to handle the conflict:
+ *     last-write-wins, server-wins, or manual merge.
+ */
+export type ConflictStrategy = 'last-write-wins' | 'server-wins' | 'manual';
+export interface OfflineMutation {
+    /** Unique mutation identifier. */
+    id: string;
+    /** API endpoint URL. */
+    url: string;
+    /** HTTP method. */
+    method: string;
+    /** Request headers (serialized). */
+    headers: Record<string, string>;
+    /** Request body (serialized JSON string). */
+    body: string | null;
+    /** Timestamp when the mutation was created offline. */
+    timestamp: number;
+    /** Version of the resource when the edit was made (for conflict detection). */
+    baseVersion?: number;
+    /** Resource identifier (e.g. "posts:123") for grouping related mutations. */
+    resourceId?: string;
+    /** Number of replay attempts. */
+    retryCount: number;
+}
+export interface ConflictInfo {
+    /** The mutation that caused the conflict. */
+    mutation: OfflineMutation;
+    /** HTTP status code from the server (typically 409). */
+    statusCode: number;
+    /** Server's current version of the resource. */
+    serverVersion?: number;
+    /** Server's current resource data (if provided in the 409 response). */
+    serverData?: unknown;
+}
+export interface ReplayResult {
+    /** Mutations that were successfully replayed. */
+    succeeded: OfflineMutation[];
+    /** Mutations that hit a conflict. */
+    conflicts: ConflictInfo[];
+    /** Mutations that failed for non-conflict reasons (network, 5xx). */
+    failed: OfflineMutation[];
+}
+/**
+ * Apply the configured conflict resolution strategy.
+ *
+ * - `last-write-wins`: Retry the mutation with a force flag, overwriting the server version.
+ * - `server-wins`: Discard the offline mutation, keeping the server state.
+ * - `manual`: Return the conflict for UI-level resolution (e.g. a merge dialog).
+ */
+export declare function resolveConflict(conflict: ConflictInfo, strategy: ConflictStrategy): Promise<{
+    resolved: boolean;
+    retryMutation?: OfflineMutation;
+}>;
+/**
+ * Replay a batch of offline mutations in FIFO order.
+ *
+ * Mutations targeting the same resource are coalesced: only the most recent
+ * mutation per resource is replayed, reducing unnecessary round-trips.
+ *
+ * @param mutations - Queued mutations in chronological order.
+ * @param strategy - Conflict resolution strategy.
+ * @returns Replay results grouped by outcome.
+ */
+export declare function replayMutations(mutations: OfflineMutation[], strategy?: ConflictStrategy): Promise<ReplayResult>;
+/**
+ * Coalesce mutations targeting the same resource.
+ * For each resourceId, keep only the latest mutation.
+ * Mutations without a resourceId are always included.
+ */
+export declare function coalesceMutations(mutations: OfflineMutation[]): OfflineMutation[];
+//# sourceMappingURL=conflict-resolution.d.ts.map

package/dist/conflict-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict-resolution.d.ts","sourceRoot":"","sources":["../src/conflict-resolution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG,aAAa,GAAG,QAAQ,CAAC;AAE5E,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,6CAA6C;IAC7C,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,QAAQ,EAAE,eAAe,CAAC;IAC1B,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,qCAAqC;IACrC,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,qEAAqE;IACrE,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAID;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,eAAe,CAAA;CAAE,CAAC,CAwBjE;AAID;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,eAAe,EAAE,EAC5B,QAAQ,GAAE,gBAAoC,GAC7C,OAAO,CAAC,YAAY,CAAC,CAwFvB;AAID;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAkBjF"}

package/dist/conflict-resolution.js

@@ -0,0 +1,166 @@
+/**
+ * Conflict Resolution for Offline Edits
+ *
+ * Provides version-based conflict detection and configurable resolution
+ * strategies for mutations queued while offline.
+ *
+ * Architecture:
+ *   - Each mutation carries a `baseVersion` (the version of the resource
+ *     at the time the edit was made offline).
+ *   - On replay, the server may respond with 409 Conflict if the resource
+ *     has been modified since `baseVersion`.
+ *   - The resolution strategy determines how to handle the conflict:
+ *     last-write-wins, server-wins, or manual merge.
+ */
+// ─── Resolution ──────────────────────────────────────────────────────────────
+/**
+ * Apply the configured conflict resolution strategy.
+ *
+ * - `last-write-wins`: Retry the mutation with a force flag, overwriting the server version.
+ * - `server-wins`: Discard the offline mutation, keeping the server state.
+ * - `manual`: Return the conflict for UI-level resolution (e.g. a merge dialog).
+ */
+export async function resolveConflict(conflict, strategy) {
+    switch (strategy) {
+        case 'last-write-wins': {
+            // Retry with force header to tell the server to accept regardless of version
+            const retryMutation = {
+                ...conflict.mutation,
+                headers: {
+                    ...conflict.mutation.headers,
+                    'X-Force-Overwrite': 'true',
+                    'X-Base-Version': String(conflict.serverVersion ?? 0),
+                },
+                retryCount: conflict.mutation.retryCount + 1,
+            };
+            return { resolved: true, retryMutation };
+        }
+        case 'server-wins':
+            // Discard the offline mutation
+            return { resolved: true };
+        case 'manual':
+            // Return unresolved for UI handling
+            return { resolved: false };
+    }
+}
+// ─── Replay Engine ─────────��─────────────────────────────────────────────────
+/**
+ * Replay a batch of offline mutations in FIFO order.
+ *
+ * Mutations targeting the same resource are coalesced: only the most recent
+ * mutation per resource is replayed, reducing unnecessary round-trips.
+ *
+ * @param mutations - Queued mutations in chronological order.
+ * @param strategy - Conflict resolution strategy.
+ * @returns Replay results grouped by outcome.
+ */
+export async function replayMutations(mutations, strategy = 'last-write-wins') {
+    const result = {
+        succeeded: [],
+        conflicts: [],
+        failed: [],
+    };
+    // Coalesce: for each resourceId, keep only the latest mutation
+    const coalesced = coalesceMutations(mutations);
+    for (const mutation of coalesced) {
+        try {
+            const response = await fetch(mutation.url, {
+                method: mutation.method,
+                headers: {
+                    ...mutation.headers,
+                    ...(mutation.baseVersion != null ? { 'If-Match': String(mutation.baseVersion) } : {}),
+                },
+                body: mutation.body || undefined,
+            });
+            if (response.ok) {
+                result.succeeded.push(mutation);
+                continue;
+            }
+            if (response.status === 409) {
+                let serverData;
+                let serverVersion;
+                try {
+                    const body = await response.json();
+                    serverData = body.data;
+                    serverVersion = body.version;
+                }
+                catch {
+                    // 409 without JSON body
+                }
+                const conflict = {
+                    mutation,
+                    statusCode: 409,
+                    serverVersion,
+                    serverData,
+                };
+                const resolution = await resolveConflict(conflict, strategy);
+                if (resolution.resolved && resolution.retryMutation) {
+                    // Retry the mutation with force overwrite
+                    try {
+                        const retryResponse = await fetch(resolution.retryMutation.url, {
+                            method: resolution.retryMutation.method,
+                            headers: resolution.retryMutation.headers,
+                            body: resolution.retryMutation.body || undefined,
+                        });
+                        if (retryResponse.ok) {
+                            result.succeeded.push(mutation);
+                        }
+                        else {
+                            result.failed.push(mutation);
+                        }
+                    }
+                    catch {
+                        result.failed.push(mutation);
+                    }
+                }
+                else if (resolution.resolved) {
+                    // server-wins: mutation discarded, count as succeeded (intentionally dropped)
+                    result.succeeded.push(mutation);
+                }
+                else {
+                    // manual: surface the conflict
+                    result.conflicts.push(conflict);
+                }
+                continue;
+            }
+            // Server error or other non-conflict failure
+            if (response.status >= 500) {
+                result.failed.push(mutation);
+                // Stop replaying on server errors to avoid cascading failures
+                break;
+            }
+            // Client error (4xx other than 409): discard, not recoverable
+            result.failed.push(mutation);
+        }
+        catch {
+            // Network error: stop replaying
+            result.failed.push(mutation);
+            break;
+        }
+    }
+    return result;
+}
+// ─── Coalescing ──────��───────────────────────────────────────────────────────
+/**
+ * Coalesce mutations targeting the same resource.
+ * For each resourceId, keep only the latest mutation.
+ * Mutations without a resourceId are always included.
+ */
+export function coalesceMutations(mutations) {
+    const byResource = new Map();
+    const ungrouped = [];
+    for (const mutation of mutations) {
+        if (mutation.resourceId) {
+            const existing = byResource.get(mutation.resourceId);
+            if (!existing || mutation.timestamp > existing.timestamp) {
+                byResource.set(mutation.resourceId, mutation);
+            }
+        }
+        else {
+            ungrouped.push(mutation);
+        }
+    }
+    // Maintain chronological order: ungrouped first, then coalesced by timestamp
+    const coalesced = [...byResource.values()].sort((a, b) => a.timestamp - b.timestamp);
+    return [...ungrouped, ...coalesced];
+}

package/dist/fetch-with-timeout.d.ts

@@ -1,7 +1,7 @@
 /**
  * A fetch wrapper that aborts requests after {@link SHAPE_FETCH_TIMEOUT_MS} (10 s).
  * Passed as `fetchClient` to ElectricSQL `useShape` so that shape subscription
- * requests to the CMS proxy do not hang indefinitely.
+ * requests to the admin proxy do not hang indefinitely.
  */
 export declare function fetchWithTimeout(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
 //# sourceMappingURL=fetch-with-timeout.d.ts.map

package/dist/fetch-with-timeout.js

@@ -3,7 +3,7 @@ const SHAPE_FETCH_TIMEOUT_MS = 10_000;
 /**
  * A fetch wrapper that aborts requests after {@link SHAPE_FETCH_TIMEOUT_MS} (10 s).
  * Passed as `fetchClient` to ElectricSQL `useShape` so that shape subscription
- * requests to the CMS proxy do not hang indefinitely.
+ * requests to the admin proxy do not hang indefinitely.
  */
 export function fetchWithTimeout(input, init) {
     // If the caller already provides a signal, respect it and compose with our timeout.

package/dist/hooks/browser-cache-factory.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Browser cache factory for PGlite-backed offline cache.
+ * Separated into its own file so tests can vi.mock() it without
+ * triggering PGlite WASM loading in jsdom.
+ * @internal
+ */
+interface CacheStoreLike {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T, ttlSeconds: number, tags?: string[]): Promise<void>;
+    delete(...keys: string[]): Promise<number>;
+    close(): Promise<void>;
+}
+export declare function createOfflineCache(): Promise<CacheStoreLike | null>;
+export {};
+//# sourceMappingURL=browser-cache-factory.d.ts.map

package/dist/hooks/browser-cache-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-cache-factory.d.ts","sourceRoot":"","sources":["../../src/hooks/browser-cache-factory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,UAAU,cAAc;IACtB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACjD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5F,MAAM,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAUzE"}

package/dist/hooks/browser-cache-factory.js

@@ -0,0 +1,16 @@
+/**
+ * Browser cache factory for PGlite-backed offline cache.
+ * Separated into its own file so tests can vi.mock() it without
+ * triggering PGlite WASM loading in jsdom.
+ * @internal
+ */
+export async function createOfflineCache() {
+    try {
+        const specifier = ['@revealui', 'cache', 'adapters'].join('/');
+        const mod = await Function('s', 'return import(s)')(specifier);
+        return await mod.createBrowserCache({ dbName: 'revealui-offline' });
+    }
+    catch {
+        return null;
+    }
+}

package/dist/hooks/index.d.ts

@@ -1,4 +1,6 @@
 export { useOfflineCache } from './useOfflineCache.js';
 export type { OnlineStatusResult } from './useOnlineStatus.js';
 export { useOnlineStatus } from './useOnlineStatus.js';
+export type { InvalidationAction } from './useShapeCacheInvalidation.js';
+export { useShapeCacheInvalidation } from './useShapeCacheInvalidation.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/hooks/index.js

@@ -1,2 +1,3 @@
 export { useOfflineCache } from './useOfflineCache.js';
 export { useOnlineStatus } from './useOnlineStatus.js';
+export { useShapeCacheInvalidation } from './useShapeCacheInvalidation.js';

package/dist/hooks/useConversations.js

@@ -4,12 +4,12 @@ import { fetchWithTimeout } from '../fetch-with-timeout.js';
 import { useSyncMutations } from '../mutations.js';
 import { useElectricConfig } from '../provider/index.js';
 import { toRecords } from '../shape-utils.js';
-// _userId kept for API compatibility — filtering is enforced by the server-side
+// _userId kept for API compatibility  -  filtering is enforced by the server-side
 // proxy at /api/shapes/conversations, which reads the session cookie directly.
 export function useConversations(_userId) {
     const { proxyBaseUrl } = useElectricConfig();
     // The proxy validates the session and enforces row-level filtering server-side.
-    // Client-provided params are not forwarded — the proxy overrides them.
+    // Client-provided params are not forwarded  -  the proxy overrides them.
     const { data, isLoading, error } = useShape({
         url: `${proxyBaseUrl}/api/shapes/conversations`,
         fetchClient: fetchWithTimeout,

package/dist/hooks/useOfflineCache.d.ts

@@ -1,13 +1,15 @@
 interface UseOfflineCacheOptions {
     /** ElectricSQL shape subscription URL. */
     shapeUrl: string;
-    /** Unique key for the localStorage cache entry. */
+    /** Unique key for the cache entry. */
     cacheKey: string;
     /** How long cached data is considered fresh (seconds). Defaults to 3600. */
     ttlSeconds?: number;
+    /** Additional cache tags for targeted invalidation. */
+    tags?: string[];
 }
 interface UseOfflineCacheResult<T> {
-    /** The current data — live from the shape when online, cached when offline. */
+    /** The current data: live from the shape when online, cached when offline. */
     data: T[];
     /** Whether the browser has network connectivity. */
     isOnline: boolean;
@@ -17,13 +19,20 @@ interface UseOfflineCacheResult<T> {
     lastSyncedAt: Date | null;
     /** Shape subscription or cache-read error, if any. */
     error: Error | null;
+    /** Manually invalidate the cache for this key. */
+    invalidate: () => Promise<void>;
 }
+/** Reset singleton state between tests. @internal */
+export declare function _resetCacheState(): void;
 /**
  * Wrap an ElectricSQL `useShape` subscription with offline-first caching.
  *
- * When online the hook delegates to `useShape` and mirrors results into
- * `localStorage`. When offline (or during initial load) it returns the
- * most recent cached snapshot if one exists within the TTL window.
+ * When online the hook delegates to `useShape` and mirrors results into a
+ * PGlite browser cache (IndexedDB). When offline (or during initial load) it
+ * returns the most recent cached snapshot if one exists within the TTL window.
+ *
+ * Falls back to localStorage when PGlite is unavailable (e.g. private browsing
+ * or environments without WASM support).
  *
  * @typeParam T - Row type returned by the shape subscription.
  */

package/dist/hooks/useOfflineCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOfflineCache.d.ts","sourceRoot":"","sources":["../../src/hooks/useOfflineCache.ts"],"names":[],"mappings":"AAmBA,UAAU,sBAAsB;IAC9B,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,qBAAqB,CAAC,CAAC;IAC/B,+EAA+E;IAC/E,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAC;IAClB,sEAAsE;IACtE,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,sDAAsD;IACtD,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAqED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAiD5F"}
+{"version":3,"file":"useOfflineCache.d.ts","sourceRoot":"","sources":["../../src/hooks/useOfflineCache.ts"],"names":[],"mappings":"AAcA,UAAU,sBAAsB;IAC9B,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,UAAU,qBAAqB,CAAC,CAAC;IAC/B,8EAA8E;IAC9E,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAC;IAClB,sEAAsE;IACtE,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,sDAAsD;IACtD,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,kDAAkD;IAClD,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAuDD,qDAAqD;AACrD,wBAAgB,gBAAgB,IAAI,IAAI,CAIvC;AAuCD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAmI5F"}

package/dist/hooks/useOfflineCache.js

@@ -1,112 +1,213 @@
 'use client';
 import { useShape } from '@electric-sql/react';
-import { useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { fetchWithTimeout } from '../fetch-with-timeout.js';
 import { toRecords } from '../shape-utils.js';
 import { useOnlineStatus } from './useOnlineStatus.js';
-/** Prefix for all offline-cache localStorage keys. */
-const CACHE_PREFIX = 'revealui:cache:';
 /** Default time-to-live for cached data (seconds). */
 const DEFAULT_TTL_SECONDS = 3600;
-/**
- * Check whether `localStorage` is usable.
- */
-function hasLocalStorage() {
-    if (typeof window === 'undefined') {
-        return false;
-    }
-    try {
-        const testKey = '__revealui_oc_test__';
-        window.localStorage.setItem(testKey, '1');
-        window.localStorage.removeItem(testKey);
-        return true;
-    }
-    catch {
-        return false;
-    }
+/** Tag prefix applied to all offline cache entries for bulk invalidation. */
+const OFFLINE_CACHE_TAG = 'offline-cache';
+let browserCache = null;
+let cacheInitPromise = null;
+let cacheRefCount = 0;
+function isBrowserWithIndexedDB() {
+    return (typeof window !== 'undefined' &&
+        typeof indexedDB !== 'undefined' &&
+        typeof navigator !== 'undefined' &&
+        // Exclude jsdom/test environments where PGlite WASM cannot run
+        navigator.userAgent.indexOf('jsdom') === -1);
 }
-/**
- * Read cached data from localStorage. Returns `null` when the entry is
- * missing, expired, or unreadable.
- */
-function readCache(cacheKey, ttlSeconds) {
-    if (!hasLocalStorage()) {
+async function getBrowserCache() {
+    if (browserCache)
+        return browserCache;
+    if (cacheInitPromise)
+        return cacheInitPromise;
+    if (!isBrowserWithIndexedDB())
         return null;
+    cacheInitPromise = (async () => {
+        try {
+            const { createOfflineCache } = await import('./browser-cache-factory.js');
+            const cache = await createOfflineCache();
+            browserCache = cache;
+            return cache;
+        }
+        catch {
+            return null;
+        }
+    })();
+    return cacheInitPromise;
+}
+function releaseBrowserCache() {
+    cacheRefCount--;
+    if (cacheRefCount === 0 && browserCache) {
+        browserCache.close().catch(() => {
+            /* fire-and-forget cleanup */
+        });
+        browserCache = null;
+        cacheInitPromise = null;
     }
+}
+/** Reset singleton state between tests. @internal */
+export function _resetCacheState() {
+    browserCache = null;
+    cacheInitPromise = null;
+    cacheRefCount = 0;
+}
+const LS_PREFIX = 'revealui:cache:';
+function readLocalStorageCache(key, ttlSeconds) {
+    if (typeof window === 'undefined')
+        return null;
     try {
-        const raw = window.localStorage.getItem(CACHE_PREFIX + cacheKey);
-        if (raw === null) {
+        const raw = window.localStorage.getItem(LS_PREFIX + key);
+        if (raw === null)
             return null;
-        }
         const parsed = JSON.parse(raw);
-        if (!Array.isArray(parsed.data)) {
+        if (!Array.isArray(parsed.data))
             return null;
-        }
-        // Check TTL.
         const cachedTime = new Date(parsed.cachedAt).getTime();
-        if (Number.isNaN(cachedTime)) {
+        if (Number.isNaN(cachedTime))
             return null;
-        }
-        const ageSeconds = (Date.now() - cachedTime) / 1_000;
-        if (ageSeconds > ttlSeconds) {
+        if ((Date.now() - cachedTime) / 1_000 > ttlSeconds)
             return null;
-        }
-        return parsed;
+        return parsed.data;
     }
     catch {
         return null;
     }
 }
-/**
- * Write data to the localStorage cache. Silently ignores failures.
- */
-function writeCache(cacheKey, data) {
-    if (!hasLocalStorage()) {
+function writeLocalStorageCache(key, data) {
+    if (typeof window === 'undefined')
         return;
-    }
     try {
-        const payload = {
-            data,
-            cachedAt: new Date().toISOString(),
-        };
-        window.localStorage.setItem(CACHE_PREFIX + cacheKey, JSON.stringify(payload));
+        const payload = { data, cachedAt: new Date().toISOString() };
+        window.localStorage.setItem(LS_PREFIX + key, JSON.stringify(payload));
     }
     catch {
-        // Quota exceeded or private browsing — drop silently.
+        // Quota exceeded or private browsing.
     }
 }
+// ─── Hook ────────────────────────────────────────────────────────────────────
 /**
  * Wrap an ElectricSQL `useShape` subscription with offline-first caching.
  *
- * When online the hook delegates to `useShape` and mirrors results into
- * `localStorage`. When offline (or during initial load) it returns the
- * most recent cached snapshot if one exists within the TTL window.
+ * When online the hook delegates to `useShape` and mirrors results into a
+ * PGlite browser cache (IndexedDB). When offline (or during initial load) it
+ * returns the most recent cached snapshot if one exists within the TTL window.
+ *
+ * Falls back to localStorage when PGlite is unavailable (e.g. private browsing
+ * or environments without WASM support).
  *
  * @typeParam T - Row type returned by the shape subscription.
  */
 export function useOfflineCache(options) {
-    const { shapeUrl, cacheKey, ttlSeconds = DEFAULT_TTL_SECONDS } = options;
+    const { shapeUrl, cacheKey, ttlSeconds = DEFAULT_TTL_SECONDS, tags } = options;
     const { isOnline } = useOnlineStatus();
-    // Shape subscription — runs continuously; ElectricSQL handles reconnection.
     const shape = useShape({ url: shapeUrl, fetchClient: fetchWithTimeout });
-    const [lastSyncedAt, setLastSyncedAt] = useState(null);
-    // Keep a ref to avoid stale closures in the sync effect.
+    // Read localStorage synchronously on first render for instant offline data
+    const [cache, setCache] = useState(browserCache);
+    const [cachedData, setCachedData] = useState(() => readLocalStorageCache(cacheKey, ttlSeconds));
+    const [lastSyncedAt, setLastSyncedAt] = useState(() => {
+        // Recover lastSyncedAt from localStorage cache timestamp
+        if (typeof window === 'undefined')
+            return null;
+        try {
+            const raw = window.localStorage.getItem(LS_PREFIX + cacheKey);
+            if (!raw)
+                return null;
+            const parsed = JSON.parse(raw);
+            const time = new Date(parsed.cachedAt).getTime();
+            return Number.isNaN(time) ? null : new Date(parsed.cachedAt);
+        }
+        catch {
+            return null;
+        }
+    });
+    const mounted = useRef(true);
     const cacheKeyRef = useRef(cacheKey);
     cacheKeyRef.current = cacheKey;
-    // Persist live data to cache whenever the shape delivers fresh rows.
+    const ttlSecondsRef = useRef(ttlSeconds);
+    ttlSecondsRef.current = ttlSeconds;
+    const tagsRef = useRef(tags);
+    tagsRef.current = tags;
+    // Initialize PGlite browser cache
+    useEffect(() => {
+        mounted.current = true;
+        cacheRefCount++;
+        getBrowserCache()
+            .then((c) => {
+            if (!mounted.current)
+                return null;
+            if (c) {
+                setCache(c);
+                return c.get(cacheKeyRef.current);
+            }
+            // PGlite unavailable; fall back to localStorage
+            const lsData = readLocalStorageCache(cacheKeyRef.current, ttlSecondsRef.current);
+            if (lsData && mounted.current)
+                setCachedData(lsData);
+            return null;
+        })
+            .then((data) => {
+            if (mounted.current && data) {
+                setCachedData(data);
+            }
+        })
+            .catch(() => {
+            if (mounted.current) {
+                // Fall back to localStorage
+                const lsData = readLocalStorageCache(cacheKeyRef.current, ttlSecondsRef.current);
+                if (lsData)
+                    setCachedData(lsData);
+            }
+        });
+        return () => {
+            mounted.current = false;
+            releaseBrowserCache();
+        };
+    }, []); // eslint-disable-line react-hooks/exhaustive-deps
+    // Persist live data to PGlite (or localStorage fallback) when shape delivers fresh rows
     const shapeData = shape.data;
     useEffect(() => {
-        if (!isOnline) {
+        if (!isOnline)
             return;
-        }
-        if (!Array.isArray(shapeData) || shapeData.length === 0) {
+        if (!Array.isArray(shapeData) || shapeData.length === 0)
             return;
-        }
         const typed = toRecords(shapeData);
-        writeCache(cacheKeyRef.current, typed);
-        setLastSyncedAt(new Date());
-    }, [shapeData, isOnline]);
-    // Determine what to return.
+        const allTags = [OFFLINE_CACHE_TAG, ...(tagsRef.current ?? [])];
+        if (cache) {
+            cache.set(cacheKeyRef.current, typed, ttlSecondsRef.current, allTags).catch(() => {
+                // PGlite write failed; fall back to localStorage
+                writeLocalStorageCache(cacheKeyRef.current, typed);
+            });
+        }
+        else {
+            writeLocalStorageCache(cacheKeyRef.current, typed);
+        }
+        if (mounted.current) {
+            setCachedData(typed);
+            setLastSyncedAt(new Date());
+        }
+    }, [shapeData, isOnline, cache]);
+    // Manual invalidation
+    const invalidate = useCallback(async () => {
+        if (cache) {
+            await cache.delete(cacheKeyRef.current);
+        }
+        if (typeof window !== 'undefined') {
+            try {
+                window.localStorage.removeItem(LS_PREFIX + cacheKeyRef.current);
+            }
+            catch {
+                // Ignore
+            }
+        }
+        if (mounted.current) {
+            setCachedData(null);
+            setLastSyncedAt(null);
+        }
+    }, [cache]);
+    // Determine what to return
     if (isOnline && Array.isArray(shapeData) && shapeData.length > 0) {
         return {
             data: toRecords(shapeData),
@@ -114,16 +215,16 @@ export function useOfflineCache(options) {
             isSyncing: shape.isLoading,
             lastSyncedAt,
             error: shape.error || null,
+            invalidate,
         };
     }
-    // Offline or shape has not loaded yet — try the cache.
-    const cached = readCache(cacheKey, ttlSeconds);
-    const cachedSyncDate = cached !== null ? new Date(cached.cachedAt) : null;
+    // Offline or shape has not loaded yet: use cached data
     return {
-        data: cached?.data ?? [],
+        data: cachedData ?? [],
         isOnline,
         isSyncing: isOnline && shape.isLoading,
-        lastSyncedAt: lastSyncedAt ?? cachedSyncDate,
+        lastSyncedAt,
         error: shape.error || null,
+        invalidate,
     };
 }

package/dist/hooks/useOnlineStatus.js

@@ -32,7 +32,7 @@ export function useOnlineStatus() {
     const [lastOnlineAt, setLastOnlineAt] = useState(null);
     const resetTimerRef = useRef(null);
     useEffect(() => {
-        // No-op during SSR — the effect only runs in the browser.
+        // No-op during SSR  -  the effect only runs in the browser.
         if (!isBrowser()) {
             return;
         }

package/dist/hooks/useShapeCacheInvalidation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Invalidation action triggered when shape data changes.
+ * Maps to CacheInvalidationChannel event types.
+ */
+export type InvalidationAction = {
+    type: 'delete';
+    keys: string[];
+} | {
+    type: 'delete-prefix';
+    prefix: string;
+} | {
+    type: 'delete-tags';
+    tags: string[];
+} | {
+    type: 'clear';
+};
+interface UseShapeCacheInvalidationOptions {
+    /** ElectricSQL shape subscription URL to watch. */
+    shapeUrl: string;
+    /**
+     * Determine which cache entries to invalidate when shape data changes.
+     * Receives the new data from the shape subscription and returns one or
+     * more invalidation actions.
+     */
+    getInvalidations: (data: unknown[]) => InvalidationAction[];
+    /**
+     * Callback to execute the invalidation actions. Typically this calls
+     * methods on a CacheStore or CacheInvalidationChannel instance.
+     */
+    onInvalidate: (actions: InvalidationAction[]) => Promise<void>;
+    /** Whether invalidation is enabled (default: true). */
+    enabled?: boolean;
+}
+/**
+ * Subscribe to an ElectricSQL shape and trigger cache invalidation
+ * when the shape data changes.
+ *
+ * This hook bridges ElectricSQL's real-time sync with the cache
+ * invalidation system, enabling push-based cache busting without polling.
+ *
+ * Example:
+ *   useShapeCacheInvalidation({
+ *     shapeUrl: `${ELECTRIC_URL}/v1/shape?table=posts`,
+ *     getInvalidations: (data) => [
+ *       { type: 'delete-tags', tags: ['posts'] },
+ *     ],
+ *     onInvalidate: async (actions) => {
+ *       for (const action of actions) {
+ *         if (action.type === 'delete-tags') {
+ *           await channel.publishDeleteTags(action.tags);
+ *         }
+ *       }
+ *     },
+ *   });
+ */
+export declare function useShapeCacheInvalidation(options: UseShapeCacheInvalidationOptions): void;
+export {};
+//# sourceMappingURL=useShapeCacheInvalidation.d.ts.map

package/dist/hooks/useShapeCacheInvalidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useShapeCacheInvalidation.d.ts","sourceRoot":"","sources":["../../src/hooks/useShapeCacheInvalidation.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB,UAAU,gCAAgC;IACxC,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,gBAAgB,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,kBAAkB,EAAE,CAAC;IAC5D;;;OAGG;IACH,YAAY,EAAE,CAAC,OAAO,EAAE,kBAAkB,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gCAAgC,GAAG,IAAI,CAyCzF"}

package/dist/hooks/useShapeCacheInvalidation.js

@@ -0,0 +1,64 @@
+'use client';
+import { useShape } from '@electric-sql/react';
+import { useEffect, useRef } from 'react';
+import { fetchWithTimeout } from '../fetch-with-timeout.js';
+/**
+ * Subscribe to an ElectricSQL shape and trigger cache invalidation
+ * when the shape data changes.
+ *
+ * This hook bridges ElectricSQL's real-time sync with the cache
+ * invalidation system, enabling push-based cache busting without polling.
+ *
+ * Example:
+ *   useShapeCacheInvalidation({
+ *     shapeUrl: `${ELECTRIC_URL}/v1/shape?table=posts`,
+ *     getInvalidations: (data) => [
+ *       { type: 'delete-tags', tags: ['posts'] },
+ *     ],
+ *     onInvalidate: async (actions) => {
+ *       for (const action of actions) {
+ *         if (action.type === 'delete-tags') {
+ *           await channel.publishDeleteTags(action.tags);
+ *         }
+ *       }
+ *     },
+ *   });
+ */
+export function useShapeCacheInvalidation(options) {
+    const { shapeUrl, getInvalidations, onInvalidate, enabled = true } = options;
+    const shape = useShape({ url: shapeUrl, fetchClient: fetchWithTimeout });
+    const prevDataRef = useRef(null);
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    const shapeData = shape.data;
+    useEffect(() => {
+        if (!enabled)
+            return;
+        if (shape.isLoading)
+            return;
+        if (!Array.isArray(shapeData))
+            return;
+        // Skip the initial load (no previous data to compare against)
+        if (prevDataRef.current === null) {
+            prevDataRef.current = shapeData;
+            return;
+        }
+        // Skip if data reference hasn't changed
+        if (prevDataRef.current === shapeData)
+            return;
+        prevDataRef.current = shapeData;
+        const actions = getInvalidations(shapeData);
+        if (actions.length === 0)
+            return;
+        if (mounted.current) {
+            onInvalidate(actions).catch(() => {
+                // Invalidation is best-effort; stale cache entries will expire via TTL
+            });
+        }
+    }, [shapeData, shape.isLoading, enabled, getInvalidations, onInvalidate]);
+}

package/dist/index.d.ts

@@ -1,16 +1,18 @@
 /**
- * @revealui/sync — Real-time collaboration and sync primitives.
+ * @revealui/sync  -  Real-time collaboration and sync primitives.
  *
  * The collab layer (Yjs-based) is fully functional.
  * ElectricProvider provides proxyBaseUrl config to child hooks. All hooks route
- * through the authenticated CMS proxy at /api/shapes/* — no direct Electric client.
+ * through the authenticated admin proxy at /api/shapes/*  -  no direct Electric client.
  *
  * Reads use ElectricSQL shape subscriptions for real-time updates.
- * Writes use REST mutations via /api/sync/* — changes propagate to all
+ * Writes use REST mutations via /api/sync/*  -  changes propagate to all
  * subscribers automatically through ElectricSQL replication.
  */
 export type { CollabDocumentState, UseCollaborationOptions, UseCollaborationResult, } from './collab/index.js';
 export { CollabProvider, useCollabDocument, useCollaboration, } from './collab/index.js';
+export type { ConflictInfo, ConflictStrategy, OfflineMutation, ReplayResult, } from './conflict-resolution.js';
+export { coalesceMutations, replayMutations, resolveConflict, } from './conflict-resolution.js';
 export type { AgentContextRecord, CreateAgentContextInput, UpdateAgentContextInput, UseAgentContextsResult, } from './hooks/useAgentContexts.js';
 export { useAgentContexts } from './hooks/useAgentContexts.js';
 export type { AgentMemoryRecord, CreateAgentMemoryInput, UpdateAgentMemoryInput, UseAgentMemoryResult, } from './hooks/useAgentMemory.js';
@@ -21,6 +23,11 @@ export type { CoordinationSessionRecord, CreateCoordinationSessionInput, UpdateC
 export { useCoordinationSessions } from './hooks/useCoordinationSessions.js';
 export type { CoordinationWorkItemRecord, CreateCoordinationWorkItemInput, UpdateCoordinationWorkItemInput, UseCoordinationWorkItemsResult, } from './hooks/useCoordinationWorkItems.js';
 export { useCoordinationWorkItems } from './hooks/useCoordinationWorkItems.js';
+export { useOfflineCache } from './hooks/useOfflineCache.js';
+export type { OnlineStatusResult } from './hooks/useOnlineStatus.js';
+export { useOnlineStatus } from './hooks/useOnlineStatus.js';
+export type { InvalidationAction } from './hooks/useShapeCacheInvalidation.js';
+export { useShapeCacheInvalidation } from './hooks/useShapeCacheInvalidation.js';
 export type { MutationResult } from './mutations.js';
 export { ElectricProvider, useElectricConfig } from './provider/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,YAAY,EACV,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,YAAY,EACV,yBAAyB,EACzB,8BAA8B,EAC9B,8BAA8B,EAC9B,6BAA6B,GAC9B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,YAAY,EACV,0BAA0B,EAC1B,+BAA+B,EAC/B,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,YAAY,GACb,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,YAAY,EACV,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,YAAY,EACV,yBAAyB,EACzB,8BAA8B,EAC9B,8BAA8B,EAC9B,6BAA6B,GAC9B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,YAAY,EACV,0BAA0B,EAC1B,+BAA+B,EAC/B,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,YAAY,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AACjF,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,18 +1,22 @@
 /**
- * @revealui/sync — Real-time collaboration and sync primitives.
+ * @revealui/sync  -  Real-time collaboration and sync primitives.
  *
  * The collab layer (Yjs-based) is fully functional.
  * ElectricProvider provides proxyBaseUrl config to child hooks. All hooks route
- * through the authenticated CMS proxy at /api/shapes/* — no direct Electric client.
+ * through the authenticated admin proxy at /api/shapes/*  -  no direct Electric client.
  *
  * Reads use ElectricSQL shape subscriptions for real-time updates.
- * Writes use REST mutations via /api/sync/* — changes propagate to all
+ * Writes use REST mutations via /api/sync/*  -  changes propagate to all
  * subscribers automatically through ElectricSQL replication.
  */
 export { CollabProvider, useCollabDocument, useCollaboration, } from './collab/index.js';
+export { coalesceMutations, replayMutations, resolveConflict, } from './conflict-resolution.js';
 export { useAgentContexts } from './hooks/useAgentContexts.js';
 export { useAgentMemory } from './hooks/useAgentMemory.js';
 export { useConversations } from './hooks/useConversations.js';
 export { useCoordinationSessions } from './hooks/useCoordinationSessions.js';
 export { useCoordinationWorkItems } from './hooks/useCoordinationWorkItems.js';
+export { useOfflineCache } from './hooks/useOfflineCache.js';
+export { useOnlineStatus } from './hooks/useOnlineStatus.js';
+export { useShapeCacheInvalidation } from './hooks/useShapeCacheInvalidation.js';
 export { ElectricProvider, useElectricConfig } from './provider/index.js';

package/dist/mutations.js

@@ -4,7 +4,7 @@ import { useElectricConfig } from './provider/index.js';
 /** Default timeout for mutation fetch requests (milliseconds). */
 const MUTATION_FETCH_TIMEOUT_MS = 10_000;
 /**
- * Make an authenticated mutation request to the CMS API.
+ * Make an authenticated mutation request to the admin API.
  * Credentials are included so the session cookie is sent cross-origin.
  * Requests are aborted after {@link MUTATION_FETCH_TIMEOUT_MS} (10 s).
  */

package/dist/offline-queue.d.ts

@@ -1,5 +1,5 @@
 /**
- * Offline mutation queue — stores pending mutations in localStorage
+ * Offline mutation queue  -  stores pending mutations in localStorage
  * so they survive page reloads and can be flushed when connectivity returns.
  */
 /** A single pending mutation waiting to be sent to the server. */

package/dist/offline-queue.js

@@ -1,5 +1,5 @@
 /**
- * Offline mutation queue — stores pending mutations in localStorage
+ * Offline mutation queue  -  stores pending mutations in localStorage
  * so they survive page reloads and can be flushed when connectivity returns.
  */
 /** localStorage key for the persisted queue. */
@@ -57,7 +57,7 @@ function writeQueue(queue) {
         window.localStorage.setItem(STORAGE_KEY, JSON.stringify(queue));
     }
     catch {
-        // Quota exceeded or private browsing — drop silently.
+        // Quota exceeded or private browsing  -  drop silently.
     }
 }
 /**
@@ -120,7 +120,7 @@ export class OfflineMutationQueue {
             window.localStorage.removeItem(STORAGE_KEY);
         }
         catch {
-            // Ignore — same guard as writeQueue.
+            // Ignore  -  same guard as writeQueue.
         }
     }
 }

package/dist/provider/index.d.ts

@@ -2,14 +2,14 @@ import { type ReactNode } from 'react';
 interface ElectricContextValue {
     /**
      * Direct Electric service URL (e.g. the Railway instance).
-     * Stored in context for future use — not consumed by the current proxy-based hooks.
+     * Stored in context for future use  -  not consumed by the current proxy-based hooks.
      * All hooks use proxyBaseUrl + /api/shapes/* instead.
      */
     serviceUrl: string | null;
     /**
-     * Base URL prefix for authenticated CMS shape proxy routes.
+     * Base URL prefix for authenticated admin shape proxy routes.
      * Default '' keeps all hook URLs relative (works for same-origin apps).
-     * Set to 'https://cms.revealui.com' when consuming from a different origin.
+     * Set to 'https://admin.revealui.com' when consuming from a different origin.
      */
     proxyBaseUrl: string;
     debug: boolean;
@@ -18,7 +18,7 @@ interface ElectricContextValue {
  * Provides ElectricSQL configuration to child hooks (`useConversations`, `useCollabDocument`).
  *
  * Provides proxyBaseUrl (and optional serviceUrl/debug) to child hooks via context.
- * All hooks use the CMS proxy pattern — no direct Electric connection is established here.
+ * All hooks use the admin proxy pattern  -  no direct Electric connection is established here.
  */
 export declare function ElectricProvider(props: {
     children: ReactNode;

package/dist/provider/index.js

@@ -10,7 +10,7 @@ const ElectricContext = createContext({
  * Provides ElectricSQL configuration to child hooks (`useConversations`, `useCollabDocument`).
  *
  * Provides proxyBaseUrl (and optional serviceUrl/debug) to child hooks via context.
- * All hooks use the CMS proxy pattern — no direct Electric connection is established here.
+ * All hooks use the admin proxy pattern  -  no direct Electric connection is established here.
  */
 export function ElectricProvider(props) {
     const value = useMemo(() => ({

package/package.json

@@ -1,28 +1,29 @@
 {
   "name": "@revealui/sync",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "ElectricSQL sync utilities for RevealUI",
   "license": "MIT",
   "dependencies": {
-    "@electric-sql/react": "^1.0.27",
+    "@electric-sql/react": "^1.0.43",
     "lib0": "^0.2.117",
-    "ws": "^8.18.0",
+    "ws": "^8.20.0",
     "y-protocols": "^1.0.7",
-    "yjs": "^13.6.29",
-    "@revealui/contracts": "1.3.6",
-    "@revealui/db": "0.3.6"
+    "yjs": "^13.6.30",
+    "@revealui/cache": "0.1.4",
+    "@revealui/contracts": "1.3.7",
+    "@revealui/db": "0.3.7"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.6.4",
-    "@testing-library/react": "^16.3.0",
-    "@types/ws": "^8.5.14",
-    "@vitest/coverage-v8": "^4.1.0",
-    "jsdom": "^29.0.1",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^4.1.3",
+    "jsdom": "29.0.1",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.0",
-    "dev": "0.0.1"
+    "vitest": "^4.1.3",
+    "@revealui/dev": "0.1.0"
   },
   "engines": {
     "node": ">=24.13.0"
@@ -61,6 +62,18 @@
     "url": "https://github.com/RevealUIStudio/revealui.git",
     "directory": "packages/sync"
   },
+  "homepage": "https://revealui.com",
+  "author": "RevealUI Studio <founder@revealui.com>",
+  "bugs": {
+    "url": "https://github.com/RevealUIStudio/revealui/issues"
+  },
+  "keywords": [
+    "revealui",
+    "sync",
+    "real-time",
+    "electricsql",
+    "collaborative"
+  ],
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",