@interop/was-react 0.1.0

package/dist/storage/rehydrate.test.js

@@ -0,0 +1,172 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { setLocalStore, clearLocalStore } from './storageManager.js';
+import { patchFromChange, hydrateAll, clearAllEntityStores, scheduleRehydrate } from './rehydrate.js';
+// A fake LocalStore: `decryptEnvelope` unwraps `{ jwe: payload }` (mirroring the
+// lww handler test's fake cipher); the envelope index calls just record.
+function makeFakeStore({ failDecrypt = false } = {}) {
+    const remembered = [];
+    const forgotten = [];
+    const store = {
+        decryptEnvelope: async (_key, envelope) => {
+            if (failDecrypt) {
+                throw new Error('decrypt failed');
+            }
+            return envelope.jwe;
+        },
+        rememberEnvelope: (key, uuid, envelopeId) => {
+            remembered.push([key, uuid, envelopeId]);
+        },
+        forgetEnvelope: (key, uuid) => {
+            forgotten.push([key, uuid]);
+        }
+    };
+    return { store, remembered, forgotten };
+}
+// A fake registry entry that records what the mechanism drives.
+function makeRegistry() {
+    const calls = {
+        hydrate: 0,
+        upsert: [],
+        drop: [],
+        clear: 0
+    };
+    const registry = {
+        notes: {
+            hydrate: async () => {
+                calls.hydrate += 1;
+            },
+            upsert: doc => {
+                calls.upsert.push(doc);
+            },
+            drop: uuid => {
+                calls.drop.push(uuid);
+            },
+            clear: () => {
+                calls.clear += 1;
+            }
+        }
+    };
+    return { registry, calls };
+}
+function envelope(payload) {
+    return { jwe: payload };
+}
+afterEach(() => {
+    clearLocalStore();
+});
+describe('rehydrate mechanism', () => {
+    it('hydrateAll drives every registry entry', async () => {
+        const { registry, calls } = makeRegistry();
+        await hydrateAll(registry);
+        expect(calls.hydrate).toBe(1);
+    });
+    it('clearAllEntityStores drives every registry entry', () => {
+        const { registry, calls } = makeRegistry();
+        clearAllEntityStores(registry);
+        expect(calls.clear).toBe(1);
+    });
+    describe('patchFromChange', () => {
+        beforeEach(() => {
+            const { store } = makeFakeStore();
+            setLocalStore(store);
+        });
+        it('upserts an inserted payload and remembers its envelope', async () => {
+            const { store, remembered } = makeFakeStore();
+            setLocalStore(store);
+            const { registry, calls } = makeRegistry();
+            const payload = { id: 'note-1' };
+            await patchFromChange(registry, 'notes', {
+                operation: 'INSERT',
+                documentData: { id: 'env-1', data: envelope(payload) }
+            });
+            expect(calls.upsert).toEqual([payload]);
+            expect(calls.drop).toEqual([]);
+            expect(remembered).toEqual([['notes', 'note-1', 'env-1']]);
+        });
+        it('drops a deleted payload and forgets its envelope', async () => {
+            const { store, forgotten } = makeFakeStore();
+            setLocalStore(store);
+            const { registry, calls } = makeRegistry();
+            await patchFromChange(registry, 'notes', {
+                operation: 'DELETE',
+                documentData: { id: 'env-1', data: envelope({ id: 'note-1' }) }
+            });
+            expect(calls.drop).toEqual(['note-1']);
+            expect(calls.upsert).toEqual([]);
+            expect(forgotten).toEqual([['notes', 'note-1']]);
+        });
+        it('drops on a soft-delete (_deleted) row', async () => {
+            const { store } = makeFakeStore();
+            setLocalStore(store);
+            const { registry, calls } = makeRegistry();
+            await patchFromChange(registry, 'notes', {
+                operation: 'UPDATE',
+                documentData: {
+                    id: 'env-1',
+                    data: envelope({ id: 'note-1' }),
+                    _deleted: true
+                }
+            });
+            expect(calls.drop).toEqual(['note-1']);
+        });
+        it('is a no-op for an unregistered collection', async () => {
+            const { registry, calls } = makeRegistry();
+            await patchFromChange(registry, 'unknown', {
+                operation: 'INSERT',
+                documentData: { id: 'env-1', data: envelope({ id: 'x' }) }
+            });
+            expect(calls.upsert).toEqual([]);
+            expect(calls.drop).toEqual([]);
+        });
+        it('schedules a re-hydrate when the envelope is missing', async () => {
+            vi.useFakeTimers();
+            try {
+                const { registry, calls } = makeRegistry();
+                await patchFromChange(registry, 'notes', {
+                    operation: 'INSERT',
+                    documentData: { id: 'env-1' }
+                });
+                expect(calls.upsert).toEqual([]);
+                await vi.advanceTimersByTimeAsync(60);
+                expect(calls.hydrate).toBe(1);
+            }
+            finally {
+                vi.useRealTimers();
+            }
+        });
+        it('schedules a re-hydrate when decryption fails', async () => {
+            vi.useFakeTimers();
+            try {
+                const { store } = makeFakeStore({ failDecrypt: true });
+                setLocalStore(store);
+                const { registry, calls } = makeRegistry();
+                await patchFromChange(registry, 'notes', {
+                    operation: 'INSERT',
+                    documentData: { id: 'env-1', data: envelope({ id: 'note-1' }) }
+                });
+                expect(calls.upsert).toEqual([]);
+                await vi.advanceTimersByTimeAsync(60);
+                expect(calls.hydrate).toBe(1);
+            }
+            finally {
+                vi.useRealTimers();
+            }
+        });
+    });
+    it('scheduleRehydrate is a no-op for an unregistered collection', () => {
+        vi.useFakeTimers();
+        try {
+            const { registry, calls } = makeRegistry();
+            scheduleRehydrate(registry, 'unknown');
+            vi.advanceTimersByTime(60);
+            expect(calls.hydrate).toBe(0);
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+});
+//# sourceMappingURL=rehydrate.test.js.map

package/dist/storage/rehydrate.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehydrate.test.js","sourceRoot":"","sources":["../../src/storage/rehydrate.test.ts"],"names":[],"mappings":"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"}

package/dist/storage/storageManager.d.ts

@@ -0,0 +1,39 @@
+import type { LocalStore } from './localStore.js';
+/**
+ * Installs the opened store (called once by the app bootstrap).
+ *
+ * @param store {LocalStore}
+ * @returns {void}
+ */
+export declare function setLocalStore(store: LocalStore): void;
+/**
+ * The opened store, or throws if the app has not bootstrapped yet.
+ *
+ * @returns {LocalStore}
+ */
+export declare function requireStore(): LocalStore;
+/**
+ * Whether the store has been opened.
+ *
+ * @returns {boolean}
+ */
+export declare function hasStore(): boolean;
+/**
+ * Releases the held store reference (logout; the caller closes the db).
+ *
+ * @returns {void}
+ */
+export declare function clearLocalStore(): void;
+/**
+ * A stable per-install device id (the last-write-wins tiebreak stamped into
+ * every payload), persisted in localStorage under `<prefix>deviceId`.
+ *
+ * @param [options] {object}
+ * @param [options.storageKeyPrefix] {string}   the localStorage key prefix
+ *   (defaults to {@link DEFAULT_STORAGE_KEY_PREFIX})
+ * @returns {string}
+ */
+export declare function getDeviceId({ storageKeyPrefix }?: {
+    storageKeyPrefix?: string;
+}): string;
+//# sourceMappingURL=storageManager.d.ts.map

package/dist/storage/storageManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageManager.d.ts","sourceRoot":"","sources":["../../src/storage/storageManager.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAIjD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAErD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,UAAU,CAKzC;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAElC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,EAC1B,gBAA6C,EAC9C,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAQ7C"}

package/dist/storage/storageManager.js

@@ -0,0 +1,68 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The storage manager: a thin process-wide holder for the one {@link LocalStore}
+ * instance plus the per-install device id. Entity stores reach for the store
+ * through {@link requireStore} inside their CRUD actions rather than importing it
+ * directly, which keeps this module free of store imports (no cycle) and lets
+ * the app own the init/hydrate ordering.
+ */
+import { uuidv7 } from 'uuidv7';
+import { DEFAULT_STORAGE_KEY_PREFIX } from '../config.js';
+let localStore = null;
+/**
+ * Installs the opened store (called once by the app bootstrap).
+ *
+ * @param store {LocalStore}
+ * @returns {void}
+ */
+export function setLocalStore(store) {
+    localStore = store;
+}
+/**
+ * The opened store, or throws if the app has not bootstrapped yet.
+ *
+ * @returns {LocalStore}
+ */
+export function requireStore() {
+    if (!localStore) {
+        throw new Error('LocalStore is not initialized; open it first.');
+    }
+    return localStore;
+}
+/**
+ * Whether the store has been opened.
+ *
+ * @returns {boolean}
+ */
+export function hasStore() {
+    return localStore !== null;
+}
+/**
+ * Releases the held store reference (logout; the caller closes the db).
+ *
+ * @returns {void}
+ */
+export function clearLocalStore() {
+    localStore = null;
+}
+/**
+ * A stable per-install device id (the last-write-wins tiebreak stamped into
+ * every payload), persisted in localStorage under `<prefix>deviceId`.
+ *
+ * @param [options] {object}
+ * @param [options.storageKeyPrefix] {string}   the localStorage key prefix
+ *   (defaults to {@link DEFAULT_STORAGE_KEY_PREFIX})
+ * @returns {string}
+ */
+export function getDeviceId({ storageKeyPrefix = DEFAULT_STORAGE_KEY_PREFIX } = {}) {
+    const deviceIdKey = `${storageKeyPrefix}deviceId`;
+    let id = localStorage.getItem(deviceIdKey);
+    if (!id) {
+        id = uuidv7();
+        localStorage.setItem(deviceIdKey, id);
+    }
+    return id;
+}
+//# sourceMappingURL=storageManager.js.map

package/dist/storage/storageManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageManager.js","sourceRoot":"","sources":["../../src/storage/storageManager.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;GAMG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AAGzD,IAAI,UAAU,GAAsB,IAAI,CAAA;AAExC;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,UAAU,GAAG,KAAK,CAAA;AACpB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY;IAC1B,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAA;IAClE,CAAC;IACD,OAAO,UAAU,CAAA;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO,UAAU,KAAK,IAAI,CAAA;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,UAAU,GAAG,IAAI,CAAA;AACnB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,EAC1B,gBAAgB,GAAG,0BAA0B,KACZ,EAAE;IACnC,MAAM,WAAW,GAAG,GAAG,gBAAgB,UAAU,CAAA;IACjD,IAAI,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;IAC1C,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,EAAE,GAAG,MAAM,EAAE,CAAA;QACb,YAAY,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAA;IACvC,CAAC;IACD,OAAO,EAAE,CAAA;AACX,CAAC"}

package/dist/storage/syncController.d.ts

@@ -0,0 +1,79 @@
+import type { RxChangeEvent } from 'rxdb/plugins/core';
+import { type SyncedDoc } from '../sync/index.js';
+import { type WasCollectionConfig, type WasSyncConfig } from '../config.js';
+import type { LocalStore } from './localStore.js';
+import type { WasRemoteStore } from './wasRemoteStore.js';
+/**
+ * Whether a replication error (an RxError wrapping the port's thrown errors)
+ * carries an HTTP 401/403 anywhere in its tree -- the storage-access-expired
+ * signal.
+ *
+ * @param err {unknown}
+ * @returns {boolean}
+ */
+export declare function isAuthError(err: unknown): boolean;
+/**
+ * A per-session controller around background replication. Construct via
+ * {@link createSyncController}.
+ */
+export declare class SyncController {
+    private _collections;
+    private _sync;
+    private _replications;
+    private _onlineHandler?;
+    private _pollTimer?;
+    private _started;
+    constructor({ collections, sync }: {
+        collections: WasCollectionConfig[];
+        sync?: WasSyncConfig;
+    });
+    /**
+     * Starts background replication for every entity collection covered by the
+     * grant set. Idempotent (a no-op if already running).
+     *
+     * @param options {object}
+     * @param options.remoteStore {WasRemoteStore}
+     * @param options.localStore {LocalStore}
+     * @param [options.onRemoteChange] {(collectionKey: string, event) => void}
+     *   fired per RxDB change (pull or conflict-resolved push) for reactive
+     *   per-doc store patching
+     * @param [options.onAuthError] {() => void}   fired when a replication error
+     *   carries a 401/403 (storage access expired/revoked)
+     * @returns {Promise<void>}
+     */
+    start({ remoteStore, localStore, onRemoteChange, onAuthError }: {
+        remoteStore: WasRemoteStore;
+        localStore: LocalStore;
+        onRemoteChange?: (collectionKey: string, event: RxChangeEvent<SyncedDoc>) => void;
+        onAuthError?: () => void;
+    }): Promise<void>;
+    /**
+     * Triggers an immediate replication cycle on every running collection, rather
+     * than waiting for RxDB's next scheduled tick. Fire-and-forget.
+     *
+     * @returns {void}
+     */
+    reSync(): void;
+    /**
+     * Stops replication and releases resources (the database is owned by the
+     * caller). Idempotent.
+     *
+     * @returns {Promise<void>}
+     */
+    stop(): Promise<void>;
+}
+/**
+ * Builds a fresh {@link SyncController} bound to the collection registry and
+ * sync tuning. Prefer one controller per session (started once, stopped on
+ * logout) over a module-level singleton.
+ *
+ * @param options {object}
+ * @param options.collections {WasCollectionConfig[]}
+ * @param [options.sync] {WasSyncConfig}
+ * @returns {SyncController}
+ */
+export declare function createSyncController({ collections, sync }: {
+    collections: WasCollectionConfig[];
+    sync?: WasSyncConfig;
+}): SyncController;
+//# sourceMappingURL=syncController.d.ts.map

package/dist/storage/syncController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncController.d.ts","sourceRoot":"","sources":["../../src/storage/syncController.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,aAAa,EACnB,MAAM,cAAc,CAAA;AACrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAMzD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAoCjD;AAOD;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,aAAa,CAA8B;IACnD,OAAO,CAAC,cAAc,CAAC,CAAY;IACnC,OAAO,CAAC,UAAU,CAAC,CAAgC;IACnD,OAAO,CAAC,QAAQ,CAAQ;gBAEZ,EACV,WAAW,EACX,IAAI,EACL,EAAE;QACD,WAAW,EAAE,mBAAmB,EAAE,CAAA;QAClC,IAAI,CAAC,EAAE,aAAa,CAAA;KACrB;IAKD;;;;;;;;;;;;;OAaG;IACG,KAAK,CAAC,EACV,WAAW,EACX,UAAU,EACV,cAAc,EACd,WAAW,EACZ,EAAE;QACD,WAAW,EAAE,cAAc,CAAA;QAC3B,UAAU,EAAE,UAAU,CAAA;QACtB,cAAc,CAAC,EAAE,CACf,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,KAC5B,IAAI,CAAA;QACT,WAAW,CAAC,EAAE,MAAM,IAAI,CAAA;KACzB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuEjB;;;;;OAKG;IACH,MAAM,IAAI,IAAI;IAMd;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAuB5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,WAAW,EACX,IAAI,EACL,EAAE;IACD,WAAW,EAAE,mBAAmB,EAAE,CAAA;IAClC,IAAI,CAAC,EAAE,aAAa,CAAA;CACrB,GAAG,cAAc,CAEjB"}

package/dist/storage/syncController.js

@@ -0,0 +1,189 @@
+import { createWasReplication, createWasSyncPort, withFeedMasterRead } from '../sync/index.js';
+import { DEFAULT_SYNC_POLL_MS } from '../config.js';
+import { useSyncStatusStore } from './syncStatusStore.js';
+/**
+ * Whether a replication error (an RxError wrapping the port's thrown errors)
+ * carries an HTTP 401/403 anywhere in its tree -- the storage-access-expired
+ * signal.
+ *
+ * @param err {unknown}
+ * @returns {boolean}
+ */
+export function isAuthError(err) {
+    const seen = new Set();
+    const queue = [err];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === null || typeof current !== 'object' || seen.has(current)) {
+            continue;
+        }
+        seen.add(current);
+        const candidate = current;
+        const statuses = [
+            candidate.status,
+            candidate.statusCode,
+            candidate.response?.status
+        ];
+        if (statuses.includes(401) || statuses.includes(403)) {
+            return true;
+        }
+        if (candidate.cause) {
+            queue.push(candidate.cause);
+        }
+        if (Array.isArray(candidate.errors)) {
+            queue.push(...candidate.errors);
+        }
+        if (Array.isArray(candidate.parameters?.errors)) {
+            queue.push(...candidate.parameters.errors);
+        }
+    }
+    return false;
+}
+/**
+ * A per-session controller around background replication. Construct via
+ * {@link createSyncController}.
+ */
+export class SyncController {
+    _collections;
+    _sync;
+    _replications = [];
+    _onlineHandler;
+    _pollTimer;
+    _started = false;
+    constructor({ collections, sync }) {
+        this._collections = collections;
+        this._sync = sync ?? {};
+    }
+    /**
+     * Starts background replication for every entity collection covered by the
+     * grant set. Idempotent (a no-op if already running).
+     *
+     * @param options {object}
+     * @param options.remoteStore {WasRemoteStore}
+     * @param options.localStore {LocalStore}
+     * @param [options.onRemoteChange] {(collectionKey: string, event) => void}
+     *   fired per RxDB change (pull or conflict-resolved push) for reactive
+     *   per-doc store patching
+     * @param [options.onAuthError] {() => void}   fired when a replication error
+     *   carries a 401/403 (storage access expired/revoked)
+     * @returns {Promise<void>}
+     */
+    async start({ remoteStore, localStore, onRemoteChange, onAuthError }) {
+        if (this._started) {
+            return;
+        }
+        this._started = true;
+        const setStatus = useSyncStatusStore.getState().setStatus;
+        const batchSize = this._sync.batchSize;
+        const retryMs = this._sync.retryMs;
+        const pollMs = this._sync.pollMs ?? DEFAULT_SYNC_POLL_MS;
+        try {
+            for (const { key, id } of this._collections) {
+                setStatus(id, 'idle');
+                // Wrap the verbatim port so the 412 conflict re-read resolves `version`
+                // from the changes-feed body (CORS hides the `GET` ETag cross-origin).
+                const wasPort = withFeedMasterRead(createWasSyncPort({
+                    was: remoteStore.was,
+                    spaceId: remoteStore.spaceId,
+                    collectionId: id,
+                    ...(remoteStore.collectionCapability(id) && {
+                        capability: remoteStore.collectionCapability(id)
+                    })
+                }));
+                const state = createWasReplication({
+                    rxCollection: localStore.rxCollection(key),
+                    wasPort,
+                    replicationIdentifier: `was-sync:${remoteStore.serverUrl}:${remoteStore.spaceId}:${id}`,
+                    ...(batchSize !== undefined && { batchSize }),
+                    ...(retryMs !== undefined && { retryTime: retryMs })
+                });
+                const subscriptions = [
+                    state.active$.subscribe(active => {
+                        setStatus(id, active ? 'syncing' : 'synced');
+                    }),
+                    state.error$.subscribe(err => {
+                        console.error(`Sync error for "${id}":`, err);
+                        setStatus(id, 'error');
+                        if (onAuthError && isAuthError(err)) {
+                            onAuthError();
+                        }
+                    })
+                ];
+                if (onRemoteChange) {
+                    subscriptions.push(localStore
+                        .rxCollection(key)
+                        .$.subscribe(event => onRemoteChange(key, event)));
+                }
+                this._replications.push({ state, subscriptions });
+            }
+            this._onlineHandler = () => this.reSync();
+            window.addEventListener('online', this._onlineHandler);
+            // The pull side has no server-side live stream, so an already-open session
+            // would otherwise never see another device's edits. A low-frequency
+            // periodic reSync polls the changes feed so multi-device edits converge
+            // live (the change subscriptions above then patch the stores).
+            if (pollMs > 0) {
+                this._pollTimer = setInterval(() => this.reSync(), pollMs);
+            }
+        }
+        catch (err) {
+            console.error('Failed to start sync controller:', err);
+            await this.stop();
+        }
+    }
+    /**
+     * Triggers an immediate replication cycle on every running collection, rather
+     * than waiting for RxDB's next scheduled tick. Fire-and-forget.
+     *
+     * @returns {void}
+     */
+    reSync() {
+        for (const { state } of this._replications) {
+            state.reSync();
+        }
+    }
+    /**
+     * Stops replication and releases resources (the database is owned by the
+     * caller). Idempotent.
+     *
+     * @returns {Promise<void>}
+     */
+    async stop() {
+        if (this._onlineHandler) {
+            window.removeEventListener('online', this._onlineHandler);
+            this._onlineHandler = undefined;
+        }
+        if (this._pollTimer) {
+            clearInterval(this._pollTimer);
+            this._pollTimer = undefined;
+        }
+        for (const { state, subscriptions } of this._replications) {
+            for (const subscription of subscriptions) {
+                subscription.unsubscribe();
+            }
+            try {
+                await state.cancel();
+            }
+            catch (err) {
+                console.error('Error cancelling replication:', err);
+            }
+        }
+        this._replications = [];
+        useSyncStatusStore.getState().reset();
+        this._started = false;
+    }
+}
+/**
+ * Builds a fresh {@link SyncController} bound to the collection registry and
+ * sync tuning. Prefer one controller per session (started once, stopped on
+ * logout) over a module-level singleton.
+ *
+ * @param options {object}
+ * @param options.collections {WasCollectionConfig[]}
+ * @param [options.sync] {WasSyncConfig}
+ * @returns {SyncController}
+ */
+export function createSyncController({ collections, sync }) {
+    return new SyncController({ collections, ...(sync && { sync }) });
+}
+//# sourceMappingURL=syncController.js.map

package/dist/storage/syncController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncController.js","sourceRoot":"","sources":["../../src/storage/syncController.ts"],"names":[],"mappings":"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"}

package/dist/storage/syncStatusStore.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A single collection's replication status:
+ * - `idle`    -- configured but no cycle has run yet
+ * - `syncing` -- a pull/push cycle is in flight
+ * - `synced`  -- last cycle completed without error
+ * - `error`   -- last cycle failed (RxDB is backing off / will retry)
+ */
+export type SyncStatus = 'idle' | 'syncing' | 'synced' | 'error';
+interface SyncStatusState {
+    /** Keyed by WAS collection id (e.g. `action-items`). */
+    statuses: Record<string, SyncStatus>;
+    setStatus: (collectionId: string, status: SyncStatus) => void;
+    reset: () => void;
+}
+export declare const useSyncStatusStore: import("zustand").UseBoundStore<import("zustand").StoreApi<SyncStatusState>>;
+export {};
+//# sourceMappingURL=syncStatusStore.d.ts.map

package/dist/storage/syncStatusStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncStatusStore.d.ts","sourceRoot":"","sources":["../../src/storage/syncStatusStore.ts"],"names":[],"mappings":"AAYA;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAA;AAEhE,UAAU,eAAe;IACvB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACpC,SAAS,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAA;IAC7D,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED,eAAO,MAAM,kBAAkB,8EAO5B,CAAA"}

package/dist/storage/syncStatusStore.js

@@ -0,0 +1,19 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Zustand store holding per-collection replication status, mirroring the WAS
+ * per-replica sync-status vocabulary. The sync controller writes to it off the
+ * RxDB replication `active$` / `error$` streams; UI (e.g. a header indicator or
+ * a settings page) reads from it. In-memory only, like the session -- cleared on
+ * logout.
+ */
+import { create } from 'zustand';
+export const useSyncStatusStore = create()(set => ({
+    statuses: {},
+    setStatus: (collectionId, status) => set(state => ({
+        statuses: { ...state.statuses, [collectionId]: status }
+    })),
+    reset: () => set({ statuses: {} })
+}));
+//# sourceMappingURL=syncStatusStore.js.map

package/dist/storage/syncStatusStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncStatusStore.js","sourceRoot":"","sources":["../../src/storage/syncStatusStore.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;GAMG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAkBhC,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,EAAmB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClE,QAAQ,EAAE,EAAE;IACZ,SAAS,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,EAAE,CAClC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACZ,QAAQ,EAAE,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE;KACxD,CAAC,CAAC;IACL,KAAK,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;CACnC,CAAC,CAAC,CAAA"}