@bayonai/offline 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-## 0.8.0 - Unreleased
+## 0.9.0 - 2026-09-26
+
+- Added independent read-cache freshness and retention windows with explicit
+  `fresh`, `stale`, and `miss` outcomes and selectable refresh-failure behavior.
+- Added retained fallback and stale in-flight response protection to forced
+  `loadReadCacheResource` refreshes.
+- Added payload-free read-cache outcome callbacks for host-owned telemetry.
+- Preserved existing `maxAgeMs` behavior for callers that do not opt into the
+  new policy. Forced refreshes retain fallback data while invalidating older
+  in-flight cache writes.
+- Isolated pending-write listing and clearing by `keyPrefix` when logical
+  queues share one physical object store.
+- Fixed NodeNext declaration resolution and supplied matching declarations for
+  both ESM and CommonJS consumers.
+- Restored offline retry-control text when a reload attempt throws.
+
+## 0.8.0 - 2026-09-25
 
 - Added authoritative-result reconciliation to `createDurableCommandStore`,
   including rebasing remaining optimistic commands without a transient revert.

package/README.md

@@ -25,8 +25,15 @@ import {
   createReadCacheKey,
   loadReadCacheResource,
   pruneReadCache,
+  type ReadCachePolicy,
 } from "@bayonai/offline";
 
+const policy: ReadCachePolicy = {
+  freshForMs: 30_000,
+  retainForMs: 7 * 24 * 60 * 60_000,
+  refreshFailure: "use-retained",
+};
+
 const cache = createBrowserReadCache({
   databaseName: "my-app:v1",
   storeName: "read-cache",
@@ -43,13 +50,41 @@ const projects = await loadReadCacheResource({
   cache,
   key,
   loadFresh: () => fetchProjects(),
-  maxAgeMs: 30_000,
-  onUpdate: ({ data, fromCache }) => {
-    renderProjects(data, { fromCache });
+  onOutcome: (outcome) => telemetry.record("offline-read", { outcome }),
+  policy,
+  onUpdate: ({ data, status, fromCache }) => {
+    renderProjects(data, { fromCache, status });
   },
 });
 ```
 
+`freshForMs` controls how long a cached value can avoid a remote read.
+`retainForMs` independently controls how long it can be shown as an offline
+fallback. A stale-but-retained value is emitted immediately and revalidated;
+an expired value is not emitted and cannot mask a loader failure. The
+`status` is `fresh`, `stale`, or `miss`: a stale update is retained data while
+refreshing or after a failed refresh, and a miss is a successful loader result
+with no retained cache. Successful remote results are `fresh` when replacing
+stale data and `miss` when there was no usable retained data.
+
+`onOutcome` emits only a fixed event name (`fresh-hit`, `stale-hit`,
+`cache-miss`, `forced-refresh`, `loader-success`, or `loader-failure`). It never
+includes cache keys, user identifiers, payloads, or error messages. Callback
+exceptions are logged and isolated from the read.
+
+When refresh fails, `refreshFailure: "use-retained"` returns retained data
+with `status: "stale"` and the error; `"throw"` propagates the loader error.
+This also applies to forced refresh. Set `forceFresh: true` on
+`loadReadCacheResource` or `readThroughCache` to bypass freshness, retain
+eligible data as the failure fallback, and advance the cache generation so an
+older in-flight load cannot overwrite the refresh. `readThroughCache` returns
+the `status` field alongside its existing `fromCache`, `stale`, and `error`
+fields.
+
+For compatibility, callers that omit `policy` retain the previous `maxAgeMs`
+freshness behavior and have no age-based fallback expiry. New callers should
+use `policy`; when supplied it takes precedence over the legacy `maxAgeMs`.
+
 After a successful write, use `readThroughCache({ forceFresh: true })` when
 the next read must be server-confirmed rather than a pre-write cached or
 in-flight response. Concurrent ordinary reads for the same cache/key share one
@@ -102,6 +137,11 @@ Failed sync results include a safe persisted `error` string and the original
 non-persisted `failure` value. Hosts may use `failure` for structured logging or
 domain error classification; it is never written into the pending-write store.
 
+`keyPrefix` is an isolation boundary inside a shared object store. Listing,
+recovery, and `clearAll()` affect only that prefix, so independent logical
+queues may safely share the same IndexedDB database and store when their
+prefixes are distinct.
+
 For a browser application that wants durable, silent recovery, mount the
 headless controller once for the active account or workspace:
 
@@ -306,15 +346,16 @@ opened at the same version.
 
 ```bash
 pnpm --filter @bayonai/offline test
+pnpm --filter @bayonai/offline test:coverage
 pnpm --filter @bayonai/offline run build
-pnpm --filter @bayonai/offline pack --dry-run
+pnpm --filter @bayonai/offline pack:smoke
 ```
 
 ## Publish Checklist
 
 1. Run the package tests and build.
 2. Run the 100% coverage gate and production dependency audit.
-3. Run `pnpm --filter @bayonai/offline pack --dry-run` and confirm the tarball
+3. Run `pnpm --filter @bayonai/offline pack:smoke` and confirm the tarball
    includes only `package.json`, `dist`, `dist-cjs`, `README.md`,
    `CHANGELOG.md`, and `LICENSE`.
 4. Install the generated tarball into an isolated consumer and verify ESM,

package/dist/browserFallbackRecovery.js

@@ -12,6 +12,7 @@ export function createBrowserOfflineFallbackRecovery({ control, environment = cr
     function retry() {
         if (retrying)
             return;
+        const previousText = control.textContent;
         retrying = true;
         control.disabled = true;
         control.textContent = retryingText;
@@ -25,6 +26,7 @@ export function createBrowserOfflineFallbackRecovery({ control, environment = cr
             });
             retrying = false;
             control.disabled = false;
+            control.textContent = previousText;
         }
     }
     function handleTouchStart(event) {

package/dist/browserRecovery.d.ts

@@ -1,5 +1,5 @@
-import { type PendingWriteRecord, type PendingWriteStore, type PendingWriteSync, type SyncPendingWritesResult } from "./pendingWrites";
-import type { BrowserPendingWriteRecoveryCoordination } from "./browserCoordination";
+import { type PendingWriteRecord, type PendingWriteStore, type PendingWriteSync, type SyncPendingWritesResult } from "./pendingWrites.js";
+import type { BrowserPendingWriteRecoveryCoordination } from "./browserCoordination.js";
 export declare const initialPendingWriteRetryDelayMs = 2000;
 export declare const maxPendingWriteRetryDelayMs = 60000;
 export type BrowserPendingWriteRecoveryEnvironment = {

package/dist/durableCommandStore.d.ts

@@ -1,4 +1,4 @@
-import { type PendingWriteRecord, type PendingWriteStore } from "./pendingWrites";
+import { type PendingWriteRecord, type PendingWriteStore } from "./pendingWrites.js";
 export type DurableCommandErrorCategory = "auth" | "conflict" | "connectivity" | "local-storage" | "permission" | "unexpected" | "validation";
 export type DurableCommandOperation<Command> = {
     command: Command;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export * from "./readCache";
-export * from "./pendingWrites";
-export * from "./browserRecovery";
-export * from "./browserCoordination";
-export * from "./browserFallbackRecovery";
-export * from "./durableCommandStore";
-export { OfflineStorageError } from "./idbDriver";
+export * from "./readCache.js";
+export * from "./pendingWrites.js";
+export * from "./browserRecovery.js";
+export * from "./browserCoordination.js";
+export * from "./browserFallbackRecovery.js";
+export * from "./durableCommandStore.js";
+export { OfflineStorageError } from "./idbDriver.js";

package/dist/pendingWrites.d.ts

@@ -1,4 +1,4 @@
-import { type BrowserKeyValueDriverOptions } from "./idbDriver";
+import { type BrowserKeyValueDriverOptions } from "./idbDriver.js";
 export declare const pendingWriteSchemaVersion = 1;
 export declare const pendingWriteOperationTimeoutMs = 2000;
 export declare const pendingWriteSyncLeaseTimeoutMs = 60000;
@@ -22,10 +22,14 @@ export type PendingWritePayloadNormalizer<Payload = unknown> = (payload: unknown
 export type PendingWriteDriver = {
     clear: (key: string) => Promise<void>;
     clearIf: (key: string, predicate: PendingWritePredicate) => Promise<boolean>;
-    clearAll: () => Promise<void>;
+    clearAll?: () => Promise<void>;
     close?: () => Promise<void>;
     get: (key: string) => Promise<unknown | null>;
     list: () => Promise<unknown[]>;
+    listEntries?: () => Promise<Array<{
+        key: string;
+        value: unknown;
+    }>>;
     set: (key: string, value: unknown) => Promise<void>;
     setIf: (key: string, value: unknown, predicate: PendingWritePredicate) => Promise<boolean>;
 };

package/dist/pendingWrites.js

@@ -17,6 +17,29 @@ export function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyReco
             }
         }
     };
+    async function listScopedRecords() {
+        const readOptions = { normalizeLegacyRecord, normalizePayload };
+        const entries = await driver.listEntries?.();
+        if (entries) {
+            const keyPrefixBoundary = `${keyPrefix}:`;
+            return entries
+                .filter(({ key }) => key.startsWith(keyPrefixBoundary))
+                .map(({ value }) => toPendingWriteEnvelope(value, schemaVersion, readOptions)
+                ?.record)
+                .filter((record) => Boolean(record));
+        }
+        // Compatibility path for custom drivers created before listEntries was
+        // available. Point reads prove that each candidate belongs to this prefix.
+        const candidateIds = new Set((await driver.list())
+            .map((value) => toPendingWriteEnvelope(value, schemaVersion, readOptions)
+            ?.record.id)
+            .filter((id) => Boolean(id)));
+        const records = await Promise.all([...candidateIds].map(async (id) => {
+            const value = await driver.get(createPendingWriteKey({ id, prefix: keyPrefix }));
+            return toPendingWriteEnvelope(value, schemaVersion, readOptions)?.record;
+        }));
+        return records.filter((record) => Boolean(record));
+    }
     return {
         async claimIfSnapshotId(id, snapshotId, record, now) {
             const claimed = await driver.setIf(createPendingWriteKey({ id, prefix: keyPrefix }), { record, schemaVersion }, (value) => {
@@ -37,7 +60,20 @@ export function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyReco
             notify({ id, type: "clear" });
         },
         async clearAll() {
-            await driver.clearAll();
+            const entries = await driver.listEntries?.();
+            if (entries) {
+                const keyPrefixBoundary = `${keyPrefix}:`;
+                await Promise.all(entries
+                    .filter(({ key }) => key.startsWith(keyPrefixBoundary))
+                    .map(({ key }) => driver.clear(key)));
+            }
+            else {
+                const records = await listScopedRecords();
+                await Promise.all(records.map((record) => driver.clearIf(createPendingWriteKey({ id: record.id, prefix: keyPrefix }), (value) => toPendingWriteEnvelope(value, schemaVersion, {
+                    normalizeLegacyRecord,
+                    normalizePayload,
+                })?.record.snapshotId === record.snapshotId)));
+            }
             notify({ type: "clearAll" });
         },
         async clearIfSnapshotId(id, snapshotId) {
@@ -57,13 +93,7 @@ export function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyReco
             return (toPendingWriteEnvelope(await driver.get(createPendingWriteKey({ id, prefix: keyPrefix })), schemaVersion, { normalizeLegacyRecord, normalizePayload })?.record ?? null);
         },
         async list() {
-            return (await driver.list())
-                .map((value) => toPendingWriteEnvelope(value, schemaVersion, {
-                normalizeLegacyRecord,
-                normalizePayload,
-            })?.record)
-                .filter((record) => Boolean(record))
-                .sort((left, right) => left.savedAt.localeCompare(right.savedAt) ||
+            return (await listScopedRecords()).sort((left, right) => left.savedAt.localeCompare(right.savedAt) ||
                 left.id.localeCompare(right.id));
         },
         async replaceIfSnapshotId(id, snapshotId, record) {
@@ -118,6 +148,9 @@ export function createMemoryPendingWriteDriver() {
         async list() {
             return [...records.values()];
         },
+        async listEntries() {
+            return [...records].map(([key, value]) => ({ key, value }));
+        },
         async set(key, value) {
             records.set(key, value);
         },
@@ -374,7 +407,6 @@ function createUnavailablePendingWriteDriver() {
         async clearIf() {
             return false;
         },
-        async clearAll() { },
         async close() { },
         async get() {
             return null;
@@ -398,6 +430,7 @@ function toPendingWriteDriver(driver) {
         close: driver.close,
         get: driver.get,
         list: driver.list,
+        listEntries: driver.listEntries,
         set: driver.set,
         setIf: driver.setIf,
     };

package/dist/readCache.d.ts

@@ -1,4 +1,4 @@
-import { type BrowserKeyValueDriverOptions } from "./idbDriver";
+import { type BrowserKeyValueDriverOptions } from "./idbDriver.js";
 export declare const readCacheSchemaVersion = 1;
 export declare const readCacheFreshnessMaxAgeMs = 30000;
 export declare const durableReadCacheFreshnessMaxAgeMs: number;
@@ -29,21 +29,36 @@ export type ReadCache = {
     clear: () => Promise<void>;
     close: () => Promise<void>;
     delete: (key: string) => Promise<void>;
+    /** Advances a key's generation without deleting its retained value. */
+    invalidate?: (key: string) => void;
     get: <T>(key: string) => Promise<ReadCacheHit<T> | null>;
     getVersion: (key: string) => string;
     set: <T>(key: string, value: T) => Promise<void>;
     setIfVersion: <T>(key: string, value: T, version: string) => Promise<boolean>;
 };
+export type ReadCachePolicy = {
+    /** Time that a cached value can suppress a remote read. */
+    freshForMs: number;
+    /** Maximum age at which cached data remains eligible as an offline fallback. */
+    retainForMs: number;
+    /** Behavior when revalidation fails while retained data is available. */
+    refreshFailure: "use-retained" | "throw";
+};
+export type ReadCacheStatus = "fresh" | "stale" | "miss";
+/** Payload-free cache lifecycle events suitable for host-owned telemetry. */
+export type ReadCacheOutcome = "fresh-hit" | "stale-hit" | "cache-miss" | "forced-refresh" | "loader-success" | "loader-failure";
 export type ReadThroughCacheResult<T> = {
     data: T;
     error: Error | null;
     fromCache: boolean;
     stale: boolean;
+    status: ReadCacheStatus;
 };
 export type ReadCacheResourceUpdate<T> = {
     data: T;
     error?: Error;
     fromCache: boolean;
+    status: ReadCacheStatus;
 };
 export type BrowserReadCacheOptions = Partial<Pick<BrowserKeyValueDriverOptions, "databaseVersion" | "indexedDB">> & {
     databaseName: string;
@@ -69,22 +84,28 @@ export declare function pruneReadCache({ cache, maxAgeMs, now, }: {
     now?: () => number;
 }): Promise<number>;
 export declare function createReadCacheKey({ namespace, params, prefix, scope, }: ReadCacheKeyOptions): string;
-export declare function readThroughCache<T>({ cache, forceFresh, key, loadFresh, maxAgeMs, }: {
+export declare function readThroughCache<T>({ cache, forceFresh, key, loadFresh, maxAgeMs, onOutcome, policy, }: {
     cache: ReadCache;
     /**
-     * Invalidates the current value before loading. Use after a successful write
-     * when a cached or earlier in-flight response must not become authoritative.
+     * Revalidates after advancing the key generation, retaining the prior value
+     * as a possible fallback if refresh fails.
      */
     forceFresh?: boolean;
     key: string;
     loadFresh: () => Promise<T>;
     maxAgeMs?: number;
+    onOutcome?: (outcome: ReadCacheOutcome) => void;
+    policy?: ReadCachePolicy;
 }): Promise<ReadThroughCacheResult<T>>;
-export declare function loadReadCacheResource<T>({ cache, key, loadFresh, maxAgeMs, onCacheWriteError, onUpdate, skipCache, }: {
+export declare function loadReadCacheResource<T>({ cache, forceFresh, key, loadFresh, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache, }: {
     cache: ReadCache;
+    /** Revalidate while retaining eligible data as fallback on loader failure. */
+    forceFresh?: boolean;
     key: string;
     loadFresh: () => Promise<T>;
     maxAgeMs?: number;
+    onOutcome?: (outcome: ReadCacheOutcome) => void;
+    policy?: ReadCachePolicy;
     onCacheWriteError?: (error: Error) => void;
     onUpdate: (update: ReadCacheResourceUpdate<T>) => void;
     skipCache?: boolean;

package/dist/readCache.js

@@ -16,6 +16,10 @@ export function createReadCache(driver) {
     function getVersion(key) {
         return `${globalVersion}:${keyVersions.get(key) ?? 0}`;
     }
+    function invalidate(key) {
+        pendingLoads.delete(key);
+        keyVersions.set(key, (keyVersions.get(key) ?? 0) + 1);
+    }
     function enqueue(operation) {
         const next = operationQueue.then(operation, operation);
         operationQueue = next.then(() => undefined, () => undefined);
@@ -32,10 +36,10 @@ export function createReadCache(driver) {
             await enqueue(async () => driver.close?.());
         },
         async delete(key) {
-            pendingLoads.delete(key);
-            keyVersions.set(key, (keyVersions.get(key) ?? 0) + 1);
+            invalidate(key);
             await enqueue(() => driver.delete(key));
         },
+        invalidate,
         async get(key) {
             const envelope = toReadCacheEnvelope(await driver.get(key));
             return envelope
@@ -152,13 +156,21 @@ export function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
         .filter(Boolean)
         .join(":");
 }
-export async function readThroughCache({ cache, forceFresh = false, key, loadFresh, maxAgeMs, }) {
+export async function readThroughCache({ cache, forceFresh = false, key, loadFresh, maxAgeMs, onOutcome, policy, }) {
     const resourceCache = cache.capture?.() ?? cache;
+    const resolvedPolicy = resolvePolicy(policy, maxAgeMs);
+    const forcedFallback = forceFresh ? await resourceCache.get(key) : null;
     if (forceFresh) {
-        // Deletion advances the cache version, so a request started before this
-        // post-write refresh cannot restore stale data after it finishes.
+        reportReadCacheOutcome(onOutcome, "forced-refresh");
+        // Built-in caches advance generation without deleting fallback data.
+        // Legacy custom adapters retain their old delete behavior.
         try {
-            await resourceCache.delete(key);
+            if (resourceCache.invalidate) {
+                resourceCache.invalidate(key);
+            }
+            else {
+                await resourceCache.delete(key);
+            }
         }
         catch (error) {
             console.error("[Bayon offline] Unable to invalidate the read cache.", {
@@ -168,17 +180,22 @@ export async function readThroughCache({ cache, forceFresh = false, key, loadFre
         }
     }
     const version = resourceCache.getVersion(key);
-    const cached = await resourceCache.get(key);
-    if (cached && isCacheFresh(cached.savedAt, maxAgeMs)) {
+    const cached = forcedFallback ?? (await resourceCache.get(key));
+    const retained = cached && isCacheRetained(cached.savedAt, resolvedPolicy);
+    if (!forceFresh && retained && isCacheFresh(cached.savedAt, resolvedPolicy)) {
+        reportReadCacheOutcome(onOutcome, "fresh-hit");
         return {
             data: cached.value,
             error: null,
             fromCache: true,
             stale: false,
+            status: "fresh",
         };
     }
+    reportReadCacheOutcome(onOutcome, retained ? "stale-hit" : "cache-miss");
     try {
         const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
+        reportReadCacheOutcome(onOutcome, "loader-success");
         try {
             await resourceCache.setIfVersion(key, fresh, version);
         }
@@ -193,33 +210,74 @@ export async function readThroughCache({ cache, forceFresh = false, key, loadFre
             error: null,
             fromCache: false,
             stale: false,
+            status: retained ? "fresh" : "miss",
         };
     }
     catch (error) {
-        if (cached) {
+        reportReadCacheOutcome(onOutcome, "loader-failure");
+        if (retained && resolvedPolicy.refreshFailure === "use-retained") {
             return {
                 data: cached.value,
                 error: normalizeError(error),
                 fromCache: true,
                 stale: true,
+                status: "stale",
             };
         }
         throw error;
     }
 }
-export async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, onCacheWriteError, onUpdate, skipCache = false, }) {
+export async function loadReadCacheResource({ cache, forceFresh = false, key, loadFresh, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache = false, }) {
     const resourceCache = cache.capture?.() ?? cache;
+    const resolvedPolicy = resolvePolicy(policy, maxAgeMs);
+    const forcedFallback = forceFresh ? await resourceCache.get(key) : null;
+    if (forceFresh) {
+        reportReadCacheOutcome(onOutcome, "forced-refresh");
+        try {
+            if (resourceCache.invalidate) {
+                resourceCache.invalidate(key);
+            }
+            else {
+                await resourceCache.delete(key);
+            }
+        }
+        catch (error) {
+            console.error("[Bayon offline] Unable to invalidate the read cache.", {
+                error: normalizeError(error),
+                key,
+            });
+        }
+    }
     const version = resourceCache.getVersion(key);
-    const cached = skipCache ? null : await resourceCache.get(key);
-    if (cached) {
-        onUpdate({ data: cached.value, fromCache: true });
-        if (isCacheFresh(cached.savedAt, maxAgeMs)) {
+    const cached = skipCache
+        ? null
+        : (forcedFallback ?? (await resourceCache.get(key)));
+    const retained = cached && isCacheRetained(cached.savedAt, resolvedPolicy);
+    if (retained) {
+        const fresh = isCacheFresh(cached.savedAt, resolvedPolicy);
+        reportReadCacheOutcome(onOutcome, fresh && !forceFresh ? "fresh-hit" : "stale-hit");
+        onUpdate({
+            data: cached.value,
+            fromCache: true,
+            status: fresh && !forceFresh ? "fresh" : "stale",
+        });
+        if (fresh && !forceFresh) {
             return cached.value;
         }
     }
+    else {
+        reportReadCacheOutcome(onOutcome, "cache-miss");
+    }
     try {
         const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
-        onUpdate({ data: fresh, fromCache: false });
+        reportReadCacheOutcome(onOutcome, "loader-success");
+        if (resourceCache.getVersion(key) === version) {
+            onUpdate({
+                data: fresh,
+                fromCache: false,
+                status: retained ? "fresh" : "miss",
+            });
+        }
         void resourceCache.setIfVersion(key, fresh, version).catch((error) => {
             const normalizedError = normalizeError(error);
             console.error("[Bayon offline] Unable to refresh the read cache.", {
@@ -231,17 +289,32 @@ export async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, o
         return fresh;
     }
     catch (error) {
-        if (!cached) {
+        reportReadCacheOutcome(onOutcome, "loader-failure");
+        if (!retained || resolvedPolicy.refreshFailure === "throw") {
             throw error;
         }
         onUpdate({
             data: cached.value,
             error: normalizeError(error),
             fromCache: true,
+            status: "stale",
         });
         return cached.value;
     }
 }
+function reportReadCacheOutcome(onOutcome, outcome) {
+    if (!onOutcome)
+        return;
+    try {
+        onOutcome(outcome);
+    }
+    catch (error) {
+        console.error("[Bayon offline] Read-cache outcome callback failed.", {
+            error: normalizeError(error),
+            outcome,
+        });
+    }
+}
 function createNoopReadCacheDriver() {
     return {
         async clear() { },
@@ -256,12 +329,33 @@ function createNoopReadCacheDriver() {
         async set() { },
     };
 }
-function isCacheFresh(savedAt, maxAgeMs) {
-    if (!maxAgeMs || maxAgeMs <= 0) {
+function isCacheFresh(savedAt, policy) {
+    if (policy.freshForMs <= 0) {
         return false;
     }
     const savedTime = Date.parse(savedAt);
-    return Number.isFinite(savedTime) && Date.now() - savedTime <= maxAgeMs;
+    return (Number.isFinite(savedTime) && Date.now() - savedTime <= policy.freshForMs);
+}
+function resolvePolicy(policy, maxAgeMs) {
+    if (policy) {
+        if (!Number.isFinite(policy.freshForMs) ||
+            policy.freshForMs < 0 ||
+            !Number.isFinite(policy.retainForMs) ||
+            policy.retainForMs < policy.freshForMs ||
+            !["use-retained", "throw"].includes(policy.refreshFailure)) {
+            throw new RangeError("[Bayon offline] Invalid read-cache policy: require finite non-negative durations, retainForMs >= freshForMs, and a supported refreshFailure mode.");
+        }
+        return policy;
+    }
+    return {
+        freshForMs: maxAgeMs ?? 0,
+        retainForMs: Number.POSITIVE_INFINITY,
+        refreshFailure: "use-retained",
+    };
+}
+function isCacheRetained(savedAt, policy) {
+    const savedTime = Date.parse(savedAt);
+    return (Number.isFinite(savedTime) && Date.now() - savedTime <= policy.retainForMs);
 }
 async function loadSharedFreshResource(cache, key, loadFresh) {
     const pendingLoads = getPendingFreshLoads(cache);

package/dist-cjs/browserCoordination.d.ts

@@ -0,0 +1,23 @@
+export type BrowserRecoveryMessageChannel = {
+    addEventListener: (type: "message", listener: () => void) => void;
+    close: () => void;
+    postMessage: (message: "pending-write-recovery") => void;
+    removeEventListener: (type: "message", listener: () => void) => void;
+};
+export type BrowserRecoveryLockManager = {
+    request: <T>(name: string, options: {
+        ifAvailable: true;
+    }, callback: (lock: unknown | null) => Promise<T | null>) => Promise<T | null>;
+};
+export type BrowserPendingWriteRecoveryCoordination = {
+    close: () => void;
+    notify: () => void;
+    runExclusive: <T>(attempt: () => Promise<T>) => Promise<T | null>;
+    subscribe: (listener: () => void) => () => void;
+};
+export declare function createBrowserPendingWriteRecoveryCoordination({ channelName, leaseName, channel, locks, }: {
+    channel?: BrowserRecoveryMessageChannel | null;
+    channelName: string;
+    leaseName: string;
+    locks?: BrowserRecoveryLockManager | null;
+}): BrowserPendingWriteRecoveryCoordination;

package/dist-cjs/browserFallbackRecovery.d.ts

@@ -0,0 +1,32 @@
+export declare const defaultOfflineFallbackRetryEvent = "app:network-restored";
+export declare const defaultOfflineFallbackPullThreshold = 72;
+export type BrowserOfflineFallbackRecoveryEnvironment = {
+    addEventListener: (type: string, listener: (event: unknown) => void) => void;
+    getScrollY: () => number;
+    reload: () => void;
+    removeEventListener: (type: string, listener: (event: unknown) => void) => void;
+};
+export type OfflineFallbackRetryControl = {
+    disabled: boolean;
+    textContent: string | null;
+};
+export type BrowserOfflineFallbackRecovery = {
+    /** Attempts recovery once. Repeated calls are ignored while navigation starts. */
+    retry: () => void;
+    start: () => void;
+    stop: () => void;
+};
+export type BrowserOfflineFallbackRecoveryOptions = {
+    control: OfflineFallbackRetryControl;
+    environment?: BrowserOfflineFallbackRecoveryEnvironment;
+    /** A host-native validation callback may dispatch this event after connectivity returns. */
+    retryEvent?: string;
+    retryingText?: string;
+    /** Set to `null` to omit touch pull-to-retry. */
+    pullThreshold?: number | null;
+};
+/**
+ * Owns generic recovery mechanics for a static offline fallback. Hosts retain
+ * all markup, copy, styling, and the choice of a native reconnect event.
+ */
+export declare function createBrowserOfflineFallbackRecovery({ control, environment, pullThreshold, retryEvent, retryingText, }: BrowserOfflineFallbackRecoveryOptions): BrowserOfflineFallbackRecovery;

package/dist-cjs/browserFallbackRecovery.js

@@ -16,6 +16,7 @@ function createBrowserOfflineFallbackRecovery({ control, environment = createDef
     function retry() {
         if (retrying)
             return;
+        const previousText = control.textContent;
         retrying = true;
         control.disabled = true;
         control.textContent = retryingText;
@@ -29,6 +30,7 @@ function createBrowserOfflineFallbackRecovery({ control, environment = createDef
             });
             retrying = false;
             control.disabled = false;
+            control.textContent = previousText;
         }
     }
     function handleTouchStart(event) {