@bayonai/offline 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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

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/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-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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bayonai/offline",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Reusable offline read-cache, pending-write, and silent recovery primitives.",
   "license": "MIT",
   "author": "Bayon AI",