@bayonai/offline 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -1,7 +1,10 @@
-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";
+export * from "./readBoundary.js";
+export * from "./recoveryPolicy.js";
+export * from "./pendingWriteSupersession.js";

package/dist/index.js

@@ -5,3 +5,6 @@ export * from "./browserCoordination.js";
 export * from "./browserFallbackRecovery.js";
 export * from "./durableCommandStore.js";
 export { OfflineStorageError } from "./idbDriver.js";
+export * from "./readBoundary.js";
+export * from "./recoveryPolicy.js";
+export * from "./pendingWriteSupersession.js";

package/dist/pendingWriteSupersession.d.ts

@@ -0,0 +1,11 @@
+import type { PendingWriteRecord, PendingWriteStore } from "./pendingWrites.js";
+/**
+ * After remote acknowledgment, retire only rejected snapshots superseded by an
+ * explicit host-owned account/entity/field key. Never infer keys from payloads.
+ */
+export declare function clearSupersededPendingWriteFailures<Payload>({ acknowledged, getSupersessionKey, isRejected, store, }: {
+    acknowledged: PendingWriteRecord<Payload>;
+    getSupersessionKey: (record: PendingWriteRecord<Payload>) => string | null;
+    isRejected: (record: PendingWriteRecord<Payload>) => boolean;
+    store: PendingWriteStore<Payload>;
+}): Promise<number>;

package/dist/pendingWriteSupersession.js

@@ -0,0 +1,25 @@
+/**
+ * After remote acknowledgment, retire only rejected snapshots superseded by an
+ * explicit host-owned account/entity/field key. Never infer keys from payloads.
+ */
+export async function clearSupersededPendingWriteFailures({ acknowledged, getSupersessionKey, isRejected, store, }) {
+    const key = getSupersessionKey(acknowledged);
+    if (key === null)
+        return 0;
+    let cleared = 0;
+    for (const previous of await store.list()) {
+        const older = previous.savedAt.localeCompare(acknowledged.savedAt) ||
+            previous.id.localeCompare(acknowledged.id);
+        if (previous.id === acknowledged.id ||
+            older >= 0 ||
+            previous.syncStatus !== "failed" ||
+            previous.syncingAt ||
+            !isRejected(previous) ||
+            getSupersessionKey(previous) !== key)
+            continue;
+        // Snapshot fencing protects a correction or claim accepted during the scan.
+        if (await store.clearIfSnapshotId(previous.id, previous.snapshotId))
+            cleared++;
+    }
+    return cleared;
+}

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);
         },
@@ -137,6 +170,7 @@ export function createBrowserPendingWriteDriver({ databaseName, databaseVersion,
         indexedDB,
         operationTimeoutMs,
         storeName,
+        readFailureMode: "throw",
     });
     return driver ? toPendingWriteDriver(driver) : null;
 }
@@ -374,13 +408,12 @@ function createUnavailablePendingWriteDriver() {
         async clearIf() {
             return false;
         },
-        async clearAll() { },
         async close() { },
         async get() {
-            return null;
+            throw unavailable();
         },
         async list() {
-            return [];
+            throw unavailable();
         },
         async set() {
             throw unavailable();
@@ -398,6 +431,7 @@ function toPendingWriteDriver(driver) {
         close: driver.close,
         get: driver.get,
         list: driver.list,
+        listEntries: driver.listEntries,
         set: driver.set,
         setIf: driver.setIf,
     };

package/dist/readBoundary.d.ts

@@ -0,0 +1,13 @@
+export type ReadBoundaryOptions = {
+    modules: Readonly<Record<string, readonly string[]>>;
+    roots: readonly string[];
+    allowedAdapters: readonly string[];
+    isForbidden: (moduleId: string) => boolean;
+};
+/**
+ * Host contract: supply every reachable local runtime dependency, including
+ * re-exports and dynamic imports. Absent nodes are external leaves. Exact
+ * trusted adapter IDs stop traversal; hosts verify their cache policy separately.
+ * This test utility deliberately owns no parser, framework, or provider policy.
+ */
+export declare function assertReadBoundary({ modules, roots, allowedAdapters, isForbidden, }: ReadBoundaryOptions): void;

package/dist/readBoundary.js

@@ -0,0 +1,23 @@
+/**
+ * Host contract: supply every reachable local runtime dependency, including
+ * re-exports and dynamic imports. Absent nodes are external leaves. Exact
+ * trusted adapter IDs stop traversal; hosts verify their cache policy separately.
+ * This test utility deliberately owns no parser, framework, or provider policy.
+ */
+export function assertReadBoundary({ modules, roots, allowedAdapters, isForbidden, }) {
+    const adapters = new Set(allowedAdapters);
+    const visited = new Set();
+    function visit(id, path) {
+        if (adapters.has(id) || visited.has(id))
+            return;
+        const nextPath = [...path, id];
+        if (isForbidden(id)) {
+            throw new Error(`Read boundary violation: ${nextPath.join(" -> ")}`);
+        }
+        visited.add(id);
+        for (const dependency of modules[id] ?? [])
+            visit(dependency, nextPath);
+    }
+    for (const root of roots)
+        visit(root, []);
+}

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/recoveryPolicy.d.ts

@@ -0,0 +1,20 @@
+/** Shared product decision: recovery is application work, never a retry prompt. */
+export declare const offlineRecoveryCopy: {
+    readonly reload: "Reload";
+    readonly reloading: "Reconnecting…";
+    readonly preservedChanges: "Some changes could not be saved. Your edits are preserved.";
+};
+export type PendingChangesGuidanceState = {
+    hasReadyChanges: boolean;
+    hasDrafts: boolean;
+    hasErrors: boolean;
+    isOffline: boolean;
+};
+/** Hosts project domain records to flags; payloads never enter shared guidance. */
+export declare function getPendingChangesGuidance({ hasReadyChanges, hasDrafts, hasErrors, isOffline, }: PendingChangesGuidanceState): string;
+/**
+ * Recognize known transient transport/service failures without a provider SDK.
+ * Hosts still own domain validation, idempotency, account scope and replay selection.
+ * Unknown failures are not permission to blindly repeat a mutation.
+ */
+export declare function isTransientOfflineError(error: unknown): boolean;

package/dist/recoveryPolicy.js

@@ -0,0 +1,73 @@
+/** Shared product decision: recovery is application work, never a retry prompt. */
+export const offlineRecoveryCopy = {
+    reload: "Reload",
+    reloading: "Reconnecting…",
+    preservedChanges: "Some changes could not be saved. Your edits are preserved.",
+};
+/** Hosts project domain records to flags; payloads never enter shared guidance. */
+export function getPendingChangesGuidance({ hasReadyChanges, hasDrafts, hasErrors, isOffline, }) {
+    if (!hasReadyChanges)
+        return hasDrafts
+            ? "Finish editing these drafts to save them."
+            : offlineRecoveryCopy.preservedChanges;
+    if (!hasDrafts && !hasErrors)
+        return isOffline
+            ? "We’ll sync when you’re back online."
+            : "We’ll sync automatically.";
+    const sync = isOffline
+        ? "Changes ready to send will sync when you’re back online."
+        : "Changes ready to send will sync automatically.";
+    return hasDrafts ? `${sync} Finish editing drafts to save them.` : sync;
+}
+const terminalCodes = new Set([
+    "unauthenticated",
+    "permission-denied",
+    "resource-exhausted",
+    "invalid-argument",
+    "failed-precondition",
+    "not-found",
+    "already-exists",
+]);
+const transientCodes = new Set([
+    "unavailable",
+    "deadline-exceeded",
+    "cancelled",
+    "network-request-failed",
+    "internal",
+    "aborted",
+]);
+// Exact transport diagnostics are safe fallbacks only when no structured code
+// exists. Domain messages mentioning a network/offline setting are not signals.
+const connectivityMessages = new Set([
+    "failed to fetch",
+    "fetch failed",
+    "network request failed",
+    "load failed",
+    "offline",
+    "network unavailable",
+    "failed to get documents from server. these documents may exist in the local cache",
+    "failed to get document because the client is offline",
+]);
+/**
+ * Recognize known transient transport/service failures without a provider SDK.
+ * Hosts still own domain validation, idempotency, account scope and replay selection.
+ * Unknown failures are not permission to blindly repeat a mutation.
+ */
+export function isTransientOfflineError(error) {
+    const record = error && typeof error === "object" ? error : {};
+    const rawCode = "code" in record ? record.code : undefined;
+    const code = typeof rawCode === "string" ? rawCode.toLowerCase().split("/").at(-1) : "";
+    if (terminalCodes.has(code))
+        return false;
+    if (transientCodes.has(code))
+        return true;
+    if (code)
+        return false;
+    const rawMessage = typeof error === "string"
+        ? error
+        : "message" in record
+            ? record.message
+            : undefined;
+    const message = typeof rawMessage === "string" ? rawMessage.toLowerCase() : "";
+    return connectivityMessages.has(message.trim().replace(/[.!]$/, ""));
+}

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;