@interocitor/core 0.0.0-beta.6 → 0.0.0-beta.8

package/README.md

@@ -163,6 +163,32 @@ What we do **not** guarantee:
   manifest). See `docs/security-model.md`.
 - Recovery if the passphrase is lost — see "New device / restore".
 
+### Sync cadence
+
+The engine adapts how often it polls the remote so it does useful work
+when there is data to sync, and stays out of the way otherwise. This is
+all automatic — there is no configuration knob.
+
+- **Adaptive backoff.** Polling starts at `pollInterval` (30 s by
+  default). After every poll that merges zero entries the interval
+  doubles, capped at 60 s. Any poll that merges ≥ 1 entry resets the
+  interval back to base. The intent is to absorb idle bursts of clients
+  without hammering the remote, while still recovering immediately when
+  data starts flowing.
+- **Tab visibility.** When the host page is hidden
+  (`document.visibilityState === 'hidden'`) the current poll interval is
+  multiplied by 10 — backgrounded tabs poll lazily. When the tab becomes
+  visible again the interval is reset to base **and** an immediate
+  `pull()` is fired so foregrounded data jumps in without waiting for
+  the next tick. This is a standard SWR‑style refresh‑on‑focus pattern.
+  The listener is wired during `connect()` and torn down by
+  `disconnect()`; environments without `document` (e.g. Node) skip it.
+- **Push fallback.** Adapters that push invalidations (Cloudflare relay)
+  trigger an immediate pull and bypass the polling cadence entirely.
+  Polling is the safety net when the push channel is unavailable; the
+  WS connection itself uses bounded retries with a long cooldown after
+  repeated failed upgrades, so a misbehaving relay cannot DDoS itself.
+
 ## Setup lifecycle
 
 ```
@@ -210,15 +236,56 @@ Joining a new device to an existing mesh requires three things:
 3. Access to the same **remote mailbox** (the same `remotePath` on a
    storage backend the new device can reach).
 
-The pairing flow ships these three over an ECDH relay handshake (see
-`generateShareQR` / `handleScannedQR` in the handshake module). After
-the handshake the new device:
+A production app should keep CRUD, sync lifecycle, and pairing separate:
+
+```text
+lib/interocitor-db.ts      engine, schema, local repository, credential primitives
+lib/interocitor-sync.ts    mesh id lifecycle, adapter, connect/disconnect, recovery
+lib/interocitor-pairing.ts QR handshake only
+```
+
+The pairing flow ships credentials over an ECDH relay handshake. The handshake relay base and sync adapter base are different concepts: a relay base is the temporary handshake-file path, such as `/Taska`; the Cloudflare adapter base URL is the concrete Worker route, such as `/sync/io/{meshId}`. The engine `remotePath` is still the mesh folder path used inside that adapter, such as `/Taska`.
+
+### Pairing intents
+
+**Join QR** is for a device that does not have credentials yet:
+
+1. Joiner mints a fresh mesh id.
+2. Joiner creates a Cloudflare adapter with base URL `/sync/io/{meshId}`.
+3. Joiner calls `generateJoinQR()`.
+4. Existing paired device scans and pushes credentials.
+5. Joiner receives credentials from `credentials` on the result.
+6. Joiner applies the passphrase and connects to the minted mesh.
+
+**Share QR** is for an existing mesh member inviting a new device:
+
+1. Existing device connects to the active mesh.
+2. Existing device calls `generateShareQR()` with `remotePath` and `passphrase`.
+3. New device scans and receives credentials from `handleScannedQR()`.
+4. New device applies credentials and connects using the adapter config from the payload.
+
+`handleScannedQR()` returns `null` for join intent because the scanner pushed its own credentials. It returns credentials for share intent because the scanner received credentials. Always handle the return value:
+
+```ts
+import { decodeQRPayload, handleScannedQR, parseQRFromUrl } from '@interocitor/core';
+// Raw QR payload decoder is also available from '@interocitor/core/handshake/qr'.
+
+const payload = parseQRFromUrl(location.hash) ?? decodeQRPayload(rawPastedPayload);
+const received = await handleScannedQR({ adapter, relayBase: '/Taska', payload });
+
+if (received) {
+  if (received.passphrase) db.setPassphrase(received.passphrase);
+  await connectFromPayload(received.remotePath);
+}
+```
+
+After the handshake the new device:
 
 ```ts
 const db = new Interocitor(adapter, {
   dbName: 'my-app',
   appName: 'My App',
-  remotePath: '/MyApp',
+  remotePath: '/Taska',
   passphrase: 'base58-from-handshake',
   encrypted: true,
 });

package/dist/adapters/cloudflare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../src/adapters/cloudflare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAEtH,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAUD;;;;;;;;;;;;;GAaG;AACH,wFAAwF;AACxF,MAAM,WAAW,yBAAyB;IACxC,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,iBAAkB,YAAW,cAAc;IACtD,QAAQ,CAAC,IAAI,gBAAgB;IAE7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,aAAa,CAAS;IAM9B,OAAO,CAAC,cAAc,CAA0B;gBAEpC,MAAM,EAAE,uBAAuB;IAI3C,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,YAAY;IAWpB,OAAO,KAAK,SAAS,GAMpB;IAED,OAAO,KAAK,SAAS,GAWpB;IAED,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,OAAO;IAMT,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBnC;;;OAGG;IACH,kBAAkB,IAAI,MAAM;IAK5B,eAAe,IAAI,OAAO;IAI1B,wBAAwB,CACtB,YAAY,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,EAC1D,KAAK,CAAC,EAAE,uBAAuB,GAC9B,MAAM,IAAI;IA+DP,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe/C;;0BAEsB;IACtB,gBAAgB,IAAI,IAAI;IAIlB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAqB7C,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAe5C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAa3C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcjE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;CAsB/D"}
+{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../../src/adapters/cloudflare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAEtH,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAUD;;;;;;;;;;;;;GAaG;AACH,wFAAwF;AACxF,MAAM,WAAW,yBAAyB;IACxC,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,iBAAkB,YAAW,cAAc;IACtD,QAAQ,CAAC,IAAI,gBAAgB;IAE7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,aAAa,CAAS;IAM9B,OAAO,CAAC,cAAc,CAA0B;gBAEpC,MAAM,EAAE,uBAAuB;IAI3C,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,YAAY;IAWpB,OAAO,KAAK,SAAS,GAMpB;IAED,OAAO,KAAK,SAAS,GAWpB;IAED,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,OAAO;IAMT,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBnC;;;OAGG;IACH,kBAAkB,IAAI,MAAM;IAK5B,eAAe,IAAI,OAAO;IAI1B,wBAAwB,CACtB,YAAY,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,EAC1D,KAAK,CAAC,EAAE,uBAAuB,GAC9B,MAAM,IAAI;IAsFP,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe/C;;0BAEsB;IACtB,gBAAgB,IAAI,IAAI;IAIlB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAqB7C,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAe5C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAa3C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcjE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;CAsB/D"}

package/dist/adapters/cloudflare.js

@@ -101,18 +101,29 @@ export class CloudflareAdapter {
         let cancelled = false;
         let backoffMs = 1000;
         const MAX_BACKOFF_MS = 30000;
+        // Attempts where the socket closed before ever opening (failed upgrade).
+        // After MAX_FAILED_UPGRADES consecutive such failures we back off to a long
+        // cooldown interval rather than hammering (e.g. DO free-tier exhaustion).
+        // Once the cooldown elapses we try again — self-healing if the server recovers.
+        let failedUpgradeStreak = 0;
+        const MAX_FAILED_UPGRADES = 5;
+        const COOLDOWN_MS = 60 * 60 * 1000; // 1 hour
         const connect = () => {
             if (cancelled)
                 return;
+            let opened = false;
             try {
                 ws = new WebSocket(this.notifyUrl);
             }
             catch (error) {
                 hooks?.onError?.(error);
+                failedUpgradeStreak++;
                 scheduleReconnect();
                 return;
             }
             ws.onopen = () => {
+                opened = true;
+                failedUpgradeStreak = 0;
                 backoffMs = 1000;
                 hooks?.onReady?.();
             };
@@ -131,8 +142,20 @@ export class CloudflareAdapter {
                 hooks?.onError?.(event);
             };
             ws.onclose = () => {
+                if (!opened) {
+                    // The upgrade itself failed (server returned non-101, e.g. 500/503).
+                    failedUpgradeStreak++;
+                }
                 if (!cancelled) {
                     hooks?.onClose?.();
+                    if (failedUpgradeStreak >= MAX_FAILED_UPGRADES) {
+                        // Back off to a long cooldown then try again — self-healing if the
+                        // server recovers (e.g. DO free-tier resets).
+                        failedUpgradeStreak = 0;
+                        backoffMs = 1000;
+                        setTimeout(() => connect(), COOLDOWN_MS);
+                        return;
+                    }
                     scheduleReconnect();
                 }
             };

package/dist/core/sync-engine.d.ts

@@ -69,6 +69,10 @@ export declare class Interocitor<S extends Record<string, Record<string, unknown
     private batchTimer;
     private pendingBatch;
     private pollTimer;
+    private pollBaseIntervalMs;
+    private pollCurrentIntervalMs;
+    private pollGeneration;
+    private visibilityChangeListener;
     private unsubscribeRemoteInvalidations;
     private remoteInvalidationPullPromise;
     private remoteInvalidationPullQueued;
@@ -176,6 +180,8 @@ export declare class Interocitor<S extends Record<string, Record<string, unknown
     private jitterDelay;
     private stopPolling;
     private startPolling;
+    /** Called by emit() to adapt the poll interval based on pull activity. */
+    private adaptPollInterval;
     private stopRemoteInvalidations;
     private startRemoteInvalidations;
     private getRowHlc;
@@ -202,8 +208,12 @@ export declare class Interocitor<S extends Record<string, Record<string, unknown
     private applyInitialState;
     configureMesh(state: SyncInitialState): void;
     /**
-     * Set the mesh encryption passphrase.
-     * Call before init() or between disconnect() and init().
+     * Set or replace the mesh encryption passphrase before connecting.
+     *
+     * Apps may call this before init(), after init(), or after credentials
+     * arrive from pairing. It intentionally does not rebuild the engine or
+     * change remotePath/deviceId; it only invalidates the derived key so the
+     * next connect/flush uses the new passphrase.
      */
     setPassphrase(passphrase: string): void;
     /**
@@ -250,6 +260,8 @@ export declare class Interocitor<S extends Record<string, Record<string, unknown
     connect(): Promise<void>;
     private tryConnectFastPath;
     private doConnect;
+    private startVisibilityTracking;
+    private stopVisibilityTracking;
     disconnect(): Promise<void>;
     setRemoteStorage(adapter: StorageAdapter | null): Promise<void>;
     setLocalStorage(local: LocalStoreAdapter): Promise<void>;

package/dist/core/sync-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-engine.d.ts","sourceRoot":"","sources":["../../src/core/sync-engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync-engine.d.ts","sourceRoot":"","sources":["../../src/core/sync-engine.ts"],"names":[],"mappings":"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"}

package/dist/core/sync-engine.js

@@ -23,6 +23,7 @@ import { flushToAdapter } from "./flush.js";
 import { pull as doPull } from "./pull.js";
 import { compact as doCompact, rehydrate as doRehydrate } from "./compaction.js";
 const DEFAULT_COMPACT_WARNING_THRESHOLD = 50;
+const POLL_BACKGROUND_MULTIPLIER = 10;
 const DEFAULT_COMPACT_AUTO_THRESHOLD = 50;
 const DEFAULT_COMPACT_AUTO_SAMPLE_NUMERATOR = 10;
 const DEFAULT_COMPACT_AUTO_DEVICE_COUNT = 1;
@@ -56,6 +57,10 @@ export class Interocitor {
         this.pendingBatch = null;
         // Poll / push invalidation management
         this.pollTimer = null;
+        this.pollBaseIntervalMs = 0;
+        this.pollCurrentIntervalMs = 0;
+        this.pollGeneration = {};
+        this.visibilityChangeListener = null;
         this.unsubscribeRemoteInvalidations = null;
         this.remoteInvalidationPullPromise = null;
         this.remoteInvalidationPullQueued = false;
@@ -570,15 +575,51 @@ export class Interocitor {
     }
     stopPolling() {
         if (this.pollTimer) {
-            clearInterval(this.pollTimer);
+            clearTimeout(this.pollTimer);
             this.pollTimer = null;
         }
+        this.pollGeneration = {}; // invalidate any in-flight pull's generation
+        this.pollBaseIntervalMs = 0;
     }
     startPolling(intervalMs = this.config.pollInterval) {
         this.stopPolling();
-        this.pollTimer = setInterval(() => {
-            this.pull().catch(() => { });
-        }, intervalMs);
+        this.pollBaseIntervalMs = intervalMs;
+        this.pollCurrentIntervalMs = intervalMs;
+        // Each startPolling call gets its own generation token so that in-flight
+        // pulls from a previous polling session don't reschedule after stopPolling.
+        const generation = {};
+        this.pollGeneration = generation;
+        const schedule = () => {
+            this.pollTimer = setTimeout(() => {
+                this.pollTimer = null;
+                this.pull().catch(() => { }).finally(() => {
+                    if (this.pollGeneration === generation) {
+                        schedule();
+                    }
+                });
+            }, this.pollCurrentIntervalMs);
+        };
+        schedule();
+    }
+    /** Called by emit() to adapt the poll interval based on pull activity. */
+    adaptPollInterval(entriesMerged) {
+        if (!this.pollBaseIntervalMs)
+            return; // not polling
+        const MAX_POLL_INTERVAL_MS = 60000;
+        if (entriesMerged > 0) {
+            // Activity — reset to base interval.
+            if (this.pollCurrentIntervalMs !== this.pollBaseIntervalMs) {
+                this.pollCurrentIntervalMs = this.pollBaseIntervalMs;
+                this.log('debug', '[interocitor:poll] activity detected, poll interval reset', { intervalMs: this.pollCurrentIntervalMs });
+            }
+        }
+        else {
+            // Idle — back off toward max.
+            if (this.pollCurrentIntervalMs < MAX_POLL_INTERVAL_MS) {
+                this.pollCurrentIntervalMs = Math.min(this.pollCurrentIntervalMs * 2, MAX_POLL_INTERVAL_MS);
+                this.log('debug', '[interocitor:poll] idle, poll interval backed off', { intervalMs: this.pollCurrentIntervalMs });
+            }
+        }
     }
     stopRemoteInvalidations() {
         if (this.unsubscribeRemoteInvalidations) {
@@ -777,6 +818,9 @@ export class Interocitor {
             this.invalidateQueryCacheForTable(event.table);
             this.invalidateRowCacheForTable(event.table);
         }
+        if (event.type === 'sync:complete') {
+            this.adaptPollInterval(event.entriesMerged);
+        }
         for (const listener of this.listeners) {
             try {
                 listener(event);
@@ -953,11 +997,27 @@ export class Interocitor {
         });
     }
     /**
-     * Set the mesh encryption passphrase.
-     * Call before init() or between disconnect() and init().
+     * Set or replace the mesh encryption passphrase before connecting.
+     *
+     * Apps may call this before init(), after init(), or after credentials
+     * arrive from pairing. It intentionally does not rebuild the engine or
+     * change remotePath/deviceId; it only invalidates the derived key so the
+     * next connect/flush uses the new passphrase.
      */
     setPassphrase(passphrase) {
-        this.configureMesh({ passphrase, encrypted: true });
+        if (this.connected)
+            throw new Error('Cannot set passphrase while connected; disconnect first');
+        this.passphrase = passphrase;
+        this.encryptionKey = null;
+        this.encrypted = true;
+        this.emit({
+            type: 'mesh:configured',
+            dbName: this.dbName,
+            remotePath: this.config.remotePath,
+            deviceId: this.deviceId,
+            encrypted: this.encrypted,
+            hadPassphrase: true,
+        });
     }
     /**
      * Get the current mesh passphrase.
@@ -1211,6 +1271,8 @@ export class Interocitor {
             hasInFlight: !!this.connectPromise,
         });
         await this.ensureReady();
+        if (this.encrypted && !this.encryptionKey)
+            await this.resolveEncryption();
         if (!this.config.remotePath)
             throw new Error('connect() requires remotePath; configure mesh before connecting');
         // Idempotent. If we are already connected to a live mesh on this
@@ -1449,12 +1511,41 @@ export class Interocitor {
         this.startRemoteInvalidations(adapter);
         this.connected = true;
         this.log('info', 'connect() — connected', { remotePath: this.config.remotePath, deviceId: this.deviceId, pollInterval: this.config.pollInterval });
-        if (typeof window !== 'undefined') {
-            window.addEventListener('visibilitychange', () => {
-                if (document.visibilityState === 'hidden') {
-                    this.doFlush().catch(() => { });
+        this.startVisibilityTracking();
+    }
+    startVisibilityTracking() {
+        this.stopVisibilityTracking();
+        if (typeof document === 'undefined')
+            return;
+        const listener = () => {
+            if (document.visibilityState === 'hidden') {
+                // Tab backgrounded: flush pending writes and slow down polling 10×.
+                this.doFlush().catch(() => { });
+                if (this.pollBaseIntervalMs) {
+                    this.pollCurrentIntervalMs = Math.min(this.pollCurrentIntervalMs * POLL_BACKGROUND_MULTIPLIER, this.pollBaseIntervalMs * POLL_BACKGROUND_MULTIPLIER);
+                    this.log('debug', '[interocitor:poll] tab hidden, poll interval slowed', { intervalMs: this.pollCurrentIntervalMs });
                 }
-            });
+            }
+            else {
+                // Tab foregrounded: pull immediately then reset to base interval.
+                this.log('debug', '[interocitor:poll] tab visible, forcing pull and resetting interval');
+                if (this.pollBaseIntervalMs) {
+                    this.pollCurrentIntervalMs = this.pollBaseIntervalMs;
+                }
+                if (this.connected) {
+                    this.pull().catch(() => { });
+                }
+            }
+        };
+        this.visibilityChangeListener = listener;
+        document.addEventListener('visibilitychange', listener);
+    }
+    stopVisibilityTracking() {
+        if (this.visibilityChangeListener) {
+            if (typeof document !== 'undefined') {
+                document.removeEventListener('visibilitychange', this.visibilityChangeListener);
+            }
+            this.visibilityChangeListener = null;
         }
     }
     async disconnect() {
@@ -1463,6 +1554,7 @@ export class Interocitor {
         // poll/push/flush touches the adapter while we are killing the session.
         this.stopPolling();
         this.stopRemoteInvalidations();
+        this.stopVisibilityTracking();
         this.clearScheduledFlush();
         this.clearCompactTimers();
         this.clearBatchTimer();

package/dist/handshake/qr-public.d.ts

@@ -0,0 +1,3 @@
+export { buildPairUrl, decodeQRPayload, encodeQRPayload, parseQRFromUrl, } from './qr.ts';
+export type { HandshakeIntent, HandshakeQRPayload, } from './qr.ts';
+//# sourceMappingURL=qr-public.d.ts.map

package/dist/handshake/qr-public.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qr-public.d.ts","sourceRoot":"","sources":["../../src/handshake/qr-public.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,eAAe,EACf,kBAAkB,GACnB,MAAM,SAAS,CAAC"}

package/dist/handshake/qr-public.js

@@ -0,0 +1 @@
+export { buildPairUrl, decodeQRPayload, encodeQRPayload, parseQRFromUrl, } from "./qr.js";

package/dist/index.d.ts

@@ -36,6 +36,7 @@ export { generateShareQR, generateJoinQR, handleScannedQR, buildPairUrl, parseQR
 export type { HandshakeCredentials, HandshakeQRPayload, HandshakeIntent, GenerateShareQROptions, GenerateShareQRResult, GenerateJoinQROptions, GenerateJoinQRResult, HandleScannedQROptions, } from './handshake/index.ts';
 export { Interocitor, type InterocitorInitContext, } from './core/sync-engine.ts';
 export { LocalStore } from './storage/local-store.ts';
+export { resetLocalDatabase } from './storage/reset.ts';
 export { type CredentialStore, type StoredCredentials, LocalStorageCredentialStore, WebAuthnCredentialStore, createCredentialStore, } from './storage/credential-store.ts';
 export { Table, QueryResult, RowResult } from './core/table.ts';
 export { types } from './core/schema-types.ts';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH,OAAO,EACL,eAAe,EACf,cAAc,EACd,eAAe,EACf,YAAY,EACZ,cAAc,EACd,eAAe,EACf,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EACV,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EACL,WAAW,EACX,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,2BAA2B,EAC3B,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAI/C,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EACL,MAAM,EACN,cAAc,EACd,eAAe,EACf,WAAW,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAI3D,YAAY,EAEV,cAAc,EACd,SAAS,EAGT,iBAAiB,EACjB,iBAAiB,EAGjB,UAAU,EACV,gBAAgB,EAChB,QAAQ,EACR,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,UAAU,EACV,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,wBAAwB,EACxB,WAAW,EACX,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,2BAA2B,EAC3B,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,cAAc,EACd,aAAa,EAGb,SAAS,EACT,iBAAiB,EAGjB,GAAG,EAGH,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,UAAU,EACV,UAAU,EACV,WAAW,EACX,aAAa,GACd,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH,OAAO,EACL,eAAe,EACf,cAAc,EACd,eAAe,EACf,YAAY,EACZ,cAAc,EACd,eAAe,EACf,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EACV,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EACL,WAAW,EACX,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,2BAA2B,EAC3B,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAI/C,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EACL,MAAM,EACN,cAAc,EACd,eAAe,EACf,WAAW,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAI3D,YAAY,EAEV,cAAc,EACd,SAAS,EAGT,iBAAiB,EACjB,iBAAiB,EAGjB,UAAU,EACV,gBAAgB,EAChB,QAAQ,EACR,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,UAAU,EACV,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,wBAAwB,EACxB,WAAW,EACX,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,2BAA2B,EAC3B,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,cAAc,EACd,aAAa,EAGb,SAAS,EACT,iBAAiB,EAGjB,GAAG,EAGH,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,UAAU,EACV,UAAU,EACV,WAAW,EACX,aAAa,GACd,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -37,6 +37,7 @@ export { generateShareQR, generateJoinQR, handleScannedQR, buildPairUrl, parseQR
 // ─── Engine ───────────────────────────────────────────────────────────
 export { Interocitor, } from "./core/sync-engine.js";
 export { LocalStore } from "./storage/local-store.js";
+export { resetLocalDatabase } from "./storage/reset.js";
 export { LocalStorageCredentialStore, WebAuthnCredentialStore, createCredentialStore, } from "./storage/credential-store.js";
 export { Table, QueryResult, RowResult } from "./core/table.js";
 export { types } from "./core/schema-types.js";

package/dist/storage/reset.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Delete an Interocitor IndexedDB database after callers have disconnected
+ * and cleared credentials.
+ *
+ * This is intentionally low-level: it only deletes the local IndexedDB
+ * database named by `dbName`. Apps should call it as the final destructive
+ * local reset step, then reload before creating or joining a new mesh.
+ */
+export declare function resetLocalDatabase(dbName?: string): Promise<void>;
+//# sourceMappingURL=reset.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reset.d.ts","sourceRoot":"","sources":["../../src/storage/reset.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,SAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CASxE"}

package/dist/storage/reset.js

@@ -0,0 +1,18 @@
+/**
+ * Delete an Interocitor IndexedDB database after callers have disconnected
+ * and cleared credentials.
+ *
+ * This is intentionally low-level: it only deletes the local IndexedDB
+ * database named by `dbName`. Apps should call it as the final destructive
+ * local reset step, then reload before creating or joining a new mesh.
+ */
+export function resetLocalDatabase(dbName = 'interocitor') {
+    return new Promise((resolve, reject) => {
+        const req = indexedDB.deleteDatabase(dbName);
+        req.onsuccess = () => resolve();
+        req.onerror = () => reject(req.error ?? new Error(`Failed to delete IndexedDB database "${dbName}"`));
+        req.onblocked = () => {
+            reject(new Error(`Cannot delete IndexedDB database "${dbName}" while another connection is open`));
+        };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interocitor/core",
-  "version": "0.0.0-beta.6",
+  "version": "0.0.0-beta.8",
   "description": "Encrypted local-first CRDT database that syncs over cloud storage without a purpose-built backend.",
   "type": "module",
   "main": "dist/index.js",
@@ -30,6 +30,14 @@
       "import": "./dist/storage/local-store.js",
       "types": "./dist/storage/local-store.d.ts"
     },
+    "./storage/reset": {
+      "import": "./dist/storage/reset.js",
+      "types": "./dist/storage/reset.d.ts"
+    },
+    "./handshake/qr": {
+      "import": "./dist/handshake/qr-public.js",
+      "types": "./dist/handshake/qr-public.d.ts"
+    },
     "./crypto/keys": {
       "import": "./dist/crypto/keys.js",
       "types": "./dist/crypto/keys.d.ts"