@bayonai/offline 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.5.1 - 2026-09-12
+
+- Prevented timed-out conditional IndexedDB replacements and deletions from
+  committing after the operation has already reported failure.
+- Preserved strict chronological replay when an older record has an active
+  claim by leaving it and all later records for a future ordered run.
+
+## 0.5.0 - 2026-09-12
+
+- Added `createBrowserOfflineFallbackRecovery`, a framework-free controller
+  for one-shot retry controls, browser reconnects, host-native reconnect
+  events, and optional pull-to-retry on standalone offline fallbacks.
+
 ## 0.4.0 - 2026-09-01
 
 - Fixed cross-context replay claiming: a remote sync now runs only after an

package/README.md

@@ -156,6 +156,30 @@ the current tab as before. A contested lease retries silently with bounded
 backoff. Remote write handlers must remain idempotent because leases do not
 cover other devices or every browser failure mode.
 
+## Static Offline Fallback Recovery
+
+Standalone offline documents can reuse retry mechanics while keeping their
+own markup, branding, copy, and host-native connectivity event name:
+
+```ts
+import { createBrowserOfflineFallbackRecovery } from "@bayonai/offline";
+
+const recovery = createBrowserOfflineFallbackRecovery({
+  control: document.querySelector<HTMLButtonElement>("#reload")!,
+  // Dispatch only after the host platform has validated connectivity.
+  retryEvent: "my-app:network-restored",
+});
+
+recovery.start();
+```
+
+The controller disables the control after the first retry and changes its text
+to `Reconnecting…`; it then reloads once. It listens to browser `online`, the
+configured host event, and (by default) a 72px downward touch gesture beginning
+at the top of the page. Set `pullThreshold: null` when the host owns touch
+recovery. Static fallback documents must still bundle or inline this package
+code; a browser cannot resolve a bare npm package specifier from `public/`.
+
 Use `createOrderedPendingWriteExecutor` when a new write must never overtake a
 previously queued write in the same user, workspace, or other durable scope.
 Its `recover` and `run` methods share one lane: an unresolved predecessor keeps
@@ -178,6 +202,11 @@ Interrupted sync claims expire after one minute so recovery can resume. Records
 created before snapshot identities were introduced remain readable; they receive
 a stable compatibility identity and are upgraded when next updated.
 
+Conditional IndexedDB mutations are cancelled when their storage deadline is
+exceeded, so an operation cannot report failure and then commit later. Ordered
+replay also stops at an active older claim; it never delivers a later record
+whose remote effect could subsequently be overwritten by that predecessor.
+
 Host apps that change their pending-write payload shape can normalize current
 records while keeping domain logic outside the package:
 

package/dist/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/browserFallbackRecovery.js

@@ -0,0 +1,95 @@
+export const defaultOfflineFallbackRetryEvent = "app:network-restored";
+export const defaultOfflineFallbackPullThreshold = 72;
+/**
+ * Owns generic recovery mechanics for a static offline fallback. Hosts retain
+ * all markup, copy, styling, and the choice of a native reconnect event.
+ */
+export function createBrowserOfflineFallbackRecovery({ control, environment = createDefaultBrowserOfflineFallbackRecoveryEnvironment(), pullThreshold = defaultOfflineFallbackPullThreshold, retryEvent = defaultOfflineFallbackRetryEvent, retryingText = "Reconnecting…", }) {
+    let active = false;
+    let retrying = false;
+    let pullStartY = null;
+    function retry() {
+        if (retrying)
+            return;
+        retrying = true;
+        control.disabled = true;
+        control.textContent = retryingText;
+        try {
+            environment.reload();
+        }
+        catch (error) {
+            // A failed navigation must leave the recovery action visible and usable.
+            console.error("[Bayon offline] Offline fallback reload failed.", { error });
+            retrying = false;
+            control.disabled = false;
+        }
+    }
+    function handleTouchStart(event) {
+        const touchY = getSingleTouchY(event, "touches");
+        pullStartY = environment.getScrollY() === 0 ? touchY : null;
+    }
+    function handleTouchEnd(event) {
+        const touchY = getSingleTouchY(event, "changedTouches");
+        if (pullStartY !== null &&
+            touchY !== null &&
+            touchY - pullStartY >= (pullThreshold ?? Number.POSITIVE_INFINITY)) {
+            retry();
+        }
+        pullStartY = null;
+    }
+    return {
+        retry,
+        start() {
+            if (active)
+                return;
+            active = true;
+            environment.addEventListener("online", retry);
+            environment.addEventListener(retryEvent, retry);
+            if (pullThreshold !== null) {
+                environment.addEventListener("touchstart", handleTouchStart);
+                environment.addEventListener("touchend", handleTouchEnd);
+            }
+        },
+        stop() {
+            if (!active)
+                return;
+            active = false;
+            environment.removeEventListener("online", retry);
+            environment.removeEventListener(retryEvent, retry);
+            if (pullThreshold !== null) {
+                environment.removeEventListener("touchstart", handleTouchStart);
+                environment.removeEventListener("touchend", handleTouchEnd);
+            }
+            pullStartY = null;
+        },
+    };
+}
+function createDefaultBrowserOfflineFallbackRecoveryEnvironment() {
+    const target = typeof window === "undefined" ? null : window;
+    return {
+        addEventListener(type, listener) {
+            target?.addEventListener(type, listener);
+        },
+        getScrollY() {
+            return target?.scrollY ?? 0;
+        },
+        reload() {
+            target?.location.reload();
+        },
+        removeEventListener(type, listener) {
+            target?.removeEventListener(type, listener);
+        },
+    };
+}
+function getSingleTouchY(event, key) {
+    if (!event || typeof event !== "object")
+        return null;
+    const touches = Reflect.get(event, key);
+    if (!touches || typeof touches !== "object")
+        return null;
+    const touch = Reflect.get(touches, 0);
+    if (!touch || typeof touch !== "object")
+        return null;
+    const clientY = Reflect.get(touch, "clientY");
+    return typeof clientY === "number" ? clientY : null;
+}

package/dist/idbDriver.js

@@ -1,4 +1,4 @@
-import { wrap } from "idb";
+import { wrap, } from "idb";
 export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB = globalThis.indexedDB, operationTimeoutMs, storeName, }) {
     if (!indexedDB) {
         return null;
@@ -44,25 +44,18 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
             });
         },
         async deleteIf(key, predicate) {
-            return runBrowserStorageOperation({
-                fallback: false,
+            return runConditionalStorageOperation({
+                databasePromise,
                 operationName: "conditionally delete key",
-                operation: async () => {
-                    const database = await databasePromise;
-                    // The ownership check and deletion must share a transaction; splitting
-                    // them can delete a newer offline snapshot written by another trigger.
-                    const transaction = database.transaction(storeName, "readwrite");
-                    const objectStore = transaction.objectStore(storeName);
+                storeName,
+                timeoutMs: operationTimeoutMs,
+                apply: async (objectStore) => {
                     const current = (await objectStore.get(key)) ?? null;
-                    if (!predicate(current)) {
-                        await transaction.done;
+                    if (!predicate(current))
                         return false;
-                    }
                     await objectStore.delete(key);
-                    await transaction.done;
                     return true;
                 },
-                timeoutMs: operationTimeoutMs,
             });
         },
         async get(key) {
@@ -123,23 +116,18 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
             });
         },
         async setIf(key, value, predicate) {
-            return runBrowserStorageOperation({
-                fallback: false,
+            return runConditionalStorageOperation({
+                databasePromise,
                 operationName: "conditionally replace key",
-                operation: async () => {
-                    const database = await databasePromise;
-                    const transaction = database.transaction(storeName, "readwrite");
-                    const objectStore = transaction.objectStore(storeName);
+                storeName,
+                timeoutMs: operationTimeoutMs,
+                apply: async (objectStore) => {
                     const current = (await objectStore.get(key)) ?? null;
-                    if (!predicate(current)) {
-                        await transaction.done;
+                    if (!predicate(current))
                         return false;
-                    }
                     await objectStore.put(value, key);
-                    await transaction.done;
                     return true;
                 },
-                timeoutMs: operationTimeoutMs,
             });
         },
     };
@@ -158,7 +146,7 @@ async function openKeyValueDatabase({ databaseName, databaseVersion, indexedDB,
     }
     return database;
 }
-async function runBrowserStorageOperation({ fallback, operation, operationName, timeoutMs, }) {
+async function runBrowserStorageOperation({ cancelOnTimeout, fallback, operation, operationName, timeoutMs, }) {
     let timeoutId = null;
     try {
         return await Promise.race([
@@ -168,7 +156,9 @@ async function runBrowserStorageOperation({ fallback, operation, operationName,
                     console.error(`IndexedDB timed out while trying to ${operationName}.`, {
                         timeoutMs,
                     });
-                    resolve(fallback);
+                    if (!cancelOnTimeout || cancelOnTimeout()) {
+                        resolve(fallback);
+                    }
                 }, timeoutMs);
             }),
         ]);
@@ -183,3 +173,39 @@ async function runBrowserStorageOperation({ fallback, operation, operationName,
         }
     }
 }
+async function runConditionalStorageOperation({ apply, databasePromise, operationName, storeName, timeoutMs, }) {
+    let transaction;
+    let cancelled = false;
+    return runBrowserStorageOperation({
+        fallback: false,
+        operationName,
+        timeoutMs,
+        cancelOnTimeout() {
+            cancelled = true;
+            if (!transaction)
+                return true;
+            try {
+                transaction.abort();
+                return true;
+            }
+            catch (error) {
+                // Product decision: when commit has already started, report its actual
+                // result instead of returning a false failure that can later mutate data.
+                console.warn("[Bayon offline] Conditional transaction already settling at timeout.", { error, operationName });
+                return false;
+            }
+        },
+        operation: async () => {
+            const database = await databasePromise;
+            if (cancelled)
+                return false;
+            transaction = database.transaction(storeName, "readwrite");
+            // Aborting can reject both a request and transaction.done. Observe the
+            // latter immediately so cancellation never creates an unhandled rejection.
+            void transaction.done.catch(() => undefined);
+            const result = await apply(transaction.objectStore(storeName));
+            await transaction.done;
+            return result;
+        },
+    });
+}

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from "./readCache";
 export * from "./pendingWrites";
 export * from "./browserRecovery";
 export * from "./browserCoordination";
+export * from "./browserFallbackRecovery";

package/dist/index.js

@@ -2,3 +2,4 @@ export * from "./readCache.js";
 export * from "./pendingWrites.js";
 export * from "./browserRecovery.js";
 export * from "./browserCoordination.js";
+export * from "./browserFallbackRecovery.js";

package/dist/pendingWrites.js

@@ -277,7 +277,10 @@ async function performPendingWriteSync({ select, stopOnFailure, store, sync, })
         });
         summary.attempted += 1;
         summary[result.status] += 1;
-        if (stopOnFailure && result.status === "failed") {
+        // Product decision: a superseded result can represent an older live claim.
+        // Preserve strict ordering by leaving every later record for a future run.
+        if (stopOnFailure &&
+            (result.status === "failed" || result.status === "superseded")) {
             break;
         }
     }

package/dist-cjs/browserFallbackRecovery.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultOfflineFallbackPullThreshold = exports.defaultOfflineFallbackRetryEvent = void 0;
+exports.createBrowserOfflineFallbackRecovery = createBrowserOfflineFallbackRecovery;
+exports.defaultOfflineFallbackRetryEvent = "app:network-restored";
+exports.defaultOfflineFallbackPullThreshold = 72;
+/**
+ * Owns generic recovery mechanics for a static offline fallback. Hosts retain
+ * all markup, copy, styling, and the choice of a native reconnect event.
+ */
+function createBrowserOfflineFallbackRecovery({ control, environment = createDefaultBrowserOfflineFallbackRecoveryEnvironment(), pullThreshold = exports.defaultOfflineFallbackPullThreshold, retryEvent = exports.defaultOfflineFallbackRetryEvent, retryingText = "Reconnecting…", }) {
+    let active = false;
+    let retrying = false;
+    let pullStartY = null;
+    function retry() {
+        if (retrying)
+            return;
+        retrying = true;
+        control.disabled = true;
+        control.textContent = retryingText;
+        try {
+            environment.reload();
+        }
+        catch (error) {
+            // A failed navigation must leave the recovery action visible and usable.
+            console.error("[Bayon offline] Offline fallback reload failed.", { error });
+            retrying = false;
+            control.disabled = false;
+        }
+    }
+    function handleTouchStart(event) {
+        const touchY = getSingleTouchY(event, "touches");
+        pullStartY = environment.getScrollY() === 0 ? touchY : null;
+    }
+    function handleTouchEnd(event) {
+        const touchY = getSingleTouchY(event, "changedTouches");
+        if (pullStartY !== null &&
+            touchY !== null &&
+            touchY - pullStartY >= (pullThreshold ?? Number.POSITIVE_INFINITY)) {
+            retry();
+        }
+        pullStartY = null;
+    }
+    return {
+        retry,
+        start() {
+            if (active)
+                return;
+            active = true;
+            environment.addEventListener("online", retry);
+            environment.addEventListener(retryEvent, retry);
+            if (pullThreshold !== null) {
+                environment.addEventListener("touchstart", handleTouchStart);
+                environment.addEventListener("touchend", handleTouchEnd);
+            }
+        },
+        stop() {
+            if (!active)
+                return;
+            active = false;
+            environment.removeEventListener("online", retry);
+            environment.removeEventListener(retryEvent, retry);
+            if (pullThreshold !== null) {
+                environment.removeEventListener("touchstart", handleTouchStart);
+                environment.removeEventListener("touchend", handleTouchEnd);
+            }
+            pullStartY = null;
+        },
+    };
+}
+function createDefaultBrowserOfflineFallbackRecoveryEnvironment() {
+    const target = typeof window === "undefined" ? null : window;
+    return {
+        addEventListener(type, listener) {
+            target?.addEventListener(type, listener);
+        },
+        getScrollY() {
+            return target?.scrollY ?? 0;
+        },
+        reload() {
+            target?.location.reload();
+        },
+        removeEventListener(type, listener) {
+            target?.removeEventListener(type, listener);
+        },
+    };
+}
+function getSingleTouchY(event, key) {
+    if (!event || typeof event !== "object")
+        return null;
+    const touches = Reflect.get(event, key);
+    if (!touches || typeof touches !== "object")
+        return null;
+    const touch = Reflect.get(touches, 0);
+    if (!touch || typeof touch !== "object")
+        return null;
+    const clientY = Reflect.get(touch, "clientY");
+    return typeof clientY === "number" ? clientY : null;
+}

package/dist-cjs/idbDriver.js

@@ -47,25 +47,18 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             });
         },
         async deleteIf(key, predicate) {
-            return runBrowserStorageOperation({
-                fallback: false,
+            return runConditionalStorageOperation({
+                databasePromise,
                 operationName: "conditionally delete key",
-                operation: async () => {
-                    const database = await databasePromise;
-                    // The ownership check and deletion must share a transaction; splitting
-                    // them can delete a newer offline snapshot written by another trigger.
-                    const transaction = database.transaction(storeName, "readwrite");
-                    const objectStore = transaction.objectStore(storeName);
+                storeName,
+                timeoutMs: operationTimeoutMs,
+                apply: async (objectStore) => {
                     const current = (await objectStore.get(key)) ?? null;
-                    if (!predicate(current)) {
-                        await transaction.done;
+                    if (!predicate(current))
                         return false;
-                    }
                     await objectStore.delete(key);
-                    await transaction.done;
                     return true;
                 },
-                timeoutMs: operationTimeoutMs,
             });
         },
         async get(key) {
@@ -126,23 +119,18 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             });
         },
         async setIf(key, value, predicate) {
-            return runBrowserStorageOperation({
-                fallback: false,
+            return runConditionalStorageOperation({
+                databasePromise,
                 operationName: "conditionally replace key",
-                operation: async () => {
-                    const database = await databasePromise;
-                    const transaction = database.transaction(storeName, "readwrite");
-                    const objectStore = transaction.objectStore(storeName);
+                storeName,
+                timeoutMs: operationTimeoutMs,
+                apply: async (objectStore) => {
                     const current = (await objectStore.get(key)) ?? null;
-                    if (!predicate(current)) {
-                        await transaction.done;
+                    if (!predicate(current))
                         return false;
-                    }
                     await objectStore.put(value, key);
-                    await transaction.done;
                     return true;
                 },
-                timeoutMs: operationTimeoutMs,
             });
         },
     };
@@ -161,7 +149,7 @@ async function openKeyValueDatabase({ databaseName, databaseVersion, indexedDB,
     }
     return database;
 }
-async function runBrowserStorageOperation({ fallback, operation, operationName, timeoutMs, }) {
+async function runBrowserStorageOperation({ cancelOnTimeout, fallback, operation, operationName, timeoutMs, }) {
     let timeoutId = null;
     try {
         return await Promise.race([
@@ -171,7 +159,9 @@ async function runBrowserStorageOperation({ fallback, operation, operationName,
                     console.error(`IndexedDB timed out while trying to ${operationName}.`, {
                         timeoutMs,
                     });
-                    resolve(fallback);
+                    if (!cancelOnTimeout || cancelOnTimeout()) {
+                        resolve(fallback);
+                    }
                 }, timeoutMs);
             }),
         ]);
@@ -186,3 +176,39 @@ async function runBrowserStorageOperation({ fallback, operation, operationName,
         }
     }
 }
+async function runConditionalStorageOperation({ apply, databasePromise, operationName, storeName, timeoutMs, }) {
+    let transaction;
+    let cancelled = false;
+    return runBrowserStorageOperation({
+        fallback: false,
+        operationName,
+        timeoutMs,
+        cancelOnTimeout() {
+            cancelled = true;
+            if (!transaction)
+                return true;
+            try {
+                transaction.abort();
+                return true;
+            }
+            catch (error) {
+                // Product decision: when commit has already started, report its actual
+                // result instead of returning a false failure that can later mutate data.
+                console.warn("[Bayon offline] Conditional transaction already settling at timeout.", { error, operationName });
+                return false;
+            }
+        },
+        operation: async () => {
+            const database = await databasePromise;
+            if (cancelled)
+                return false;
+            transaction = database.transaction(storeName, "readwrite");
+            // Aborting can reject both a request and transaction.done. Observe the
+            // latter immediately so cancellation never creates an unhandled rejection.
+            void transaction.done.catch(() => undefined);
+            const result = await apply(transaction.objectStore(storeName));
+            await transaction.done;
+            return result;
+        },
+    });
+}

package/dist-cjs/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./readCache"), exports);
 __exportStar(require("./pendingWrites"), exports);
 __exportStar(require("./browserRecovery"), exports);
 __exportStar(require("./browserCoordination"), exports);
+__exportStar(require("./browserFallbackRecovery"), exports);

package/dist-cjs/pendingWrites.js

@@ -291,7 +291,10 @@ async function performPendingWriteSync({ select, stopOnFailure, store, sync, })
         });
         summary.attempted += 1;
         summary[result.status] += 1;
-        if (stopOnFailure && result.status === "failed") {
+        // Product decision: a superseded result can represent an older live claim.
+        // Preserve strict ordering by leaving every later record for a future run.
+        if (stopOnFailure &&
+            (result.status === "failed" || result.status === "superseded")) {
             break;
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bayonai/offline",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Reusable offline read-cache, pending-write, and silent recovery primitives.",
   "license": "MIT",
   "author": "Bayon AI",
@@ -55,6 +55,7 @@
     "idb": "^8.0.3"
   },
   "devDependencies": {
+    "fake-indexeddb": "^6.2.5",
     "typescript": "^5",
     "vitest": "^4.1.6"
   }