@koolbase/core 12.13.1 → 12.15.0

package/dist/cjs/database.js

@@ -7,9 +7,10 @@ const database_errors_js_1 = require("./database-errors.js");
 const errors_js_1 = require("./errors.js");
 const cache_store_js_1 = require("./cache-store.js");
 const offline_state_js_1 = require("./offline-state.js");
+const cache_store_js_2 = require("./cache-store.js");
 const conflict_js_1 = require("./conflict.js");
 const pending_write_js_1 = require("./pending-write.js");
-const cache_store_js_2 = require("./cache-store.js");
+const cache_store_js_3 = require("./cache-store.js");
 const sync_engine_js_1 = require("./sync-engine.js");
 const record_js_1 = require("./record.js");
 const database_errors_js_2 = require("./database-errors.js");
@@ -45,6 +46,8 @@ function batchOpToWire(op) {
 }
 class KoolbaseDatabase {
     constructor(config, getUserId, getToken, onSessionExpired) {
+        this.stateWatchers = new Set();
+        this.offStateChange = null;
         /**
          * Resolves by id, reloading the stored conflict first.
          *
@@ -94,7 +97,7 @@ class KoolbaseDatabase {
         };
     }
     async request(method, path, body) {
-        const res = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}${path}`, {
+        const res = await (0, network_js_1.sessionFetch)(`${this.config.baseUrl}${path}`, {
             method,
             headers: await this.buildHeaders(),
             body: body ? JSON.stringify(body) : undefined,
@@ -132,7 +135,7 @@ class KoolbaseDatabase {
      * none of them clearing a rejected session. One path, two shapes of result.
      */
     async requestWithStatus(method, path, body) {
-        const res = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}${path}`, {
+        const res = await (0, network_js_1.sessionFetch)(`${this.config.baseUrl}${path}`, {
             method,
             headers: await this.buildHeaders(),
             body: body ? JSON.stringify(body) : undefined,
@@ -207,12 +210,12 @@ class KoolbaseDatabase {
         // query's identity, so both policies share one cache entry. onRefresh is
         // who to tell, not what to read, so it stays out the same way.
         const { cache: cachePolicy, onRefresh, ...queryOptions } = options;
-        const queryHash = (0, cache_store_js_2.hashQuery)(collection, queryOptions);
-        const cached = cachePolicy === 'network-only' ? null : await (0, cache_store_js_2.getCached)(userId, collection, queryHash);
+        const queryHash = (0, cache_store_js_3.hashQuery)(collection, queryOptions);
+        const cached = cachePolicy === 'network-only' ? null : await (0, cache_store_js_3.getCached)(userId, collection, queryHash);
         if (cached) {
             this.runQuery(collection, queryOptions)
                 .then(async (result) => {
-                await (0, cache_store_js_2.setCached)(userId, collection, queryHash, result);
+                await (0, cache_store_js_3.setCached)(userId, collection, queryHash, result);
                 // Told outside the catch below, which is for the network: an
                 // exception from the caller's callback is the caller's to see.
                 if (onRefresh)
@@ -224,7 +227,7 @@ class KoolbaseDatabase {
             return { ...cached, isFromCache: true };
         }
         const result = await this.runQuery(collection, queryOptions);
-        await (0, cache_store_js_2.setCached)(userId, collection, queryHash, result);
+        await (0, cache_store_js_3.setCached)(userId, collection, queryHash, result);
         return { ...result, isFromCache: false };
     }
     /**
@@ -233,7 +236,7 @@ class KoolbaseDatabase {
      * a server, or another user. The SDK's own writes already do this.
      */
     async invalidate(collection) {
-        await (0, cache_store_js_2.invalidateCache)(this.getUserId() ?? 'anonymous', collection);
+        await (0, cache_store_js_3.invalidateCache)(this.getUserId() ?? 'anonymous', collection);
         void (0, query_refresh_js_1.refreshCollectionQueries)(collection);
     }
     // ─── Insert (online-first with offline fallback) ───────────────────────────
@@ -257,7 +260,7 @@ class KoolbaseDatabase {
             // next query sees real data instead of a stale optimistic copy.
             const raw = await this.request('POST', '/v1/sdk/db/insert', { collection, data });
             const record = (0, record_js_1.recordFromWire)(raw);
-            await (0, cache_store_js_2.invalidateCache)(userId, collection);
+            await (0, cache_store_js_3.invalidateCache)(userId, collection);
             void (0, query_refresh_js_1.refreshCollectionQueries)(collection);
             // The response carries a fresh revision, so caching it keeps the
             // baseline current for whatever edits this record next.
@@ -293,7 +296,7 @@ class KoolbaseDatabase {
                 createdAt: new Date().toISOString(),
                 updatedAt: new Date().toISOString(),
             };
-            await (0, cache_store_js_2.optimisticallyInsert)(userId, collection, optimisticRecord);
+            await (0, cache_store_js_3.optimisticallyInsert)(userId, collection, optimisticRecord);
             // No baseline: an insert has no prior state, and the record does not
             // exist on the server yet, so there is nothing to be conditional against.
             // An offline edit to it composes against this queued write instead.
@@ -332,7 +335,7 @@ class KoolbaseDatabase {
         const record = (0, record_js_1.recordFromWire)(body);
         // Keep the cache fresh, same intent as insert's post-success invalidate.
         const userId = this.getUserId() ?? 'anonymous';
-        await (0, cache_store_js_2.invalidateCache)(userId, collection);
+        await (0, cache_store_js_3.invalidateCache)(userId, collection);
         void (0, query_refresh_js_1.refreshCollectionQueries)(collection);
         await (0, cache_store_js_1.cacheRecord)(userId, collection, record.id, record.data, record.revision);
         return { record, created };
@@ -352,7 +355,7 @@ class KoolbaseDatabase {
     async deleteWhere(collection, filters) {
         const body = await this.request('POST', '/v1/sdk/db/delete-where', { collection, filters });
         const userId = this.getUserId() ?? 'anonymous';
-        await (0, cache_store_js_2.invalidateCache)(userId, collection);
+        await (0, cache_store_js_3.invalidateCache)(userId, collection);
         void (0, query_refresh_js_1.refreshCollectionQueries)(collection);
         return body.deleted ?? 0;
     }
@@ -416,7 +419,7 @@ class KoolbaseDatabase {
             }
         }
         for (const col of touched) {
-            await (0, cache_store_js_2.invalidateCache)(userId, col);
+            await (0, cache_store_js_3.invalidateCache)(userId, col);
             void (0, query_refresh_js_1.refreshCollectionQueries)(col);
         }
         return results;
@@ -433,6 +436,29 @@ class KoolbaseDatabase {
         }
         return record;
     }
+    /**
+     * The device's saved copy of a record: what this device last read, with the
+     * changes queued on it applied. Never contacts the server. Null when there is
+     * none: never read here, or deleted on this device.
+     *
+     * For showing something at once while get() asks the server -- saved-first,
+     * never saved-only. Kept data and revision, not createdAt or createdBy, which
+     * the saved copy does not hold (empty strings here).
+     */
+    async getSaved(recordId) {
+        const userId = this.getUserId() ?? 'anonymous';
+        const base = await this.resolveBaseline(userId, recordId);
+        if (!base)
+            return null;
+        return {
+            id: recordId,
+            collection: base.collection,
+            data: { ...base.baseline },
+            createdAt: '',
+            updatedAt: '',
+            revision: base.revision,
+        };
+    }
     // ─── Conflicts ──────────────────────────────────────────────────────────────
     /**
      * Writes that could not be applied, waiting for a decision.
@@ -453,6 +479,69 @@ class KoolbaseDatabase {
         const { pending } = await (0, offline_state_js_1.readOfflineState)(userId);
         return pending.map(pending_write_js_1.toPendingWrite);
     }
+    /**
+     * The pending writes now, and again whenever they change -- here, in another
+     * tab, or because the signed-in user changed. For a sync badge that reflects
+     * reality. null while signed out: per-user state has no answer then, and a
+     * fake empty list is how a badge says "all synced" while a user's changes
+     * sit queued. Returns the unsubscribe.
+     */
+    watchPendingWrites(listener) {
+        return this.watchState(async (userId) => {
+            if (!userId)
+                return () => listener(null);
+            const { pending } = await (0, offline_state_js_1.readOfflineState)(userId);
+            const writes = pending.map(pending_write_js_1.toPendingWrite);
+            return () => listener(writes);
+        });
+    }
+    /** The unresolved conflicts now, and again whenever they change. null while signed out. */
+    watchConflicts(listener) {
+        return this.watchState(async (userId) => {
+            if (!userId)
+                return () => listener(null);
+            const list = await this.conflicts();
+            return () => listener(list);
+        });
+    }
+    /**
+     * The signed-in user changed: every watcher reads again, for the new user
+     * (or null, signed out). Koolbase.initialize wires it to auth changes.
+     */
+    sessionChanged() {
+        for (const emit of [...this.stateWatchers])
+            emit();
+    }
+    /**
+     * One watcher: reads at once, then on every change to the signed-in user's
+     * offline state. Reads can finish out of order; only the latest delivers.
+     */
+    watchState(read) {
+        let latest = 0;
+        let active = true;
+        const emit = () => {
+            const mine = ++latest;
+            read(this.getUserId()).then((deliver) => { if (active && mine === latest)
+                deliver(); }, () => { });
+        };
+        this.stateWatchers.add(emit);
+        if (!this.offStateChange) {
+            this.offStateChange = (0, offline_state_js_1.onOfflineStateChange)((userId) => {
+                if (userId === this.getUserId())
+                    for (const w of [...this.stateWatchers])
+                        w();
+            });
+        }
+        emit();
+        return () => {
+            active = false;
+            this.stateWatchers.delete(emit);
+            if (this.stateWatchers.size === 0 && this.offStateChange) {
+                this.offStateChange();
+                this.offStateChange = null;
+            }
+        };
+    }
     /**
      * Count and total over a whole collection, with the read rule applied
      * inside the query.
@@ -630,7 +719,7 @@ class KoolbaseDatabase {
         }
         const landedRevision = landed && typeof landed.$revision === 'number' ? landed.$revision : undefined;
         await this.settleConflict(c, landed ?? undefined, landedRevision);
-        await (0, cache_store_js_2.invalidateCache)(this.getUserId() ?? 'anonymous', c.collection);
+        await (0, cache_store_js_3.invalidateCache)(this.getUserId() ?? 'anonymous', c.collection);
         void (0, query_refresh_js_1.refreshCollectionQueries)(c.collection);
     }
     // ─── Update (online-first with offline fallback) ───────────────────────────
@@ -667,8 +756,11 @@ class KoolbaseDatabase {
             for (const w of queued) {
                 if (w.operation === 'insert')
                     projected = { ...(w.data ?? {}) };
+                // An edit applies to the record as it was: the queued add's state, or
+                // -- first in a chain with no add -- the baseline the edit was made
+                // against. Starting from nothing dropped every field it did not touch.
                 else if (w.operation === 'update')
-                    projected = { ...(projected ?? {}), ...(w.data ?? {}) };
+                    projected = { ...(projected ?? w.baseline ?? {}), ...(w.data ?? {}) };
                 else if (w.operation === 'delete')
                     projected = null;
             }
@@ -737,6 +829,8 @@ class KoolbaseDatabase {
             });
             const merged = { ...base.baseline, ...data };
             await (0, cache_store_js_1.cacheRecord)(userId, base.collection, recordId, merged, base.revision);
+            // And in the saved lists, so they show what the user just changed.
+            await (0, cache_store_js_2.updateInCachedQueries)(userId, base.collection, recordId, data);
             // Optimistic: durable locally and queued to send, not yet accepted.
             return {
                 id: recordId,
@@ -797,8 +891,9 @@ class KoolbaseDatabase {
             });
             // The queued write holds its own copy of the baseline, so removing the
             // cached record costs nothing and keeps local reads consistent with what
-            // the user just did.
+            // the user just did -- saved lists included.
             await (0, cache_store_js_1.removeCachedRecord)(userId, recordId);
+            await (0, cache_store_js_2.removeFromCachedQueries)(userId, base.collection, recordId);
         }
     }
     // ─── Vectors ────────────────────────────────────────────────────────────────

package/dist/cjs/fiscal.js

@@ -113,7 +113,7 @@ class KoolbaseFiscal {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), params.timeoutMs ?? 30000);
         try {
-            const res = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}/v1/sdk/fiscal/submit`, {
+            const res = await (0, network_js_1.sessionFetch)(`${this.config.baseUrl}/v1/sdk/fiscal/submit`, {
                 method: 'POST',
                 headers: await this.buildHeaders(),
                 signal: controller.signal,
@@ -151,7 +151,7 @@ class KoolbaseFiscal {
                 device_id: params.deviceId,
                 client_ref: params.clientRef,
             });
-            const res = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}/v1/sdk/fiscal/status?${q.toString()}`, { method: 'GET', headers: await this.buildHeaders(), signal: controller.signal });
+            const res = await (0, network_js_1.sessionFetch)(`${this.config.baseUrl}/v1/sdk/fiscal/status?${q.toString()}`, { method: 'GET', headers: await this.buildHeaders(), signal: controller.signal });
             return await this.decode(res);
         }
         catch (e) {

package/dist/cjs/functions.js

@@ -14,7 +14,7 @@ class KoolbaseFunctions {
     // ─── Deploy ────────────────────────────────────────────────────────────────
     async deploy(options) {
         const runtime = options.runtime ?? types_js_1.FunctionRuntime.Deno;
-        const res = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}/v1/sdk/functions/deploy`, {
+        const res = await (0, network_js_1.sessionFetch)(`${this.config.baseUrl}/v1/sdk/functions/deploy`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -58,7 +58,7 @@ class KoolbaseFunctions {
         if (userToken) {
             headers['Authorization'] = `Bearer ${userToken}`;
         }
-        const res = await (0, network_js_1.koolbaseFetch)(`${this.config.baseUrl}/v1/sdk/functions/${name}`, {
+        const res = await (0, network_js_1.sessionFetch)(`${this.config.baseUrl}/v1/sdk/functions/${name}`, {
             method: 'POST',
             headers,
             body: JSON.stringify({ body: body ?? {} }),

package/dist/cjs/index.d.ts

@@ -17,6 +17,8 @@ export type { RecordState, RecordStatus } from './record-controller.js';
 export { KoolbaseFlags } from './flags.js';
 export { KoolbaseFunctions } from './functions.js';
 export { KoolbaseRealtime } from './realtime.js';
+export { KoolbaseConnectivity } from './connectivity.js';
+export type { ConnectivityState } from './connectivity.js';
 export { KoolbaseStorage } from './storage.js';
 export { KoolbaseAnalytics, disabledAnalytics } from './analytics.js';
 export { KoolbaseFiscal, KoolbaseFiscalError, decodeFiscalResponse, isFiscalized, isPending } from './fiscal.js';
@@ -27,4 +29,4 @@ export { getOrCreateDeviceId } from './device-id.js';
 export { koolbaseSdkVersion } from './device-metadata.js';
 export { RestoreResult } from './types.js';
 export type { AuthStateListener, FetchLike, KoolbaseAuthStorage, ResendVerificationResult } from './types.js';
-export { setPlatform, getPlatform, memoryPlatform, type PlatformAdapter, type PlatformStorage, type PlatformNetwork, type PlatformLifecycle, type PlatformLocks, type PlatformInfo, } from './platform.js';
+export { setPlatform, getPlatform, memoryPlatform, type PlatformAdapter, type PlatformBroadcast, type PlatformStorage, type PlatformNetwork, type PlatformLifecycle, type PlatformLocks, type PlatformInfo, } from './platform.js';

package/dist/cjs/index.js

@@ -19,7 +19,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.memoryPlatform = exports.getPlatform = exports.setPlatform = exports.RestoreResult = exports.koolbaseSdkVersion = exports.getOrCreateDeviceId = exports.KoolbaseMessaging = exports.isPending = exports.isFiscalized = exports.decodeFiscalResponse = exports.KoolbaseFiscalError = exports.KoolbaseFiscal = exports.disabledAnalytics = exports.KoolbaseAnalytics = exports.KoolbaseStorage = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = exports.initialRecordState = exports.KoolbaseRecordController = exports.initialCollectionState = exports.collectionQueryKey = exports.KoolbaseCollectionController = exports.KoolbaseDatabase = exports.KoolbaseAuth = void 0;
+exports.memoryPlatform = exports.getPlatform = exports.setPlatform = exports.RestoreResult = exports.koolbaseSdkVersion = exports.getOrCreateDeviceId = exports.KoolbaseMessaging = exports.isPending = exports.isFiscalized = exports.decodeFiscalResponse = exports.KoolbaseFiscalError = exports.KoolbaseFiscal = exports.disabledAnalytics = exports.KoolbaseAnalytics = exports.KoolbaseStorage = exports.KoolbaseConnectivity = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = exports.initialRecordState = exports.KoolbaseRecordController = exports.initialCollectionState = exports.collectionQueryKey = exports.KoolbaseCollectionController = exports.KoolbaseDatabase = exports.KoolbaseAuth = void 0;
 __exportStar(require("./types.js"), exports);
 __exportStar(require("./errors.js"), exports);
 __exportStar(require("./network.js"), exports);
@@ -47,6 +47,8 @@ var functions_js_1 = require("./functions.js");
 Object.defineProperty(exports, "KoolbaseFunctions", { enumerable: true, get: function () { return functions_js_1.KoolbaseFunctions; } });
 var realtime_js_1 = require("./realtime.js");
 Object.defineProperty(exports, "KoolbaseRealtime", { enumerable: true, get: function () { return realtime_js_1.KoolbaseRealtime; } });
+var connectivity_js_1 = require("./connectivity.js");
+Object.defineProperty(exports, "KoolbaseConnectivity", { enumerable: true, get: function () { return connectivity_js_1.KoolbaseConnectivity; } });
 var storage_js_1 = require("./storage.js");
 Object.defineProperty(exports, "KoolbaseStorage", { enumerable: true, get: function () { return storage_js_1.KoolbaseStorage; } });
 var analytics_js_1 = require("./analytics.js");

package/dist/cjs/network.d.ts

@@ -19,3 +19,17 @@ export declare class KoolbaseNetworkError extends TypeError {
 }
 /** fetch, with network failures turned into a KoolbaseNetworkError. */
 export declare function koolbaseFetch(input: string, init?: RequestInit): Promise<Response>;
+type Renewal = (refusedToken: string) => Promise<string | null>;
+/** Installed by Koolbase.initialize: renews the session a request was refused with. */
+export declare function setSessionRenewal(fn: Renewal | null): void;
+/**
+ * koolbaseFetch for a data request. A request refused as unauthenticated
+ * (401) while carrying the signed-in person's token is the session needing
+ * renewal, not ending: the access token expired early, the clock is off, or
+ * another tab renewed it. The session is renewed once and the request sent
+ * again with the new token, so the caller never sees the first refusal.
+ * Only when renewal is refused does the 401 reach the caller, and with it the
+ * client's onSessionExpired, which ends the session.
+ */
+export declare function sessionFetch(input: string, init?: RequestInit): Promise<Response>;
+export {};

package/dist/cjs/network.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseNetworkError = void 0;
 exports.koolbaseFetch = koolbaseFetch;
+exports.setSessionRenewal = setSessionRenewal;
+exports.sessionFetch = sessionFetch;
 /**
  * Network failures, made actionable.
  *
@@ -52,3 +54,61 @@ async function koolbaseFetch(input, init) {
         throw new KoolbaseNetworkError(input, e);
     }
 }
+let renewal = null;
+/** Installed by Koolbase.initialize: renews the session a request was refused with. */
+function setSessionRenewal(fn) {
+    renewal = fn;
+}
+function headerOf(headers, name) {
+    if (!headers)
+        return undefined;
+    if (typeof headers.get === 'function')
+        return headers.get(name) ?? undefined;
+    if (Array.isArray(headers))
+        return headers.find(([k]) => k.toLowerCase() === name.toLowerCase())?.[1];
+    const rec = headers;
+    const key = Object.keys(rec).find((k) => k.toLowerCase() === name.toLowerCase());
+    return key ? rec[key] : undefined;
+}
+function withHeader(headers, name, value) {
+    const out = {};
+    if (headers && typeof headers.forEach === 'function' && !Array.isArray(headers)) {
+        headers.forEach((v, k) => { out[k] = v; });
+    }
+    else if (Array.isArray(headers)) {
+        for (const [k, v] of headers)
+            out[k] = v;
+    }
+    else if (headers) {
+        Object.assign(out, headers);
+    }
+    for (const k of Object.keys(out))
+        if (k.toLowerCase() === name.toLowerCase())
+            delete out[k];
+    out[name] = value;
+    return out;
+}
+/**
+ * koolbaseFetch for a data request. A request refused as unauthenticated
+ * (401) while carrying the signed-in person's token is the session needing
+ * renewal, not ending: the access token expired early, the clock is off, or
+ * another tab renewed it. The session is renewed once and the request sent
+ * again with the new token, so the caller never sees the first refusal.
+ * Only when renewal is refused does the 401 reach the caller, and with it the
+ * client's onSessionExpired, which ends the session.
+ */
+async function sessionFetch(input, init) {
+    const res = await koolbaseFetch(input, init);
+    if (res.status !== 401 || !renewal)
+        return res;
+    const auth = headerOf(init?.headers, 'Authorization');
+    if (!auth || !auth.startsWith('Bearer '))
+        return res;
+    // Only a body that can be sent twice. Data requests send JSON text.
+    if (init?.body !== undefined && init.body !== null && typeof init.body !== 'string')
+        return res;
+    const fresh = await renewal(auth.slice('Bearer '.length));
+    if (!fresh)
+        return res;
+    return koolbaseFetch(input, { ...init, headers: withHeader(init?.headers, 'Authorization', `Bearer ${fresh}`) });
+}

package/dist/cjs/offline-state.d.ts

@@ -119,3 +119,7 @@ export declare function migrateLegacyQueue(userId: string): Promise<void>;
  * be replayed through its projected states instead.
  */
 export declare function rebaseHeldWrites(state: OfflineState, recordId: string, resolved: Record<string, unknown>, revision: number | undefined): void;
+type StateListener = (userId: string) => void;
+/** Called with the user id whenever that user's offline state changes. */
+export declare function onOfflineStateChange(listener: StateListener): () => void;
+export {};

package/dist/cjs/offline-state.js

@@ -9,6 +9,7 @@ exports.mutateOfflineState = mutateOfflineState;
 exports.queueWrite = queueWrite;
 exports.migrateLegacyQueue = migrateLegacyQueue;
 exports.rebaseHeldWrites = rebaseHeldWrites;
+exports.onOfflineStateChange = onOfflineStateChange;
 const platform_js_1 = require("./platform.js");
 const shared_js_1 = require("./shared.js");
 /**
@@ -142,6 +143,7 @@ async function mutateOfflineState(userId, mutate) {
         }
         await (0, platform_js_1.getPlatform)().storage.setItem(stateKey(userId), serialised);
     });
+    announce(userId);
 }
 /** Adds a write to the queue, under the user's lock. */
 async function queueWrite(userId, write) {
@@ -247,3 +249,37 @@ function rebaseHeldWrites(state, recordId, resolved, revision) {
             break;
     }
 }
+// ─── Change notification ─────────────────────────────────────────────────────
+const ANNOUNCE_PREFIX = 'koolbase:offline-state:';
+function stateListeners() {
+    return (0, shared_js_1.shared)('offlineStateListeners', () => new Set());
+}
+/**
+ * Tells whoever is watching that a user's offline state changed -- here, and
+ * in every other copy of the SDK sharing this storage (other tabs). A badge in
+ * one tab must move when another tab's sync drains the queue.
+ */
+function announce(userId) {
+    for (const listener of [...stateListeners()]) {
+        try {
+            listener(userId);
+        }
+        catch { /* one broken listener must not stop the rest */ }
+    }
+    try {
+        (0, platform_js_1.getPlatform)().broadcast?.post(ANNOUNCE_PREFIX + userId);
+    }
+    catch { /* best effort */ }
+}
+/** Called with the user id whenever that user's offline state changes. */
+function onOfflineStateChange(listener) {
+    stateListeners().add(listener);
+    const off = (0, platform_js_1.getPlatform)().broadcast?.on((message) => {
+        if (message.startsWith(ANNOUNCE_PREFIX))
+            listener(message.slice(ANNOUNCE_PREFIX.length));
+    });
+    return () => {
+        stateListeners().delete(listener);
+        off?.();
+    };
+}

package/dist/cjs/platform.d.ts

@@ -12,6 +12,21 @@ export interface PlatformNetwork {
      * Koolbase is unreachable is handled the same as any failed request.
      */
     onChange(callback: (online: boolean) => void): () => void;
+    /**
+     * What the host believes right now: true online, false offline, null when
+     * it cannot tell. Optional: a host without it reports nothing until its
+     * first change, and connectivity stays 'unknown' until then.
+     */
+    current?(): Promise<boolean | null>;
+}
+/**
+ * A message to every other copy of the SDK sharing this storage -- other tabs
+ * of the same origin in a browser. Optional: one process (React Native) has no
+ * other copies to tell.
+ */
+export interface PlatformBroadcast {
+    post(message: string): void;
+    on(callback: (message: string) => void): () => void;
 }
 export interface PlatformLifecycle {
     /** Subscribe to the app moving to the background. Used to flush analytics. */
@@ -54,6 +69,7 @@ export interface PlatformAdapter {
     lifecycle: PlatformLifecycle;
     info: PlatformInfo;
     locks: PlatformLocks;
+    broadcast?: PlatformBroadcast;
     /**
      * The host's best persistent store for the auth session, or null if it has
      * none worth the name. Used only when the app injects nothing through

package/dist/cjs/react/use-record.d.ts

@@ -3,6 +3,6 @@ export interface UseRecordResult extends RecordState {
     /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
     refresh: () => Promise<void>;
 }
-export declare function createUseRecord(getDb: () => Pick<KoolbaseDatabase, 'get'>): (collection: string, id: string | null | undefined, options?: {
+export declare function createUseRecord(getDb: () => Pick<KoolbaseDatabase, 'get'> & Partial<Pick<KoolbaseDatabase, 'getSaved'>>): (collection: string, id: string | null | undefined, options?: {
     live?: boolean;
 }) => UseRecordResult;

package/dist/cjs/record-controller.d.ts

@@ -8,9 +8,14 @@ export interface RecordState {
     readonly error: unknown;
     /** True while refresh() runs. */
     readonly refreshing: boolean;
+    /**
+     * True while the record shown is the device's saved copy and the server has
+     * not confirmed it on this load. Stays true if the server cannot be reached.
+     */
+    readonly isSaved: boolean;
 }
 export declare const initialRecordState: RecordState;
-type RecordReader = Pick<KoolbaseDatabase, 'get'>;
+type RecordReader = Pick<KoolbaseDatabase, 'get'> & Partial<Pick<KoolbaseDatabase, 'getSaved'>>;
 export declare class KoolbaseRecordController {
     readonly collection: string;
     readonly id: string;
@@ -31,6 +36,8 @@ export declare class KoolbaseRecordController {
     subscribe(listener: () => void): () => void;
     /** The first load. Call once; refresh() for later loads. */
     load(): Promise<void>;
+    /** The device's saved copy, shown at once while the server is asked. */
+    private showSaved;
     /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
     refresh(): Promise<void>;
     /** Stops all updates. A result still in flight is dropped when it lands. */

package/dist/cjs/record-controller.js

@@ -15,8 +15,10 @@
 //    or landing after dispose(), is dropped.
 //  - live (the option): realtime events for THIS record only. An update
 //    re-reads it silently, once per burst; a delete is notFound at once.
-// Not yet: an offline fallback from the record cache, which keeps data and
-// revision but not createdAt or createdBy.
+//  - saved-first, never saved-only: the device's saved copy (db.getSaved)
+//    shows at once with isSaved true while the server is asked. Success
+//    replaces it (isSaved false); failure keeps it (isSaved stays true); not
+//    found is notFound. No saved copy: the ordinary loading/error states.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseRecordController = exports.initialRecordState = void 0;
 const database_errors_js_1 = require("./database-errors.js");
@@ -26,6 +28,7 @@ exports.initialRecordState = Object.freeze({
     record: null,
     error: null,
     refreshing: false,
+    isSaved: false,
 });
 class KoolbaseRecordController {
     constructor(db, collection, id, options = {}) {
@@ -61,8 +64,27 @@ class KoolbaseRecordController {
         if (this.live && this.id) {
             this.unlive ?? (this.unlive = (0, live_source_js_1.liveSource)()?.subscribe(this.collection, (event) => this.onLive(event)) ?? null);
         }
+        await this.showSaved();
         await this.fetch();
     }
+    /** The device's saved copy, shown at once while the server is asked. */
+    async showSaved() {
+        if (!this.id || !this.db.getSaved)
+            return;
+        const gen = this.generation;
+        let saved = null;
+        try {
+            saved = await this.db.getSaved(this.id);
+        }
+        catch {
+            return;
+        }
+        if (!saved || this.isStale(gen) || this.state.status !== 'loading')
+            return;
+        if (saved.collection !== undefined && saved.collection !== this.collection)
+            return;
+        this.set({ status: 'loaded', record: saved, error: null, isSaved: true });
+    }
     /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
     async refresh() {
         if (this.disposed)
@@ -102,7 +124,7 @@ class KoolbaseRecordController {
                 this.liveTimer = null;
             }
             this.generation += 1;
-            this.set({ status: 'notFound', record: null, error: null, refreshing: false });
+            this.set({ status: 'notFound', record: null, error: null, refreshing: false, isSaved: false });
             return;
         }
         if (this.liveTimer)
@@ -117,7 +139,7 @@ class KoolbaseRecordController {
     async fetch() {
         const gen = ++this.generation;
         if (!this.id) {
-            this.set({ status: 'notFound', record: null, error: null });
+            this.set({ status: 'notFound', record: null, error: null, isSaved: false });
             return gen;
         }
         try {
@@ -125,17 +147,17 @@ class KoolbaseRecordController {
             if (this.isStale(gen))
                 return gen;
             if (record.collection !== undefined && record.collection !== this.collection) {
-                this.set({ status: 'notFound', record: null, error: null });
+                this.set({ status: 'notFound', record: null, error: null, isSaved: false });
             }
             else {
-                this.set({ status: 'loaded', record, error: null });
+                this.set({ status: 'loaded', record, error: null, isSaved: false });
             }
         }
         catch (error) {
             if (this.isStale(gen))
                 return gen;
             if (error instanceof database_errors_js_1.KoolbaseNotFoundError) {
-                this.set({ status: 'notFound', record: null, error: null });
+                this.set({ status: 'notFound', record: null, error: null, isSaved: false });
             }
             else if (this.state.record === null) {
                 this.set({ status: 'error', error });

package/dist/cjs/shared.d.ts

@@ -1,4 +1,5 @@
 interface Slot {
+    offlineStateListeners: Set<(userId: string) => void>;
     platform?: unknown;
     locks?: Map<string, Promise<unknown>>;
 }