@rebasepro/client 0.10.0 → 0.10.1-canary.0a881d4

package/src/auth.ts

@@ -166,22 +166,86 @@ export function createAuth(transport: Transport, options?: CreateAuthOptions) {
      */
     function isFatalRefreshError(err: unknown): boolean {
         if (!(err instanceof RebaseApiError)) return false; // network/other → transient
+        // Another tab (or a retry of our own request) rotated the token we
+        // were holding. In cookie mode the jar may ALREADY contain the
+        // replacement, so this is the one 401 that is worth retrying: giving
+        // up here is precisely the bug where opening a second tab signs you
+        // out of both.
+        if (err.code === "TOKEN_ALREADY_USED") return false;
         if (err.code === "INVALID_TOKEN" || err.code === "TOKEN_EXPIRED") return true;
         // 401/403 are auth failures; other statuses (incl. 5xx, 0) are transient.
         return err.status === 401 || err.status === 403;
     }
 
+    /**
+     * Drop this client's session without telling the server.
+     *
+     * `signOut()` is a user action: it POSTs /logout, which revokes the whole
+     * sign-in. That is the wrong hammer for a refresh that failed. Our token
+     * may be stale precisely because a sibling tab holds a live one, and
+     * logging out on its behalf would turn one tab's bad luck into everybody
+     * being signed out — the exact failure this work exists to remove.
+     */
+    function abandonSessionLocally() {
+        currentSession = null;
+        clearStoredSession();
+        if (refreshTimeout) {
+            clearTimeout(refreshTimeout);
+            refreshTimeout = null;
+        }
+        transport.setToken(null);
+        emit("SIGNED_OUT", null);
+    }
+
+    /**
+     * Recover from a 401 on an ordinary API request.
+     *
+     * Returns `true` when the caller should retry — we minted a fresh access
+     * token. When the refresh is rejected *fatally* (the refresh token itself
+     * is invalid, expired or revoked) this client can no longer act as the
+     * user at all, so we drop the session and emit `SIGNED_OUT`. UIs gate on
+     * that event, so they show their login screen instead of leaving the user
+     * staring at "Invalid or expired token" on every view.
+     *
+     * Transient failures (offline, 5xx, backend restarting) keep the session:
+     * the scheduled refresh backs off and retries, and the token is very
+     * likely still good once the backend answers again.
+     */
+    async function handleUnauthorized(): Promise<boolean> {
+        // No session to recover: the 401 is just an anonymous caller hitting a
+        // protected route. Emitting SIGNED_OUT here would fire sign-out
+        // handlers for a user who was never signed in.
+        if (!currentSession) return false;
+
+        // Nothing to refresh *with* — the access token is dead and there is no
+        // way back. Same end state as a rejected refresh token.
+        if (authFlowMode !== "cookie" && !currentSession.refreshToken) {
+            abandonSessionLocally();
+            return false;
+        }
+
+        try {
+            await refreshSession();
+            return true;
+        } catch (err) {
+            if (isFatalRefreshError(err)) {
+                abandonSessionLocally();
+            }
+            return false;
+        }
+    }
+
     async function attemptScheduledRefresh(attempt: number) {
         try {
             await refreshSession();
             // On success, refreshSession() re-schedules the next refresh itself.
         } catch (err) {
             if (isFatalRefreshError(err)) {
-                signOut();
+                abandonSessionLocally();
                 return;
             }
             if (attempt >= MAX_REFRESH_RETRIES) {
-                signOut();
+                abandonSessionLocally();
                 return;
             }
             // Transient failure — back off and retry rather than dropping the session.
@@ -395,10 +459,52 @@ redirectUri });
         emit("SIGNED_OUT", null);
     }
 
+    /**
+     * Serialise refreshes across TABS, not just within one.
+     *
+     * The in-flight promise below covers callers inside a single JavaScript
+     * context. It does nothing about the far more common case: two tabs of the
+     * same app booting together, each firing its own /refresh with the same
+     * cookie. The server tolerates that now (superseded tokens stay usable for
+     * a grace window), but tolerating a stampede is not the same as avoiding
+     * one, and every extra rotation is another chance to end up holding a
+     * token whose response never arrived.
+     *
+     * Web Locks are best-effort on purpose. supabase-js shipped this and then
+     * spent a year fielding deadlock reports — a lock held by a crashed or
+     * frozen tab must never be able to wedge sign-in — so a lock we cannot
+     * take within the timeout is simply not taken, and the refresh proceeds
+     * unserialised, exactly as it did before.
+     */
+    const REFRESH_LOCK_NAME = "rebase-auth-refresh";
+    const REFRESH_LOCK_TIMEOUT_MS = 5000;
+
+    async function withRefreshLock<T>(fn: () => Promise<T>): Promise<T> {
+        const locks = (globalThis as { navigator?: { locks?: LockManager } }).navigator?.locks;
+        if (!locks?.request) return fn();
+
+        const controller = new AbortController();
+        const giveUp = setTimeout(() => controller.abort(), REFRESH_LOCK_TIMEOUT_MS);
+        try {
+            return await locks.request(
+                REFRESH_LOCK_NAME,
+                { signal: controller.signal },
+                async () => fn()
+            ) as T;
+        } catch (e) {
+            // AbortError means only that we waited long enough for the lock.
+            // Anything the callback itself threw has to keep propagating.
+            if ((e as { name?: string })?.name !== "AbortError") throw e;
+            return fn();
+        } finally {
+            clearTimeout(giveUp);
+        }
+    }
+
     function refreshSession(): Promise<RebaseSession> {
         // Share a single in-flight refresh across concurrent callers.
         if (inFlightRefresh) return inFlightRefresh;
-        inFlightRefresh = doRefreshSession().finally(() => {
+        inFlightRefresh = withRefreshLock(() => doRefreshSession()).finally(() => {
             inFlightRefresh = null;
         });
         return inFlightRefresh;
@@ -691,6 +797,7 @@ refreshToken: session.refreshToken };
         signInWithSpotify,
         signOut,
         refreshSession,
+        handleUnauthorized,
         getUser,
         findUserByEmail,
         updateUser,

package/src/collection.ts

@@ -11,6 +11,43 @@ import {
 
 import { SDKQueryBuilder } from "./sdk_query_builder";
 
+/**
+ * A live query result: a normal {@link FindResult} plus what an interface
+ * needs to decide whether to show a "saving…" or "offline" affordance over it.
+ *
+ * The three flags are always `false` on a client without offline support —
+ * every result there came straight from the server.
+ */
+export interface LiveResult<M extends Record<string, unknown>> extends FindResult<M> {
+    /** The data came from the local database, not from a completed request. */
+    fromCache: boolean;
+    /** At least one row here carries a write the server has not accepted yet. */
+    hasPendingWrites: boolean;
+    /**
+     * The local database may not hold every row the server would have
+     * returned, so treat this as a best effort rather than a complete answer.
+     */
+    partial: boolean;
+    /** The most recent revalidation failure, when the last one failed. */
+    error?: Error;
+}
+
+/** Snapshot metadata for a single observed row. */
+export interface RowSnapshotMeta {
+    fromCache: boolean;
+    hasPendingWrites: boolean;
+}
+
+export interface ObserveOptions {
+    /**
+     * Keep the subscription live off the realtime socket, so changes made by
+     * other clients arrive without a refetch. On by default whenever realtime
+     * is enabled on the client; pass `false` for a one-shot read that still
+     * reports offline/pending metadata.
+     */
+    realtime?: boolean;
+}
+
 /**
  * The concrete, HTTP-backed implementation of the public
  * {@link SDKCollectionClient} contract — flat rows (no Entity wrapper), plus
@@ -18,8 +55,8 @@ import { SDKQueryBuilder } from "./sdk_query_builder";
  *
  * This is what `createRebaseClient().data.<collection>` returns. It is not a
  * separate API from {@link SDKCollectionClient}; it only widens it with
- * `count()`. Program against {@link SDKCollectionClient} when you want a
- * transport-agnostic type.
+ * `count()` and the reactive `observe()` pair. Program against
+ * {@link SDKCollectionClient} when you want a transport-agnostic type.
  */
 export interface CollectionClient<
     M extends Record<string, unknown> = Record<string, unknown>,
@@ -27,6 +64,36 @@ export interface CollectionClient<
     U = Partial<M>
 > extends SDKCollectionClient<M, I, U> {
     count(params?: FindParams): Promise<number>;
+
+    /**
+     * Subscribe to a query's results.
+     *
+     * This is the reactive read primitive, and the one to reach for in a UI:
+     * unlike `find()` it keeps emitting. On a client with `offline` enabled it
+     * is local-first — the first emission comes from the local database, with
+     * no request in the way — and re-emits on every local write, every queued
+     * write reaching the server, and every rollback. With realtime enabled it
+     * also re-emits on changes made by other clients.
+     *
+     * Emissions are de-duplicated: a refresh that changes nothing does not
+     * call back.
+     *
+     * @returns An unsubscribe function.
+     */
+    observe(
+        params: FindParams | undefined,
+        onResult: (result: LiveResult<M>) => void,
+        onError?: (error: Error) => void,
+        options?: ObserveOptions
+    ): () => void;
+
+    /** {@link CollectionClient.observe} for a single row. */
+    observeById(
+        id: string | number,
+        onResult: (row: M | undefined, meta: RowSnapshotMeta) => void,
+        onError?: (error: Error) => void,
+        options?: ObserveOptions
+    ): () => void;
 }
 
 export function createCollectionClient<M extends Record<string, unknown> = Record<string, unknown>>(transport: Transport, slug: string, ws?: RebaseWebSocketClient): CollectionClient<M> {
@@ -111,6 +178,55 @@ export function createCollectionClient<M extends Record<string, unknown> = Recor
             return raw.count ?? 0;
         },
 
+        // Reactive reads. Without the offline layer there is no local database
+        // to read from, so this is a fetch plus — when realtime is available —
+        // the live subscription that keeps it current.
+        observe(
+            params: FindParams | undefined,
+            onResult: (result: LiveResult<M>) => void,
+            onError?: (error: Error) => void,
+            options?: ObserveOptions
+        ) {
+            let closed = false;
+            const emit = (result: FindResult<M>) => {
+                if (closed) return;
+                onResult({ ...result, fromCache: false, hasPendingWrites: false, partial: false });
+            };
+            client.find(params).then(emit).catch((error) => {
+                if (!closed) onError?.(error as Error);
+            });
+            const live = options?.realtime !== false && client.listen
+                ? client.listen(params, emit, onError)
+                : undefined;
+            return () => {
+                closed = true;
+                live?.();
+            };
+        },
+
+        observeById(
+            id: string | number,
+            onResult: (row: M | undefined, meta: RowSnapshotMeta) => void,
+            onError?: (error: Error) => void,
+            options?: ObserveOptions
+        ) {
+            let closed = false;
+            const emit = (row: M | undefined) => {
+                if (closed) return;
+                onResult(row, { fromCache: false, hasPendingWrites: false });
+            };
+            client.findById(id).then(emit).catch((error) => {
+                if (!closed) onError?.(error as Error);
+            });
+            const live = options?.realtime !== false && client.listenById
+                ? client.listenById(id, emit, onError)
+                : undefined;
+            return () => {
+                closed = true;
+                live?.();
+            };
+        },
+
         // Fluent builder instantiation
         where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown) {
             const builder = new SDKQueryBuilder<M>(client);

package/src/index.ts

@@ -11,6 +11,7 @@ import { createStorage } from "./storage";
 import { ClientStorageSourceRegistry } from "./storage-registry";
 import { RebaseWebSocketClient } from "./websocket";
 import { RebaseRealtimeChannel, type ChannelOptions } from "./realtime-channel";
+import { OfflineManager, type OfflineApi, type OfflineConfig } from "./offline";
 import {
     DEFAULT_STORAGE_SOURCE_KEY,
     InsertOf,
@@ -88,6 +89,20 @@ export type {
     ChannelHistoryResult
 } from "./realtime-channel";
 
+// Offline: config, the `client.offline` surface, and the metadata a UI needs
+// to reflect sync state. `isOfflineError` distinguishes "there was no network
+// and nothing local to answer with" from a request that genuinely failed.
+// The store contract is public so other environments (React Native/
+// AsyncStorage, Electron, …) can supply their own persistence;
+// `MemoryOfflineStore` is exported for tests and as the reference
+// implementation, while the IndexedDB store is wired automatically in the
+// browser and needs no direct construction.
+export type { OfflineApi, OfflineConfig, OfflineStatus } from "./offline";
+export { isOfflineError } from "./offline";
+export type { LiveResult, ObserveOptions, RowSnapshotMeta } from "./collection";
+export type { OfflineStore, OfflineCacheEntry, OfflineCacheRecord, PendingMutation, MutationRollback } from "./offline-store";
+export { MemoryOfflineStore } from "./offline-store";
+
 export interface CreateRebaseClientOptions extends RebaseClientConfig {
     auth?: CreateAuthOptions;
     admin?: CreateAdminOptions;
@@ -108,6 +123,21 @@ export interface CreateRebaseClientOptions extends RebaseClientConfig {
      * correct slugs via this map before falling back to automatic snake_casing.
      */
     collections?: Record<string, string>;
+    /**
+     * Local-first sync for the data layer.
+     *
+     * `true` enables it with defaults: reads populate a local row database and
+     * fall back to it (evaluating filters and sorts locally) when the network
+     * is gone, writes made offline apply immediately and replay in order when
+     * it returns, and `observe()` becomes a live query that emits from the
+     * local database first. A rejected write is rolled back. Pass an
+     * {@link OfflineConfig} to control the store, cache sizes, retry backoff,
+     * or rejection handling.
+     *
+     * Local rows and queued writes are partitioned per signed-in user, and
+     * shared across tabs. Off by default.
+     */
+    offline?: boolean | OfflineConfig;
 }
 
 // ─── Typed Data Proxy ────────────────────────────────────────────────────────
@@ -186,6 +216,8 @@ export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<Rebase
     call: <T = unknown>(endpoint: string, payload?: unknown) => Promise<T>;
     collection: <M extends Record<string, unknown> = Record<string, unknown>>(slug: string) => CollectionClient<M>;
     data: TypedDataLayer<DB>;
+    /** Present only when the client was created with `offline` enabled. */
+    offline?: OfflineApi;
 };
 
 // ─── Factory ─────────────────────────────────────────────────────────────────
@@ -288,14 +320,7 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
     /** One channel object per name — see `realtime.channel`. */
     const realtimeChannels = new Map<string, RebaseRealtimeChannel>();
     if (resolvedWsUrl) {
-        const wsOnUnauthorized = options.onUnauthorized || (async () => {
-            try {
-                await auth.refreshSession();
-                return true;
-            } catch (e) {
-                return false;
-            }
-        });
+        const wsOnUnauthorized = options.onUnauthorized || (() => auth.handleUnauthorized());
 
         ws = new RebaseWebSocketClient({
             websocketUrl: resolvedWsUrl,
@@ -334,14 +359,11 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
     // options.onUnauthorized — because the transport was already created above
     // and captured the (undefined) value from the config closure.
     if (!options.onUnauthorized) {
-        transport.setOnUnauthorized(async () => {
-            try {
-                await auth.refreshSession();
-                return true;
-            } catch (e) {
-                return false;
-            }
-        });
+        // `handleUnauthorized` (not a bare `refreshSession`) so that a refresh
+        // the server rejects outright drops the session and emits SIGNED_OUT —
+        // otherwise the app keeps thinking it is signed in and every view just
+        // renders "Invalid or expired token".
+        transport.setOnUnauthorized(() => auth.handleUnauthorized());
     }
 
     /**
@@ -398,12 +420,33 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         return undefined;
     }
 
+    // Offline layer: wraps every collection client with a read cache and a
+    // write queue. Replay goes through *unwrapped* clients (the factory below)
+    // so a failing replay can never re-queue itself.
+    const offlineManager = options.offline
+        ? new OfflineManager(
+            typeof options.offline === "object" ? options.offline : {},
+            (slug) => createCollectionClient(transport, slug)
+        )
+        : undefined;
+
+    if (offlineManager) {
+        // Cache and queue are partitioned per user: cached rows are RLS-scoped
+        // to whoever fetched them, and queued writes must replay as the user
+        // who made them — a shared browser must never mix the two.
+        offlineManager.setScope(auth.getSession()?.user?.uid);
+        auth.onAuthStateChange((event, session) => {
+            offlineManager.setScope(event === "SIGNED_OUT" ? undefined : session?.user?.uid);
+        });
+    }
+
     const collectionClients = new Map<string, CollectionClient<Record<string, unknown>>>();
     let untypedWarned = false;
 
     function collection(slug: string): CollectionClient<Record<string, unknown>> {
         if (!collectionClients.has(slug)) {
-            collectionClients.set(slug, createCollectionClient(transport, slug, ws));
+            const inner = createCollectionClient(transport, slug, ws);
+            collectionClients.set(slug, offlineManager ? offlineManager.wrap(slug, inner) : inner);
         }
         return collectionClients.get(slug)!;
     }
@@ -510,6 +553,9 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
             // Permanent: nothing queued afterwards may redial and keep the
             // event loop alive, which is the reason this method exists.
             ws?.disconnect(true);
+            // The offline retry timer is unref'd but the `online` listener is
+            // not, and neither should outlive the client.
+            offlineManager?.dispose();
         },
         setToken: transport.setToken,
         setAuthTokenGetter: transport.setAuthTokenGetter,
@@ -526,6 +572,7 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
             return res.data ?? (res as T);
         },
         data: dataProxy,
+        ...(offlineManager ? { offline: offlineManager.api } : {}),
     } as unknown as CreateRebaseClientResult<DB>;
 
     return target;

package/src/offline-codec.ts

@@ -0,0 +1,79 @@
+import { EntityReference, EntityRelation, GeoPoint, Vector } from "@rebasepro/types";
+import { rebaseReviver } from "./reviver";
+
+/**
+ * Lossless round-tripping of rows through the offline store.
+ *
+ * Both persistence backends move values by structured clone, which keeps
+ * `Date` but flattens every class instance to a plain object. For
+ * `EntityReference`/`EntityRelation` that is harmless — they carry their own
+ * `__type` discriminator, so the JSON reviver can rebuild them — but
+ * `GeoPoint` and `Vector` do not, and would come back out of the cache as
+ * anonymous `{ latitude, longitude }` / `{ value }` bags. A row read from the
+ * cache must be indistinguishable from the same row read from the network, so
+ * those two are tagged on the way in and revived on the way out.
+ *
+ * Type tests here are structural rather than `instanceof`, because a structured
+ * clone can arrive from another realm — an iframe, a worker, or the polyfill
+ * the tests run against — where the constructor identity differs but the value
+ * is the real thing. Only *plain* objects are walked; anything else is passed
+ * through whole, so a class instance is never quietly reduced to `{}`.
+ */
+
+function isDate(value: unknown): value is Date {
+    return Object.prototype.toString.call(value) === "[object Date]";
+}
+
+/** An object literal — not a Date, RegExp, Map, or any class instance. */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+    const proto = Object.getPrototypeOf(value) as { constructor?: { name?: string } } | null;
+    if (proto === null || proto === Object.prototype) return true;
+    // A literal cloned out of another realm has a different `Object.prototype`
+    // but is still, in every way that matters here, a plain object.
+    return proto.constructor?.name === "Object";
+}
+
+function dehydrateValue(value: unknown): unknown {
+    if (value === null || value === undefined) return value;
+    if (value instanceof GeoPoint) {
+        return { __type: "GeoPoint", latitude: value.latitude, longitude: value.longitude };
+    }
+    if (value instanceof Vector) return { __type: "Vector", value: [...value.value] };
+    // EntityReference/EntityRelation already serialize themselves via `__type`
+    // own properties, so a structured clone is enough for the reviver below.
+    if (value instanceof EntityReference || value instanceof EntityRelation) return value;
+    if (Array.isArray(value)) return value.map(dehydrateValue);
+    if (isPlainObject(value)) {
+        const out: Record<string, unknown> = {};
+        for (const [key, inner] of Object.entries(value)) out[key] = dehydrateValue(inner);
+        return out;
+    }
+    return value;
+}
+
+function hydrateValue(value: unknown): unknown {
+    if (value === null || value === undefined || isDate(value)) return value;
+    if (Array.isArray(value)) return value.map(hydrateValue);
+    if (typeof value === "object") {
+        const revived = rebaseReviver("", value);
+        // The reviver recognised it — hand back the class instance untouched
+        // rather than walking into its (now private) internals.
+        if (revived !== value) return revived;
+        if (!isPlainObject(value)) return value;
+        const out: Record<string, unknown> = {};
+        for (const [key, inner] of Object.entries(value)) out[key] = hydrateValue(inner);
+        return out;
+    }
+    return value;
+}
+
+/** Prepare a row for the store. */
+export function dehydrateRow<T extends Record<string, unknown>>(row: T): Record<string, unknown> {
+    return dehydrateValue(row) as Record<string, unknown>;
+}
+
+/** Restore a row read back from the store. */
+export function hydrateRow<T extends Record<string, unknown>>(row: Record<string, unknown>): T {
+    return hydrateValue(row) as T;
+}

package/src/offline-connectivity.test.ts

@@ -0,0 +1,157 @@
+import { ConnectivityMonitor, isNetworkError, isRetryableError } from "./offline-connectivity";
+import { RebaseApiError } from "./transport";
+
+/**
+ * The monitor decides whether a request is worth sending at all, so getting it
+ * wrong is either an app that hangs on every read during an outage, or one that
+ * never notices the network came back.
+ */
+describe("network error classification", () => {
+    it("recognises a request that never reached the server", () => {
+        expect(isNetworkError(new TypeError("Failed to fetch"))).toBe(true);
+        expect(isNetworkError(new TypeError("fetch failed"))).toBe(true);
+        expect(isNetworkError(Object.assign(new Error("aborted"), { name: "AbortError" }))).toBe(true);
+        expect(isNetworkError(Object.assign(new Error("timed out"), { name: "TimeoutError" }))).toBe(true);
+        expect(isNetworkError(new RebaseApiError("no response", { status: 0 }))).toBe(true);
+    });
+
+    it("does not mistake a server's answer for a dead network", () => {
+        expect(isNetworkError(new RebaseApiError("nope", { status: 403 }))).toBe(false);
+        expect(isNetworkError(new RebaseApiError("boom", { status: 500 }))).toBe(false);
+        // A programming error must propagate, not be swallowed as "offline".
+        expect(isNetworkError(new RangeError("bug"))).toBe(false);
+    });
+
+    it("retries what will pass and gives up on what will not", () => {
+        expect(isRetryableError(new TypeError("Failed to fetch"))).toBe(true);
+        expect(isRetryableError(new RebaseApiError("busy", { status: 429 }))).toBe(true);
+        expect(isRetryableError(new RebaseApiError("down", { status: 503 }))).toBe(true);
+        expect(isRetryableError(new RebaseApiError("gateway", { status: 502 }))).toBe(true);
+
+        expect(isRetryableError(new RebaseApiError("invalid", { status: 400 }))).toBe(false);
+        expect(isRetryableError(new RebaseApiError("denied", { status: 403 }))).toBe(false);
+        expect(isRetryableError(new RebaseApiError("gone", { status: 404 }))).toBe(false);
+        // A 500 is far more often a bug the same payload will hit again than a
+        // blip, and retrying it forever jams every write queued behind it.
+        expect(isRetryableError(new RebaseApiError("boom", { status: 500 }))).toBe(false);
+    });
+});
+
+describe("ConnectivityMonitor", () => {
+    function createMonitor(overrides: Partial<ConstructorParameters<typeof ConnectivityMonitor>[0]> = {}) {
+        let now = 1_000_000;
+        const timers: { fn: () => void; at: number }[] = [];
+        const monitor = new ConnectivityMonitor({
+            initialBackoffMs: 100,
+            maxBackoffMs: 800,
+            now: () => now,
+            setTimer: ((fn: () => void, ms: number) => {
+                timers.push({ fn, at: now + ms });
+                return timers.length as unknown as ReturnType<typeof setTimeout>;
+            }) as never,
+            clearTimer: (() => undefined) as never,
+            ...overrides
+        });
+        const advance = (ms: number) => {
+            now += ms;
+            for (const timer of timers.splice(0)) {
+                if (timer.at <= now) timer.fn();
+                else timers.push(timer);
+            }
+        };
+        return { monitor, advance, at: () => now };
+    }
+
+    it("starts willing to try", () => {
+        const { monitor } = createMonitor();
+        expect(monitor.isOnline()).toBe(true);
+        expect(monitor.shouldAttempt()).toBe(true);
+    });
+
+    it("stops attempting after a failure, until the backoff window opens", () => {
+        const { monitor, advance } = createMonitor();
+        monitor.markFailure();
+
+        expect(monitor.isOnline()).toBe(false);
+        // This is the whole point: the second read during an outage costs
+        // nothing instead of another timeout.
+        expect(monitor.shouldAttempt()).toBe(false);
+
+        advance(200);
+        expect(monitor.shouldAttempt()).toBe(true);
+    });
+
+    it("doubles the delay on repeated failures and caps it", () => {
+        const { monitor, advance } = createMonitor();
+        monitor.markFailure();
+        const first = monitor.msUntilRetry();
+        advance(first);
+
+        monitor.markFailure();
+        const second = monitor.msUntilRetry();
+        expect(second).toBeGreaterThan(first);
+
+        for (let i = 0; i < 10; i++) {
+            advance(monitor.msUntilRetry());
+            monitor.markFailure();
+        }
+        // 800 plus the 20% jitter ceiling.
+        expect(monitor.msUntilRetry()).toBeLessThanOrEqual(800 * 1.2);
+    });
+
+    it("resets the backoff once a request gets through", () => {
+        const { monitor, advance } = createMonitor();
+        monitor.markFailure();
+        advance(monitor.msUntilRetry());
+        monitor.markFailure();
+        monitor.markSuccess();
+
+        expect(monitor.isOnline()).toBe(true);
+        expect(monitor.shouldAttempt()).toBe(true);
+        monitor.markFailure();
+        // Back to the initial delay, not to where the doubling had reached.
+        expect(monitor.msUntilRetry()).toBeLessThanOrEqual(100 * 1.2);
+    });
+
+    it("fires the retry hook when the window opens", () => {
+        const { monitor, advance } = createMonitor();
+        let retries = 0;
+        monitor.onRetryDue = () => { retries++; };
+
+        monitor.markFailure();
+        expect(retries).toBe(0);
+        advance(200);
+        expect(retries).toBe(1);
+    });
+
+    it("backs off without claiming the connection is gone", () => {
+        const { monitor } = createMonitor();
+        // A 429 means the server answered — the app is demonstrably online and
+        // an "offline" badge would be a lie.
+        monitor.deferRetry();
+        expect(monitor.isOnline()).toBe(true);
+        expect(monitor.shouldAttempt()).toBe(true);
+    });
+
+    it("notifies listeners on each transition, and only on transitions", () => {
+        const { monitor } = createMonitor();
+        const seen: boolean[] = [];
+        monitor.onChange((online) => seen.push(online));
+
+        monitor.markFailure();
+        monitor.markFailure();
+        monitor.markSuccess();
+        monitor.markSuccess();
+
+        expect(seen).toEqual([false, true]);
+    });
+
+    it("keeps attempting when backoff suppression is off", () => {
+        // Without a retry timer nothing would ever reopen the window, so
+        // suppressing attempts would strand the client offline forever.
+        const { monitor } = createMonitor({ respectBackoff: false });
+        monitor.markFailure();
+        expect(monitor.isOnline()).toBe(false);
+        expect(monitor.shouldAttempt()).toBe(true);
+    });
+});