@revealui/sync 0.3.3 → 0.3.5

package/README.md

@@ -182,6 +182,20 @@ pnpm --filter @revealui/sync test       # Run tests
 pnpm --filter @revealui/sync typecheck  # Type check
 ```
 
+## When to Use This
+
+- 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
+
+## 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
+- **Hermetic**: All mutations go through authenticated REST endpoints; ElectricSQL replication is read-only on the client
+
 ## License
 
 MIT

package/dist/components/SyncStatusIndicator.d.ts

@@ -0,0 +1,17 @@
+interface SyncStatusIndicatorProps {
+    /** Optional CSS class name for positioning or layout overrides. */
+    className?: string;
+    /** Whether data is currently being synced. */
+    isSyncing?: boolean;
+}
+/**
+ * Visual indicator for sync / connectivity status.
+ *
+ * - **Online + synced**: green dot
+ * - **Online + syncing**: pulsing yellow dot
+ * - **Offline**: red dot with "Offline" label
+ * - **Recently reconnected**: green dot with "Synced" label (fades after 3 s)
+ */
+export declare function SyncStatusIndicator(props: SyncStatusIndicatorProps): React.ReactNode;
+export {};
+//# sourceMappingURL=SyncStatusIndicator.d.ts.map

package/dist/components/SyncStatusIndicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyncStatusIndicator.d.ts","sourceRoot":"","sources":["../../src/components/SyncStatusIndicator.tsx"],"names":[],"mappings":"AAQA,UAAU,wBAAwB;IAChC,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,KAAK,CAAC,SAAS,CAgEpF"}

package/dist/components/SyncStatusIndicator.js

@@ -0,0 +1,65 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { useOnlineStatus } from '../hooks/useOnlineStatus.js';
+/** Duration in ms before the "Synced" label fades away. */
+const SYNCED_LABEL_DURATION_MS = 3_000;
+/**
+ * Visual indicator for sync / connectivity status.
+ *
+ * - **Online + synced**: green dot
+ * - **Online + syncing**: pulsing yellow dot
+ * - **Offline**: red dot with "Offline" label
+ * - **Recently reconnected**: green dot with "Synced" label (fades after 3 s)
+ */
+export function SyncStatusIndicator(props) {
+    const { className, isSyncing = false } = props;
+    const { isOnline, wasOffline } = useOnlineStatus();
+    // Show "Synced" label for 3 s after reconnection.
+    const [showSyncedLabel, setShowSyncedLabel] = useState(false);
+    useEffect(() => {
+        if (!wasOffline) {
+            return;
+        }
+        setShowSyncedLabel(true);
+        const timer = setTimeout(() => {
+            setShowSyncedLabel(false);
+        }, SYNCED_LABEL_DURATION_MS);
+        return () => clearTimeout(timer);
+    }, [wasOffline]);
+    // Determine dot color and label.
+    let dotColor;
+    let label = null;
+    let pulse = false;
+    if (!isOnline) {
+        dotColor = '#ef4444'; // red-500
+        label = 'Offline';
+    }
+    else if (isSyncing) {
+        dotColor = '#eab308'; // yellow-500
+        pulse = true;
+    }
+    else if (showSyncedLabel) {
+        dotColor = '#22c55e'; // green-500
+        label = 'Synced';
+    }
+    else {
+        dotColor = '#22c55e'; // green-500
+    }
+    const dotStyle = {
+        display: 'inline-block',
+        width: '8px',
+        height: '8px',
+        borderRadius: '50%',
+        backgroundColor: dotColor,
+        animation: pulse ? 'revealui-pulse 1.5s ease-in-out infinite' : undefined,
+    };
+    const containerStyle = {
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: '6px',
+        fontSize: '12px',
+        lineHeight: '1',
+    };
+    return (_jsxs("span", { className: className, style: containerStyle, role: "status", "aria-label": label ?? 'Online', children: [_jsx("span", { style: dotStyle }), label !== null ? _jsx("span", { children: label }) : null, pulse ? (_jsx("style", { children: '@keyframes revealui-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.4; } }' })) : null] }));
+}

package/dist/hooks/index.d.ts

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

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

@@ -0,0 +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"}

package/dist/hooks/index.js

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

package/dist/hooks/useOfflineCache.d.ts

@@ -0,0 +1,32 @@
+interface UseOfflineCacheOptions {
+    /** ElectricSQL shape subscription URL. */
+    shapeUrl: string;
+    /** Unique key for the localStorage cache entry. */
+    cacheKey: string;
+    /** How long cached data is considered fresh (seconds). Defaults to 3600. */
+    ttlSeconds?: number;
+}
+interface UseOfflineCacheResult<T> {
+    /** The current data — live from the shape when online, cached when offline. */
+    data: T[];
+    /** Whether the browser has network connectivity. */
+    isOnline: boolean;
+    /** Whether the shape subscription is currently loading fresh data. */
+    isSyncing: boolean;
+    /** Timestamp of the most recent successful sync to cache. */
+    lastSyncedAt: Date | null;
+    /** Shape subscription or cache-read error, if any. */
+    error: Error | null;
+}
+/**
+ * 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.
+ *
+ * @typeParam T - Row type returned by the shape subscription.
+ */
+export declare function useOfflineCache<T>(options: UseOfflineCacheOptions): UseOfflineCacheResult<T>;
+export {};
+//# sourceMappingURL=useOfflineCache.d.ts.map

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

@@ -0,0 +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"}

package/dist/hooks/useOfflineCache.js

@@ -0,0 +1,129 @@
+'use client';
+import { useShape } from '@electric-sql/react';
+import { 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;
+    }
+}
+/**
+ * Read cached data from localStorage. Returns `null` when the entry is
+ * missing, expired, or unreadable.
+ */
+function readCache(cacheKey, ttlSeconds) {
+    if (!hasLocalStorage()) {
+        return null;
+    }
+    try {
+        const raw = window.localStorage.getItem(CACHE_PREFIX + cacheKey);
+        if (raw === null) {
+            return null;
+        }
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.data)) {
+            return null;
+        }
+        // Check TTL.
+        const cachedTime = new Date(parsed.cachedAt).getTime();
+        if (Number.isNaN(cachedTime)) {
+            return null;
+        }
+        const ageSeconds = (Date.now() - cachedTime) / 1_000;
+        if (ageSeconds > ttlSeconds) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write data to the localStorage cache. Silently ignores failures.
+ */
+function writeCache(cacheKey, data) {
+    if (!hasLocalStorage()) {
+        return;
+    }
+    try {
+        const payload = {
+            data,
+            cachedAt: new Date().toISOString(),
+        };
+        window.localStorage.setItem(CACHE_PREFIX + cacheKey, JSON.stringify(payload));
+    }
+    catch {
+        // Quota exceeded or private browsing — drop silently.
+    }
+}
+/**
+ * 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.
+ *
+ * @typeParam T - Row type returned by the shape subscription.
+ */
+export function useOfflineCache(options) {
+    const { shapeUrl, cacheKey, ttlSeconds = DEFAULT_TTL_SECONDS } = 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.
+    const cacheKeyRef = useRef(cacheKey);
+    cacheKeyRef.current = cacheKey;
+    // Persist live data to cache whenever the shape delivers fresh rows.
+    const shapeData = shape.data;
+    useEffect(() => {
+        if (!isOnline) {
+            return;
+        }
+        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.
+    if (isOnline && Array.isArray(shapeData) && shapeData.length > 0) {
+        return {
+            data: toRecords(shapeData),
+            isOnline,
+            isSyncing: shape.isLoading,
+            lastSyncedAt,
+            error: shape.error || null,
+        };
+    }
+    // Offline or shape has not loaded yet — try the cache.
+    const cached = readCache(cacheKey, ttlSeconds);
+    const cachedSyncDate = cached !== null ? new Date(cached.cachedAt) : null;
+    return {
+        data: cached?.data ?? [],
+        isOnline,
+        isSyncing: isOnline && shape.isLoading,
+        lastSyncedAt: lastSyncedAt ?? cachedSyncDate,
+        error: shape.error || null,
+    };
+}

package/dist/hooks/useOnlineStatus.d.ts

@@ -0,0 +1,21 @@
+export interface OnlineStatusResult {
+    /** Whether the browser currently has network connectivity. */
+    isOnline: boolean;
+    /** Whether the connection was recently restored (resets after 5 s). */
+    wasOffline: boolean;
+    /** Timestamp of the last time the browser was confirmed online. */
+    lastOnlineAt: Date | null;
+}
+/**
+ * Track browser online/offline status with reconnection awareness.
+ *
+ * - `isOnline` reflects `navigator.onLine` and live `online`/`offline` events.
+ * - `wasOffline` becomes `true` when connectivity is restored and resets to
+ *   `false` after 5 seconds.
+ * - `lastOnlineAt` records the most recent reconnection timestamp.
+ *
+ * During SSR (when `window` is not available) the hook returns
+ * `{ isOnline: true, wasOffline: false, lastOnlineAt: null }`.
+ */
+export declare function useOnlineStatus(): OnlineStatusResult;
+//# sourceMappingURL=useOnlineStatus.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useOnlineStatus.d.ts","sourceRoot":"","sources":["../../src/hooks/useOnlineStatus.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,UAAU,EAAE,OAAO,CAAC;IACpB,mEAAmE;IACnE,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;CAC3B;AAiBD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,kBAAkB,CAuDpD"}

package/dist/hooks/useOnlineStatus.js

@@ -0,0 +1,74 @@
+'use client';
+import { useEffect, useRef, useState } from 'react';
+/** Duration in ms before `wasOffline` resets after reconnection. */
+const WAS_OFFLINE_RESET_MS = 5_000;
+/** SSR-safe default: assume online when `window` is unavailable. */
+const SSR_DEFAULT = {
+    isOnline: true,
+    wasOffline: false,
+    lastOnlineAt: null,
+};
+/**
+ * Check whether the current environment is a browser.
+ * Returns `false` during SSR / Node.js test runs without a DOM.
+ */
+function isBrowser() {
+    return typeof window !== 'undefined';
+}
+/**
+ * Track browser online/offline status with reconnection awareness.
+ *
+ * - `isOnline` reflects `navigator.onLine` and live `online`/`offline` events.
+ * - `wasOffline` becomes `true` when connectivity is restored and resets to
+ *   `false` after 5 seconds.
+ * - `lastOnlineAt` records the most recent reconnection timestamp.
+ *
+ * During SSR (when `window` is not available) the hook returns
+ * `{ isOnline: true, wasOffline: false, lastOnlineAt: null }`.
+ */
+export function useOnlineStatus() {
+    const [isOnline, setIsOnline] = useState(() => (isBrowser() ? navigator.onLine : true));
+    const [wasOffline, setWasOffline] = useState(false);
+    const [lastOnlineAt, setLastOnlineAt] = useState(null);
+    const resetTimerRef = useRef(null);
+    useEffect(() => {
+        // No-op during SSR — the effect only runs in the browser.
+        if (!isBrowser()) {
+            return;
+        }
+        function handleOnline() {
+            setIsOnline(true);
+            setLastOnlineAt(new Date());
+            setWasOffline(true);
+            // Clear any existing timer before setting a new one.
+            if (resetTimerRef.current !== null) {
+                clearTimeout(resetTimerRef.current);
+            }
+            resetTimerRef.current = setTimeout(() => {
+                setWasOffline(false);
+                resetTimerRef.current = null;
+            }, WAS_OFFLINE_RESET_MS);
+        }
+        function handleOffline() {
+            setIsOnline(false);
+            setWasOffline(false);
+            if (resetTimerRef.current !== null) {
+                clearTimeout(resetTimerRef.current);
+                resetTimerRef.current = null;
+            }
+        }
+        window.addEventListener('online', handleOnline);
+        window.addEventListener('offline', handleOffline);
+        return () => {
+            window.removeEventListener('online', handleOnline);
+            window.removeEventListener('offline', handleOffline);
+            if (resetTimerRef.current !== null) {
+                clearTimeout(resetTimerRef.current);
+            }
+        };
+    }, []);
+    if (!isBrowser()) {
+        return SSR_DEFAULT;
+    }
+    return { isOnline, wasOffline, lastOnlineAt };
+}

package/dist/offline-queue.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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. */
+export interface OfflineMutation {
+    /** Unique identifier for this mutation (UUID). */
+    id: string;
+    /** Database table the mutation targets. */
+    table: string;
+    /** Type of operation. */
+    operation: 'insert' | 'update' | 'delete';
+    /** Mutation payload (row data or partial update). */
+    data: Record<string, unknown>;
+    /** ISO-8601 timestamp when the mutation was enqueued. */
+    timestamp: string;
+}
+/**
+ * Manages a FIFO queue of mutations that were created while the browser
+ * was offline. Mutations are persisted in `localStorage` under the key
+ * `revealui:offline-queue`.
+ *
+ * All operations are no-ops when `localStorage` is unavailable (SSR,
+ * private browsing that throws, etc.).
+ */
+export declare class OfflineMutationQueue {
+    /**
+     * Add a mutation to the end of the queue.
+     *
+     * @param mutation - The mutation to enqueue (must include a unique `id`).
+     */
+    enqueue(mutation: OfflineMutation): void;
+    /**
+     * Execute all queued mutations in order via the provided executor.
+     * Each mutation is removed from the persisted queue only after the
+     * executor resolves successfully. Processing stops at the first failure
+     * so ordering is preserved.
+     *
+     * @param executor - Async function that sends a single mutation to the server.
+     */
+    flush(executor: (mutation: OfflineMutation) => Promise<void>): Promise<void>;
+    /**
+     * Return all pending mutations without removing them.
+     */
+    peek(): OfflineMutation[];
+    /**
+     * Number of mutations currently in the queue.
+     */
+    get size(): number;
+    /**
+     * Remove all pending mutations from the queue.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=offline-queue.d.ts.map

package/dist/offline-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline-queue.d.ts","sourceRoot":"","sources":["../src/offline-queue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC1C,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;CACnB;AA0DD;;;;;;;GAOG;AACH,qBAAa,oBAAoB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAMxC;;;;;;;OAOG;IACG,KAAK,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlF;;OAEG;IACH,IAAI,IAAI,eAAe,EAAE;IAIzB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;CAUd"}

package/dist/offline-queue.js

@@ -0,0 +1,126 @@
+/**
+ * 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. */
+const STORAGE_KEY = 'revealui:offline-queue';
+/**
+ * Check whether `localStorage` is available.
+ * Returns `false` during SSR or in private-browsing contexts that throw on access.
+ */
+function hasLocalStorage() {
+    if (typeof window === 'undefined') {
+        return false;
+    }
+    try {
+        const testKey = '__revealui_ls_test__';
+        window.localStorage.setItem(testKey, '1');
+        window.localStorage.removeItem(testKey);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the current queue from localStorage.
+ * Returns an empty array when storage is unavailable or the data is corrupt.
+ */
+function readQueue() {
+    if (!hasLocalStorage()) {
+        return [];
+    }
+    try {
+        const raw = window.localStorage.getItem(STORAGE_KEY);
+        if (raw === null) {
+            return [];
+        }
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+        return parsed;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Persist the queue to localStorage.
+ * Silently ignores errors (e.g. quota exceeded, private browsing).
+ */
+function writeQueue(queue) {
+    if (!hasLocalStorage()) {
+        return;
+    }
+    try {
+        window.localStorage.setItem(STORAGE_KEY, JSON.stringify(queue));
+    }
+    catch {
+        // Quota exceeded or private browsing — drop silently.
+    }
+}
+/**
+ * Manages a FIFO queue of mutations that were created while the browser
+ * was offline. Mutations are persisted in `localStorage` under the key
+ * `revealui:offline-queue`.
+ *
+ * All operations are no-ops when `localStorage` is unavailable (SSR,
+ * private browsing that throws, etc.).
+ */
+export class OfflineMutationQueue {
+    /**
+     * Add a mutation to the end of the queue.
+     *
+     * @param mutation - The mutation to enqueue (must include a unique `id`).
+     */
+    enqueue(mutation) {
+        const queue = readQueue();
+        queue.push(mutation);
+        writeQueue(queue);
+    }
+    /**
+     * Execute all queued mutations in order via the provided executor.
+     * Each mutation is removed from the persisted queue only after the
+     * executor resolves successfully. Processing stops at the first failure
+     * so ordering is preserved.
+     *
+     * @param executor - Async function that sends a single mutation to the server.
+     */
+    async flush(executor) {
+        const queue = readQueue();
+        for (const mutation of queue) {
+            await executor(mutation);
+            // Remove the successfully-processed mutation from storage.
+            const current = readQueue();
+            const updated = current.filter((m) => m.id !== mutation.id);
+            writeQueue(updated);
+        }
+    }
+    /**
+     * Return all pending mutations without removing them.
+     */
+    peek() {
+        return readQueue();
+    }
+    /**
+     * Number of mutations currently in the queue.
+     */
+    get size() {
+        return readQueue().length;
+    }
+    /**
+     * Remove all pending mutations from the queue.
+     */
+    clear() {
+        if (!hasLocalStorage()) {
+            return;
+        }
+        try {
+            window.localStorage.removeItem(STORAGE_KEY);
+        }
+        catch {
+            // Ignore — same guard as writeQueue.
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revealui/sync",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "ElectricSQL sync utilities for RevealUI",
   "license": "MIT",
   "dependencies": {
@@ -9,8 +9,8 @@
     "ws": "^8.18.0",
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.29",
-    "@revealui/db": "0.3.3",
-    "@revealui/contracts": "1.3.3"
+    "@revealui/contracts": "1.3.5",
+    "@revealui/db": "0.3.5"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.4",